##// END OF EJS Templates
Merge branch 'formatters' of http://github.com/rkern/ipython into rkern-formatters
Fernando Perez -
r3221:ead71f34 merge
parent child Browse files
Show More
@@ -0,0 +1,160
1 # -*- coding: utf-8 -*-
2 """Displayhook formatters.
3
4 The DefaultFormatter is always present and may be configured from the
5 ipython_config.py file. For example, to add a pretty-printer for a numpy.dtype
6 object::
7
8 def dtype_pprinter(obj, p, cycle):
9 if cycle:
10 return p.text('dtype(...)')
11 if hasattr(obj, 'fields'):
12 if obj.fields is None:
13 p.text(repr(obj))
14 else:
15 p.begin_group(7, 'dtype([')
16 for i, field in enumerate(obj.descr):
17 if i > 0:
18 p.text(',')
19 p.breakable()
20 p.pretty(field)
21 p.end_group(7, '])')
22
23 c.DefaultFormatter.deferred_pprinters = {
24 ('numpy', 'dtype'): dtype_pprinter,
25 }
26
27 The deferred_pprinters dictionary is the preferred way to configure these
28 pretty-printers. This allows you to define the pretty-printer without needing to
29 import the type itself. The dictionary maps (modulename, typename) pairs to
30 a function.
31
32 See the `IPython.external.pretty` documentation for how to write
33 pretty-printer functions.
34
35 Authors:
36
37 * Robert Kern
38 """
39
40 import abc
41 from cStringIO import StringIO
42
43 from IPython.config.configurable import Configurable
44 from IPython.external import pretty
45 from IPython.utils.traitlets import Bool, Dict, Int, Str
46
47
48 class DefaultFormatter(Configurable):
49 """ The default pretty-printer.
50 """
51
52 # The ID of the formatter.
53 id = Str('default')
54
55 # The kind of data returned.
56 # This is often, but not always a MIME type.
57 format = Str('text/plain')
58
59 # Whether to pretty-print or not.
60 pprint = Bool(True, config=True)
61
62 # Whether to be verbose or not.
63 verbose = Bool(False, config=True)
64
65 # The maximum width.
66 max_width = Int(79, config=True)
67
68 # The newline character.
69 newline = Str('\n', config=True)
70
71 # The singleton prettyprinters.
72 # Maps the IDs of the builtin singleton objects to the format functions.
73 singleton_pprinters = Dict(config=True)
74 def _singleton_pprinters_default(self):
75 return pretty._singleton_pprinters.copy()
76
77 # The type-specific prettyprinters.
78 # Map type objects to the format functions.
79 type_pprinters = Dict(config=True)
80 def _type_pprinters_default(self):
81 return pretty._type_pprinters.copy()
82
83 # The deferred-import type-specific prettyprinters.
84 # Map (modulename, classname) pairs to the format functions.
85 deferred_pprinters = Dict(config=True)
86 def _deferred_pprinters_default(self):
87 return pretty._deferred_type_pprinters.copy()
88
89 #### FormatterABC interface ####
90
91 def __call__(self, obj):
92 """ Format the object.
93 """
94 if not self.pprint:
95 try:
96 return repr(obj)
97 except TypeError:
98 return ''
99 else:
100 stream = StringIO()
101 printer = pretty.RepresentationPrinter(stream, self.verbose,
102 self.max_width, self.newline,
103 singleton_pprinters=self.singleton_pprinters,
104 type_pprinters=self.type_pprinters,
105 deferred_pprinters=self.deferred_pprinters)
106 printer.pretty(obj)
107 printer.flush()
108 return stream.getvalue()
109
110
111 #### DefaultFormatter interface ####
112
113 def for_type(self, typ, func):
114 """
115 Add a pretty printer for a given type.
116 """
117 oldfunc = self.type_pprinters.get(typ, None)
118 if func is not None:
119 # To support easy restoration of old pprinters, we need to ignore
120 # Nones.
121 self.type_pprinters[typ] = func
122 return oldfunc
123
124 def for_type_by_name(self, type_module, type_name, func):
125 """
126 Add a pretty printer for a type specified by the module and name of
127 a type rather than the type object itself.
128 """
129 key = (type_module, type_name)
130 oldfunc = self.deferred_pprinters.get(key, None)
131 if func is not None:
132 # To support easy restoration of old pprinters, we need to ignore
133 # Nones.
134 self.deferred_pprinters[key] = func
135 return oldfunc
136
137
138 class FormatterABC(object):
139 """ Abstract base class for Formatters.
140 """
141 __metaclass__ = abc.ABCMeta
142
143 # The ID of the formatter.
144 id = 'abstract'
145
146 # The kind of data returned.
147 format = 'text/plain'
148
149 @abc.abstractmethod
150 def __call__(self, obj):
151 """ Return a JSONable representation of the object.
152
153 If the object cannot be formatted by this formatter, then return None
154 """
155 try:
156 return repr(obj)
157 except TypeError:
158 return None
159
160 FormatterABC.register(DefaultFormatter)
@@ -0,0 +1,30
1 """Tests for the Formatters.
2 """
3
4 import nose.tools as nt
5
6 from IPython.core.formatters import FormatterABC, DefaultFormatter
7
8 class A(object):
9 def __repr__(self):
10 return 'A()'
11
12 class B(A):
13 def __repr__(self):
14 return 'B()'
15
16 def foo_printer(obj, pp, cycle):
17 pp.text('foo')
18
19 def test_pretty():
20 f = DefaultFormatter()
21 f.for_type(A, foo_printer)
22 nt.assert_equals(f(A()), 'foo')
23 nt.assert_equals(f(B()), 'foo')
24 f.pprint = False
25 nt.assert_equals(f(A()), 'A()')
26 nt.assert_equals(f(B()), 'B()')
27
28 def test_deferred():
29 f = DefaultFormatter()
30
@@ -1,297 +1,301
1 1 # -*- coding: utf-8 -*-
2 2 """Displayhook for IPython.
3 3
4 4 Authors:
5 5
6 6 * Fernando Perez
7 7 * Brian Granger
8 8 """
9 9
10 10 #-----------------------------------------------------------------------------
11 11 # Copyright (C) 2008-2010 The IPython Development Team
12 12 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
13 13 #
14 14 # Distributed under the terms of the BSD License. The full license is in
15 15 # the file COPYING, distributed as part of this software.
16 16 #-----------------------------------------------------------------------------
17 17
18 18 #-----------------------------------------------------------------------------
19 19 # Imports
20 20 #-----------------------------------------------------------------------------
21 21
22 22 import __builtin__
23 from pprint import PrettyPrinter
24 pformat = PrettyPrinter().pformat
25 23
26 24 from IPython.config.configurable import Configurable
27 25 from IPython.core import prompts
28 26 import IPython.utils.generics
29 27 import IPython.utils.io
30 from IPython.utils.traitlets import Instance, Int
28 from IPython.utils.traitlets import Instance, List
31 29 from IPython.utils.warn import warn
30 from IPython.core.formatters import DefaultFormatter
32 31
33 32 #-----------------------------------------------------------------------------
34 33 # Main displayhook class
35 34 #-----------------------------------------------------------------------------
36 35
37 36 # TODO: The DisplayHook class should be split into two classes, one that
38 37 # manages the prompts and their synchronization and another that just does the
39 38 # displayhook logic and calls into the prompt manager.
40 39
41 40 # TODO: Move the various attributes (cache_size, colors, input_sep,
42 41 # output_sep, output_sep2, ps1, ps2, ps_out, pad_left). Some of these are also
43 42 # attributes of InteractiveShell. They should be on ONE object only and the
44 43 # other objects should ask that one object for their values.
45 44
46 45 class DisplayHook(Configurable):
47 46 """The custom IPython displayhook to replace sys.displayhook.
48 47
49 48 This class does many things, but the basic idea is that it is a callable
50 49 that gets called anytime user code returns a value.
51 50
52 51 Currently this class does more than just the displayhook logic and that
53 52 extra logic should eventually be moved out of here.
54 53 """
55 54
56 55 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
57 56
57 # The default formatter.
58 default_formatter = Instance('IPython.core.formatters.FormatterABC')
59 def _default_formatter_default(self):
60 # FIXME: backwards compatibility for the InteractiveShell.pprint option?
61 return DefaultFormatter(config=self.config)
62
63 # Any additional FormatterABC instances we use.
64 # FIXME: currently unused.
65 extra_formatters = List(config=True)
66
58 67 # Each call to the In[] prompt raises it by 1, even the first.
59 68 #prompt_count = Int(0)
60 69
61 70 def __init__(self, shell=None, cache_size=1000,
62 71 colors='NoColor', input_sep='\n',
63 72 output_sep='\n', output_sep2='',
64 73 ps1 = None, ps2 = None, ps_out = None, pad_left=True,
65 74 config=None):
66 75 super(DisplayHook, self).__init__(shell=shell, config=config)
67 76
68 77 cache_size_min = 3
69 78 if cache_size <= 0:
70 79 self.do_full_cache = 0
71 80 cache_size = 0
72 81 elif cache_size < cache_size_min:
73 82 self.do_full_cache = 0
74 83 cache_size = 0
75 84 warn('caching was disabled (min value for cache size is %s).' %
76 85 cache_size_min,level=3)
77 86 else:
78 87 self.do_full_cache = 1
79 88
80 89 self.cache_size = cache_size
81 90 self.input_sep = input_sep
82 91
83 92 # we need a reference to the user-level namespace
84 93 self.shell = shell
85 94
86 95 # Set input prompt strings and colors
87 96 if cache_size == 0:
88 97 if ps1.find('%n') > -1 or ps1.find(r'\#') > -1 \
89 98 or ps1.find(r'\N') > -1:
90 99 ps1 = '>>> '
91 100 if ps2.find('%n') > -1 or ps2.find(r'\#') > -1 \
92 101 or ps2.find(r'\N') > -1:
93 102 ps2 = '... '
94 103 self.ps1_str = self._set_prompt_str(ps1,'In [\\#]: ','>>> ')
95 104 self.ps2_str = self._set_prompt_str(ps2,' .\\D.: ','... ')
96 105 self.ps_out_str = self._set_prompt_str(ps_out,'Out[\\#]: ','')
97 106
98 107 self.color_table = prompts.PromptColors
99 108 self.prompt1 = prompts.Prompt1(self,sep=input_sep,prompt=self.ps1_str,
100 109 pad_left=pad_left)
101 110 self.prompt2 = prompts.Prompt2(self,prompt=self.ps2_str,pad_left=pad_left)
102 111 self.prompt_out = prompts.PromptOut(self,sep='',prompt=self.ps_out_str,
103 112 pad_left=pad_left)
104 113 self.set_colors(colors)
105 114
106 115 # Store the last prompt string each time, we need it for aligning
107 116 # continuation and auto-rewrite prompts
108 117 self.last_prompt = ''
109 118 self.output_sep = output_sep
110 119 self.output_sep2 = output_sep2
111 120 self._,self.__,self.___ = '','',''
112 self.pprint_types = map(type,[(),[],{}])
113 121
114 122 # these are deliberately global:
115 123 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
116 124 self.shell.user_ns.update(to_user_ns)
117 125
118 126 @property
119 127 def prompt_count(self):
120 128 return self.shell.execution_count
121 129
122 130 def _set_prompt_str(self,p_str,cache_def,no_cache_def):
123 131 if p_str is None:
124 132 if self.do_full_cache:
125 133 return cache_def
126 134 else:
127 135 return no_cache_def
128 136 else:
129 137 return p_str
130 138
131 139 def set_colors(self, colors):
132 140 """Set the active color scheme and configure colors for the three
133 141 prompt subsystems."""
134 142
135 143 # FIXME: This modifying of the global prompts.prompt_specials needs
136 144 # to be fixed. We need to refactor all of the prompts stuff to use
137 145 # proper configuration and traits notifications.
138 146 if colors.lower()=='nocolor':
139 147 prompts.prompt_specials = prompts.prompt_specials_nocolor
140 148 else:
141 149 prompts.prompt_specials = prompts.prompt_specials_color
142 150
143 151 self.color_table.set_active_scheme(colors)
144 152 self.prompt1.set_colors()
145 153 self.prompt2.set_colors()
146 154 self.prompt_out.set_colors()
147 155
148 156 #-------------------------------------------------------------------------
149 157 # Methods used in __call__. Override these methods to modify the behavior
150 158 # of the displayhook.
151 159 #-------------------------------------------------------------------------
152 160
153 161 def check_for_underscore(self):
154 162 """Check if the user has set the '_' variable by hand."""
155 163 # If something injected a '_' variable in __builtin__, delete
156 164 # ipython's automatic one so we don't clobber that. gettext() in
157 165 # particular uses _, so we need to stay away from it.
158 166 if '_' in __builtin__.__dict__:
159 167 try:
160 168 del self.shell.user_ns['_']
161 169 except KeyError:
162 170 pass
163 171
164 172 def quiet(self):
165 173 """Should we silence the display hook because of ';'?"""
166 174 # do not print output if input ends in ';'
167 175 try:
168 176 if self.shell.input_hist[self.prompt_count].endswith(';\n'):
169 177 return True
170 178 except IndexError:
171 179 # some uses of ipshellembed may fail here
172 180 pass
173 181 return False
174 182
175 183 def start_displayhook(self):
176 184 """Start the displayhook, initializing resources."""
177 185 pass
178 186
179 187 def write_output_prompt(self):
180 188 """Write the output prompt."""
181 189 # Use write, not print which adds an extra space.
182 190 IPython.utils.io.Term.cout.write(self.output_sep)
183 191 outprompt = str(self.prompt_out)
184 192 if self.do_full_cache:
185 193 IPython.utils.io.Term.cout.write(outprompt)
186 194
187 # TODO: Make this method an extension point. The previous implementation
188 # has both a result_display hook as well as a result_display generic
189 # function to customize the repr on a per class basis. We need to rethink
190 # the hooks mechanism before doing this though.
191 195 def compute_result_repr(self, result):
192 196 """Compute and return the repr of the object to be displayed.
193 197
194 198 This method only compute the string form of the repr and should NOT
195 actual print or write that to a stream. This method may also transform
196 the result itself, but the default implementation passes the original
197 through.
199 actual print or write that to a stream.
198 200 """
199 try:
200 if self.shell.pprint:
201 try:
202 result_repr = pformat(result)
203 except:
204 # Work around possible bugs in pformat
205 result_repr = repr(result)
206 if '\n' in result_repr:
207 # So that multi-line strings line up with the left column of
208 # the screen, instead of having the output prompt mess up
209 # their first line.
210 result_repr = '\n' + result_repr
211 else:
212 result_repr = repr(result)
213 except TypeError:
214 # This happens when result.__repr__ doesn't return a string,
215 # such as when it returns None.
216 result_repr = '\n'
217 return result, result_repr
218
219 def write_result_repr(self, result_repr):
201 result_repr = self.default_formatter(result)
202 if '\n' in result_repr:
203 # So that multi-line strings line up with the left column of
204 # the screen, instead of having the output prompt mess up
205 # their first line.
206 outprompt = str(self.prompt_out)
207 if outprompt and not outprompt.endswith('\n'):
208 # But avoid extraneous empty lines.
209 result_repr = '\n' + result_repr
210
211 extra_formats = []
212 for f in self.extra_formatters:
213 try:
214 data = f(result)
215 except Exception:
216 # FIXME: log the exception.
217 continue
218 if data is not None:
219 extra_formats.append((f.id, f.format, data))
220
221 return result_repr, extra_formats
222
223 def write_result_repr(self, result_repr, extra_formats):
220 224 # We want to print because we want to always make sure we have a
221 225 # newline, even if all the prompt separators are ''. This is the
222 226 # standard IPython behavior.
223 227 print >>IPython.utils.io.Term.cout, result_repr
224 228
225 229 def update_user_ns(self, result):
226 230 """Update user_ns with various things like _, __, _1, etc."""
227 231
228 232 # Avoid recursive reference when displaying _oh/Out
229 233 if result is not self.shell.user_ns['_oh']:
230 234 if len(self.shell.user_ns['_oh']) >= self.cache_size and self.do_full_cache:
231 235 warn('Output cache limit (currently '+
232 236 `self.cache_size`+' entries) hit.\n'
233 237 'Flushing cache and resetting history counter...\n'
234 238 'The only history variables available will be _,__,___ and _1\n'
235 239 'with the current result.')
236 240
237 241 self.flush()
238 242 # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
239 243 # we cause buggy behavior for things like gettext).
240 244 if '_' not in __builtin__.__dict__:
241 245 self.___ = self.__
242 246 self.__ = self._
243 247 self._ = result
244 248 self.shell.user_ns.update({'_':self._,'__':self.__,'___':self.___})
245 249
246 250 # hackish access to top-level namespace to create _1,_2... dynamically
247 251 to_main = {}
248 252 if self.do_full_cache:
249 253 new_result = '_'+`self.prompt_count`
250 254 to_main[new_result] = result
251 255 self.shell.user_ns.update(to_main)
252 256 self.shell.user_ns['_oh'][self.prompt_count] = result
253 257
254 258 def log_output(self, result):
255 259 """Log the output."""
256 260 if self.shell.logger.log_output:
257 261 self.shell.logger.log_write(repr(result), 'output')
258 262
259 263 def finish_displayhook(self):
260 264 """Finish up all displayhook activities."""
261 265 IPython.utils.io.Term.cout.write(self.output_sep2)
262 266 IPython.utils.io.Term.cout.flush()
263 267
264 268 def __call__(self, result=None):
265 269 """Printing with history cache management.
266 270
267 271 This is invoked everytime the interpreter needs to print, and is
268 272 activated by setting the variable sys.displayhook to it.
269 273 """
270 274 self.check_for_underscore()
271 275 if result is not None and not self.quiet():
272 276 self.start_displayhook()
273 277 self.write_output_prompt()
274 result, result_repr = self.compute_result_repr(result)
275 self.write_result_repr(result_repr)
278 result_repr, extra_formats = self.compute_result_repr(result)
279 self.write_result_repr(result_repr, extra_formats)
276 280 self.update_user_ns(result)
277 281 self.log_output(result)
278 282 self.finish_displayhook()
279 283
280 284 def flush(self):
281 285 if not self.do_full_cache:
282 286 raise ValueError,"You shouldn't have reached the cache flush "\
283 287 "if full caching is not enabled!"
284 288 # delete auto-generated vars from global namespace
285 289
286 290 for n in range(1,self.prompt_count + 1):
287 291 key = '_'+`n`
288 292 try:
289 293 del self.shell.user_ns[key]
290 294 except: pass
291 295 self.shell.user_ns['_oh'].clear()
292 296
293 297 if '_' not in __builtin__.__dict__:
294 298 self.shell.user_ns.update({'_':None,'__':None, '___':None})
295 299 import gc
296 300 gc.collect() # xxx needed?
297 301
@@ -1,2537 +1,2538
1 1 # -*- coding: utf-8 -*-
2 2 """Main IPython class."""
3 3
4 4 #-----------------------------------------------------------------------------
5 5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 7 # Copyright (C) 2008-2010 The IPython Development Team
8 8 #
9 9 # Distributed under the terms of the BSD License. The full license is in
10 10 # the file COPYING, distributed as part of this software.
11 11 #-----------------------------------------------------------------------------
12 12
13 13 #-----------------------------------------------------------------------------
14 14 # Imports
15 15 #-----------------------------------------------------------------------------
16 16
17 17 from __future__ import with_statement
18 18 from __future__ import absolute_import
19 19
20 20 import __builtin__
21 21 import __future__
22 22 import abc
23 23 import atexit
24 24 import codeop
25 25 import os
26 26 import re
27 27 import sys
28 28 import tempfile
29 29 import types
30 30 from contextlib import nested
31 31
32 32 from IPython.config.configurable import Configurable
33 33 from IPython.core import debugger, oinspect
34 34 from IPython.core import history as ipcorehist
35 35 from IPython.core import page
36 36 from IPython.core import prefilter
37 37 from IPython.core import shadowns
38 38 from IPython.core import ultratb
39 39 from IPython.core.alias import AliasManager
40 40 from IPython.core.builtin_trap import BuiltinTrap
41 41 from IPython.core.compilerop import CachingCompiler
42 42 from IPython.core.display_trap import DisplayTrap
43 43 from IPython.core.displayhook import DisplayHook
44 44 from IPython.core.error import TryNext, UsageError
45 45 from IPython.core.extensions import ExtensionManager
46 46 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
47 47 from IPython.core.history import HistoryManager
48 48 from IPython.core.inputlist import InputList
49 49 from IPython.core.inputsplitter import IPythonInputSplitter
50 50 from IPython.core.logger import Logger
51 51 from IPython.core.magic import Magic
52 52 from IPython.core.payload import PayloadManager
53 53 from IPython.core.plugin import PluginManager
54 54 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
55 55 from IPython.external.Itpl import ItplNS
56 56 from IPython.utils import PyColorize
57 57 from IPython.utils import io
58 58 from IPython.utils import pickleshare
59 59 from IPython.utils.doctestreload import doctest_reload
60 60 from IPython.utils.io import ask_yes_no, rprint
61 61 from IPython.utils.ipstruct import Struct
62 62 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
63 63 from IPython.utils.process import system, getoutput
64 64 from IPython.utils.strdispatch import StrDispatch
65 65 from IPython.utils.syspathcontext import prepended_to_syspath
66 66 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
67 67 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
68 68 List, Unicode, Instance, Type)
69 69 from IPython.utils.warn import warn, error, fatal
70 70 import IPython.core.hooks
71 71
72 72 #-----------------------------------------------------------------------------
73 73 # Globals
74 74 #-----------------------------------------------------------------------------
75 75
76 76 # compiled regexps for autoindent management
77 77 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
78 78
79 79 #-----------------------------------------------------------------------------
80 80 # Utilities
81 81 #-----------------------------------------------------------------------------
82 82
83 83 # store the builtin raw_input globally, and use this always, in case user code
84 84 # overwrites it (like wx.py.PyShell does)
85 85 raw_input_original = raw_input
86 86
87 87 def softspace(file, newvalue):
88 88 """Copied from code.py, to remove the dependency"""
89 89
90 90 oldvalue = 0
91 91 try:
92 92 oldvalue = file.softspace
93 93 except AttributeError:
94 94 pass
95 95 try:
96 96 file.softspace = newvalue
97 97 except (AttributeError, TypeError):
98 98 # "attribute-less object" or "read-only attributes"
99 99 pass
100 100 return oldvalue
101 101
102 102
103 103 def no_op(*a, **kw): pass
104 104
105 105 class SpaceInInput(Exception): pass
106 106
107 107 class Bunch: pass
108 108
109 109
110 110 def get_default_colors():
111 111 if sys.platform=='darwin':
112 112 return "LightBG"
113 113 elif os.name=='nt':
114 114 return 'Linux'
115 115 else:
116 116 return 'Linux'
117 117
118 118
119 119 class SeparateStr(Str):
120 120 """A Str subclass to validate separate_in, separate_out, etc.
121 121
122 122 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
123 123 """
124 124
125 125 def validate(self, obj, value):
126 126 if value == '0': value = ''
127 127 value = value.replace('\\n','\n')
128 128 return super(SeparateStr, self).validate(obj, value)
129 129
130 130 class MultipleInstanceError(Exception):
131 131 pass
132 132
133 133
134 134 #-----------------------------------------------------------------------------
135 135 # Main IPython class
136 136 #-----------------------------------------------------------------------------
137 137
138 138 class InteractiveShell(Configurable, Magic):
139 139 """An enhanced, interactive shell for Python."""
140 140
141 141 _instance = None
142 142 autocall = Enum((0,1,2), default_value=1, config=True)
143 143 # TODO: remove all autoindent logic and put into frontends.
144 144 # We can't do this yet because even runlines uses the autoindent.
145 145 autoindent = CBool(True, config=True)
146 146 automagic = CBool(True, config=True)
147 147 cache_size = Int(1000, config=True)
148 148 color_info = CBool(True, config=True)
149 149 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
150 150 default_value=get_default_colors(), config=True)
151 151 debug = CBool(False, config=True)
152 152 deep_reload = CBool(False, config=True)
153 153 displayhook_class = Type(DisplayHook)
154 154 exit_now = CBool(False)
155 155 # Monotonically increasing execution counter
156 156 execution_count = Int(1)
157 157 filename = Str("<ipython console>")
158 158 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
159 159
160 160 # Input splitter, to split entire cells of input into either individual
161 161 # interactive statements or whole blocks.
162 162 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
163 163 (), {})
164 164 logstart = CBool(False, config=True)
165 165 logfile = Str('', config=True)
166 166 logappend = Str('', config=True)
167 167 object_info_string_level = Enum((0,1,2), default_value=0,
168 168 config=True)
169 169 pdb = CBool(False, config=True)
170 170
171 171 pprint = CBool(True, config=True)
172 172 profile = Str('', config=True)
173 173 prompt_in1 = Str('In [\\#]: ', config=True)
174 174 prompt_in2 = Str(' .\\D.: ', config=True)
175 175 prompt_out = Str('Out[\\#]: ', config=True)
176 176 prompts_pad_left = CBool(True, config=True)
177 177 quiet = CBool(False, config=True)
178 178
179 179 # The readline stuff will eventually be moved to the terminal subclass
180 180 # but for now, we can't do that as readline is welded in everywhere.
181 181 readline_use = CBool(True, config=True)
182 182 readline_merge_completions = CBool(True, config=True)
183 183 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
184 184 readline_remove_delims = Str('-/~', config=True)
185 185 readline_parse_and_bind = List([
186 186 'tab: complete',
187 187 '"\C-l": clear-screen',
188 188 'set show-all-if-ambiguous on',
189 189 '"\C-o": tab-insert',
190 190 '"\M-i": " "',
191 191 '"\M-o": "\d\d\d\d"',
192 192 '"\M-I": "\d\d\d\d"',
193 193 '"\C-r": reverse-search-history',
194 194 '"\C-s": forward-search-history',
195 195 '"\C-p": history-search-backward',
196 196 '"\C-n": history-search-forward',
197 197 '"\e[A": history-search-backward',
198 198 '"\e[B": history-search-forward',
199 199 '"\C-k": kill-line',
200 200 '"\C-u": unix-line-discard',
201 201 ], allow_none=False, config=True)
202 202
203 203 # TODO: this part of prompt management should be moved to the frontends.
204 204 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
205 205 separate_in = SeparateStr('\n', config=True)
206 206 separate_out = SeparateStr('', config=True)
207 207 separate_out2 = SeparateStr('', config=True)
208 208 wildcards_case_sensitive = CBool(True, config=True)
209 209 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
210 210 default_value='Context', config=True)
211 211
212 212 # Subcomponents of InteractiveShell
213 213 alias_manager = Instance('IPython.core.alias.AliasManager')
214 214 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
215 215 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
216 216 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
217 217 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
218 218 plugin_manager = Instance('IPython.core.plugin.PluginManager')
219 219 payload_manager = Instance('IPython.core.payload.PayloadManager')
220 220 history_manager = Instance('IPython.core.history.HistoryManager')
221 221
222 222 # Private interface
223 223 _post_execute = set()
224 224
225 225 def __init__(self, config=None, ipython_dir=None,
226 226 user_ns=None, user_global_ns=None,
227 227 custom_exceptions=((), None)):
228 228
229 229 # This is where traits with a config_key argument are updated
230 230 # from the values on config.
231 231 super(InteractiveShell, self).__init__(config=config)
232 232
233 233 # These are relatively independent and stateless
234 234 self.init_ipython_dir(ipython_dir)
235 235 self.init_instance_attrs()
236 236 self.init_environment()
237 237
238 238 # Create namespaces (user_ns, user_global_ns, etc.)
239 239 self.init_create_namespaces(user_ns, user_global_ns)
240 240 # This has to be done after init_create_namespaces because it uses
241 241 # something in self.user_ns, but before init_sys_modules, which
242 242 # is the first thing to modify sys.
243 243 # TODO: When we override sys.stdout and sys.stderr before this class
244 244 # is created, we are saving the overridden ones here. Not sure if this
245 245 # is what we want to do.
246 246 self.save_sys_module_state()
247 247 self.init_sys_modules()
248 248
249 249 self.init_history()
250 250 self.init_encoding()
251 251 self.init_prefilter()
252 252
253 253 Magic.__init__(self, self)
254 254
255 255 self.init_syntax_highlighting()
256 256 self.init_hooks()
257 257 self.init_pushd_popd_magic()
258 258 # self.init_traceback_handlers use to be here, but we moved it below
259 259 # because it and init_io have to come after init_readline.
260 260 self.init_user_ns()
261 261 self.init_logger()
262 262 self.init_alias()
263 263 self.init_builtins()
264 264
265 265 # pre_config_initialization
266 266
267 267 # The next section should contain everything that was in ipmaker.
268 268 self.init_logstart()
269 269
270 270 # The following was in post_config_initialization
271 271 self.init_inspector()
272 272 # init_readline() must come before init_io(), because init_io uses
273 273 # readline related things.
274 274 self.init_readline()
275 275 # init_completer must come after init_readline, because it needs to
276 276 # know whether readline is present or not system-wide to configure the
277 277 # completers, since the completion machinery can now operate
278 278 # independently of readline (e.g. over the network)
279 279 self.init_completer()
280 280 # TODO: init_io() needs to happen before init_traceback handlers
281 281 # because the traceback handlers hardcode the stdout/stderr streams.
282 282 # This logic in in debugger.Pdb and should eventually be changed.
283 283 self.init_io()
284 284 self.init_traceback_handlers(custom_exceptions)
285 285 self.init_prompts()
286 286 self.init_displayhook()
287 287 self.init_reload_doctest()
288 288 self.init_magics()
289 289 self.init_pdb()
290 290 self.init_extension_manager()
291 291 self.init_plugin_manager()
292 292 self.init_payload()
293 293 self.hooks.late_startup_hook()
294 294 atexit.register(self.atexit_operations)
295 295
296 296 @classmethod
297 297 def instance(cls, *args, **kwargs):
298 298 """Returns a global InteractiveShell instance."""
299 299 if cls._instance is None:
300 300 inst = cls(*args, **kwargs)
301 301 # Now make sure that the instance will also be returned by
302 302 # the subclasses instance attribute.
303 303 for subclass in cls.mro():
304 304 if issubclass(cls, subclass) and \
305 305 issubclass(subclass, InteractiveShell):
306 306 subclass._instance = inst
307 307 else:
308 308 break
309 309 if isinstance(cls._instance, cls):
310 310 return cls._instance
311 311 else:
312 312 raise MultipleInstanceError(
313 313 'Multiple incompatible subclass instances of '
314 314 'InteractiveShell are being created.'
315 315 )
316 316
317 317 @classmethod
318 318 def initialized(cls):
319 319 return hasattr(cls, "_instance")
320 320
321 321 def get_ipython(self):
322 322 """Return the currently running IPython instance."""
323 323 return self
324 324
325 325 #-------------------------------------------------------------------------
326 326 # Trait changed handlers
327 327 #-------------------------------------------------------------------------
328 328
329 329 def _ipython_dir_changed(self, name, new):
330 330 if not os.path.isdir(new):
331 331 os.makedirs(new, mode = 0777)
332 332
333 333 def set_autoindent(self,value=None):
334 334 """Set the autoindent flag, checking for readline support.
335 335
336 336 If called with no arguments, it acts as a toggle."""
337 337
338 338 if not self.has_readline:
339 339 if os.name == 'posix':
340 340 warn("The auto-indent feature requires the readline library")
341 341 self.autoindent = 0
342 342 return
343 343 if value is None:
344 344 self.autoindent = not self.autoindent
345 345 else:
346 346 self.autoindent = value
347 347
348 348 #-------------------------------------------------------------------------
349 349 # init_* methods called by __init__
350 350 #-------------------------------------------------------------------------
351 351
352 352 def init_ipython_dir(self, ipython_dir):
353 353 if ipython_dir is not None:
354 354 self.ipython_dir = ipython_dir
355 355 self.config.Global.ipython_dir = self.ipython_dir
356 356 return
357 357
358 358 if hasattr(self.config.Global, 'ipython_dir'):
359 359 self.ipython_dir = self.config.Global.ipython_dir
360 360 else:
361 361 self.ipython_dir = get_ipython_dir()
362 362
363 363 # All children can just read this
364 364 self.config.Global.ipython_dir = self.ipython_dir
365 365
366 366 def init_instance_attrs(self):
367 367 self.more = False
368 368
369 369 # command compiler
370 370 self.compile = CachingCompiler()
371 371
372 372 # User input buffers
373 373 # NOTE: these variables are slated for full removal, once we are 100%
374 374 # sure that the new execution logic is solid. We will delte runlines,
375 375 # push_line and these buffers, as all input will be managed by the
376 376 # frontends via an inputsplitter instance.
377 377 self.buffer = []
378 378 self.buffer_raw = []
379 379
380 380 # Make an empty namespace, which extension writers can rely on both
381 381 # existing and NEVER being used by ipython itself. This gives them a
382 382 # convenient location for storing additional information and state
383 383 # their extensions may require, without fear of collisions with other
384 384 # ipython names that may develop later.
385 385 self.meta = Struct()
386 386
387 387 # Object variable to store code object waiting execution. This is
388 388 # used mainly by the multithreaded shells, but it can come in handy in
389 389 # other situations. No need to use a Queue here, since it's a single
390 390 # item which gets cleared once run.
391 391 self.code_to_run = None
392 392
393 393 # Temporary files used for various purposes. Deleted at exit.
394 394 self.tempfiles = []
395 395
396 396 # Keep track of readline usage (later set by init_readline)
397 397 self.has_readline = False
398 398
399 399 # keep track of where we started running (mainly for crash post-mortem)
400 400 # This is not being used anywhere currently.
401 401 self.starting_dir = os.getcwd()
402 402
403 403 # Indentation management
404 404 self.indent_current_nsp = 0
405 405
406 406 def init_environment(self):
407 407 """Any changes we need to make to the user's environment."""
408 408 pass
409 409
410 410 def init_encoding(self):
411 411 # Get system encoding at startup time. Certain terminals (like Emacs
412 412 # under Win32 have it set to None, and we need to have a known valid
413 413 # encoding to use in the raw_input() method
414 414 try:
415 415 self.stdin_encoding = sys.stdin.encoding or 'ascii'
416 416 except AttributeError:
417 417 self.stdin_encoding = 'ascii'
418 418
419 419 def init_syntax_highlighting(self):
420 420 # Python source parser/formatter for syntax highlighting
421 421 pyformat = PyColorize.Parser().format
422 422 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
423 423
424 424 def init_pushd_popd_magic(self):
425 425 # for pushd/popd management
426 426 try:
427 427 self.home_dir = get_home_dir()
428 428 except HomeDirError, msg:
429 429 fatal(msg)
430 430
431 431 self.dir_stack = []
432 432
433 433 def init_logger(self):
434 434 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
435 435 logmode='rotate')
436 436
437 437 def init_logstart(self):
438 438 """Initialize logging in case it was requested at the command line.
439 439 """
440 440 if self.logappend:
441 441 self.magic_logstart(self.logappend + ' append')
442 442 elif self.logfile:
443 443 self.magic_logstart(self.logfile)
444 444 elif self.logstart:
445 445 self.magic_logstart()
446 446
447 447 def init_builtins(self):
448 448 self.builtin_trap = BuiltinTrap(shell=self)
449 449
450 450 def init_inspector(self):
451 451 # Object inspector
452 452 self.inspector = oinspect.Inspector(oinspect.InspectColors,
453 453 PyColorize.ANSICodeColors,
454 454 'NoColor',
455 455 self.object_info_string_level)
456 456
457 457 def init_io(self):
458 458 # This will just use sys.stdout and sys.stderr. If you want to
459 459 # override sys.stdout and sys.stderr themselves, you need to do that
460 460 # *before* instantiating this class, because Term holds onto
461 461 # references to the underlying streams.
462 462 if sys.platform == 'win32' and self.has_readline:
463 463 Term = io.IOTerm(cout=self.readline._outputfile,
464 464 cerr=self.readline._outputfile)
465 465 else:
466 466 Term = io.IOTerm()
467 467 io.Term = Term
468 468
469 469 def init_prompts(self):
470 470 # TODO: This is a pass for now because the prompts are managed inside
471 471 # the DisplayHook. Once there is a separate prompt manager, this
472 472 # will initialize that object and all prompt related information.
473 473 pass
474 474
475 475 def init_displayhook(self):
476 476 # Initialize displayhook, set in/out prompts and printing system
477 477 self.displayhook = self.displayhook_class(
478 config=self.config,
478 479 shell=self,
479 480 cache_size=self.cache_size,
480 481 input_sep = self.separate_in,
481 482 output_sep = self.separate_out,
482 483 output_sep2 = self.separate_out2,
483 484 ps1 = self.prompt_in1,
484 485 ps2 = self.prompt_in2,
485 486 ps_out = self.prompt_out,
486 487 pad_left = self.prompts_pad_left
487 488 )
488 489 # This is a context manager that installs/revmoes the displayhook at
489 490 # the appropriate time.
490 491 self.display_trap = DisplayTrap(hook=self.displayhook)
491 492
492 493 def init_reload_doctest(self):
493 494 # Do a proper resetting of doctest, including the necessary displayhook
494 495 # monkeypatching
495 496 try:
496 497 doctest_reload()
497 498 except ImportError:
498 499 warn("doctest module does not exist.")
499 500
500 501 #-------------------------------------------------------------------------
501 502 # Things related to injections into the sys module
502 503 #-------------------------------------------------------------------------
503 504
504 505 def save_sys_module_state(self):
505 506 """Save the state of hooks in the sys module.
506 507
507 508 This has to be called after self.user_ns is created.
508 509 """
509 510 self._orig_sys_module_state = {}
510 511 self._orig_sys_module_state['stdin'] = sys.stdin
511 512 self._orig_sys_module_state['stdout'] = sys.stdout
512 513 self._orig_sys_module_state['stderr'] = sys.stderr
513 514 self._orig_sys_module_state['excepthook'] = sys.excepthook
514 515 try:
515 516 self._orig_sys_modules_main_name = self.user_ns['__name__']
516 517 except KeyError:
517 518 pass
518 519
519 520 def restore_sys_module_state(self):
520 521 """Restore the state of the sys module."""
521 522 try:
522 523 for k, v in self._orig_sys_module_state.iteritems():
523 524 setattr(sys, k, v)
524 525 except AttributeError:
525 526 pass
526 527 # Reset what what done in self.init_sys_modules
527 528 try:
528 529 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
529 530 except (AttributeError, KeyError):
530 531 pass
531 532
532 533 #-------------------------------------------------------------------------
533 534 # Things related to hooks
534 535 #-------------------------------------------------------------------------
535 536
536 537 def init_hooks(self):
537 538 # hooks holds pointers used for user-side customizations
538 539 self.hooks = Struct()
539 540
540 541 self.strdispatchers = {}
541 542
542 543 # Set all default hooks, defined in the IPython.hooks module.
543 544 hooks = IPython.core.hooks
544 545 for hook_name in hooks.__all__:
545 546 # default hooks have priority 100, i.e. low; user hooks should have
546 547 # 0-100 priority
547 548 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
548 549
549 550 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
550 551 """set_hook(name,hook) -> sets an internal IPython hook.
551 552
552 553 IPython exposes some of its internal API as user-modifiable hooks. By
553 554 adding your function to one of these hooks, you can modify IPython's
554 555 behavior to call at runtime your own routines."""
555 556
556 557 # At some point in the future, this should validate the hook before it
557 558 # accepts it. Probably at least check that the hook takes the number
558 559 # of args it's supposed to.
559 560
560 561 f = types.MethodType(hook,self)
561 562
562 563 # check if the hook is for strdispatcher first
563 564 if str_key is not None:
564 565 sdp = self.strdispatchers.get(name, StrDispatch())
565 566 sdp.add_s(str_key, f, priority )
566 567 self.strdispatchers[name] = sdp
567 568 return
568 569 if re_key is not None:
569 570 sdp = self.strdispatchers.get(name, StrDispatch())
570 571 sdp.add_re(re.compile(re_key), f, priority )
571 572 self.strdispatchers[name] = sdp
572 573 return
573 574
574 575 dp = getattr(self.hooks, name, None)
575 576 if name not in IPython.core.hooks.__all__:
576 577 print "Warning! Hook '%s' is not one of %s" % \
577 578 (name, IPython.core.hooks.__all__ )
578 579 if not dp:
579 580 dp = IPython.core.hooks.CommandChainDispatcher()
580 581
581 582 try:
582 583 dp.add(f,priority)
583 584 except AttributeError:
584 585 # it was not commandchain, plain old func - replace
585 586 dp = f
586 587
587 588 setattr(self.hooks,name, dp)
588 589
589 590 def register_post_execute(self, func):
590 591 """Register a function for calling after code execution.
591 592 """
592 593 if not callable(func):
593 594 raise ValueError('argument %s must be callable' % func)
594 595 self._post_execute.add(func)
595 596
596 597 #-------------------------------------------------------------------------
597 598 # Things related to the "main" module
598 599 #-------------------------------------------------------------------------
599 600
600 601 def new_main_mod(self,ns=None):
601 602 """Return a new 'main' module object for user code execution.
602 603 """
603 604 main_mod = self._user_main_module
604 605 init_fakemod_dict(main_mod,ns)
605 606 return main_mod
606 607
607 608 def cache_main_mod(self,ns,fname):
608 609 """Cache a main module's namespace.
609 610
610 611 When scripts are executed via %run, we must keep a reference to the
611 612 namespace of their __main__ module (a FakeModule instance) around so
612 613 that Python doesn't clear it, rendering objects defined therein
613 614 useless.
614 615
615 616 This method keeps said reference in a private dict, keyed by the
616 617 absolute path of the module object (which corresponds to the script
617 618 path). This way, for multiple executions of the same script we only
618 619 keep one copy of the namespace (the last one), thus preventing memory
619 620 leaks from old references while allowing the objects from the last
620 621 execution to be accessible.
621 622
622 623 Note: we can not allow the actual FakeModule instances to be deleted,
623 624 because of how Python tears down modules (it hard-sets all their
624 625 references to None without regard for reference counts). This method
625 626 must therefore make a *copy* of the given namespace, to allow the
626 627 original module's __dict__ to be cleared and reused.
627 628
628 629
629 630 Parameters
630 631 ----------
631 632 ns : a namespace (a dict, typically)
632 633
633 634 fname : str
634 635 Filename associated with the namespace.
635 636
636 637 Examples
637 638 --------
638 639
639 640 In [10]: import IPython
640 641
641 642 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
642 643
643 644 In [12]: IPython.__file__ in _ip._main_ns_cache
644 645 Out[12]: True
645 646 """
646 647 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
647 648
648 649 def clear_main_mod_cache(self):
649 650 """Clear the cache of main modules.
650 651
651 652 Mainly for use by utilities like %reset.
652 653
653 654 Examples
654 655 --------
655 656
656 657 In [15]: import IPython
657 658
658 659 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
659 660
660 661 In [17]: len(_ip._main_ns_cache) > 0
661 662 Out[17]: True
662 663
663 664 In [18]: _ip.clear_main_mod_cache()
664 665
665 666 In [19]: len(_ip._main_ns_cache) == 0
666 667 Out[19]: True
667 668 """
668 669 self._main_ns_cache.clear()
669 670
670 671 #-------------------------------------------------------------------------
671 672 # Things related to debugging
672 673 #-------------------------------------------------------------------------
673 674
674 675 def init_pdb(self):
675 676 # Set calling of pdb on exceptions
676 677 # self.call_pdb is a property
677 678 self.call_pdb = self.pdb
678 679
679 680 def _get_call_pdb(self):
680 681 return self._call_pdb
681 682
682 683 def _set_call_pdb(self,val):
683 684
684 685 if val not in (0,1,False,True):
685 686 raise ValueError,'new call_pdb value must be boolean'
686 687
687 688 # store value in instance
688 689 self._call_pdb = val
689 690
690 691 # notify the actual exception handlers
691 692 self.InteractiveTB.call_pdb = val
692 693
693 694 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
694 695 'Control auto-activation of pdb at exceptions')
695 696
696 697 def debugger(self,force=False):
697 698 """Call the pydb/pdb debugger.
698 699
699 700 Keywords:
700 701
701 702 - force(False): by default, this routine checks the instance call_pdb
702 703 flag and does not actually invoke the debugger if the flag is false.
703 704 The 'force' option forces the debugger to activate even if the flag
704 705 is false.
705 706 """
706 707
707 708 if not (force or self.call_pdb):
708 709 return
709 710
710 711 if not hasattr(sys,'last_traceback'):
711 712 error('No traceback has been produced, nothing to debug.')
712 713 return
713 714
714 715 # use pydb if available
715 716 if debugger.has_pydb:
716 717 from pydb import pm
717 718 else:
718 719 # fallback to our internal debugger
719 720 pm = lambda : self.InteractiveTB.debugger(force=True)
720 721 self.history_saving_wrapper(pm)()
721 722
722 723 #-------------------------------------------------------------------------
723 724 # Things related to IPython's various namespaces
724 725 #-------------------------------------------------------------------------
725 726
726 727 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
727 728 # Create the namespace where the user will operate. user_ns is
728 729 # normally the only one used, and it is passed to the exec calls as
729 730 # the locals argument. But we do carry a user_global_ns namespace
730 731 # given as the exec 'globals' argument, This is useful in embedding
731 732 # situations where the ipython shell opens in a context where the
732 733 # distinction between locals and globals is meaningful. For
733 734 # non-embedded contexts, it is just the same object as the user_ns dict.
734 735
735 736 # FIXME. For some strange reason, __builtins__ is showing up at user
736 737 # level as a dict instead of a module. This is a manual fix, but I
737 738 # should really track down where the problem is coming from. Alex
738 739 # Schmolck reported this problem first.
739 740
740 741 # A useful post by Alex Martelli on this topic:
741 742 # Re: inconsistent value from __builtins__
742 743 # Von: Alex Martelli <aleaxit@yahoo.com>
743 744 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
744 745 # Gruppen: comp.lang.python
745 746
746 747 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
747 748 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
748 749 # > <type 'dict'>
749 750 # > >>> print type(__builtins__)
750 751 # > <type 'module'>
751 752 # > Is this difference in return value intentional?
752 753
753 754 # Well, it's documented that '__builtins__' can be either a dictionary
754 755 # or a module, and it's been that way for a long time. Whether it's
755 756 # intentional (or sensible), I don't know. In any case, the idea is
756 757 # that if you need to access the built-in namespace directly, you
757 758 # should start with "import __builtin__" (note, no 's') which will
758 759 # definitely give you a module. Yeah, it's somewhat confusing:-(.
759 760
760 761 # These routines return properly built dicts as needed by the rest of
761 762 # the code, and can also be used by extension writers to generate
762 763 # properly initialized namespaces.
763 764 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
764 765 user_global_ns)
765 766
766 767 # Assign namespaces
767 768 # This is the namespace where all normal user variables live
768 769 self.user_ns = user_ns
769 770 self.user_global_ns = user_global_ns
770 771
771 772 # An auxiliary namespace that checks what parts of the user_ns were
772 773 # loaded at startup, so we can list later only variables defined in
773 774 # actual interactive use. Since it is always a subset of user_ns, it
774 775 # doesn't need to be separately tracked in the ns_table.
775 776 self.user_ns_hidden = {}
776 777
777 778 # A namespace to keep track of internal data structures to prevent
778 779 # them from cluttering user-visible stuff. Will be updated later
779 780 self.internal_ns = {}
780 781
781 782 # Now that FakeModule produces a real module, we've run into a nasty
782 783 # problem: after script execution (via %run), the module where the user
783 784 # code ran is deleted. Now that this object is a true module (needed
784 785 # so docetst and other tools work correctly), the Python module
785 786 # teardown mechanism runs over it, and sets to None every variable
786 787 # present in that module. Top-level references to objects from the
787 788 # script survive, because the user_ns is updated with them. However,
788 789 # calling functions defined in the script that use other things from
789 790 # the script will fail, because the function's closure had references
790 791 # to the original objects, which are now all None. So we must protect
791 792 # these modules from deletion by keeping a cache.
792 793 #
793 794 # To avoid keeping stale modules around (we only need the one from the
794 795 # last run), we use a dict keyed with the full path to the script, so
795 796 # only the last version of the module is held in the cache. Note,
796 797 # however, that we must cache the module *namespace contents* (their
797 798 # __dict__). Because if we try to cache the actual modules, old ones
798 799 # (uncached) could be destroyed while still holding references (such as
799 800 # those held by GUI objects that tend to be long-lived)>
800 801 #
801 802 # The %reset command will flush this cache. See the cache_main_mod()
802 803 # and clear_main_mod_cache() methods for details on use.
803 804
804 805 # This is the cache used for 'main' namespaces
805 806 self._main_ns_cache = {}
806 807 # And this is the single instance of FakeModule whose __dict__ we keep
807 808 # copying and clearing for reuse on each %run
808 809 self._user_main_module = FakeModule()
809 810
810 811 # A table holding all the namespaces IPython deals with, so that
811 812 # introspection facilities can search easily.
812 813 self.ns_table = {'user':user_ns,
813 814 'user_global':user_global_ns,
814 815 'internal':self.internal_ns,
815 816 'builtin':__builtin__.__dict__
816 817 }
817 818
818 819 # Similarly, track all namespaces where references can be held and that
819 820 # we can safely clear (so it can NOT include builtin). This one can be
820 821 # a simple list. Note that the main execution namespaces, user_ns and
821 822 # user_global_ns, can NOT be listed here, as clearing them blindly
822 823 # causes errors in object __del__ methods. Instead, the reset() method
823 824 # clears them manually and carefully.
824 825 self.ns_refs_table = [ self.user_ns_hidden,
825 826 self.internal_ns, self._main_ns_cache ]
826 827
827 828 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
828 829 """Return a valid local and global user interactive namespaces.
829 830
830 831 This builds a dict with the minimal information needed to operate as a
831 832 valid IPython user namespace, which you can pass to the various
832 833 embedding classes in ipython. The default implementation returns the
833 834 same dict for both the locals and the globals to allow functions to
834 835 refer to variables in the namespace. Customized implementations can
835 836 return different dicts. The locals dictionary can actually be anything
836 837 following the basic mapping protocol of a dict, but the globals dict
837 838 must be a true dict, not even a subclass. It is recommended that any
838 839 custom object for the locals namespace synchronize with the globals
839 840 dict somehow.
840 841
841 842 Raises TypeError if the provided globals namespace is not a true dict.
842 843
843 844 Parameters
844 845 ----------
845 846 user_ns : dict-like, optional
846 847 The current user namespace. The items in this namespace should
847 848 be included in the output. If None, an appropriate blank
848 849 namespace should be created.
849 850 user_global_ns : dict, optional
850 851 The current user global namespace. The items in this namespace
851 852 should be included in the output. If None, an appropriate
852 853 blank namespace should be created.
853 854
854 855 Returns
855 856 -------
856 857 A pair of dictionary-like object to be used as the local namespace
857 858 of the interpreter and a dict to be used as the global namespace.
858 859 """
859 860
860 861
861 862 # We must ensure that __builtin__ (without the final 's') is always
862 863 # available and pointing to the __builtin__ *module*. For more details:
863 864 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
864 865
865 866 if user_ns is None:
866 867 # Set __name__ to __main__ to better match the behavior of the
867 868 # normal interpreter.
868 869 user_ns = {'__name__' :'__main__',
869 870 '__builtin__' : __builtin__,
870 871 '__builtins__' : __builtin__,
871 872 }
872 873 else:
873 874 user_ns.setdefault('__name__','__main__')
874 875 user_ns.setdefault('__builtin__',__builtin__)
875 876 user_ns.setdefault('__builtins__',__builtin__)
876 877
877 878 if user_global_ns is None:
878 879 user_global_ns = user_ns
879 880 if type(user_global_ns) is not dict:
880 881 raise TypeError("user_global_ns must be a true dict; got %r"
881 882 % type(user_global_ns))
882 883
883 884 return user_ns, user_global_ns
884 885
885 886 def init_sys_modules(self):
886 887 # We need to insert into sys.modules something that looks like a
887 888 # module but which accesses the IPython namespace, for shelve and
888 889 # pickle to work interactively. Normally they rely on getting
889 890 # everything out of __main__, but for embedding purposes each IPython
890 891 # instance has its own private namespace, so we can't go shoving
891 892 # everything into __main__.
892 893
893 894 # note, however, that we should only do this for non-embedded
894 895 # ipythons, which really mimic the __main__.__dict__ with their own
895 896 # namespace. Embedded instances, on the other hand, should not do
896 897 # this because they need to manage the user local/global namespaces
897 898 # only, but they live within a 'normal' __main__ (meaning, they
898 899 # shouldn't overtake the execution environment of the script they're
899 900 # embedded in).
900 901
901 902 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
902 903
903 904 try:
904 905 main_name = self.user_ns['__name__']
905 906 except KeyError:
906 907 raise KeyError('user_ns dictionary MUST have a "__name__" key')
907 908 else:
908 909 sys.modules[main_name] = FakeModule(self.user_ns)
909 910
910 911 def init_user_ns(self):
911 912 """Initialize all user-visible namespaces to their minimum defaults.
912 913
913 914 Certain history lists are also initialized here, as they effectively
914 915 act as user namespaces.
915 916
916 917 Notes
917 918 -----
918 919 All data structures here are only filled in, they are NOT reset by this
919 920 method. If they were not empty before, data will simply be added to
920 921 therm.
921 922 """
922 923 # This function works in two parts: first we put a few things in
923 924 # user_ns, and we sync that contents into user_ns_hidden so that these
924 925 # initial variables aren't shown by %who. After the sync, we add the
925 926 # rest of what we *do* want the user to see with %who even on a new
926 927 # session (probably nothing, so theye really only see their own stuff)
927 928
928 929 # The user dict must *always* have a __builtin__ reference to the
929 930 # Python standard __builtin__ namespace, which must be imported.
930 931 # This is so that certain operations in prompt evaluation can be
931 932 # reliably executed with builtins. Note that we can NOT use
932 933 # __builtins__ (note the 's'), because that can either be a dict or a
933 934 # module, and can even mutate at runtime, depending on the context
934 935 # (Python makes no guarantees on it). In contrast, __builtin__ is
935 936 # always a module object, though it must be explicitly imported.
936 937
937 938 # For more details:
938 939 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
939 940 ns = dict(__builtin__ = __builtin__)
940 941
941 942 # Put 'help' in the user namespace
942 943 try:
943 944 from site import _Helper
944 945 ns['help'] = _Helper()
945 946 except ImportError:
946 947 warn('help() not available - check site.py')
947 948
948 949 # make global variables for user access to the histories
949 950 ns['_ih'] = self.input_hist
950 951 ns['_oh'] = self.output_hist
951 952 ns['_dh'] = self.dir_hist
952 953
953 954 ns['_sh'] = shadowns
954 955
955 956 # user aliases to input and output histories. These shouldn't show up
956 957 # in %who, as they can have very large reprs.
957 958 ns['In'] = self.input_hist
958 959 ns['Out'] = self.output_hist
959 960
960 961 # Store myself as the public api!!!
961 962 ns['get_ipython'] = self.get_ipython
962 963
963 964 # Sync what we've added so far to user_ns_hidden so these aren't seen
964 965 # by %who
965 966 self.user_ns_hidden.update(ns)
966 967
967 968 # Anything put into ns now would show up in %who. Think twice before
968 969 # putting anything here, as we really want %who to show the user their
969 970 # stuff, not our variables.
970 971
971 972 # Finally, update the real user's namespace
972 973 self.user_ns.update(ns)
973 974
974 975 def reset(self):
975 976 """Clear all internal namespaces.
976 977
977 978 Note that this is much more aggressive than %reset, since it clears
978 979 fully all namespaces, as well as all input/output lists.
979 980 """
980 981 # Clear histories
981 982 self.history_manager.reset()
982 983
983 984 # Reset counter used to index all histories
984 985 self.execution_count = 0
985 986
986 987 # Restore the user namespaces to minimal usability
987 988 for ns in self.ns_refs_table:
988 989 ns.clear()
989 990
990 991 # The main execution namespaces must be cleared very carefully,
991 992 # skipping the deletion of the builtin-related keys, because doing so
992 993 # would cause errors in many object's __del__ methods.
993 994 for ns in [self.user_ns, self.user_global_ns]:
994 995 drop_keys = set(ns.keys())
995 996 drop_keys.discard('__builtin__')
996 997 drop_keys.discard('__builtins__')
997 998 for k in drop_keys:
998 999 del ns[k]
999 1000
1000 1001 # Restore the user namespaces to minimal usability
1001 1002 self.init_user_ns()
1002 1003
1003 1004 # Restore the default and user aliases
1004 1005 self.alias_manager.clear_aliases()
1005 1006 self.alias_manager.init_aliases()
1006 1007
1007 1008 def reset_selective(self, regex=None):
1008 1009 """Clear selective variables from internal namespaces based on a
1009 1010 specified regular expression.
1010 1011
1011 1012 Parameters
1012 1013 ----------
1013 1014 regex : string or compiled pattern, optional
1014 1015 A regular expression pattern that will be used in searching
1015 1016 variable names in the users namespaces.
1016 1017 """
1017 1018 if regex is not None:
1018 1019 try:
1019 1020 m = re.compile(regex)
1020 1021 except TypeError:
1021 1022 raise TypeError('regex must be a string or compiled pattern')
1022 1023 # Search for keys in each namespace that match the given regex
1023 1024 # If a match is found, delete the key/value pair.
1024 1025 for ns in self.ns_refs_table:
1025 1026 for var in ns:
1026 1027 if m.search(var):
1027 1028 del ns[var]
1028 1029
1029 1030 def push(self, variables, interactive=True):
1030 1031 """Inject a group of variables into the IPython user namespace.
1031 1032
1032 1033 Parameters
1033 1034 ----------
1034 1035 variables : dict, str or list/tuple of str
1035 1036 The variables to inject into the user's namespace. If a dict, a
1036 1037 simple update is done. If a str, the string is assumed to have
1037 1038 variable names separated by spaces. A list/tuple of str can also
1038 1039 be used to give the variable names. If just the variable names are
1039 1040 give (list/tuple/str) then the variable values looked up in the
1040 1041 callers frame.
1041 1042 interactive : bool
1042 1043 If True (default), the variables will be listed with the ``who``
1043 1044 magic.
1044 1045 """
1045 1046 vdict = None
1046 1047
1047 1048 # We need a dict of name/value pairs to do namespace updates.
1048 1049 if isinstance(variables, dict):
1049 1050 vdict = variables
1050 1051 elif isinstance(variables, (basestring, list, tuple)):
1051 1052 if isinstance(variables, basestring):
1052 1053 vlist = variables.split()
1053 1054 else:
1054 1055 vlist = variables
1055 1056 vdict = {}
1056 1057 cf = sys._getframe(1)
1057 1058 for name in vlist:
1058 1059 try:
1059 1060 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1060 1061 except:
1061 1062 print ('Could not get variable %s from %s' %
1062 1063 (name,cf.f_code.co_name))
1063 1064 else:
1064 1065 raise ValueError('variables must be a dict/str/list/tuple')
1065 1066
1066 1067 # Propagate variables to user namespace
1067 1068 self.user_ns.update(vdict)
1068 1069
1069 1070 # And configure interactive visibility
1070 1071 config_ns = self.user_ns_hidden
1071 1072 if interactive:
1072 1073 for name, val in vdict.iteritems():
1073 1074 config_ns.pop(name, None)
1074 1075 else:
1075 1076 for name,val in vdict.iteritems():
1076 1077 config_ns[name] = val
1077 1078
1078 1079 #-------------------------------------------------------------------------
1079 1080 # Things related to object introspection
1080 1081 #-------------------------------------------------------------------------
1081 1082
1082 1083 def _ofind(self, oname, namespaces=None):
1083 1084 """Find an object in the available namespaces.
1084 1085
1085 1086 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1086 1087
1087 1088 Has special code to detect magic functions.
1088 1089 """
1089 1090 #oname = oname.strip()
1090 1091 #print '1- oname: <%r>' % oname # dbg
1091 1092 try:
1092 1093 oname = oname.strip().encode('ascii')
1093 1094 #print '2- oname: <%r>' % oname # dbg
1094 1095 except UnicodeEncodeError:
1095 1096 print 'Python identifiers can only contain ascii characters.'
1096 1097 return dict(found=False)
1097 1098
1098 1099 alias_ns = None
1099 1100 if namespaces is None:
1100 1101 # Namespaces to search in:
1101 1102 # Put them in a list. The order is important so that we
1102 1103 # find things in the same order that Python finds them.
1103 1104 namespaces = [ ('Interactive', self.user_ns),
1104 1105 ('IPython internal', self.internal_ns),
1105 1106 ('Python builtin', __builtin__.__dict__),
1106 1107 ('Alias', self.alias_manager.alias_table),
1107 1108 ]
1108 1109 alias_ns = self.alias_manager.alias_table
1109 1110
1110 1111 # initialize results to 'null'
1111 1112 found = False; obj = None; ospace = None; ds = None;
1112 1113 ismagic = False; isalias = False; parent = None
1113 1114
1114 1115 # We need to special-case 'print', which as of python2.6 registers as a
1115 1116 # function but should only be treated as one if print_function was
1116 1117 # loaded with a future import. In this case, just bail.
1117 1118 if (oname == 'print' and not (self.compile.compiler_flags &
1118 1119 __future__.CO_FUTURE_PRINT_FUNCTION)):
1119 1120 return {'found':found, 'obj':obj, 'namespace':ospace,
1120 1121 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1121 1122
1122 1123 # Look for the given name by splitting it in parts. If the head is
1123 1124 # found, then we look for all the remaining parts as members, and only
1124 1125 # declare success if we can find them all.
1125 1126 oname_parts = oname.split('.')
1126 1127 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1127 1128 for nsname,ns in namespaces:
1128 1129 try:
1129 1130 obj = ns[oname_head]
1130 1131 except KeyError:
1131 1132 continue
1132 1133 else:
1133 1134 #print 'oname_rest:', oname_rest # dbg
1134 1135 for part in oname_rest:
1135 1136 try:
1136 1137 parent = obj
1137 1138 obj = getattr(obj,part)
1138 1139 except:
1139 1140 # Blanket except b/c some badly implemented objects
1140 1141 # allow __getattr__ to raise exceptions other than
1141 1142 # AttributeError, which then crashes IPython.
1142 1143 break
1143 1144 else:
1144 1145 # If we finish the for loop (no break), we got all members
1145 1146 found = True
1146 1147 ospace = nsname
1147 1148 if ns == alias_ns:
1148 1149 isalias = True
1149 1150 break # namespace loop
1150 1151
1151 1152 # Try to see if it's magic
1152 1153 if not found:
1153 1154 if oname.startswith(ESC_MAGIC):
1154 1155 oname = oname[1:]
1155 1156 obj = getattr(self,'magic_'+oname,None)
1156 1157 if obj is not None:
1157 1158 found = True
1158 1159 ospace = 'IPython internal'
1159 1160 ismagic = True
1160 1161
1161 1162 # Last try: special-case some literals like '', [], {}, etc:
1162 1163 if not found and oname_head in ["''",'""','[]','{}','()']:
1163 1164 obj = eval(oname_head)
1164 1165 found = True
1165 1166 ospace = 'Interactive'
1166 1167
1167 1168 return {'found':found, 'obj':obj, 'namespace':ospace,
1168 1169 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1169 1170
1170 1171 def _ofind_property(self, oname, info):
1171 1172 """Second part of object finding, to look for property details."""
1172 1173 if info.found:
1173 1174 # Get the docstring of the class property if it exists.
1174 1175 path = oname.split('.')
1175 1176 root = '.'.join(path[:-1])
1176 1177 if info.parent is not None:
1177 1178 try:
1178 1179 target = getattr(info.parent, '__class__')
1179 1180 # The object belongs to a class instance.
1180 1181 try:
1181 1182 target = getattr(target, path[-1])
1182 1183 # The class defines the object.
1183 1184 if isinstance(target, property):
1184 1185 oname = root + '.__class__.' + path[-1]
1185 1186 info = Struct(self._ofind(oname))
1186 1187 except AttributeError: pass
1187 1188 except AttributeError: pass
1188 1189
1189 1190 # We return either the new info or the unmodified input if the object
1190 1191 # hadn't been found
1191 1192 return info
1192 1193
1193 1194 def _object_find(self, oname, namespaces=None):
1194 1195 """Find an object and return a struct with info about it."""
1195 1196 inf = Struct(self._ofind(oname, namespaces))
1196 1197 return Struct(self._ofind_property(oname, inf))
1197 1198
1198 1199 def _inspect(self, meth, oname, namespaces=None, **kw):
1199 1200 """Generic interface to the inspector system.
1200 1201
1201 1202 This function is meant to be called by pdef, pdoc & friends."""
1202 1203 info = self._object_find(oname)
1203 1204 if info.found:
1204 1205 pmethod = getattr(self.inspector, meth)
1205 1206 formatter = format_screen if info.ismagic else None
1206 1207 if meth == 'pdoc':
1207 1208 pmethod(info.obj, oname, formatter)
1208 1209 elif meth == 'pinfo':
1209 1210 pmethod(info.obj, oname, formatter, info, **kw)
1210 1211 else:
1211 1212 pmethod(info.obj, oname)
1212 1213 else:
1213 1214 print 'Object `%s` not found.' % oname
1214 1215 return 'not found' # so callers can take other action
1215 1216
1216 1217 def object_inspect(self, oname):
1217 1218 info = self._object_find(oname)
1218 1219 if info.found:
1219 1220 return self.inspector.info(info.obj, oname, info=info)
1220 1221 else:
1221 1222 return oinspect.object_info(name=oname, found=False)
1222 1223
1223 1224 #-------------------------------------------------------------------------
1224 1225 # Things related to history management
1225 1226 #-------------------------------------------------------------------------
1226 1227
1227 1228 def init_history(self):
1228 1229 self.history_manager = HistoryManager(shell=self)
1229 1230
1230 1231 def save_hist(self):
1231 1232 """Save input history to a file (via readline library)."""
1232 1233 self.history_manager.save_hist()
1233 1234
1234 1235 # For backwards compatibility
1235 1236 savehist = save_hist
1236 1237
1237 1238 def reload_hist(self):
1238 1239 """Reload the input history from disk file."""
1239 1240 self.history_manager.reload_hist()
1240 1241
1241 1242 # For backwards compatibility
1242 1243 reloadhist = reload_hist
1243 1244
1244 1245 def history_saving_wrapper(self, func):
1245 1246 """ Wrap func for readline history saving
1246 1247
1247 1248 Convert func into callable that saves & restores
1248 1249 history around the call """
1249 1250
1250 1251 if self.has_readline:
1251 1252 from IPython.utils import rlineimpl as readline
1252 1253 else:
1253 1254 return func
1254 1255
1255 1256 def wrapper():
1256 1257 self.save_hist()
1257 1258 try:
1258 1259 func()
1259 1260 finally:
1260 1261 readline.read_history_file(self.histfile)
1261 1262 return wrapper
1262 1263
1263 1264 #-------------------------------------------------------------------------
1264 1265 # Things related to exception handling and tracebacks (not debugging)
1265 1266 #-------------------------------------------------------------------------
1266 1267
1267 1268 def init_traceback_handlers(self, custom_exceptions):
1268 1269 # Syntax error handler.
1269 1270 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1270 1271
1271 1272 # The interactive one is initialized with an offset, meaning we always
1272 1273 # want to remove the topmost item in the traceback, which is our own
1273 1274 # internal code. Valid modes: ['Plain','Context','Verbose']
1274 1275 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1275 1276 color_scheme='NoColor',
1276 1277 tb_offset = 1,
1277 1278 check_cache=self.compile.check_cache)
1278 1279
1279 1280 # The instance will store a pointer to the system-wide exception hook,
1280 1281 # so that runtime code (such as magics) can access it. This is because
1281 1282 # during the read-eval loop, it may get temporarily overwritten.
1282 1283 self.sys_excepthook = sys.excepthook
1283 1284
1284 1285 # and add any custom exception handlers the user may have specified
1285 1286 self.set_custom_exc(*custom_exceptions)
1286 1287
1287 1288 # Set the exception mode
1288 1289 self.InteractiveTB.set_mode(mode=self.xmode)
1289 1290
1290 1291 def set_custom_exc(self, exc_tuple, handler):
1291 1292 """set_custom_exc(exc_tuple,handler)
1292 1293
1293 1294 Set a custom exception handler, which will be called if any of the
1294 1295 exceptions in exc_tuple occur in the mainloop (specifically, in the
1295 1296 run_code() method.
1296 1297
1297 1298 Inputs:
1298 1299
1299 1300 - exc_tuple: a *tuple* of valid exceptions to call the defined
1300 1301 handler for. It is very important that you use a tuple, and NOT A
1301 1302 LIST here, because of the way Python's except statement works. If
1302 1303 you only want to trap a single exception, use a singleton tuple:
1303 1304
1304 1305 exc_tuple == (MyCustomException,)
1305 1306
1306 1307 - handler: this must be defined as a function with the following
1307 1308 basic interface::
1308 1309
1309 1310 def my_handler(self, etype, value, tb, tb_offset=None)
1310 1311 ...
1311 1312 # The return value must be
1312 1313 return structured_traceback
1313 1314
1314 1315 This will be made into an instance method (via types.MethodType)
1315 1316 of IPython itself, and it will be called if any of the exceptions
1316 1317 listed in the exc_tuple are caught. If the handler is None, an
1317 1318 internal basic one is used, which just prints basic info.
1318 1319
1319 1320 WARNING: by putting in your own exception handler into IPython's main
1320 1321 execution loop, you run a very good chance of nasty crashes. This
1321 1322 facility should only be used if you really know what you are doing."""
1322 1323
1323 1324 assert type(exc_tuple)==type(()) , \
1324 1325 "The custom exceptions must be given AS A TUPLE."
1325 1326
1326 1327 def dummy_handler(self,etype,value,tb):
1327 1328 print '*** Simple custom exception handler ***'
1328 1329 print 'Exception type :',etype
1329 1330 print 'Exception value:',value
1330 1331 print 'Traceback :',tb
1331 1332 print 'Source code :','\n'.join(self.buffer)
1332 1333
1333 1334 if handler is None: handler = dummy_handler
1334 1335
1335 1336 self.CustomTB = types.MethodType(handler,self)
1336 1337 self.custom_exceptions = exc_tuple
1337 1338
1338 1339 def excepthook(self, etype, value, tb):
1339 1340 """One more defense for GUI apps that call sys.excepthook.
1340 1341
1341 1342 GUI frameworks like wxPython trap exceptions and call
1342 1343 sys.excepthook themselves. I guess this is a feature that
1343 1344 enables them to keep running after exceptions that would
1344 1345 otherwise kill their mainloop. This is a bother for IPython
1345 1346 which excepts to catch all of the program exceptions with a try:
1346 1347 except: statement.
1347 1348
1348 1349 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1349 1350 any app directly invokes sys.excepthook, it will look to the user like
1350 1351 IPython crashed. In order to work around this, we can disable the
1351 1352 CrashHandler and replace it with this excepthook instead, which prints a
1352 1353 regular traceback using our InteractiveTB. In this fashion, apps which
1353 1354 call sys.excepthook will generate a regular-looking exception from
1354 1355 IPython, and the CrashHandler will only be triggered by real IPython
1355 1356 crashes.
1356 1357
1357 1358 This hook should be used sparingly, only in places which are not likely
1358 1359 to be true IPython errors.
1359 1360 """
1360 1361 self.showtraceback((etype,value,tb),tb_offset=0)
1361 1362
1362 1363 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1363 1364 exception_only=False):
1364 1365 """Display the exception that just occurred.
1365 1366
1366 1367 If nothing is known about the exception, this is the method which
1367 1368 should be used throughout the code for presenting user tracebacks,
1368 1369 rather than directly invoking the InteractiveTB object.
1369 1370
1370 1371 A specific showsyntaxerror() also exists, but this method can take
1371 1372 care of calling it if needed, so unless you are explicitly catching a
1372 1373 SyntaxError exception, don't try to analyze the stack manually and
1373 1374 simply call this method."""
1374 1375
1375 1376 try:
1376 1377 if exc_tuple is None:
1377 1378 etype, value, tb = sys.exc_info()
1378 1379 else:
1379 1380 etype, value, tb = exc_tuple
1380 1381
1381 1382 if etype is None:
1382 1383 if hasattr(sys, 'last_type'):
1383 1384 etype, value, tb = sys.last_type, sys.last_value, \
1384 1385 sys.last_traceback
1385 1386 else:
1386 1387 self.write_err('No traceback available to show.\n')
1387 1388 return
1388 1389
1389 1390 if etype is SyntaxError:
1390 1391 # Though this won't be called by syntax errors in the input
1391 1392 # line, there may be SyntaxError cases whith imported code.
1392 1393 self.showsyntaxerror(filename)
1393 1394 elif etype is UsageError:
1394 1395 print "UsageError:", value
1395 1396 else:
1396 1397 # WARNING: these variables are somewhat deprecated and not
1397 1398 # necessarily safe to use in a threaded environment, but tools
1398 1399 # like pdb depend on their existence, so let's set them. If we
1399 1400 # find problems in the field, we'll need to revisit their use.
1400 1401 sys.last_type = etype
1401 1402 sys.last_value = value
1402 1403 sys.last_traceback = tb
1403 1404
1404 1405 if etype in self.custom_exceptions:
1405 1406 # FIXME: Old custom traceback objects may just return a
1406 1407 # string, in that case we just put it into a list
1407 1408 stb = self.CustomTB(etype, value, tb, tb_offset)
1408 1409 if isinstance(ctb, basestring):
1409 1410 stb = [stb]
1410 1411 else:
1411 1412 if exception_only:
1412 1413 stb = ['An exception has occurred, use %tb to see '
1413 1414 'the full traceback.\n']
1414 1415 stb.extend(self.InteractiveTB.get_exception_only(etype,
1415 1416 value))
1416 1417 else:
1417 1418 stb = self.InteractiveTB.structured_traceback(etype,
1418 1419 value, tb, tb_offset=tb_offset)
1419 1420 # FIXME: the pdb calling should be done by us, not by
1420 1421 # the code computing the traceback.
1421 1422 if self.InteractiveTB.call_pdb:
1422 1423 # pdb mucks up readline, fix it back
1423 1424 self.set_readline_completer()
1424 1425
1425 1426 # Actually show the traceback
1426 1427 self._showtraceback(etype, value, stb)
1427 1428
1428 1429 except KeyboardInterrupt:
1429 1430 self.write_err("\nKeyboardInterrupt\n")
1430 1431
1431 1432 def _showtraceback(self, etype, evalue, stb):
1432 1433 """Actually show a traceback.
1433 1434
1434 1435 Subclasses may override this method to put the traceback on a different
1435 1436 place, like a side channel.
1436 1437 """
1437 1438 print >> io.Term.cout, self.InteractiveTB.stb2text(stb)
1438 1439
1439 1440 def showsyntaxerror(self, filename=None):
1440 1441 """Display the syntax error that just occurred.
1441 1442
1442 1443 This doesn't display a stack trace because there isn't one.
1443 1444
1444 1445 If a filename is given, it is stuffed in the exception instead
1445 1446 of what was there before (because Python's parser always uses
1446 1447 "<string>" when reading from a string).
1447 1448 """
1448 1449 etype, value, last_traceback = sys.exc_info()
1449 1450
1450 1451 # See note about these variables in showtraceback() above
1451 1452 sys.last_type = etype
1452 1453 sys.last_value = value
1453 1454 sys.last_traceback = last_traceback
1454 1455
1455 1456 if filename and etype is SyntaxError:
1456 1457 # Work hard to stuff the correct filename in the exception
1457 1458 try:
1458 1459 msg, (dummy_filename, lineno, offset, line) = value
1459 1460 except:
1460 1461 # Not the format we expect; leave it alone
1461 1462 pass
1462 1463 else:
1463 1464 # Stuff in the right filename
1464 1465 try:
1465 1466 # Assume SyntaxError is a class exception
1466 1467 value = SyntaxError(msg, (filename, lineno, offset, line))
1467 1468 except:
1468 1469 # If that failed, assume SyntaxError is a string
1469 1470 value = msg, (filename, lineno, offset, line)
1470 1471 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1471 1472 self._showtraceback(etype, value, stb)
1472 1473
1473 1474 #-------------------------------------------------------------------------
1474 1475 # Things related to readline
1475 1476 #-------------------------------------------------------------------------
1476 1477
1477 1478 def init_readline(self):
1478 1479 """Command history completion/saving/reloading."""
1479 1480
1480 1481 if self.readline_use:
1481 1482 import IPython.utils.rlineimpl as readline
1482 1483
1483 1484 self.rl_next_input = None
1484 1485 self.rl_do_indent = False
1485 1486
1486 1487 if not self.readline_use or not readline.have_readline:
1487 1488 self.has_readline = False
1488 1489 self.readline = None
1489 1490 # Set a number of methods that depend on readline to be no-op
1490 1491 self.save_hist = no_op
1491 1492 self.reload_hist = no_op
1492 1493 self.set_readline_completer = no_op
1493 1494 self.set_custom_completer = no_op
1494 1495 self.set_completer_frame = no_op
1495 1496 warn('Readline services not available or not loaded.')
1496 1497 else:
1497 1498 self.has_readline = True
1498 1499 self.readline = readline
1499 1500 sys.modules['readline'] = readline
1500 1501
1501 1502 # Platform-specific configuration
1502 1503 if os.name == 'nt':
1503 1504 # FIXME - check with Frederick to see if we can harmonize
1504 1505 # naming conventions with pyreadline to avoid this
1505 1506 # platform-dependent check
1506 1507 self.readline_startup_hook = readline.set_pre_input_hook
1507 1508 else:
1508 1509 self.readline_startup_hook = readline.set_startup_hook
1509 1510
1510 1511 # Load user's initrc file (readline config)
1511 1512 # Or if libedit is used, load editrc.
1512 1513 inputrc_name = os.environ.get('INPUTRC')
1513 1514 if inputrc_name is None:
1514 1515 home_dir = get_home_dir()
1515 1516 if home_dir is not None:
1516 1517 inputrc_name = '.inputrc'
1517 1518 if readline.uses_libedit:
1518 1519 inputrc_name = '.editrc'
1519 1520 inputrc_name = os.path.join(home_dir, inputrc_name)
1520 1521 if os.path.isfile(inputrc_name):
1521 1522 try:
1522 1523 readline.read_init_file(inputrc_name)
1523 1524 except:
1524 1525 warn('Problems reading readline initialization file <%s>'
1525 1526 % inputrc_name)
1526 1527
1527 1528 # Configure readline according to user's prefs
1528 1529 # This is only done if GNU readline is being used. If libedit
1529 1530 # is being used (as on Leopard) the readline config is
1530 1531 # not run as the syntax for libedit is different.
1531 1532 if not readline.uses_libedit:
1532 1533 for rlcommand in self.readline_parse_and_bind:
1533 1534 #print "loading rl:",rlcommand # dbg
1534 1535 readline.parse_and_bind(rlcommand)
1535 1536
1536 1537 # Remove some chars from the delimiters list. If we encounter
1537 1538 # unicode chars, discard them.
1538 1539 delims = readline.get_completer_delims().encode("ascii", "ignore")
1539 1540 delims = delims.translate(None, self.readline_remove_delims)
1540 1541 delims = delims.replace(ESC_MAGIC, '')
1541 1542 readline.set_completer_delims(delims)
1542 1543 # otherwise we end up with a monster history after a while:
1543 1544 readline.set_history_length(1000)
1544 1545 try:
1545 1546 #print '*** Reading readline history' # dbg
1546 1547 readline.read_history_file(self.histfile)
1547 1548 except IOError:
1548 1549 pass # It doesn't exist yet.
1549 1550
1550 1551 # If we have readline, we want our history saved upon ipython
1551 1552 # exiting.
1552 1553 atexit.register(self.save_hist)
1553 1554
1554 1555 # Configure auto-indent for all platforms
1555 1556 self.set_autoindent(self.autoindent)
1556 1557
1557 1558 def set_next_input(self, s):
1558 1559 """ Sets the 'default' input string for the next command line.
1559 1560
1560 1561 Requires readline.
1561 1562
1562 1563 Example:
1563 1564
1564 1565 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1565 1566 [D:\ipython]|2> Hello Word_ # cursor is here
1566 1567 """
1567 1568
1568 1569 self.rl_next_input = s
1569 1570
1570 1571 # Maybe move this to the terminal subclass?
1571 1572 def pre_readline(self):
1572 1573 """readline hook to be used at the start of each line.
1573 1574
1574 1575 Currently it handles auto-indent only."""
1575 1576
1576 1577 if self.rl_do_indent:
1577 1578 self.readline.insert_text(self._indent_current_str())
1578 1579 if self.rl_next_input is not None:
1579 1580 self.readline.insert_text(self.rl_next_input)
1580 1581 self.rl_next_input = None
1581 1582
1582 1583 def _indent_current_str(self):
1583 1584 """return the current level of indentation as a string"""
1584 1585 return self.input_splitter.indent_spaces * ' '
1585 1586
1586 1587 #-------------------------------------------------------------------------
1587 1588 # Things related to text completion
1588 1589 #-------------------------------------------------------------------------
1589 1590
1590 1591 def init_completer(self):
1591 1592 """Initialize the completion machinery.
1592 1593
1593 1594 This creates completion machinery that can be used by client code,
1594 1595 either interactively in-process (typically triggered by the readline
1595 1596 library), programatically (such as in test suites) or out-of-prcess
1596 1597 (typically over the network by remote frontends).
1597 1598 """
1598 1599 from IPython.core.completer import IPCompleter
1599 1600 from IPython.core.completerlib import (module_completer,
1600 1601 magic_run_completer, cd_completer)
1601 1602
1602 1603 self.Completer = IPCompleter(self,
1603 1604 self.user_ns,
1604 1605 self.user_global_ns,
1605 1606 self.readline_omit__names,
1606 1607 self.alias_manager.alias_table,
1607 1608 self.has_readline)
1608 1609
1609 1610 # Add custom completers to the basic ones built into IPCompleter
1610 1611 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1611 1612 self.strdispatchers['complete_command'] = sdisp
1612 1613 self.Completer.custom_completers = sdisp
1613 1614
1614 1615 self.set_hook('complete_command', module_completer, str_key = 'import')
1615 1616 self.set_hook('complete_command', module_completer, str_key = 'from')
1616 1617 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1617 1618 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1618 1619
1619 1620 # Only configure readline if we truly are using readline. IPython can
1620 1621 # do tab-completion over the network, in GUIs, etc, where readline
1621 1622 # itself may be absent
1622 1623 if self.has_readline:
1623 1624 self.set_readline_completer()
1624 1625
1625 1626 def complete(self, text, line=None, cursor_pos=None):
1626 1627 """Return the completed text and a list of completions.
1627 1628
1628 1629 Parameters
1629 1630 ----------
1630 1631
1631 1632 text : string
1632 1633 A string of text to be completed on. It can be given as empty and
1633 1634 instead a line/position pair are given. In this case, the
1634 1635 completer itself will split the line like readline does.
1635 1636
1636 1637 line : string, optional
1637 1638 The complete line that text is part of.
1638 1639
1639 1640 cursor_pos : int, optional
1640 1641 The position of the cursor on the input line.
1641 1642
1642 1643 Returns
1643 1644 -------
1644 1645 text : string
1645 1646 The actual text that was completed.
1646 1647
1647 1648 matches : list
1648 1649 A sorted list with all possible completions.
1649 1650
1650 1651 The optional arguments allow the completion to take more context into
1651 1652 account, and are part of the low-level completion API.
1652 1653
1653 1654 This is a wrapper around the completion mechanism, similar to what
1654 1655 readline does at the command line when the TAB key is hit. By
1655 1656 exposing it as a method, it can be used by other non-readline
1656 1657 environments (such as GUIs) for text completion.
1657 1658
1658 1659 Simple usage example:
1659 1660
1660 1661 In [1]: x = 'hello'
1661 1662
1662 1663 In [2]: _ip.complete('x.l')
1663 1664 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1664 1665 """
1665 1666
1666 1667 # Inject names into __builtin__ so we can complete on the added names.
1667 1668 with self.builtin_trap:
1668 1669 return self.Completer.complete(text, line, cursor_pos)
1669 1670
1670 1671 def set_custom_completer(self, completer, pos=0):
1671 1672 """Adds a new custom completer function.
1672 1673
1673 1674 The position argument (defaults to 0) is the index in the completers
1674 1675 list where you want the completer to be inserted."""
1675 1676
1676 1677 newcomp = types.MethodType(completer,self.Completer)
1677 1678 self.Completer.matchers.insert(pos,newcomp)
1678 1679
1679 1680 def set_readline_completer(self):
1680 1681 """Reset readline's completer to be our own."""
1681 1682 self.readline.set_completer(self.Completer.rlcomplete)
1682 1683
1683 1684 def set_completer_frame(self, frame=None):
1684 1685 """Set the frame of the completer."""
1685 1686 if frame:
1686 1687 self.Completer.namespace = frame.f_locals
1687 1688 self.Completer.global_namespace = frame.f_globals
1688 1689 else:
1689 1690 self.Completer.namespace = self.user_ns
1690 1691 self.Completer.global_namespace = self.user_global_ns
1691 1692
1692 1693 #-------------------------------------------------------------------------
1693 1694 # Things related to magics
1694 1695 #-------------------------------------------------------------------------
1695 1696
1696 1697 def init_magics(self):
1697 1698 # FIXME: Move the color initialization to the DisplayHook, which
1698 1699 # should be split into a prompt manager and displayhook. We probably
1699 1700 # even need a centralize colors management object.
1700 1701 self.magic_colors(self.colors)
1701 1702 # History was moved to a separate module
1702 1703 from . import history
1703 1704 history.init_ipython(self)
1704 1705
1705 1706 def magic(self,arg_s):
1706 1707 """Call a magic function by name.
1707 1708
1708 1709 Input: a string containing the name of the magic function to call and
1709 1710 any additional arguments to be passed to the magic.
1710 1711
1711 1712 magic('name -opt foo bar') is equivalent to typing at the ipython
1712 1713 prompt:
1713 1714
1714 1715 In[1]: %name -opt foo bar
1715 1716
1716 1717 To call a magic without arguments, simply use magic('name').
1717 1718
1718 1719 This provides a proper Python function to call IPython's magics in any
1719 1720 valid Python code you can type at the interpreter, including loops and
1720 1721 compound statements.
1721 1722 """
1722 1723 args = arg_s.split(' ',1)
1723 1724 magic_name = args[0]
1724 1725 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1725 1726
1726 1727 try:
1727 1728 magic_args = args[1]
1728 1729 except IndexError:
1729 1730 magic_args = ''
1730 1731 fn = getattr(self,'magic_'+magic_name,None)
1731 1732 if fn is None:
1732 1733 error("Magic function `%s` not found." % magic_name)
1733 1734 else:
1734 1735 magic_args = self.var_expand(magic_args,1)
1735 1736 with nested(self.builtin_trap,):
1736 1737 result = fn(magic_args)
1737 1738 return result
1738 1739
1739 1740 def define_magic(self, magicname, func):
1740 1741 """Expose own function as magic function for ipython
1741 1742
1742 1743 def foo_impl(self,parameter_s=''):
1743 1744 'My very own magic!. (Use docstrings, IPython reads them).'
1744 1745 print 'Magic function. Passed parameter is between < >:'
1745 1746 print '<%s>' % parameter_s
1746 1747 print 'The self object is:',self
1747 1748
1748 1749 self.define_magic('foo',foo_impl)
1749 1750 """
1750 1751
1751 1752 import new
1752 1753 im = types.MethodType(func,self)
1753 1754 old = getattr(self, "magic_" + magicname, None)
1754 1755 setattr(self, "magic_" + magicname, im)
1755 1756 return old
1756 1757
1757 1758 #-------------------------------------------------------------------------
1758 1759 # Things related to macros
1759 1760 #-------------------------------------------------------------------------
1760 1761
1761 1762 def define_macro(self, name, themacro):
1762 1763 """Define a new macro
1763 1764
1764 1765 Parameters
1765 1766 ----------
1766 1767 name : str
1767 1768 The name of the macro.
1768 1769 themacro : str or Macro
1769 1770 The action to do upon invoking the macro. If a string, a new
1770 1771 Macro object is created by passing the string to it.
1771 1772 """
1772 1773
1773 1774 from IPython.core import macro
1774 1775
1775 1776 if isinstance(themacro, basestring):
1776 1777 themacro = macro.Macro(themacro)
1777 1778 if not isinstance(themacro, macro.Macro):
1778 1779 raise ValueError('A macro must be a string or a Macro instance.')
1779 1780 self.user_ns[name] = themacro
1780 1781
1781 1782 #-------------------------------------------------------------------------
1782 1783 # Things related to the running of system commands
1783 1784 #-------------------------------------------------------------------------
1784 1785
1785 1786 def system(self, cmd):
1786 1787 """Call the given cmd in a subprocess.
1787 1788
1788 1789 Parameters
1789 1790 ----------
1790 1791 cmd : str
1791 1792 Command to execute (can not end in '&', as bacground processes are
1792 1793 not supported.
1793 1794 """
1794 1795 # We do not support backgrounding processes because we either use
1795 1796 # pexpect or pipes to read from. Users can always just call
1796 1797 # os.system() if they really want a background process.
1797 1798 if cmd.endswith('&'):
1798 1799 raise OSError("Background processes not supported.")
1799 1800
1800 1801 return system(self.var_expand(cmd, depth=2))
1801 1802
1802 1803 def getoutput(self, cmd, split=True):
1803 1804 """Get output (possibly including stderr) from a subprocess.
1804 1805
1805 1806 Parameters
1806 1807 ----------
1807 1808 cmd : str
1808 1809 Command to execute (can not end in '&', as background processes are
1809 1810 not supported.
1810 1811 split : bool, optional
1811 1812
1812 1813 If True, split the output into an IPython SList. Otherwise, an
1813 1814 IPython LSString is returned. These are objects similar to normal
1814 1815 lists and strings, with a few convenience attributes for easier
1815 1816 manipulation of line-based output. You can use '?' on them for
1816 1817 details.
1817 1818 """
1818 1819 if cmd.endswith('&'):
1819 1820 raise OSError("Background processes not supported.")
1820 1821 out = getoutput(self.var_expand(cmd, depth=2))
1821 1822 if split:
1822 1823 out = SList(out.splitlines())
1823 1824 else:
1824 1825 out = LSString(out)
1825 1826 return out
1826 1827
1827 1828 #-------------------------------------------------------------------------
1828 1829 # Things related to aliases
1829 1830 #-------------------------------------------------------------------------
1830 1831
1831 1832 def init_alias(self):
1832 1833 self.alias_manager = AliasManager(shell=self, config=self.config)
1833 1834 self.ns_table['alias'] = self.alias_manager.alias_table,
1834 1835
1835 1836 #-------------------------------------------------------------------------
1836 1837 # Things related to extensions and plugins
1837 1838 #-------------------------------------------------------------------------
1838 1839
1839 1840 def init_extension_manager(self):
1840 1841 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1841 1842
1842 1843 def init_plugin_manager(self):
1843 1844 self.plugin_manager = PluginManager(config=self.config)
1844 1845
1845 1846 #-------------------------------------------------------------------------
1846 1847 # Things related to payloads
1847 1848 #-------------------------------------------------------------------------
1848 1849
1849 1850 def init_payload(self):
1850 1851 self.payload_manager = PayloadManager(config=self.config)
1851 1852
1852 1853 #-------------------------------------------------------------------------
1853 1854 # Things related to the prefilter
1854 1855 #-------------------------------------------------------------------------
1855 1856
1856 1857 def init_prefilter(self):
1857 1858 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1858 1859 # Ultimately this will be refactored in the new interpreter code, but
1859 1860 # for now, we should expose the main prefilter method (there's legacy
1860 1861 # code out there that may rely on this).
1861 1862 self.prefilter = self.prefilter_manager.prefilter_lines
1862 1863
1863 1864 def auto_rewrite_input(self, cmd):
1864 1865 """Print to the screen the rewritten form of the user's command.
1865 1866
1866 1867 This shows visual feedback by rewriting input lines that cause
1867 1868 automatic calling to kick in, like::
1868 1869
1869 1870 /f x
1870 1871
1871 1872 into::
1872 1873
1873 1874 ------> f(x)
1874 1875
1875 1876 after the user's input prompt. This helps the user understand that the
1876 1877 input line was transformed automatically by IPython.
1877 1878 """
1878 1879 rw = self.displayhook.prompt1.auto_rewrite() + cmd
1879 1880
1880 1881 try:
1881 1882 # plain ascii works better w/ pyreadline, on some machines, so
1882 1883 # we use it and only print uncolored rewrite if we have unicode
1883 1884 rw = str(rw)
1884 1885 print >> IPython.utils.io.Term.cout, rw
1885 1886 except UnicodeEncodeError:
1886 1887 print "------> " + cmd
1887 1888
1888 1889 #-------------------------------------------------------------------------
1889 1890 # Things related to extracting values/expressions from kernel and user_ns
1890 1891 #-------------------------------------------------------------------------
1891 1892
1892 1893 def _simple_error(self):
1893 1894 etype, value = sys.exc_info()[:2]
1894 1895 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1895 1896
1896 1897 def user_variables(self, names):
1897 1898 """Get a list of variable names from the user's namespace.
1898 1899
1899 1900 Parameters
1900 1901 ----------
1901 1902 names : list of strings
1902 1903 A list of names of variables to be read from the user namespace.
1903 1904
1904 1905 Returns
1905 1906 -------
1906 1907 A dict, keyed by the input names and with the repr() of each value.
1907 1908 """
1908 1909 out = {}
1909 1910 user_ns = self.user_ns
1910 1911 for varname in names:
1911 1912 try:
1912 1913 value = repr(user_ns[varname])
1913 1914 except:
1914 1915 value = self._simple_error()
1915 1916 out[varname] = value
1916 1917 return out
1917 1918
1918 1919 def user_expressions(self, expressions):
1919 1920 """Evaluate a dict of expressions in the user's namespace.
1920 1921
1921 1922 Parameters
1922 1923 ----------
1923 1924 expressions : dict
1924 1925 A dict with string keys and string values. The expression values
1925 1926 should be valid Python expressions, each of which will be evaluated
1926 1927 in the user namespace.
1927 1928
1928 1929 Returns
1929 1930 -------
1930 1931 A dict, keyed like the input expressions dict, with the repr() of each
1931 1932 value.
1932 1933 """
1933 1934 out = {}
1934 1935 user_ns = self.user_ns
1935 1936 global_ns = self.user_global_ns
1936 1937 for key, expr in expressions.iteritems():
1937 1938 try:
1938 1939 value = repr(eval(expr, global_ns, user_ns))
1939 1940 except:
1940 1941 value = self._simple_error()
1941 1942 out[key] = value
1942 1943 return out
1943 1944
1944 1945 #-------------------------------------------------------------------------
1945 1946 # Things related to the running of code
1946 1947 #-------------------------------------------------------------------------
1947 1948
1948 1949 def ex(self, cmd):
1949 1950 """Execute a normal python statement in user namespace."""
1950 1951 with nested(self.builtin_trap,):
1951 1952 exec cmd in self.user_global_ns, self.user_ns
1952 1953
1953 1954 def ev(self, expr):
1954 1955 """Evaluate python expression expr in user namespace.
1955 1956
1956 1957 Returns the result of evaluation
1957 1958 """
1958 1959 with nested(self.builtin_trap,):
1959 1960 return eval(expr, self.user_global_ns, self.user_ns)
1960 1961
1961 1962 def safe_execfile(self, fname, *where, **kw):
1962 1963 """A safe version of the builtin execfile().
1963 1964
1964 1965 This version will never throw an exception, but instead print
1965 1966 helpful error messages to the screen. This only works on pure
1966 1967 Python files with the .py extension.
1967 1968
1968 1969 Parameters
1969 1970 ----------
1970 1971 fname : string
1971 1972 The name of the file to be executed.
1972 1973 where : tuple
1973 1974 One or two namespaces, passed to execfile() as (globals,locals).
1974 1975 If only one is given, it is passed as both.
1975 1976 exit_ignore : bool (False)
1976 1977 If True, then silence SystemExit for non-zero status (it is always
1977 1978 silenced for zero status, as it is so common).
1978 1979 """
1979 1980 kw.setdefault('exit_ignore', False)
1980 1981
1981 1982 fname = os.path.abspath(os.path.expanduser(fname))
1982 1983
1983 1984 # Make sure we have a .py file
1984 1985 if not fname.endswith('.py'):
1985 1986 warn('File must end with .py to be run using execfile: <%s>' % fname)
1986 1987
1987 1988 # Make sure we can open the file
1988 1989 try:
1989 1990 with open(fname) as thefile:
1990 1991 pass
1991 1992 except:
1992 1993 warn('Could not open file <%s> for safe execution.' % fname)
1993 1994 return
1994 1995
1995 1996 # Find things also in current directory. This is needed to mimic the
1996 1997 # behavior of running a script from the system command line, where
1997 1998 # Python inserts the script's directory into sys.path
1998 1999 dname = os.path.dirname(fname)
1999 2000
2000 2001 with prepended_to_syspath(dname):
2001 2002 try:
2002 2003 execfile(fname,*where)
2003 2004 except SystemExit, status:
2004 2005 # If the call was made with 0 or None exit status (sys.exit(0)
2005 2006 # or sys.exit() ), don't bother showing a traceback, as both of
2006 2007 # these are considered normal by the OS:
2007 2008 # > python -c'import sys;sys.exit(0)'; echo $?
2008 2009 # 0
2009 2010 # > python -c'import sys;sys.exit()'; echo $?
2010 2011 # 0
2011 2012 # For other exit status, we show the exception unless
2012 2013 # explicitly silenced, but only in short form.
2013 2014 if status.code not in (0, None) and not kw['exit_ignore']:
2014 2015 self.showtraceback(exception_only=True)
2015 2016 except:
2016 2017 self.showtraceback()
2017 2018
2018 2019 def safe_execfile_ipy(self, fname):
2019 2020 """Like safe_execfile, but for .ipy files with IPython syntax.
2020 2021
2021 2022 Parameters
2022 2023 ----------
2023 2024 fname : str
2024 2025 The name of the file to execute. The filename must have a
2025 2026 .ipy extension.
2026 2027 """
2027 2028 fname = os.path.abspath(os.path.expanduser(fname))
2028 2029
2029 2030 # Make sure we have a .py file
2030 2031 if not fname.endswith('.ipy'):
2031 2032 warn('File must end with .py to be run using execfile: <%s>' % fname)
2032 2033
2033 2034 # Make sure we can open the file
2034 2035 try:
2035 2036 with open(fname) as thefile:
2036 2037 pass
2037 2038 except:
2038 2039 warn('Could not open file <%s> for safe execution.' % fname)
2039 2040 return
2040 2041
2041 2042 # Find things also in current directory. This is needed to mimic the
2042 2043 # behavior of running a script from the system command line, where
2043 2044 # Python inserts the script's directory into sys.path
2044 2045 dname = os.path.dirname(fname)
2045 2046
2046 2047 with prepended_to_syspath(dname):
2047 2048 try:
2048 2049 with open(fname) as thefile:
2049 2050 # self.run_cell currently captures all exceptions
2050 2051 # raised in user code. It would be nice if there were
2051 2052 # versions of runlines, execfile that did raise, so
2052 2053 # we could catch the errors.
2053 2054 self.run_cell(thefile.read())
2054 2055 except:
2055 2056 self.showtraceback()
2056 2057 warn('Unknown failure executing file: <%s>' % fname)
2057 2058
2058 2059 def run_cell(self, cell):
2059 2060 """Run the contents of an entire multiline 'cell' of code.
2060 2061
2061 2062 The cell is split into separate blocks which can be executed
2062 2063 individually. Then, based on how many blocks there are, they are
2063 2064 executed as follows:
2064 2065
2065 2066 - A single block: 'single' mode.
2066 2067
2067 2068 If there's more than one block, it depends:
2068 2069
2069 2070 - if the last one is no more than two lines long, run all but the last
2070 2071 in 'exec' mode and the very last one in 'single' mode. This makes it
2071 2072 easy to type simple expressions at the end to see computed values. -
2072 2073 otherwise (last one is also multiline), run all in 'exec' mode
2073 2074
2074 2075 When code is executed in 'single' mode, :func:`sys.displayhook` fires,
2075 2076 results are displayed and output prompts are computed. In 'exec' mode,
2076 2077 no results are displayed unless :func:`print` is called explicitly;
2077 2078 this mode is more akin to running a script.
2078 2079
2079 2080 Parameters
2080 2081 ----------
2081 2082 cell : str
2082 2083 A single or multiline string.
2083 2084 """
2084 2085
2085 2086 # We need to break up the input into executable blocks that can be run
2086 2087 # in 'single' mode, to provide comfortable user behavior.
2087 2088 blocks = self.input_splitter.split_blocks(cell)
2088 2089
2089 2090 if not blocks:
2090 2091 return
2091 2092
2092 2093 # Store the 'ipython' version of the cell as well, since that's what
2093 2094 # needs to go into the translated history and get executed (the
2094 2095 # original cell may contain non-python syntax).
2095 2096 ipy_cell = ''.join(blocks)
2096 2097
2097 2098 # Store raw and processed history
2098 2099 self.history_manager.store_inputs(ipy_cell, cell)
2099 2100
2100 2101 self.logger.log(ipy_cell, cell)
2101 2102 # dbg code!!!
2102 2103 if 0:
2103 2104 def myapp(self, val): # dbg
2104 2105 import traceback as tb
2105 2106 stack = ''.join(tb.format_stack())
2106 2107 print 'Value:', val
2107 2108 print 'Stack:\n', stack
2108 2109 list.append(self, val)
2109 2110
2110 2111 import new
2111 2112 self.input_hist.append = types.MethodType(myapp, self.input_hist)
2112 2113 # End dbg
2113 2114
2114 2115 # All user code execution must happen with our context managers active
2115 2116 with nested(self.builtin_trap, self.display_trap):
2116 2117
2117 2118 # Single-block input should behave like an interactive prompt
2118 2119 if len(blocks) == 1:
2119 2120 # since we return here, we need to update the execution count
2120 2121 out = self.run_one_block(blocks[0])
2121 2122 self.execution_count += 1
2122 2123 return out
2123 2124
2124 2125 # In multi-block input, if the last block is a simple (one-two
2125 2126 # lines) expression, run it in single mode so it produces output.
2126 2127 # Otherwise just feed the whole thing to run_code. This seems like
2127 2128 # a reasonable usability design.
2128 2129 last = blocks[-1]
2129 2130 last_nlines = len(last.splitlines())
2130 2131
2131 2132 # Note: below, whenever we call run_code, we must sync history
2132 2133 # ourselves, because run_code is NOT meant to manage history at all.
2133 2134 if last_nlines < 2:
2134 2135 # Here we consider the cell split between 'body' and 'last',
2135 2136 # store all history and execute 'body', and if successful, then
2136 2137 # proceed to execute 'last'.
2137 2138
2138 2139 # Get the main body to run as a cell
2139 2140 ipy_body = ''.join(blocks[:-1])
2140 2141 retcode = self.run_source(ipy_body, symbol='exec',
2141 2142 post_execute=False)
2142 2143 if retcode==0:
2143 2144 # And the last expression via runlines so it produces output
2144 2145 self.run_one_block(last)
2145 2146 else:
2146 2147 # Run the whole cell as one entity, storing both raw and
2147 2148 # processed input in history
2148 2149 self.run_source(ipy_cell, symbol='exec')
2149 2150
2150 2151 # Each cell is a *single* input, regardless of how many lines it has
2151 2152 self.execution_count += 1
2152 2153
2153 2154 def run_one_block(self, block):
2154 2155 """Run a single interactive block.
2155 2156
2156 2157 If the block is single-line, dynamic transformations are applied to it
2157 2158 (like automagics, autocall and alias recognition).
2158 2159 """
2159 2160 if len(block.splitlines()) <= 1:
2160 2161 out = self.run_single_line(block)
2161 2162 else:
2162 2163 out = self.run_code(block)
2163 2164 return out
2164 2165
2165 2166 def run_single_line(self, line):
2166 2167 """Run a single-line interactive statement.
2167 2168
2168 2169 This assumes the input has been transformed to IPython syntax by
2169 2170 applying all static transformations (those with an explicit prefix like
2170 2171 % or !), but it will further try to apply the dynamic ones.
2171 2172
2172 2173 It does not update history.
2173 2174 """
2174 2175 tline = self.prefilter_manager.prefilter_line(line)
2175 2176 return self.run_source(tline)
2176 2177
2177 2178 # PENDING REMOVAL: this method is slated for deletion, once our new
2178 2179 # input logic has been 100% moved to frontends and is stable.
2179 2180 def runlines(self, lines, clean=False):
2180 2181 """Run a string of one or more lines of source.
2181 2182
2182 2183 This method is capable of running a string containing multiple source
2183 2184 lines, as if they had been entered at the IPython prompt. Since it
2184 2185 exposes IPython's processing machinery, the given strings can contain
2185 2186 magic calls (%magic), special shell access (!cmd), etc.
2186 2187 """
2187 2188
2188 2189 if isinstance(lines, (list, tuple)):
2189 2190 lines = '\n'.join(lines)
2190 2191
2191 2192 if clean:
2192 2193 lines = self._cleanup_ipy_script(lines)
2193 2194
2194 2195 # We must start with a clean buffer, in case this is run from an
2195 2196 # interactive IPython session (via a magic, for example).
2196 2197 self.reset_buffer()
2197 2198 lines = lines.splitlines()
2198 2199
2199 2200 # Since we will prefilter all lines, store the user's raw input too
2200 2201 # before we apply any transformations
2201 2202 self.buffer_raw[:] = [ l+'\n' for l in lines]
2202 2203
2203 2204 more = False
2204 2205 prefilter_lines = self.prefilter_manager.prefilter_lines
2205 2206 with nested(self.builtin_trap, self.display_trap):
2206 2207 for line in lines:
2207 2208 # skip blank lines so we don't mess up the prompt counter, but
2208 2209 # do NOT skip even a blank line if we are in a code block (more
2209 2210 # is true)
2210 2211
2211 2212 if line or more:
2212 2213 more = self.push_line(prefilter_lines(line, more))
2213 2214 # IPython's run_source returns None if there was an error
2214 2215 # compiling the code. This allows us to stop processing
2215 2216 # right away, so the user gets the error message at the
2216 2217 # right place.
2217 2218 if more is None:
2218 2219 break
2219 2220 # final newline in case the input didn't have it, so that the code
2220 2221 # actually does get executed
2221 2222 if more:
2222 2223 self.push_line('\n')
2223 2224
2224 2225 def run_source(self, source, filename=None,
2225 2226 symbol='single', post_execute=True):
2226 2227 """Compile and run some source in the interpreter.
2227 2228
2228 2229 Arguments are as for compile_command().
2229 2230
2230 2231 One several things can happen:
2231 2232
2232 2233 1) The input is incorrect; compile_command() raised an
2233 2234 exception (SyntaxError or OverflowError). A syntax traceback
2234 2235 will be printed by calling the showsyntaxerror() method.
2235 2236
2236 2237 2) The input is incomplete, and more input is required;
2237 2238 compile_command() returned None. Nothing happens.
2238 2239
2239 2240 3) The input is complete; compile_command() returned a code
2240 2241 object. The code is executed by calling self.run_code() (which
2241 2242 also handles run-time exceptions, except for SystemExit).
2242 2243
2243 2244 The return value is:
2244 2245
2245 2246 - True in case 2
2246 2247
2247 2248 - False in the other cases, unless an exception is raised, where
2248 2249 None is returned instead. This can be used by external callers to
2249 2250 know whether to continue feeding input or not.
2250 2251
2251 2252 The return value can be used to decide whether to use sys.ps1 or
2252 2253 sys.ps2 to prompt the next line."""
2253 2254
2254 2255 # We need to ensure that the source is unicode from here on.
2255 2256 if type(source)==str:
2256 2257 usource = source.decode(self.stdin_encoding)
2257 2258 else:
2258 2259 usource = source
2259 2260
2260 2261 if 0: # dbg
2261 2262 print 'Source:', repr(source) # dbg
2262 2263 print 'USource:', repr(usource) # dbg
2263 2264 print 'type:', type(source) # dbg
2264 2265 print 'encoding', self.stdin_encoding # dbg
2265 2266
2266 2267 try:
2267 2268 code = self.compile(usource, symbol, self.execution_count)
2268 2269 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2269 2270 # Case 1
2270 2271 self.showsyntaxerror(filename)
2271 2272 return None
2272 2273
2273 2274 if code is None:
2274 2275 # Case 2
2275 2276 return True
2276 2277
2277 2278 # Case 3
2278 2279 # We store the code object so that threaded shells and
2279 2280 # custom exception handlers can access all this info if needed.
2280 2281 # The source corresponding to this can be obtained from the
2281 2282 # buffer attribute as '\n'.join(self.buffer).
2282 2283 self.code_to_run = code
2283 2284 # now actually execute the code object
2284 2285 if self.run_code(code, post_execute) == 0:
2285 2286 return False
2286 2287 else:
2287 2288 return None
2288 2289
2289 2290 # For backwards compatibility
2290 2291 runsource = run_source
2291 2292
2292 2293 def run_code(self, code_obj, post_execute=True):
2293 2294 """Execute a code object.
2294 2295
2295 2296 When an exception occurs, self.showtraceback() is called to display a
2296 2297 traceback.
2297 2298
2298 2299 Return value: a flag indicating whether the code to be run completed
2299 2300 successfully:
2300 2301
2301 2302 - 0: successful execution.
2302 2303 - 1: an error occurred.
2303 2304 """
2304 2305
2305 2306 # Set our own excepthook in case the user code tries to call it
2306 2307 # directly, so that the IPython crash handler doesn't get triggered
2307 2308 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2308 2309
2309 2310 # we save the original sys.excepthook in the instance, in case config
2310 2311 # code (such as magics) needs access to it.
2311 2312 self.sys_excepthook = old_excepthook
2312 2313 outflag = 1 # happens in more places, so it's easier as default
2313 2314 try:
2314 2315 try:
2315 2316 self.hooks.pre_run_code_hook()
2316 2317 #rprint('Running code') # dbg
2317 2318 exec code_obj in self.user_global_ns, self.user_ns
2318 2319 finally:
2319 2320 # Reset our crash handler in place
2320 2321 sys.excepthook = old_excepthook
2321 2322 except SystemExit:
2322 2323 self.reset_buffer()
2323 2324 self.showtraceback(exception_only=True)
2324 2325 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2325 2326 except self.custom_exceptions:
2326 2327 etype,value,tb = sys.exc_info()
2327 2328 self.CustomTB(etype,value,tb)
2328 2329 except:
2329 2330 self.showtraceback()
2330 2331 else:
2331 2332 outflag = 0
2332 2333 if softspace(sys.stdout, 0):
2333 2334 print
2334 2335
2335 2336 # Execute any registered post-execution functions. Here, any errors
2336 2337 # are reported only minimally and just on the terminal, because the
2337 2338 # main exception channel may be occupied with a user traceback.
2338 2339 # FIXME: we need to think this mechanism a little more carefully.
2339 2340 if post_execute:
2340 2341 for func in self._post_execute:
2341 2342 try:
2342 2343 func()
2343 2344 except:
2344 2345 head = '[ ERROR ] Evaluating post_execute function: %s' % \
2345 2346 func
2346 2347 print >> io.Term.cout, head
2347 2348 print >> io.Term.cout, self._simple_error()
2348 2349 print >> io.Term.cout, 'Removing from post_execute'
2349 2350 self._post_execute.remove(func)
2350 2351
2351 2352 # Flush out code object which has been run (and source)
2352 2353 self.code_to_run = None
2353 2354 return outflag
2354 2355
2355 2356 # For backwards compatibility
2356 2357 runcode = run_code
2357 2358
2358 2359 # PENDING REMOVAL: this method is slated for deletion, once our new
2359 2360 # input logic has been 100% moved to frontends and is stable.
2360 2361 def push_line(self, line):
2361 2362 """Push a line to the interpreter.
2362 2363
2363 2364 The line should not have a trailing newline; it may have
2364 2365 internal newlines. The line is appended to a buffer and the
2365 2366 interpreter's run_source() method is called with the
2366 2367 concatenated contents of the buffer as source. If this
2367 2368 indicates that the command was executed or invalid, the buffer
2368 2369 is reset; otherwise, the command is incomplete, and the buffer
2369 2370 is left as it was after the line was appended. The return
2370 2371 value is 1 if more input is required, 0 if the line was dealt
2371 2372 with in some way (this is the same as run_source()).
2372 2373 """
2373 2374
2374 2375 # autoindent management should be done here, and not in the
2375 2376 # interactive loop, since that one is only seen by keyboard input. We
2376 2377 # need this done correctly even for code run via runlines (which uses
2377 2378 # push).
2378 2379
2379 2380 #print 'push line: <%s>' % line # dbg
2380 2381 self.buffer.append(line)
2381 2382 full_source = '\n'.join(self.buffer)
2382 2383 more = self.run_source(full_source, self.filename)
2383 2384 if not more:
2384 2385 self.history_manager.store_inputs('\n'.join(self.buffer_raw),
2385 2386 full_source)
2386 2387 self.reset_buffer()
2387 2388 self.execution_count += 1
2388 2389 return more
2389 2390
2390 2391 def reset_buffer(self):
2391 2392 """Reset the input buffer."""
2392 2393 self.buffer[:] = []
2393 2394 self.buffer_raw[:] = []
2394 2395 self.input_splitter.reset()
2395 2396
2396 2397 # For backwards compatibility
2397 2398 resetbuffer = reset_buffer
2398 2399
2399 2400 def _is_secondary_block_start(self, s):
2400 2401 if not s.endswith(':'):
2401 2402 return False
2402 2403 if (s.startswith('elif') or
2403 2404 s.startswith('else') or
2404 2405 s.startswith('except') or
2405 2406 s.startswith('finally')):
2406 2407 return True
2407 2408
2408 2409 def _cleanup_ipy_script(self, script):
2409 2410 """Make a script safe for self.runlines()
2410 2411
2411 2412 Currently, IPython is lines based, with blocks being detected by
2412 2413 empty lines. This is a problem for block based scripts that may
2413 2414 not have empty lines after blocks. This script adds those empty
2414 2415 lines to make scripts safe for running in the current line based
2415 2416 IPython.
2416 2417 """
2417 2418 res = []
2418 2419 lines = script.splitlines()
2419 2420 level = 0
2420 2421
2421 2422 for l in lines:
2422 2423 lstripped = l.lstrip()
2423 2424 stripped = l.strip()
2424 2425 if not stripped:
2425 2426 continue
2426 2427 newlevel = len(l) - len(lstripped)
2427 2428 if level > 0 and newlevel == 0 and \
2428 2429 not self._is_secondary_block_start(stripped):
2429 2430 # add empty line
2430 2431 res.append('')
2431 2432 res.append(l)
2432 2433 level = newlevel
2433 2434
2434 2435 return '\n'.join(res) + '\n'
2435 2436
2436 2437 #-------------------------------------------------------------------------
2437 2438 # Things related to GUI support and pylab
2438 2439 #-------------------------------------------------------------------------
2439 2440
2440 2441 def enable_pylab(self, gui=None):
2441 2442 raise NotImplementedError('Implement enable_pylab in a subclass')
2442 2443
2443 2444 #-------------------------------------------------------------------------
2444 2445 # Utilities
2445 2446 #-------------------------------------------------------------------------
2446 2447
2447 2448 def var_expand(self,cmd,depth=0):
2448 2449 """Expand python variables in a string.
2449 2450
2450 2451 The depth argument indicates how many frames above the caller should
2451 2452 be walked to look for the local namespace where to expand variables.
2452 2453
2453 2454 The global namespace for expansion is always the user's interactive
2454 2455 namespace.
2455 2456 """
2456 2457
2457 2458 return str(ItplNS(cmd,
2458 2459 self.user_ns, # globals
2459 2460 # Skip our own frame in searching for locals:
2460 2461 sys._getframe(depth+1).f_locals # locals
2461 2462 ))
2462 2463
2463 2464 def mktempfile(self, data=None, prefix='ipython_edit_'):
2464 2465 """Make a new tempfile and return its filename.
2465 2466
2466 2467 This makes a call to tempfile.mktemp, but it registers the created
2467 2468 filename internally so ipython cleans it up at exit time.
2468 2469
2469 2470 Optional inputs:
2470 2471
2471 2472 - data(None): if data is given, it gets written out to the temp file
2472 2473 immediately, and the file is closed again."""
2473 2474
2474 2475 filename = tempfile.mktemp('.py', prefix)
2475 2476 self.tempfiles.append(filename)
2476 2477
2477 2478 if data:
2478 2479 tmp_file = open(filename,'w')
2479 2480 tmp_file.write(data)
2480 2481 tmp_file.close()
2481 2482 return filename
2482 2483
2483 2484 # TODO: This should be removed when Term is refactored.
2484 2485 def write(self,data):
2485 2486 """Write a string to the default output"""
2486 2487 io.Term.cout.write(data)
2487 2488
2488 2489 # TODO: This should be removed when Term is refactored.
2489 2490 def write_err(self,data):
2490 2491 """Write a string to the default error output"""
2491 2492 io.Term.cerr.write(data)
2492 2493
2493 2494 def ask_yes_no(self,prompt,default=True):
2494 2495 if self.quiet:
2495 2496 return True
2496 2497 return ask_yes_no(prompt,default)
2497 2498
2498 2499 def show_usage(self):
2499 2500 """Show a usage message"""
2500 2501 page.page(IPython.core.usage.interactive_usage)
2501 2502
2502 2503 #-------------------------------------------------------------------------
2503 2504 # Things related to IPython exiting
2504 2505 #-------------------------------------------------------------------------
2505 2506 def atexit_operations(self):
2506 2507 """This will be executed at the time of exit.
2507 2508
2508 2509 Cleanup operations and saving of persistent data that is done
2509 2510 unconditionally by IPython should be performed here.
2510 2511
2511 2512 For things that may depend on startup flags or platform specifics (such
2512 2513 as having readline or not), register a separate atexit function in the
2513 2514 code that has the appropriate information, rather than trying to
2514 2515 clutter
2515 2516 """
2516 2517 # Cleanup all tempfiles left around
2517 2518 for tfile in self.tempfiles:
2518 2519 try:
2519 2520 os.unlink(tfile)
2520 2521 except OSError:
2521 2522 pass
2522 2523
2523 2524 # Clear all user namespaces to release all references cleanly.
2524 2525 self.reset()
2525 2526
2526 2527 # Run user hooks
2527 2528 self.hooks.shutdown_hook()
2528 2529
2529 2530 def cleanup(self):
2530 2531 self.restore_sys_module_state()
2531 2532
2532 2533
2533 2534 class InteractiveShellABC(object):
2534 2535 """An abstract base class for InteractiveShell."""
2535 2536 __metaclass__ = abc.ABCMeta
2536 2537
2537 2538 InteractiveShellABC.register(InteractiveShell)
@@ -1,690 +1,700
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 pretty
4 4 ~~
5 5
6 6 Python advanced pretty printer. This pretty printer is intended to
7 7 replace the old `pprint` python module which does not allow developers
8 8 to provide their own pretty print callbacks.
9 9
10 10 This module is based on ruby's `prettyprint.rb` library by `Tanaka Akira`.
11 11
12 12
13 13 Example Usage
14 14 =============
15 15
16 16 To directly print the representation of an object use `pprint`::
17 17
18 18 from pretty import pprint
19 19 pprint(complex_object)
20 20
21 21 To get a string of the output use `pretty`::
22 22
23 23 from pretty import pretty
24 24 string = pretty(complex_object)
25 25
26 26
27 27 Extending
28 28 =========
29 29
30 30 The pretty library allows developers to add pretty printing rules for their
31 31 own objects. This process is straightforward. All you have to do is to
32 32 add a `__pretty__` method to your object and call the methods on the
33 33 pretty printer passed::
34 34
35 35 class MyObject(object):
36 36
37 37 def __pretty__(self, p, cycle):
38 38 ...
39 39
40 40 Depending on the python version you want to support you have two
41 41 possibilities. The following list shows the python 2.5 version and the
42 42 compatibility one.
43 43
44 44
45 45 Here the example implementation of a `__pretty__` method for a list
46 46 subclass for python 2.5 and higher (python 2.5 requires the with statement
47 47 __future__ import)::
48 48
49 49 class MyList(list):
50 50
51 51 def __pretty__(self, p, cycle):
52 52 if cycle:
53 53 p.text('MyList(...)')
54 54 else:
55 55 with p.group(8, 'MyList([', '])'):
56 56 for idx, item in enumerate(self):
57 57 if idx:
58 58 p.text(',')
59 59 p.breakable()
60 60 p.pretty(item)
61 61
62 62 The `cycle` parameter is `True` if pretty detected a cycle. You *have* to
63 63 react to that or the result is an infinite loop. `p.text()` just adds
64 64 non breaking text to the output, `p.breakable()` either adds a whitespace
65 65 or breaks here. If you pass it an argument it's used instead of the
66 66 default space. `p.pretty` prettyprints another object using the pretty print
67 67 method.
68 68
69 69 The first parameter to the `group` function specifies the extra indentation
70 70 of the next line. In this example the next item will either be not
71 71 breaked (if the items are short enough) or aligned with the right edge of
72 72 the opening bracked of `MyList`.
73 73
74 74 If you want to support python 2.4 and lower you can use this code::
75 75
76 76 class MyList(list):
77 77
78 78 def __pretty__(self, p, cycle):
79 79 if cycle:
80 80 p.text('MyList(...)')
81 81 else:
82 82 p.begin_group(8, 'MyList([')
83 83 for idx, item in enumerate(self):
84 84 if idx:
85 85 p.text(',')
86 86 p.breakable()
87 87 p.pretty(item)
88 88 p.end_group(8, '])')
89 89
90 90 If you just want to indent something you can use the group function
91 91 without open / close parameters. Under python 2.5 you can also use this
92 92 code::
93 93
94 94 with p.indent(2):
95 95 ...
96 96
97 97 Or under python2.4 you might want to modify ``p.indentation`` by hand but
98 98 this is rather ugly.
99 99
100 100 :copyright: 2007 by Armin Ronacher.
101 101 Portions (c) 2009 by Robert Kern.
102 102 :license: BSD License.
103 103 """
104 104 from __future__ import with_statement
105 105 from contextlib import contextmanager
106 106 import sys
107 107 import types
108 108 import re
109 109 import datetime
110 110 from StringIO import StringIO
111 111 from collections import deque
112 112
113 113
114 114 __all__ = ['pretty', 'pprint', 'PrettyPrinter', 'RepresentationPrinter',
115 115 'for_type', 'for_type_by_name']
116 116
117 117
118 118 _re_pattern_type = type(re.compile(''))
119 119
120 120
121 121 def pretty(obj, verbose=False, max_width=79, newline='\n'):
122 122 """
123 123 Pretty print the object's representation.
124 124 """
125 125 stream = StringIO()
126 126 printer = RepresentationPrinter(stream, verbose, max_width, newline)
127 127 printer.pretty(obj)
128 128 printer.flush()
129 129 return stream.getvalue()
130 130
131 131
132 132 def pprint(obj, verbose=False, max_width=79, newline='\n'):
133 133 """
134 134 Like `pretty` but print to stdout.
135 135 """
136 136 printer = RepresentationPrinter(sys.stdout, verbose, max_width, newline)
137 137 printer.pretty(obj)
138 138 printer.flush()
139 139 sys.stdout.write(newline)
140 140 sys.stdout.flush()
141 141
142 142 class _PrettyPrinterBase(object):
143 143
144 144 @contextmanager
145 145 def indent(self, indent):
146 146 """with statement support for indenting/dedenting."""
147 147 self.indentation += indent
148 148 try:
149 149 yield
150 150 finally:
151 151 self.indentation -= indent
152 152
153 153 @contextmanager
154 154 def group(self, indent=0, open='', close=''):
155 155 """like begin_group / end_group but for the with statement."""
156 156 self.begin_group(indent, open)
157 157 try:
158 158 with self.indent(indent):
159 159 yield
160 160 finally:
161 161 self.end_group(indent, close)
162 162
163 163 class PrettyPrinter(_PrettyPrinterBase):
164 164 """
165 165 Baseclass for the `RepresentationPrinter` prettyprinter that is used to
166 166 generate pretty reprs of objects. Contrary to the `RepresentationPrinter`
167 167 this printer knows nothing about the default pprinters or the `__pretty__`
168 168 callback method.
169 169 """
170 170
171 171 def __init__(self, output, max_width=79, newline='\n'):
172 172 self.output = output
173 173 self.max_width = max_width
174 174 self.newline = newline
175 175 self.output_width = 0
176 176 self.buffer_width = 0
177 177 self.buffer = deque()
178 178
179 179 root_group = Group(0)
180 180 self.group_stack = [root_group]
181 181 self.group_queue = GroupQueue(root_group)
182 182 self.indentation = 0
183 183
184 184 def _break_outer_groups(self):
185 185 while self.max_width < self.output_width + self.buffer_width:
186 186 group = self.group_queue.deq()
187 187 if not group:
188 188 return
189 189 while group.breakables:
190 190 x = self.buffer.popleft()
191 191 self.output_width = x.output(self.output, self.output_width)
192 192 self.buffer_width -= x.width
193 193 while self.buffer and isinstance(self.buffer[0], Text):
194 194 x = self.buffer.popleft()
195 195 self.output_width = x.output(self.output, self.output_width)
196 196 self.buffer_width -= x.width
197 197
198 198 def text(self, obj):
199 199 """Add literal text to the output."""
200 200 width = len(obj)
201 201 if self.buffer:
202 202 text = self.buffer[-1]
203 203 if not isinstance(text, Text):
204 204 text = Text()
205 205 self.buffer.append(text)
206 206 text.add(obj, width)
207 207 self.buffer_width += width
208 208 self._break_outer_groups()
209 209 else:
210 210 self.output.write(obj)
211 211 self.output_width += width
212 212
213 213 def breakable(self, sep=' '):
214 214 """
215 215 Add a breakable separator to the output. This does not mean that it
216 216 will automatically break here. If no breaking on this position takes
217 217 place the `sep` is inserted which default to one space.
218 218 """
219 219 width = len(sep)
220 220 group = self.group_stack[-1]
221 221 if group.want_break:
222 222 self.flush()
223 223 self.output.write(self.newline)
224 224 self.output.write(' ' * self.indentation)
225 225 self.output_width = self.indentation
226 226 self.buffer_width = 0
227 227 else:
228 228 self.buffer.append(Breakable(sep, width, self))
229 229 self.buffer_width += width
230 230 self._break_outer_groups()
231 231
232 232
233 233 def begin_group(self, indent=0, open=''):
234 234 """
235 235 Begin a group. If you want support for python < 2.5 which doesn't has
236 236 the with statement this is the preferred way:
237 237
238 238 p.begin_group(1, '{')
239 239 ...
240 240 p.end_group(1, '}')
241 241
242 242 The python 2.5 expression would be this:
243 243
244 244 with p.group(1, '{', '}'):
245 245 ...
246 246
247 247 The first parameter specifies the indentation for the next line (usually
248 248 the width of the opening text), the second the opening text. All
249 249 parameters are optional.
250 250 """
251 251 if open:
252 252 self.text(open)
253 253 group = Group(self.group_stack[-1].depth + 1)
254 254 self.group_stack.append(group)
255 255 self.group_queue.enq(group)
256 256 self.indentation += indent
257 257
258 258 def end_group(self, dedent=0, close=''):
259 259 """End a group. See `begin_group` for more details."""
260 260 self.indentation -= dedent
261 261 group = self.group_stack.pop()
262 262 if not group.breakables:
263 263 self.group_queue.remove(group)
264 264 if close:
265 265 self.text(close)
266 266
267 267 def flush(self):
268 268 """Flush data that is left in the buffer."""
269 269 for data in self.buffer:
270 270 self.output_width += data.output(self.output, self.output_width)
271 271 self.buffer.clear()
272 272 self.buffer_width = 0
273 273
274 274
275 275 def _get_mro(obj_class):
276 276 """ Get a reasonable method resolution order of a class and its superclasses
277 277 for both old-style and new-style classes.
278 278 """
279 279 if not hasattr(obj_class, '__mro__'):
280 280 # Old-style class. Mix in object to make a fake new-style class.
281 281 try:
282 282 obj_class = type(obj_class.__name__, (obj_class, object), {})
283 283 except TypeError:
284 284 # Old-style extension type that does not descend from object.
285 285 # FIXME: try to construct a more thorough MRO.
286 286 mro = [obj_class]
287 287 else:
288 288 mro = obj_class.__mro__[1:-1]
289 289 else:
290 290 mro = obj_class.__mro__
291 291 return mro
292 292
293 293
294 294 class RepresentationPrinter(PrettyPrinter):
295 295 """
296 296 Special pretty printer that has a `pretty` method that calls the pretty
297 297 printer for a python object.
298 298
299 299 This class stores processing data on `self` so you must *never* use
300 300 this class in a threaded environment. Always lock it or reinstanciate
301 301 it.
302 302
303 303 Instances also have a verbose flag callbacks can access to control their
304 304 output. For example the default instance repr prints all attributes and
305 305 methods that are not prefixed by an underscore if the printer is in
306 306 verbose mode.
307 307 """
308 308
309 def __init__(self, output, verbose=False, max_width=79, newline='\n'):
309 def __init__(self, output, verbose=False, max_width=79, newline='\n',
310 singleton_pprinters=None, type_pprinters=None, deferred_pprinters=None):
311
310 312 PrettyPrinter.__init__(self, output, max_width, newline)
311 313 self.verbose = verbose
312 314 self.stack = []
315 if singleton_pprinters is None:
316 singleton_pprinters = _singleton_pprinters.copy()
317 self.singleton_pprinters = singleton_pprinters
318 if type_pprinters is None:
319 type_pprinters = _type_pprinters.copy()
320 self.type_pprinters = type_pprinters
321 if deferred_pprinters is None:
322 deferred_pprinters = _deferred_type_pprinters.copy()
323 self.deferred_pprinters = deferred_pprinters
313 324
314 325 def pretty(self, obj):
315 326 """Pretty print the given object."""
316 327 obj_id = id(obj)
317 328 cycle = obj_id in self.stack
318 329 self.stack.append(obj_id)
319 330 self.begin_group()
320 331 try:
321 332 obj_class = getattr(obj, '__class__', None) or type(obj)
322 333 if hasattr(obj_class, '__pretty__'):
323 334 return obj_class.__pretty__(obj, self, cycle)
324 335 try:
325 printer = _singleton_pprinters[obj_id]
336 printer = self.singleton_pprinters[obj_id]
326 337 except (TypeError, KeyError):
327 338 pass
328 339 else:
329 340 return printer(obj, self, cycle)
330 341 for cls in _get_mro(obj_class):
331 if cls in _type_pprinters:
332 return _type_pprinters[cls](obj, self, cycle)
342 if cls in self.type_pprinters:
343 return self.type_pprinters[cls](obj, self, cycle)
333 344 else:
334 345 printer = self._in_deferred_types(cls)
335 346 if printer is not None:
336 347 return printer(obj, self, cycle)
337 348 return _default_pprint(obj, self, cycle)
338 349 finally:
339 350 self.end_group()
340 351 self.stack.pop()
341 352
342 353 def _in_deferred_types(self, cls):
343 354 """
344 355 Check if the given class is specified in the deferred type registry.
345 356
346 357 Returns the printer from the registry if it exists, and None if the
347 358 class is not in the registry. Successful matches will be moved to the
348 359 regular type registry for future use.
349 360 """
350 361 mod = getattr(cls, '__module__', None)
351 362 name = getattr(cls, '__name__', None)
352 363 key = (mod, name)
353 364 printer = None
354 if key in _deferred_type_pprinters:
365 if key in self.deferred_pprinters:
355 366 # Move the printer over to the regular registry.
356 printer = _deferred_type_pprinters.pop(key)
357 _type_pprinters[cls] = printer
367 printer = self.deferred_pprinters.pop(key)
368 self.type_pprinters[cls] = printer
358 369 return printer
359 370
360 371
361
362 372 class Printable(object):
363 373
364 374 def output(self, stream, output_width):
365 375 return output_width
366 376
367 377
368 378 class Text(Printable):
369 379
370 380 def __init__(self):
371 381 self.objs = []
372 382 self.width = 0
373 383
374 384 def output(self, stream, output_width):
375 385 for obj in self.objs:
376 386 stream.write(obj)
377 387 return output_width + self.width
378 388
379 389 def add(self, obj, width):
380 390 self.objs.append(obj)
381 391 self.width += width
382 392
383 393
384 394 class Breakable(Printable):
385 395
386 396 def __init__(self, seq, width, pretty):
387 397 self.obj = seq
388 398 self.width = width
389 399 self.pretty = pretty
390 400 self.indentation = pretty.indentation
391 401 self.group = pretty.group_stack[-1]
392 402 self.group.breakables.append(self)
393 403
394 404 def output(self, stream, output_width):
395 405 self.group.breakables.popleft()
396 406 if self.group.want_break:
397 407 stream.write(self.pretty.newline)
398 408 stream.write(' ' * self.indentation)
399 409 return self.indentation
400 410 if not self.group.breakables:
401 411 self.pretty.group_queue.remove(self.group)
402 412 stream.write(self.obj)
403 413 return output_width + self.width
404 414
405 415
406 416 class Group(Printable):
407 417
408 418 def __init__(self, depth):
409 419 self.depth = depth
410 420 self.breakables = deque()
411 421 self.want_break = False
412 422
413 423
414 424 class GroupQueue(object):
415 425
416 426 def __init__(self, *groups):
417 427 self.queue = []
418 428 for group in groups:
419 429 self.enq(group)
420 430
421 431 def enq(self, group):
422 432 depth = group.depth
423 433 while depth > len(self.queue) - 1:
424 434 self.queue.append([])
425 435 self.queue[depth].append(group)
426 436
427 437 def deq(self):
428 438 for stack in self.queue:
429 439 for idx, group in enumerate(reversed(stack)):
430 440 if group.breakables:
431 441 del stack[idx]
432 442 group.want_break = True
433 443 return group
434 444 for group in stack:
435 445 group.want_break = True
436 446 del stack[:]
437 447
438 448 def remove(self, group):
439 449 try:
440 450 self.queue[group.depth].remove(group)
441 451 except ValueError:
442 452 pass
443 453
444 454
445 455 _baseclass_reprs = (object.__repr__, types.InstanceType.__repr__)
446 456
447 457
448 458 def _default_pprint(obj, p, cycle):
449 459 """
450 460 The default print function. Used if an object does not provide one and
451 461 it's none of the builtin objects.
452 462 """
453 463 klass = getattr(obj, '__class__', None) or type(obj)
454 464 if getattr(klass, '__repr__', None) not in _baseclass_reprs:
455 465 # A user-provided repr.
456 466 p.text(repr(obj))
457 467 return
458 468 p.begin_group(1, '<')
459 469 p.pretty(klass)
460 470 p.text(' at 0x%x' % id(obj))
461 471 if cycle:
462 472 p.text(' ...')
463 473 elif p.verbose:
464 474 first = True
465 475 for key in dir(obj):
466 476 if not key.startswith('_'):
467 477 try:
468 478 value = getattr(obj, key)
469 479 except AttributeError:
470 480 continue
471 481 if isinstance(value, types.MethodType):
472 482 continue
473 483 if not first:
474 484 p.text(',')
475 485 p.breakable()
476 486 p.text(key)
477 487 p.text('=')
478 488 step = len(key) + 1
479 489 p.indentation += step
480 490 p.pretty(value)
481 491 p.indentation -= step
482 492 first = False
483 493 p.end_group(1, '>')
484 494
485 495
486 496 def _seq_pprinter_factory(start, end):
487 497 """
488 498 Factory that returns a pprint function useful for sequences. Used by
489 499 the default pprint for tuples, dicts, lists, sets and frozensets.
490 500 """
491 501 def inner(obj, p, cycle):
492 502 if cycle:
493 503 return p.text(start + '...' + end)
494 504 step = len(start)
495 505 p.begin_group(step, start)
496 506 for idx, x in enumerate(obj):
497 507 if idx:
498 508 p.text(',')
499 509 p.breakable()
500 510 p.pretty(x)
501 511 if len(obj) == 1 and type(obj) is tuple:
502 512 # Special case for 1-item tuples.
503 513 p.text(',')
504 514 p.end_group(step, end)
505 515 return inner
506 516
507 517
508 518 def _dict_pprinter_factory(start, end):
509 519 """
510 520 Factory that returns a pprint function used by the default pprint of
511 521 dicts and dict proxies.
512 522 """
513 523 def inner(obj, p, cycle):
514 524 if cycle:
515 525 return p.text('{...}')
516 526 p.begin_group(1, start)
517 527 keys = obj.keys()
518 528 try:
519 529 keys.sort()
520 530 except Exception, e:
521 531 # Sometimes the keys don't sort.
522 532 pass
523 533 for idx, key in enumerate(keys):
524 534 if idx:
525 535 p.text(',')
526 536 p.breakable()
527 537 p.pretty(key)
528 538 p.text(': ')
529 539 p.pretty(obj[key])
530 540 p.end_group(1, end)
531 541 return inner
532 542
533 543
534 544 def _super_pprint(obj, p, cycle):
535 545 """The pprint for the super type."""
536 546 p.begin_group(8, '<super: ')
537 547 p.pretty(obj.__self_class__)
538 548 p.text(',')
539 549 p.breakable()
540 550 p.pretty(obj.__self__)
541 551 p.end_group(8, '>')
542 552
543 553
544 554 def _re_pattern_pprint(obj, p, cycle):
545 555 """The pprint function for regular expression patterns."""
546 556 p.text('re.compile(')
547 557 pattern = repr(obj.pattern)
548 558 if pattern[:1] in 'uU':
549 559 pattern = pattern[1:]
550 560 prefix = 'ur'
551 561 else:
552 562 prefix = 'r'
553 563 pattern = prefix + pattern.replace('\\\\', '\\')
554 564 p.text(pattern)
555 565 if obj.flags:
556 566 p.text(',')
557 567 p.breakable()
558 568 done_one = False
559 569 for flag in ('TEMPLATE', 'IGNORECASE', 'LOCALE', 'MULTILINE', 'DOTALL',
560 570 'UNICODE', 'VERBOSE', 'DEBUG'):
561 571 if obj.flags & getattr(re, flag):
562 572 if done_one:
563 573 p.text('|')
564 574 p.text('re.' + flag)
565 575 done_one = True
566 576 p.text(')')
567 577
568 578
569 579 def _type_pprint(obj, p, cycle):
570 580 """The pprint for classes and types."""
571 581 if obj.__module__ in ('__builtin__', 'exceptions'):
572 582 name = obj.__name__
573 583 else:
574 584 name = obj.__module__ + '.' + obj.__name__
575 585 p.text(name)
576 586
577 587
578 588 def _repr_pprint(obj, p, cycle):
579 589 """A pprint that just redirects to the normal repr function."""
580 590 p.text(repr(obj))
581 591
582 592
583 593 def _function_pprint(obj, p, cycle):
584 594 """Base pprint for all functions and builtin functions."""
585 595 if obj.__module__ in ('__builtin__', 'exceptions') or not obj.__module__:
586 596 name = obj.__name__
587 597 else:
588 598 name = obj.__module__ + '.' + obj.__name__
589 599 p.text('<function %s>' % name)
590 600
591 601
592 602 def _exception_pprint(obj, p, cycle):
593 603 """Base pprint for all exceptions."""
594 604 if obj.__class__.__module__ == 'exceptions':
595 605 name = obj.__class__.__name__
596 606 else:
597 607 name = '%s.%s' % (
598 608 obj.__class__.__module__,
599 609 obj.__class__.__name__
600 610 )
601 611 step = len(name) + 1
602 612 p.begin_group(step, '(')
603 613 for idx, arg in enumerate(getattr(obj, 'args', ())):
604 614 if idx:
605 615 p.text(',')
606 616 p.breakable()
607 617 p.pretty(arg)
608 618 p.end_group(step, ')')
609 619
610 620
611 621 #: the exception base
612 622 try:
613 623 _exception_base = BaseException
614 624 except NameError:
615 625 _exception_base = Exception
616 626
617 627
618 628 #: printers for builtin types
619 629 _type_pprinters = {
620 630 int: _repr_pprint,
621 631 long: _repr_pprint,
622 632 float: _repr_pprint,
623 633 str: _repr_pprint,
624 634 unicode: _repr_pprint,
625 635 tuple: _seq_pprinter_factory('(', ')'),
626 636 list: _seq_pprinter_factory('[', ']'),
627 637 dict: _dict_pprinter_factory('{', '}'),
628 638 types.DictProxyType: _dict_pprinter_factory('<dictproxy {', '}>'),
629 639 set: _seq_pprinter_factory('set([', '])'),
630 640 frozenset: _seq_pprinter_factory('frozenset([', '])'),
631 641 super: _super_pprint,
632 642 _re_pattern_type: _re_pattern_pprint,
633 643 type: _type_pprint,
634 644 types.ClassType: _type_pprint,
635 645 types.FunctionType: _function_pprint,
636 646 types.BuiltinFunctionType: _function_pprint,
637 647 types.SliceType: _repr_pprint,
638 648 types.MethodType: _repr_pprint,
639 649 xrange: _repr_pprint,
640 650 datetime.datetime: _repr_pprint,
641 651 datetime.timedelta: _repr_pprint,
642 652 _exception_base: _exception_pprint
643 653 }
644 654
645 655 #: printers for types specified by name
646 656 _deferred_type_pprinters = {
647 657 }
648 658
649 659 def for_type(typ, func):
650 660 """
651 661 Add a pretty printer for a given type.
652 662 """
653 663 oldfunc = _type_pprinters.get(typ, None)
654 664 if func is not None:
655 665 # To support easy restoration of old pprinters, we need to ignore Nones.
656 666 _type_pprinters[typ] = func
657 667 return oldfunc
658 668
659 669 def for_type_by_name(type_module, type_name, func):
660 670 """
661 671 Add a pretty printer for a type specified by the module and name of a type
662 672 rather than the type object itself.
663 673 """
664 674 key = (type_module, type_name)
665 675 oldfunc = _deferred_type_pprinters.get(key, None)
666 676 if func is not None:
667 677 # To support easy restoration of old pprinters, we need to ignore Nones.
668 678 _deferred_type_pprinters[key] = func
669 679 return oldfunc
670 680
671 681
672 682 #: printers for the default singletons
673 683 _singleton_pprinters = dict.fromkeys(map(id, [None, True, False, Ellipsis,
674 684 NotImplemented]), _repr_pprint)
675 685
676 686
677 687 if __name__ == '__main__':
678 688 from random import randrange
679 689 class Foo(object):
680 690 def __init__(self):
681 691 self.foo = 1
682 692 self.bar = re.compile(r'\s+')
683 693 self.blub = dict.fromkeys(range(30), randrange(1, 40))
684 694 self.hehe = 23424.234234
685 695 self.list = ["blub", "blah", self]
686 696
687 697 def get_foo(self):
688 698 print "foo"
689 699
690 700 pprint(Foo(), verbose=True)
@@ -1,87 +1,106
1 1 """ Defines miscellaneous Qt-related helper classes and functions.
2 2 """
3 3
4 # Standard library imports.
5 import inspect
6
4 7 # System library imports.
5 8 from PyQt4 import QtCore, QtGui
6 9
7 10 # IPython imports.
8 from IPython.utils.traitlets import HasTraits
11 from IPython.utils.traitlets import HasTraits, TraitType
9 12
10 13 #-----------------------------------------------------------------------------
11 14 # Metaclasses
12 15 #-----------------------------------------------------------------------------
13 16
14 17 MetaHasTraits = type(HasTraits)
15 18 MetaQObject = type(QtCore.QObject)
16 19
17 # You can switch the order of the parents here and it doesn't seem to matter.
18 20 class MetaQObjectHasTraits(MetaQObject, MetaHasTraits):
19 21 """ A metaclass that inherits from the metaclasses of HasTraits and QObject.
20 22
21 23 Using this metaclass allows a class to inherit from both HasTraits and
22 24 QObject. Using SuperQObject instead of QObject is highly recommended. See
23 25 QtKernelManager for an example.
24 26 """
25 pass
27 def __new__(mcls, name, bases, classdict):
28 # FIXME: this duplicates the code from MetaHasTraits.
29 # I don't think a super() call will help me here.
30 for k,v in classdict.iteritems():
31 if isinstance(v, TraitType):
32 v.name = k
33 elif inspect.isclass(v):
34 if issubclass(v, TraitType):
35 vinst = v()
36 vinst.name = k
37 classdict[k] = vinst
38 cls = MetaQObject.__new__(mcls, name, bases, classdict)
39 return cls
40
41 def __init__(mcls, name, bases, classdict):
42 # Note: super() did not work, so we explicitly call these.
43 MetaQObject.__init__(mcls, name, bases, classdict)
44 MetaHasTraits.__init__(mcls, name, bases, classdict)
26 45
27 46 #-----------------------------------------------------------------------------
28 47 # Classes
29 48 #-----------------------------------------------------------------------------
30 49
31 50 class SuperQObject(QtCore.QObject):
32 51 """ Permits the use of super() in class hierarchies that contain QObject.
33 52
34 53 Unlike QObject, SuperQObject does not accept a QObject parent. If it did,
35 54 super could not be emulated properly (all other classes in the heierarchy
36 55 would have to accept the parent argument--they don't, of course, because
37 56 they don't inherit QObject.)
38 57
39 58 This class is primarily useful for attaching signals to existing non-Qt
40 59 classes. See QtKernelManager for an example.
41 60 """
42 61
43 62 def __new__(cls, *args, **kw):
44 63 # We initialize QObject as early as possible. Without this, Qt complains
45 64 # if SuperQObject is not the first class in the super class list.
46 65 inst = QtCore.QObject.__new__(cls)
47 66 QtCore.QObject.__init__(inst)
48 67 return inst
49 68
50 69 def __init__(self, *args, **kw):
51 70 # Emulate super by calling the next method in the MRO, if there is one.
52 71 mro = self.__class__.mro()
53 72 for qt_class in QtCore.QObject.mro():
54 73 mro.remove(qt_class)
55 74 next_index = mro.index(SuperQObject) + 1
56 75 if next_index < len(mro):
57 76 mro[next_index].__init__(self, *args, **kw)
58 77
59 78 #-----------------------------------------------------------------------------
60 79 # Functions
61 80 #-----------------------------------------------------------------------------
62 81
63 82 def get_font(family, fallback=None):
64 83 """Return a font of the requested family, using fallback as alternative.
65 84
66 85 If a fallback is provided, it is used in case the requested family isn't
67 86 found. If no fallback is given, no alternative is chosen and Qt's internal
68 87 algorithms may automatically choose a fallback font.
69 88
70 89 Parameters
71 90 ----------
72 91 family : str
73 92 A font name.
74 93 fallback : str
75 94 A font name.
76 95
77 96 Returns
78 97 -------
79 98 font : QFont object
80 99 """
81 100 font = QtGui.QFont(family)
82 101 # Check whether we got what we wanted using QFontInfo, since exactMatch()
83 102 # is overly strict and returns false in too many cases.
84 103 font_info = QtGui.QFontInfo(font)
85 104 if fallback is not None and font_info.family() != family:
86 105 font = QtGui.QFont(fallback)
87 106 return font
@@ -1,706 +1,729
1 1 #!/usr/bin/env python
2 2 # encoding: utf-8
3 3 """
4 4 Tests for IPython.utils.traitlets.
5 5
6 6 Authors:
7 7
8 8 * Brian Granger
9 9 * Enthought, Inc. Some of the code in this file comes from enthought.traits
10 10 and is licensed under the BSD license. Also, many of the ideas also come
11 11 from enthought.traits even though our implementation is very different.
12 12 """
13 13
14 14 #-----------------------------------------------------------------------------
15 15 # Copyright (C) 2008-2009 The IPython Development Team
16 16 #
17 17 # Distributed under the terms of the BSD License. The full license is in
18 18 # the file COPYING, distributed as part of this software.
19 19 #-----------------------------------------------------------------------------
20 20
21 21 #-----------------------------------------------------------------------------
22 22 # Imports
23 23 #-----------------------------------------------------------------------------
24 24
25 25 from unittest import TestCase
26 26
27 27 from IPython.utils.traitlets import (
28 28 HasTraits, MetaHasTraits, TraitType, Any,
29 29 Int, Long, Float, Complex, Str, Unicode, TraitError,
30 30 Undefined, Type, This, Instance, TCPAddress
31 31 )
32 32
33 33
34 34 #-----------------------------------------------------------------------------
35 35 # Helper classes for testing
36 36 #-----------------------------------------------------------------------------
37 37
38 38
39 39 class HasTraitsStub(HasTraits):
40 40
41 41 def _notify_trait(self, name, old, new):
42 42 self._notify_name = name
43 43 self._notify_old = old
44 44 self._notify_new = new
45 45
46 46
47 47 #-----------------------------------------------------------------------------
48 48 # Test classes
49 49 #-----------------------------------------------------------------------------
50 50
51 51
52 52 class TestTraitType(TestCase):
53 53
54 54 def test_get_undefined(self):
55 55 class A(HasTraits):
56 56 a = TraitType
57 57 a = A()
58 58 self.assertEquals(a.a, Undefined)
59 59
60 60 def test_set(self):
61 61 class A(HasTraitsStub):
62 62 a = TraitType
63 63
64 64 a = A()
65 65 a.a = 10
66 66 self.assertEquals(a.a, 10)
67 67 self.assertEquals(a._notify_name, 'a')
68 68 self.assertEquals(a._notify_old, Undefined)
69 69 self.assertEquals(a._notify_new, 10)
70 70
71 71 def test_validate(self):
72 72 class MyTT(TraitType):
73 73 def validate(self, inst, value):
74 74 return -1
75 75 class A(HasTraitsStub):
76 76 tt = MyTT
77 77
78 78 a = A()
79 79 a.tt = 10
80 80 self.assertEquals(a.tt, -1)
81 81
82 82 def test_default_validate(self):
83 83 class MyIntTT(TraitType):
84 84 def validate(self, obj, value):
85 85 if isinstance(value, int):
86 86 return value
87 87 self.error(obj, value)
88 88 class A(HasTraits):
89 89 tt = MyIntTT(10)
90 90 a = A()
91 91 self.assertEquals(a.tt, 10)
92 92
93 93 # Defaults are validated when the HasTraits is instantiated
94 94 class B(HasTraits):
95 95 tt = MyIntTT('bad default')
96 96 self.assertRaises(TraitError, B)
97 97
98 98 def test_is_valid_for(self):
99 99 class MyTT(TraitType):
100 100 def is_valid_for(self, value):
101 101 return True
102 102 class A(HasTraits):
103 103 tt = MyTT
104 104
105 105 a = A()
106 106 a.tt = 10
107 107 self.assertEquals(a.tt, 10)
108 108
109 109 def test_value_for(self):
110 110 class MyTT(TraitType):
111 111 def value_for(self, value):
112 112 return 20
113 113 class A(HasTraits):
114 114 tt = MyTT
115 115
116 116 a = A()
117 117 a.tt = 10
118 118 self.assertEquals(a.tt, 20)
119 119
120 120 def test_info(self):
121 121 class A(HasTraits):
122 122 tt = TraitType
123 123 a = A()
124 124 self.assertEquals(A.tt.info(), 'any value')
125 125
126 126 def test_error(self):
127 127 class A(HasTraits):
128 128 tt = TraitType
129 129 a = A()
130 130 self.assertRaises(TraitError, A.tt.error, a, 10)
131 131
132 def test_dynamic_initializer(self):
133 class A(HasTraits):
134 x = Int(10)
135 def _x_default(self):
136 return 11
137 class B(A):
138 x = Int(20)
139 class C(A):
140 def _x_default(self):
141 return 21
142
143 a = A()
144 self.assertEquals(a._trait_values, {})
145 self.assertEquals(a.x, 11)
146 self.assertEquals(a._trait_values, {'x': 11})
147 b = B()
148 self.assertEquals(b._trait_values, {'x': 20})
149 self.assertEquals(b.x, 20)
150 c = C()
151 self.assertEquals(c._trait_values, {})
152 self.assertEquals(c.x, 21)
153 self.assertEquals(c._trait_values, {'x': 21})
154
132 155
133 156 class TestHasTraitsMeta(TestCase):
134 157
135 158 def test_metaclass(self):
136 159 self.assertEquals(type(HasTraits), MetaHasTraits)
137 160
138 161 class A(HasTraits):
139 162 a = Int
140 163
141 164 a = A()
142 165 self.assertEquals(type(a.__class__), MetaHasTraits)
143 166 self.assertEquals(a.a,0)
144 167 a.a = 10
145 168 self.assertEquals(a.a,10)
146 169
147 170 class B(HasTraits):
148 171 b = Int()
149 172
150 173 b = B()
151 174 self.assertEquals(b.b,0)
152 175 b.b = 10
153 176 self.assertEquals(b.b,10)
154 177
155 178 class C(HasTraits):
156 179 c = Int(30)
157 180
158 181 c = C()
159 182 self.assertEquals(c.c,30)
160 183 c.c = 10
161 184 self.assertEquals(c.c,10)
162 185
163 186 def test_this_class(self):
164 187 class A(HasTraits):
165 188 t = This()
166 189 tt = This()
167 190 class B(A):
168 191 tt = This()
169 192 ttt = This()
170 193 self.assertEquals(A.t.this_class, A)
171 194 self.assertEquals(B.t.this_class, A)
172 195 self.assertEquals(B.tt.this_class, B)
173 196 self.assertEquals(B.ttt.this_class, B)
174 197
175 198 class TestHasTraitsNotify(TestCase):
176 199
177 200 def setUp(self):
178 201 self._notify1 = []
179 202 self._notify2 = []
180 203
181 204 def notify1(self, name, old, new):
182 205 self._notify1.append((name, old, new))
183 206
184 207 def notify2(self, name, old, new):
185 208 self._notify2.append((name, old, new))
186 209
187 210 def test_notify_all(self):
188 211
189 212 class A(HasTraits):
190 213 a = Int
191 214 b = Float
192 215
193 216 a = A()
194 217 a.on_trait_change(self.notify1)
195 218 a.a = 0
196 219 self.assertEquals(len(self._notify1),0)
197 220 a.b = 0.0
198 221 self.assertEquals(len(self._notify1),0)
199 222 a.a = 10
200 223 self.assert_(('a',0,10) in self._notify1)
201 224 a.b = 10.0
202 225 self.assert_(('b',0.0,10.0) in self._notify1)
203 226 self.assertRaises(TraitError,setattr,a,'a','bad string')
204 227 self.assertRaises(TraitError,setattr,a,'b','bad string')
205 228 self._notify1 = []
206 229 a.on_trait_change(self.notify1,remove=True)
207 230 a.a = 20
208 231 a.b = 20.0
209 232 self.assertEquals(len(self._notify1),0)
210 233
211 234 def test_notify_one(self):
212 235
213 236 class A(HasTraits):
214 237 a = Int
215 238 b = Float
216 239
217 240 a = A()
218 241 a.on_trait_change(self.notify1, 'a')
219 242 a.a = 0
220 243 self.assertEquals(len(self._notify1),0)
221 244 a.a = 10
222 245 self.assert_(('a',0,10) in self._notify1)
223 246 self.assertRaises(TraitError,setattr,a,'a','bad string')
224 247
225 248 def test_subclass(self):
226 249
227 250 class A(HasTraits):
228 251 a = Int
229 252
230 253 class B(A):
231 254 b = Float
232 255
233 256 b = B()
234 257 self.assertEquals(b.a,0)
235 258 self.assertEquals(b.b,0.0)
236 259 b.a = 100
237 260 b.b = 100.0
238 261 self.assertEquals(b.a,100)
239 262 self.assertEquals(b.b,100.0)
240 263
241 264 def test_notify_subclass(self):
242 265
243 266 class A(HasTraits):
244 267 a = Int
245 268
246 269 class B(A):
247 270 b = Float
248 271
249 272 b = B()
250 273 b.on_trait_change(self.notify1, 'a')
251 274 b.on_trait_change(self.notify2, 'b')
252 275 b.a = 0
253 276 b.b = 0.0
254 277 self.assertEquals(len(self._notify1),0)
255 278 self.assertEquals(len(self._notify2),0)
256 279 b.a = 10
257 280 b.b = 10.0
258 281 self.assert_(('a',0,10) in self._notify1)
259 282 self.assert_(('b',0.0,10.0) in self._notify2)
260 283
261 284 def test_static_notify(self):
262 285
263 286 class A(HasTraits):
264 287 a = Int
265 288 _notify1 = []
266 289 def _a_changed(self, name, old, new):
267 290 self._notify1.append((name, old, new))
268 291
269 292 a = A()
270 293 a.a = 0
271 294 # This is broken!!!
272 295 self.assertEquals(len(a._notify1),0)
273 296 a.a = 10
274 297 self.assert_(('a',0,10) in a._notify1)
275 298
276 299 class B(A):
277 300 b = Float
278 301 _notify2 = []
279 302 def _b_changed(self, name, old, new):
280 303 self._notify2.append((name, old, new))
281 304
282 305 b = B()
283 306 b.a = 10
284 307 b.b = 10.0
285 308 self.assert_(('a',0,10) in b._notify1)
286 309 self.assert_(('b',0.0,10.0) in b._notify2)
287 310
288 311 def test_notify_args(self):
289 312
290 313 def callback0():
291 314 self.cb = ()
292 315 def callback1(name):
293 316 self.cb = (name,)
294 317 def callback2(name, new):
295 318 self.cb = (name, new)
296 319 def callback3(name, old, new):
297 320 self.cb = (name, old, new)
298 321
299 322 class A(HasTraits):
300 323 a = Int
301 324
302 325 a = A()
303 326 a.on_trait_change(callback0, 'a')
304 327 a.a = 10
305 328 self.assertEquals(self.cb,())
306 329 a.on_trait_change(callback0, 'a', remove=True)
307 330
308 331 a.on_trait_change(callback1, 'a')
309 332 a.a = 100
310 333 self.assertEquals(self.cb,('a',))
311 334 a.on_trait_change(callback1, 'a', remove=True)
312 335
313 336 a.on_trait_change(callback2, 'a')
314 337 a.a = 1000
315 338 self.assertEquals(self.cb,('a',1000))
316 339 a.on_trait_change(callback2, 'a', remove=True)
317 340
318 341 a.on_trait_change(callback3, 'a')
319 342 a.a = 10000
320 343 self.assertEquals(self.cb,('a',1000,10000))
321 344 a.on_trait_change(callback3, 'a', remove=True)
322 345
323 346 self.assertEquals(len(a._trait_notifiers['a']),0)
324 347
325 348
326 349 class TestHasTraits(TestCase):
327 350
328 351 def test_trait_names(self):
329 352 class A(HasTraits):
330 353 i = Int
331 354 f = Float
332 355 a = A()
333 356 self.assertEquals(a.trait_names(),['i','f'])
334 357
335 358 def test_trait_metadata(self):
336 359 class A(HasTraits):
337 360 i = Int(config_key='MY_VALUE')
338 361 a = A()
339 362 self.assertEquals(a.trait_metadata('i','config_key'), 'MY_VALUE')
340 363
341 364 def test_traits(self):
342 365 class A(HasTraits):
343 366 i = Int
344 367 f = Float
345 368 a = A()
346 369 self.assertEquals(a.traits(), dict(i=A.i, f=A.f))
347 370
348 371 def test_traits_metadata(self):
349 372 class A(HasTraits):
350 373 i = Int(config_key='VALUE1', other_thing='VALUE2')
351 374 f = Float(config_key='VALUE3', other_thing='VALUE2')
352 375 j = Int(0)
353 376 a = A()
354 377 self.assertEquals(a.traits(), dict(i=A.i, f=A.f, j=A.j))
355 378 traits = a.traits(config_key='VALUE1', other_thing='VALUE2')
356 379 self.assertEquals(traits, dict(i=A.i))
357 380
358 381 # This passes, but it shouldn't because I am replicating a bug in
359 382 # traits.
360 383 traits = a.traits(config_key=lambda v: True)
361 384 self.assertEquals(traits, dict(i=A.i, f=A.f, j=A.j))
362 385
363 386 def test_init(self):
364 387 class A(HasTraits):
365 388 i = Int()
366 389 x = Float()
367 390 a = A(i=1, x=10.0)
368 391 self.assertEquals(a.i, 1)
369 392 self.assertEquals(a.x, 10.0)
370 393
371 394 #-----------------------------------------------------------------------------
372 395 # Tests for specific trait types
373 396 #-----------------------------------------------------------------------------
374 397
375 398
376 399 class TestType(TestCase):
377 400
378 401 def test_default(self):
379 402
380 403 class B(object): pass
381 404 class A(HasTraits):
382 405 klass = Type
383 406
384 407 a = A()
385 408 self.assertEquals(a.klass, None)
386 409
387 410 a.klass = B
388 411 self.assertEquals(a.klass, B)
389 412 self.assertRaises(TraitError, setattr, a, 'klass', 10)
390 413
391 414 def test_value(self):
392 415
393 416 class B(object): pass
394 417 class C(object): pass
395 418 class A(HasTraits):
396 419 klass = Type(B)
397 420
398 421 a = A()
399 422 self.assertEquals(a.klass, B)
400 423 self.assertRaises(TraitError, setattr, a, 'klass', C)
401 424 self.assertRaises(TraitError, setattr, a, 'klass', object)
402 425 a.klass = B
403 426
404 427 def test_allow_none(self):
405 428
406 429 class B(object): pass
407 430 class C(B): pass
408 431 class A(HasTraits):
409 432 klass = Type(B, allow_none=False)
410 433
411 434 a = A()
412 435 self.assertEquals(a.klass, B)
413 436 self.assertRaises(TraitError, setattr, a, 'klass', None)
414 437 a.klass = C
415 438 self.assertEquals(a.klass, C)
416 439
417 440 def test_validate_klass(self):
418 441
419 442 class A(HasTraits):
420 443 klass = Type('no strings allowed')
421 444
422 445 self.assertRaises(ImportError, A)
423 446
424 447 class A(HasTraits):
425 448 klass = Type('rub.adub.Duck')
426 449
427 450 self.assertRaises(ImportError, A)
428 451
429 452 def test_validate_default(self):
430 453
431 454 class B(object): pass
432 455 class A(HasTraits):
433 456 klass = Type('bad default', B)
434 457
435 458 self.assertRaises(ImportError, A)
436 459
437 460 class C(HasTraits):
438 461 klass = Type(None, B, allow_none=False)
439 462
440 463 self.assertRaises(TraitError, C)
441 464
442 465 def test_str_klass(self):
443 466
444 467 class A(HasTraits):
445 468 klass = Type('IPython.utils.ipstruct.Struct')
446 469
447 470 from IPython.utils.ipstruct import Struct
448 471 a = A()
449 472 a.klass = Struct
450 473 self.assertEquals(a.klass, Struct)
451 474
452 475 self.assertRaises(TraitError, setattr, a, 'klass', 10)
453 476
454 477 class TestInstance(TestCase):
455 478
456 479 def test_basic(self):
457 480 class Foo(object): pass
458 481 class Bar(Foo): pass
459 482 class Bah(object): pass
460 483
461 484 class A(HasTraits):
462 485 inst = Instance(Foo)
463 486
464 487 a = A()
465 488 self.assert_(a.inst is None)
466 489 a.inst = Foo()
467 490 self.assert_(isinstance(a.inst, Foo))
468 491 a.inst = Bar()
469 492 self.assert_(isinstance(a.inst, Foo))
470 493 self.assertRaises(TraitError, setattr, a, 'inst', Foo)
471 494 self.assertRaises(TraitError, setattr, a, 'inst', Bar)
472 495 self.assertRaises(TraitError, setattr, a, 'inst', Bah())
473 496
474 497 def test_unique_default_value(self):
475 498 class Foo(object): pass
476 499 class A(HasTraits):
477 500 inst = Instance(Foo,(),{})
478 501
479 502 a = A()
480 503 b = A()
481 504 self.assert_(a.inst is not b.inst)
482 505
483 506 def test_args_kw(self):
484 507 class Foo(object):
485 508 def __init__(self, c): self.c = c
486 509 class Bar(object): pass
487 510 class Bah(object):
488 511 def __init__(self, c, d):
489 512 self.c = c; self.d = d
490 513
491 514 class A(HasTraits):
492 515 inst = Instance(Foo, (10,))
493 516 a = A()
494 517 self.assertEquals(a.inst.c, 10)
495 518
496 519 class B(HasTraits):
497 520 inst = Instance(Bah, args=(10,), kw=dict(d=20))
498 521 b = B()
499 522 self.assertEquals(b.inst.c, 10)
500 523 self.assertEquals(b.inst.d, 20)
501 524
502 525 class C(HasTraits):
503 526 inst = Instance(Foo)
504 527 c = C()
505 528 self.assert_(c.inst is None)
506 529
507 530 def test_bad_default(self):
508 531 class Foo(object): pass
509 532
510 533 class A(HasTraits):
511 534 inst = Instance(Foo, allow_none=False)
512 535
513 536 self.assertRaises(TraitError, A)
514 537
515 538 def test_instance(self):
516 539 class Foo(object): pass
517 540
518 541 def inner():
519 542 class A(HasTraits):
520 543 inst = Instance(Foo())
521 544
522 545 self.assertRaises(TraitError, inner)
523 546
524 547
525 548 class TestThis(TestCase):
526 549
527 550 def test_this_class(self):
528 551 class Foo(HasTraits):
529 552 this = This
530 553
531 554 f = Foo()
532 555 self.assertEquals(f.this, None)
533 556 g = Foo()
534 557 f.this = g
535 558 self.assertEquals(f.this, g)
536 559 self.assertRaises(TraitError, setattr, f, 'this', 10)
537 560
538 561 def test_this_inst(self):
539 562 class Foo(HasTraits):
540 563 this = This()
541 564
542 565 f = Foo()
543 566 f.this = Foo()
544 567 self.assert_(isinstance(f.this, Foo))
545 568
546 569 def test_subclass(self):
547 570 class Foo(HasTraits):
548 571 t = This()
549 572 class Bar(Foo):
550 573 pass
551 574 f = Foo()
552 575 b = Bar()
553 576 f.t = b
554 577 b.t = f
555 578 self.assertEquals(f.t, b)
556 579 self.assertEquals(b.t, f)
557 580
558 581 def test_subclass_override(self):
559 582 class Foo(HasTraits):
560 583 t = This()
561 584 class Bar(Foo):
562 585 t = This()
563 586 f = Foo()
564 587 b = Bar()
565 588 f.t = b
566 589 self.assertEquals(f.t, b)
567 590 self.assertRaises(TraitError, setattr, b, 't', f)
568 591
569 592 class TraitTestBase(TestCase):
570 593 """A best testing class for basic trait types."""
571 594
572 595 def assign(self, value):
573 596 self.obj.value = value
574 597
575 598 def coerce(self, value):
576 599 return value
577 600
578 601 def test_good_values(self):
579 602 if hasattr(self, '_good_values'):
580 603 for value in self._good_values:
581 604 self.assign(value)
582 605 self.assertEquals(self.obj.value, self.coerce(value))
583 606
584 607 def test_bad_values(self):
585 608 if hasattr(self, '_bad_values'):
586 609 for value in self._bad_values:
587 610 self.assertRaises(TraitError, self.assign, value)
588 611
589 612 def test_default_value(self):
590 613 if hasattr(self, '_default_value'):
591 614 self.assertEquals(self._default_value, self.obj.value)
592 615
593 616
594 617 class AnyTrait(HasTraits):
595 618
596 619 value = Any
597 620
598 621 class AnyTraitTest(TraitTestBase):
599 622
600 623 obj = AnyTrait()
601 624
602 625 _default_value = None
603 626 _good_values = [10.0, 'ten', u'ten', [10], {'ten': 10},(10,), None, 1j]
604 627 _bad_values = []
605 628
606 629
607 630 class IntTrait(HasTraits):
608 631
609 632 value = Int(99)
610 633
611 634 class TestInt(TraitTestBase):
612 635
613 636 obj = IntTrait()
614 637 _default_value = 99
615 638 _good_values = [10, -10]
616 639 _bad_values = ['ten', u'ten', [10], {'ten': 10},(10,), None, 1j, 10L,
617 640 -10L, 10.1, -10.1, '10L', '-10L', '10.1', '-10.1', u'10L',
618 641 u'-10L', u'10.1', u'-10.1', '10', '-10', u'10', u'-10']
619 642
620 643
621 644 class LongTrait(HasTraits):
622 645
623 646 value = Long(99L)
624 647
625 648 class TestLong(TraitTestBase):
626 649
627 650 obj = LongTrait()
628 651
629 652 _default_value = 99L
630 653 _good_values = [10, -10, 10L, -10L]
631 654 _bad_values = ['ten', u'ten', [10], [10l], {'ten': 10},(10,),(10L,),
632 655 None, 1j, 10.1, -10.1, '10', '-10', '10L', '-10L', '10.1',
633 656 '-10.1', u'10', u'-10', u'10L', u'-10L', u'10.1',
634 657 u'-10.1']
635 658
636 659
637 660 class FloatTrait(HasTraits):
638 661
639 662 value = Float(99.0)
640 663
641 664 class TestFloat(TraitTestBase):
642 665
643 666 obj = FloatTrait()
644 667
645 668 _default_value = 99.0
646 669 _good_values = [10, -10, 10.1, -10.1]
647 670 _bad_values = [10L, -10L, 'ten', u'ten', [10], {'ten': 10},(10,), None,
648 671 1j, '10', '-10', '10L', '-10L', '10.1', '-10.1', u'10',
649 672 u'-10', u'10L', u'-10L', u'10.1', u'-10.1']
650 673
651 674
652 675 class ComplexTrait(HasTraits):
653 676
654 677 value = Complex(99.0-99.0j)
655 678
656 679 class TestComplex(TraitTestBase):
657 680
658 681 obj = ComplexTrait()
659 682
660 683 _default_value = 99.0-99.0j
661 684 _good_values = [10, -10, 10.1, -10.1, 10j, 10+10j, 10-10j,
662 685 10.1j, 10.1+10.1j, 10.1-10.1j]
663 686 _bad_values = [10L, -10L, u'10L', u'-10L', 'ten', [10], {'ten': 10},(10,), None]
664 687
665 688
666 689 class StringTrait(HasTraits):
667 690
668 691 value = Str('string')
669 692
670 693 class TestString(TraitTestBase):
671 694
672 695 obj = StringTrait()
673 696
674 697 _default_value = 'string'
675 698 _good_values = ['10', '-10', '10L',
676 699 '-10L', '10.1', '-10.1', 'string']
677 700 _bad_values = [10, -10, 10L, -10L, 10.1, -10.1, 1j, [10],
678 701 ['ten'],{'ten': 10},(10,), None, u'string']
679 702
680 703
681 704 class UnicodeTrait(HasTraits):
682 705
683 706 value = Unicode(u'unicode')
684 707
685 708 class TestUnicode(TraitTestBase):
686 709
687 710 obj = UnicodeTrait()
688 711
689 712 _default_value = u'unicode'
690 713 _good_values = ['10', '-10', '10L', '-10L', '10.1',
691 714 '-10.1', '', u'', 'string', u'string', ]
692 715 _bad_values = [10, -10, 10L, -10L, 10.1, -10.1, 1j,
693 716 [10], ['ten'], [u'ten'], {'ten': 10},(10,), None]
694 717
695 718
696 719 class TCPAddressTrait(HasTraits):
697 720
698 721 value = TCPAddress()
699 722
700 723 class TestTCPAddress(TraitTestBase):
701 724
702 725 obj = TCPAddressTrait()
703 726
704 727 _default_value = ('127.0.0.1',0)
705 728 _good_values = [('localhost',0),('192.168.0.1',1000),('www.google.com',80)]
706 729 _bad_values = [(0,0),('localhost',10.0),('localhost',-1)]
@@ -1,1050 +1,1079
1 1 #!/usr/bin/env python
2 2 # encoding: utf-8
3 3 """
4 4 A lightweight Traits like module.
5 5
6 6 This is designed to provide a lightweight, simple, pure Python version of
7 7 many of the capabilities of enthought.traits. This includes:
8 8
9 9 * Validation
10 10 * Type specification with defaults
11 11 * Static and dynamic notification
12 12 * Basic predefined types
13 13 * An API that is similar to enthought.traits
14 14
15 15 We don't support:
16 16
17 17 * Delegation
18 18 * Automatic GUI generation
19 19 * A full set of trait types. Most importantly, we don't provide container
20 20 traits (list, dict, tuple) that can trigger notifications if their
21 21 contents change.
22 22 * API compatibility with enthought.traits
23 23
24 24 There are also some important difference in our design:
25 25
26 26 * enthought.traits does not validate default values. We do.
27 27
28 28 We choose to create this module because we need these capabilities, but
29 29 we need them to be pure Python so they work in all Python implementations,
30 30 including Jython and IronPython.
31 31
32 32 Authors:
33 33
34 34 * Brian Granger
35 35 * Enthought, Inc. Some of the code in this file comes from enthought.traits
36 36 and is licensed under the BSD license. Also, many of the ideas also come
37 37 from enthought.traits even though our implementation is very different.
38 38 """
39 39
40 40 #-----------------------------------------------------------------------------
41 41 # Copyright (C) 2008-2009 The IPython Development Team
42 42 #
43 43 # Distributed under the terms of the BSD License. The full license is in
44 44 # the file COPYING, distributed as part of this software.
45 45 #-----------------------------------------------------------------------------
46 46
47 47 #-----------------------------------------------------------------------------
48 48 # Imports
49 49 #-----------------------------------------------------------------------------
50 50
51 51
52 52 import inspect
53 53 import sys
54 54 import types
55 55 from types import (
56 56 InstanceType, ClassType, FunctionType,
57 57 ListType, TupleType
58 58 )
59 59 from .importstring import import_item
60 60
61 61 ClassTypes = (ClassType, type)
62 62
63 63 SequenceTypes = (ListType, TupleType)
64 64
65 65 #-----------------------------------------------------------------------------
66 66 # Basic classes
67 67 #-----------------------------------------------------------------------------
68 68
69 69
70 70 class NoDefaultSpecified ( object ): pass
71 71 NoDefaultSpecified = NoDefaultSpecified()
72 72
73 73
74 74 class Undefined ( object ): pass
75 75 Undefined = Undefined()
76 76
77 77 class TraitError(Exception):
78 78 pass
79 79
80 80 #-----------------------------------------------------------------------------
81 81 # Utilities
82 82 #-----------------------------------------------------------------------------
83 83
84 84
85 85 def class_of ( object ):
86 86 """ Returns a string containing the class name of an object with the
87 87 correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image',
88 88 'a PlotValue').
89 89 """
90 90 if isinstance( object, basestring ):
91 91 return add_article( object )
92 92
93 93 return add_article( object.__class__.__name__ )
94 94
95 95
96 96 def add_article ( name ):
97 97 """ Returns a string containing the correct indefinite article ('a' or 'an')
98 98 prefixed to the specified string.
99 99 """
100 100 if name[:1].lower() in 'aeiou':
101 101 return 'an ' + name
102 102
103 103 return 'a ' + name
104 104
105 105
106 106 def repr_type(obj):
107 107 """ Return a string representation of a value and its type for readable
108 108 error messages.
109 109 """
110 110 the_type = type(obj)
111 111 if the_type is InstanceType:
112 112 # Old-style class.
113 113 the_type = obj.__class__
114 114 msg = '%r %r' % (obj, the_type)
115 115 return msg
116 116
117 117
118 118 def parse_notifier_name(name):
119 119 """Convert the name argument to a list of names.
120 120
121 121 Examples
122 122 --------
123 123
124 124 >>> parse_notifier_name('a')
125 125 ['a']
126 126 >>> parse_notifier_name(['a','b'])
127 127 ['a', 'b']
128 128 >>> parse_notifier_name(None)
129 129 ['anytrait']
130 130 """
131 131 if isinstance(name, str):
132 132 return [name]
133 133 elif name is None:
134 134 return ['anytrait']
135 135 elif isinstance(name, (list, tuple)):
136 136 for n in name:
137 137 assert isinstance(n, str), "names must be strings"
138 138 return name
139 139
140 140
141 141 class _SimpleTest:
142 142 def __init__ ( self, value ): self.value = value
143 143 def __call__ ( self, test ):
144 144 return test == self.value
145 145 def __repr__(self):
146 146 return "<SimpleTest(%r)" % self.value
147 147 def __str__(self):
148 148 return self.__repr__()
149 149
150 150
151 151 def getmembers(object, predicate=None):
152 152 """A safe version of inspect.getmembers that handles missing attributes.
153 153
154 154 This is useful when there are descriptor based attributes that for
155 155 some reason raise AttributeError even though they exist. This happens
156 156 in zope.inteface with the __provides__ attribute.
157 157 """
158 158 results = []
159 159 for key in dir(object):
160 160 try:
161 161 value = getattr(object, key)
162 162 except AttributeError:
163 163 pass
164 164 else:
165 165 if not predicate or predicate(value):
166 166 results.append((key, value))
167 167 results.sort()
168 168 return results
169 169
170 170
171 171 #-----------------------------------------------------------------------------
172 172 # Base TraitType for all traits
173 173 #-----------------------------------------------------------------------------
174 174
175 175
176 176 class TraitType(object):
177 177 """A base class for all trait descriptors.
178 178
179 179 Notes
180 180 -----
181 181 Our implementation of traits is based on Python's descriptor
182 182 prototol. This class is the base class for all such descriptors. The
183 183 only magic we use is a custom metaclass for the main :class:`HasTraits`
184 184 class that does the following:
185 185
186 186 1. Sets the :attr:`name` attribute of every :class:`TraitType`
187 187 instance in the class dict to the name of the attribute.
188 188 2. Sets the :attr:`this_class` attribute of every :class:`TraitType`
189 189 instance in the class dict to the *class* that declared the trait.
190 190 This is used by the :class:`This` trait to allow subclasses to
191 191 accept superclasses for :class:`This` values.
192 192 """
193 193
194 194
195 195 metadata = {}
196 196 default_value = Undefined
197 197 info_text = 'any value'
198 198
199 199 def __init__(self, default_value=NoDefaultSpecified, **metadata):
200 200 """Create a TraitType.
201 201 """
202 202 if default_value is not NoDefaultSpecified:
203 203 self.default_value = default_value
204 204
205 205 if len(metadata) > 0:
206 206 if len(self.metadata) > 0:
207 207 self._metadata = self.metadata.copy()
208 208 self._metadata.update(metadata)
209 209 else:
210 210 self._metadata = metadata
211 211 else:
212 212 self._metadata = self.metadata
213 213
214 214 self.init()
215 215
216 216 def init(self):
217 217 pass
218 218
219 219 def get_default_value(self):
220 220 """Create a new instance of the default value."""
221 221 return self.default_value
222 222
223 223 def instance_init(self, obj):
224 224 """This is called by :meth:`HasTraits.__new__` to finish init'ing.
225 225
226 226 Some stages of initialization must be delayed until the parent
227 227 :class:`HasTraits` instance has been created. This method is
228 228 called in :meth:`HasTraits.__new__` after the instance has been
229 229 created.
230 230
231 231 This method trigger the creation and validation of default values
232 232 and also things like the resolution of str given class names in
233 233 :class:`Type` and :class`Instance`.
234 234
235 235 Parameters
236 236 ----------
237 237 obj : :class:`HasTraits` instance
238 238 The parent :class:`HasTraits` instance that has just been
239 239 created.
240 240 """
241 241 self.set_default_value(obj)
242 242
243 243 def set_default_value(self, obj):
244 244 """Set the default value on a per instance basis.
245 245
246 246 This method is called by :meth:`instance_init` to create and
247 247 validate the default value. The creation and validation of
248 248 default values must be delayed until the parent :class:`HasTraits`
249 249 class has been instantiated.
250 250 """
251 dv = self.get_default_value()
252 newdv = self._validate(obj, dv)
253 obj._trait_values[self.name] = newdv
251 # Check for a deferred initializer defined in the same class as the
252 # trait declaration or above.
253 mro = type(obj).mro()
254 meth_name = '_%s_default' % self.name
255 for cls in mro[:mro.index(self.this_class)+1]:
256 if meth_name in cls.__dict__:
257 break
258 else:
259 # We didn't find one. Do static initialization.
260 dv = self.get_default_value()
261 newdv = self._validate(obj, dv)
262 obj._trait_values[self.name] = newdv
263 return
264 # Complete the dynamic initialization.
265 self.dynamic_initializer = cls.__dict__[meth_name]
254 266
255 267 def __get__(self, obj, cls=None):
256 268 """Get the value of the trait by self.name for the instance.
257 269
258 270 Default values are instantiated when :meth:`HasTraits.__new__`
259 271 is called. Thus by the time this method gets called either the
260 272 default value or a user defined value (they called :meth:`__set__`)
261 273 is in the :class:`HasTraits` instance.
262 274 """
263 275 if obj is None:
264 276 return self
265 277 else:
266 278 try:
267 279 value = obj._trait_values[self.name]
268 except:
280 except KeyError:
281 # Check for a dynamic initializer.
282 if hasattr(self, 'dynamic_initializer'):
283 value = self.dynamic_initializer(obj)
284 # FIXME: Do we really validate here?
285 value = self._validate(obj, value)
286 obj._trait_values[self.name] = value
287 return value
288 else:
289 raise TraitError('Unexpected error in TraitType: '
290 'both default value and dynamic initializer are '
291 'absent.')
292 except Exception:
269 293 # HasTraits should call set_default_value to populate
270 294 # this. So this should never be reached.
271 295 raise TraitError('Unexpected error in TraitType: '
272 296 'default value not set properly')
273 297 else:
274 298 return value
275 299
276 300 def __set__(self, obj, value):
277 301 new_value = self._validate(obj, value)
278 302 old_value = self.__get__(obj)
279 303 if old_value != new_value:
280 304 obj._trait_values[self.name] = new_value
281 305 obj._notify_trait(self.name, old_value, new_value)
282 306
283 307 def _validate(self, obj, value):
284 308 if hasattr(self, 'validate'):
285 309 return self.validate(obj, value)
286 310 elif hasattr(self, 'is_valid_for'):
287 311 valid = self.is_valid_for(value)
288 312 if valid:
289 313 return value
290 314 else:
291 315 raise TraitError('invalid value for type: %r' % value)
292 316 elif hasattr(self, 'value_for'):
293 317 return self.value_for(value)
294 318 else:
295 319 return value
296 320
321 def set_dynamic_initializer(self, method):
322 """ Set the dynamic initializer method, if any.
323 """
324 self.dynamic_initializer = method
325
297 326 def info(self):
298 327 return self.info_text
299 328
300 329 def error(self, obj, value):
301 330 if obj is not None:
302 331 e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
303 332 % (self.name, class_of(obj),
304 333 self.info(), repr_type(value))
305 334 else:
306 335 e = "The '%s' trait must be %s, but a value of %r was specified." \
307 336 % (self.name, self.info(), repr_type(value))
308 337 raise TraitError(e)
309 338
310 339 def get_metadata(self, key):
311 340 return getattr(self, '_metadata', {}).get(key, None)
312 341
313 342 def set_metadata(self, key, value):
314 343 getattr(self, '_metadata', {})[key] = value
315 344
316 345
317 346 #-----------------------------------------------------------------------------
318 347 # The HasTraits implementation
319 348 #-----------------------------------------------------------------------------
320 349
321 350
322 351 class MetaHasTraits(type):
323 352 """A metaclass for HasTraits.
324 353
325 354 This metaclass makes sure that any TraitType class attributes are
326 355 instantiated and sets their name attribute.
327 356 """
328 357
329 358 def __new__(mcls, name, bases, classdict):
330 359 """Create the HasTraits class.
331 360
332 361 This instantiates all TraitTypes in the class dict and sets their
333 362 :attr:`name` attribute.
334 363 """
335 364 # print "MetaHasTraitlets (mcls, name): ", mcls, name
336 365 # print "MetaHasTraitlets (bases): ", bases
337 366 # print "MetaHasTraitlets (classdict): ", classdict
338 367 for k,v in classdict.iteritems():
339 368 if isinstance(v, TraitType):
340 369 v.name = k
341 370 elif inspect.isclass(v):
342 371 if issubclass(v, TraitType):
343 372 vinst = v()
344 373 vinst.name = k
345 374 classdict[k] = vinst
346 375 return super(MetaHasTraits, mcls).__new__(mcls, name, bases, classdict)
347 376
348 377 def __init__(cls, name, bases, classdict):
349 378 """Finish initializing the HasTraits class.
350 379
351 380 This sets the :attr:`this_class` attribute of each TraitType in the
352 381 class dict to the newly created class ``cls``.
353 382 """
354 383 for k, v in classdict.iteritems():
355 384 if isinstance(v, TraitType):
356 385 v.this_class = cls
357 386 super(MetaHasTraits, cls).__init__(name, bases, classdict)
358 387
359 388 class HasTraits(object):
360 389
361 390 __metaclass__ = MetaHasTraits
362 391
363 392 def __new__(cls, **kw):
364 393 # This is needed because in Python 2.6 object.__new__ only accepts
365 394 # the cls argument.
366 395 new_meth = super(HasTraits, cls).__new__
367 396 if new_meth is object.__new__:
368 397 inst = new_meth(cls)
369 398 else:
370 399 inst = new_meth(cls, **kw)
371 400 inst._trait_values = {}
372 401 inst._trait_notifiers = {}
373 402 # Here we tell all the TraitType instances to set their default
374 403 # values on the instance.
375 404 for key in dir(cls):
376 405 # Some descriptors raise AttributeError like zope.interface's
377 406 # __provides__ attributes even though they exist. This causes
378 407 # AttributeErrors even though they are listed in dir(cls).
379 408 try:
380 409 value = getattr(cls, key)
381 410 except AttributeError:
382 411 pass
383 412 else:
384 413 if isinstance(value, TraitType):
385 414 value.instance_init(inst)
386 415
387 416 return inst
388 417
389 418 def __init__(self, **kw):
390 419 # Allow trait values to be set using keyword arguments.
391 420 # We need to use setattr for this to trigger validation and
392 421 # notifications.
393 422 for key, value in kw.iteritems():
394 423 setattr(self, key, value)
395 424
396 425 def _notify_trait(self, name, old_value, new_value):
397 426
398 427 # First dynamic ones
399 428 callables = self._trait_notifiers.get(name,[])
400 429 more_callables = self._trait_notifiers.get('anytrait',[])
401 430 callables.extend(more_callables)
402 431
403 432 # Now static ones
404 433 try:
405 434 cb = getattr(self, '_%s_changed' % name)
406 435 except:
407 436 pass
408 437 else:
409 438 callables.append(cb)
410 439
411 440 # Call them all now
412 441 for c in callables:
413 442 # Traits catches and logs errors here. I allow them to raise
414 443 if callable(c):
415 444 argspec = inspect.getargspec(c)
416 445 nargs = len(argspec[0])
417 446 # Bound methods have an additional 'self' argument
418 447 # I don't know how to treat unbound methods, but they
419 448 # can't really be used for callbacks.
420 449 if isinstance(c, types.MethodType):
421 450 offset = -1
422 451 else:
423 452 offset = 0
424 453 if nargs + offset == 0:
425 454 c()
426 455 elif nargs + offset == 1:
427 456 c(name)
428 457 elif nargs + offset == 2:
429 458 c(name, new_value)
430 459 elif nargs + offset == 3:
431 460 c(name, old_value, new_value)
432 461 else:
433 462 raise TraitError('a trait changed callback '
434 463 'must have 0-3 arguments.')
435 464 else:
436 465 raise TraitError('a trait changed callback '
437 466 'must be callable.')
438 467
439 468
440 469 def _add_notifiers(self, handler, name):
441 470 if not self._trait_notifiers.has_key(name):
442 471 nlist = []
443 472 self._trait_notifiers[name] = nlist
444 473 else:
445 474 nlist = self._trait_notifiers[name]
446 475 if handler not in nlist:
447 476 nlist.append(handler)
448 477
449 478 def _remove_notifiers(self, handler, name):
450 479 if self._trait_notifiers.has_key(name):
451 480 nlist = self._trait_notifiers[name]
452 481 try:
453 482 index = nlist.index(handler)
454 483 except ValueError:
455 484 pass
456 485 else:
457 486 del nlist[index]
458 487
459 488 def on_trait_change(self, handler, name=None, remove=False):
460 489 """Setup a handler to be called when a trait changes.
461 490
462 491 This is used to setup dynamic notifications of trait changes.
463 492
464 493 Static handlers can be created by creating methods on a HasTraits
465 494 subclass with the naming convention '_[traitname]_changed'. Thus,
466 495 to create static handler for the trait 'a', create the method
467 496 _a_changed(self, name, old, new) (fewer arguments can be used, see
468 497 below).
469 498
470 499 Parameters
471 500 ----------
472 501 handler : callable
473 502 A callable that is called when a trait changes. Its
474 503 signature can be handler(), handler(name), handler(name, new)
475 504 or handler(name, old, new).
476 505 name : list, str, None
477 506 If None, the handler will apply to all traits. If a list
478 507 of str, handler will apply to all names in the list. If a
479 508 str, the handler will apply just to that name.
480 509 remove : bool
481 510 If False (the default), then install the handler. If True
482 511 then unintall it.
483 512 """
484 513 if remove:
485 514 names = parse_notifier_name(name)
486 515 for n in names:
487 516 self._remove_notifiers(handler, n)
488 517 else:
489 518 names = parse_notifier_name(name)
490 519 for n in names:
491 520 self._add_notifiers(handler, n)
492 521
493 522 def trait_names(self, **metadata):
494 523 """Get a list of all the names of this classes traits."""
495 524 return self.traits(**metadata).keys()
496 525
497 526 def traits(self, **metadata):
498 527 """Get a list of all the traits of this class.
499 528
500 529 The TraitTypes returned don't know anything about the values
501 530 that the various HasTrait's instances are holding.
502 531
503 532 This follows the same algorithm as traits does and does not allow
504 533 for any simple way of specifying merely that a metadata name
505 534 exists, but has any value. This is because get_metadata returns
506 535 None if a metadata key doesn't exist.
507 536 """
508 537 traits = dict([memb for memb in getmembers(self.__class__) if \
509 538 isinstance(memb[1], TraitType)])
510 539
511 540 if len(metadata) == 0:
512 541 return traits
513 542
514 543 for meta_name, meta_eval in metadata.items():
515 544 if type(meta_eval) is not FunctionType:
516 545 metadata[meta_name] = _SimpleTest(meta_eval)
517 546
518 547 result = {}
519 548 for name, trait in traits.items():
520 549 for meta_name, meta_eval in metadata.items():
521 550 if not meta_eval(trait.get_metadata(meta_name)):
522 551 break
523 552 else:
524 553 result[name] = trait
525 554
526 555 return result
527 556
528 557 def trait_metadata(self, traitname, key):
529 558 """Get metadata values for trait by key."""
530 559 try:
531 560 trait = getattr(self.__class__, traitname)
532 561 except AttributeError:
533 562 raise TraitError("Class %s does not have a trait named %s" %
534 563 (self.__class__.__name__, traitname))
535 564 else:
536 565 return trait.get_metadata(key)
537 566
538 567 #-----------------------------------------------------------------------------
539 568 # Actual TraitTypes implementations/subclasses
540 569 #-----------------------------------------------------------------------------
541 570
542 571 #-----------------------------------------------------------------------------
543 572 # TraitTypes subclasses for handling classes and instances of classes
544 573 #-----------------------------------------------------------------------------
545 574
546 575
547 576 class ClassBasedTraitType(TraitType):
548 577 """A trait with error reporting for Type, Instance and This."""
549 578
550 579 def error(self, obj, value):
551 580 kind = type(value)
552 581 if kind is InstanceType:
553 582 msg = 'class %s' % value.__class__.__name__
554 583 else:
555 584 msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) )
556 585
557 586 super(ClassBasedTraitType, self).error(obj, msg)
558 587
559 588
560 589 class Type(ClassBasedTraitType):
561 590 """A trait whose value must be a subclass of a specified class."""
562 591
563 592 def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ):
564 593 """Construct a Type trait
565 594
566 595 A Type trait specifies that its values must be subclasses of
567 596 a particular class.
568 597
569 598 If only ``default_value`` is given, it is used for the ``klass`` as
570 599 well.
571 600
572 601 Parameters
573 602 ----------
574 603 default_value : class, str or None
575 604 The default value must be a subclass of klass. If an str,
576 605 the str must be a fully specified class name, like 'foo.bar.Bah'.
577 606 The string is resolved into real class, when the parent
578 607 :class:`HasTraits` class is instantiated.
579 608 klass : class, str, None
580 609 Values of this trait must be a subclass of klass. The klass
581 610 may be specified in a string like: 'foo.bar.MyClass'.
582 611 The string is resolved into real class, when the parent
583 612 :class:`HasTraits` class is instantiated.
584 613 allow_none : boolean
585 614 Indicates whether None is allowed as an assignable value. Even if
586 615 ``False``, the default value may be ``None``.
587 616 """
588 617 if default_value is None:
589 618 if klass is None:
590 619 klass = object
591 620 elif klass is None:
592 621 klass = default_value
593 622
594 623 if not (inspect.isclass(klass) or isinstance(klass, basestring)):
595 624 raise TraitError("A Type trait must specify a class.")
596 625
597 626 self.klass = klass
598 627 self._allow_none = allow_none
599 628
600 629 super(Type, self).__init__(default_value, **metadata)
601 630
602 631 def validate(self, obj, value):
603 632 """Validates that the value is a valid object instance."""
604 633 try:
605 634 if issubclass(value, self.klass):
606 635 return value
607 636 except:
608 637 if (value is None) and (self._allow_none):
609 638 return value
610 639
611 640 self.error(obj, value)
612 641
613 642 def info(self):
614 643 """ Returns a description of the trait."""
615 644 if isinstance(self.klass, basestring):
616 645 klass = self.klass
617 646 else:
618 647 klass = self.klass.__name__
619 648 result = 'a subclass of ' + klass
620 649 if self._allow_none:
621 650 return result + ' or None'
622 651 return result
623 652
624 653 def instance_init(self, obj):
625 654 self._resolve_classes()
626 655 super(Type, self).instance_init(obj)
627 656
628 657 def _resolve_classes(self):
629 658 if isinstance(self.klass, basestring):
630 659 self.klass = import_item(self.klass)
631 660 if isinstance(self.default_value, basestring):
632 661 self.default_value = import_item(self.default_value)
633 662
634 663 def get_default_value(self):
635 664 return self.default_value
636 665
637 666
638 667 class DefaultValueGenerator(object):
639 668 """A class for generating new default value instances."""
640 669
641 670 def __init__(self, *args, **kw):
642 671 self.args = args
643 672 self.kw = kw
644 673
645 674 def generate(self, klass):
646 675 return klass(*self.args, **self.kw)
647 676
648 677
649 678 class Instance(ClassBasedTraitType):
650 679 """A trait whose value must be an instance of a specified class.
651 680
652 681 The value can also be an instance of a subclass of the specified class.
653 682 """
654 683
655 684 def __init__(self, klass=None, args=None, kw=None,
656 685 allow_none=True, **metadata ):
657 686 """Construct an Instance trait.
658 687
659 688 This trait allows values that are instances of a particular
660 689 class or its sublclasses. Our implementation is quite different
661 690 from that of enthough.traits as we don't allow instances to be used
662 691 for klass and we handle the ``args`` and ``kw`` arguments differently.
663 692
664 693 Parameters
665 694 ----------
666 695 klass : class, str
667 696 The class that forms the basis for the trait. Class names
668 697 can also be specified as strings, like 'foo.bar.Bar'.
669 698 args : tuple
670 699 Positional arguments for generating the default value.
671 700 kw : dict
672 701 Keyword arguments for generating the default value.
673 702 allow_none : bool
674 703 Indicates whether None is allowed as a value.
675 704
676 705 Default Value
677 706 -------------
678 707 If both ``args`` and ``kw`` are None, then the default value is None.
679 708 If ``args`` is a tuple and ``kw`` is a dict, then the default is
680 709 created as ``klass(*args, **kw)``. If either ``args`` or ``kw`` is
681 710 not (but not both), None is replace by ``()`` or ``{}``.
682 711 """
683 712
684 713 self._allow_none = allow_none
685 714
686 715 if (klass is None) or (not (inspect.isclass(klass) or isinstance(klass, basestring))):
687 716 raise TraitError('The klass argument must be a class'
688 717 ' you gave: %r' % klass)
689 718 self.klass = klass
690 719
691 720 # self.klass is a class, so handle default_value
692 721 if args is None and kw is None:
693 722 default_value = None
694 723 else:
695 724 if args is None:
696 725 # kw is not None
697 726 args = ()
698 727 elif kw is None:
699 728 # args is not None
700 729 kw = {}
701 730
702 731 if not isinstance(kw, dict):
703 732 raise TraitError("The 'kw' argument must be a dict or None.")
704 733 if not isinstance(args, tuple):
705 734 raise TraitError("The 'args' argument must be a tuple or None.")
706 735
707 736 default_value = DefaultValueGenerator(*args, **kw)
708 737
709 738 super(Instance, self).__init__(default_value, **metadata)
710 739
711 740 def validate(self, obj, value):
712 741 if value is None:
713 742 if self._allow_none:
714 743 return value
715 744 self.error(obj, value)
716 745
717 746 if isinstance(value, self.klass):
718 747 return value
719 748 else:
720 749 self.error(obj, value)
721 750
722 751 def info(self):
723 752 if isinstance(self.klass, basestring):
724 753 klass = self.klass
725 754 else:
726 755 klass = self.klass.__name__
727 756 result = class_of(klass)
728 757 if self._allow_none:
729 758 return result + ' or None'
730 759
731 760 return result
732 761
733 762 def instance_init(self, obj):
734 763 self._resolve_classes()
735 764 super(Instance, self).instance_init(obj)
736 765
737 766 def _resolve_classes(self):
738 767 if isinstance(self.klass, basestring):
739 768 self.klass = import_item(self.klass)
740 769
741 770 def get_default_value(self):
742 771 """Instantiate a default value instance.
743 772
744 773 This is called when the containing HasTraits classes'
745 774 :meth:`__new__` method is called to ensure that a unique instance
746 775 is created for each HasTraits instance.
747 776 """
748 777 dv = self.default_value
749 778 if isinstance(dv, DefaultValueGenerator):
750 779 return dv.generate(self.klass)
751 780 else:
752 781 return dv
753 782
754 783
755 784 class This(ClassBasedTraitType):
756 785 """A trait for instances of the class containing this trait.
757 786
758 787 Because how how and when class bodies are executed, the ``This``
759 788 trait can only have a default value of None. This, and because we
760 789 always validate default values, ``allow_none`` is *always* true.
761 790 """
762 791
763 792 info_text = 'an instance of the same type as the receiver or None'
764 793
765 794 def __init__(self, **metadata):
766 795 super(This, self).__init__(None, **metadata)
767 796
768 797 def validate(self, obj, value):
769 798 # What if value is a superclass of obj.__class__? This is
770 799 # complicated if it was the superclass that defined the This
771 800 # trait.
772 801 if isinstance(value, self.this_class) or (value is None):
773 802 return value
774 803 else:
775 804 self.error(obj, value)
776 805
777 806
778 807 #-----------------------------------------------------------------------------
779 808 # Basic TraitTypes implementations/subclasses
780 809 #-----------------------------------------------------------------------------
781 810
782 811
783 812 class Any(TraitType):
784 813 default_value = None
785 814 info_text = 'any value'
786 815
787 816
788 817 class Int(TraitType):
789 818 """A integer trait."""
790 819
791 820 default_value = 0
792 821 info_text = 'an integer'
793 822
794 823 def validate(self, obj, value):
795 824 if isinstance(value, int):
796 825 return value
797 826 self.error(obj, value)
798 827
799 828 class CInt(Int):
800 829 """A casting version of the int trait."""
801 830
802 831 def validate(self, obj, value):
803 832 try:
804 833 return int(value)
805 834 except:
806 835 self.error(obj, value)
807 836
808 837
809 838 class Long(TraitType):
810 839 """A long integer trait."""
811 840
812 841 default_value = 0L
813 842 info_text = 'a long'
814 843
815 844 def validate(self, obj, value):
816 845 if isinstance(value, long):
817 846 return value
818 847 if isinstance(value, int):
819 848 return long(value)
820 849 self.error(obj, value)
821 850
822 851
823 852 class CLong(Long):
824 853 """A casting version of the long integer trait."""
825 854
826 855 def validate(self, obj, value):
827 856 try:
828 857 return long(value)
829 858 except:
830 859 self.error(obj, value)
831 860
832 861
833 862 class Float(TraitType):
834 863 """A float trait."""
835 864
836 865 default_value = 0.0
837 866 info_text = 'a float'
838 867
839 868 def validate(self, obj, value):
840 869 if isinstance(value, float):
841 870 return value
842 871 if isinstance(value, int):
843 872 return float(value)
844 873 self.error(obj, value)
845 874
846 875
847 876 class CFloat(Float):
848 877 """A casting version of the float trait."""
849 878
850 879 def validate(self, obj, value):
851 880 try:
852 881 return float(value)
853 882 except:
854 883 self.error(obj, value)
855 884
856 885 class Complex(TraitType):
857 886 """A trait for complex numbers."""
858 887
859 888 default_value = 0.0 + 0.0j
860 889 info_text = 'a complex number'
861 890
862 891 def validate(self, obj, value):
863 892 if isinstance(value, complex):
864 893 return value
865 894 if isinstance(value, (float, int)):
866 895 return complex(value)
867 896 self.error(obj, value)
868 897
869 898
870 899 class CComplex(Complex):
871 900 """A casting version of the complex number trait."""
872 901
873 902 def validate (self, obj, value):
874 903 try:
875 904 return complex(value)
876 905 except:
877 906 self.error(obj, value)
878 907
879 908
880 909 class Str(TraitType):
881 910 """A trait for strings."""
882 911
883 912 default_value = ''
884 913 info_text = 'a string'
885 914
886 915 def validate(self, obj, value):
887 916 if isinstance(value, str):
888 917 return value
889 918 self.error(obj, value)
890 919
891 920
892 921 class CStr(Str):
893 922 """A casting version of the string trait."""
894 923
895 924 def validate(self, obj, value):
896 925 try:
897 926 return str(value)
898 927 except:
899 928 try:
900 929 return unicode(value)
901 930 except:
902 931 self.error(obj, value)
903 932
904 933
905 934 class Unicode(TraitType):
906 935 """A trait for unicode strings."""
907 936
908 937 default_value = u''
909 938 info_text = 'a unicode string'
910 939
911 940 def validate(self, obj, value):
912 941 if isinstance(value, unicode):
913 942 return value
914 943 if isinstance(value, str):
915 944 return unicode(value)
916 945 self.error(obj, value)
917 946
918 947
919 948 class CUnicode(Unicode):
920 949 """A casting version of the unicode trait."""
921 950
922 951 def validate(self, obj, value):
923 952 try:
924 953 return unicode(value)
925 954 except:
926 955 self.error(obj, value)
927 956
928 957
929 958 class Bool(TraitType):
930 959 """A boolean (True, False) trait."""
931 960
932 961 default_value = False
933 962 info_text = 'a boolean'
934 963
935 964 def validate(self, obj, value):
936 965 if isinstance(value, bool):
937 966 return value
938 967 self.error(obj, value)
939 968
940 969
941 970 class CBool(Bool):
942 971 """A casting version of the boolean trait."""
943 972
944 973 def validate(self, obj, value):
945 974 try:
946 975 return bool(value)
947 976 except:
948 977 self.error(obj, value)
949 978
950 979
951 980 class Enum(TraitType):
952 981 """An enum that whose value must be in a given sequence."""
953 982
954 983 def __init__(self, values, default_value=None, allow_none=True, **metadata):
955 984 self.values = values
956 985 self._allow_none = allow_none
957 986 super(Enum, self).__init__(default_value, **metadata)
958 987
959 988 def validate(self, obj, value):
960 989 if value is None:
961 990 if self._allow_none:
962 991 return value
963 992
964 993 if value in self.values:
965 994 return value
966 995 self.error(obj, value)
967 996
968 997 def info(self):
969 998 """ Returns a description of the trait."""
970 999 result = 'any of ' + repr(self.values)
971 1000 if self._allow_none:
972 1001 return result + ' or None'
973 1002 return result
974 1003
975 1004 class CaselessStrEnum(Enum):
976 1005 """An enum of strings that are caseless in validate."""
977 1006
978 1007 def validate(self, obj, value):
979 1008 if value is None:
980 1009 if self._allow_none:
981 1010 return value
982 1011
983 1012 if not isinstance(value, str):
984 1013 self.error(obj, value)
985 1014
986 1015 for v in self.values:
987 1016 if v.lower() == value.lower():
988 1017 return v
989 1018 self.error(obj, value)
990 1019
991 1020
992 1021 class List(Instance):
993 1022 """An instance of a Python list."""
994 1023
995 1024 def __init__(self, default_value=None, allow_none=True, **metadata):
996 1025 """Create a list trait type from a list or tuple.
997 1026
998 1027 The default value is created by doing ``list(default_value)``,
999 1028 which creates a copy of the ``default_value``.
1000 1029 """
1001 1030 if default_value is None:
1002 1031 args = ((),)
1003 1032 elif isinstance(default_value, SequenceTypes):
1004 1033 args = (default_value,)
1005 1034 else:
1006 1035 raise TypeError('default value of List was %s' % default_value)
1007 1036
1008 1037 super(List,self).__init__(klass=list, args=args,
1009 1038 allow_none=allow_none, **metadata)
1010 1039
1011 1040
1012 1041 class Dict(Instance):
1013 1042 """An instance of a Python dict."""
1014 1043
1015 1044 def __init__(self, default_value=None, allow_none=True, **metadata):
1016 1045 """Create a dict trait type from a dict.
1017 1046
1018 1047 The default value is created by doing ``dict(default_value)``,
1019 1048 which creates a copy of the ``default_value``.
1020 1049 """
1021 1050 if default_value is None:
1022 1051 args = ((),)
1023 1052 elif isinstance(default_value, dict):
1024 1053 args = (default_value,)
1025 1054 elif isinstance(default_value, SequenceTypes):
1026 1055 args = (default_value,)
1027 1056 else:
1028 1057 raise TypeError('default value of Dict was %s' % default_value)
1029 1058
1030 1059 super(Dict,self).__init__(klass=dict, args=args,
1031 1060 allow_none=allow_none, **metadata)
1032 1061
1033 1062
1034 1063 class TCPAddress(TraitType):
1035 1064 """A trait for an (ip, port) tuple.
1036 1065
1037 1066 This allows for both IPv4 IP addresses as well as hostnames.
1038 1067 """
1039 1068
1040 1069 default_value = ('127.0.0.1', 0)
1041 1070 info_text = 'an (ip, port) tuple'
1042 1071
1043 1072 def validate(self, obj, value):
1044 1073 if isinstance(value, tuple):
1045 1074 if len(value) == 2:
1046 1075 if isinstance(value[0], basestring) and isinstance(value[1], int):
1047 1076 port = value[1]
1048 1077 if port >= 0 and port <= 65535:
1049 1078 return value
1050 1079 self.error(obj, value)
@@ -1,580 +1,581
1 1 """A ZMQ-based subclass of InteractiveShell.
2 2
3 3 This code is meant to ease the refactoring of the base InteractiveShell into
4 4 something with a cleaner architecture for 2-process use, without actually
5 5 breaking InteractiveShell itself. So we're doing something a bit ugly, where
6 6 we subclass and override what we want to fix. Once this is working well, we
7 7 can go back to the base class and refactor the code for a cleaner inheritance
8 8 implementation that doesn't rely on so much monkeypatching.
9 9
10 10 But this lets us maintain a fully working IPython as we develop the new
11 11 machinery. This should thus be thought of as scaffolding.
12 12 """
13 13 #-----------------------------------------------------------------------------
14 14 # Imports
15 15 #-----------------------------------------------------------------------------
16 16 from __future__ import print_function
17 17
18 18 # Stdlib
19 19 import inspect
20 20 import os
21 21 import re
22 22
23 23 # Our own
24 24 from IPython.core.interactiveshell import (
25 25 InteractiveShell, InteractiveShellABC
26 26 )
27 27 from IPython.core import page
28 28 from IPython.core.displayhook import DisplayHook
29 29 from IPython.core.macro import Macro
30 30 from IPython.core.payloadpage import install_payload_page
31 31 from IPython.utils import io
32 32 from IPython.utils.path import get_py_filename
33 33 from IPython.utils.text import StringTypes
34 34 from IPython.utils.traitlets import Instance, Type, Dict
35 35 from IPython.utils.warn import warn
36 36 from IPython.zmq.session import extract_header
37 37 from session import Session
38 38
39 39 #-----------------------------------------------------------------------------
40 40 # Globals and side-effects
41 41 #-----------------------------------------------------------------------------
42 42
43 43 # Install the payload version of page.
44 44 install_payload_page()
45 45
46 46 #-----------------------------------------------------------------------------
47 47 # Functions and classes
48 48 #-----------------------------------------------------------------------------
49 49
50 50 class ZMQDisplayHook(DisplayHook):
51 51
52 52 session = Instance(Session)
53 53 pub_socket = Instance('zmq.Socket')
54 54 parent_header = Dict({})
55 55
56 56 def set_parent(self, parent):
57 57 """Set the parent for outbound messages."""
58 58 self.parent_header = extract_header(parent)
59 59
60 60 def start_displayhook(self):
61 61 self.msg = self.session.msg(u'pyout', {}, parent=self.parent_header)
62 62
63 63 def write_output_prompt(self):
64 64 """Write the output prompt."""
65 65 if self.do_full_cache:
66 66 self.msg['content']['execution_count'] = self.prompt_count
67 67
68 def write_result_repr(self, result_repr):
68 def write_result_repr(self, result_repr, extra_formats):
69 69 self.msg['content']['data'] = result_repr
70 self.msg['content']['extra_formats'] = extra_formats
70 71
71 72 def finish_displayhook(self):
72 73 """Finish up all displayhook activities."""
73 74 self.pub_socket.send_json(self.msg)
74 75 self.msg = None
75 76
76 77
77 78 class ZMQInteractiveShell(InteractiveShell):
78 79 """A subclass of InteractiveShell for ZMQ."""
79 80
80 81 displayhook_class = Type(ZMQDisplayHook)
81 82 keepkernel_on_exit = None
82 83
83 84 def init_environment(self):
84 85 """Configure the user's environment.
85 86
86 87 """
87 88 env = os.environ
88 89 # These two ensure 'ls' produces nice coloring on BSD-derived systems
89 90 env['TERM'] = 'xterm-color'
90 91 env['CLICOLOR'] = '1'
91 92 # Since normal pagers don't work at all (over pexpect we don't have
92 93 # single-key control of the subprocess), try to disable paging in
93 94 # subprocesses as much as possible.
94 95 env['PAGER'] = 'cat'
95 96 env['GIT_PAGER'] = 'cat'
96 97
97 98 def auto_rewrite_input(self, cmd):
98 99 """Called to show the auto-rewritten input for autocall and friends.
99 100
100 101 FIXME: this payload is currently not correctly processed by the
101 102 frontend.
102 103 """
103 104 new = self.displayhook.prompt1.auto_rewrite() + cmd
104 105 payload = dict(
105 106 source='IPython.zmq.zmqshell.ZMQInteractiveShell.auto_rewrite_input',
106 107 transformed_input=new,
107 108 )
108 109 self.payload_manager.write_payload(payload)
109 110
110 111 def ask_exit(self):
111 112 """Engage the exit actions."""
112 113 payload = dict(
113 114 source='IPython.zmq.zmqshell.ZMQInteractiveShell.ask_exit',
114 115 exit=True,
115 116 keepkernel=self.keepkernel_on_exit,
116 117 )
117 118 self.payload_manager.write_payload(payload)
118 119
119 120 def _showtraceback(self, etype, evalue, stb):
120 121
121 122 exc_content = {
122 123 u'traceback' : stb,
123 124 u'ename' : unicode(etype.__name__),
124 125 u'evalue' : unicode(evalue)
125 126 }
126 127
127 128 dh = self.displayhook
128 129 exc_msg = dh.session.msg(u'pyerr', exc_content, dh.parent_header)
129 130 # Send exception info over pub socket for other clients than the caller
130 131 # to pick up
131 132 dh.pub_socket.send_json(exc_msg)
132 133
133 134 # FIXME - Hack: store exception info in shell object. Right now, the
134 135 # caller is reading this info after the fact, we need to fix this logic
135 136 # to remove this hack. Even uglier, we need to store the error status
136 137 # here, because in the main loop, the logic that sets it is being
137 138 # skipped because runlines swallows the exceptions.
138 139 exc_content[u'status'] = u'error'
139 140 self._reply_content = exc_content
140 141 # /FIXME
141 142
142 143 return exc_content
143 144
144 145 #------------------------------------------------------------------------
145 146 # Magic overrides
146 147 #------------------------------------------------------------------------
147 148 # Once the base class stops inheriting from magic, this code needs to be
148 149 # moved into a separate machinery as well. For now, at least isolate here
149 150 # the magics which this class needs to implement differently from the base
150 151 # class, or that are unique to it.
151 152
152 153 def magic_doctest_mode(self,parameter_s=''):
153 154 """Toggle doctest mode on and off.
154 155
155 156 This mode is intended to make IPython behave as much as possible like a
156 157 plain Python shell, from the perspective of how its prompts, exceptions
157 158 and output look. This makes it easy to copy and paste parts of a
158 159 session into doctests. It does so by:
159 160
160 161 - Changing the prompts to the classic ``>>>`` ones.
161 162 - Changing the exception reporting mode to 'Plain'.
162 163 - Disabling pretty-printing of output.
163 164
164 165 Note that IPython also supports the pasting of code snippets that have
165 166 leading '>>>' and '...' prompts in them. This means that you can paste
166 167 doctests from files or docstrings (even if they have leading
167 168 whitespace), and the code will execute correctly. You can then use
168 169 '%history -t' to see the translated history; this will give you the
169 170 input after removal of all the leading prompts and whitespace, which
170 171 can be pasted back into an editor.
171 172
172 173 With these features, you can switch into this mode easily whenever you
173 174 need to do testing and changes to doctests, without having to leave
174 175 your existing IPython session.
175 176 """
176 177
177 178 from IPython.utils.ipstruct import Struct
178 179
179 180 # Shorthands
180 181 shell = self.shell
181 182 # dstore is a data store kept in the instance metadata bag to track any
182 183 # changes we make, so we can undo them later.
183 184 dstore = shell.meta.setdefault('doctest_mode', Struct())
184 185 save_dstore = dstore.setdefault
185 186
186 187 # save a few values we'll need to recover later
187 188 mode = save_dstore('mode', False)
188 189 save_dstore('rc_pprint', shell.pprint)
189 190 save_dstore('xmode', shell.InteractiveTB.mode)
190 191
191 192 if mode == False:
192 193 # turn on
193 194 shell.pprint = False
194 195 shell.magic_xmode('Plain')
195 196 else:
196 197 # turn off
197 198 shell.pprint = dstore.rc_pprint
198 199 shell.magic_xmode(dstore.xmode)
199 200
200 201 # Store new mode and inform on console
201 202 dstore.mode = bool(1-int(mode))
202 203 mode_label = ['OFF','ON'][dstore.mode]
203 204 print('Doctest mode is:', mode_label)
204 205
205 206 # Send the payload back so that clients can modify their prompt display
206 207 payload = dict(
207 208 source='IPython.zmq.zmqshell.ZMQInteractiveShell.magic_doctest_mode',
208 209 mode=dstore.mode)
209 210 self.payload_manager.write_payload(payload)
210 211
211 212 def magic_edit(self,parameter_s='',last_call=['','']):
212 213 """Bring up an editor and execute the resulting code.
213 214
214 215 Usage:
215 216 %edit [options] [args]
216 217
217 218 %edit runs IPython's editor hook. The default version of this hook is
218 219 set to call the __IPYTHON__.rc.editor command. This is read from your
219 220 environment variable $EDITOR. If this isn't found, it will default to
220 221 vi under Linux/Unix and to notepad under Windows. See the end of this
221 222 docstring for how to change the editor hook.
222 223
223 224 You can also set the value of this editor via the command line option
224 225 '-editor' or in your ipythonrc file. This is useful if you wish to use
225 226 specifically for IPython an editor different from your typical default
226 227 (and for Windows users who typically don't set environment variables).
227 228
228 229 This command allows you to conveniently edit multi-line code right in
229 230 your IPython session.
230 231
231 232 If called without arguments, %edit opens up an empty editor with a
232 233 temporary file and will execute the contents of this file when you
233 234 close it (don't forget to save it!).
234 235
235 236
236 237 Options:
237 238
238 239 -n <number>: open the editor at a specified line number. By default,
239 240 the IPython editor hook uses the unix syntax 'editor +N filename', but
240 241 you can configure this by providing your own modified hook if your
241 242 favorite editor supports line-number specifications with a different
242 243 syntax.
243 244
244 245 -p: this will call the editor with the same data as the previous time
245 246 it was used, regardless of how long ago (in your current session) it
246 247 was.
247 248
248 249 -r: use 'raw' input. This option only applies to input taken from the
249 250 user's history. By default, the 'processed' history is used, so that
250 251 magics are loaded in their transformed version to valid Python. If
251 252 this option is given, the raw input as typed as the command line is
252 253 used instead. When you exit the editor, it will be executed by
253 254 IPython's own processor.
254 255
255 256 -x: do not execute the edited code immediately upon exit. This is
256 257 mainly useful if you are editing programs which need to be called with
257 258 command line arguments, which you can then do using %run.
258 259
259 260
260 261 Arguments:
261 262
262 263 If arguments are given, the following possibilites exist:
263 264
264 265 - The arguments are numbers or pairs of colon-separated numbers (like
265 266 1 4:8 9). These are interpreted as lines of previous input to be
266 267 loaded into the editor. The syntax is the same of the %macro command.
267 268
268 269 - If the argument doesn't start with a number, it is evaluated as a
269 270 variable and its contents loaded into the editor. You can thus edit
270 271 any string which contains python code (including the result of
271 272 previous edits).
272 273
273 274 - If the argument is the name of an object (other than a string),
274 275 IPython will try to locate the file where it was defined and open the
275 276 editor at the point where it is defined. You can use `%edit function`
276 277 to load an editor exactly at the point where 'function' is defined,
277 278 edit it and have the file be executed automatically.
278 279
279 280 If the object is a macro (see %macro for details), this opens up your
280 281 specified editor with a temporary file containing the macro's data.
281 282 Upon exit, the macro is reloaded with the contents of the file.
282 283
283 284 Note: opening at an exact line is only supported under Unix, and some
284 285 editors (like kedit and gedit up to Gnome 2.8) do not understand the
285 286 '+NUMBER' parameter necessary for this feature. Good editors like
286 287 (X)Emacs, vi, jed, pico and joe all do.
287 288
288 289 - If the argument is not found as a variable, IPython will look for a
289 290 file with that name (adding .py if necessary) and load it into the
290 291 editor. It will execute its contents with execfile() when you exit,
291 292 loading any code in the file into your interactive namespace.
292 293
293 294 After executing your code, %edit will return as output the code you
294 295 typed in the editor (except when it was an existing file). This way
295 296 you can reload the code in further invocations of %edit as a variable,
296 297 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
297 298 the output.
298 299
299 300 Note that %edit is also available through the alias %ed.
300 301
301 302 This is an example of creating a simple function inside the editor and
302 303 then modifying it. First, start up the editor:
303 304
304 305 In [1]: ed
305 306 Editing... done. Executing edited code...
306 307 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
307 308
308 309 We can then call the function foo():
309 310
310 311 In [2]: foo()
311 312 foo() was defined in an editing session
312 313
313 314 Now we edit foo. IPython automatically loads the editor with the
314 315 (temporary) file where foo() was previously defined:
315 316
316 317 In [3]: ed foo
317 318 Editing... done. Executing edited code...
318 319
319 320 And if we call foo() again we get the modified version:
320 321
321 322 In [4]: foo()
322 323 foo() has now been changed!
323 324
324 325 Here is an example of how to edit a code snippet successive
325 326 times. First we call the editor:
326 327
327 328 In [5]: ed
328 329 Editing... done. Executing edited code...
329 330 hello
330 331 Out[5]: "print 'hello'n"
331 332
332 333 Now we call it again with the previous output (stored in _):
333 334
334 335 In [6]: ed _
335 336 Editing... done. Executing edited code...
336 337 hello world
337 338 Out[6]: "print 'hello world'n"
338 339
339 340 Now we call it with the output #8 (stored in _8, also as Out[8]):
340 341
341 342 In [7]: ed _8
342 343 Editing... done. Executing edited code...
343 344 hello again
344 345 Out[7]: "print 'hello again'n"
345 346
346 347
347 348 Changing the default editor hook:
348 349
349 350 If you wish to write your own editor hook, you can put it in a
350 351 configuration file which you load at startup time. The default hook
351 352 is defined in the IPython.core.hooks module, and you can use that as a
352 353 starting example for further modifications. That file also has
353 354 general instructions on how to set a new hook for use once you've
354 355 defined it."""
355 356
356 357 # FIXME: This function has become a convoluted mess. It needs a
357 358 # ground-up rewrite with clean, simple logic.
358 359
359 360 def make_filename(arg):
360 361 "Make a filename from the given args"
361 362 try:
362 363 filename = get_py_filename(arg)
363 364 except IOError:
364 365 if args.endswith('.py'):
365 366 filename = arg
366 367 else:
367 368 filename = None
368 369 return filename
369 370
370 371 # custom exceptions
371 372 class DataIsObject(Exception): pass
372 373
373 374 opts,args = self.parse_options(parameter_s,'prn:')
374 375 # Set a few locals from the options for convenience:
375 376 opts_p = opts.has_key('p')
376 377 opts_r = opts.has_key('r')
377 378
378 379 # Default line number value
379 380 lineno = opts.get('n',None)
380 381 if lineno is not None:
381 382 try:
382 383 lineno = int(lineno)
383 384 except:
384 385 warn("The -n argument must be an integer.")
385 386 return
386 387
387 388 if opts_p:
388 389 args = '_%s' % last_call[0]
389 390 if not self.shell.user_ns.has_key(args):
390 391 args = last_call[1]
391 392
392 393 # use last_call to remember the state of the previous call, but don't
393 394 # let it be clobbered by successive '-p' calls.
394 395 try:
395 396 last_call[0] = self.shell.displayhook.prompt_count
396 397 if not opts_p:
397 398 last_call[1] = parameter_s
398 399 except:
399 400 pass
400 401
401 402 # by default this is done with temp files, except when the given
402 403 # arg is a filename
403 404 use_temp = 1
404 405
405 406 if re.match(r'\d',args):
406 407 # Mode where user specifies ranges of lines, like in %macro.
407 408 # This means that you can't edit files whose names begin with
408 409 # numbers this way. Tough.
409 410 ranges = args.split()
410 411 data = ''.join(self.extract_input_slices(ranges,opts_r))
411 412 elif args.endswith('.py'):
412 413 filename = make_filename(args)
413 414 data = ''
414 415 use_temp = 0
415 416 elif args:
416 417 try:
417 418 # Load the parameter given as a variable. If not a string,
418 419 # process it as an object instead (below)
419 420
420 421 #print '*** args',args,'type',type(args) # dbg
421 422 data = eval(args,self.shell.user_ns)
422 423 if not type(data) in StringTypes:
423 424 raise DataIsObject
424 425
425 426 except (NameError,SyntaxError):
426 427 # given argument is not a variable, try as a filename
427 428 filename = make_filename(args)
428 429 if filename is None:
429 430 warn("Argument given (%s) can't be found as a variable "
430 431 "or as a filename." % args)
431 432 return
432 433
433 434 data = ''
434 435 use_temp = 0
435 436 except DataIsObject:
436 437
437 438 # macros have a special edit function
438 439 if isinstance(data,Macro):
439 440 self._edit_macro(args,data)
440 441 return
441 442
442 443 # For objects, try to edit the file where they are defined
443 444 try:
444 445 filename = inspect.getabsfile(data)
445 446 if 'fakemodule' in filename.lower() and inspect.isclass(data):
446 447 # class created by %edit? Try to find source
447 448 # by looking for method definitions instead, the
448 449 # __module__ in those classes is FakeModule.
449 450 attrs = [getattr(data, aname) for aname in dir(data)]
450 451 for attr in attrs:
451 452 if not inspect.ismethod(attr):
452 453 continue
453 454 filename = inspect.getabsfile(attr)
454 455 if filename and 'fakemodule' not in filename.lower():
455 456 # change the attribute to be the edit target instead
456 457 data = attr
457 458 break
458 459
459 460 datafile = 1
460 461 except TypeError:
461 462 filename = make_filename(args)
462 463 datafile = 1
463 464 warn('Could not find file where `%s` is defined.\n'
464 465 'Opening a file named `%s`' % (args,filename))
465 466 # Now, make sure we can actually read the source (if it was in
466 467 # a temp file it's gone by now).
467 468 if datafile:
468 469 try:
469 470 if lineno is None:
470 471 lineno = inspect.getsourcelines(data)[1]
471 472 except IOError:
472 473 filename = make_filename(args)
473 474 if filename is None:
474 475 warn('The file `%s` where `%s` was defined cannot '
475 476 'be read.' % (filename,data))
476 477 return
477 478 use_temp = 0
478 479 else:
479 480 data = ''
480 481
481 482 if use_temp:
482 483 filename = self.shell.mktempfile(data)
483 484 print('IPython will make a temporary file named:', filename)
484 485
485 486 # Make sure we send to the client an absolute path, in case the working
486 487 # directory of client and kernel don't match
487 488 filename = os.path.abspath(filename)
488 489
489 490 payload = {
490 491 'source' : 'IPython.zmq.zmqshell.ZMQInteractiveShell.edit_magic',
491 492 'filename' : filename,
492 493 'line_number' : lineno
493 494 }
494 495 self.payload_manager.write_payload(payload)
495 496
496 497 def magic_gui(self, *args, **kwargs):
497 498 raise NotImplementedError(
498 499 'GUI support must be enabled in command line options.')
499 500
500 501 def magic_pylab(self, *args, **kwargs):
501 502 raise NotImplementedError(
502 503 'pylab support must be enabled in command line options.')
503 504
504 505 # A few magics that are adapted to the specifics of using pexpect and a
505 506 # remote terminal
506 507
507 508 def magic_clear(self, arg_s):
508 509 """Clear the terminal."""
509 510 if os.name == 'posix':
510 511 self.shell.system("clear")
511 512 else:
512 513 self.shell.system("cls")
513 514
514 515 if os.name == 'nt':
515 516 # This is the usual name in windows
516 517 magic_cls = magic_clear
517 518
518 519 # Terminal pagers won't work over pexpect, but we do have our own pager
519 520
520 521 def magic_less(self, arg_s):
521 522 """Show a file through the pager.
522 523
523 524 Files ending in .py are syntax-highlighted."""
524 525 cont = open(arg_s).read()
525 526 if arg_s.endswith('.py'):
526 527 cont = self.shell.pycolorize(cont)
527 528 page.page(cont)
528 529
529 530 magic_more = magic_less
530 531
531 532 # Man calls a pager, so we also need to redefine it
532 533 if os.name == 'posix':
533 534 def magic_man(self, arg_s):
534 535 """Find the man page for the given command and display in pager."""
535 536 page.page(self.shell.getoutput('man %s | col -b' % arg_s,
536 537 split=False))
537 538
538 539 # FIXME: this is specific to the GUI, so we should let the gui app load
539 540 # magics at startup that are only for the gui. Once the gui app has proper
540 541 # profile and configuration management, we can have it initialize a kernel
541 542 # with a special config file that provides these.
542 543 def magic_guiref(self, arg_s):
543 544 """Show a basic reference about the GUI console."""
544 545 from IPython.core.usage import gui_reference
545 546 page.page(gui_reference, auto_html=True)
546 547
547 548 def magic_loadpy(self, arg_s):
548 549 """Load a .py python script into the GUI console.
549 550
550 551 This magic command can either take a local filename or a url::
551 552
552 553 %loadpy myscript.py
553 554 %loadpy http://www.example.com/myscript.py
554 555 """
555 556 if not arg_s.endswith('.py'):
556 557 raise ValueError('%%load only works with .py files: %s' % arg_s)
557 558 if arg_s.startswith('http'):
558 559 import urllib2
559 560 response = urllib2.urlopen(arg_s)
560 561 content = response.read()
561 562 else:
562 563 content = open(arg_s).read()
563 564 payload = dict(
564 565 source='IPython.zmq.zmqshell.ZMQInteractiveShell.magic_loadpy',
565 566 text=content
566 567 )
567 568 self.payload_manager.write_payload(payload)
568 569
569 570 def magic_Exit(self, parameter_s=''):
570 571 """Exit IPython. If the -k option is provided, the kernel will be left
571 572 running. Otherwise, it will shutdown without prompting.
572 573 """
573 574 opts,args = self.parse_options(parameter_s,'k')
574 575 self.shell.keepkernel_on_exit = opts.has_key('k')
575 576 self.shell.ask_exit()
576 577
577 578 # Add aliases as magics so all common forms work: exit, quit, Exit, Quit.
578 579 magic_exit = magic_quit = magic_Quit = magic_Exit
579 580
580 581 InteractiveShellABC.register(ZMQInteractiveShell)
@@ -1,873 +1,892
1 1 .. _messaging:
2 2
3 3 ======================
4 4 Messaging in IPython
5 5 ======================
6 6
7 7
8 8 Introduction
9 9 ============
10 10
11 11 This document explains the basic communications design and messaging
12 12 specification for how the various IPython objects interact over a network
13 13 transport. The current implementation uses the ZeroMQ_ library for messaging
14 14 within and between hosts.
15 15
16 16 .. Note::
17 17
18 18 This document should be considered the authoritative description of the
19 19 IPython messaging protocol, and all developers are strongly encouraged to
20 20 keep it updated as the implementation evolves, so that we have a single
21 21 common reference for all protocol details.
22 22
23 23 The basic design is explained in the following diagram:
24 24
25 25 .. image:: frontend-kernel.png
26 26 :width: 450px
27 27 :alt: IPython kernel/frontend messaging architecture.
28 28 :align: center
29 29 :target: ../_images/frontend-kernel.png
30 30
31 31 A single kernel can be simultaneously connected to one or more frontends. The
32 32 kernel has three sockets that serve the following functions:
33 33
34 34 1. REQ: this socket is connected to a *single* frontend at a time, and it allows
35 35 the kernel to request input from a frontend when :func:`raw_input` is called.
36 36 The frontend holding the matching REP socket acts as a 'virtual keyboard'
37 37 for the kernel while this communication is happening (illustrated in the
38 38 figure by the black outline around the central keyboard). In practice,
39 39 frontends may display such kernel requests using a special input widget or
40 40 otherwise indicating that the user is to type input for the kernel instead
41 41 of normal commands in the frontend.
42 42
43 43 2. XREP: this single sockets allows multiple incoming connections from
44 44 frontends, and this is the socket where requests for code execution, object
45 45 information, prompts, etc. are made to the kernel by any frontend. The
46 46 communication on this socket is a sequence of request/reply actions from
47 47 each frontend and the kernel.
48 48
49 49 3. PUB: this socket is the 'broadcast channel' where the kernel publishes all
50 50 side effects (stdout, stderr, etc.) as well as the requests coming from any
51 51 client over the XREP socket and its own requests on the REP socket. There
52 52 are a number of actions in Python which generate side effects: :func:`print`
53 53 writes to ``sys.stdout``, errors generate tracebacks, etc. Additionally, in
54 54 a multi-client scenario, we want all frontends to be able to know what each
55 55 other has sent to the kernel (this can be useful in collaborative scenarios,
56 56 for example). This socket allows both side effects and the information
57 57 about communications taking place with one client over the XREQ/XREP channel
58 58 to be made available to all clients in a uniform manner.
59 59
60 60 All messages are tagged with enough information (details below) for clients
61 61 to know which messages come from their own interaction with the kernel and
62 62 which ones are from other clients, so they can display each type
63 63 appropriately.
64 64
65 65 The actual format of the messages allowed on each of these channels is
66 66 specified below. Messages are dicts of dicts with string keys and values that
67 67 are reasonably representable in JSON. Our current implementation uses JSON
68 68 explicitly as its message format, but this shouldn't be considered a permanent
69 69 feature. As we've discovered that JSON has non-trivial performance issues due
70 70 to excessive copying, we may in the future move to a pure pickle-based raw
71 71 message format. However, it should be possible to easily convert from the raw
72 72 objects to JSON, since we may have non-python clients (e.g. a web frontend).
73 73 As long as it's easy to make a JSON version of the objects that is a faithful
74 74 representation of all the data, we can communicate with such clients.
75 75
76 76 .. Note::
77 77
78 78 Not all of these have yet been fully fleshed out, but the key ones are, see
79 79 kernel and frontend files for actual implementation details.
80 80
81 81
82 82 Python functional API
83 83 =====================
84 84
85 85 As messages are dicts, they map naturally to a ``func(**kw)`` call form. We
86 86 should develop, at a few key points, functional forms of all the requests that
87 87 take arguments in this manner and automatically construct the necessary dict
88 88 for sending.
89 89
90 90
91 91 General Message Format
92 92 ======================
93 93
94 94 All messages send or received by any IPython process should have the following
95 95 generic structure::
96 96
97 97 {
98 98 # The message header contains a pair of unique identifiers for the
99 99 # originating session and the actual message id, in addition to the
100 100 # username for the process that generated the message. This is useful in
101 101 # collaborative settings where multiple users may be interacting with the
102 102 # same kernel simultaneously, so that frontends can label the various
103 103 # messages in a meaningful way.
104 104 'header' : { 'msg_id' : uuid,
105 105 'username' : str,
106 106 'session' : uuid
107 107 },
108 108
109 109 # In a chain of messages, the header from the parent is copied so that
110 110 # clients can track where messages come from.
111 111 'parent_header' : dict,
112 112
113 113 # All recognized message type strings are listed below.
114 114 'msg_type' : str,
115 115
116 116 # The actual content of the message must be a dict, whose structure
117 117 # depends on the message type.x
118 118 'content' : dict,
119 119 }
120 120
121 121 For each message type, the actual content will differ and all existing message
122 122 types are specified in what follows of this document.
123 123
124 124
125 125 Messages on the XREP/XREQ socket
126 126 ================================
127 127
128 128 .. _execute:
129 129
130 130 Execute
131 131 -------
132 132
133 133 This message type is used by frontends to ask the kernel to execute code on
134 134 behalf of the user, in a namespace reserved to the user's variables (and thus
135 135 separate from the kernel's own internal code and variables).
136 136
137 137 Message type: ``execute_request``::
138 138
139 139 content = {
140 140 # Source code to be executed by the kernel, one or more lines.
141 141 'code' : str,
142 142
143 143 # A boolean flag which, if True, signals the kernel to execute this
144 144 # code as quietly as possible. This means that the kernel will compile
145 145 # the code witIPython/core/tests/h 'exec' instead of 'single' (so
146 146 # sys.displayhook will not fire), and will *not*:
147 147 # - broadcast exceptions on the PUB socket
148 148 # - do any logging
149 149 # - populate any history
150 150 #
151 151 # The default is False.
152 152 'silent' : bool,
153 153
154 154 # A list of variable names from the user's namespace to be retrieved. What
155 155 # returns is a JSON string of the variable's repr(), not a python object.
156 156 'user_variables' : list,
157 157
158 158 # Similarly, a dict mapping names to expressions to be evaluated in the
159 159 # user's dict.
160 160 'user_expressions' : dict,
161 161 }
162 162
163 163 The ``code`` field contains a single string (possibly multiline). The kernel
164 164 is responsible for splitting this into one or more independent execution blocks
165 165 and deciding whether to compile these in 'single' or 'exec' mode (see below for
166 166 detailed execution semantics).
167 167
168 168 The ``user_`` fields deserve a detailed explanation. In the past, IPython had
169 169 the notion of a prompt string that allowed arbitrary code to be evaluated, and
170 170 this was put to good use by many in creating prompts that displayed system
171 171 status, path information, and even more esoteric uses like remote instrument
172 172 status aqcuired over the network. But now that IPython has a clean separation
173 173 between the kernel and the clients, the kernel has no prompt knowledge; prompts
174 174 are a frontend-side feature, and it should be even possible for different
175 175 frontends to display different prompts while interacting with the same kernel.
176 176
177 177 The kernel now provides the ability to retrieve data from the user's namespace
178 178 after the execution of the main ``code``, thanks to two fields in the
179 179 ``execute_request`` message:
180 180
181 181 - ``user_variables``: If only variables from the user's namespace are needed, a
182 182 list of variable names can be passed and a dict with these names as keys and
183 183 their :func:`repr()` as values will be returned.
184 184
185 185 - ``user_expressions``: For more complex expressions that require function
186 186 evaluations, a dict can be provided with string keys and arbitrary python
187 187 expressions as values. The return message will contain also a dict with the
188 188 same keys and the :func:`repr()` of the evaluated expressions as value.
189 189
190 190 With this information, frontends can display any status information they wish
191 191 in the form that best suits each frontend (a status line, a popup, inline for a
192 192 terminal, etc).
193 193
194 194 .. Note::
195 195
196 196 In order to obtain the current execution counter for the purposes of
197 197 displaying input prompts, frontends simply make an execution request with an
198 198 empty code string and ``silent=True``.
199 199
200 200 Execution semantics
201 201 ~~~~~~~~~~~~~~~~~~~
202 202
203 203 When the silent flag is false, the execution of use code consists of the
204 204 following phases (in silent mode, only the ``code`` field is executed):
205 205
206 206 1. Run the ``pre_runcode_hook``.
207 207
208 208 2. Execute the ``code`` field, see below for details.
209 209
210 210 3. If #2 succeeds, compute ``user_variables`` and ``user_expressions`` are
211 211 computed. This ensures that any error in the latter don't harm the main
212 212 code execution.
213 213
214 214 4. Call any method registered with :meth:`register_post_execute`.
215 215
216 216 .. warning::
217 217
218 218 The API for running code before/after the main code block is likely to
219 219 change soon. Both the ``pre_runcode_hook`` and the
220 220 :meth:`register_post_execute` are susceptible to modification, as we find a
221 221 consistent model for both.
222 222
223 223 To understand how the ``code`` field is executed, one must know that Python
224 224 code can be compiled in one of three modes (controlled by the ``mode`` argument
225 225 to the :func:`compile` builtin):
226 226
227 227 *single*
228 228 Valid for a single interactive statement (though the source can contain
229 229 multiple lines, such as a for loop). When compiled in this mode, the
230 230 generated bytecode contains special instructions that trigger the calling of
231 231 :func:`sys.displayhook` for any expression in the block that returns a value.
232 232 This means that a single statement can actually produce multiple calls to
233 233 :func:`sys.displayhook`, if for example it contains a loop where each
234 234 iteration computes an unassigned expression would generate 10 calls::
235 235
236 236 for i in range(10):
237 237 i**2
238 238
239 239 *exec*
240 240 An arbitrary amount of source code, this is how modules are compiled.
241 241 :func:`sys.displayhook` is *never* implicitly called.
242 242
243 243 *eval*
244 244 A single expression that returns a value. :func:`sys.displayhook` is *never*
245 245 implicitly called.
246 246
247 247
248 248 The ``code`` field is split into individual blocks each of which is valid for
249 249 execution in 'single' mode, and then:
250 250
251 251 - If there is only a single block: it is executed in 'single' mode.
252 252
253 253 - If there is more than one block:
254 254
255 255 * if the last one is a single line long, run all but the last in 'exec' mode
256 256 and the very last one in 'single' mode. This makes it easy to type simple
257 257 expressions at the end to see computed values.
258 258
259 259 * if the last one is no more than two lines long, run all but the last in
260 260 'exec' mode and the very last one in 'single' mode. This makes it easy to
261 261 type simple expressions at the end to see computed values. - otherwise
262 262 (last one is also multiline), run all in 'exec' mode
263 263
264 264 * otherwise (last one is also multiline), run all in 'exec' mode as a single
265 265 unit.
266 266
267 267 Any error in retrieving the ``user_variables`` or evaluating the
268 268 ``user_expressions`` will result in a simple error message in the return fields
269 269 of the form::
270 270
271 271 [ERROR] ExceptionType: Exception message
272 272
273 273 The user can simply send the same variable name or expression for evaluation to
274 274 see a regular traceback.
275 275
276 276 Errors in any registered post_execute functions are also reported similarly,
277 277 and the failing function is removed from the post_execution set so that it does
278 278 not continue triggering failures.
279 279
280 280 Upon completion of the execution request, the kernel *always* sends a reply,
281 281 with a status code indicating what happened and additional data depending on
282 282 the outcome. See :ref:`below <execution_results>` for the possible return
283 283 codes and associated data.
284 284
285 285
286 286 Execution counter (old prompt number)
287 287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
288 288
289 289 The kernel has a single, monotonically increasing counter of all execution
290 290 requests that are made with ``silent=False``. This counter is used to populate
291 291 the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
292 292 display it in some form to the user, which will typically (but not necessarily)
293 293 be done in the prompts. The value of this counter will be returned as the
294 294 ``execution_count`` field of all ``execute_reply`` messages.
295 295
296 296 .. _execution_results:
297 297
298 298 Execution results
299 299 ~~~~~~~~~~~~~~~~~
300 300
301 301 Message type: ``execute_reply``::
302 302
303 303 content = {
304 304 # One of: 'ok' OR 'error' OR 'abort'
305 305 'status' : str,
306 306
307 307 # The global kernel counter that increases by one with each non-silent
308 308 # executed request. This will typically be used by clients to display
309 309 # prompt numbers to the user. If the request was a silent one, this will
310 310 # be the current value of the counter in the kernel.
311 311 'execution_count' : int,
312 312 }
313 313
314 314 When status is 'ok', the following extra fields are present::
315 315
316 316 {
317 317 # The execution payload is a dict with string keys that may have been
318 318 # produced by the code being executed. It is retrieved by the kernel at
319 319 # the end of the execution and sent back to the front end, which can take
320 320 # action on it as needed. See main text for further details.
321 321 'payload' : dict,
322 322
323 323 # Results for the user_variables and user_expressions.
324 324 'user_variables' : dict,
325 325 'user_expressions' : dict,
326 326
327 327 # The kernel will often transform the input provided to it. If the
328 328 # '---->' transform had been applied, this is filled, otherwise it's the
329 329 # empty string. So transformations like magics don't appear here, only
330 330 # autocall ones.
331 331 'transformed_code' : str,
332 332 }
333 333
334 334 .. admonition:: Execution payloads
335 335
336 336 The notion of an 'execution payload' is different from a return value of a
337 337 given set of code, which normally is just displayed on the pyout stream
338 338 through the PUB socket. The idea of a payload is to allow special types of
339 339 code, typically magics, to populate a data container in the IPython kernel
340 340 that will be shipped back to the caller via this channel. The kernel will
341 341 have an API for this, probably something along the lines of::
342 342
343 343 ip.exec_payload_add(key, value)
344 344
345 345 though this API is still in the design stages. The data returned in this
346 346 payload will allow frontends to present special views of what just happened.
347 347
348 348
349 349 When status is 'error', the following extra fields are present::
350 350
351 351 {
352 352 'exc_name' : str, # Exception name, as a string
353 353 'exc_value' : str, # Exception value, as a string
354 354
355 355 # The traceback will contain a list of frames, represented each as a
356 356 # string. For now we'll stick to the existing design of ultraTB, which
357 357 # controls exception level of detail statefully. But eventually we'll
358 358 # want to grow into a model where more information is collected and
359 359 # packed into the traceback object, with clients deciding how little or
360 360 # how much of it to unpack. But for now, let's start with a simple list
361 361 # of strings, since that requires only minimal changes to ultratb as
362 362 # written.
363 363 'traceback' : list,
364 364 }
365 365
366 366
367 367 When status is 'abort', there are for now no additional data fields. This
368 368 happens when the kernel was interrupted by a signal.
369 369
370 370 Kernel attribute access
371 371 -----------------------
372 372
373 373 .. warning::
374 374
375 375 This part of the messaging spec is not actually implemented in the kernel
376 376 yet.
377 377
378 378 While this protocol does not specify full RPC access to arbitrary methods of
379 379 the kernel object, the kernel does allow read (and in some cases write) access
380 380 to certain attributes.
381 381
382 382 The policy for which attributes can be read is: any attribute of the kernel, or
383 383 its sub-objects, that belongs to a :class:`Configurable` object and has been
384 384 declared at the class-level with Traits validation, is in principle accessible
385 385 as long as its name does not begin with a leading underscore. The attribute
386 386 itself will have metadata indicating whether it allows remote read and/or write
387 387 access. The message spec follows for attribute read and write requests.
388 388
389 389 Message type: ``getattr_request``::
390 390
391 391 content = {
392 392 # The (possibly dotted) name of the attribute
393 393 'name' : str,
394 394 }
395 395
396 396 When a ``getattr_request`` fails, there are two possible error types:
397 397
398 398 - AttributeError: this type of error was raised when trying to access the
399 399 given name by the kernel itself. This means that the attribute likely
400 400 doesn't exist.
401 401
402 402 - AccessError: the attribute exists but its value is not readable remotely.
403 403
404 404
405 405 Message type: ``getattr_reply``::
406 406
407 407 content = {
408 408 # One of ['ok', 'AttributeError', 'AccessError'].
409 409 'status' : str,
410 410 # If status is 'ok', a JSON object.
411 411 'value' : object,
412 412 }
413 413
414 414 Message type: ``setattr_request``::
415 415
416 416 content = {
417 417 # The (possibly dotted) name of the attribute
418 418 'name' : str,
419 419
420 420 # A JSON-encoded object, that will be validated by the Traits
421 421 # information in the kernel
422 422 'value' : object,
423 423 }
424 424
425 425 When a ``setattr_request`` fails, there are also two possible error types with
426 426 similar meanings as those of the ``getattr_request`` case, but for writing.
427 427
428 428 Message type: ``setattr_reply``::
429 429
430 430 content = {
431 431 # One of ['ok', 'AttributeError', 'AccessError'].
432 432 'status' : str,
433 433 }
434 434
435 435
436 436
437 437 Object information
438 438 ------------------
439 439
440 440 One of IPython's most used capabilities is the introspection of Python objects
441 441 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
442 442 (which in reality are shorthands for the ``%pinfo`` magic). This is used often
443 443 enough that it warrants an explicit message type, especially because frontends
444 444 may want to get object information in response to user keystrokes (like Tab or
445 445 F1) besides from the user explicitly typing code like ``x??``.
446 446
447 447 Message type: ``object_info_request``::
448 448
449 449 content = {
450 450 # The (possibly dotted) name of the object to be searched in all
451 451 # relevant namespaces
452 452 'name' : str,
453 453
454 454 # The level of detail desired. The default (0) is equivalent to typing
455 455 # 'x?' at the prompt, 1 is equivalent to 'x??'.
456 456 'detail_level' : int,
457 457 }
458 458
459 459 The returned information will be a dictionary with keys very similar to the
460 460 field names that IPython prints at the terminal.
461 461
462 462 Message type: ``object_info_reply``::
463 463
464 464 content = {
465 465 # The name the object was requested under
466 466 'name' : str,
467 467
468 468 # Boolean flag indicating whether the named object was found or not. If
469 469 # it's false, all other fields will be empty.
470 470 'found' : bool,
471 471
472 472 # Flags for magics and system aliases
473 473 'ismagic' : bool,
474 474 'isalias' : bool,
475 475
476 476 # The name of the namespace where the object was found ('builtin',
477 477 # 'magics', 'alias', 'interactive', etc.)
478 478 'namespace' : str,
479 479
480 480 # The type name will be type.__name__ for normal Python objects, but it
481 481 # can also be a string like 'Magic function' or 'System alias'
482 482 'type_name' : str,
483 483
484 484 'string_form' : str,
485 485
486 486 # For objects with a __class__ attribute this will be set
487 487 'base_class' : str,
488 488
489 489 # For objects with a __len__ attribute this will be set
490 490 'length' : int,
491 491
492 492 # If the object is a function, class or method whose file we can find,
493 493 # we give its full path
494 494 'file' : str,
495 495
496 496 # For pure Python callable objects, we can reconstruct the object
497 497 # definition line which provides its call signature. For convenience this
498 498 # is returned as a single 'definition' field, but below the raw parts that
499 499 # compose it are also returned as the argspec field.
500 500 'definition' : str,
501 501
502 502 # The individual parts that together form the definition string. Clients
503 503 # with rich display capabilities may use this to provide a richer and more
504 504 # precise representation of the definition line (e.g. by highlighting
505 505 # arguments based on the user's cursor position). For non-callable
506 506 # objects, this field is empty.
507 507 'argspec' : { # The names of all the arguments
508 508 args : list,
509 509 # The name of the varargs (*args), if any
510 510 varargs : str,
511 511 # The name of the varkw (**kw), if any
512 512 varkw : str,
513 513 # The values (as strings) of all default arguments. Note
514 514 # that these must be matched *in reverse* with the 'args'
515 515 # list above, since the first positional args have no default
516 516 # value at all.
517 517 defaults : list,
518 518 },
519 519
520 520 # For instances, provide the constructor signature (the definition of
521 521 # the __init__ method):
522 522 'init_definition' : str,
523 523
524 524 # Docstrings: for any object (function, method, module, package) with a
525 525 # docstring, we show it. But in addition, we may provide additional
526 526 # docstrings. For example, for instances we will show the constructor
527 527 # and class docstrings as well, if available.
528 528 'docstring' : str,
529 529
530 530 # For instances, provide the constructor and class docstrings
531 531 'init_docstring' : str,
532 532 'class_docstring' : str,
533 533
534 534 # If it's a callable object whose call method has a separate docstring and
535 535 # definition line:
536 536 'call_def' : str,
537 537 'call_docstring' : str,
538 538
539 539 # If detail_level was 1, we also try to find the source code that
540 540 # defines the object, if possible. The string 'None' will indicate
541 541 # that no source was found.
542 542 'source' : str,
543 543 }
544 544 '
545 545
546 546 Complete
547 547 --------
548 548
549 549 Message type: ``complete_request``::
550 550
551 551 content = {
552 552 # The text to be completed, such as 'a.is'
553 553 'text' : str,
554 554
555 555 # The full line, such as 'print a.is'. This allows completers to
556 556 # make decisions that may require information about more than just the
557 557 # current word.
558 558 'line' : str,
559 559
560 560 # The entire block of text where the line is. This may be useful in the
561 561 # case of multiline completions where more context may be needed. Note: if
562 562 # in practice this field proves unnecessary, remove it to lighten the
563 563 # messages.
564 564
565 565 'block' : str,
566 566
567 567 # The position of the cursor where the user hit 'TAB' on the line.
568 568 'cursor_pos' : int,
569 569 }
570 570
571 571 Message type: ``complete_reply``::
572 572
573 573 content = {
574 574 # The list of all matches to the completion request, such as
575 575 # ['a.isalnum', 'a.isalpha'] for the above example.
576 576 'matches' : list
577 577 }
578 578
579 579
580 580 History
581 581 -------
582 582
583 583 For clients to explicitly request history from a kernel. The kernel has all
584 584 the actual execution history stored in a single location, so clients can
585 585 request it from the kernel when needed.
586 586
587 587 Message type: ``history_request``::
588 588
589 589 content = {
590 590
591 591 # If True, also return output history in the resulting dict.
592 592 'output' : bool,
593 593
594 594 # If True, return the raw input history, else the transformed input.
595 595 'raw' : bool,
596 596
597 597 # This parameter can be one of: A number, a pair of numbers, None
598 598 # If not given, last 40 are returned.
599 599 # - number n: return the last n entries.
600 600 # - pair n1, n2: return entries in the range(n1, n2).
601 601 # - None: return all history
602 602 'index' : n or (n1, n2) or None,
603 603 }
604 604
605 605 Message type: ``history_reply``::
606 606
607 607 content = {
608 608 # A dict with prompt numbers as keys and either (input, output) or input
609 609 # as the value depending on whether output was True or False,
610 610 # respectively.
611 611 'history' : dict,
612 612 }
613 613
614 614
615 615 Connect
616 616 -------
617 617
618 618 When a client connects to the request/reply socket of the kernel, it can issue
619 619 a connect request to get basic information about the kernel, such as the ports
620 620 the other ZeroMQ sockets are listening on. This allows clients to only have
621 621 to know about a single port (the XREQ/XREP channel) to connect to a kernel.
622 622
623 623 Message type: ``connect_request``::
624 624
625 625 content = {
626 626 }
627 627
628 628 Message type: ``connect_reply``::
629 629
630 630 content = {
631 631 'xrep_port' : int # The port the XREP socket is listening on.
632 632 'pub_port' : int # The port the PUB socket is listening on.
633 633 'req_port' : int # The port the REQ socket is listening on.
634 634 'hb_port' : int # The port the heartbeat socket is listening on.
635 635 }
636 636
637 637
638 638
639 639 Kernel shutdown
640 640 ---------------
641 641
642 642 The clients can request the kernel to shut itself down; this is used in
643 643 multiple cases:
644 644
645 645 - when the user chooses to close the client application via a menu or window
646 646 control.
647 647 - when the user types 'exit' or 'quit' (or their uppercase magic equivalents).
648 648 - when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the
649 649 IPythonQt client) to force a kernel restart to get a clean kernel without
650 650 losing client-side state like history or inlined figures.
651 651
652 652 The client sends a shutdown request to the kernel, and once it receives the
653 653 reply message (which is otherwise empty), it can assume that the kernel has
654 654 completed shutdown safely.
655 655
656 656 Upon their own shutdown, client applications will typically execute a last
657 657 minute sanity check and forcefully terminate any kernel that is still alive, to
658 658 avoid leaving stray processes in the user's machine.
659 659
660 660 For both shutdown request and reply, there is no actual content that needs to
661 661 be sent, so the content dict is empty.
662 662
663 663 Message type: ``shutdown_request``::
664 664
665 665 content = {
666 666 'restart' : bool # whether the shutdown is final, or precedes a restart
667 667 }
668 668
669 669 Message type: ``shutdown_reply``::
670 670
671 671 content = {
672 672 'restart' : bool # whether the shutdown is final, or precedes a restart
673 673 }
674 674
675 675 .. Note::
676 676
677 677 When the clients detect a dead kernel thanks to inactivity on the heartbeat
678 678 socket, they simply send a forceful process termination signal, since a dead
679 679 process is unlikely to respond in any useful way to messages.
680 680
681 681
682 682 Messages on the PUB/SUB socket
683 683 ==============================
684 684
685 685 Streams (stdout, stderr, etc)
686 686 ------------------------------
687 687
688 688 Message type: ``stream``::
689 689
690 690 content = {
691 691 # The name of the stream is one of 'stdin', 'stdout', 'stderr'
692 692 'name' : str,
693 693
694 694 # The data is an arbitrary string to be written to that stream
695 695 'data' : str,
696 696 }
697 697
698 698 When a kernel receives a raw_input call, it should also broadcast it on the pub
699 699 socket with the names 'stdin' and 'stdin_reply'. This will allow other clients
700 700 to monitor/display kernel interactions and possibly replay them to their user
701 701 or otherwise expose them.
702 702
703 703 Python inputs
704 704 -------------
705 705
706 706 These messages are the re-broadcast of the ``execute_request``.
707 707
708 708 Message type: ``pyin``::
709 709
710 710 content = {
711 711 # Source code to be executed, one or more lines
712 712 'code' : str
713 713 }
714 714
715 715 Python outputs
716 716 --------------
717 717
718 718 When Python produces output from code that has been compiled in with the
719 719 'single' flag to :func:`compile`, any expression that produces a value (such as
720 720 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
721 721 this value whatever it wants. The default behavior of ``sys.displayhook`` in
722 722 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
723 723 the value as long as it is not ``None`` (which isn't printed at all). In our
724 724 case, the kernel instantiates as ``sys.displayhook`` an object which has
725 725 similar behavior, but which instead of printing to stdout, broadcasts these
726 726 values as ``pyout`` messages for clients to display appropriately.
727 727
728 IPython's displayhook can handle multiple simultaneous formats depending on its
729 configuration. The default pretty-printed repr text is always given with the
730 ``data`` entry in this message. Any other formats are provided in the
731 ``extra_formats`` list. Frontends are free to display any or all of these
732 according to its capabilities. ``extra_formats`` list contains 3-tuples of an ID
733 string, a type string, and the data. The ID is unique to the formatter
734 implementation that created the data. Frontends will typically ignore the ID
735 unless if it has requested a particular formatter. The type string tells the
736 frontend how to interpret the data. It is often, but not always a MIME type.
737 Frontends should ignore types that it does not understand. The data itself is
738 any JSON object and depends on the format. It is often, but not always a string.
739
728 740 Message type: ``pyout``::
729 741
730 742 content = {
731 # The data is typically the repr() of the object.
732 'data' : str,
743 # The data is typically the repr() of the object. It should be displayed
744 # as monospaced text.
745 'data' : str,
733 746
734 # The counter for this execution is also provided so that clients can
735 # display it, since IPython automatically creates variables called _N (for
736 # prompt N).
737 'execution_count' : int,
747 # The counter for this execution is also provided so that clients can
748 # display it, since IPython automatically creates variables called _N
749 # (for prompt N).
750 'execution_count' : int,
751
752 # Any extra formats.
753 # The tuples are of the form (ID, type, data).
754 'extra_formats' : [
755 [str, str, object]
756 ]
738 757 }
739 758
740 759 Python errors
741 760 -------------
742 761
743 762 When an error occurs during code execution
744 763
745 764 Message type: ``pyerr``::
746 765
747 766 content = {
748 767 # Similar content to the execute_reply messages for the 'error' case,
749 768 # except the 'status' field is omitted.
750 769 }
751 770
752 771 Kernel status
753 772 -------------
754 773
755 774 This message type is used by frontends to monitor the status of the kernel.
756 775
757 776 Message type: ``status``::
758 777
759 778 content = {
760 779 # When the kernel starts to execute code, it will enter the 'busy'
761 780 # state and when it finishes, it will enter the 'idle' state.
762 781 execution_state : ('busy', 'idle')
763 782 }
764 783
765 784 Kernel crashes
766 785 --------------
767 786
768 787 When the kernel has an unexpected exception, caught by the last-resort
769 788 sys.excepthook, we should broadcast the crash handler's output before exiting.
770 789 This will allow clients to notice that a kernel died, inform the user and
771 790 propose further actions.
772 791
773 792 Message type: ``crash``::
774 793
775 794 content = {
776 795 # Similarly to the 'error' case for execute_reply messages, this will
777 796 # contain exc_name, exc_type and traceback fields.
778 797
779 798 # An additional field with supplementary information such as where to
780 799 # send the crash message
781 800 'info' : str,
782 801 }
783 802
784 803
785 804 Future ideas
786 805 ------------
787 806
788 807 Other potential message types, currently unimplemented, listed below as ideas.
789 808
790 809 Message type: ``file``::
791 810
792 811 content = {
793 812 'path' : 'cool.jpg',
794 813 'mimetype' : str,
795 814 'data' : str,
796 815 }
797 816
798 817
799 818 Messages on the REQ/REP socket
800 819 ==============================
801 820
802 821 This is a socket that goes in the opposite direction: from the kernel to a
803 822 *single* frontend, and its purpose is to allow ``raw_input`` and similar
804 823 operations that read from ``sys.stdin`` on the kernel to be fulfilled by the
805 824 client. For now we will keep these messages as simple as possible, since they
806 825 basically only mean to convey the ``raw_input(prompt)`` call.
807 826
808 827 Message type: ``input_request``::
809 828
810 829 content = { 'prompt' : str }
811 830
812 831 Message type: ``input_reply``::
813 832
814 833 content = { 'value' : str }
815 834
816 835 .. Note::
817 836
818 837 We do not explicitly try to forward the raw ``sys.stdin`` object, because in
819 838 practice the kernel should behave like an interactive program. When a
820 839 program is opened on the console, the keyboard effectively takes over the
821 840 ``stdin`` file descriptor, and it can't be used for raw reading anymore.
822 841 Since the IPython kernel effectively behaves like a console program (albeit
823 842 one whose "keyboard" is actually living in a separate process and
824 843 transported over the zmq connection), raw ``stdin`` isn't expected to be
825 844 available.
826 845
827 846
828 847 Heartbeat for kernels
829 848 =====================
830 849
831 850 Initially we had considered using messages like those above over ZMQ for a
832 851 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
833 852 alive at all, even if it may be busy executing user code). But this has the
834 853 problem that if the kernel is locked inside extension code, it wouldn't execute
835 854 the python heartbeat code. But it turns out that we can implement a basic
836 855 heartbeat with pure ZMQ, without using any Python messaging at all.
837 856
838 857 The monitor sends out a single zmq message (right now, it is a str of the
839 858 monitor's lifetime in seconds), and gets the same message right back, prefixed
840 859 with the zmq identity of the XREQ socket in the heartbeat process. This can be
841 860 a uuid, or even a full message, but there doesn't seem to be a need for packing
842 861 up a message when the sender and receiver are the exact same Python object.
843 862
844 863 The model is this::
845 864
846 865 monitor.send(str(self.lifetime)) # '1.2345678910'
847 866
848 867 and the monitor receives some number of messages of the form::
849 868
850 869 ['uuid-abcd-dead-beef', '1.2345678910']
851 870
852 871 where the first part is the zmq.IDENTITY of the heart's XREQ on the engine, and
853 872 the rest is the message sent by the monitor. No Python code ever has any
854 873 access to the message between the monitor's send, and the monitor's recv.
855 874
856 875
857 876 ToDo
858 877 ====
859 878
860 879 Missing things include:
861 880
862 881 * Important: finish thinking through the payload concept and API.
863 882
864 883 * Important: ensure that we have a good solution for magics like %edit. It's
865 884 likely that with the payload concept we can build a full solution, but not
866 885 100% clear yet.
867 886
868 887 * Finishing the details of the heartbeat protocol.
869 888
870 889 * Signal handling: specify what kind of information kernel should broadcast (or
871 890 not) when it receives signals.
872 891
873 892 .. include:: ../links.rst
General Comments 0
You need to be logged in to leave comments. Login now