##// END OF EJS Templates
Added functionality to %R and %octave magics so that -i first looks in local...
Guy Haskin Fernald -
Show More
@@ -1,3029 +1,3030 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Main IPython class."""
2 """Main IPython class."""
3
3
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 # Copyright (C) 2008-2011 The IPython Development Team
7 # Copyright (C) 2008-2011 The IPython Development Team
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import with_statement
17 from __future__ import with_statement
18 from __future__ import absolute_import
18 from __future__ import absolute_import
19 from __future__ import print_function
19 from __future__ import print_function
20
20
21 import __builtin__ as builtin_mod
21 import __builtin__ as builtin_mod
22 import __future__
22 import __future__
23 import abc
23 import abc
24 import ast
24 import ast
25 import atexit
25 import atexit
26 import os
26 import os
27 import re
27 import re
28 import runpy
28 import runpy
29 import sys
29 import sys
30 import tempfile
30 import tempfile
31 import types
31 import types
32
32
33 # We need to use nested to support python 2.6, once we move to >=2.7, we can
33 # We need to use nested to support python 2.6, once we move to >=2.7, we can
34 # use the with keyword's new builtin support for nested managers
34 # use the with keyword's new builtin support for nested managers
35 try:
35 try:
36 from contextlib import nested
36 from contextlib import nested
37 except:
37 except:
38 from IPython.utils.nested_context import nested
38 from IPython.utils.nested_context import nested
39
39
40 from IPython.config.configurable import SingletonConfigurable
40 from IPython.config.configurable import SingletonConfigurable
41 from IPython.core import debugger, oinspect
41 from IPython.core import debugger, oinspect
42 from IPython.core import history as ipcorehist
42 from IPython.core import history as ipcorehist
43 from IPython.core import magic
43 from IPython.core import magic
44 from IPython.core import page
44 from IPython.core import page
45 from IPython.core import prefilter
45 from IPython.core import prefilter
46 from IPython.core import shadowns
46 from IPython.core import shadowns
47 from IPython.core import ultratb
47 from IPython.core import ultratb
48 from IPython.core.alias import AliasManager, AliasError
48 from IPython.core.alias import AliasManager, AliasError
49 from IPython.core.autocall import ExitAutocall
49 from IPython.core.autocall import ExitAutocall
50 from IPython.core.builtin_trap import BuiltinTrap
50 from IPython.core.builtin_trap import BuiltinTrap
51 from IPython.core.compilerop import CachingCompiler
51 from IPython.core.compilerop import CachingCompiler
52 from IPython.core.display_trap import DisplayTrap
52 from IPython.core.display_trap import DisplayTrap
53 from IPython.core.displayhook import DisplayHook
53 from IPython.core.displayhook import DisplayHook
54 from IPython.core.displaypub import DisplayPublisher
54 from IPython.core.displaypub import DisplayPublisher
55 from IPython.core.error import UsageError
55 from IPython.core.error import UsageError
56 from IPython.core.extensions import ExtensionManager
56 from IPython.core.extensions import ExtensionManager
57 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
57 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
58 from IPython.core.formatters import DisplayFormatter
58 from IPython.core.formatters import DisplayFormatter
59 from IPython.core.history import HistoryManager
59 from IPython.core.history import HistoryManager
60 from IPython.core.inputsplitter import IPythonInputSplitter, ESC_MAGIC, ESC_MAGIC2
60 from IPython.core.inputsplitter import IPythonInputSplitter, ESC_MAGIC, ESC_MAGIC2
61 from IPython.core.logger import Logger
61 from IPython.core.logger import Logger
62 from IPython.core.macro import Macro
62 from IPython.core.macro import Macro
63 from IPython.core.payload import PayloadManager
63 from IPython.core.payload import PayloadManager
64 from IPython.core.plugin import PluginManager
64 from IPython.core.plugin import PluginManager
65 from IPython.core.prefilter import PrefilterManager
65 from IPython.core.prefilter import PrefilterManager
66 from IPython.core.profiledir import ProfileDir
66 from IPython.core.profiledir import ProfileDir
67 from IPython.core.pylabtools import pylab_activate
67 from IPython.core.pylabtools import pylab_activate
68 from IPython.core.prompts import PromptManager
68 from IPython.core.prompts import PromptManager
69 from IPython.lib.latextools import LaTeXTool
69 from IPython.lib.latextools import LaTeXTool
70 from IPython.utils import PyColorize
70 from IPython.utils import PyColorize
71 from IPython.utils import io
71 from IPython.utils import io
72 from IPython.utils import py3compat
72 from IPython.utils import py3compat
73 from IPython.utils import openpy
73 from IPython.utils import openpy
74 from IPython.utils.doctestreload import doctest_reload
74 from IPython.utils.doctestreload import doctest_reload
75 from IPython.utils.io import ask_yes_no
75 from IPython.utils.io import ask_yes_no
76 from IPython.utils.ipstruct import Struct
76 from IPython.utils.ipstruct import Struct
77 from IPython.utils.path import get_home_dir, get_ipython_dir, get_py_filename, unquote_filename
77 from IPython.utils.path import get_home_dir, get_ipython_dir, get_py_filename, unquote_filename
78 from IPython.utils.pickleshare import PickleShareDB
78 from IPython.utils.pickleshare import PickleShareDB
79 from IPython.utils.process import system, getoutput
79 from IPython.utils.process import system, getoutput
80 from IPython.utils.strdispatch import StrDispatch
80 from IPython.utils.strdispatch import StrDispatch
81 from IPython.utils.syspathcontext import prepended_to_syspath
81 from IPython.utils.syspathcontext import prepended_to_syspath
82 from IPython.utils.text import (format_screen, LSString, SList,
82 from IPython.utils.text import (format_screen, LSString, SList,
83 DollarFormatter)
83 DollarFormatter)
84 from IPython.utils.traitlets import (Integer, CBool, CaselessStrEnum, Enum,
84 from IPython.utils.traitlets import (Integer, CBool, CaselessStrEnum, Enum,
85 List, Unicode, Instance, Type)
85 List, Unicode, Instance, Type)
86 from IPython.utils.warn import warn, error
86 from IPython.utils.warn import warn, error
87 import IPython.core.hooks
87 import IPython.core.hooks
88
88
89 #-----------------------------------------------------------------------------
89 #-----------------------------------------------------------------------------
90 # Globals
90 # Globals
91 #-----------------------------------------------------------------------------
91 #-----------------------------------------------------------------------------
92
92
93 # compiled regexps for autoindent management
93 # compiled regexps for autoindent management
94 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
94 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
95
95
96 #-----------------------------------------------------------------------------
96 #-----------------------------------------------------------------------------
97 # Utilities
97 # Utilities
98 #-----------------------------------------------------------------------------
98 #-----------------------------------------------------------------------------
99
99
100 def softspace(file, newvalue):
100 def softspace(file, newvalue):
101 """Copied from code.py, to remove the dependency"""
101 """Copied from code.py, to remove the dependency"""
102
102
103 oldvalue = 0
103 oldvalue = 0
104 try:
104 try:
105 oldvalue = file.softspace
105 oldvalue = file.softspace
106 except AttributeError:
106 except AttributeError:
107 pass
107 pass
108 try:
108 try:
109 file.softspace = newvalue
109 file.softspace = newvalue
110 except (AttributeError, TypeError):
110 except (AttributeError, TypeError):
111 # "attribute-less object" or "read-only attributes"
111 # "attribute-less object" or "read-only attributes"
112 pass
112 pass
113 return oldvalue
113 return oldvalue
114
114
115
115
116 def no_op(*a, **kw): pass
116 def no_op(*a, **kw): pass
117
117
118 class NoOpContext(object):
118 class NoOpContext(object):
119 def __enter__(self): pass
119 def __enter__(self): pass
120 def __exit__(self, type, value, traceback): pass
120 def __exit__(self, type, value, traceback): pass
121 no_op_context = NoOpContext()
121 no_op_context = NoOpContext()
122
122
123 class SpaceInInput(Exception): pass
123 class SpaceInInput(Exception): pass
124
124
125 class Bunch: pass
125 class Bunch: pass
126
126
127
127
128 def get_default_colors():
128 def get_default_colors():
129 if sys.platform=='darwin':
129 if sys.platform=='darwin':
130 return "LightBG"
130 return "LightBG"
131 elif os.name=='nt':
131 elif os.name=='nt':
132 return 'Linux'
132 return 'Linux'
133 else:
133 else:
134 return 'Linux'
134 return 'Linux'
135
135
136
136
137 class SeparateUnicode(Unicode):
137 class SeparateUnicode(Unicode):
138 """A Unicode subclass to validate separate_in, separate_out, etc.
138 """A Unicode subclass to validate separate_in, separate_out, etc.
139
139
140 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
140 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
141 """
141 """
142
142
143 def validate(self, obj, value):
143 def validate(self, obj, value):
144 if value == '0': value = ''
144 if value == '0': value = ''
145 value = value.replace('\\n','\n')
145 value = value.replace('\\n','\n')
146 return super(SeparateUnicode, self).validate(obj, value)
146 return super(SeparateUnicode, self).validate(obj, value)
147
147
148
148
149 class ReadlineNoRecord(object):
149 class ReadlineNoRecord(object):
150 """Context manager to execute some code, then reload readline history
150 """Context manager to execute some code, then reload readline history
151 so that interactive input to the code doesn't appear when pressing up."""
151 so that interactive input to the code doesn't appear when pressing up."""
152 def __init__(self, shell):
152 def __init__(self, shell):
153 self.shell = shell
153 self.shell = shell
154 self._nested_level = 0
154 self._nested_level = 0
155
155
156 def __enter__(self):
156 def __enter__(self):
157 if self._nested_level == 0:
157 if self._nested_level == 0:
158 try:
158 try:
159 self.orig_length = self.current_length()
159 self.orig_length = self.current_length()
160 self.readline_tail = self.get_readline_tail()
160 self.readline_tail = self.get_readline_tail()
161 except (AttributeError, IndexError): # Can fail with pyreadline
161 except (AttributeError, IndexError): # Can fail with pyreadline
162 self.orig_length, self.readline_tail = 999999, []
162 self.orig_length, self.readline_tail = 999999, []
163 self._nested_level += 1
163 self._nested_level += 1
164
164
165 def __exit__(self, type, value, traceback):
165 def __exit__(self, type, value, traceback):
166 self._nested_level -= 1
166 self._nested_level -= 1
167 if self._nested_level == 0:
167 if self._nested_level == 0:
168 # Try clipping the end if it's got longer
168 # Try clipping the end if it's got longer
169 try:
169 try:
170 e = self.current_length() - self.orig_length
170 e = self.current_length() - self.orig_length
171 if e > 0:
171 if e > 0:
172 for _ in range(e):
172 for _ in range(e):
173 self.shell.readline.remove_history_item(self.orig_length)
173 self.shell.readline.remove_history_item(self.orig_length)
174
174
175 # If it still doesn't match, just reload readline history.
175 # If it still doesn't match, just reload readline history.
176 if self.current_length() != self.orig_length \
176 if self.current_length() != self.orig_length \
177 or self.get_readline_tail() != self.readline_tail:
177 or self.get_readline_tail() != self.readline_tail:
178 self.shell.refill_readline_hist()
178 self.shell.refill_readline_hist()
179 except (AttributeError, IndexError):
179 except (AttributeError, IndexError):
180 pass
180 pass
181 # Returning False will cause exceptions to propagate
181 # Returning False will cause exceptions to propagate
182 return False
182 return False
183
183
184 def current_length(self):
184 def current_length(self):
185 return self.shell.readline.get_current_history_length()
185 return self.shell.readline.get_current_history_length()
186
186
187 def get_readline_tail(self, n=10):
187 def get_readline_tail(self, n=10):
188 """Get the last n items in readline history."""
188 """Get the last n items in readline history."""
189 end = self.shell.readline.get_current_history_length() + 1
189 end = self.shell.readline.get_current_history_length() + 1
190 start = max(end-n, 1)
190 start = max(end-n, 1)
191 ghi = self.shell.readline.get_history_item
191 ghi = self.shell.readline.get_history_item
192 return [ghi(x) for x in range(start, end)]
192 return [ghi(x) for x in range(start, end)]
193
193
194 #-----------------------------------------------------------------------------
194 #-----------------------------------------------------------------------------
195 # Main IPython class
195 # Main IPython class
196 #-----------------------------------------------------------------------------
196 #-----------------------------------------------------------------------------
197
197
198 class InteractiveShell(SingletonConfigurable):
198 class InteractiveShell(SingletonConfigurable):
199 """An enhanced, interactive shell for Python."""
199 """An enhanced, interactive shell for Python."""
200
200
201 _instance = None
201 _instance = None
202
202
203 autocall = Enum((0,1,2), default_value=0, config=True, help=
203 autocall = Enum((0,1,2), default_value=0, config=True, help=
204 """
204 """
205 Make IPython automatically call any callable object even if you didn't
205 Make IPython automatically call any callable object even if you didn't
206 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
206 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
207 automatically. The value can be '0' to disable the feature, '1' for
207 automatically. The value can be '0' to disable the feature, '1' for
208 'smart' autocall, where it is not applied if there are no more
208 'smart' autocall, where it is not applied if there are no more
209 arguments on the line, and '2' for 'full' autocall, where all callable
209 arguments on the line, and '2' for 'full' autocall, where all callable
210 objects are automatically called (even if no arguments are present).
210 objects are automatically called (even if no arguments are present).
211 """
211 """
212 )
212 )
213 # TODO: remove all autoindent logic and put into frontends.
213 # TODO: remove all autoindent logic and put into frontends.
214 # We can't do this yet because even runlines uses the autoindent.
214 # We can't do this yet because even runlines uses the autoindent.
215 autoindent = CBool(True, config=True, help=
215 autoindent = CBool(True, config=True, help=
216 """
216 """
217 Autoindent IPython code entered interactively.
217 Autoindent IPython code entered interactively.
218 """
218 """
219 )
219 )
220 automagic = CBool(True, config=True, help=
220 automagic = CBool(True, config=True, help=
221 """
221 """
222 Enable magic commands to be called without the leading %.
222 Enable magic commands to be called without the leading %.
223 """
223 """
224 )
224 )
225 cache_size = Integer(1000, config=True, help=
225 cache_size = Integer(1000, config=True, help=
226 """
226 """
227 Set the size of the output cache. The default is 1000, you can
227 Set the size of the output cache. The default is 1000, you can
228 change it permanently in your config file. Setting it to 0 completely
228 change it permanently in your config file. Setting it to 0 completely
229 disables the caching system, and the minimum value accepted is 20 (if
229 disables the caching system, and the minimum value accepted is 20 (if
230 you provide a value less than 20, it is reset to 0 and a warning is
230 you provide a value less than 20, it is reset to 0 and a warning is
231 issued). This limit is defined because otherwise you'll spend more
231 issued). This limit is defined because otherwise you'll spend more
232 time re-flushing a too small cache than working
232 time re-flushing a too small cache than working
233 """
233 """
234 )
234 )
235 color_info = CBool(True, config=True, help=
235 color_info = CBool(True, config=True, help=
236 """
236 """
237 Use colors for displaying information about objects. Because this
237 Use colors for displaying information about objects. Because this
238 information is passed through a pager (like 'less'), and some pagers
238 information is passed through a pager (like 'less'), and some pagers
239 get confused with color codes, this capability can be turned off.
239 get confused with color codes, this capability can be turned off.
240 """
240 """
241 )
241 )
242 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
242 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
243 default_value=get_default_colors(), config=True,
243 default_value=get_default_colors(), config=True,
244 help="Set the color scheme (NoColor, Linux, or LightBG)."
244 help="Set the color scheme (NoColor, Linux, or LightBG)."
245 )
245 )
246 colors_force = CBool(False, help=
246 colors_force = CBool(False, help=
247 """
247 """
248 Force use of ANSI color codes, regardless of OS and readline
248 Force use of ANSI color codes, regardless of OS and readline
249 availability.
249 availability.
250 """
250 """
251 # FIXME: This is essentially a hack to allow ZMQShell to show colors
251 # FIXME: This is essentially a hack to allow ZMQShell to show colors
252 # without readline on Win32. When the ZMQ formatting system is
252 # without readline on Win32. When the ZMQ formatting system is
253 # refactored, this should be removed.
253 # refactored, this should be removed.
254 )
254 )
255 debug = CBool(False, config=True)
255 debug = CBool(False, config=True)
256 deep_reload = CBool(False, config=True, help=
256 deep_reload = CBool(False, config=True, help=
257 """
257 """
258 Enable deep (recursive) reloading by default. IPython can use the
258 Enable deep (recursive) reloading by default. IPython can use the
259 deep_reload module which reloads changes in modules recursively (it
259 deep_reload module which reloads changes in modules recursively (it
260 replaces the reload() function, so you don't need to change anything to
260 replaces the reload() function, so you don't need to change anything to
261 use it). deep_reload() forces a full reload of modules whose code may
261 use it). deep_reload() forces a full reload of modules whose code may
262 have changed, which the default reload() function does not. When
262 have changed, which the default reload() function does not. When
263 deep_reload is off, IPython will use the normal reload(), but
263 deep_reload is off, IPython will use the normal reload(), but
264 deep_reload will still be available as dreload().
264 deep_reload will still be available as dreload().
265 """
265 """
266 )
266 )
267 disable_failing_post_execute = CBool(False, config=True,
267 disable_failing_post_execute = CBool(False, config=True,
268 help="Don't call post-execute functions that have failed in the past."
268 help="Don't call post-execute functions that have failed in the past."
269 )
269 )
270 display_formatter = Instance(DisplayFormatter)
270 display_formatter = Instance(DisplayFormatter)
271 displayhook_class = Type(DisplayHook)
271 displayhook_class = Type(DisplayHook)
272 display_pub_class = Type(DisplayPublisher)
272 display_pub_class = Type(DisplayPublisher)
273 data_pub_class = None
273 data_pub_class = None
274
274
275 exit_now = CBool(False)
275 exit_now = CBool(False)
276 exiter = Instance(ExitAutocall)
276 exiter = Instance(ExitAutocall)
277 def _exiter_default(self):
277 def _exiter_default(self):
278 return ExitAutocall(self)
278 return ExitAutocall(self)
279 # Monotonically increasing execution counter
279 # Monotonically increasing execution counter
280 execution_count = Integer(1)
280 execution_count = Integer(1)
281 filename = Unicode("<ipython console>")
281 filename = Unicode("<ipython console>")
282 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
282 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
283
283
284 # Input splitter, to split entire cells of input into either individual
284 # Input splitter, to split entire cells of input into either individual
285 # interactive statements or whole blocks.
285 # interactive statements or whole blocks.
286 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
286 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
287 (), {})
287 (), {})
288 logstart = CBool(False, config=True, help=
288 logstart = CBool(False, config=True, help=
289 """
289 """
290 Start logging to the default log file.
290 Start logging to the default log file.
291 """
291 """
292 )
292 )
293 logfile = Unicode('', config=True, help=
293 logfile = Unicode('', config=True, help=
294 """
294 """
295 The name of the logfile to use.
295 The name of the logfile to use.
296 """
296 """
297 )
297 )
298 logappend = Unicode('', config=True, help=
298 logappend = Unicode('', config=True, help=
299 """
299 """
300 Start logging to the given file in append mode.
300 Start logging to the given file in append mode.
301 """
301 """
302 )
302 )
303 object_info_string_level = Enum((0,1,2), default_value=0,
303 object_info_string_level = Enum((0,1,2), default_value=0,
304 config=True)
304 config=True)
305 pdb = CBool(False, config=True, help=
305 pdb = CBool(False, config=True, help=
306 """
306 """
307 Automatically call the pdb debugger after every exception.
307 Automatically call the pdb debugger after every exception.
308 """
308 """
309 )
309 )
310 multiline_history = CBool(sys.platform != 'win32', config=True,
310 multiline_history = CBool(sys.platform != 'win32', config=True,
311 help="Save multi-line entries as one entry in readline history"
311 help="Save multi-line entries as one entry in readline history"
312 )
312 )
313
313
314 # deprecated prompt traits:
314 # deprecated prompt traits:
315
315
316 prompt_in1 = Unicode('In [\\#]: ', config=True,
316 prompt_in1 = Unicode('In [\\#]: ', config=True,
317 help="Deprecated, use PromptManager.in_template")
317 help="Deprecated, use PromptManager.in_template")
318 prompt_in2 = Unicode(' .\\D.: ', config=True,
318 prompt_in2 = Unicode(' .\\D.: ', config=True,
319 help="Deprecated, use PromptManager.in2_template")
319 help="Deprecated, use PromptManager.in2_template")
320 prompt_out = Unicode('Out[\\#]: ', config=True,
320 prompt_out = Unicode('Out[\\#]: ', config=True,
321 help="Deprecated, use PromptManager.out_template")
321 help="Deprecated, use PromptManager.out_template")
322 prompts_pad_left = CBool(True, config=True,
322 prompts_pad_left = CBool(True, config=True,
323 help="Deprecated, use PromptManager.justify")
323 help="Deprecated, use PromptManager.justify")
324
324
325 def _prompt_trait_changed(self, name, old, new):
325 def _prompt_trait_changed(self, name, old, new):
326 table = {
326 table = {
327 'prompt_in1' : 'in_template',
327 'prompt_in1' : 'in_template',
328 'prompt_in2' : 'in2_template',
328 'prompt_in2' : 'in2_template',
329 'prompt_out' : 'out_template',
329 'prompt_out' : 'out_template',
330 'prompts_pad_left' : 'justify',
330 'prompts_pad_left' : 'justify',
331 }
331 }
332 warn("InteractiveShell.{name} is deprecated, use PromptManager.{newname}\n".format(
332 warn("InteractiveShell.{name} is deprecated, use PromptManager.{newname}\n".format(
333 name=name, newname=table[name])
333 name=name, newname=table[name])
334 )
334 )
335 # protect against weird cases where self.config may not exist:
335 # protect against weird cases where self.config may not exist:
336 if self.config is not None:
336 if self.config is not None:
337 # propagate to corresponding PromptManager trait
337 # propagate to corresponding PromptManager trait
338 setattr(self.config.PromptManager, table[name], new)
338 setattr(self.config.PromptManager, table[name], new)
339
339
340 _prompt_in1_changed = _prompt_trait_changed
340 _prompt_in1_changed = _prompt_trait_changed
341 _prompt_in2_changed = _prompt_trait_changed
341 _prompt_in2_changed = _prompt_trait_changed
342 _prompt_out_changed = _prompt_trait_changed
342 _prompt_out_changed = _prompt_trait_changed
343 _prompt_pad_left_changed = _prompt_trait_changed
343 _prompt_pad_left_changed = _prompt_trait_changed
344
344
345 show_rewritten_input = CBool(True, config=True,
345 show_rewritten_input = CBool(True, config=True,
346 help="Show rewritten input, e.g. for autocall."
346 help="Show rewritten input, e.g. for autocall."
347 )
347 )
348
348
349 quiet = CBool(False, config=True)
349 quiet = CBool(False, config=True)
350
350
351 history_length = Integer(10000, config=True)
351 history_length = Integer(10000, config=True)
352
352
353 # The readline stuff will eventually be moved to the terminal subclass
353 # The readline stuff will eventually be moved to the terminal subclass
354 # but for now, we can't do that as readline is welded in everywhere.
354 # but for now, we can't do that as readline is welded in everywhere.
355 readline_use = CBool(True, config=True)
355 readline_use = CBool(True, config=True)
356 readline_remove_delims = Unicode('-/~', config=True)
356 readline_remove_delims = Unicode('-/~', config=True)
357 # don't use \M- bindings by default, because they
357 # don't use \M- bindings by default, because they
358 # conflict with 8-bit encodings. See gh-58,gh-88
358 # conflict with 8-bit encodings. See gh-58,gh-88
359 readline_parse_and_bind = List([
359 readline_parse_and_bind = List([
360 'tab: complete',
360 'tab: complete',
361 '"\C-l": clear-screen',
361 '"\C-l": clear-screen',
362 'set show-all-if-ambiguous on',
362 'set show-all-if-ambiguous on',
363 '"\C-o": tab-insert',
363 '"\C-o": tab-insert',
364 '"\C-r": reverse-search-history',
364 '"\C-r": reverse-search-history',
365 '"\C-s": forward-search-history',
365 '"\C-s": forward-search-history',
366 '"\C-p": history-search-backward',
366 '"\C-p": history-search-backward',
367 '"\C-n": history-search-forward',
367 '"\C-n": history-search-forward',
368 '"\e[A": history-search-backward',
368 '"\e[A": history-search-backward',
369 '"\e[B": history-search-forward',
369 '"\e[B": history-search-forward',
370 '"\C-k": kill-line',
370 '"\C-k": kill-line',
371 '"\C-u": unix-line-discard',
371 '"\C-u": unix-line-discard',
372 ], allow_none=False, config=True)
372 ], allow_none=False, config=True)
373
373
374 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none'],
374 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none'],
375 default_value='last_expr', config=True,
375 default_value='last_expr', config=True,
376 help="""
376 help="""
377 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
377 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
378 run interactively (displaying output from expressions).""")
378 run interactively (displaying output from expressions).""")
379
379
380 # TODO: this part of prompt management should be moved to the frontends.
380 # TODO: this part of prompt management should be moved to the frontends.
381 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
381 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
382 separate_in = SeparateUnicode('\n', config=True)
382 separate_in = SeparateUnicode('\n', config=True)
383 separate_out = SeparateUnicode('', config=True)
383 separate_out = SeparateUnicode('', config=True)
384 separate_out2 = SeparateUnicode('', config=True)
384 separate_out2 = SeparateUnicode('', config=True)
385 wildcards_case_sensitive = CBool(True, config=True)
385 wildcards_case_sensitive = CBool(True, config=True)
386 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
386 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
387 default_value='Context', config=True)
387 default_value='Context', config=True)
388
388
389 # Subcomponents of InteractiveShell
389 # Subcomponents of InteractiveShell
390 alias_manager = Instance('IPython.core.alias.AliasManager')
390 alias_manager = Instance('IPython.core.alias.AliasManager')
391 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
391 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
392 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
392 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
393 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
393 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
394 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
394 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
395 plugin_manager = Instance('IPython.core.plugin.PluginManager')
395 plugin_manager = Instance('IPython.core.plugin.PluginManager')
396 payload_manager = Instance('IPython.core.payload.PayloadManager')
396 payload_manager = Instance('IPython.core.payload.PayloadManager')
397 history_manager = Instance('IPython.core.history.HistoryManager')
397 history_manager = Instance('IPython.core.history.HistoryManager')
398 magics_manager = Instance('IPython.core.magic.MagicsManager')
398 magics_manager = Instance('IPython.core.magic.MagicsManager')
399
399
400 profile_dir = Instance('IPython.core.application.ProfileDir')
400 profile_dir = Instance('IPython.core.application.ProfileDir')
401 @property
401 @property
402 def profile(self):
402 def profile(self):
403 if self.profile_dir is not None:
403 if self.profile_dir is not None:
404 name = os.path.basename(self.profile_dir.location)
404 name = os.path.basename(self.profile_dir.location)
405 return name.replace('profile_','')
405 return name.replace('profile_','')
406
406
407
407
408 # Private interface
408 # Private interface
409 _post_execute = Instance(dict)
409 _post_execute = Instance(dict)
410
410
411 # Tracks any GUI loop loaded for pylab
411 # Tracks any GUI loop loaded for pylab
412 pylab_gui_select = None
412 pylab_gui_select = None
413
413
414 def __init__(self, config=None, ipython_dir=None, profile_dir=None,
414 def __init__(self, config=None, ipython_dir=None, profile_dir=None,
415 user_module=None, user_ns=None,
415 user_module=None, user_ns=None,
416 custom_exceptions=((), None)):
416 custom_exceptions=((), None)):
417
417
418 # This is where traits with a config_key argument are updated
418 # This is where traits with a config_key argument are updated
419 # from the values on config.
419 # from the values on config.
420 super(InteractiveShell, self).__init__(config=config)
420 super(InteractiveShell, self).__init__(config=config)
421 self.configurables = [self]
421 self.configurables = [self]
422
422
423 # These are relatively independent and stateless
423 # These are relatively independent and stateless
424 self.init_ipython_dir(ipython_dir)
424 self.init_ipython_dir(ipython_dir)
425 self.init_profile_dir(profile_dir)
425 self.init_profile_dir(profile_dir)
426 self.init_instance_attrs()
426 self.init_instance_attrs()
427 self.init_environment()
427 self.init_environment()
428
428
429 # Check if we're in a virtualenv, and set up sys.path.
429 # Check if we're in a virtualenv, and set up sys.path.
430 self.init_virtualenv()
430 self.init_virtualenv()
431
431
432 # Create namespaces (user_ns, user_global_ns, etc.)
432 # Create namespaces (user_ns, user_global_ns, etc.)
433 self.init_create_namespaces(user_module, user_ns)
433 self.init_create_namespaces(user_module, user_ns)
434 # This has to be done after init_create_namespaces because it uses
434 # This has to be done after init_create_namespaces because it uses
435 # something in self.user_ns, but before init_sys_modules, which
435 # something in self.user_ns, but before init_sys_modules, which
436 # is the first thing to modify sys.
436 # is the first thing to modify sys.
437 # TODO: When we override sys.stdout and sys.stderr before this class
437 # TODO: When we override sys.stdout and sys.stderr before this class
438 # is created, we are saving the overridden ones here. Not sure if this
438 # is created, we are saving the overridden ones here. Not sure if this
439 # is what we want to do.
439 # is what we want to do.
440 self.save_sys_module_state()
440 self.save_sys_module_state()
441 self.init_sys_modules()
441 self.init_sys_modules()
442
442
443 # While we're trying to have each part of the code directly access what
443 # While we're trying to have each part of the code directly access what
444 # it needs without keeping redundant references to objects, we have too
444 # it needs without keeping redundant references to objects, we have too
445 # much legacy code that expects ip.db to exist.
445 # much legacy code that expects ip.db to exist.
446 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
446 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
447
447
448 self.init_history()
448 self.init_history()
449 self.init_encoding()
449 self.init_encoding()
450 self.init_prefilter()
450 self.init_prefilter()
451
451
452 self.init_syntax_highlighting()
452 self.init_syntax_highlighting()
453 self.init_hooks()
453 self.init_hooks()
454 self.init_pushd_popd_magic()
454 self.init_pushd_popd_magic()
455 # self.init_traceback_handlers use to be here, but we moved it below
455 # self.init_traceback_handlers use to be here, but we moved it below
456 # because it and init_io have to come after init_readline.
456 # because it and init_io have to come after init_readline.
457 self.init_user_ns()
457 self.init_user_ns()
458 self.init_logger()
458 self.init_logger()
459 self.init_alias()
459 self.init_alias()
460 self.init_builtins()
460 self.init_builtins()
461
461
462 # The following was in post_config_initialization
462 # The following was in post_config_initialization
463 self.init_inspector()
463 self.init_inspector()
464 # init_readline() must come before init_io(), because init_io uses
464 # init_readline() must come before init_io(), because init_io uses
465 # readline related things.
465 # readline related things.
466 self.init_readline()
466 self.init_readline()
467 # We save this here in case user code replaces raw_input, but it needs
467 # We save this here in case user code replaces raw_input, but it needs
468 # to be after init_readline(), because PyPy's readline works by replacing
468 # to be after init_readline(), because PyPy's readline works by replacing
469 # raw_input.
469 # raw_input.
470 if py3compat.PY3:
470 if py3compat.PY3:
471 self.raw_input_original = input
471 self.raw_input_original = input
472 else:
472 else:
473 self.raw_input_original = raw_input
473 self.raw_input_original = raw_input
474 # init_completer must come after init_readline, because it needs to
474 # init_completer must come after init_readline, because it needs to
475 # know whether readline is present or not system-wide to configure the
475 # know whether readline is present or not system-wide to configure the
476 # completers, since the completion machinery can now operate
476 # completers, since the completion machinery can now operate
477 # independently of readline (e.g. over the network)
477 # independently of readline (e.g. over the network)
478 self.init_completer()
478 self.init_completer()
479 # TODO: init_io() needs to happen before init_traceback handlers
479 # TODO: init_io() needs to happen before init_traceback handlers
480 # because the traceback handlers hardcode the stdout/stderr streams.
480 # because the traceback handlers hardcode the stdout/stderr streams.
481 # This logic in in debugger.Pdb and should eventually be changed.
481 # This logic in in debugger.Pdb and should eventually be changed.
482 self.init_io()
482 self.init_io()
483 self.init_traceback_handlers(custom_exceptions)
483 self.init_traceback_handlers(custom_exceptions)
484 self.init_prompts()
484 self.init_prompts()
485 self.init_display_formatter()
485 self.init_display_formatter()
486 self.init_display_pub()
486 self.init_display_pub()
487 self.init_data_pub()
487 self.init_data_pub()
488 self.init_displayhook()
488 self.init_displayhook()
489 self.init_reload_doctest()
489 self.init_reload_doctest()
490 self.init_latextool()
490 self.init_latextool()
491 self.init_magics()
491 self.init_magics()
492 self.init_logstart()
492 self.init_logstart()
493 self.init_pdb()
493 self.init_pdb()
494 self.init_extension_manager()
494 self.init_extension_manager()
495 self.init_plugin_manager()
495 self.init_plugin_manager()
496 self.init_payload()
496 self.init_payload()
497 self.hooks.late_startup_hook()
497 self.hooks.late_startup_hook()
498 atexit.register(self.atexit_operations)
498 atexit.register(self.atexit_operations)
499
499
500 def get_ipython(self):
500 def get_ipython(self):
501 """Return the currently running IPython instance."""
501 """Return the currently running IPython instance."""
502 return self
502 return self
503
503
504 #-------------------------------------------------------------------------
504 #-------------------------------------------------------------------------
505 # Trait changed handlers
505 # Trait changed handlers
506 #-------------------------------------------------------------------------
506 #-------------------------------------------------------------------------
507
507
508 def _ipython_dir_changed(self, name, new):
508 def _ipython_dir_changed(self, name, new):
509 if not os.path.isdir(new):
509 if not os.path.isdir(new):
510 os.makedirs(new, mode = 0777)
510 os.makedirs(new, mode = 0777)
511
511
512 def set_autoindent(self,value=None):
512 def set_autoindent(self,value=None):
513 """Set the autoindent flag, checking for readline support.
513 """Set the autoindent flag, checking for readline support.
514
514
515 If called with no arguments, it acts as a toggle."""
515 If called with no arguments, it acts as a toggle."""
516
516
517 if value != 0 and not self.has_readline:
517 if value != 0 and not self.has_readline:
518 if os.name == 'posix':
518 if os.name == 'posix':
519 warn("The auto-indent feature requires the readline library")
519 warn("The auto-indent feature requires the readline library")
520 self.autoindent = 0
520 self.autoindent = 0
521 return
521 return
522 if value is None:
522 if value is None:
523 self.autoindent = not self.autoindent
523 self.autoindent = not self.autoindent
524 else:
524 else:
525 self.autoindent = value
525 self.autoindent = value
526
526
527 #-------------------------------------------------------------------------
527 #-------------------------------------------------------------------------
528 # init_* methods called by __init__
528 # init_* methods called by __init__
529 #-------------------------------------------------------------------------
529 #-------------------------------------------------------------------------
530
530
531 def init_ipython_dir(self, ipython_dir):
531 def init_ipython_dir(self, ipython_dir):
532 if ipython_dir is not None:
532 if ipython_dir is not None:
533 self.ipython_dir = ipython_dir
533 self.ipython_dir = ipython_dir
534 return
534 return
535
535
536 self.ipython_dir = get_ipython_dir()
536 self.ipython_dir = get_ipython_dir()
537
537
538 def init_profile_dir(self, profile_dir):
538 def init_profile_dir(self, profile_dir):
539 if profile_dir is not None:
539 if profile_dir is not None:
540 self.profile_dir = profile_dir
540 self.profile_dir = profile_dir
541 return
541 return
542 self.profile_dir =\
542 self.profile_dir =\
543 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
543 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
544
544
545 def init_instance_attrs(self):
545 def init_instance_attrs(self):
546 self.more = False
546 self.more = False
547
547
548 # command compiler
548 # command compiler
549 self.compile = CachingCompiler()
549 self.compile = CachingCompiler()
550
550
551 # Make an empty namespace, which extension writers can rely on both
551 # Make an empty namespace, which extension writers can rely on both
552 # existing and NEVER being used by ipython itself. This gives them a
552 # existing and NEVER being used by ipython itself. This gives them a
553 # convenient location for storing additional information and state
553 # convenient location for storing additional information and state
554 # their extensions may require, without fear of collisions with other
554 # their extensions may require, without fear of collisions with other
555 # ipython names that may develop later.
555 # ipython names that may develop later.
556 self.meta = Struct()
556 self.meta = Struct()
557
557
558 # Temporary files used for various purposes. Deleted at exit.
558 # Temporary files used for various purposes. Deleted at exit.
559 self.tempfiles = []
559 self.tempfiles = []
560
560
561 # Keep track of readline usage (later set by init_readline)
561 # Keep track of readline usage (later set by init_readline)
562 self.has_readline = False
562 self.has_readline = False
563
563
564 # keep track of where we started running (mainly for crash post-mortem)
564 # keep track of where we started running (mainly for crash post-mortem)
565 # This is not being used anywhere currently.
565 # This is not being used anywhere currently.
566 self.starting_dir = os.getcwdu()
566 self.starting_dir = os.getcwdu()
567
567
568 # Indentation management
568 # Indentation management
569 self.indent_current_nsp = 0
569 self.indent_current_nsp = 0
570
570
571 # Dict to track post-execution functions that have been registered
571 # Dict to track post-execution functions that have been registered
572 self._post_execute = {}
572 self._post_execute = {}
573
573
574 def init_environment(self):
574 def init_environment(self):
575 """Any changes we need to make to the user's environment."""
575 """Any changes we need to make to the user's environment."""
576 pass
576 pass
577
577
578 def init_encoding(self):
578 def init_encoding(self):
579 # Get system encoding at startup time. Certain terminals (like Emacs
579 # Get system encoding at startup time. Certain terminals (like Emacs
580 # under Win32 have it set to None, and we need to have a known valid
580 # under Win32 have it set to None, and we need to have a known valid
581 # encoding to use in the raw_input() method
581 # encoding to use in the raw_input() method
582 try:
582 try:
583 self.stdin_encoding = sys.stdin.encoding or 'ascii'
583 self.stdin_encoding = sys.stdin.encoding or 'ascii'
584 except AttributeError:
584 except AttributeError:
585 self.stdin_encoding = 'ascii'
585 self.stdin_encoding = 'ascii'
586
586
587 def init_syntax_highlighting(self):
587 def init_syntax_highlighting(self):
588 # Python source parser/formatter for syntax highlighting
588 # Python source parser/formatter for syntax highlighting
589 pyformat = PyColorize.Parser().format
589 pyformat = PyColorize.Parser().format
590 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
590 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
591
591
592 def init_pushd_popd_magic(self):
592 def init_pushd_popd_magic(self):
593 # for pushd/popd management
593 # for pushd/popd management
594 self.home_dir = get_home_dir()
594 self.home_dir = get_home_dir()
595
595
596 self.dir_stack = []
596 self.dir_stack = []
597
597
598 def init_logger(self):
598 def init_logger(self):
599 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
599 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
600 logmode='rotate')
600 logmode='rotate')
601
601
602 def init_logstart(self):
602 def init_logstart(self):
603 """Initialize logging in case it was requested at the command line.
603 """Initialize logging in case it was requested at the command line.
604 """
604 """
605 if self.logappend:
605 if self.logappend:
606 self.magic('logstart %s append' % self.logappend)
606 self.magic('logstart %s append' % self.logappend)
607 elif self.logfile:
607 elif self.logfile:
608 self.magic('logstart %s' % self.logfile)
608 self.magic('logstart %s' % self.logfile)
609 elif self.logstart:
609 elif self.logstart:
610 self.magic('logstart')
610 self.magic('logstart')
611
611
612 def init_builtins(self):
612 def init_builtins(self):
613 # A single, static flag that we set to True. Its presence indicates
613 # A single, static flag that we set to True. Its presence indicates
614 # that an IPython shell has been created, and we make no attempts at
614 # that an IPython shell has been created, and we make no attempts at
615 # removing on exit or representing the existence of more than one
615 # removing on exit or representing the existence of more than one
616 # IPython at a time.
616 # IPython at a time.
617 builtin_mod.__dict__['__IPYTHON__'] = True
617 builtin_mod.__dict__['__IPYTHON__'] = True
618
618
619 # In 0.11 we introduced '__IPYTHON__active' as an integer we'd try to
619 # In 0.11 we introduced '__IPYTHON__active' as an integer we'd try to
620 # manage on enter/exit, but with all our shells it's virtually
620 # manage on enter/exit, but with all our shells it's virtually
621 # impossible to get all the cases right. We're leaving the name in for
621 # impossible to get all the cases right. We're leaving the name in for
622 # those who adapted their codes to check for this flag, but will
622 # those who adapted their codes to check for this flag, but will
623 # eventually remove it after a few more releases.
623 # eventually remove it after a few more releases.
624 builtin_mod.__dict__['__IPYTHON__active'] = \
624 builtin_mod.__dict__['__IPYTHON__active'] = \
625 'Deprecated, check for __IPYTHON__'
625 'Deprecated, check for __IPYTHON__'
626
626
627 self.builtin_trap = BuiltinTrap(shell=self)
627 self.builtin_trap = BuiltinTrap(shell=self)
628
628
629 def init_inspector(self):
629 def init_inspector(self):
630 # Object inspector
630 # Object inspector
631 self.inspector = oinspect.Inspector(oinspect.InspectColors,
631 self.inspector = oinspect.Inspector(oinspect.InspectColors,
632 PyColorize.ANSICodeColors,
632 PyColorize.ANSICodeColors,
633 'NoColor',
633 'NoColor',
634 self.object_info_string_level)
634 self.object_info_string_level)
635
635
636 def init_io(self):
636 def init_io(self):
637 # This will just use sys.stdout and sys.stderr. If you want to
637 # This will just use sys.stdout and sys.stderr. If you want to
638 # override sys.stdout and sys.stderr themselves, you need to do that
638 # override sys.stdout and sys.stderr themselves, you need to do that
639 # *before* instantiating this class, because io holds onto
639 # *before* instantiating this class, because io holds onto
640 # references to the underlying streams.
640 # references to the underlying streams.
641 if sys.platform == 'win32' and self.has_readline:
641 if sys.platform == 'win32' and self.has_readline:
642 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
642 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
643 else:
643 else:
644 io.stdout = io.IOStream(sys.stdout)
644 io.stdout = io.IOStream(sys.stdout)
645 io.stderr = io.IOStream(sys.stderr)
645 io.stderr = io.IOStream(sys.stderr)
646
646
647 def init_prompts(self):
647 def init_prompts(self):
648 self.prompt_manager = PromptManager(shell=self, config=self.config)
648 self.prompt_manager = PromptManager(shell=self, config=self.config)
649 self.configurables.append(self.prompt_manager)
649 self.configurables.append(self.prompt_manager)
650 # Set system prompts, so that scripts can decide if they are running
650 # Set system prompts, so that scripts can decide if they are running
651 # interactively.
651 # interactively.
652 sys.ps1 = 'In : '
652 sys.ps1 = 'In : '
653 sys.ps2 = '...: '
653 sys.ps2 = '...: '
654 sys.ps3 = 'Out: '
654 sys.ps3 = 'Out: '
655
655
656 def init_display_formatter(self):
656 def init_display_formatter(self):
657 self.display_formatter = DisplayFormatter(config=self.config)
657 self.display_formatter = DisplayFormatter(config=self.config)
658 self.configurables.append(self.display_formatter)
658 self.configurables.append(self.display_formatter)
659
659
660 def init_display_pub(self):
660 def init_display_pub(self):
661 self.display_pub = self.display_pub_class(config=self.config)
661 self.display_pub = self.display_pub_class(config=self.config)
662 self.configurables.append(self.display_pub)
662 self.configurables.append(self.display_pub)
663
663
664 def init_data_pub(self):
664 def init_data_pub(self):
665 if not self.data_pub_class:
665 if not self.data_pub_class:
666 self.data_pub = None
666 self.data_pub = None
667 return
667 return
668 self.data_pub = self.data_pub_class(config=self.config)
668 self.data_pub = self.data_pub_class(config=self.config)
669 self.configurables.append(self.data_pub)
669 self.configurables.append(self.data_pub)
670
670
671 def init_displayhook(self):
671 def init_displayhook(self):
672 # Initialize displayhook, set in/out prompts and printing system
672 # Initialize displayhook, set in/out prompts and printing system
673 self.displayhook = self.displayhook_class(
673 self.displayhook = self.displayhook_class(
674 config=self.config,
674 config=self.config,
675 shell=self,
675 shell=self,
676 cache_size=self.cache_size,
676 cache_size=self.cache_size,
677 )
677 )
678 self.configurables.append(self.displayhook)
678 self.configurables.append(self.displayhook)
679 # This is a context manager that installs/revmoes the displayhook at
679 # This is a context manager that installs/revmoes the displayhook at
680 # the appropriate time.
680 # the appropriate time.
681 self.display_trap = DisplayTrap(hook=self.displayhook)
681 self.display_trap = DisplayTrap(hook=self.displayhook)
682
682
683 def init_reload_doctest(self):
683 def init_reload_doctest(self):
684 # Do a proper resetting of doctest, including the necessary displayhook
684 # Do a proper resetting of doctest, including the necessary displayhook
685 # monkeypatching
685 # monkeypatching
686 try:
686 try:
687 doctest_reload()
687 doctest_reload()
688 except ImportError:
688 except ImportError:
689 warn("doctest module does not exist.")
689 warn("doctest module does not exist.")
690
690
691 def init_latextool(self):
691 def init_latextool(self):
692 """Configure LaTeXTool."""
692 """Configure LaTeXTool."""
693 cfg = LaTeXTool.instance(config=self.config)
693 cfg = LaTeXTool.instance(config=self.config)
694 if cfg not in self.configurables:
694 if cfg not in self.configurables:
695 self.configurables.append(cfg)
695 self.configurables.append(cfg)
696
696
697 def init_virtualenv(self):
697 def init_virtualenv(self):
698 """Add a virtualenv to sys.path so the user can import modules from it.
698 """Add a virtualenv to sys.path so the user can import modules from it.
699 This isn't perfect: it doesn't use the Python interpreter with which the
699 This isn't perfect: it doesn't use the Python interpreter with which the
700 virtualenv was built, and it ignores the --no-site-packages option. A
700 virtualenv was built, and it ignores the --no-site-packages option. A
701 warning will appear suggesting the user installs IPython in the
701 warning will appear suggesting the user installs IPython in the
702 virtualenv, but for many cases, it probably works well enough.
702 virtualenv, but for many cases, it probably works well enough.
703
703
704 Adapted from code snippets online.
704 Adapted from code snippets online.
705
705
706 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
706 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
707 """
707 """
708 if 'VIRTUAL_ENV' not in os.environ:
708 if 'VIRTUAL_ENV' not in os.environ:
709 # Not in a virtualenv
709 # Not in a virtualenv
710 return
710 return
711
711
712 if sys.executable.startswith(os.environ['VIRTUAL_ENV']):
712 if sys.executable.startswith(os.environ['VIRTUAL_ENV']):
713 # Running properly in the virtualenv, don't need to do anything
713 # Running properly in the virtualenv, don't need to do anything
714 return
714 return
715
715
716 warn("Attempting to work in a virtualenv. If you encounter problems, please "
716 warn("Attempting to work in a virtualenv. If you encounter problems, please "
717 "install IPython inside the virtualenv.\n")
717 "install IPython inside the virtualenv.\n")
718 if sys.platform == "win32":
718 if sys.platform == "win32":
719 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
719 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
720 else:
720 else:
721 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
721 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
722 'python%d.%d' % sys.version_info[:2], 'site-packages')
722 'python%d.%d' % sys.version_info[:2], 'site-packages')
723
723
724 import site
724 import site
725 sys.path.insert(0, virtual_env)
725 sys.path.insert(0, virtual_env)
726 site.addsitedir(virtual_env)
726 site.addsitedir(virtual_env)
727
727
728 #-------------------------------------------------------------------------
728 #-------------------------------------------------------------------------
729 # Things related to injections into the sys module
729 # Things related to injections into the sys module
730 #-------------------------------------------------------------------------
730 #-------------------------------------------------------------------------
731
731
732 def save_sys_module_state(self):
732 def save_sys_module_state(self):
733 """Save the state of hooks in the sys module.
733 """Save the state of hooks in the sys module.
734
734
735 This has to be called after self.user_module is created.
735 This has to be called after self.user_module is created.
736 """
736 """
737 self._orig_sys_module_state = {}
737 self._orig_sys_module_state = {}
738 self._orig_sys_module_state['stdin'] = sys.stdin
738 self._orig_sys_module_state['stdin'] = sys.stdin
739 self._orig_sys_module_state['stdout'] = sys.stdout
739 self._orig_sys_module_state['stdout'] = sys.stdout
740 self._orig_sys_module_state['stderr'] = sys.stderr
740 self._orig_sys_module_state['stderr'] = sys.stderr
741 self._orig_sys_module_state['excepthook'] = sys.excepthook
741 self._orig_sys_module_state['excepthook'] = sys.excepthook
742 self._orig_sys_modules_main_name = self.user_module.__name__
742 self._orig_sys_modules_main_name = self.user_module.__name__
743 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
743 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
744
744
745 def restore_sys_module_state(self):
745 def restore_sys_module_state(self):
746 """Restore the state of the sys module."""
746 """Restore the state of the sys module."""
747 try:
747 try:
748 for k, v in self._orig_sys_module_state.iteritems():
748 for k, v in self._orig_sys_module_state.iteritems():
749 setattr(sys, k, v)
749 setattr(sys, k, v)
750 except AttributeError:
750 except AttributeError:
751 pass
751 pass
752 # Reset what what done in self.init_sys_modules
752 # Reset what what done in self.init_sys_modules
753 if self._orig_sys_modules_main_mod is not None:
753 if self._orig_sys_modules_main_mod is not None:
754 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
754 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
755
755
756 #-------------------------------------------------------------------------
756 #-------------------------------------------------------------------------
757 # Things related to hooks
757 # Things related to hooks
758 #-------------------------------------------------------------------------
758 #-------------------------------------------------------------------------
759
759
760 def init_hooks(self):
760 def init_hooks(self):
761 # hooks holds pointers used for user-side customizations
761 # hooks holds pointers used for user-side customizations
762 self.hooks = Struct()
762 self.hooks = Struct()
763
763
764 self.strdispatchers = {}
764 self.strdispatchers = {}
765
765
766 # Set all default hooks, defined in the IPython.hooks module.
766 # Set all default hooks, defined in the IPython.hooks module.
767 hooks = IPython.core.hooks
767 hooks = IPython.core.hooks
768 for hook_name in hooks.__all__:
768 for hook_name in hooks.__all__:
769 # default hooks have priority 100, i.e. low; user hooks should have
769 # default hooks have priority 100, i.e. low; user hooks should have
770 # 0-100 priority
770 # 0-100 priority
771 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
771 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
772
772
773 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
773 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
774 """set_hook(name,hook) -> sets an internal IPython hook.
774 """set_hook(name,hook) -> sets an internal IPython hook.
775
775
776 IPython exposes some of its internal API as user-modifiable hooks. By
776 IPython exposes some of its internal API as user-modifiable hooks. By
777 adding your function to one of these hooks, you can modify IPython's
777 adding your function to one of these hooks, you can modify IPython's
778 behavior to call at runtime your own routines."""
778 behavior to call at runtime your own routines."""
779
779
780 # At some point in the future, this should validate the hook before it
780 # At some point in the future, this should validate the hook before it
781 # accepts it. Probably at least check that the hook takes the number
781 # accepts it. Probably at least check that the hook takes the number
782 # of args it's supposed to.
782 # of args it's supposed to.
783
783
784 f = types.MethodType(hook,self)
784 f = types.MethodType(hook,self)
785
785
786 # check if the hook is for strdispatcher first
786 # check if the hook is for strdispatcher first
787 if str_key is not None:
787 if str_key is not None:
788 sdp = self.strdispatchers.get(name, StrDispatch())
788 sdp = self.strdispatchers.get(name, StrDispatch())
789 sdp.add_s(str_key, f, priority )
789 sdp.add_s(str_key, f, priority )
790 self.strdispatchers[name] = sdp
790 self.strdispatchers[name] = sdp
791 return
791 return
792 if re_key is not None:
792 if re_key is not None:
793 sdp = self.strdispatchers.get(name, StrDispatch())
793 sdp = self.strdispatchers.get(name, StrDispatch())
794 sdp.add_re(re.compile(re_key), f, priority )
794 sdp.add_re(re.compile(re_key), f, priority )
795 self.strdispatchers[name] = sdp
795 self.strdispatchers[name] = sdp
796 return
796 return
797
797
798 dp = getattr(self.hooks, name, None)
798 dp = getattr(self.hooks, name, None)
799 if name not in IPython.core.hooks.__all__:
799 if name not in IPython.core.hooks.__all__:
800 print("Warning! Hook '%s' is not one of %s" % \
800 print("Warning! Hook '%s' is not one of %s" % \
801 (name, IPython.core.hooks.__all__ ))
801 (name, IPython.core.hooks.__all__ ))
802 if not dp:
802 if not dp:
803 dp = IPython.core.hooks.CommandChainDispatcher()
803 dp = IPython.core.hooks.CommandChainDispatcher()
804
804
805 try:
805 try:
806 dp.add(f,priority)
806 dp.add(f,priority)
807 except AttributeError:
807 except AttributeError:
808 # it was not commandchain, plain old func - replace
808 # it was not commandchain, plain old func - replace
809 dp = f
809 dp = f
810
810
811 setattr(self.hooks,name, dp)
811 setattr(self.hooks,name, dp)
812
812
813 def register_post_execute(self, func):
813 def register_post_execute(self, func):
814 """Register a function for calling after code execution.
814 """Register a function for calling after code execution.
815 """
815 """
816 if not callable(func):
816 if not callable(func):
817 raise ValueError('argument %s must be callable' % func)
817 raise ValueError('argument %s must be callable' % func)
818 self._post_execute[func] = True
818 self._post_execute[func] = True
819
819
820 #-------------------------------------------------------------------------
820 #-------------------------------------------------------------------------
821 # Things related to the "main" module
821 # Things related to the "main" module
822 #-------------------------------------------------------------------------
822 #-------------------------------------------------------------------------
823
823
824 def new_main_mod(self,ns=None):
824 def new_main_mod(self,ns=None):
825 """Return a new 'main' module object for user code execution.
825 """Return a new 'main' module object for user code execution.
826 """
826 """
827 main_mod = self._user_main_module
827 main_mod = self._user_main_module
828 init_fakemod_dict(main_mod,ns)
828 init_fakemod_dict(main_mod,ns)
829 return main_mod
829 return main_mod
830
830
831 def cache_main_mod(self,ns,fname):
831 def cache_main_mod(self,ns,fname):
832 """Cache a main module's namespace.
832 """Cache a main module's namespace.
833
833
834 When scripts are executed via %run, we must keep a reference to the
834 When scripts are executed via %run, we must keep a reference to the
835 namespace of their __main__ module (a FakeModule instance) around so
835 namespace of their __main__ module (a FakeModule instance) around so
836 that Python doesn't clear it, rendering objects defined therein
836 that Python doesn't clear it, rendering objects defined therein
837 useless.
837 useless.
838
838
839 This method keeps said reference in a private dict, keyed by the
839 This method keeps said reference in a private dict, keyed by the
840 absolute path of the module object (which corresponds to the script
840 absolute path of the module object (which corresponds to the script
841 path). This way, for multiple executions of the same script we only
841 path). This way, for multiple executions of the same script we only
842 keep one copy of the namespace (the last one), thus preventing memory
842 keep one copy of the namespace (the last one), thus preventing memory
843 leaks from old references while allowing the objects from the last
843 leaks from old references while allowing the objects from the last
844 execution to be accessible.
844 execution to be accessible.
845
845
846 Note: we can not allow the actual FakeModule instances to be deleted,
846 Note: we can not allow the actual FakeModule instances to be deleted,
847 because of how Python tears down modules (it hard-sets all their
847 because of how Python tears down modules (it hard-sets all their
848 references to None without regard for reference counts). This method
848 references to None without regard for reference counts). This method
849 must therefore make a *copy* of the given namespace, to allow the
849 must therefore make a *copy* of the given namespace, to allow the
850 original module's __dict__ to be cleared and reused.
850 original module's __dict__ to be cleared and reused.
851
851
852
852
853 Parameters
853 Parameters
854 ----------
854 ----------
855 ns : a namespace (a dict, typically)
855 ns : a namespace (a dict, typically)
856
856
857 fname : str
857 fname : str
858 Filename associated with the namespace.
858 Filename associated with the namespace.
859
859
860 Examples
860 Examples
861 --------
861 --------
862
862
863 In [10]: import IPython
863 In [10]: import IPython
864
864
865 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
865 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
866
866
867 In [12]: IPython.__file__ in _ip._main_ns_cache
867 In [12]: IPython.__file__ in _ip._main_ns_cache
868 Out[12]: True
868 Out[12]: True
869 """
869 """
870 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
870 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
871
871
872 def clear_main_mod_cache(self):
872 def clear_main_mod_cache(self):
873 """Clear the cache of main modules.
873 """Clear the cache of main modules.
874
874
875 Mainly for use by utilities like %reset.
875 Mainly for use by utilities like %reset.
876
876
877 Examples
877 Examples
878 --------
878 --------
879
879
880 In [15]: import IPython
880 In [15]: import IPython
881
881
882 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
882 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
883
883
884 In [17]: len(_ip._main_ns_cache) > 0
884 In [17]: len(_ip._main_ns_cache) > 0
885 Out[17]: True
885 Out[17]: True
886
886
887 In [18]: _ip.clear_main_mod_cache()
887 In [18]: _ip.clear_main_mod_cache()
888
888
889 In [19]: len(_ip._main_ns_cache) == 0
889 In [19]: len(_ip._main_ns_cache) == 0
890 Out[19]: True
890 Out[19]: True
891 """
891 """
892 self._main_ns_cache.clear()
892 self._main_ns_cache.clear()
893
893
894 #-------------------------------------------------------------------------
894 #-------------------------------------------------------------------------
895 # Things related to debugging
895 # Things related to debugging
896 #-------------------------------------------------------------------------
896 #-------------------------------------------------------------------------
897
897
898 def init_pdb(self):
898 def init_pdb(self):
899 # Set calling of pdb on exceptions
899 # Set calling of pdb on exceptions
900 # self.call_pdb is a property
900 # self.call_pdb is a property
901 self.call_pdb = self.pdb
901 self.call_pdb = self.pdb
902
902
903 def _get_call_pdb(self):
903 def _get_call_pdb(self):
904 return self._call_pdb
904 return self._call_pdb
905
905
906 def _set_call_pdb(self,val):
906 def _set_call_pdb(self,val):
907
907
908 if val not in (0,1,False,True):
908 if val not in (0,1,False,True):
909 raise ValueError('new call_pdb value must be boolean')
909 raise ValueError('new call_pdb value must be boolean')
910
910
911 # store value in instance
911 # store value in instance
912 self._call_pdb = val
912 self._call_pdb = val
913
913
914 # notify the actual exception handlers
914 # notify the actual exception handlers
915 self.InteractiveTB.call_pdb = val
915 self.InteractiveTB.call_pdb = val
916
916
917 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
917 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
918 'Control auto-activation of pdb at exceptions')
918 'Control auto-activation of pdb at exceptions')
919
919
920 def debugger(self,force=False):
920 def debugger(self,force=False):
921 """Call the pydb/pdb debugger.
921 """Call the pydb/pdb debugger.
922
922
923 Keywords:
923 Keywords:
924
924
925 - force(False): by default, this routine checks the instance call_pdb
925 - force(False): by default, this routine checks the instance call_pdb
926 flag and does not actually invoke the debugger if the flag is false.
926 flag and does not actually invoke the debugger if the flag is false.
927 The 'force' option forces the debugger to activate even if the flag
927 The 'force' option forces the debugger to activate even if the flag
928 is false.
928 is false.
929 """
929 """
930
930
931 if not (force or self.call_pdb):
931 if not (force or self.call_pdb):
932 return
932 return
933
933
934 if not hasattr(sys,'last_traceback'):
934 if not hasattr(sys,'last_traceback'):
935 error('No traceback has been produced, nothing to debug.')
935 error('No traceback has been produced, nothing to debug.')
936 return
936 return
937
937
938 # use pydb if available
938 # use pydb if available
939 if debugger.has_pydb:
939 if debugger.has_pydb:
940 from pydb import pm
940 from pydb import pm
941 else:
941 else:
942 # fallback to our internal debugger
942 # fallback to our internal debugger
943 pm = lambda : self.InteractiveTB.debugger(force=True)
943 pm = lambda : self.InteractiveTB.debugger(force=True)
944
944
945 with self.readline_no_record:
945 with self.readline_no_record:
946 pm()
946 pm()
947
947
948 #-------------------------------------------------------------------------
948 #-------------------------------------------------------------------------
949 # Things related to IPython's various namespaces
949 # Things related to IPython's various namespaces
950 #-------------------------------------------------------------------------
950 #-------------------------------------------------------------------------
951 default_user_namespaces = True
951 default_user_namespaces = True
952
952
953 def init_create_namespaces(self, user_module=None, user_ns=None):
953 def init_create_namespaces(self, user_module=None, user_ns=None):
954 # Create the namespace where the user will operate. user_ns is
954 # Create the namespace where the user will operate. user_ns is
955 # normally the only one used, and it is passed to the exec calls as
955 # normally the only one used, and it is passed to the exec calls as
956 # the locals argument. But we do carry a user_global_ns namespace
956 # the locals argument. But we do carry a user_global_ns namespace
957 # given as the exec 'globals' argument, This is useful in embedding
957 # given as the exec 'globals' argument, This is useful in embedding
958 # situations where the ipython shell opens in a context where the
958 # situations where the ipython shell opens in a context where the
959 # distinction between locals and globals is meaningful. For
959 # distinction between locals and globals is meaningful. For
960 # non-embedded contexts, it is just the same object as the user_ns dict.
960 # non-embedded contexts, it is just the same object as the user_ns dict.
961
961
962 # FIXME. For some strange reason, __builtins__ is showing up at user
962 # FIXME. For some strange reason, __builtins__ is showing up at user
963 # level as a dict instead of a module. This is a manual fix, but I
963 # level as a dict instead of a module. This is a manual fix, but I
964 # should really track down where the problem is coming from. Alex
964 # should really track down where the problem is coming from. Alex
965 # Schmolck reported this problem first.
965 # Schmolck reported this problem first.
966
966
967 # A useful post by Alex Martelli on this topic:
967 # A useful post by Alex Martelli on this topic:
968 # Re: inconsistent value from __builtins__
968 # Re: inconsistent value from __builtins__
969 # Von: Alex Martelli <aleaxit@yahoo.com>
969 # Von: Alex Martelli <aleaxit@yahoo.com>
970 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
970 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
971 # Gruppen: comp.lang.python
971 # Gruppen: comp.lang.python
972
972
973 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
973 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
974 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
974 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
975 # > <type 'dict'>
975 # > <type 'dict'>
976 # > >>> print type(__builtins__)
976 # > >>> print type(__builtins__)
977 # > <type 'module'>
977 # > <type 'module'>
978 # > Is this difference in return value intentional?
978 # > Is this difference in return value intentional?
979
979
980 # Well, it's documented that '__builtins__' can be either a dictionary
980 # Well, it's documented that '__builtins__' can be either a dictionary
981 # or a module, and it's been that way for a long time. Whether it's
981 # or a module, and it's been that way for a long time. Whether it's
982 # intentional (or sensible), I don't know. In any case, the idea is
982 # intentional (or sensible), I don't know. In any case, the idea is
983 # that if you need to access the built-in namespace directly, you
983 # that if you need to access the built-in namespace directly, you
984 # should start with "import __builtin__" (note, no 's') which will
984 # should start with "import __builtin__" (note, no 's') which will
985 # definitely give you a module. Yeah, it's somewhat confusing:-(.
985 # definitely give you a module. Yeah, it's somewhat confusing:-(.
986
986
987 # These routines return a properly built module and dict as needed by
987 # These routines return a properly built module and dict as needed by
988 # the rest of the code, and can also be used by extension writers to
988 # the rest of the code, and can also be used by extension writers to
989 # generate properly initialized namespaces.
989 # generate properly initialized namespaces.
990 if (user_ns is not None) or (user_module is not None):
990 if (user_ns is not None) or (user_module is not None):
991 self.default_user_namespaces = False
991 self.default_user_namespaces = False
992 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
992 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
993
993
994 # A record of hidden variables we have added to the user namespace, so
994 # A record of hidden variables we have added to the user namespace, so
995 # we can list later only variables defined in actual interactive use.
995 # we can list later only variables defined in actual interactive use.
996 self.user_ns_hidden = set()
996 self.user_ns_hidden = set()
997
997
998 # Now that FakeModule produces a real module, we've run into a nasty
998 # Now that FakeModule produces a real module, we've run into a nasty
999 # problem: after script execution (via %run), the module where the user
999 # problem: after script execution (via %run), the module where the user
1000 # code ran is deleted. Now that this object is a true module (needed
1000 # code ran is deleted. Now that this object is a true module (needed
1001 # so docetst and other tools work correctly), the Python module
1001 # so docetst and other tools work correctly), the Python module
1002 # teardown mechanism runs over it, and sets to None every variable
1002 # teardown mechanism runs over it, and sets to None every variable
1003 # present in that module. Top-level references to objects from the
1003 # present in that module. Top-level references to objects from the
1004 # script survive, because the user_ns is updated with them. However,
1004 # script survive, because the user_ns is updated with them. However,
1005 # calling functions defined in the script that use other things from
1005 # calling functions defined in the script that use other things from
1006 # the script will fail, because the function's closure had references
1006 # the script will fail, because the function's closure had references
1007 # to the original objects, which are now all None. So we must protect
1007 # to the original objects, which are now all None. So we must protect
1008 # these modules from deletion by keeping a cache.
1008 # these modules from deletion by keeping a cache.
1009 #
1009 #
1010 # To avoid keeping stale modules around (we only need the one from the
1010 # To avoid keeping stale modules around (we only need the one from the
1011 # last run), we use a dict keyed with the full path to the script, so
1011 # last run), we use a dict keyed with the full path to the script, so
1012 # only the last version of the module is held in the cache. Note,
1012 # only the last version of the module is held in the cache. Note,
1013 # however, that we must cache the module *namespace contents* (their
1013 # however, that we must cache the module *namespace contents* (their
1014 # __dict__). Because if we try to cache the actual modules, old ones
1014 # __dict__). Because if we try to cache the actual modules, old ones
1015 # (uncached) could be destroyed while still holding references (such as
1015 # (uncached) could be destroyed while still holding references (such as
1016 # those held by GUI objects that tend to be long-lived)>
1016 # those held by GUI objects that tend to be long-lived)>
1017 #
1017 #
1018 # The %reset command will flush this cache. See the cache_main_mod()
1018 # The %reset command will flush this cache. See the cache_main_mod()
1019 # and clear_main_mod_cache() methods for details on use.
1019 # and clear_main_mod_cache() methods for details on use.
1020
1020
1021 # This is the cache used for 'main' namespaces
1021 # This is the cache used for 'main' namespaces
1022 self._main_ns_cache = {}
1022 self._main_ns_cache = {}
1023 # And this is the single instance of FakeModule whose __dict__ we keep
1023 # And this is the single instance of FakeModule whose __dict__ we keep
1024 # copying and clearing for reuse on each %run
1024 # copying and clearing for reuse on each %run
1025 self._user_main_module = FakeModule()
1025 self._user_main_module = FakeModule()
1026
1026
1027 # A table holding all the namespaces IPython deals with, so that
1027 # A table holding all the namespaces IPython deals with, so that
1028 # introspection facilities can search easily.
1028 # introspection facilities can search easily.
1029 self.ns_table = {'user_global':self.user_module.__dict__,
1029 self.ns_table = {'user_global':self.user_module.__dict__,
1030 'user_local':self.user_ns,
1030 'user_local':self.user_ns,
1031 'builtin':builtin_mod.__dict__
1031 'builtin':builtin_mod.__dict__
1032 }
1032 }
1033
1033
1034 @property
1034 @property
1035 def user_global_ns(self):
1035 def user_global_ns(self):
1036 return self.user_module.__dict__
1036 return self.user_module.__dict__
1037
1037
1038 def prepare_user_module(self, user_module=None, user_ns=None):
1038 def prepare_user_module(self, user_module=None, user_ns=None):
1039 """Prepare the module and namespace in which user code will be run.
1039 """Prepare the module and namespace in which user code will be run.
1040
1040
1041 When IPython is started normally, both parameters are None: a new module
1041 When IPython is started normally, both parameters are None: a new module
1042 is created automatically, and its __dict__ used as the namespace.
1042 is created automatically, and its __dict__ used as the namespace.
1043
1043
1044 If only user_module is provided, its __dict__ is used as the namespace.
1044 If only user_module is provided, its __dict__ is used as the namespace.
1045 If only user_ns is provided, a dummy module is created, and user_ns
1045 If only user_ns is provided, a dummy module is created, and user_ns
1046 becomes the global namespace. If both are provided (as they may be
1046 becomes the global namespace. If both are provided (as they may be
1047 when embedding), user_ns is the local namespace, and user_module
1047 when embedding), user_ns is the local namespace, and user_module
1048 provides the global namespace.
1048 provides the global namespace.
1049
1049
1050 Parameters
1050 Parameters
1051 ----------
1051 ----------
1052 user_module : module, optional
1052 user_module : module, optional
1053 The current user module in which IPython is being run. If None,
1053 The current user module in which IPython is being run. If None,
1054 a clean module will be created.
1054 a clean module will be created.
1055 user_ns : dict, optional
1055 user_ns : dict, optional
1056 A namespace in which to run interactive commands.
1056 A namespace in which to run interactive commands.
1057
1057
1058 Returns
1058 Returns
1059 -------
1059 -------
1060 A tuple of user_module and user_ns, each properly initialised.
1060 A tuple of user_module and user_ns, each properly initialised.
1061 """
1061 """
1062 if user_module is None and user_ns is not None:
1062 if user_module is None and user_ns is not None:
1063 user_ns.setdefault("__name__", "__main__")
1063 user_ns.setdefault("__name__", "__main__")
1064 class DummyMod(object):
1064 class DummyMod(object):
1065 "A dummy module used for IPython's interactive namespace."
1065 "A dummy module used for IPython's interactive namespace."
1066 pass
1066 pass
1067 user_module = DummyMod()
1067 user_module = DummyMod()
1068 user_module.__dict__ = user_ns
1068 user_module.__dict__ = user_ns
1069
1069
1070 if user_module is None:
1070 if user_module is None:
1071 user_module = types.ModuleType("__main__",
1071 user_module = types.ModuleType("__main__",
1072 doc="Automatically created module for IPython interactive environment")
1072 doc="Automatically created module for IPython interactive environment")
1073
1073
1074 # We must ensure that __builtin__ (without the final 's') is always
1074 # We must ensure that __builtin__ (without the final 's') is always
1075 # available and pointing to the __builtin__ *module*. For more details:
1075 # available and pointing to the __builtin__ *module*. For more details:
1076 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1076 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1077 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1077 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1078 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1078 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1079
1079
1080 if user_ns is None:
1080 if user_ns is None:
1081 user_ns = user_module.__dict__
1081 user_ns = user_module.__dict__
1082
1082
1083 return user_module, user_ns
1083 return user_module, user_ns
1084
1084
1085 def init_sys_modules(self):
1085 def init_sys_modules(self):
1086 # We need to insert into sys.modules something that looks like a
1086 # We need to insert into sys.modules something that looks like a
1087 # module but which accesses the IPython namespace, for shelve and
1087 # module but which accesses the IPython namespace, for shelve and
1088 # pickle to work interactively. Normally they rely on getting
1088 # pickle to work interactively. Normally they rely on getting
1089 # everything out of __main__, but for embedding purposes each IPython
1089 # everything out of __main__, but for embedding purposes each IPython
1090 # instance has its own private namespace, so we can't go shoving
1090 # instance has its own private namespace, so we can't go shoving
1091 # everything into __main__.
1091 # everything into __main__.
1092
1092
1093 # note, however, that we should only do this for non-embedded
1093 # note, however, that we should only do this for non-embedded
1094 # ipythons, which really mimic the __main__.__dict__ with their own
1094 # ipythons, which really mimic the __main__.__dict__ with their own
1095 # namespace. Embedded instances, on the other hand, should not do
1095 # namespace. Embedded instances, on the other hand, should not do
1096 # this because they need to manage the user local/global namespaces
1096 # this because they need to manage the user local/global namespaces
1097 # only, but they live within a 'normal' __main__ (meaning, they
1097 # only, but they live within a 'normal' __main__ (meaning, they
1098 # shouldn't overtake the execution environment of the script they're
1098 # shouldn't overtake the execution environment of the script they're
1099 # embedded in).
1099 # embedded in).
1100
1100
1101 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1101 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1102 main_name = self.user_module.__name__
1102 main_name = self.user_module.__name__
1103 sys.modules[main_name] = self.user_module
1103 sys.modules[main_name] = self.user_module
1104
1104
1105 def init_user_ns(self):
1105 def init_user_ns(self):
1106 """Initialize all user-visible namespaces to their minimum defaults.
1106 """Initialize all user-visible namespaces to their minimum defaults.
1107
1107
1108 Certain history lists are also initialized here, as they effectively
1108 Certain history lists are also initialized here, as they effectively
1109 act as user namespaces.
1109 act as user namespaces.
1110
1110
1111 Notes
1111 Notes
1112 -----
1112 -----
1113 All data structures here are only filled in, they are NOT reset by this
1113 All data structures here are only filled in, they are NOT reset by this
1114 method. If they were not empty before, data will simply be added to
1114 method. If they were not empty before, data will simply be added to
1115 therm.
1115 therm.
1116 """
1116 """
1117 # This function works in two parts: first we put a few things in
1117 # This function works in two parts: first we put a few things in
1118 # user_ns, and we sync that contents into user_ns_hidden so that these
1118 # user_ns, and we sync that contents into user_ns_hidden so that these
1119 # initial variables aren't shown by %who. After the sync, we add the
1119 # initial variables aren't shown by %who. After the sync, we add the
1120 # rest of what we *do* want the user to see with %who even on a new
1120 # rest of what we *do* want the user to see with %who even on a new
1121 # session (probably nothing, so theye really only see their own stuff)
1121 # session (probably nothing, so theye really only see their own stuff)
1122
1122
1123 # The user dict must *always* have a __builtin__ reference to the
1123 # The user dict must *always* have a __builtin__ reference to the
1124 # Python standard __builtin__ namespace, which must be imported.
1124 # Python standard __builtin__ namespace, which must be imported.
1125 # This is so that certain operations in prompt evaluation can be
1125 # This is so that certain operations in prompt evaluation can be
1126 # reliably executed with builtins. Note that we can NOT use
1126 # reliably executed with builtins. Note that we can NOT use
1127 # __builtins__ (note the 's'), because that can either be a dict or a
1127 # __builtins__ (note the 's'), because that can either be a dict or a
1128 # module, and can even mutate at runtime, depending on the context
1128 # module, and can even mutate at runtime, depending on the context
1129 # (Python makes no guarantees on it). In contrast, __builtin__ is
1129 # (Python makes no guarantees on it). In contrast, __builtin__ is
1130 # always a module object, though it must be explicitly imported.
1130 # always a module object, though it must be explicitly imported.
1131
1131
1132 # For more details:
1132 # For more details:
1133 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1133 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1134 ns = dict()
1134 ns = dict()
1135
1135
1136 # Put 'help' in the user namespace
1136 # Put 'help' in the user namespace
1137 try:
1137 try:
1138 from site import _Helper
1138 from site import _Helper
1139 ns['help'] = _Helper()
1139 ns['help'] = _Helper()
1140 except ImportError:
1140 except ImportError:
1141 warn('help() not available - check site.py')
1141 warn('help() not available - check site.py')
1142
1142
1143 # make global variables for user access to the histories
1143 # make global variables for user access to the histories
1144 ns['_ih'] = self.history_manager.input_hist_parsed
1144 ns['_ih'] = self.history_manager.input_hist_parsed
1145 ns['_oh'] = self.history_manager.output_hist
1145 ns['_oh'] = self.history_manager.output_hist
1146 ns['_dh'] = self.history_manager.dir_hist
1146 ns['_dh'] = self.history_manager.dir_hist
1147
1147
1148 ns['_sh'] = shadowns
1148 ns['_sh'] = shadowns
1149
1149
1150 # user aliases to input and output histories. These shouldn't show up
1150 # user aliases to input and output histories. These shouldn't show up
1151 # in %who, as they can have very large reprs.
1151 # in %who, as they can have very large reprs.
1152 ns['In'] = self.history_manager.input_hist_parsed
1152 ns['In'] = self.history_manager.input_hist_parsed
1153 ns['Out'] = self.history_manager.output_hist
1153 ns['Out'] = self.history_manager.output_hist
1154
1154
1155 # Store myself as the public api!!!
1155 # Store myself as the public api!!!
1156 ns['get_ipython'] = self.get_ipython
1156 ns['get_ipython'] = self.get_ipython
1157
1157
1158 ns['exit'] = self.exiter
1158 ns['exit'] = self.exiter
1159 ns['quit'] = self.exiter
1159 ns['quit'] = self.exiter
1160
1160
1161 # Sync what we've added so far to user_ns_hidden so these aren't seen
1161 # Sync what we've added so far to user_ns_hidden so these aren't seen
1162 # by %who
1162 # by %who
1163 self.user_ns_hidden.update(ns)
1163 self.user_ns_hidden.update(ns)
1164
1164
1165 # Anything put into ns now would show up in %who. Think twice before
1165 # Anything put into ns now would show up in %who. Think twice before
1166 # putting anything here, as we really want %who to show the user their
1166 # putting anything here, as we really want %who to show the user their
1167 # stuff, not our variables.
1167 # stuff, not our variables.
1168
1168
1169 # Finally, update the real user's namespace
1169 # Finally, update the real user's namespace
1170 self.user_ns.update(ns)
1170 self.user_ns.update(ns)
1171
1171
1172 @property
1172 @property
1173 def all_ns_refs(self):
1173 def all_ns_refs(self):
1174 """Get a list of references to all the namespace dictionaries in which
1174 """Get a list of references to all the namespace dictionaries in which
1175 IPython might store a user-created object.
1175 IPython might store a user-created object.
1176
1176
1177 Note that this does not include the displayhook, which also caches
1177 Note that this does not include the displayhook, which also caches
1178 objects from the output."""
1178 objects from the output."""
1179 return [self.user_ns, self.user_global_ns,
1179 return [self.user_ns, self.user_global_ns,
1180 self._user_main_module.__dict__] + self._main_ns_cache.values()
1180 self._user_main_module.__dict__] + self._main_ns_cache.values()
1181
1181
1182 def reset(self, new_session=True):
1182 def reset(self, new_session=True):
1183 """Clear all internal namespaces, and attempt to release references to
1183 """Clear all internal namespaces, and attempt to release references to
1184 user objects.
1184 user objects.
1185
1185
1186 If new_session is True, a new history session will be opened.
1186 If new_session is True, a new history session will be opened.
1187 """
1187 """
1188 # Clear histories
1188 # Clear histories
1189 self.history_manager.reset(new_session)
1189 self.history_manager.reset(new_session)
1190 # Reset counter used to index all histories
1190 # Reset counter used to index all histories
1191 if new_session:
1191 if new_session:
1192 self.execution_count = 1
1192 self.execution_count = 1
1193
1193
1194 # Flush cached output items
1194 # Flush cached output items
1195 if self.displayhook.do_full_cache:
1195 if self.displayhook.do_full_cache:
1196 self.displayhook.flush()
1196 self.displayhook.flush()
1197
1197
1198 # The main execution namespaces must be cleared very carefully,
1198 # The main execution namespaces must be cleared very carefully,
1199 # skipping the deletion of the builtin-related keys, because doing so
1199 # skipping the deletion of the builtin-related keys, because doing so
1200 # would cause errors in many object's __del__ methods.
1200 # would cause errors in many object's __del__ methods.
1201 if self.user_ns is not self.user_global_ns:
1201 if self.user_ns is not self.user_global_ns:
1202 self.user_ns.clear()
1202 self.user_ns.clear()
1203 ns = self.user_global_ns
1203 ns = self.user_global_ns
1204 drop_keys = set(ns.keys())
1204 drop_keys = set(ns.keys())
1205 drop_keys.discard('__builtin__')
1205 drop_keys.discard('__builtin__')
1206 drop_keys.discard('__builtins__')
1206 drop_keys.discard('__builtins__')
1207 drop_keys.discard('__name__')
1207 drop_keys.discard('__name__')
1208 for k in drop_keys:
1208 for k in drop_keys:
1209 del ns[k]
1209 del ns[k]
1210
1210
1211 self.user_ns_hidden.clear()
1211 self.user_ns_hidden.clear()
1212
1212
1213 # Restore the user namespaces to minimal usability
1213 # Restore the user namespaces to minimal usability
1214 self.init_user_ns()
1214 self.init_user_ns()
1215
1215
1216 # Restore the default and user aliases
1216 # Restore the default and user aliases
1217 self.alias_manager.clear_aliases()
1217 self.alias_manager.clear_aliases()
1218 self.alias_manager.init_aliases()
1218 self.alias_manager.init_aliases()
1219
1219
1220 # Flush the private list of module references kept for script
1220 # Flush the private list of module references kept for script
1221 # execution protection
1221 # execution protection
1222 self.clear_main_mod_cache()
1222 self.clear_main_mod_cache()
1223
1223
1224 # Clear out the namespace from the last %run
1224 # Clear out the namespace from the last %run
1225 self.new_main_mod()
1225 self.new_main_mod()
1226
1226
1227 def del_var(self, varname, by_name=False):
1227 def del_var(self, varname, by_name=False):
1228 """Delete a variable from the various namespaces, so that, as
1228 """Delete a variable from the various namespaces, so that, as
1229 far as possible, we're not keeping any hidden references to it.
1229 far as possible, we're not keeping any hidden references to it.
1230
1230
1231 Parameters
1231 Parameters
1232 ----------
1232 ----------
1233 varname : str
1233 varname : str
1234 The name of the variable to delete.
1234 The name of the variable to delete.
1235 by_name : bool
1235 by_name : bool
1236 If True, delete variables with the given name in each
1236 If True, delete variables with the given name in each
1237 namespace. If False (default), find the variable in the user
1237 namespace. If False (default), find the variable in the user
1238 namespace, and delete references to it.
1238 namespace, and delete references to it.
1239 """
1239 """
1240 if varname in ('__builtin__', '__builtins__'):
1240 if varname in ('__builtin__', '__builtins__'):
1241 raise ValueError("Refusing to delete %s" % varname)
1241 raise ValueError("Refusing to delete %s" % varname)
1242
1242
1243 ns_refs = self.all_ns_refs
1243 ns_refs = self.all_ns_refs
1244
1244
1245 if by_name: # Delete by name
1245 if by_name: # Delete by name
1246 for ns in ns_refs:
1246 for ns in ns_refs:
1247 try:
1247 try:
1248 del ns[varname]
1248 del ns[varname]
1249 except KeyError:
1249 except KeyError:
1250 pass
1250 pass
1251 else: # Delete by object
1251 else: # Delete by object
1252 try:
1252 try:
1253 obj = self.user_ns[varname]
1253 obj = self.user_ns[varname]
1254 except KeyError:
1254 except KeyError:
1255 raise NameError("name '%s' is not defined" % varname)
1255 raise NameError("name '%s' is not defined" % varname)
1256 # Also check in output history
1256 # Also check in output history
1257 ns_refs.append(self.history_manager.output_hist)
1257 ns_refs.append(self.history_manager.output_hist)
1258 for ns in ns_refs:
1258 for ns in ns_refs:
1259 to_delete = [n for n, o in ns.iteritems() if o is obj]
1259 to_delete = [n for n, o in ns.iteritems() if o is obj]
1260 for name in to_delete:
1260 for name in to_delete:
1261 del ns[name]
1261 del ns[name]
1262
1262
1263 # displayhook keeps extra references, but not in a dictionary
1263 # displayhook keeps extra references, but not in a dictionary
1264 for name in ('_', '__', '___'):
1264 for name in ('_', '__', '___'):
1265 if getattr(self.displayhook, name) is obj:
1265 if getattr(self.displayhook, name) is obj:
1266 setattr(self.displayhook, name, None)
1266 setattr(self.displayhook, name, None)
1267
1267
1268 def reset_selective(self, regex=None):
1268 def reset_selective(self, regex=None):
1269 """Clear selective variables from internal namespaces based on a
1269 """Clear selective variables from internal namespaces based on a
1270 specified regular expression.
1270 specified regular expression.
1271
1271
1272 Parameters
1272 Parameters
1273 ----------
1273 ----------
1274 regex : string or compiled pattern, optional
1274 regex : string or compiled pattern, optional
1275 A regular expression pattern that will be used in searching
1275 A regular expression pattern that will be used in searching
1276 variable names in the users namespaces.
1276 variable names in the users namespaces.
1277 """
1277 """
1278 if regex is not None:
1278 if regex is not None:
1279 try:
1279 try:
1280 m = re.compile(regex)
1280 m = re.compile(regex)
1281 except TypeError:
1281 except TypeError:
1282 raise TypeError('regex must be a string or compiled pattern')
1282 raise TypeError('regex must be a string or compiled pattern')
1283 # Search for keys in each namespace that match the given regex
1283 # Search for keys in each namespace that match the given regex
1284 # If a match is found, delete the key/value pair.
1284 # If a match is found, delete the key/value pair.
1285 for ns in self.all_ns_refs:
1285 for ns in self.all_ns_refs:
1286 for var in ns:
1286 for var in ns:
1287 if m.search(var):
1287 if m.search(var):
1288 del ns[var]
1288 del ns[var]
1289
1289
1290 def push(self, variables, interactive=True):
1290 def push(self, variables, interactive=True):
1291 """Inject a group of variables into the IPython user namespace.
1291 """Inject a group of variables into the IPython user namespace.
1292
1292
1293 Parameters
1293 Parameters
1294 ----------
1294 ----------
1295 variables : dict, str or list/tuple of str
1295 variables : dict, str or list/tuple of str
1296 The variables to inject into the user's namespace. If a dict, a
1296 The variables to inject into the user's namespace. If a dict, a
1297 simple update is done. If a str, the string is assumed to have
1297 simple update is done. If a str, the string is assumed to have
1298 variable names separated by spaces. A list/tuple of str can also
1298 variable names separated by spaces. A list/tuple of str can also
1299 be used to give the variable names. If just the variable names are
1299 be used to give the variable names. If just the variable names are
1300 give (list/tuple/str) then the variable values looked up in the
1300 give (list/tuple/str) then the variable values looked up in the
1301 callers frame.
1301 callers frame.
1302 interactive : bool
1302 interactive : bool
1303 If True (default), the variables will be listed with the ``who``
1303 If True (default), the variables will be listed with the ``who``
1304 magic.
1304 magic.
1305 """
1305 """
1306 vdict = None
1306 vdict = None
1307
1307
1308 # We need a dict of name/value pairs to do namespace updates.
1308 # We need a dict of name/value pairs to do namespace updates.
1309 if isinstance(variables, dict):
1309 if isinstance(variables, dict):
1310 vdict = variables
1310 vdict = variables
1311 elif isinstance(variables, (basestring, list, tuple)):
1311 elif isinstance(variables, (basestring, list, tuple)):
1312 if isinstance(variables, basestring):
1312 if isinstance(variables, basestring):
1313 vlist = variables.split()
1313 vlist = variables.split()
1314 else:
1314 else:
1315 vlist = variables
1315 vlist = variables
1316 vdict = {}
1316 vdict = {}
1317 cf = sys._getframe(1)
1317 cf = sys._getframe(1)
1318 for name in vlist:
1318 for name in vlist:
1319 try:
1319 try:
1320 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1320 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1321 except:
1321 except:
1322 print('Could not get variable %s from %s' %
1322 print('Could not get variable %s from %s' %
1323 (name,cf.f_code.co_name))
1323 (name,cf.f_code.co_name))
1324 else:
1324 else:
1325 raise ValueError('variables must be a dict/str/list/tuple')
1325 raise ValueError('variables must be a dict/str/list/tuple')
1326
1326
1327 # Propagate variables to user namespace
1327 # Propagate variables to user namespace
1328 self.user_ns.update(vdict)
1328 self.user_ns.update(vdict)
1329
1329
1330 # And configure interactive visibility
1330 # And configure interactive visibility
1331 user_ns_hidden = self.user_ns_hidden
1331 user_ns_hidden = self.user_ns_hidden
1332 if interactive:
1332 if interactive:
1333 user_ns_hidden.difference_update(vdict)
1333 user_ns_hidden.difference_update(vdict)
1334 else:
1334 else:
1335 user_ns_hidden.update(vdict)
1335 user_ns_hidden.update(vdict)
1336
1336
1337 def drop_by_id(self, variables):
1337 def drop_by_id(self, variables):
1338 """Remove a dict of variables from the user namespace, if they are the
1338 """Remove a dict of variables from the user namespace, if they are the
1339 same as the values in the dictionary.
1339 same as the values in the dictionary.
1340
1340
1341 This is intended for use by extensions: variables that they've added can
1341 This is intended for use by extensions: variables that they've added can
1342 be taken back out if they are unloaded, without removing any that the
1342 be taken back out if they are unloaded, without removing any that the
1343 user has overwritten.
1343 user has overwritten.
1344
1344
1345 Parameters
1345 Parameters
1346 ----------
1346 ----------
1347 variables : dict
1347 variables : dict
1348 A dictionary mapping object names (as strings) to the objects.
1348 A dictionary mapping object names (as strings) to the objects.
1349 """
1349 """
1350 for name, obj in variables.iteritems():
1350 for name, obj in variables.iteritems():
1351 if name in self.user_ns and self.user_ns[name] is obj:
1351 if name in self.user_ns and self.user_ns[name] is obj:
1352 del self.user_ns[name]
1352 del self.user_ns[name]
1353 self.user_ns_hidden.discard(name)
1353 self.user_ns_hidden.discard(name)
1354
1354
1355 #-------------------------------------------------------------------------
1355 #-------------------------------------------------------------------------
1356 # Things related to object introspection
1356 # Things related to object introspection
1357 #-------------------------------------------------------------------------
1357 #-------------------------------------------------------------------------
1358
1358
1359 def _ofind(self, oname, namespaces=None):
1359 def _ofind(self, oname, namespaces=None):
1360 """Find an object in the available namespaces.
1360 """Find an object in the available namespaces.
1361
1361
1362 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1362 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1363
1363
1364 Has special code to detect magic functions.
1364 Has special code to detect magic functions.
1365 """
1365 """
1366 oname = oname.strip()
1366 oname = oname.strip()
1367 #print '1- oname: <%r>' % oname # dbg
1367 #print '1- oname: <%r>' % oname # dbg
1368 if not oname.startswith(ESC_MAGIC) and \
1368 if not oname.startswith(ESC_MAGIC) and \
1369 not oname.startswith(ESC_MAGIC2) and \
1369 not oname.startswith(ESC_MAGIC2) and \
1370 not py3compat.isidentifier(oname, dotted=True):
1370 not py3compat.isidentifier(oname, dotted=True):
1371 return dict(found=False)
1371 return dict(found=False)
1372
1372
1373 alias_ns = None
1373 alias_ns = None
1374 if namespaces is None:
1374 if namespaces is None:
1375 # Namespaces to search in:
1375 # Namespaces to search in:
1376 # Put them in a list. The order is important so that we
1376 # Put them in a list. The order is important so that we
1377 # find things in the same order that Python finds them.
1377 # find things in the same order that Python finds them.
1378 namespaces = [ ('Interactive', self.user_ns),
1378 namespaces = [ ('Interactive', self.user_ns),
1379 ('Interactive (global)', self.user_global_ns),
1379 ('Interactive (global)', self.user_global_ns),
1380 ('Python builtin', builtin_mod.__dict__),
1380 ('Python builtin', builtin_mod.__dict__),
1381 ('Alias', self.alias_manager.alias_table),
1381 ('Alias', self.alias_manager.alias_table),
1382 ]
1382 ]
1383 alias_ns = self.alias_manager.alias_table
1383 alias_ns = self.alias_manager.alias_table
1384
1384
1385 # initialize results to 'null'
1385 # initialize results to 'null'
1386 found = False; obj = None; ospace = None; ds = None;
1386 found = False; obj = None; ospace = None; ds = None;
1387 ismagic = False; isalias = False; parent = None
1387 ismagic = False; isalias = False; parent = None
1388
1388
1389 # We need to special-case 'print', which as of python2.6 registers as a
1389 # We need to special-case 'print', which as of python2.6 registers as a
1390 # function but should only be treated as one if print_function was
1390 # function but should only be treated as one if print_function was
1391 # loaded with a future import. In this case, just bail.
1391 # loaded with a future import. In this case, just bail.
1392 if (oname == 'print' and not py3compat.PY3 and not \
1392 if (oname == 'print' and not py3compat.PY3 and not \
1393 (self.compile.compiler_flags & __future__.CO_FUTURE_PRINT_FUNCTION)):
1393 (self.compile.compiler_flags & __future__.CO_FUTURE_PRINT_FUNCTION)):
1394 return {'found':found, 'obj':obj, 'namespace':ospace,
1394 return {'found':found, 'obj':obj, 'namespace':ospace,
1395 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1395 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1396
1396
1397 # Look for the given name by splitting it in parts. If the head is
1397 # Look for the given name by splitting it in parts. If the head is
1398 # found, then we look for all the remaining parts as members, and only
1398 # found, then we look for all the remaining parts as members, and only
1399 # declare success if we can find them all.
1399 # declare success if we can find them all.
1400 oname_parts = oname.split('.')
1400 oname_parts = oname.split('.')
1401 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1401 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1402 for nsname,ns in namespaces:
1402 for nsname,ns in namespaces:
1403 try:
1403 try:
1404 obj = ns[oname_head]
1404 obj = ns[oname_head]
1405 except KeyError:
1405 except KeyError:
1406 continue
1406 continue
1407 else:
1407 else:
1408 #print 'oname_rest:', oname_rest # dbg
1408 #print 'oname_rest:', oname_rest # dbg
1409 for part in oname_rest:
1409 for part in oname_rest:
1410 try:
1410 try:
1411 parent = obj
1411 parent = obj
1412 obj = getattr(obj,part)
1412 obj = getattr(obj,part)
1413 except:
1413 except:
1414 # Blanket except b/c some badly implemented objects
1414 # Blanket except b/c some badly implemented objects
1415 # allow __getattr__ to raise exceptions other than
1415 # allow __getattr__ to raise exceptions other than
1416 # AttributeError, which then crashes IPython.
1416 # AttributeError, which then crashes IPython.
1417 break
1417 break
1418 else:
1418 else:
1419 # If we finish the for loop (no break), we got all members
1419 # If we finish the for loop (no break), we got all members
1420 found = True
1420 found = True
1421 ospace = nsname
1421 ospace = nsname
1422 if ns == alias_ns:
1422 if ns == alias_ns:
1423 isalias = True
1423 isalias = True
1424 break # namespace loop
1424 break # namespace loop
1425
1425
1426 # Try to see if it's magic
1426 # Try to see if it's magic
1427 if not found:
1427 if not found:
1428 obj = None
1428 obj = None
1429 if oname.startswith(ESC_MAGIC2):
1429 if oname.startswith(ESC_MAGIC2):
1430 oname = oname.lstrip(ESC_MAGIC2)
1430 oname = oname.lstrip(ESC_MAGIC2)
1431 obj = self.find_cell_magic(oname)
1431 obj = self.find_cell_magic(oname)
1432 elif oname.startswith(ESC_MAGIC):
1432 elif oname.startswith(ESC_MAGIC):
1433 oname = oname.lstrip(ESC_MAGIC)
1433 oname = oname.lstrip(ESC_MAGIC)
1434 obj = self.find_line_magic(oname)
1434 obj = self.find_line_magic(oname)
1435 else:
1435 else:
1436 # search without prefix, so run? will find %run?
1436 # search without prefix, so run? will find %run?
1437 obj = self.find_line_magic(oname)
1437 obj = self.find_line_magic(oname)
1438 if obj is None:
1438 if obj is None:
1439 obj = self.find_cell_magic(oname)
1439 obj = self.find_cell_magic(oname)
1440 if obj is not None:
1440 if obj is not None:
1441 found = True
1441 found = True
1442 ospace = 'IPython internal'
1442 ospace = 'IPython internal'
1443 ismagic = True
1443 ismagic = True
1444
1444
1445 # Last try: special-case some literals like '', [], {}, etc:
1445 # Last try: special-case some literals like '', [], {}, etc:
1446 if not found and oname_head in ["''",'""','[]','{}','()']:
1446 if not found and oname_head in ["''",'""','[]','{}','()']:
1447 obj = eval(oname_head)
1447 obj = eval(oname_head)
1448 found = True
1448 found = True
1449 ospace = 'Interactive'
1449 ospace = 'Interactive'
1450
1450
1451 return {'found':found, 'obj':obj, 'namespace':ospace,
1451 return {'found':found, 'obj':obj, 'namespace':ospace,
1452 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1452 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1453
1453
1454 def _ofind_property(self, oname, info):
1454 def _ofind_property(self, oname, info):
1455 """Second part of object finding, to look for property details."""
1455 """Second part of object finding, to look for property details."""
1456 if info.found:
1456 if info.found:
1457 # Get the docstring of the class property if it exists.
1457 # Get the docstring of the class property if it exists.
1458 path = oname.split('.')
1458 path = oname.split('.')
1459 root = '.'.join(path[:-1])
1459 root = '.'.join(path[:-1])
1460 if info.parent is not None:
1460 if info.parent is not None:
1461 try:
1461 try:
1462 target = getattr(info.parent, '__class__')
1462 target = getattr(info.parent, '__class__')
1463 # The object belongs to a class instance.
1463 # The object belongs to a class instance.
1464 try:
1464 try:
1465 target = getattr(target, path[-1])
1465 target = getattr(target, path[-1])
1466 # The class defines the object.
1466 # The class defines the object.
1467 if isinstance(target, property):
1467 if isinstance(target, property):
1468 oname = root + '.__class__.' + path[-1]
1468 oname = root + '.__class__.' + path[-1]
1469 info = Struct(self._ofind(oname))
1469 info = Struct(self._ofind(oname))
1470 except AttributeError: pass
1470 except AttributeError: pass
1471 except AttributeError: pass
1471 except AttributeError: pass
1472
1472
1473 # We return either the new info or the unmodified input if the object
1473 # We return either the new info or the unmodified input if the object
1474 # hadn't been found
1474 # hadn't been found
1475 return info
1475 return info
1476
1476
1477 def _object_find(self, oname, namespaces=None):
1477 def _object_find(self, oname, namespaces=None):
1478 """Find an object and return a struct with info about it."""
1478 """Find an object and return a struct with info about it."""
1479 inf = Struct(self._ofind(oname, namespaces))
1479 inf = Struct(self._ofind(oname, namespaces))
1480 return Struct(self._ofind_property(oname, inf))
1480 return Struct(self._ofind_property(oname, inf))
1481
1481
1482 def _inspect(self, meth, oname, namespaces=None, **kw):
1482 def _inspect(self, meth, oname, namespaces=None, **kw):
1483 """Generic interface to the inspector system.
1483 """Generic interface to the inspector system.
1484
1484
1485 This function is meant to be called by pdef, pdoc & friends."""
1485 This function is meant to be called by pdef, pdoc & friends."""
1486 info = self._object_find(oname, namespaces)
1486 info = self._object_find(oname, namespaces)
1487 if info.found:
1487 if info.found:
1488 pmethod = getattr(self.inspector, meth)
1488 pmethod = getattr(self.inspector, meth)
1489 formatter = format_screen if info.ismagic else None
1489 formatter = format_screen if info.ismagic else None
1490 if meth == 'pdoc':
1490 if meth == 'pdoc':
1491 pmethod(info.obj, oname, formatter)
1491 pmethod(info.obj, oname, formatter)
1492 elif meth == 'pinfo':
1492 elif meth == 'pinfo':
1493 pmethod(info.obj, oname, formatter, info, **kw)
1493 pmethod(info.obj, oname, formatter, info, **kw)
1494 else:
1494 else:
1495 pmethod(info.obj, oname)
1495 pmethod(info.obj, oname)
1496 else:
1496 else:
1497 print('Object `%s` not found.' % oname)
1497 print('Object `%s` not found.' % oname)
1498 return 'not found' # so callers can take other action
1498 return 'not found' # so callers can take other action
1499
1499
1500 def object_inspect(self, oname, detail_level=0):
1500 def object_inspect(self, oname, detail_level=0):
1501 with self.builtin_trap:
1501 with self.builtin_trap:
1502 info = self._object_find(oname)
1502 info = self._object_find(oname)
1503 if info.found:
1503 if info.found:
1504 return self.inspector.info(info.obj, oname, info=info,
1504 return self.inspector.info(info.obj, oname, info=info,
1505 detail_level=detail_level
1505 detail_level=detail_level
1506 )
1506 )
1507 else:
1507 else:
1508 return oinspect.object_info(name=oname, found=False)
1508 return oinspect.object_info(name=oname, found=False)
1509
1509
1510 #-------------------------------------------------------------------------
1510 #-------------------------------------------------------------------------
1511 # Things related to history management
1511 # Things related to history management
1512 #-------------------------------------------------------------------------
1512 #-------------------------------------------------------------------------
1513
1513
1514 def init_history(self):
1514 def init_history(self):
1515 """Sets up the command history, and starts regular autosaves."""
1515 """Sets up the command history, and starts regular autosaves."""
1516 self.history_manager = HistoryManager(shell=self, config=self.config)
1516 self.history_manager = HistoryManager(shell=self, config=self.config)
1517 self.configurables.append(self.history_manager)
1517 self.configurables.append(self.history_manager)
1518
1518
1519 #-------------------------------------------------------------------------
1519 #-------------------------------------------------------------------------
1520 # Things related to exception handling and tracebacks (not debugging)
1520 # Things related to exception handling and tracebacks (not debugging)
1521 #-------------------------------------------------------------------------
1521 #-------------------------------------------------------------------------
1522
1522
1523 def init_traceback_handlers(self, custom_exceptions):
1523 def init_traceback_handlers(self, custom_exceptions):
1524 # Syntax error handler.
1524 # Syntax error handler.
1525 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1525 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1526
1526
1527 # The interactive one is initialized with an offset, meaning we always
1527 # The interactive one is initialized with an offset, meaning we always
1528 # want to remove the topmost item in the traceback, which is our own
1528 # want to remove the topmost item in the traceback, which is our own
1529 # internal code. Valid modes: ['Plain','Context','Verbose']
1529 # internal code. Valid modes: ['Plain','Context','Verbose']
1530 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1530 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1531 color_scheme='NoColor',
1531 color_scheme='NoColor',
1532 tb_offset = 1,
1532 tb_offset = 1,
1533 check_cache=self.compile.check_cache)
1533 check_cache=self.compile.check_cache)
1534
1534
1535 # The instance will store a pointer to the system-wide exception hook,
1535 # The instance will store a pointer to the system-wide exception hook,
1536 # so that runtime code (such as magics) can access it. This is because
1536 # so that runtime code (such as magics) can access it. This is because
1537 # during the read-eval loop, it may get temporarily overwritten.
1537 # during the read-eval loop, it may get temporarily overwritten.
1538 self.sys_excepthook = sys.excepthook
1538 self.sys_excepthook = sys.excepthook
1539
1539
1540 # and add any custom exception handlers the user may have specified
1540 # and add any custom exception handlers the user may have specified
1541 self.set_custom_exc(*custom_exceptions)
1541 self.set_custom_exc(*custom_exceptions)
1542
1542
1543 # Set the exception mode
1543 # Set the exception mode
1544 self.InteractiveTB.set_mode(mode=self.xmode)
1544 self.InteractiveTB.set_mode(mode=self.xmode)
1545
1545
1546 def set_custom_exc(self, exc_tuple, handler):
1546 def set_custom_exc(self, exc_tuple, handler):
1547 """set_custom_exc(exc_tuple,handler)
1547 """set_custom_exc(exc_tuple,handler)
1548
1548
1549 Set a custom exception handler, which will be called if any of the
1549 Set a custom exception handler, which will be called if any of the
1550 exceptions in exc_tuple occur in the mainloop (specifically, in the
1550 exceptions in exc_tuple occur in the mainloop (specifically, in the
1551 run_code() method).
1551 run_code() method).
1552
1552
1553 Parameters
1553 Parameters
1554 ----------
1554 ----------
1555
1555
1556 exc_tuple : tuple of exception classes
1556 exc_tuple : tuple of exception classes
1557 A *tuple* of exception classes, for which to call the defined
1557 A *tuple* of exception classes, for which to call the defined
1558 handler. It is very important that you use a tuple, and NOT A
1558 handler. It is very important that you use a tuple, and NOT A
1559 LIST here, because of the way Python's except statement works. If
1559 LIST here, because of the way Python's except statement works. If
1560 you only want to trap a single exception, use a singleton tuple::
1560 you only want to trap a single exception, use a singleton tuple::
1561
1561
1562 exc_tuple == (MyCustomException,)
1562 exc_tuple == (MyCustomException,)
1563
1563
1564 handler : callable
1564 handler : callable
1565 handler must have the following signature::
1565 handler must have the following signature::
1566
1566
1567 def my_handler(self, etype, value, tb, tb_offset=None):
1567 def my_handler(self, etype, value, tb, tb_offset=None):
1568 ...
1568 ...
1569 return structured_traceback
1569 return structured_traceback
1570
1570
1571 Your handler must return a structured traceback (a list of strings),
1571 Your handler must return a structured traceback (a list of strings),
1572 or None.
1572 or None.
1573
1573
1574 This will be made into an instance method (via types.MethodType)
1574 This will be made into an instance method (via types.MethodType)
1575 of IPython itself, and it will be called if any of the exceptions
1575 of IPython itself, and it will be called if any of the exceptions
1576 listed in the exc_tuple are caught. If the handler is None, an
1576 listed in the exc_tuple are caught. If the handler is None, an
1577 internal basic one is used, which just prints basic info.
1577 internal basic one is used, which just prints basic info.
1578
1578
1579 To protect IPython from crashes, if your handler ever raises an
1579 To protect IPython from crashes, if your handler ever raises an
1580 exception or returns an invalid result, it will be immediately
1580 exception or returns an invalid result, it will be immediately
1581 disabled.
1581 disabled.
1582
1582
1583 WARNING: by putting in your own exception handler into IPython's main
1583 WARNING: by putting in your own exception handler into IPython's main
1584 execution loop, you run a very good chance of nasty crashes. This
1584 execution loop, you run a very good chance of nasty crashes. This
1585 facility should only be used if you really know what you are doing."""
1585 facility should only be used if you really know what you are doing."""
1586
1586
1587 assert type(exc_tuple)==type(()) , \
1587 assert type(exc_tuple)==type(()) , \
1588 "The custom exceptions must be given AS A TUPLE."
1588 "The custom exceptions must be given AS A TUPLE."
1589
1589
1590 def dummy_handler(self,etype,value,tb,tb_offset=None):
1590 def dummy_handler(self,etype,value,tb,tb_offset=None):
1591 print('*** Simple custom exception handler ***')
1591 print('*** Simple custom exception handler ***')
1592 print('Exception type :',etype)
1592 print('Exception type :',etype)
1593 print('Exception value:',value)
1593 print('Exception value:',value)
1594 print('Traceback :',tb)
1594 print('Traceback :',tb)
1595 #print 'Source code :','\n'.join(self.buffer)
1595 #print 'Source code :','\n'.join(self.buffer)
1596
1596
1597 def validate_stb(stb):
1597 def validate_stb(stb):
1598 """validate structured traceback return type
1598 """validate structured traceback return type
1599
1599
1600 return type of CustomTB *should* be a list of strings, but allow
1600 return type of CustomTB *should* be a list of strings, but allow
1601 single strings or None, which are harmless.
1601 single strings or None, which are harmless.
1602
1602
1603 This function will *always* return a list of strings,
1603 This function will *always* return a list of strings,
1604 and will raise a TypeError if stb is inappropriate.
1604 and will raise a TypeError if stb is inappropriate.
1605 """
1605 """
1606 msg = "CustomTB must return list of strings, not %r" % stb
1606 msg = "CustomTB must return list of strings, not %r" % stb
1607 if stb is None:
1607 if stb is None:
1608 return []
1608 return []
1609 elif isinstance(stb, basestring):
1609 elif isinstance(stb, basestring):
1610 return [stb]
1610 return [stb]
1611 elif not isinstance(stb, list):
1611 elif not isinstance(stb, list):
1612 raise TypeError(msg)
1612 raise TypeError(msg)
1613 # it's a list
1613 # it's a list
1614 for line in stb:
1614 for line in stb:
1615 # check every element
1615 # check every element
1616 if not isinstance(line, basestring):
1616 if not isinstance(line, basestring):
1617 raise TypeError(msg)
1617 raise TypeError(msg)
1618 return stb
1618 return stb
1619
1619
1620 if handler is None:
1620 if handler is None:
1621 wrapped = dummy_handler
1621 wrapped = dummy_handler
1622 else:
1622 else:
1623 def wrapped(self,etype,value,tb,tb_offset=None):
1623 def wrapped(self,etype,value,tb,tb_offset=None):
1624 """wrap CustomTB handler, to protect IPython from user code
1624 """wrap CustomTB handler, to protect IPython from user code
1625
1625
1626 This makes it harder (but not impossible) for custom exception
1626 This makes it harder (but not impossible) for custom exception
1627 handlers to crash IPython.
1627 handlers to crash IPython.
1628 """
1628 """
1629 try:
1629 try:
1630 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1630 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1631 return validate_stb(stb)
1631 return validate_stb(stb)
1632 except:
1632 except:
1633 # clear custom handler immediately
1633 # clear custom handler immediately
1634 self.set_custom_exc((), None)
1634 self.set_custom_exc((), None)
1635 print("Custom TB Handler failed, unregistering", file=io.stderr)
1635 print("Custom TB Handler failed, unregistering", file=io.stderr)
1636 # show the exception in handler first
1636 # show the exception in handler first
1637 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1637 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1638 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1638 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1639 print("The original exception:", file=io.stdout)
1639 print("The original exception:", file=io.stdout)
1640 stb = self.InteractiveTB.structured_traceback(
1640 stb = self.InteractiveTB.structured_traceback(
1641 (etype,value,tb), tb_offset=tb_offset
1641 (etype,value,tb), tb_offset=tb_offset
1642 )
1642 )
1643 return stb
1643 return stb
1644
1644
1645 self.CustomTB = types.MethodType(wrapped,self)
1645 self.CustomTB = types.MethodType(wrapped,self)
1646 self.custom_exceptions = exc_tuple
1646 self.custom_exceptions = exc_tuple
1647
1647
1648 def excepthook(self, etype, value, tb):
1648 def excepthook(self, etype, value, tb):
1649 """One more defense for GUI apps that call sys.excepthook.
1649 """One more defense for GUI apps that call sys.excepthook.
1650
1650
1651 GUI frameworks like wxPython trap exceptions and call
1651 GUI frameworks like wxPython trap exceptions and call
1652 sys.excepthook themselves. I guess this is a feature that
1652 sys.excepthook themselves. I guess this is a feature that
1653 enables them to keep running after exceptions that would
1653 enables them to keep running after exceptions that would
1654 otherwise kill their mainloop. This is a bother for IPython
1654 otherwise kill their mainloop. This is a bother for IPython
1655 which excepts to catch all of the program exceptions with a try:
1655 which excepts to catch all of the program exceptions with a try:
1656 except: statement.
1656 except: statement.
1657
1657
1658 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1658 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1659 any app directly invokes sys.excepthook, it will look to the user like
1659 any app directly invokes sys.excepthook, it will look to the user like
1660 IPython crashed. In order to work around this, we can disable the
1660 IPython crashed. In order to work around this, we can disable the
1661 CrashHandler and replace it with this excepthook instead, which prints a
1661 CrashHandler and replace it with this excepthook instead, which prints a
1662 regular traceback using our InteractiveTB. In this fashion, apps which
1662 regular traceback using our InteractiveTB. In this fashion, apps which
1663 call sys.excepthook will generate a regular-looking exception from
1663 call sys.excepthook will generate a regular-looking exception from
1664 IPython, and the CrashHandler will only be triggered by real IPython
1664 IPython, and the CrashHandler will only be triggered by real IPython
1665 crashes.
1665 crashes.
1666
1666
1667 This hook should be used sparingly, only in places which are not likely
1667 This hook should be used sparingly, only in places which are not likely
1668 to be true IPython errors.
1668 to be true IPython errors.
1669 """
1669 """
1670 self.showtraceback((etype,value,tb),tb_offset=0)
1670 self.showtraceback((etype,value,tb),tb_offset=0)
1671
1671
1672 def _get_exc_info(self, exc_tuple=None):
1672 def _get_exc_info(self, exc_tuple=None):
1673 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1673 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1674
1674
1675 Ensures sys.last_type,value,traceback hold the exc_info we found,
1675 Ensures sys.last_type,value,traceback hold the exc_info we found,
1676 from whichever source.
1676 from whichever source.
1677
1677
1678 raises ValueError if none of these contain any information
1678 raises ValueError if none of these contain any information
1679 """
1679 """
1680 if exc_tuple is None:
1680 if exc_tuple is None:
1681 etype, value, tb = sys.exc_info()
1681 etype, value, tb = sys.exc_info()
1682 else:
1682 else:
1683 etype, value, tb = exc_tuple
1683 etype, value, tb = exc_tuple
1684
1684
1685 if etype is None:
1685 if etype is None:
1686 if hasattr(sys, 'last_type'):
1686 if hasattr(sys, 'last_type'):
1687 etype, value, tb = sys.last_type, sys.last_value, \
1687 etype, value, tb = sys.last_type, sys.last_value, \
1688 sys.last_traceback
1688 sys.last_traceback
1689
1689
1690 if etype is None:
1690 if etype is None:
1691 raise ValueError("No exception to find")
1691 raise ValueError("No exception to find")
1692
1692
1693 # Now store the exception info in sys.last_type etc.
1693 # Now store the exception info in sys.last_type etc.
1694 # WARNING: these variables are somewhat deprecated and not
1694 # WARNING: these variables are somewhat deprecated and not
1695 # necessarily safe to use in a threaded environment, but tools
1695 # necessarily safe to use in a threaded environment, but tools
1696 # like pdb depend on their existence, so let's set them. If we
1696 # like pdb depend on their existence, so let's set them. If we
1697 # find problems in the field, we'll need to revisit their use.
1697 # find problems in the field, we'll need to revisit their use.
1698 sys.last_type = etype
1698 sys.last_type = etype
1699 sys.last_value = value
1699 sys.last_value = value
1700 sys.last_traceback = tb
1700 sys.last_traceback = tb
1701
1701
1702 return etype, value, tb
1702 return etype, value, tb
1703
1703
1704
1704
1705 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1705 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1706 exception_only=False):
1706 exception_only=False):
1707 """Display the exception that just occurred.
1707 """Display the exception that just occurred.
1708
1708
1709 If nothing is known about the exception, this is the method which
1709 If nothing is known about the exception, this is the method which
1710 should be used throughout the code for presenting user tracebacks,
1710 should be used throughout the code for presenting user tracebacks,
1711 rather than directly invoking the InteractiveTB object.
1711 rather than directly invoking the InteractiveTB object.
1712
1712
1713 A specific showsyntaxerror() also exists, but this method can take
1713 A specific showsyntaxerror() also exists, but this method can take
1714 care of calling it if needed, so unless you are explicitly catching a
1714 care of calling it if needed, so unless you are explicitly catching a
1715 SyntaxError exception, don't try to analyze the stack manually and
1715 SyntaxError exception, don't try to analyze the stack manually and
1716 simply call this method."""
1716 simply call this method."""
1717
1717
1718 try:
1718 try:
1719 try:
1719 try:
1720 etype, value, tb = self._get_exc_info(exc_tuple)
1720 etype, value, tb = self._get_exc_info(exc_tuple)
1721 except ValueError:
1721 except ValueError:
1722 self.write_err('No traceback available to show.\n')
1722 self.write_err('No traceback available to show.\n')
1723 return
1723 return
1724
1724
1725 if etype is SyntaxError:
1725 if etype is SyntaxError:
1726 # Though this won't be called by syntax errors in the input
1726 # Though this won't be called by syntax errors in the input
1727 # line, there may be SyntaxError cases with imported code.
1727 # line, there may be SyntaxError cases with imported code.
1728 self.showsyntaxerror(filename)
1728 self.showsyntaxerror(filename)
1729 elif etype is UsageError:
1729 elif etype is UsageError:
1730 self.write_err("UsageError: %s" % value)
1730 self.write_err("UsageError: %s" % value)
1731 else:
1731 else:
1732 if exception_only:
1732 if exception_only:
1733 stb = ['An exception has occurred, use %tb to see '
1733 stb = ['An exception has occurred, use %tb to see '
1734 'the full traceback.\n']
1734 'the full traceback.\n']
1735 stb.extend(self.InteractiveTB.get_exception_only(etype,
1735 stb.extend(self.InteractiveTB.get_exception_only(etype,
1736 value))
1736 value))
1737 else:
1737 else:
1738 try:
1738 try:
1739 # Exception classes can customise their traceback - we
1739 # Exception classes can customise their traceback - we
1740 # use this in IPython.parallel for exceptions occurring
1740 # use this in IPython.parallel for exceptions occurring
1741 # in the engines. This should return a list of strings.
1741 # in the engines. This should return a list of strings.
1742 stb = value._render_traceback_()
1742 stb = value._render_traceback_()
1743 except Exception:
1743 except Exception:
1744 stb = self.InteractiveTB.structured_traceback(etype,
1744 stb = self.InteractiveTB.structured_traceback(etype,
1745 value, tb, tb_offset=tb_offset)
1745 value, tb, tb_offset=tb_offset)
1746
1746
1747 self._showtraceback(etype, value, stb)
1747 self._showtraceback(etype, value, stb)
1748 if self.call_pdb:
1748 if self.call_pdb:
1749 # drop into debugger
1749 # drop into debugger
1750 self.debugger(force=True)
1750 self.debugger(force=True)
1751 return
1751 return
1752
1752
1753 # Actually show the traceback
1753 # Actually show the traceback
1754 self._showtraceback(etype, value, stb)
1754 self._showtraceback(etype, value, stb)
1755
1755
1756 except KeyboardInterrupt:
1756 except KeyboardInterrupt:
1757 self.write_err("\nKeyboardInterrupt\n")
1757 self.write_err("\nKeyboardInterrupt\n")
1758
1758
1759 def _showtraceback(self, etype, evalue, stb):
1759 def _showtraceback(self, etype, evalue, stb):
1760 """Actually show a traceback.
1760 """Actually show a traceback.
1761
1761
1762 Subclasses may override this method to put the traceback on a different
1762 Subclasses may override this method to put the traceback on a different
1763 place, like a side channel.
1763 place, like a side channel.
1764 """
1764 """
1765 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1765 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1766
1766
1767 def showsyntaxerror(self, filename=None):
1767 def showsyntaxerror(self, filename=None):
1768 """Display the syntax error that just occurred.
1768 """Display the syntax error that just occurred.
1769
1769
1770 This doesn't display a stack trace because there isn't one.
1770 This doesn't display a stack trace because there isn't one.
1771
1771
1772 If a filename is given, it is stuffed in the exception instead
1772 If a filename is given, it is stuffed in the exception instead
1773 of what was there before (because Python's parser always uses
1773 of what was there before (because Python's parser always uses
1774 "<string>" when reading from a string).
1774 "<string>" when reading from a string).
1775 """
1775 """
1776 etype, value, last_traceback = self._get_exc_info()
1776 etype, value, last_traceback = self._get_exc_info()
1777
1777
1778 if filename and etype is SyntaxError:
1778 if filename and etype is SyntaxError:
1779 try:
1779 try:
1780 value.filename = filename
1780 value.filename = filename
1781 except:
1781 except:
1782 # Not the format we expect; leave it alone
1782 # Not the format we expect; leave it alone
1783 pass
1783 pass
1784
1784
1785 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1785 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1786 self._showtraceback(etype, value, stb)
1786 self._showtraceback(etype, value, stb)
1787
1787
1788 # This is overridden in TerminalInteractiveShell to show a message about
1788 # This is overridden in TerminalInteractiveShell to show a message about
1789 # the %paste magic.
1789 # the %paste magic.
1790 def showindentationerror(self):
1790 def showindentationerror(self):
1791 """Called by run_cell when there's an IndentationError in code entered
1791 """Called by run_cell when there's an IndentationError in code entered
1792 at the prompt.
1792 at the prompt.
1793
1793
1794 This is overridden in TerminalInteractiveShell to show a message about
1794 This is overridden in TerminalInteractiveShell to show a message about
1795 the %paste magic."""
1795 the %paste magic."""
1796 self.showsyntaxerror()
1796 self.showsyntaxerror()
1797
1797
1798 #-------------------------------------------------------------------------
1798 #-------------------------------------------------------------------------
1799 # Things related to readline
1799 # Things related to readline
1800 #-------------------------------------------------------------------------
1800 #-------------------------------------------------------------------------
1801
1801
1802 def init_readline(self):
1802 def init_readline(self):
1803 """Command history completion/saving/reloading."""
1803 """Command history completion/saving/reloading."""
1804
1804
1805 if self.readline_use:
1805 if self.readline_use:
1806 import IPython.utils.rlineimpl as readline
1806 import IPython.utils.rlineimpl as readline
1807
1807
1808 self.rl_next_input = None
1808 self.rl_next_input = None
1809 self.rl_do_indent = False
1809 self.rl_do_indent = False
1810
1810
1811 if not self.readline_use or not readline.have_readline:
1811 if not self.readline_use or not readline.have_readline:
1812 self.has_readline = False
1812 self.has_readline = False
1813 self.readline = None
1813 self.readline = None
1814 # Set a number of methods that depend on readline to be no-op
1814 # Set a number of methods that depend on readline to be no-op
1815 self.readline_no_record = no_op_context
1815 self.readline_no_record = no_op_context
1816 self.set_readline_completer = no_op
1816 self.set_readline_completer = no_op
1817 self.set_custom_completer = no_op
1817 self.set_custom_completer = no_op
1818 if self.readline_use:
1818 if self.readline_use:
1819 warn('Readline services not available or not loaded.')
1819 warn('Readline services not available or not loaded.')
1820 else:
1820 else:
1821 self.has_readline = True
1821 self.has_readline = True
1822 self.readline = readline
1822 self.readline = readline
1823 sys.modules['readline'] = readline
1823 sys.modules['readline'] = readline
1824
1824
1825 # Platform-specific configuration
1825 # Platform-specific configuration
1826 if os.name == 'nt':
1826 if os.name == 'nt':
1827 # FIXME - check with Frederick to see if we can harmonize
1827 # FIXME - check with Frederick to see if we can harmonize
1828 # naming conventions with pyreadline to avoid this
1828 # naming conventions with pyreadline to avoid this
1829 # platform-dependent check
1829 # platform-dependent check
1830 self.readline_startup_hook = readline.set_pre_input_hook
1830 self.readline_startup_hook = readline.set_pre_input_hook
1831 else:
1831 else:
1832 self.readline_startup_hook = readline.set_startup_hook
1832 self.readline_startup_hook = readline.set_startup_hook
1833
1833
1834 # Load user's initrc file (readline config)
1834 # Load user's initrc file (readline config)
1835 # Or if libedit is used, load editrc.
1835 # Or if libedit is used, load editrc.
1836 inputrc_name = os.environ.get('INPUTRC')
1836 inputrc_name = os.environ.get('INPUTRC')
1837 if inputrc_name is None:
1837 if inputrc_name is None:
1838 inputrc_name = '.inputrc'
1838 inputrc_name = '.inputrc'
1839 if readline.uses_libedit:
1839 if readline.uses_libedit:
1840 inputrc_name = '.editrc'
1840 inputrc_name = '.editrc'
1841 inputrc_name = os.path.join(self.home_dir, inputrc_name)
1841 inputrc_name = os.path.join(self.home_dir, inputrc_name)
1842 if os.path.isfile(inputrc_name):
1842 if os.path.isfile(inputrc_name):
1843 try:
1843 try:
1844 readline.read_init_file(inputrc_name)
1844 readline.read_init_file(inputrc_name)
1845 except:
1845 except:
1846 warn('Problems reading readline initialization file <%s>'
1846 warn('Problems reading readline initialization file <%s>'
1847 % inputrc_name)
1847 % inputrc_name)
1848
1848
1849 # Configure readline according to user's prefs
1849 # Configure readline according to user's prefs
1850 # This is only done if GNU readline is being used. If libedit
1850 # This is only done if GNU readline is being used. If libedit
1851 # is being used (as on Leopard) the readline config is
1851 # is being used (as on Leopard) the readline config is
1852 # not run as the syntax for libedit is different.
1852 # not run as the syntax for libedit is different.
1853 if not readline.uses_libedit:
1853 if not readline.uses_libedit:
1854 for rlcommand in self.readline_parse_and_bind:
1854 for rlcommand in self.readline_parse_and_bind:
1855 #print "loading rl:",rlcommand # dbg
1855 #print "loading rl:",rlcommand # dbg
1856 readline.parse_and_bind(rlcommand)
1856 readline.parse_and_bind(rlcommand)
1857
1857
1858 # Remove some chars from the delimiters list. If we encounter
1858 # Remove some chars from the delimiters list. If we encounter
1859 # unicode chars, discard them.
1859 # unicode chars, discard them.
1860 delims = readline.get_completer_delims()
1860 delims = readline.get_completer_delims()
1861 if not py3compat.PY3:
1861 if not py3compat.PY3:
1862 delims = delims.encode("ascii", "ignore")
1862 delims = delims.encode("ascii", "ignore")
1863 for d in self.readline_remove_delims:
1863 for d in self.readline_remove_delims:
1864 delims = delims.replace(d, "")
1864 delims = delims.replace(d, "")
1865 delims = delims.replace(ESC_MAGIC, '')
1865 delims = delims.replace(ESC_MAGIC, '')
1866 readline.set_completer_delims(delims)
1866 readline.set_completer_delims(delims)
1867 # otherwise we end up with a monster history after a while:
1867 # otherwise we end up with a monster history after a while:
1868 readline.set_history_length(self.history_length)
1868 readline.set_history_length(self.history_length)
1869
1869
1870 self.refill_readline_hist()
1870 self.refill_readline_hist()
1871 self.readline_no_record = ReadlineNoRecord(self)
1871 self.readline_no_record = ReadlineNoRecord(self)
1872
1872
1873 # Configure auto-indent for all platforms
1873 # Configure auto-indent for all platforms
1874 self.set_autoindent(self.autoindent)
1874 self.set_autoindent(self.autoindent)
1875
1875
1876 def refill_readline_hist(self):
1876 def refill_readline_hist(self):
1877 # Load the last 1000 lines from history
1877 # Load the last 1000 lines from history
1878 self.readline.clear_history()
1878 self.readline.clear_history()
1879 stdin_encoding = sys.stdin.encoding or "utf-8"
1879 stdin_encoding = sys.stdin.encoding or "utf-8"
1880 last_cell = u""
1880 last_cell = u""
1881 for _, _, cell in self.history_manager.get_tail(1000,
1881 for _, _, cell in self.history_manager.get_tail(1000,
1882 include_latest=True):
1882 include_latest=True):
1883 # Ignore blank lines and consecutive duplicates
1883 # Ignore blank lines and consecutive duplicates
1884 cell = cell.rstrip()
1884 cell = cell.rstrip()
1885 if cell and (cell != last_cell):
1885 if cell and (cell != last_cell):
1886 if self.multiline_history:
1886 if self.multiline_history:
1887 self.readline.add_history(py3compat.unicode_to_str(cell,
1887 self.readline.add_history(py3compat.unicode_to_str(cell,
1888 stdin_encoding))
1888 stdin_encoding))
1889 else:
1889 else:
1890 for line in cell.splitlines():
1890 for line in cell.splitlines():
1891 self.readline.add_history(py3compat.unicode_to_str(line,
1891 self.readline.add_history(py3compat.unicode_to_str(line,
1892 stdin_encoding))
1892 stdin_encoding))
1893 last_cell = cell
1893 last_cell = cell
1894
1894
1895 def set_next_input(self, s):
1895 def set_next_input(self, s):
1896 """ Sets the 'default' input string for the next command line.
1896 """ Sets the 'default' input string for the next command line.
1897
1897
1898 Requires readline.
1898 Requires readline.
1899
1899
1900 Example:
1900 Example:
1901
1901
1902 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1902 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1903 [D:\ipython]|2> Hello Word_ # cursor is here
1903 [D:\ipython]|2> Hello Word_ # cursor is here
1904 """
1904 """
1905 self.rl_next_input = py3compat.cast_bytes_py2(s)
1905 self.rl_next_input = py3compat.cast_bytes_py2(s)
1906
1906
1907 # Maybe move this to the terminal subclass?
1907 # Maybe move this to the terminal subclass?
1908 def pre_readline(self):
1908 def pre_readline(self):
1909 """readline hook to be used at the start of each line.
1909 """readline hook to be used at the start of each line.
1910
1910
1911 Currently it handles auto-indent only."""
1911 Currently it handles auto-indent only."""
1912
1912
1913 if self.rl_do_indent:
1913 if self.rl_do_indent:
1914 self.readline.insert_text(self._indent_current_str())
1914 self.readline.insert_text(self._indent_current_str())
1915 if self.rl_next_input is not None:
1915 if self.rl_next_input is not None:
1916 self.readline.insert_text(self.rl_next_input)
1916 self.readline.insert_text(self.rl_next_input)
1917 self.rl_next_input = None
1917 self.rl_next_input = None
1918
1918
1919 def _indent_current_str(self):
1919 def _indent_current_str(self):
1920 """return the current level of indentation as a string"""
1920 """return the current level of indentation as a string"""
1921 return self.input_splitter.indent_spaces * ' '
1921 return self.input_splitter.indent_spaces * ' '
1922
1922
1923 #-------------------------------------------------------------------------
1923 #-------------------------------------------------------------------------
1924 # Things related to text completion
1924 # Things related to text completion
1925 #-------------------------------------------------------------------------
1925 #-------------------------------------------------------------------------
1926
1926
1927 def init_completer(self):
1927 def init_completer(self):
1928 """Initialize the completion machinery.
1928 """Initialize the completion machinery.
1929
1929
1930 This creates completion machinery that can be used by client code,
1930 This creates completion machinery that can be used by client code,
1931 either interactively in-process (typically triggered by the readline
1931 either interactively in-process (typically triggered by the readline
1932 library), programatically (such as in test suites) or out-of-prcess
1932 library), programatically (such as in test suites) or out-of-prcess
1933 (typically over the network by remote frontends).
1933 (typically over the network by remote frontends).
1934 """
1934 """
1935 from IPython.core.completer import IPCompleter
1935 from IPython.core.completer import IPCompleter
1936 from IPython.core.completerlib import (module_completer,
1936 from IPython.core.completerlib import (module_completer,
1937 magic_run_completer, cd_completer, reset_completer)
1937 magic_run_completer, cd_completer, reset_completer)
1938
1938
1939 self.Completer = IPCompleter(shell=self,
1939 self.Completer = IPCompleter(shell=self,
1940 namespace=self.user_ns,
1940 namespace=self.user_ns,
1941 global_namespace=self.user_global_ns,
1941 global_namespace=self.user_global_ns,
1942 alias_table=self.alias_manager.alias_table,
1942 alias_table=self.alias_manager.alias_table,
1943 use_readline=self.has_readline,
1943 use_readline=self.has_readline,
1944 config=self.config,
1944 config=self.config,
1945 )
1945 )
1946 self.configurables.append(self.Completer)
1946 self.configurables.append(self.Completer)
1947
1947
1948 # Add custom completers to the basic ones built into IPCompleter
1948 # Add custom completers to the basic ones built into IPCompleter
1949 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1949 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1950 self.strdispatchers['complete_command'] = sdisp
1950 self.strdispatchers['complete_command'] = sdisp
1951 self.Completer.custom_completers = sdisp
1951 self.Completer.custom_completers = sdisp
1952
1952
1953 self.set_hook('complete_command', module_completer, str_key = 'import')
1953 self.set_hook('complete_command', module_completer, str_key = 'import')
1954 self.set_hook('complete_command', module_completer, str_key = 'from')
1954 self.set_hook('complete_command', module_completer, str_key = 'from')
1955 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1955 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1956 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1956 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1957 self.set_hook('complete_command', reset_completer, str_key = '%reset')
1957 self.set_hook('complete_command', reset_completer, str_key = '%reset')
1958
1958
1959 # Only configure readline if we truly are using readline. IPython can
1959 # Only configure readline if we truly are using readline. IPython can
1960 # do tab-completion over the network, in GUIs, etc, where readline
1960 # do tab-completion over the network, in GUIs, etc, where readline
1961 # itself may be absent
1961 # itself may be absent
1962 if self.has_readline:
1962 if self.has_readline:
1963 self.set_readline_completer()
1963 self.set_readline_completer()
1964
1964
1965 def complete(self, text, line=None, cursor_pos=None):
1965 def complete(self, text, line=None, cursor_pos=None):
1966 """Return the completed text and a list of completions.
1966 """Return the completed text and a list of completions.
1967
1967
1968 Parameters
1968 Parameters
1969 ----------
1969 ----------
1970
1970
1971 text : string
1971 text : string
1972 A string of text to be completed on. It can be given as empty and
1972 A string of text to be completed on. It can be given as empty and
1973 instead a line/position pair are given. In this case, the
1973 instead a line/position pair are given. In this case, the
1974 completer itself will split the line like readline does.
1974 completer itself will split the line like readline does.
1975
1975
1976 line : string, optional
1976 line : string, optional
1977 The complete line that text is part of.
1977 The complete line that text is part of.
1978
1978
1979 cursor_pos : int, optional
1979 cursor_pos : int, optional
1980 The position of the cursor on the input line.
1980 The position of the cursor on the input line.
1981
1981
1982 Returns
1982 Returns
1983 -------
1983 -------
1984 text : string
1984 text : string
1985 The actual text that was completed.
1985 The actual text that was completed.
1986
1986
1987 matches : list
1987 matches : list
1988 A sorted list with all possible completions.
1988 A sorted list with all possible completions.
1989
1989
1990 The optional arguments allow the completion to take more context into
1990 The optional arguments allow the completion to take more context into
1991 account, and are part of the low-level completion API.
1991 account, and are part of the low-level completion API.
1992
1992
1993 This is a wrapper around the completion mechanism, similar to what
1993 This is a wrapper around the completion mechanism, similar to what
1994 readline does at the command line when the TAB key is hit. By
1994 readline does at the command line when the TAB key is hit. By
1995 exposing it as a method, it can be used by other non-readline
1995 exposing it as a method, it can be used by other non-readline
1996 environments (such as GUIs) for text completion.
1996 environments (such as GUIs) for text completion.
1997
1997
1998 Simple usage example:
1998 Simple usage example:
1999
1999
2000 In [1]: x = 'hello'
2000 In [1]: x = 'hello'
2001
2001
2002 In [2]: _ip.complete('x.l')
2002 In [2]: _ip.complete('x.l')
2003 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2003 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2004 """
2004 """
2005
2005
2006 # Inject names into __builtin__ so we can complete on the added names.
2006 # Inject names into __builtin__ so we can complete on the added names.
2007 with self.builtin_trap:
2007 with self.builtin_trap:
2008 return self.Completer.complete(text, line, cursor_pos)
2008 return self.Completer.complete(text, line, cursor_pos)
2009
2009
2010 def set_custom_completer(self, completer, pos=0):
2010 def set_custom_completer(self, completer, pos=0):
2011 """Adds a new custom completer function.
2011 """Adds a new custom completer function.
2012
2012
2013 The position argument (defaults to 0) is the index in the completers
2013 The position argument (defaults to 0) is the index in the completers
2014 list where you want the completer to be inserted."""
2014 list where you want the completer to be inserted."""
2015
2015
2016 newcomp = types.MethodType(completer,self.Completer)
2016 newcomp = types.MethodType(completer,self.Completer)
2017 self.Completer.matchers.insert(pos,newcomp)
2017 self.Completer.matchers.insert(pos,newcomp)
2018
2018
2019 def set_readline_completer(self):
2019 def set_readline_completer(self):
2020 """Reset readline's completer to be our own."""
2020 """Reset readline's completer to be our own."""
2021 self.readline.set_completer(self.Completer.rlcomplete)
2021 self.readline.set_completer(self.Completer.rlcomplete)
2022
2022
2023 def set_completer_frame(self, frame=None):
2023 def set_completer_frame(self, frame=None):
2024 """Set the frame of the completer."""
2024 """Set the frame of the completer."""
2025 if frame:
2025 if frame:
2026 self.Completer.namespace = frame.f_locals
2026 self.Completer.namespace = frame.f_locals
2027 self.Completer.global_namespace = frame.f_globals
2027 self.Completer.global_namespace = frame.f_globals
2028 else:
2028 else:
2029 self.Completer.namespace = self.user_ns
2029 self.Completer.namespace = self.user_ns
2030 self.Completer.global_namespace = self.user_global_ns
2030 self.Completer.global_namespace = self.user_global_ns
2031
2031
2032 #-------------------------------------------------------------------------
2032 #-------------------------------------------------------------------------
2033 # Things related to magics
2033 # Things related to magics
2034 #-------------------------------------------------------------------------
2034 #-------------------------------------------------------------------------
2035
2035
2036 def init_magics(self):
2036 def init_magics(self):
2037 from IPython.core import magics as m
2037 from IPython.core import magics as m
2038 self.magics_manager = magic.MagicsManager(shell=self,
2038 self.magics_manager = magic.MagicsManager(shell=self,
2039 confg=self.config,
2039 confg=self.config,
2040 user_magics=m.UserMagics(self))
2040 user_magics=m.UserMagics(self))
2041 self.configurables.append(self.magics_manager)
2041 self.configurables.append(self.magics_manager)
2042
2042
2043 # Expose as public API from the magics manager
2043 # Expose as public API from the magics manager
2044 self.register_magics = self.magics_manager.register
2044 self.register_magics = self.magics_manager.register
2045 self.register_magic_function = self.magics_manager.register_function
2045 self.register_magic_function = self.magics_manager.register_function
2046 self.define_magic = self.magics_manager.define_magic
2046 self.define_magic = self.magics_manager.define_magic
2047
2047
2048 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2048 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2049 m.ConfigMagics, m.DeprecatedMagics, m.DisplayMagics, m.ExecutionMagics,
2049 m.ConfigMagics, m.DeprecatedMagics, m.DisplayMagics, m.ExecutionMagics,
2050 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2050 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2051 m.NamespaceMagics, m.OSMagics, m.PylabMagics, m.ScriptMagics,
2051 m.NamespaceMagics, m.OSMagics, m.PylabMagics, m.ScriptMagics,
2052 )
2052 )
2053
2053
2054 # Register Magic Aliases
2054 # Register Magic Aliases
2055 mman = self.magics_manager
2055 mman = self.magics_manager
2056 mman.register_alias('ed', 'edit')
2056 mman.register_alias('ed', 'edit')
2057 mman.register_alias('hist', 'history')
2057 mman.register_alias('hist', 'history')
2058 mman.register_alias('rep', 'recall')
2058 mman.register_alias('rep', 'recall')
2059
2059
2060 # FIXME: Move the color initialization to the DisplayHook, which
2060 # FIXME: Move the color initialization to the DisplayHook, which
2061 # should be split into a prompt manager and displayhook. We probably
2061 # should be split into a prompt manager and displayhook. We probably
2062 # even need a centralize colors management object.
2062 # even need a centralize colors management object.
2063 self.magic('colors %s' % self.colors)
2063 self.magic('colors %s' % self.colors)
2064
2064
2065 def run_line_magic(self, magic_name, line):
2065 def run_line_magic(self, magic_name, line):
2066 """Execute the given line magic.
2066 """Execute the given line magic.
2067
2067
2068 Parameters
2068 Parameters
2069 ----------
2069 ----------
2070 magic_name : str
2070 magic_name : str
2071 Name of the desired magic function, without '%' prefix.
2071 Name of the desired magic function, without '%' prefix.
2072
2072
2073 line : str
2073 line : str
2074 The rest of the input line as a single string.
2074 The rest of the input line as a single string.
2075 """
2075 """
2076 fn = self.find_line_magic(magic_name)
2076 fn = self.find_line_magic(magic_name)
2077 if fn is None:
2077 if fn is None:
2078 cm = self.find_cell_magic(magic_name)
2078 cm = self.find_cell_magic(magic_name)
2079 etpl = "Line magic function `%%%s` not found%s."
2079 etpl = "Line magic function `%%%s` not found%s."
2080 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2080 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2081 'did you mean that instead?)' % magic_name )
2081 'did you mean that instead?)' % magic_name )
2082 error(etpl % (magic_name, extra))
2082 error(etpl % (magic_name, extra))
2083 else:
2083 else:
2084 # Note: this is the distance in the stack to the user's frame.
2084 # Note: this is the distance in the stack to the user's frame.
2085 # This will need to be updated if the internal calling logic gets
2085 # This will need to be updated if the internal calling logic gets
2086 # refactored, or else we'll be expanding the wrong variables.
2086 # refactored, or else we'll be expanding the wrong variables.
2087 stack_depth = 2
2087 stack_depth = 2
2088 magic_arg_s = self.var_expand(line, stack_depth)
2088 magic_arg_s = self.var_expand(line, stack_depth)
2089 # Put magic args in a list so we can call with f(*a) syntax
2089 # Put magic args in a list so we can call with f(*a) syntax
2090 args = [magic_arg_s]
2090 args = [magic_arg_s]
2091 kwargs = {}
2091 # Grab local namespace if we need it:
2092 # Grab local namespace if we need it:
2092 if getattr(fn, "needs_local_scope", False):
2093 if getattr(fn, "needs_local_scope", False):
2093 args.append(sys._getframe(stack_depth).f_locals)
2094 kwargs['local_ns'] = sys._getframe(stack_depth).f_locals
2094 with self.builtin_trap:
2095 with self.builtin_trap:
2095 result = fn(*args)
2096 result = fn(*args,**kwargs)
2096 return result
2097 return result
2097
2098
2098 def run_cell_magic(self, magic_name, line, cell):
2099 def run_cell_magic(self, magic_name, line, cell):
2099 """Execute the given cell magic.
2100 """Execute the given cell magic.
2100
2101
2101 Parameters
2102 Parameters
2102 ----------
2103 ----------
2103 magic_name : str
2104 magic_name : str
2104 Name of the desired magic function, without '%' prefix.
2105 Name of the desired magic function, without '%' prefix.
2105
2106
2106 line : str
2107 line : str
2107 The rest of the first input line as a single string.
2108 The rest of the first input line as a single string.
2108
2109
2109 cell : str
2110 cell : str
2110 The body of the cell as a (possibly multiline) string.
2111 The body of the cell as a (possibly multiline) string.
2111 """
2112 """
2112 fn = self.find_cell_magic(magic_name)
2113 fn = self.find_cell_magic(magic_name)
2113 if fn is None:
2114 if fn is None:
2114 lm = self.find_line_magic(magic_name)
2115 lm = self.find_line_magic(magic_name)
2115 etpl = "Cell magic function `%%%%%s` not found%s."
2116 etpl = "Cell magic function `%%%%%s` not found%s."
2116 extra = '' if lm is None else (' (But line magic `%%%s` exists, '
2117 extra = '' if lm is None else (' (But line magic `%%%s` exists, '
2117 'did you mean that instead?)' % magic_name )
2118 'did you mean that instead?)' % magic_name )
2118 error(etpl % (magic_name, extra))
2119 error(etpl % (magic_name, extra))
2119 else:
2120 else:
2120 # Note: this is the distance in the stack to the user's frame.
2121 # Note: this is the distance in the stack to the user's frame.
2121 # This will need to be updated if the internal calling logic gets
2122 # This will need to be updated if the internal calling logic gets
2122 # refactored, or else we'll be expanding the wrong variables.
2123 # refactored, or else we'll be expanding the wrong variables.
2123 stack_depth = 2
2124 stack_depth = 2
2124 magic_arg_s = self.var_expand(line, stack_depth)
2125 magic_arg_s = self.var_expand(line, stack_depth)
2125 with self.builtin_trap:
2126 with self.builtin_trap:
2126 result = fn(magic_arg_s, cell)
2127 result = fn(magic_arg_s, cell)
2127 return result
2128 return result
2128
2129
2129 def find_line_magic(self, magic_name):
2130 def find_line_magic(self, magic_name):
2130 """Find and return a line magic by name.
2131 """Find and return a line magic by name.
2131
2132
2132 Returns None if the magic isn't found."""
2133 Returns None if the magic isn't found."""
2133 return self.magics_manager.magics['line'].get(magic_name)
2134 return self.magics_manager.magics['line'].get(magic_name)
2134
2135
2135 def find_cell_magic(self, magic_name):
2136 def find_cell_magic(self, magic_name):
2136 """Find and return a cell magic by name.
2137 """Find and return a cell magic by name.
2137
2138
2138 Returns None if the magic isn't found."""
2139 Returns None if the magic isn't found."""
2139 return self.magics_manager.magics['cell'].get(magic_name)
2140 return self.magics_manager.magics['cell'].get(magic_name)
2140
2141
2141 def find_magic(self, magic_name, magic_kind='line'):
2142 def find_magic(self, magic_name, magic_kind='line'):
2142 """Find and return a magic of the given type by name.
2143 """Find and return a magic of the given type by name.
2143
2144
2144 Returns None if the magic isn't found."""
2145 Returns None if the magic isn't found."""
2145 return self.magics_manager.magics[magic_kind].get(magic_name)
2146 return self.magics_manager.magics[magic_kind].get(magic_name)
2146
2147
2147 def magic(self, arg_s):
2148 def magic(self, arg_s):
2148 """DEPRECATED. Use run_line_magic() instead.
2149 """DEPRECATED. Use run_line_magic() instead.
2149
2150
2150 Call a magic function by name.
2151 Call a magic function by name.
2151
2152
2152 Input: a string containing the name of the magic function to call and
2153 Input: a string containing the name of the magic function to call and
2153 any additional arguments to be passed to the magic.
2154 any additional arguments to be passed to the magic.
2154
2155
2155 magic('name -opt foo bar') is equivalent to typing at the ipython
2156 magic('name -opt foo bar') is equivalent to typing at the ipython
2156 prompt:
2157 prompt:
2157
2158
2158 In[1]: %name -opt foo bar
2159 In[1]: %name -opt foo bar
2159
2160
2160 To call a magic without arguments, simply use magic('name').
2161 To call a magic without arguments, simply use magic('name').
2161
2162
2162 This provides a proper Python function to call IPython's magics in any
2163 This provides a proper Python function to call IPython's magics in any
2163 valid Python code you can type at the interpreter, including loops and
2164 valid Python code you can type at the interpreter, including loops and
2164 compound statements.
2165 compound statements.
2165 """
2166 """
2166 # TODO: should we issue a loud deprecation warning here?
2167 # TODO: should we issue a loud deprecation warning here?
2167 magic_name, _, magic_arg_s = arg_s.partition(' ')
2168 magic_name, _, magic_arg_s = arg_s.partition(' ')
2168 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2169 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2169 return self.run_line_magic(magic_name, magic_arg_s)
2170 return self.run_line_magic(magic_name, magic_arg_s)
2170
2171
2171 #-------------------------------------------------------------------------
2172 #-------------------------------------------------------------------------
2172 # Things related to macros
2173 # Things related to macros
2173 #-------------------------------------------------------------------------
2174 #-------------------------------------------------------------------------
2174
2175
2175 def define_macro(self, name, themacro):
2176 def define_macro(self, name, themacro):
2176 """Define a new macro
2177 """Define a new macro
2177
2178
2178 Parameters
2179 Parameters
2179 ----------
2180 ----------
2180 name : str
2181 name : str
2181 The name of the macro.
2182 The name of the macro.
2182 themacro : str or Macro
2183 themacro : str or Macro
2183 The action to do upon invoking the macro. If a string, a new
2184 The action to do upon invoking the macro. If a string, a new
2184 Macro object is created by passing the string to it.
2185 Macro object is created by passing the string to it.
2185 """
2186 """
2186
2187
2187 from IPython.core import macro
2188 from IPython.core import macro
2188
2189
2189 if isinstance(themacro, basestring):
2190 if isinstance(themacro, basestring):
2190 themacro = macro.Macro(themacro)
2191 themacro = macro.Macro(themacro)
2191 if not isinstance(themacro, macro.Macro):
2192 if not isinstance(themacro, macro.Macro):
2192 raise ValueError('A macro must be a string or a Macro instance.')
2193 raise ValueError('A macro must be a string or a Macro instance.')
2193 self.user_ns[name] = themacro
2194 self.user_ns[name] = themacro
2194
2195
2195 #-------------------------------------------------------------------------
2196 #-------------------------------------------------------------------------
2196 # Things related to the running of system commands
2197 # Things related to the running of system commands
2197 #-------------------------------------------------------------------------
2198 #-------------------------------------------------------------------------
2198
2199
2199 def system_piped(self, cmd):
2200 def system_piped(self, cmd):
2200 """Call the given cmd in a subprocess, piping stdout/err
2201 """Call the given cmd in a subprocess, piping stdout/err
2201
2202
2202 Parameters
2203 Parameters
2203 ----------
2204 ----------
2204 cmd : str
2205 cmd : str
2205 Command to execute (can not end in '&', as background processes are
2206 Command to execute (can not end in '&', as background processes are
2206 not supported. Should not be a command that expects input
2207 not supported. Should not be a command that expects input
2207 other than simple text.
2208 other than simple text.
2208 """
2209 """
2209 if cmd.rstrip().endswith('&'):
2210 if cmd.rstrip().endswith('&'):
2210 # this is *far* from a rigorous test
2211 # this is *far* from a rigorous test
2211 # We do not support backgrounding processes because we either use
2212 # We do not support backgrounding processes because we either use
2212 # pexpect or pipes to read from. Users can always just call
2213 # pexpect or pipes to read from. Users can always just call
2213 # os.system() or use ip.system=ip.system_raw
2214 # os.system() or use ip.system=ip.system_raw
2214 # if they really want a background process.
2215 # if they really want a background process.
2215 raise OSError("Background processes not supported.")
2216 raise OSError("Background processes not supported.")
2216
2217
2217 # we explicitly do NOT return the subprocess status code, because
2218 # we explicitly do NOT return the subprocess status code, because
2218 # a non-None value would trigger :func:`sys.displayhook` calls.
2219 # a non-None value would trigger :func:`sys.displayhook` calls.
2219 # Instead, we store the exit_code in user_ns.
2220 # Instead, we store the exit_code in user_ns.
2220 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2221 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2221
2222
2222 def system_raw(self, cmd):
2223 def system_raw(self, cmd):
2223 """Call the given cmd in a subprocess using os.system
2224 """Call the given cmd in a subprocess using os.system
2224
2225
2225 Parameters
2226 Parameters
2226 ----------
2227 ----------
2227 cmd : str
2228 cmd : str
2228 Command to execute.
2229 Command to execute.
2229 """
2230 """
2230 cmd = self.var_expand(cmd, depth=1)
2231 cmd = self.var_expand(cmd, depth=1)
2231 # protect os.system from UNC paths on Windows, which it can't handle:
2232 # protect os.system from UNC paths on Windows, which it can't handle:
2232 if sys.platform == 'win32':
2233 if sys.platform == 'win32':
2233 from IPython.utils._process_win32 import AvoidUNCPath
2234 from IPython.utils._process_win32 import AvoidUNCPath
2234 with AvoidUNCPath() as path:
2235 with AvoidUNCPath() as path:
2235 if path is not None:
2236 if path is not None:
2236 cmd = '"pushd %s &&"%s' % (path, cmd)
2237 cmd = '"pushd %s &&"%s' % (path, cmd)
2237 cmd = py3compat.unicode_to_str(cmd)
2238 cmd = py3compat.unicode_to_str(cmd)
2238 ec = os.system(cmd)
2239 ec = os.system(cmd)
2239 else:
2240 else:
2240 cmd = py3compat.unicode_to_str(cmd)
2241 cmd = py3compat.unicode_to_str(cmd)
2241 ec = os.system(cmd)
2242 ec = os.system(cmd)
2242
2243
2243 # We explicitly do NOT return the subprocess status code, because
2244 # We explicitly do NOT return the subprocess status code, because
2244 # a non-None value would trigger :func:`sys.displayhook` calls.
2245 # a non-None value would trigger :func:`sys.displayhook` calls.
2245 # Instead, we store the exit_code in user_ns.
2246 # Instead, we store the exit_code in user_ns.
2246 self.user_ns['_exit_code'] = ec
2247 self.user_ns['_exit_code'] = ec
2247
2248
2248 # use piped system by default, because it is better behaved
2249 # use piped system by default, because it is better behaved
2249 system = system_piped
2250 system = system_piped
2250
2251
2251 def getoutput(self, cmd, split=True, depth=0):
2252 def getoutput(self, cmd, split=True, depth=0):
2252 """Get output (possibly including stderr) from a subprocess.
2253 """Get output (possibly including stderr) from a subprocess.
2253
2254
2254 Parameters
2255 Parameters
2255 ----------
2256 ----------
2256 cmd : str
2257 cmd : str
2257 Command to execute (can not end in '&', as background processes are
2258 Command to execute (can not end in '&', as background processes are
2258 not supported.
2259 not supported.
2259 split : bool, optional
2260 split : bool, optional
2260 If True, split the output into an IPython SList. Otherwise, an
2261 If True, split the output into an IPython SList. Otherwise, an
2261 IPython LSString is returned. These are objects similar to normal
2262 IPython LSString is returned. These are objects similar to normal
2262 lists and strings, with a few convenience attributes for easier
2263 lists and strings, with a few convenience attributes for easier
2263 manipulation of line-based output. You can use '?' on them for
2264 manipulation of line-based output. You can use '?' on them for
2264 details.
2265 details.
2265 depth : int, optional
2266 depth : int, optional
2266 How many frames above the caller are the local variables which should
2267 How many frames above the caller are the local variables which should
2267 be expanded in the command string? The default (0) assumes that the
2268 be expanded in the command string? The default (0) assumes that the
2268 expansion variables are in the stack frame calling this function.
2269 expansion variables are in the stack frame calling this function.
2269 """
2270 """
2270 if cmd.rstrip().endswith('&'):
2271 if cmd.rstrip().endswith('&'):
2271 # this is *far* from a rigorous test
2272 # this is *far* from a rigorous test
2272 raise OSError("Background processes not supported.")
2273 raise OSError("Background processes not supported.")
2273 out = getoutput(self.var_expand(cmd, depth=depth+1))
2274 out = getoutput(self.var_expand(cmd, depth=depth+1))
2274 if split:
2275 if split:
2275 out = SList(out.splitlines())
2276 out = SList(out.splitlines())
2276 else:
2277 else:
2277 out = LSString(out)
2278 out = LSString(out)
2278 return out
2279 return out
2279
2280
2280 #-------------------------------------------------------------------------
2281 #-------------------------------------------------------------------------
2281 # Things related to aliases
2282 # Things related to aliases
2282 #-------------------------------------------------------------------------
2283 #-------------------------------------------------------------------------
2283
2284
2284 def init_alias(self):
2285 def init_alias(self):
2285 self.alias_manager = AliasManager(shell=self, config=self.config)
2286 self.alias_manager = AliasManager(shell=self, config=self.config)
2286 self.configurables.append(self.alias_manager)
2287 self.configurables.append(self.alias_manager)
2287 self.ns_table['alias'] = self.alias_manager.alias_table,
2288 self.ns_table['alias'] = self.alias_manager.alias_table,
2288
2289
2289 #-------------------------------------------------------------------------
2290 #-------------------------------------------------------------------------
2290 # Things related to extensions and plugins
2291 # Things related to extensions and plugins
2291 #-------------------------------------------------------------------------
2292 #-------------------------------------------------------------------------
2292
2293
2293 def init_extension_manager(self):
2294 def init_extension_manager(self):
2294 self.extension_manager = ExtensionManager(shell=self, config=self.config)
2295 self.extension_manager = ExtensionManager(shell=self, config=self.config)
2295 self.configurables.append(self.extension_manager)
2296 self.configurables.append(self.extension_manager)
2296
2297
2297 def init_plugin_manager(self):
2298 def init_plugin_manager(self):
2298 self.plugin_manager = PluginManager(config=self.config)
2299 self.plugin_manager = PluginManager(config=self.config)
2299 self.configurables.append(self.plugin_manager)
2300 self.configurables.append(self.plugin_manager)
2300
2301
2301
2302
2302 #-------------------------------------------------------------------------
2303 #-------------------------------------------------------------------------
2303 # Things related to payloads
2304 # Things related to payloads
2304 #-------------------------------------------------------------------------
2305 #-------------------------------------------------------------------------
2305
2306
2306 def init_payload(self):
2307 def init_payload(self):
2307 self.payload_manager = PayloadManager(config=self.config)
2308 self.payload_manager = PayloadManager(config=self.config)
2308 self.configurables.append(self.payload_manager)
2309 self.configurables.append(self.payload_manager)
2309
2310
2310 #-------------------------------------------------------------------------
2311 #-------------------------------------------------------------------------
2311 # Things related to the prefilter
2312 # Things related to the prefilter
2312 #-------------------------------------------------------------------------
2313 #-------------------------------------------------------------------------
2313
2314
2314 def init_prefilter(self):
2315 def init_prefilter(self):
2315 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
2316 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
2316 self.configurables.append(self.prefilter_manager)
2317 self.configurables.append(self.prefilter_manager)
2317 # Ultimately this will be refactored in the new interpreter code, but
2318 # Ultimately this will be refactored in the new interpreter code, but
2318 # for now, we should expose the main prefilter method (there's legacy
2319 # for now, we should expose the main prefilter method (there's legacy
2319 # code out there that may rely on this).
2320 # code out there that may rely on this).
2320 self.prefilter = self.prefilter_manager.prefilter_lines
2321 self.prefilter = self.prefilter_manager.prefilter_lines
2321
2322
2322 def auto_rewrite_input(self, cmd):
2323 def auto_rewrite_input(self, cmd):
2323 """Print to the screen the rewritten form of the user's command.
2324 """Print to the screen the rewritten form of the user's command.
2324
2325
2325 This shows visual feedback by rewriting input lines that cause
2326 This shows visual feedback by rewriting input lines that cause
2326 automatic calling to kick in, like::
2327 automatic calling to kick in, like::
2327
2328
2328 /f x
2329 /f x
2329
2330
2330 into::
2331 into::
2331
2332
2332 ------> f(x)
2333 ------> f(x)
2333
2334
2334 after the user's input prompt. This helps the user understand that the
2335 after the user's input prompt. This helps the user understand that the
2335 input line was transformed automatically by IPython.
2336 input line was transformed automatically by IPython.
2336 """
2337 """
2337 if not self.show_rewritten_input:
2338 if not self.show_rewritten_input:
2338 return
2339 return
2339
2340
2340 rw = self.prompt_manager.render('rewrite') + cmd
2341 rw = self.prompt_manager.render('rewrite') + cmd
2341
2342
2342 try:
2343 try:
2343 # plain ascii works better w/ pyreadline, on some machines, so
2344 # plain ascii works better w/ pyreadline, on some machines, so
2344 # we use it and only print uncolored rewrite if we have unicode
2345 # we use it and only print uncolored rewrite if we have unicode
2345 rw = str(rw)
2346 rw = str(rw)
2346 print(rw, file=io.stdout)
2347 print(rw, file=io.stdout)
2347 except UnicodeEncodeError:
2348 except UnicodeEncodeError:
2348 print("------> " + cmd)
2349 print("------> " + cmd)
2349
2350
2350 #-------------------------------------------------------------------------
2351 #-------------------------------------------------------------------------
2351 # Things related to extracting values/expressions from kernel and user_ns
2352 # Things related to extracting values/expressions from kernel and user_ns
2352 #-------------------------------------------------------------------------
2353 #-------------------------------------------------------------------------
2353
2354
2354 def _simple_error(self):
2355 def _simple_error(self):
2355 etype, value = sys.exc_info()[:2]
2356 etype, value = sys.exc_info()[:2]
2356 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
2357 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
2357
2358
2358 def user_variables(self, names):
2359 def user_variables(self, names):
2359 """Get a list of variable names from the user's namespace.
2360 """Get a list of variable names from the user's namespace.
2360
2361
2361 Parameters
2362 Parameters
2362 ----------
2363 ----------
2363 names : list of strings
2364 names : list of strings
2364 A list of names of variables to be read from the user namespace.
2365 A list of names of variables to be read from the user namespace.
2365
2366
2366 Returns
2367 Returns
2367 -------
2368 -------
2368 A dict, keyed by the input names and with the repr() of each value.
2369 A dict, keyed by the input names and with the repr() of each value.
2369 """
2370 """
2370 out = {}
2371 out = {}
2371 user_ns = self.user_ns
2372 user_ns = self.user_ns
2372 for varname in names:
2373 for varname in names:
2373 try:
2374 try:
2374 value = repr(user_ns[varname])
2375 value = repr(user_ns[varname])
2375 except:
2376 except:
2376 value = self._simple_error()
2377 value = self._simple_error()
2377 out[varname] = value
2378 out[varname] = value
2378 return out
2379 return out
2379
2380
2380 def user_expressions(self, expressions):
2381 def user_expressions(self, expressions):
2381 """Evaluate a dict of expressions in the user's namespace.
2382 """Evaluate a dict of expressions in the user's namespace.
2382
2383
2383 Parameters
2384 Parameters
2384 ----------
2385 ----------
2385 expressions : dict
2386 expressions : dict
2386 A dict with string keys and string values. The expression values
2387 A dict with string keys and string values. The expression values
2387 should be valid Python expressions, each of which will be evaluated
2388 should be valid Python expressions, each of which will be evaluated
2388 in the user namespace.
2389 in the user namespace.
2389
2390
2390 Returns
2391 Returns
2391 -------
2392 -------
2392 A dict, keyed like the input expressions dict, with the repr() of each
2393 A dict, keyed like the input expressions dict, with the repr() of each
2393 value.
2394 value.
2394 """
2395 """
2395 out = {}
2396 out = {}
2396 user_ns = self.user_ns
2397 user_ns = self.user_ns
2397 global_ns = self.user_global_ns
2398 global_ns = self.user_global_ns
2398 for key, expr in expressions.iteritems():
2399 for key, expr in expressions.iteritems():
2399 try:
2400 try:
2400 value = repr(eval(expr, global_ns, user_ns))
2401 value = repr(eval(expr, global_ns, user_ns))
2401 except:
2402 except:
2402 value = self._simple_error()
2403 value = self._simple_error()
2403 out[key] = value
2404 out[key] = value
2404 return out
2405 return out
2405
2406
2406 #-------------------------------------------------------------------------
2407 #-------------------------------------------------------------------------
2407 # Things related to the running of code
2408 # Things related to the running of code
2408 #-------------------------------------------------------------------------
2409 #-------------------------------------------------------------------------
2409
2410
2410 def ex(self, cmd):
2411 def ex(self, cmd):
2411 """Execute a normal python statement in user namespace."""
2412 """Execute a normal python statement in user namespace."""
2412 with self.builtin_trap:
2413 with self.builtin_trap:
2413 exec cmd in self.user_global_ns, self.user_ns
2414 exec cmd in self.user_global_ns, self.user_ns
2414
2415
2415 def ev(self, expr):
2416 def ev(self, expr):
2416 """Evaluate python expression expr in user namespace.
2417 """Evaluate python expression expr in user namespace.
2417
2418
2418 Returns the result of evaluation
2419 Returns the result of evaluation
2419 """
2420 """
2420 with self.builtin_trap:
2421 with self.builtin_trap:
2421 return eval(expr, self.user_global_ns, self.user_ns)
2422 return eval(expr, self.user_global_ns, self.user_ns)
2422
2423
2423 def safe_execfile(self, fname, *where, **kw):
2424 def safe_execfile(self, fname, *where, **kw):
2424 """A safe version of the builtin execfile().
2425 """A safe version of the builtin execfile().
2425
2426
2426 This version will never throw an exception, but instead print
2427 This version will never throw an exception, but instead print
2427 helpful error messages to the screen. This only works on pure
2428 helpful error messages to the screen. This only works on pure
2428 Python files with the .py extension.
2429 Python files with the .py extension.
2429
2430
2430 Parameters
2431 Parameters
2431 ----------
2432 ----------
2432 fname : string
2433 fname : string
2433 The name of the file to be executed.
2434 The name of the file to be executed.
2434 where : tuple
2435 where : tuple
2435 One or two namespaces, passed to execfile() as (globals,locals).
2436 One or two namespaces, passed to execfile() as (globals,locals).
2436 If only one is given, it is passed as both.
2437 If only one is given, it is passed as both.
2437 exit_ignore : bool (False)
2438 exit_ignore : bool (False)
2438 If True, then silence SystemExit for non-zero status (it is always
2439 If True, then silence SystemExit for non-zero status (it is always
2439 silenced for zero status, as it is so common).
2440 silenced for zero status, as it is so common).
2440 raise_exceptions : bool (False)
2441 raise_exceptions : bool (False)
2441 If True raise exceptions everywhere. Meant for testing.
2442 If True raise exceptions everywhere. Meant for testing.
2442
2443
2443 """
2444 """
2444 kw.setdefault('exit_ignore', False)
2445 kw.setdefault('exit_ignore', False)
2445 kw.setdefault('raise_exceptions', False)
2446 kw.setdefault('raise_exceptions', False)
2446
2447
2447 fname = os.path.abspath(os.path.expanduser(fname))
2448 fname = os.path.abspath(os.path.expanduser(fname))
2448
2449
2449 # Make sure we can open the file
2450 # Make sure we can open the file
2450 try:
2451 try:
2451 with open(fname) as thefile:
2452 with open(fname) as thefile:
2452 pass
2453 pass
2453 except:
2454 except:
2454 warn('Could not open file <%s> for safe execution.' % fname)
2455 warn('Could not open file <%s> for safe execution.' % fname)
2455 return
2456 return
2456
2457
2457 # Find things also in current directory. This is needed to mimic the
2458 # Find things also in current directory. This is needed to mimic the
2458 # behavior of running a script from the system command line, where
2459 # behavior of running a script from the system command line, where
2459 # Python inserts the script's directory into sys.path
2460 # Python inserts the script's directory into sys.path
2460 dname = os.path.dirname(fname)
2461 dname = os.path.dirname(fname)
2461
2462
2462 with prepended_to_syspath(dname):
2463 with prepended_to_syspath(dname):
2463 # Ensure that __file__ is always defined to match Python behavior
2464 # Ensure that __file__ is always defined to match Python behavior
2464 save_fname = self.user_ns.get('__file__',None)
2465 save_fname = self.user_ns.get('__file__',None)
2465 self.user_ns['__file__'] = fname
2466 self.user_ns['__file__'] = fname
2466 try:
2467 try:
2467 py3compat.execfile(fname,*where)
2468 py3compat.execfile(fname,*where)
2468 except SystemExit as status:
2469 except SystemExit as status:
2469 # If the call was made with 0 or None exit status (sys.exit(0)
2470 # If the call was made with 0 or None exit status (sys.exit(0)
2470 # or sys.exit() ), don't bother showing a traceback, as both of
2471 # or sys.exit() ), don't bother showing a traceback, as both of
2471 # these are considered normal by the OS:
2472 # these are considered normal by the OS:
2472 # > python -c'import sys;sys.exit(0)'; echo $?
2473 # > python -c'import sys;sys.exit(0)'; echo $?
2473 # 0
2474 # 0
2474 # > python -c'import sys;sys.exit()'; echo $?
2475 # > python -c'import sys;sys.exit()'; echo $?
2475 # 0
2476 # 0
2476 # For other exit status, we show the exception unless
2477 # For other exit status, we show the exception unless
2477 # explicitly silenced, but only in short form.
2478 # explicitly silenced, but only in short form.
2478 if kw['raise_exceptions']:
2479 if kw['raise_exceptions']:
2479 raise
2480 raise
2480 if status.code not in (0, None) and not kw['exit_ignore']:
2481 if status.code not in (0, None) and not kw['exit_ignore']:
2481 self.showtraceback(exception_only=True)
2482 self.showtraceback(exception_only=True)
2482 except:
2483 except:
2483 if kw['raise_exceptions']:
2484 if kw['raise_exceptions']:
2484 raise
2485 raise
2485 self.showtraceback()
2486 self.showtraceback()
2486 finally:
2487 finally:
2487 self.user_ns['__file__'] = save_fname
2488 self.user_ns['__file__'] = save_fname
2488
2489
2489 def safe_execfile_ipy(self, fname):
2490 def safe_execfile_ipy(self, fname):
2490 """Like safe_execfile, but for .ipy files with IPython syntax.
2491 """Like safe_execfile, but for .ipy files with IPython syntax.
2491
2492
2492 Parameters
2493 Parameters
2493 ----------
2494 ----------
2494 fname : str
2495 fname : str
2495 The name of the file to execute. The filename must have a
2496 The name of the file to execute. The filename must have a
2496 .ipy extension.
2497 .ipy extension.
2497 """
2498 """
2498 fname = os.path.abspath(os.path.expanduser(fname))
2499 fname = os.path.abspath(os.path.expanduser(fname))
2499
2500
2500 # Make sure we can open the file
2501 # Make sure we can open the file
2501 try:
2502 try:
2502 with open(fname) as thefile:
2503 with open(fname) as thefile:
2503 pass
2504 pass
2504 except:
2505 except:
2505 warn('Could not open file <%s> for safe execution.' % fname)
2506 warn('Could not open file <%s> for safe execution.' % fname)
2506 return
2507 return
2507
2508
2508 # Find things also in current directory. This is needed to mimic the
2509 # Find things also in current directory. This is needed to mimic the
2509 # behavior of running a script from the system command line, where
2510 # behavior of running a script from the system command line, where
2510 # Python inserts the script's directory into sys.path
2511 # Python inserts the script's directory into sys.path
2511 dname = os.path.dirname(fname)
2512 dname = os.path.dirname(fname)
2512
2513
2513 with prepended_to_syspath(dname):
2514 with prepended_to_syspath(dname):
2514 # Ensure that __file__ is always defined to match Python behavior
2515 # Ensure that __file__ is always defined to match Python behavior
2515 save_fname = self.user_ns.get('__file__',None)
2516 save_fname = self.user_ns.get('__file__',None)
2516 self.user_ns['__file__'] = fname
2517 self.user_ns['__file__'] = fname
2517 try:
2518 try:
2518 with open(fname) as thefile:
2519 with open(fname) as thefile:
2519 # self.run_cell currently captures all exceptions
2520 # self.run_cell currently captures all exceptions
2520 # raised in user code. It would be nice if there were
2521 # raised in user code. It would be nice if there were
2521 # versions of runlines, execfile that did raise, so
2522 # versions of runlines, execfile that did raise, so
2522 # we could catch the errors.
2523 # we could catch the errors.
2523 self.run_cell(thefile.read(), store_history=False)
2524 self.run_cell(thefile.read(), store_history=False)
2524 except:
2525 except:
2525 self.showtraceback()
2526 self.showtraceback()
2526 warn('Unknown failure executing file: <%s>' % fname)
2527 warn('Unknown failure executing file: <%s>' % fname)
2527 finally:
2528 finally:
2528 self.user_ns['__file__'] = save_fname
2529 self.user_ns['__file__'] = save_fname
2529
2530
2530 def safe_run_module(self, mod_name, where):
2531 def safe_run_module(self, mod_name, where):
2531 """A safe version of runpy.run_module().
2532 """A safe version of runpy.run_module().
2532
2533
2533 This version will never throw an exception, but instead print
2534 This version will never throw an exception, but instead print
2534 helpful error messages to the screen.
2535 helpful error messages to the screen.
2535
2536
2536 Parameters
2537 Parameters
2537 ----------
2538 ----------
2538 mod_name : string
2539 mod_name : string
2539 The name of the module to be executed.
2540 The name of the module to be executed.
2540 where : dict
2541 where : dict
2541 The globals namespace.
2542 The globals namespace.
2542 """
2543 """
2543 try:
2544 try:
2544 where.update(
2545 where.update(
2545 runpy.run_module(str(mod_name), run_name="__main__",
2546 runpy.run_module(str(mod_name), run_name="__main__",
2546 alter_sys=True)
2547 alter_sys=True)
2547 )
2548 )
2548 except:
2549 except:
2549 self.showtraceback()
2550 self.showtraceback()
2550 warn('Unknown failure executing module: <%s>' % mod_name)
2551 warn('Unknown failure executing module: <%s>' % mod_name)
2551
2552
2552 def _run_cached_cell_magic(self, magic_name, line):
2553 def _run_cached_cell_magic(self, magic_name, line):
2553 """Special method to call a cell magic with the data stored in self.
2554 """Special method to call a cell magic with the data stored in self.
2554 """
2555 """
2555 cell = self._current_cell_magic_body
2556 cell = self._current_cell_magic_body
2556 self._current_cell_magic_body = None
2557 self._current_cell_magic_body = None
2557 return self.run_cell_magic(magic_name, line, cell)
2558 return self.run_cell_magic(magic_name, line, cell)
2558
2559
2559 def run_cell(self, raw_cell, store_history=False, silent=False):
2560 def run_cell(self, raw_cell, store_history=False, silent=False):
2560 """Run a complete IPython cell.
2561 """Run a complete IPython cell.
2561
2562
2562 Parameters
2563 Parameters
2563 ----------
2564 ----------
2564 raw_cell : str
2565 raw_cell : str
2565 The code (including IPython code such as %magic functions) to run.
2566 The code (including IPython code such as %magic functions) to run.
2566 store_history : bool
2567 store_history : bool
2567 If True, the raw and translated cell will be stored in IPython's
2568 If True, the raw and translated cell will be stored in IPython's
2568 history. For user code calling back into IPython's machinery, this
2569 history. For user code calling back into IPython's machinery, this
2569 should be set to False.
2570 should be set to False.
2570 silent : bool
2571 silent : bool
2571 If True, avoid side-effects, such as implicit displayhooks and
2572 If True, avoid side-effects, such as implicit displayhooks and
2572 and logging. silent=True forces store_history=False.
2573 and logging. silent=True forces store_history=False.
2573 """
2574 """
2574 if (not raw_cell) or raw_cell.isspace():
2575 if (not raw_cell) or raw_cell.isspace():
2575 return
2576 return
2576
2577
2577 if silent:
2578 if silent:
2578 store_history = False
2579 store_history = False
2579
2580
2580 self.input_splitter.push(raw_cell)
2581 self.input_splitter.push(raw_cell)
2581
2582
2582 # Check for cell magics, which leave state behind. This interface is
2583 # Check for cell magics, which leave state behind. This interface is
2583 # ugly, we need to do something cleaner later... Now the logic is
2584 # ugly, we need to do something cleaner later... Now the logic is
2584 # simply that the input_splitter remembers if there was a cell magic,
2585 # simply that the input_splitter remembers if there was a cell magic,
2585 # and in that case we grab the cell body.
2586 # and in that case we grab the cell body.
2586 if self.input_splitter.cell_magic_parts:
2587 if self.input_splitter.cell_magic_parts:
2587 self._current_cell_magic_body = \
2588 self._current_cell_magic_body = \
2588 ''.join(self.input_splitter.cell_magic_parts)
2589 ''.join(self.input_splitter.cell_magic_parts)
2589 cell = self.input_splitter.source_reset()
2590 cell = self.input_splitter.source_reset()
2590
2591
2591 with self.builtin_trap:
2592 with self.builtin_trap:
2592 prefilter_failed = False
2593 prefilter_failed = False
2593 if len(cell.splitlines()) == 1:
2594 if len(cell.splitlines()) == 1:
2594 try:
2595 try:
2595 # use prefilter_lines to handle trailing newlines
2596 # use prefilter_lines to handle trailing newlines
2596 # restore trailing newline for ast.parse
2597 # restore trailing newline for ast.parse
2597 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2598 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2598 except AliasError as e:
2599 except AliasError as e:
2599 error(e)
2600 error(e)
2600 prefilter_failed = True
2601 prefilter_failed = True
2601 except Exception:
2602 except Exception:
2602 # don't allow prefilter errors to crash IPython
2603 # don't allow prefilter errors to crash IPython
2603 self.showtraceback()
2604 self.showtraceback()
2604 prefilter_failed = True
2605 prefilter_failed = True
2605
2606
2606 # Store raw and processed history
2607 # Store raw and processed history
2607 if store_history:
2608 if store_history:
2608 self.history_manager.store_inputs(self.execution_count,
2609 self.history_manager.store_inputs(self.execution_count,
2609 cell, raw_cell)
2610 cell, raw_cell)
2610 if not silent:
2611 if not silent:
2611 self.logger.log(cell, raw_cell)
2612 self.logger.log(cell, raw_cell)
2612
2613
2613 if not prefilter_failed:
2614 if not prefilter_failed:
2614 # don't run if prefilter failed
2615 # don't run if prefilter failed
2615 cell_name = self.compile.cache(cell, self.execution_count)
2616 cell_name = self.compile.cache(cell, self.execution_count)
2616
2617
2617 with self.display_trap:
2618 with self.display_trap:
2618 try:
2619 try:
2619 code_ast = self.compile.ast_parse(cell,
2620 code_ast = self.compile.ast_parse(cell,
2620 filename=cell_name)
2621 filename=cell_name)
2621 except IndentationError:
2622 except IndentationError:
2622 self.showindentationerror()
2623 self.showindentationerror()
2623 if store_history:
2624 if store_history:
2624 self.execution_count += 1
2625 self.execution_count += 1
2625 return None
2626 return None
2626 except (OverflowError, SyntaxError, ValueError, TypeError,
2627 except (OverflowError, SyntaxError, ValueError, TypeError,
2627 MemoryError):
2628 MemoryError):
2628 self.showsyntaxerror()
2629 self.showsyntaxerror()
2629 if store_history:
2630 if store_history:
2630 self.execution_count += 1
2631 self.execution_count += 1
2631 return None
2632 return None
2632
2633
2633 interactivity = "none" if silent else self.ast_node_interactivity
2634 interactivity = "none" if silent else self.ast_node_interactivity
2634 self.run_ast_nodes(code_ast.body, cell_name,
2635 self.run_ast_nodes(code_ast.body, cell_name,
2635 interactivity=interactivity)
2636 interactivity=interactivity)
2636
2637
2637 # Execute any registered post-execution functions.
2638 # Execute any registered post-execution functions.
2638 # unless we are silent
2639 # unless we are silent
2639 post_exec = [] if silent else self._post_execute.iteritems()
2640 post_exec = [] if silent else self._post_execute.iteritems()
2640
2641
2641 for func, status in post_exec:
2642 for func, status in post_exec:
2642 if self.disable_failing_post_execute and not status:
2643 if self.disable_failing_post_execute and not status:
2643 continue
2644 continue
2644 try:
2645 try:
2645 func()
2646 func()
2646 except KeyboardInterrupt:
2647 except KeyboardInterrupt:
2647 print("\nKeyboardInterrupt", file=io.stderr)
2648 print("\nKeyboardInterrupt", file=io.stderr)
2648 except Exception:
2649 except Exception:
2649 # register as failing:
2650 # register as failing:
2650 self._post_execute[func] = False
2651 self._post_execute[func] = False
2651 self.showtraceback()
2652 self.showtraceback()
2652 print('\n'.join([
2653 print('\n'.join([
2653 "post-execution function %r produced an error." % func,
2654 "post-execution function %r produced an error." % func,
2654 "If this problem persists, you can disable failing post-exec functions with:",
2655 "If this problem persists, you can disable failing post-exec functions with:",
2655 "",
2656 "",
2656 " get_ipython().disable_failing_post_execute = True"
2657 " get_ipython().disable_failing_post_execute = True"
2657 ]), file=io.stderr)
2658 ]), file=io.stderr)
2658
2659
2659 if store_history:
2660 if store_history:
2660 # Write output to the database. Does nothing unless
2661 # Write output to the database. Does nothing unless
2661 # history output logging is enabled.
2662 # history output logging is enabled.
2662 self.history_manager.store_output(self.execution_count)
2663 self.history_manager.store_output(self.execution_count)
2663 # Each cell is a *single* input, regardless of how many lines it has
2664 # Each cell is a *single* input, regardless of how many lines it has
2664 self.execution_count += 1
2665 self.execution_count += 1
2665
2666
2666 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr'):
2667 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr'):
2667 """Run a sequence of AST nodes. The execution mode depends on the
2668 """Run a sequence of AST nodes. The execution mode depends on the
2668 interactivity parameter.
2669 interactivity parameter.
2669
2670
2670 Parameters
2671 Parameters
2671 ----------
2672 ----------
2672 nodelist : list
2673 nodelist : list
2673 A sequence of AST nodes to run.
2674 A sequence of AST nodes to run.
2674 cell_name : str
2675 cell_name : str
2675 Will be passed to the compiler as the filename of the cell. Typically
2676 Will be passed to the compiler as the filename of the cell. Typically
2676 the value returned by ip.compile.cache(cell).
2677 the value returned by ip.compile.cache(cell).
2677 interactivity : str
2678 interactivity : str
2678 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2679 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2679 run interactively (displaying output from expressions). 'last_expr'
2680 run interactively (displaying output from expressions). 'last_expr'
2680 will run the last node interactively only if it is an expression (i.e.
2681 will run the last node interactively only if it is an expression (i.e.
2681 expressions in loops or other blocks are not displayed. Other values
2682 expressions in loops or other blocks are not displayed. Other values
2682 for this parameter will raise a ValueError.
2683 for this parameter will raise a ValueError.
2683 """
2684 """
2684 if not nodelist:
2685 if not nodelist:
2685 return
2686 return
2686
2687
2687 if interactivity == 'last_expr':
2688 if interactivity == 'last_expr':
2688 if isinstance(nodelist[-1], ast.Expr):
2689 if isinstance(nodelist[-1], ast.Expr):
2689 interactivity = "last"
2690 interactivity = "last"
2690 else:
2691 else:
2691 interactivity = "none"
2692 interactivity = "none"
2692
2693
2693 if interactivity == 'none':
2694 if interactivity == 'none':
2694 to_run_exec, to_run_interactive = nodelist, []
2695 to_run_exec, to_run_interactive = nodelist, []
2695 elif interactivity == 'last':
2696 elif interactivity == 'last':
2696 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2697 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2697 elif interactivity == 'all':
2698 elif interactivity == 'all':
2698 to_run_exec, to_run_interactive = [], nodelist
2699 to_run_exec, to_run_interactive = [], nodelist
2699 else:
2700 else:
2700 raise ValueError("Interactivity was %r" % interactivity)
2701 raise ValueError("Interactivity was %r" % interactivity)
2701
2702
2702 exec_count = self.execution_count
2703 exec_count = self.execution_count
2703
2704
2704 try:
2705 try:
2705 for i, node in enumerate(to_run_exec):
2706 for i, node in enumerate(to_run_exec):
2706 mod = ast.Module([node])
2707 mod = ast.Module([node])
2707 code = self.compile(mod, cell_name, "exec")
2708 code = self.compile(mod, cell_name, "exec")
2708 if self.run_code(code):
2709 if self.run_code(code):
2709 return True
2710 return True
2710
2711
2711 for i, node in enumerate(to_run_interactive):
2712 for i, node in enumerate(to_run_interactive):
2712 mod = ast.Interactive([node])
2713 mod = ast.Interactive([node])
2713 code = self.compile(mod, cell_name, "single")
2714 code = self.compile(mod, cell_name, "single")
2714 if self.run_code(code):
2715 if self.run_code(code):
2715 return True
2716 return True
2716
2717
2717 # Flush softspace
2718 # Flush softspace
2718 if softspace(sys.stdout, 0):
2719 if softspace(sys.stdout, 0):
2719 print()
2720 print()
2720
2721
2721 except:
2722 except:
2722 # It's possible to have exceptions raised here, typically by
2723 # It's possible to have exceptions raised here, typically by
2723 # compilation of odd code (such as a naked 'return' outside a
2724 # compilation of odd code (such as a naked 'return' outside a
2724 # function) that did parse but isn't valid. Typically the exception
2725 # function) that did parse but isn't valid. Typically the exception
2725 # is a SyntaxError, but it's safest just to catch anything and show
2726 # is a SyntaxError, but it's safest just to catch anything and show
2726 # the user a traceback.
2727 # the user a traceback.
2727
2728
2728 # We do only one try/except outside the loop to minimize the impact
2729 # We do only one try/except outside the loop to minimize the impact
2729 # on runtime, and also because if any node in the node list is
2730 # on runtime, and also because if any node in the node list is
2730 # broken, we should stop execution completely.
2731 # broken, we should stop execution completely.
2731 self.showtraceback()
2732 self.showtraceback()
2732
2733
2733 return False
2734 return False
2734
2735
2735 def run_code(self, code_obj):
2736 def run_code(self, code_obj):
2736 """Execute a code object.
2737 """Execute a code object.
2737
2738
2738 When an exception occurs, self.showtraceback() is called to display a
2739 When an exception occurs, self.showtraceback() is called to display a
2739 traceback.
2740 traceback.
2740
2741
2741 Parameters
2742 Parameters
2742 ----------
2743 ----------
2743 code_obj : code object
2744 code_obj : code object
2744 A compiled code object, to be executed
2745 A compiled code object, to be executed
2745
2746
2746 Returns
2747 Returns
2747 -------
2748 -------
2748 False : successful execution.
2749 False : successful execution.
2749 True : an error occurred.
2750 True : an error occurred.
2750 """
2751 """
2751
2752
2752 # Set our own excepthook in case the user code tries to call it
2753 # Set our own excepthook in case the user code tries to call it
2753 # directly, so that the IPython crash handler doesn't get triggered
2754 # directly, so that the IPython crash handler doesn't get triggered
2754 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2755 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2755
2756
2756 # we save the original sys.excepthook in the instance, in case config
2757 # we save the original sys.excepthook in the instance, in case config
2757 # code (such as magics) needs access to it.
2758 # code (such as magics) needs access to it.
2758 self.sys_excepthook = old_excepthook
2759 self.sys_excepthook = old_excepthook
2759 outflag = 1 # happens in more places, so it's easier as default
2760 outflag = 1 # happens in more places, so it's easier as default
2760 try:
2761 try:
2761 try:
2762 try:
2762 self.hooks.pre_run_code_hook()
2763 self.hooks.pre_run_code_hook()
2763 #rprint('Running code', repr(code_obj)) # dbg
2764 #rprint('Running code', repr(code_obj)) # dbg
2764 exec code_obj in self.user_global_ns, self.user_ns
2765 exec code_obj in self.user_global_ns, self.user_ns
2765 finally:
2766 finally:
2766 # Reset our crash handler in place
2767 # Reset our crash handler in place
2767 sys.excepthook = old_excepthook
2768 sys.excepthook = old_excepthook
2768 except SystemExit:
2769 except SystemExit:
2769 self.showtraceback(exception_only=True)
2770 self.showtraceback(exception_only=True)
2770 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2771 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2771 except self.custom_exceptions:
2772 except self.custom_exceptions:
2772 etype,value,tb = sys.exc_info()
2773 etype,value,tb = sys.exc_info()
2773 self.CustomTB(etype,value,tb)
2774 self.CustomTB(etype,value,tb)
2774 except:
2775 except:
2775 self.showtraceback()
2776 self.showtraceback()
2776 else:
2777 else:
2777 outflag = 0
2778 outflag = 0
2778 return outflag
2779 return outflag
2779
2780
2780 # For backwards compatibility
2781 # For backwards compatibility
2781 runcode = run_code
2782 runcode = run_code
2782
2783
2783 #-------------------------------------------------------------------------
2784 #-------------------------------------------------------------------------
2784 # Things related to GUI support and pylab
2785 # Things related to GUI support and pylab
2785 #-------------------------------------------------------------------------
2786 #-------------------------------------------------------------------------
2786
2787
2787 def enable_gui(self, gui=None):
2788 def enable_gui(self, gui=None):
2788 raise NotImplementedError('Implement enable_gui in a subclass')
2789 raise NotImplementedError('Implement enable_gui in a subclass')
2789
2790
2790 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
2791 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
2791 """Activate pylab support at runtime.
2792 """Activate pylab support at runtime.
2792
2793
2793 This turns on support for matplotlib, preloads into the interactive
2794 This turns on support for matplotlib, preloads into the interactive
2794 namespace all of numpy and pylab, and configures IPython to correctly
2795 namespace all of numpy and pylab, and configures IPython to correctly
2795 interact with the GUI event loop. The GUI backend to be used can be
2796 interact with the GUI event loop. The GUI backend to be used can be
2796 optionally selected with the optional :param:`gui` argument.
2797 optionally selected with the optional :param:`gui` argument.
2797
2798
2798 Parameters
2799 Parameters
2799 ----------
2800 ----------
2800 gui : optional, string
2801 gui : optional, string
2801
2802
2802 If given, dictates the choice of matplotlib GUI backend to use
2803 If given, dictates the choice of matplotlib GUI backend to use
2803 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2804 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2804 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2805 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2805 matplotlib (as dictated by the matplotlib build-time options plus the
2806 matplotlib (as dictated by the matplotlib build-time options plus the
2806 user's matplotlibrc configuration file). Note that not all backends
2807 user's matplotlibrc configuration file). Note that not all backends
2807 make sense in all contexts, for example a terminal ipython can't
2808 make sense in all contexts, for example a terminal ipython can't
2808 display figures inline.
2809 display figures inline.
2809 """
2810 """
2810 from IPython.core.pylabtools import mpl_runner
2811 from IPython.core.pylabtools import mpl_runner
2811 # We want to prevent the loading of pylab to pollute the user's
2812 # We want to prevent the loading of pylab to pollute the user's
2812 # namespace as shown by the %who* magics, so we execute the activation
2813 # namespace as shown by the %who* magics, so we execute the activation
2813 # code in an empty namespace, and we update *both* user_ns and
2814 # code in an empty namespace, and we update *both* user_ns and
2814 # user_ns_hidden with this information.
2815 # user_ns_hidden with this information.
2815 ns = {}
2816 ns = {}
2816 try:
2817 try:
2817 gui = pylab_activate(ns, gui, import_all, self, welcome_message=welcome_message)
2818 gui = pylab_activate(ns, gui, import_all, self, welcome_message=welcome_message)
2818 except KeyError:
2819 except KeyError:
2819 error("Backend %r not supported" % gui)
2820 error("Backend %r not supported" % gui)
2820 return
2821 return
2821 self.user_ns.update(ns)
2822 self.user_ns.update(ns)
2822 self.user_ns_hidden.update(ns)
2823 self.user_ns_hidden.update(ns)
2823 # Now we must activate the gui pylab wants to use, and fix %run to take
2824 # Now we must activate the gui pylab wants to use, and fix %run to take
2824 # plot updates into account
2825 # plot updates into account
2825 self.enable_gui(gui)
2826 self.enable_gui(gui)
2826 self.magics_manager.registry['ExecutionMagics'].default_runner = \
2827 self.magics_manager.registry['ExecutionMagics'].default_runner = \
2827 mpl_runner(self.safe_execfile)
2828 mpl_runner(self.safe_execfile)
2828
2829
2829 #-------------------------------------------------------------------------
2830 #-------------------------------------------------------------------------
2830 # Utilities
2831 # Utilities
2831 #-------------------------------------------------------------------------
2832 #-------------------------------------------------------------------------
2832
2833
2833 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
2834 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
2834 """Expand python variables in a string.
2835 """Expand python variables in a string.
2835
2836
2836 The depth argument indicates how many frames above the caller should
2837 The depth argument indicates how many frames above the caller should
2837 be walked to look for the local namespace where to expand variables.
2838 be walked to look for the local namespace where to expand variables.
2838
2839
2839 The global namespace for expansion is always the user's interactive
2840 The global namespace for expansion is always the user's interactive
2840 namespace.
2841 namespace.
2841 """
2842 """
2842 ns = self.user_ns.copy()
2843 ns = self.user_ns.copy()
2843 ns.update(sys._getframe(depth+1).f_locals)
2844 ns.update(sys._getframe(depth+1).f_locals)
2844 try:
2845 try:
2845 # We have to use .vformat() here, because 'self' is a valid and common
2846 # We have to use .vformat() here, because 'self' is a valid and common
2846 # name, and expanding **ns for .format() would make it collide with
2847 # name, and expanding **ns for .format() would make it collide with
2847 # the 'self' argument of the method.
2848 # the 'self' argument of the method.
2848 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
2849 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
2849 except Exception:
2850 except Exception:
2850 # if formatter couldn't format, just let it go untransformed
2851 # if formatter couldn't format, just let it go untransformed
2851 pass
2852 pass
2852 return cmd
2853 return cmd
2853
2854
2854 def mktempfile(self, data=None, prefix='ipython_edit_'):
2855 def mktempfile(self, data=None, prefix='ipython_edit_'):
2855 """Make a new tempfile and return its filename.
2856 """Make a new tempfile and return its filename.
2856
2857
2857 This makes a call to tempfile.mktemp, but it registers the created
2858 This makes a call to tempfile.mktemp, but it registers the created
2858 filename internally so ipython cleans it up at exit time.
2859 filename internally so ipython cleans it up at exit time.
2859
2860
2860 Optional inputs:
2861 Optional inputs:
2861
2862
2862 - data(None): if data is given, it gets written out to the temp file
2863 - data(None): if data is given, it gets written out to the temp file
2863 immediately, and the file is closed again."""
2864 immediately, and the file is closed again."""
2864
2865
2865 filename = tempfile.mktemp('.py', prefix)
2866 filename = tempfile.mktemp('.py', prefix)
2866 self.tempfiles.append(filename)
2867 self.tempfiles.append(filename)
2867
2868
2868 if data:
2869 if data:
2869 tmp_file = open(filename,'w')
2870 tmp_file = open(filename,'w')
2870 tmp_file.write(data)
2871 tmp_file.write(data)
2871 tmp_file.close()
2872 tmp_file.close()
2872 return filename
2873 return filename
2873
2874
2874 # TODO: This should be removed when Term is refactored.
2875 # TODO: This should be removed when Term is refactored.
2875 def write(self,data):
2876 def write(self,data):
2876 """Write a string to the default output"""
2877 """Write a string to the default output"""
2877 io.stdout.write(data)
2878 io.stdout.write(data)
2878
2879
2879 # TODO: This should be removed when Term is refactored.
2880 # TODO: This should be removed when Term is refactored.
2880 def write_err(self,data):
2881 def write_err(self,data):
2881 """Write a string to the default error output"""
2882 """Write a string to the default error output"""
2882 io.stderr.write(data)
2883 io.stderr.write(data)
2883
2884
2884 def ask_yes_no(self, prompt, default=None):
2885 def ask_yes_no(self, prompt, default=None):
2885 if self.quiet:
2886 if self.quiet:
2886 return True
2887 return True
2887 return ask_yes_no(prompt,default)
2888 return ask_yes_no(prompt,default)
2888
2889
2889 def show_usage(self):
2890 def show_usage(self):
2890 """Show a usage message"""
2891 """Show a usage message"""
2891 page.page(IPython.core.usage.interactive_usage)
2892 page.page(IPython.core.usage.interactive_usage)
2892
2893
2893 def extract_input_lines(self, range_str, raw=False):
2894 def extract_input_lines(self, range_str, raw=False):
2894 """Return as a string a set of input history slices.
2895 """Return as a string a set of input history slices.
2895
2896
2896 Parameters
2897 Parameters
2897 ----------
2898 ----------
2898 range_str : string
2899 range_str : string
2899 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
2900 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
2900 since this function is for use by magic functions which get their
2901 since this function is for use by magic functions which get their
2901 arguments as strings. The number before the / is the session
2902 arguments as strings. The number before the / is the session
2902 number: ~n goes n back from the current session.
2903 number: ~n goes n back from the current session.
2903
2904
2904 Optional Parameters:
2905 Optional Parameters:
2905 - raw(False): by default, the processed input is used. If this is
2906 - raw(False): by default, the processed input is used. If this is
2906 true, the raw input history is used instead.
2907 true, the raw input history is used instead.
2907
2908
2908 Note that slices can be called with two notations:
2909 Note that slices can be called with two notations:
2909
2910
2910 N:M -> standard python form, means including items N...(M-1).
2911 N:M -> standard python form, means including items N...(M-1).
2911
2912
2912 N-M -> include items N..M (closed endpoint)."""
2913 N-M -> include items N..M (closed endpoint)."""
2913 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
2914 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
2914 return "\n".join(x for _, _, x in lines)
2915 return "\n".join(x for _, _, x in lines)
2915
2916
2916 def find_user_code(self, target, raw=True, py_only=False):
2917 def find_user_code(self, target, raw=True, py_only=False):
2917 """Get a code string from history, file, url, or a string or macro.
2918 """Get a code string from history, file, url, or a string or macro.
2918
2919
2919 This is mainly used by magic functions.
2920 This is mainly used by magic functions.
2920
2921
2921 Parameters
2922 Parameters
2922 ----------
2923 ----------
2923
2924
2924 target : str
2925 target : str
2925
2926
2926 A string specifying code to retrieve. This will be tried respectively
2927 A string specifying code to retrieve. This will be tried respectively
2927 as: ranges of input history (see %history for syntax), url,
2928 as: ranges of input history (see %history for syntax), url,
2928 correspnding .py file, filename, or an expression evaluating to a
2929 correspnding .py file, filename, or an expression evaluating to a
2929 string or Macro in the user namespace.
2930 string or Macro in the user namespace.
2930
2931
2931 raw : bool
2932 raw : bool
2932 If true (default), retrieve raw history. Has no effect on the other
2933 If true (default), retrieve raw history. Has no effect on the other
2933 retrieval mechanisms.
2934 retrieval mechanisms.
2934
2935
2935 py_only : bool (default False)
2936 py_only : bool (default False)
2936 Only try to fetch python code, do not try alternative methods to decode file
2937 Only try to fetch python code, do not try alternative methods to decode file
2937 if unicode fails.
2938 if unicode fails.
2938
2939
2939 Returns
2940 Returns
2940 -------
2941 -------
2941 A string of code.
2942 A string of code.
2942
2943
2943 ValueError is raised if nothing is found, and TypeError if it evaluates
2944 ValueError is raised if nothing is found, and TypeError if it evaluates
2944 to an object of another type. In each case, .args[0] is a printable
2945 to an object of another type. In each case, .args[0] is a printable
2945 message.
2946 message.
2946 """
2947 """
2947 code = self.extract_input_lines(target, raw=raw) # Grab history
2948 code = self.extract_input_lines(target, raw=raw) # Grab history
2948 if code:
2949 if code:
2949 return code
2950 return code
2950 utarget = unquote_filename(target)
2951 utarget = unquote_filename(target)
2951 try:
2952 try:
2952 if utarget.startswith(('http://', 'https://')):
2953 if utarget.startswith(('http://', 'https://')):
2953 return openpy.read_py_url(utarget, skip_encoding_cookie=True)
2954 return openpy.read_py_url(utarget, skip_encoding_cookie=True)
2954 except UnicodeDecodeError:
2955 except UnicodeDecodeError:
2955 if not py_only :
2956 if not py_only :
2956 response = urllib.urlopen(target)
2957 response = urllib.urlopen(target)
2957 return response.read().decode('latin1')
2958 return response.read().decode('latin1')
2958 raise ValueError(("'%s' seem to be unreadable.") % utarget)
2959 raise ValueError(("'%s' seem to be unreadable.") % utarget)
2959
2960
2960 potential_target = [target]
2961 potential_target = [target]
2961 try :
2962 try :
2962 potential_target.insert(0,get_py_filename(target))
2963 potential_target.insert(0,get_py_filename(target))
2963 except IOError:
2964 except IOError:
2964 pass
2965 pass
2965
2966
2966 for tgt in potential_target :
2967 for tgt in potential_target :
2967 if os.path.isfile(tgt): # Read file
2968 if os.path.isfile(tgt): # Read file
2968 try :
2969 try :
2969 return openpy.read_py_file(tgt, skip_encoding_cookie=True)
2970 return openpy.read_py_file(tgt, skip_encoding_cookie=True)
2970 except UnicodeDecodeError :
2971 except UnicodeDecodeError :
2971 if not py_only :
2972 if not py_only :
2972 with io_open(tgt,'r', encoding='latin1') as f :
2973 with io_open(tgt,'r', encoding='latin1') as f :
2973 return f.read()
2974 return f.read()
2974 raise ValueError(("'%s' seem to be unreadable.") % target)
2975 raise ValueError(("'%s' seem to be unreadable.") % target)
2975
2976
2976 try: # User namespace
2977 try: # User namespace
2977 codeobj = eval(target, self.user_ns)
2978 codeobj = eval(target, self.user_ns)
2978 except Exception:
2979 except Exception:
2979 raise ValueError(("'%s' was not found in history, as a file, url, "
2980 raise ValueError(("'%s' was not found in history, as a file, url, "
2980 "nor in the user namespace.") % target)
2981 "nor in the user namespace.") % target)
2981 if isinstance(codeobj, basestring):
2982 if isinstance(codeobj, basestring):
2982 return codeobj
2983 return codeobj
2983 elif isinstance(codeobj, Macro):
2984 elif isinstance(codeobj, Macro):
2984 return codeobj.value
2985 return codeobj.value
2985
2986
2986 raise TypeError("%s is neither a string nor a macro." % target,
2987 raise TypeError("%s is neither a string nor a macro." % target,
2987 codeobj)
2988 codeobj)
2988
2989
2989 #-------------------------------------------------------------------------
2990 #-------------------------------------------------------------------------
2990 # Things related to IPython exiting
2991 # Things related to IPython exiting
2991 #-------------------------------------------------------------------------
2992 #-------------------------------------------------------------------------
2992 def atexit_operations(self):
2993 def atexit_operations(self):
2993 """This will be executed at the time of exit.
2994 """This will be executed at the time of exit.
2994
2995
2995 Cleanup operations and saving of persistent data that is done
2996 Cleanup operations and saving of persistent data that is done
2996 unconditionally by IPython should be performed here.
2997 unconditionally by IPython should be performed here.
2997
2998
2998 For things that may depend on startup flags or platform specifics (such
2999 For things that may depend on startup flags or platform specifics (such
2999 as having readline or not), register a separate atexit function in the
3000 as having readline or not), register a separate atexit function in the
3000 code that has the appropriate information, rather than trying to
3001 code that has the appropriate information, rather than trying to
3001 clutter
3002 clutter
3002 """
3003 """
3003 # Close the history session (this stores the end time and line count)
3004 # Close the history session (this stores the end time and line count)
3004 # this must be *before* the tempfile cleanup, in case of temporary
3005 # this must be *before* the tempfile cleanup, in case of temporary
3005 # history db
3006 # history db
3006 self.history_manager.end_session()
3007 self.history_manager.end_session()
3007
3008
3008 # Cleanup all tempfiles left around
3009 # Cleanup all tempfiles left around
3009 for tfile in self.tempfiles:
3010 for tfile in self.tempfiles:
3010 try:
3011 try:
3011 os.unlink(tfile)
3012 os.unlink(tfile)
3012 except OSError:
3013 except OSError:
3013 pass
3014 pass
3014
3015
3015 # Clear all user namespaces to release all references cleanly.
3016 # Clear all user namespaces to release all references cleanly.
3016 self.reset(new_session=False)
3017 self.reset(new_session=False)
3017
3018
3018 # Run user hooks
3019 # Run user hooks
3019 self.hooks.shutdown_hook()
3020 self.hooks.shutdown_hook()
3020
3021
3021 def cleanup(self):
3022 def cleanup(self):
3022 self.restore_sys_module_state()
3023 self.restore_sys_module_state()
3023
3024
3024
3025
3025 class InteractiveShellABC(object):
3026 class InteractiveShellABC(object):
3026 """An abstract base class for InteractiveShell."""
3027 """An abstract base class for InteractiveShell."""
3027 __metaclass__ = abc.ABCMeta
3028 __metaclass__ = abc.ABCMeta
3028
3029
3029 InteractiveShellABC.register(InteractiveShell)
3030 InteractiveShellABC.register(InteractiveShell)
@@ -1,1014 +1,1014 b''
1 """Implementation of execution-related magic functions.
1 """Implementation of execution-related magic functions.
2 """
2 """
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Copyright (c) 2012 The IPython Development Team.
4 # Copyright (c) 2012 The IPython Development Team.
5 #
5 #
6 # Distributed under the terms of the Modified BSD License.
6 # Distributed under the terms of the Modified BSD License.
7 #
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10
10
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12 # Imports
12 # Imports
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14
14
15 # Stdlib
15 # Stdlib
16 import __builtin__ as builtin_mod
16 import __builtin__ as builtin_mod
17 import bdb
17 import bdb
18 import os
18 import os
19 import sys
19 import sys
20 import time
20 import time
21 from StringIO import StringIO
21 from StringIO import StringIO
22
22
23 # cProfile was added in Python2.5
23 # cProfile was added in Python2.5
24 try:
24 try:
25 import cProfile as profile
25 import cProfile as profile
26 import pstats
26 import pstats
27 except ImportError:
27 except ImportError:
28 # profile isn't bundled by default in Debian for license reasons
28 # profile isn't bundled by default in Debian for license reasons
29 try:
29 try:
30 import profile, pstats
30 import profile, pstats
31 except ImportError:
31 except ImportError:
32 profile = pstats = None
32 profile = pstats = None
33
33
34 # Our own packages
34 # Our own packages
35 from IPython.core import debugger, oinspect
35 from IPython.core import debugger, oinspect
36 from IPython.core import magic_arguments
36 from IPython.core import magic_arguments
37 from IPython.core import page
37 from IPython.core import page
38 from IPython.core.error import UsageError
38 from IPython.core.error import UsageError
39 from IPython.core.macro import Macro
39 from IPython.core.macro import Macro
40 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
40 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
41 line_cell_magic, on_off, needs_local_scope)
41 line_cell_magic, on_off, needs_local_scope)
42 from IPython.testing.skipdoctest import skip_doctest
42 from IPython.testing.skipdoctest import skip_doctest
43 from IPython.utils import py3compat
43 from IPython.utils import py3compat
44 from IPython.utils.io import capture_output
44 from IPython.utils.io import capture_output
45 from IPython.utils.ipstruct import Struct
45 from IPython.utils.ipstruct import Struct
46 from IPython.utils.module_paths import find_mod
46 from IPython.utils.module_paths import find_mod
47 from IPython.utils.path import get_py_filename, unquote_filename
47 from IPython.utils.path import get_py_filename, unquote_filename
48 from IPython.utils.timing import clock, clock2
48 from IPython.utils.timing import clock, clock2
49 from IPython.utils.warn import warn, error
49 from IPython.utils.warn import warn, error
50
50
51 #-----------------------------------------------------------------------------
51 #-----------------------------------------------------------------------------
52 # Magic implementation classes
52 # Magic implementation classes
53 #-----------------------------------------------------------------------------
53 #-----------------------------------------------------------------------------
54
54
55 @magics_class
55 @magics_class
56 class ExecutionMagics(Magics):
56 class ExecutionMagics(Magics):
57 """Magics related to code execution, debugging, profiling, etc.
57 """Magics related to code execution, debugging, profiling, etc.
58
58
59 """
59 """
60
60
61 def __init__(self, shell):
61 def __init__(self, shell):
62 super(ExecutionMagics, self).__init__(shell)
62 super(ExecutionMagics, self).__init__(shell)
63 if profile is None:
63 if profile is None:
64 self.prun = self.profile_missing_notice
64 self.prun = self.profile_missing_notice
65 # Default execution function used to actually run user code.
65 # Default execution function used to actually run user code.
66 self.default_runner = None
66 self.default_runner = None
67
67
68 def profile_missing_notice(self, *args, **kwargs):
68 def profile_missing_notice(self, *args, **kwargs):
69 error("""\
69 error("""\
70 The profile module could not be found. It has been removed from the standard
70 The profile module could not be found. It has been removed from the standard
71 python packages because of its non-free license. To use profiling, install the
71 python packages because of its non-free license. To use profiling, install the
72 python-profiler package from non-free.""")
72 python-profiler package from non-free.""")
73
73
74 @skip_doctest
74 @skip_doctest
75 @line_cell_magic
75 @line_cell_magic
76 def prun(self, parameter_s='', cell=None, user_mode=True,
76 def prun(self, parameter_s='', cell=None, user_mode=True,
77 opts=None,arg_lst=None,prog_ns=None):
77 opts=None,arg_lst=None,prog_ns=None):
78
78
79 """Run a statement through the python code profiler.
79 """Run a statement through the python code profiler.
80
80
81 Usage, in line mode:
81 Usage, in line mode:
82 %prun [options] statement
82 %prun [options] statement
83
83
84 Usage, in cell mode:
84 Usage, in cell mode:
85 %%prun [options] [statement]
85 %%prun [options] [statement]
86 code...
86 code...
87 code...
87 code...
88
88
89 In cell mode, the additional code lines are appended to the (possibly
89 In cell mode, the additional code lines are appended to the (possibly
90 empty) statement in the first line. Cell mode allows you to easily
90 empty) statement in the first line. Cell mode allows you to easily
91 profile multiline blocks without having to put them in a separate
91 profile multiline blocks without having to put them in a separate
92 function.
92 function.
93
93
94 The given statement (which doesn't require quote marks) is run via the
94 The given statement (which doesn't require quote marks) is run via the
95 python profiler in a manner similar to the profile.run() function.
95 python profiler in a manner similar to the profile.run() function.
96 Namespaces are internally managed to work correctly; profile.run
96 Namespaces are internally managed to work correctly; profile.run
97 cannot be used in IPython because it makes certain assumptions about
97 cannot be used in IPython because it makes certain assumptions about
98 namespaces which do not hold under IPython.
98 namespaces which do not hold under IPython.
99
99
100 Options:
100 Options:
101
101
102 -l <limit>: you can place restrictions on what or how much of the
102 -l <limit>: you can place restrictions on what or how much of the
103 profile gets printed. The limit value can be:
103 profile gets printed. The limit value can be:
104
104
105 * A string: only information for function names containing this string
105 * A string: only information for function names containing this string
106 is printed.
106 is printed.
107
107
108 * An integer: only these many lines are printed.
108 * An integer: only these many lines are printed.
109
109
110 * A float (between 0 and 1): this fraction of the report is printed
110 * A float (between 0 and 1): this fraction of the report is printed
111 (for example, use a limit of 0.4 to see the topmost 40% only).
111 (for example, use a limit of 0.4 to see the topmost 40% only).
112
112
113 You can combine several limits with repeated use of the option. For
113 You can combine several limits with repeated use of the option. For
114 example, '-l __init__ -l 5' will print only the topmost 5 lines of
114 example, '-l __init__ -l 5' will print only the topmost 5 lines of
115 information about class constructors.
115 information about class constructors.
116
116
117 -r: return the pstats.Stats object generated by the profiling. This
117 -r: return the pstats.Stats object generated by the profiling. This
118 object has all the information about the profile in it, and you can
118 object has all the information about the profile in it, and you can
119 later use it for further analysis or in other functions.
119 later use it for further analysis or in other functions.
120
120
121 -s <key>: sort profile by given key. You can provide more than one key
121 -s <key>: sort profile by given key. You can provide more than one key
122 by using the option several times: '-s key1 -s key2 -s key3...'. The
122 by using the option several times: '-s key1 -s key2 -s key3...'. The
123 default sorting key is 'time'.
123 default sorting key is 'time'.
124
124
125 The following is copied verbatim from the profile documentation
125 The following is copied verbatim from the profile documentation
126 referenced below:
126 referenced below:
127
127
128 When more than one key is provided, additional keys are used as
128 When more than one key is provided, additional keys are used as
129 secondary criteria when the there is equality in all keys selected
129 secondary criteria when the there is equality in all keys selected
130 before them.
130 before them.
131
131
132 Abbreviations can be used for any key names, as long as the
132 Abbreviations can be used for any key names, as long as the
133 abbreviation is unambiguous. The following are the keys currently
133 abbreviation is unambiguous. The following are the keys currently
134 defined:
134 defined:
135
135
136 Valid Arg Meaning
136 Valid Arg Meaning
137 "calls" call count
137 "calls" call count
138 "cumulative" cumulative time
138 "cumulative" cumulative time
139 "file" file name
139 "file" file name
140 "module" file name
140 "module" file name
141 "pcalls" primitive call count
141 "pcalls" primitive call count
142 "line" line number
142 "line" line number
143 "name" function name
143 "name" function name
144 "nfl" name/file/line
144 "nfl" name/file/line
145 "stdname" standard name
145 "stdname" standard name
146 "time" internal time
146 "time" internal time
147
147
148 Note that all sorts on statistics are in descending order (placing
148 Note that all sorts on statistics are in descending order (placing
149 most time consuming items first), where as name, file, and line number
149 most time consuming items first), where as name, file, and line number
150 searches are in ascending order (i.e., alphabetical). The subtle
150 searches are in ascending order (i.e., alphabetical). The subtle
151 distinction between "nfl" and "stdname" is that the standard name is a
151 distinction between "nfl" and "stdname" is that the standard name is a
152 sort of the name as printed, which means that the embedded line
152 sort of the name as printed, which means that the embedded line
153 numbers get compared in an odd way. For example, lines 3, 20, and 40
153 numbers get compared in an odd way. For example, lines 3, 20, and 40
154 would (if the file names were the same) appear in the string order
154 would (if the file names were the same) appear in the string order
155 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
155 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
156 line numbers. In fact, sort_stats("nfl") is the same as
156 line numbers. In fact, sort_stats("nfl") is the same as
157 sort_stats("name", "file", "line").
157 sort_stats("name", "file", "line").
158
158
159 -T <filename>: save profile results as shown on screen to a text
159 -T <filename>: save profile results as shown on screen to a text
160 file. The profile is still shown on screen.
160 file. The profile is still shown on screen.
161
161
162 -D <filename>: save (via dump_stats) profile statistics to given
162 -D <filename>: save (via dump_stats) profile statistics to given
163 filename. This data is in a format understood by the pstats module, and
163 filename. This data is in a format understood by the pstats module, and
164 is generated by a call to the dump_stats() method of profile
164 is generated by a call to the dump_stats() method of profile
165 objects. The profile is still shown on screen.
165 objects. The profile is still shown on screen.
166
166
167 -q: suppress output to the pager. Best used with -T and/or -D above.
167 -q: suppress output to the pager. Best used with -T and/or -D above.
168
168
169 If you want to run complete programs under the profiler's control, use
169 If you want to run complete programs under the profiler's control, use
170 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
170 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
171 contains profiler specific options as described here.
171 contains profiler specific options as described here.
172
172
173 You can read the complete documentation for the profile module with::
173 You can read the complete documentation for the profile module with::
174
174
175 In [1]: import profile; profile.help()
175 In [1]: import profile; profile.help()
176 """
176 """
177
177
178 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
178 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
179
179
180 if user_mode: # regular user call
180 if user_mode: # regular user call
181 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
181 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
182 list_all=True, posix=False)
182 list_all=True, posix=False)
183 namespace = self.shell.user_ns
183 namespace = self.shell.user_ns
184 if cell is not None:
184 if cell is not None:
185 arg_str += '\n' + cell
185 arg_str += '\n' + cell
186 else: # called to run a program by %run -p
186 else: # called to run a program by %run -p
187 try:
187 try:
188 filename = get_py_filename(arg_lst[0])
188 filename = get_py_filename(arg_lst[0])
189 except IOError as e:
189 except IOError as e:
190 try:
190 try:
191 msg = str(e)
191 msg = str(e)
192 except UnicodeError:
192 except UnicodeError:
193 msg = e.message
193 msg = e.message
194 error(msg)
194 error(msg)
195 return
195 return
196
196
197 arg_str = 'execfile(filename,prog_ns)'
197 arg_str = 'execfile(filename,prog_ns)'
198 namespace = {
198 namespace = {
199 'execfile': self.shell.safe_execfile,
199 'execfile': self.shell.safe_execfile,
200 'prog_ns': prog_ns,
200 'prog_ns': prog_ns,
201 'filename': filename
201 'filename': filename
202 }
202 }
203
203
204 opts.merge(opts_def)
204 opts.merge(opts_def)
205
205
206 prof = profile.Profile()
206 prof = profile.Profile()
207 try:
207 try:
208 prof = prof.runctx(arg_str,namespace,namespace)
208 prof = prof.runctx(arg_str,namespace,namespace)
209 sys_exit = ''
209 sys_exit = ''
210 except SystemExit:
210 except SystemExit:
211 sys_exit = """*** SystemExit exception caught in code being profiled."""
211 sys_exit = """*** SystemExit exception caught in code being profiled."""
212
212
213 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
213 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
214
214
215 lims = opts.l
215 lims = opts.l
216 if lims:
216 if lims:
217 lims = [] # rebuild lims with ints/floats/strings
217 lims = [] # rebuild lims with ints/floats/strings
218 for lim in opts.l:
218 for lim in opts.l:
219 try:
219 try:
220 lims.append(int(lim))
220 lims.append(int(lim))
221 except ValueError:
221 except ValueError:
222 try:
222 try:
223 lims.append(float(lim))
223 lims.append(float(lim))
224 except ValueError:
224 except ValueError:
225 lims.append(lim)
225 lims.append(lim)
226
226
227 # Trap output.
227 # Trap output.
228 stdout_trap = StringIO()
228 stdout_trap = StringIO()
229 stats_stream = stats.stream
229 stats_stream = stats.stream
230 try:
230 try:
231 stats.stream = stdout_trap
231 stats.stream = stdout_trap
232 stats.print_stats(*lims)
232 stats.print_stats(*lims)
233 finally:
233 finally:
234 stats.stream = stats_stream
234 stats.stream = stats_stream
235
235
236 output = stdout_trap.getvalue()
236 output = stdout_trap.getvalue()
237 output = output.rstrip()
237 output = output.rstrip()
238
238
239 if 'q' not in opts:
239 if 'q' not in opts:
240 page.page(output)
240 page.page(output)
241 print sys_exit,
241 print sys_exit,
242
242
243 dump_file = opts.D[0]
243 dump_file = opts.D[0]
244 text_file = opts.T[0]
244 text_file = opts.T[0]
245 if dump_file:
245 if dump_file:
246 dump_file = unquote_filename(dump_file)
246 dump_file = unquote_filename(dump_file)
247 prof.dump_stats(dump_file)
247 prof.dump_stats(dump_file)
248 print '\n*** Profile stats marshalled to file',\
248 print '\n*** Profile stats marshalled to file',\
249 repr(dump_file)+'.',sys_exit
249 repr(dump_file)+'.',sys_exit
250 if text_file:
250 if text_file:
251 text_file = unquote_filename(text_file)
251 text_file = unquote_filename(text_file)
252 pfile = open(text_file,'w')
252 pfile = open(text_file,'w')
253 pfile.write(output)
253 pfile.write(output)
254 pfile.close()
254 pfile.close()
255 print '\n*** Profile printout saved to text file',\
255 print '\n*** Profile printout saved to text file',\
256 repr(text_file)+'.',sys_exit
256 repr(text_file)+'.',sys_exit
257
257
258 if 'r' in opts:
258 if 'r' in opts:
259 return stats
259 return stats
260 else:
260 else:
261 return None
261 return None
262
262
263 @line_magic
263 @line_magic
264 def pdb(self, parameter_s=''):
264 def pdb(self, parameter_s=''):
265 """Control the automatic calling of the pdb interactive debugger.
265 """Control the automatic calling of the pdb interactive debugger.
266
266
267 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
267 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
268 argument it works as a toggle.
268 argument it works as a toggle.
269
269
270 When an exception is triggered, IPython can optionally call the
270 When an exception is triggered, IPython can optionally call the
271 interactive pdb debugger after the traceback printout. %pdb toggles
271 interactive pdb debugger after the traceback printout. %pdb toggles
272 this feature on and off.
272 this feature on and off.
273
273
274 The initial state of this feature is set in your configuration
274 The initial state of this feature is set in your configuration
275 file (the option is ``InteractiveShell.pdb``).
275 file (the option is ``InteractiveShell.pdb``).
276
276
277 If you want to just activate the debugger AFTER an exception has fired,
277 If you want to just activate the debugger AFTER an exception has fired,
278 without having to type '%pdb on' and rerunning your code, you can use
278 without having to type '%pdb on' and rerunning your code, you can use
279 the %debug magic."""
279 the %debug magic."""
280
280
281 par = parameter_s.strip().lower()
281 par = parameter_s.strip().lower()
282
282
283 if par:
283 if par:
284 try:
284 try:
285 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
285 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
286 except KeyError:
286 except KeyError:
287 print ('Incorrect argument. Use on/1, off/0, '
287 print ('Incorrect argument. Use on/1, off/0, '
288 'or nothing for a toggle.')
288 'or nothing for a toggle.')
289 return
289 return
290 else:
290 else:
291 # toggle
291 # toggle
292 new_pdb = not self.shell.call_pdb
292 new_pdb = not self.shell.call_pdb
293
293
294 # set on the shell
294 # set on the shell
295 self.shell.call_pdb = new_pdb
295 self.shell.call_pdb = new_pdb
296 print 'Automatic pdb calling has been turned',on_off(new_pdb)
296 print 'Automatic pdb calling has been turned',on_off(new_pdb)
297
297
298 @line_magic
298 @line_magic
299 def debug(self, parameter_s=''):
299 def debug(self, parameter_s=''):
300 """Activate the interactive debugger in post-mortem mode.
300 """Activate the interactive debugger in post-mortem mode.
301
301
302 If an exception has just occurred, this lets you inspect its stack
302 If an exception has just occurred, this lets you inspect its stack
303 frames interactively. Note that this will always work only on the last
303 frames interactively. Note that this will always work only on the last
304 traceback that occurred, so you must call this quickly after an
304 traceback that occurred, so you must call this quickly after an
305 exception that you wish to inspect has fired, because if another one
305 exception that you wish to inspect has fired, because if another one
306 occurs, it clobbers the previous one.
306 occurs, it clobbers the previous one.
307
307
308 If you want IPython to automatically do this on every exception, see
308 If you want IPython to automatically do this on every exception, see
309 the %pdb magic for more details.
309 the %pdb magic for more details.
310 """
310 """
311 self.shell.debugger(force=True)
311 self.shell.debugger(force=True)
312
312
313 @line_magic
313 @line_magic
314 def tb(self, s):
314 def tb(self, s):
315 """Print the last traceback with the currently active exception mode.
315 """Print the last traceback with the currently active exception mode.
316
316
317 See %xmode for changing exception reporting modes."""
317 See %xmode for changing exception reporting modes."""
318 self.shell.showtraceback()
318 self.shell.showtraceback()
319
319
320 @skip_doctest
320 @skip_doctest
321 @line_magic
321 @line_magic
322 def run(self, parameter_s='', runner=None,
322 def run(self, parameter_s='', runner=None,
323 file_finder=get_py_filename):
323 file_finder=get_py_filename):
324 """Run the named file inside IPython as a program.
324 """Run the named file inside IPython as a program.
325
325
326 Usage:\\
326 Usage:\\
327 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
327 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
328
328
329 Parameters after the filename are passed as command-line arguments to
329 Parameters after the filename are passed as command-line arguments to
330 the program (put in sys.argv). Then, control returns to IPython's
330 the program (put in sys.argv). Then, control returns to IPython's
331 prompt.
331 prompt.
332
332
333 This is similar to running at a system prompt:\\
333 This is similar to running at a system prompt:\\
334 $ python file args\\
334 $ python file args\\
335 but with the advantage of giving you IPython's tracebacks, and of
335 but with the advantage of giving you IPython's tracebacks, and of
336 loading all variables into your interactive namespace for further use
336 loading all variables into your interactive namespace for further use
337 (unless -p is used, see below).
337 (unless -p is used, see below).
338
338
339 The file is executed in a namespace initially consisting only of
339 The file is executed in a namespace initially consisting only of
340 __name__=='__main__' and sys.argv constructed as indicated. It thus
340 __name__=='__main__' and sys.argv constructed as indicated. It thus
341 sees its environment as if it were being run as a stand-alone program
341 sees its environment as if it were being run as a stand-alone program
342 (except for sharing global objects such as previously imported
342 (except for sharing global objects such as previously imported
343 modules). But after execution, the IPython interactive namespace gets
343 modules). But after execution, the IPython interactive namespace gets
344 updated with all variables defined in the program (except for __name__
344 updated with all variables defined in the program (except for __name__
345 and sys.argv). This allows for very convenient loading of code for
345 and sys.argv). This allows for very convenient loading of code for
346 interactive work, while giving each program a 'clean sheet' to run in.
346 interactive work, while giving each program a 'clean sheet' to run in.
347
347
348 Options:
348 Options:
349
349
350 -n: __name__ is NOT set to '__main__', but to the running file's name
350 -n: __name__ is NOT set to '__main__', but to the running file's name
351 without extension (as python does under import). This allows running
351 without extension (as python does under import). This allows running
352 scripts and reloading the definitions in them without calling code
352 scripts and reloading the definitions in them without calling code
353 protected by an ' if __name__ == "__main__" ' clause.
353 protected by an ' if __name__ == "__main__" ' clause.
354
354
355 -i: run the file in IPython's namespace instead of an empty one. This
355 -i: run the file in IPython's namespace instead of an empty one. This
356 is useful if you are experimenting with code written in a text editor
356 is useful if you are experimenting with code written in a text editor
357 which depends on variables defined interactively.
357 which depends on variables defined interactively.
358
358
359 -e: ignore sys.exit() calls or SystemExit exceptions in the script
359 -e: ignore sys.exit() calls or SystemExit exceptions in the script
360 being run. This is particularly useful if IPython is being used to
360 being run. This is particularly useful if IPython is being used to
361 run unittests, which always exit with a sys.exit() call. In such
361 run unittests, which always exit with a sys.exit() call. In such
362 cases you are interested in the output of the test results, not in
362 cases you are interested in the output of the test results, not in
363 seeing a traceback of the unittest module.
363 seeing a traceback of the unittest module.
364
364
365 -t: print timing information at the end of the run. IPython will give
365 -t: print timing information at the end of the run. IPython will give
366 you an estimated CPU time consumption for your script, which under
366 you an estimated CPU time consumption for your script, which under
367 Unix uses the resource module to avoid the wraparound problems of
367 Unix uses the resource module to avoid the wraparound problems of
368 time.clock(). Under Unix, an estimate of time spent on system tasks
368 time.clock(). Under Unix, an estimate of time spent on system tasks
369 is also given (for Windows platforms this is reported as 0.0).
369 is also given (for Windows platforms this is reported as 0.0).
370
370
371 If -t is given, an additional -N<N> option can be given, where <N>
371 If -t is given, an additional -N<N> option can be given, where <N>
372 must be an integer indicating how many times you want the script to
372 must be an integer indicating how many times you want the script to
373 run. The final timing report will include total and per run results.
373 run. The final timing report will include total and per run results.
374
374
375 For example (testing the script uniq_stable.py)::
375 For example (testing the script uniq_stable.py)::
376
376
377 In [1]: run -t uniq_stable
377 In [1]: run -t uniq_stable
378
378
379 IPython CPU timings (estimated):\\
379 IPython CPU timings (estimated):\\
380 User : 0.19597 s.\\
380 User : 0.19597 s.\\
381 System: 0.0 s.\\
381 System: 0.0 s.\\
382
382
383 In [2]: run -t -N5 uniq_stable
383 In [2]: run -t -N5 uniq_stable
384
384
385 IPython CPU timings (estimated):\\
385 IPython CPU timings (estimated):\\
386 Total runs performed: 5\\
386 Total runs performed: 5\\
387 Times : Total Per run\\
387 Times : Total Per run\\
388 User : 0.910862 s, 0.1821724 s.\\
388 User : 0.910862 s, 0.1821724 s.\\
389 System: 0.0 s, 0.0 s.
389 System: 0.0 s, 0.0 s.
390
390
391 -d: run your program under the control of pdb, the Python debugger.
391 -d: run your program under the control of pdb, the Python debugger.
392 This allows you to execute your program step by step, watch variables,
392 This allows you to execute your program step by step, watch variables,
393 etc. Internally, what IPython does is similar to calling:
393 etc. Internally, what IPython does is similar to calling:
394
394
395 pdb.run('execfile("YOURFILENAME")')
395 pdb.run('execfile("YOURFILENAME")')
396
396
397 with a breakpoint set on line 1 of your file. You can change the line
397 with a breakpoint set on line 1 of your file. You can change the line
398 number for this automatic breakpoint to be <N> by using the -bN option
398 number for this automatic breakpoint to be <N> by using the -bN option
399 (where N must be an integer). For example::
399 (where N must be an integer). For example::
400
400
401 %run -d -b40 myscript
401 %run -d -b40 myscript
402
402
403 will set the first breakpoint at line 40 in myscript.py. Note that
403 will set the first breakpoint at line 40 in myscript.py. Note that
404 the first breakpoint must be set on a line which actually does
404 the first breakpoint must be set on a line which actually does
405 something (not a comment or docstring) for it to stop execution.
405 something (not a comment or docstring) for it to stop execution.
406
406
407 When the pdb debugger starts, you will see a (Pdb) prompt. You must
407 When the pdb debugger starts, you will see a (Pdb) prompt. You must
408 first enter 'c' (without quotes) to start execution up to the first
408 first enter 'c' (without quotes) to start execution up to the first
409 breakpoint.
409 breakpoint.
410
410
411 Entering 'help' gives information about the use of the debugger. You
411 Entering 'help' gives information about the use of the debugger. You
412 can easily see pdb's full documentation with "import pdb;pdb.help()"
412 can easily see pdb's full documentation with "import pdb;pdb.help()"
413 at a prompt.
413 at a prompt.
414
414
415 -p: run program under the control of the Python profiler module (which
415 -p: run program under the control of the Python profiler module (which
416 prints a detailed report of execution times, function calls, etc).
416 prints a detailed report of execution times, function calls, etc).
417
417
418 You can pass other options after -p which affect the behavior of the
418 You can pass other options after -p which affect the behavior of the
419 profiler itself. See the docs for %prun for details.
419 profiler itself. See the docs for %prun for details.
420
420
421 In this mode, the program's variables do NOT propagate back to the
421 In this mode, the program's variables do NOT propagate back to the
422 IPython interactive namespace (because they remain in the namespace
422 IPython interactive namespace (because they remain in the namespace
423 where the profiler executes them).
423 where the profiler executes them).
424
424
425 Internally this triggers a call to %prun, see its documentation for
425 Internally this triggers a call to %prun, see its documentation for
426 details on the options available specifically for profiling.
426 details on the options available specifically for profiling.
427
427
428 There is one special usage for which the text above doesn't apply:
428 There is one special usage for which the text above doesn't apply:
429 if the filename ends with .ipy, the file is run as ipython script,
429 if the filename ends with .ipy, the file is run as ipython script,
430 just as if the commands were written on IPython prompt.
430 just as if the commands were written on IPython prompt.
431
431
432 -m: specify module name to load instead of script path. Similar to
432 -m: specify module name to load instead of script path. Similar to
433 the -m option for the python interpreter. Use this option last if you
433 the -m option for the python interpreter. Use this option last if you
434 want to combine with other %run options. Unlike the python interpreter
434 want to combine with other %run options. Unlike the python interpreter
435 only source modules are allowed no .pyc or .pyo files.
435 only source modules are allowed no .pyc or .pyo files.
436 For example::
436 For example::
437
437
438 %run -m example
438 %run -m example
439
439
440 will run the example module.
440 will run the example module.
441
441
442 """
442 """
443
443
444 # get arguments and set sys.argv for program to be run.
444 # get arguments and set sys.argv for program to be run.
445 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
445 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
446 mode='list', list_all=1)
446 mode='list', list_all=1)
447 if "m" in opts:
447 if "m" in opts:
448 modulename = opts["m"][0]
448 modulename = opts["m"][0]
449 modpath = find_mod(modulename)
449 modpath = find_mod(modulename)
450 if modpath is None:
450 if modpath is None:
451 warn('%r is not a valid modulename on sys.path'%modulename)
451 warn('%r is not a valid modulename on sys.path'%modulename)
452 return
452 return
453 arg_lst = [modpath] + arg_lst
453 arg_lst = [modpath] + arg_lst
454 try:
454 try:
455 filename = file_finder(arg_lst[0])
455 filename = file_finder(arg_lst[0])
456 except IndexError:
456 except IndexError:
457 warn('you must provide at least a filename.')
457 warn('you must provide at least a filename.')
458 print '\n%run:\n', oinspect.getdoc(self.run)
458 print '\n%run:\n', oinspect.getdoc(self.run)
459 return
459 return
460 except IOError as e:
460 except IOError as e:
461 try:
461 try:
462 msg = str(e)
462 msg = str(e)
463 except UnicodeError:
463 except UnicodeError:
464 msg = e.message
464 msg = e.message
465 error(msg)
465 error(msg)
466 return
466 return
467
467
468 if filename.lower().endswith('.ipy'):
468 if filename.lower().endswith('.ipy'):
469 self.shell.safe_execfile_ipy(filename)
469 self.shell.safe_execfile_ipy(filename)
470 return
470 return
471
471
472 # Control the response to exit() calls made by the script being run
472 # Control the response to exit() calls made by the script being run
473 exit_ignore = 'e' in opts
473 exit_ignore = 'e' in opts
474
474
475 # Make sure that the running script gets a proper sys.argv as if it
475 # Make sure that the running script gets a proper sys.argv as if it
476 # were run from a system shell.
476 # were run from a system shell.
477 save_argv = sys.argv # save it for later restoring
477 save_argv = sys.argv # save it for later restoring
478
478
479 # simulate shell expansion on arguments, at least tilde expansion
479 # simulate shell expansion on arguments, at least tilde expansion
480 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
480 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
481
481
482 sys.argv = [filename] + args # put in the proper filename
482 sys.argv = [filename] + args # put in the proper filename
483 # protect sys.argv from potential unicode strings on Python 2:
483 # protect sys.argv from potential unicode strings on Python 2:
484 if not py3compat.PY3:
484 if not py3compat.PY3:
485 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
485 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
486
486
487 if 'i' in opts:
487 if 'i' in opts:
488 # Run in user's interactive namespace
488 # Run in user's interactive namespace
489 prog_ns = self.shell.user_ns
489 prog_ns = self.shell.user_ns
490 __name__save = self.shell.user_ns['__name__']
490 __name__save = self.shell.user_ns['__name__']
491 prog_ns['__name__'] = '__main__'
491 prog_ns['__name__'] = '__main__'
492 main_mod = self.shell.new_main_mod(prog_ns)
492 main_mod = self.shell.new_main_mod(prog_ns)
493 else:
493 else:
494 # Run in a fresh, empty namespace
494 # Run in a fresh, empty namespace
495 if 'n' in opts:
495 if 'n' in opts:
496 name = os.path.splitext(os.path.basename(filename))[0]
496 name = os.path.splitext(os.path.basename(filename))[0]
497 else:
497 else:
498 name = '__main__'
498 name = '__main__'
499
499
500 main_mod = self.shell.new_main_mod()
500 main_mod = self.shell.new_main_mod()
501 prog_ns = main_mod.__dict__
501 prog_ns = main_mod.__dict__
502 prog_ns['__name__'] = name
502 prog_ns['__name__'] = name
503
503
504 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
504 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
505 # set the __file__ global in the script's namespace
505 # set the __file__ global in the script's namespace
506 prog_ns['__file__'] = filename
506 prog_ns['__file__'] = filename
507
507
508 # pickle fix. See interactiveshell for an explanation. But we need to
508 # pickle fix. See interactiveshell for an explanation. But we need to
509 # make sure that, if we overwrite __main__, we replace it at the end
509 # make sure that, if we overwrite __main__, we replace it at the end
510 main_mod_name = prog_ns['__name__']
510 main_mod_name = prog_ns['__name__']
511
511
512 if main_mod_name == '__main__':
512 if main_mod_name == '__main__':
513 restore_main = sys.modules['__main__']
513 restore_main = sys.modules['__main__']
514 else:
514 else:
515 restore_main = False
515 restore_main = False
516
516
517 # This needs to be undone at the end to prevent holding references to
517 # This needs to be undone at the end to prevent holding references to
518 # every single object ever created.
518 # every single object ever created.
519 sys.modules[main_mod_name] = main_mod
519 sys.modules[main_mod_name] = main_mod
520
520
521 try:
521 try:
522 stats = None
522 stats = None
523 with self.shell.readline_no_record:
523 with self.shell.readline_no_record:
524 if 'p' in opts:
524 if 'p' in opts:
525 stats = self.prun('', None, False, opts, arg_lst, prog_ns)
525 stats = self.prun('', None, False, opts, arg_lst, prog_ns)
526 else:
526 else:
527 if 'd' in opts:
527 if 'd' in opts:
528 deb = debugger.Pdb(self.shell.colors)
528 deb = debugger.Pdb(self.shell.colors)
529 # reset Breakpoint state, which is moronically kept
529 # reset Breakpoint state, which is moronically kept
530 # in a class
530 # in a class
531 bdb.Breakpoint.next = 1
531 bdb.Breakpoint.next = 1
532 bdb.Breakpoint.bplist = {}
532 bdb.Breakpoint.bplist = {}
533 bdb.Breakpoint.bpbynumber = [None]
533 bdb.Breakpoint.bpbynumber = [None]
534 # Set an initial breakpoint to stop execution
534 # Set an initial breakpoint to stop execution
535 maxtries = 10
535 maxtries = 10
536 bp = int(opts.get('b', [1])[0])
536 bp = int(opts.get('b', [1])[0])
537 checkline = deb.checkline(filename, bp)
537 checkline = deb.checkline(filename, bp)
538 if not checkline:
538 if not checkline:
539 for bp in range(bp + 1, bp + maxtries + 1):
539 for bp in range(bp + 1, bp + maxtries + 1):
540 if deb.checkline(filename, bp):
540 if deb.checkline(filename, bp):
541 break
541 break
542 else:
542 else:
543 msg = ("\nI failed to find a valid line to set "
543 msg = ("\nI failed to find a valid line to set "
544 "a breakpoint\n"
544 "a breakpoint\n"
545 "after trying up to line: %s.\n"
545 "after trying up to line: %s.\n"
546 "Please set a valid breakpoint manually "
546 "Please set a valid breakpoint manually "
547 "with the -b option." % bp)
547 "with the -b option." % bp)
548 error(msg)
548 error(msg)
549 return
549 return
550 # if we find a good linenumber, set the breakpoint
550 # if we find a good linenumber, set the breakpoint
551 deb.do_break('%s:%s' % (filename, bp))
551 deb.do_break('%s:%s' % (filename, bp))
552 # Start file run
552 # Start file run
553 print "NOTE: Enter 'c' at the",
553 print "NOTE: Enter 'c' at the",
554 print "%s prompt to start your script." % deb.prompt
554 print "%s prompt to start your script." % deb.prompt
555 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
555 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
556 try:
556 try:
557 deb.run('execfile("%s", prog_ns)' % filename, ns)
557 deb.run('execfile("%s", prog_ns)' % filename, ns)
558
558
559 except:
559 except:
560 etype, value, tb = sys.exc_info()
560 etype, value, tb = sys.exc_info()
561 # Skip three frames in the traceback: the %run one,
561 # Skip three frames in the traceback: the %run one,
562 # one inside bdb.py, and the command-line typed by the
562 # one inside bdb.py, and the command-line typed by the
563 # user (run by exec in pdb itself).
563 # user (run by exec in pdb itself).
564 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
564 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
565 else:
565 else:
566 if runner is None:
566 if runner is None:
567 runner = self.default_runner
567 runner = self.default_runner
568 if runner is None:
568 if runner is None:
569 runner = self.shell.safe_execfile
569 runner = self.shell.safe_execfile
570 if 't' in opts:
570 if 't' in opts:
571 # timed execution
571 # timed execution
572 try:
572 try:
573 nruns = int(opts['N'][0])
573 nruns = int(opts['N'][0])
574 if nruns < 1:
574 if nruns < 1:
575 error('Number of runs must be >=1')
575 error('Number of runs must be >=1')
576 return
576 return
577 except (KeyError):
577 except (KeyError):
578 nruns = 1
578 nruns = 1
579 twall0 = time.time()
579 twall0 = time.time()
580 if nruns == 1:
580 if nruns == 1:
581 t0 = clock2()
581 t0 = clock2()
582 runner(filename, prog_ns, prog_ns,
582 runner(filename, prog_ns, prog_ns,
583 exit_ignore=exit_ignore)
583 exit_ignore=exit_ignore)
584 t1 = clock2()
584 t1 = clock2()
585 t_usr = t1[0] - t0[0]
585 t_usr = t1[0] - t0[0]
586 t_sys = t1[1] - t0[1]
586 t_sys = t1[1] - t0[1]
587 print "\nIPython CPU timings (estimated):"
587 print "\nIPython CPU timings (estimated):"
588 print " User : %10.2f s." % t_usr
588 print " User : %10.2f s." % t_usr
589 print " System : %10.2f s." % t_sys
589 print " System : %10.2f s." % t_sys
590 else:
590 else:
591 runs = range(nruns)
591 runs = range(nruns)
592 t0 = clock2()
592 t0 = clock2()
593 for nr in runs:
593 for nr in runs:
594 runner(filename, prog_ns, prog_ns,
594 runner(filename, prog_ns, prog_ns,
595 exit_ignore=exit_ignore)
595 exit_ignore=exit_ignore)
596 t1 = clock2()
596 t1 = clock2()
597 t_usr = t1[0] - t0[0]
597 t_usr = t1[0] - t0[0]
598 t_sys = t1[1] - t0[1]
598 t_sys = t1[1] - t0[1]
599 print "\nIPython CPU timings (estimated):"
599 print "\nIPython CPU timings (estimated):"
600 print "Total runs performed:", nruns
600 print "Total runs performed:", nruns
601 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
601 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
602 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
602 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
603 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
603 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
604 twall1 = time.time()
604 twall1 = time.time()
605 print "Wall time: %10.2f s." % (twall1 - twall0)
605 print "Wall time: %10.2f s." % (twall1 - twall0)
606
606
607 else:
607 else:
608 # regular execution
608 # regular execution
609 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
609 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
610
610
611 if 'i' in opts:
611 if 'i' in opts:
612 self.shell.user_ns['__name__'] = __name__save
612 self.shell.user_ns['__name__'] = __name__save
613 else:
613 else:
614 # The shell MUST hold a reference to prog_ns so after %run
614 # The shell MUST hold a reference to prog_ns so after %run
615 # exits, the python deletion mechanism doesn't zero it out
615 # exits, the python deletion mechanism doesn't zero it out
616 # (leaving dangling references).
616 # (leaving dangling references).
617 self.shell.cache_main_mod(prog_ns, filename)
617 self.shell.cache_main_mod(prog_ns, filename)
618 # update IPython interactive namespace
618 # update IPython interactive namespace
619
619
620 # Some forms of read errors on the file may mean the
620 # Some forms of read errors on the file may mean the
621 # __name__ key was never set; using pop we don't have to
621 # __name__ key was never set; using pop we don't have to
622 # worry about a possible KeyError.
622 # worry about a possible KeyError.
623 prog_ns.pop('__name__', None)
623 prog_ns.pop('__name__', None)
624
624
625 self.shell.user_ns.update(prog_ns)
625 self.shell.user_ns.update(prog_ns)
626 finally:
626 finally:
627 # It's a bit of a mystery why, but __builtins__ can change from
627 # It's a bit of a mystery why, but __builtins__ can change from
628 # being a module to becoming a dict missing some key data after
628 # being a module to becoming a dict missing some key data after
629 # %run. As best I can see, this is NOT something IPython is doing
629 # %run. As best I can see, this is NOT something IPython is doing
630 # at all, and similar problems have been reported before:
630 # at all, and similar problems have been reported before:
631 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
631 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
632 # Since this seems to be done by the interpreter itself, the best
632 # Since this seems to be done by the interpreter itself, the best
633 # we can do is to at least restore __builtins__ for the user on
633 # we can do is to at least restore __builtins__ for the user on
634 # exit.
634 # exit.
635 self.shell.user_ns['__builtins__'] = builtin_mod
635 self.shell.user_ns['__builtins__'] = builtin_mod
636
636
637 # Ensure key global structures are restored
637 # Ensure key global structures are restored
638 sys.argv = save_argv
638 sys.argv = save_argv
639 if restore_main:
639 if restore_main:
640 sys.modules['__main__'] = restore_main
640 sys.modules['__main__'] = restore_main
641 else:
641 else:
642 # Remove from sys.modules the reference to main_mod we'd
642 # Remove from sys.modules the reference to main_mod we'd
643 # added. Otherwise it will trap references to objects
643 # added. Otherwise it will trap references to objects
644 # contained therein.
644 # contained therein.
645 del sys.modules[main_mod_name]
645 del sys.modules[main_mod_name]
646
646
647 return stats
647 return stats
648
648
649 @skip_doctest
649 @skip_doctest
650 @line_cell_magic
650 @line_cell_magic
651 def timeit(self, line='', cell=None):
651 def timeit(self, line='', cell=None):
652 """Time execution of a Python statement or expression
652 """Time execution of a Python statement or expression
653
653
654 Usage, in line mode:
654 Usage, in line mode:
655 %timeit [-n<N> -r<R> [-t|-c]] statement
655 %timeit [-n<N> -r<R> [-t|-c]] statement
656 or in cell mode:
656 or in cell mode:
657 %%timeit [-n<N> -r<R> [-t|-c]] setup_code
657 %%timeit [-n<N> -r<R> [-t|-c]] setup_code
658 code
658 code
659 code...
659 code...
660
660
661 Time execution of a Python statement or expression using the timeit
661 Time execution of a Python statement or expression using the timeit
662 module. This function can be used both as a line and cell magic:
662 module. This function can be used both as a line and cell magic:
663
663
664 - In line mode you can time a single-line statement (though multiple
664 - In line mode you can time a single-line statement (though multiple
665 ones can be chained with using semicolons).
665 ones can be chained with using semicolons).
666
666
667 - In cell mode, the statement in the first line is used as setup code
667 - In cell mode, the statement in the first line is used as setup code
668 (executed but not timed) and the body of the cell is timed. The cell
668 (executed but not timed) and the body of the cell is timed. The cell
669 body has access to any variables created in the setup code.
669 body has access to any variables created in the setup code.
670
670
671 Options:
671 Options:
672 -n<N>: execute the given statement <N> times in a loop. If this value
672 -n<N>: execute the given statement <N> times in a loop. If this value
673 is not given, a fitting value is chosen.
673 is not given, a fitting value is chosen.
674
674
675 -r<R>: repeat the loop iteration <R> times and take the best result.
675 -r<R>: repeat the loop iteration <R> times and take the best result.
676 Default: 3
676 Default: 3
677
677
678 -t: use time.time to measure the time, which is the default on Unix.
678 -t: use time.time to measure the time, which is the default on Unix.
679 This function measures wall time.
679 This function measures wall time.
680
680
681 -c: use time.clock to measure the time, which is the default on
681 -c: use time.clock to measure the time, which is the default on
682 Windows and measures wall time. On Unix, resource.getrusage is used
682 Windows and measures wall time. On Unix, resource.getrusage is used
683 instead and returns the CPU user time.
683 instead and returns the CPU user time.
684
684
685 -p<P>: use a precision of <P> digits to display the timing result.
685 -p<P>: use a precision of <P> digits to display the timing result.
686 Default: 3
686 Default: 3
687
687
688
688
689 Examples
689 Examples
690 --------
690 --------
691 ::
691 ::
692
692
693 In [1]: %timeit pass
693 In [1]: %timeit pass
694 10000000 loops, best of 3: 53.3 ns per loop
694 10000000 loops, best of 3: 53.3 ns per loop
695
695
696 In [2]: u = None
696 In [2]: u = None
697
697
698 In [3]: %timeit u is None
698 In [3]: %timeit u is None
699 10000000 loops, best of 3: 184 ns per loop
699 10000000 loops, best of 3: 184 ns per loop
700
700
701 In [4]: %timeit -r 4 u == None
701 In [4]: %timeit -r 4 u == None
702 1000000 loops, best of 4: 242 ns per loop
702 1000000 loops, best of 4: 242 ns per loop
703
703
704 In [5]: import time
704 In [5]: import time
705
705
706 In [6]: %timeit -n1 time.sleep(2)
706 In [6]: %timeit -n1 time.sleep(2)
707 1 loops, best of 3: 2 s per loop
707 1 loops, best of 3: 2 s per loop
708
708
709
709
710 The times reported by %timeit will be slightly higher than those
710 The times reported by %timeit will be slightly higher than those
711 reported by the timeit.py script when variables are accessed. This is
711 reported by the timeit.py script when variables are accessed. This is
712 due to the fact that %timeit executes the statement in the namespace
712 due to the fact that %timeit executes the statement in the namespace
713 of the shell, compared with timeit.py, which uses a single setup
713 of the shell, compared with timeit.py, which uses a single setup
714 statement to import function or create variables. Generally, the bias
714 statement to import function or create variables. Generally, the bias
715 does not matter as long as results from timeit.py are not mixed with
715 does not matter as long as results from timeit.py are not mixed with
716 those from %timeit."""
716 those from %timeit."""
717
717
718 import timeit
718 import timeit
719 import math
719 import math
720
720
721 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
721 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
722 # certain terminals. Until we figure out a robust way of
722 # certain terminals. Until we figure out a robust way of
723 # auto-detecting if the terminal can deal with it, use plain 'us' for
723 # auto-detecting if the terminal can deal with it, use plain 'us' for
724 # microseconds. I am really NOT happy about disabling the proper
724 # microseconds. I am really NOT happy about disabling the proper
725 # 'micro' prefix, but crashing is worse... If anyone knows what the
725 # 'micro' prefix, but crashing is worse... If anyone knows what the
726 # right solution for this is, I'm all ears...
726 # right solution for this is, I'm all ears...
727 #
727 #
728 # Note: using
728 # Note: using
729 #
729 #
730 # s = u'\xb5'
730 # s = u'\xb5'
731 # s.encode(sys.getdefaultencoding())
731 # s.encode(sys.getdefaultencoding())
732 #
732 #
733 # is not sufficient, as I've seen terminals where that fails but
733 # is not sufficient, as I've seen terminals where that fails but
734 # print s
734 # print s
735 #
735 #
736 # succeeds
736 # succeeds
737 #
737 #
738 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
738 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
739
739
740 #units = [u"s", u"ms",u'\xb5',"ns"]
740 #units = [u"s", u"ms",u'\xb5',"ns"]
741 units = [u"s", u"ms",u'us',"ns"]
741 units = [u"s", u"ms",u'us',"ns"]
742
742
743 scaling = [1, 1e3, 1e6, 1e9]
743 scaling = [1, 1e3, 1e6, 1e9]
744
744
745 opts, stmt = self.parse_options(line,'n:r:tcp:',
745 opts, stmt = self.parse_options(line,'n:r:tcp:',
746 posix=False, strict=False)
746 posix=False, strict=False)
747 if stmt == "" and cell is None:
747 if stmt == "" and cell is None:
748 return
748 return
749 timefunc = timeit.default_timer
749 timefunc = timeit.default_timer
750 number = int(getattr(opts, "n", 0))
750 number = int(getattr(opts, "n", 0))
751 repeat = int(getattr(opts, "r", timeit.default_repeat))
751 repeat = int(getattr(opts, "r", timeit.default_repeat))
752 precision = int(getattr(opts, "p", 3))
752 precision = int(getattr(opts, "p", 3))
753 if hasattr(opts, "t"):
753 if hasattr(opts, "t"):
754 timefunc = time.time
754 timefunc = time.time
755 if hasattr(opts, "c"):
755 if hasattr(opts, "c"):
756 timefunc = clock
756 timefunc = clock
757
757
758 timer = timeit.Timer(timer=timefunc)
758 timer = timeit.Timer(timer=timefunc)
759 # this code has tight coupling to the inner workings of timeit.Timer,
759 # this code has tight coupling to the inner workings of timeit.Timer,
760 # but is there a better way to achieve that the code stmt has access
760 # but is there a better way to achieve that the code stmt has access
761 # to the shell namespace?
761 # to the shell namespace?
762 transform = self.shell.input_splitter.transform_cell
762 transform = self.shell.input_splitter.transform_cell
763 if cell is None:
763 if cell is None:
764 # called as line magic
764 # called as line magic
765 setup = 'pass'
765 setup = 'pass'
766 stmt = timeit.reindent(transform(stmt), 8)
766 stmt = timeit.reindent(transform(stmt), 8)
767 else:
767 else:
768 setup = timeit.reindent(transform(stmt), 4)
768 setup = timeit.reindent(transform(stmt), 4)
769 stmt = timeit.reindent(transform(cell), 8)
769 stmt = timeit.reindent(transform(cell), 8)
770
770
771 # From Python 3.3, this template uses new-style string formatting.
771 # From Python 3.3, this template uses new-style string formatting.
772 if sys.version_info >= (3, 3):
772 if sys.version_info >= (3, 3):
773 src = timeit.template.format(stmt=stmt, setup=setup)
773 src = timeit.template.format(stmt=stmt, setup=setup)
774 else:
774 else:
775 src = timeit.template % dict(stmt=stmt, setup=setup)
775 src = timeit.template % dict(stmt=stmt, setup=setup)
776
776
777 # Track compilation time so it can be reported if too long
777 # Track compilation time so it can be reported if too long
778 # Minimum time above which compilation time will be reported
778 # Minimum time above which compilation time will be reported
779 tc_min = 0.1
779 tc_min = 0.1
780
780
781 t0 = clock()
781 t0 = clock()
782 code = compile(src, "<magic-timeit>", "exec")
782 code = compile(src, "<magic-timeit>", "exec")
783 tc = clock()-t0
783 tc = clock()-t0
784
784
785 ns = {}
785 ns = {}
786 exec code in self.shell.user_ns, ns
786 exec code in self.shell.user_ns, ns
787 timer.inner = ns["inner"]
787 timer.inner = ns["inner"]
788
788
789 if number == 0:
789 if number == 0:
790 # determine number so that 0.2 <= total time < 2.0
790 # determine number so that 0.2 <= total time < 2.0
791 number = 1
791 number = 1
792 for i in range(1, 10):
792 for i in range(1, 10):
793 if timer.timeit(number) >= 0.2:
793 if timer.timeit(number) >= 0.2:
794 break
794 break
795 number *= 10
795 number *= 10
796
796
797 best = min(timer.repeat(repeat, number)) / number
797 best = min(timer.repeat(repeat, number)) / number
798
798
799 if best > 0.0 and best < 1000.0:
799 if best > 0.0 and best < 1000.0:
800 order = min(-int(math.floor(math.log10(best)) // 3), 3)
800 order = min(-int(math.floor(math.log10(best)) // 3), 3)
801 elif best >= 1000.0:
801 elif best >= 1000.0:
802 order = 0
802 order = 0
803 else:
803 else:
804 order = 3
804 order = 3
805 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
805 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
806 precision,
806 precision,
807 best * scaling[order],
807 best * scaling[order],
808 units[order])
808 units[order])
809 if tc > tc_min:
809 if tc > tc_min:
810 print "Compiler time: %.2f s" % tc
810 print "Compiler time: %.2f s" % tc
811
811
812 @skip_doctest
812 @skip_doctest
813 @needs_local_scope
813 @needs_local_scope
814 @line_magic
814 @line_magic
815 def time(self,parameter_s, user_locals):
815 def time(self,parameter_s, local_ns=None):
816 """Time execution of a Python statement or expression.
816 """Time execution of a Python statement or expression.
817
817
818 The CPU and wall clock times are printed, and the value of the
818 The CPU and wall clock times are printed, and the value of the
819 expression (if any) is returned. Note that under Win32, system time
819 expression (if any) is returned. Note that under Win32, system time
820 is always reported as 0, since it can not be measured.
820 is always reported as 0, since it can not be measured.
821
821
822 This function provides very basic timing functionality. In Python
822 This function provides very basic timing functionality. In Python
823 2.3, the timeit module offers more control and sophistication, so this
823 2.3, the timeit module offers more control and sophistication, so this
824 could be rewritten to use it (patches welcome).
824 could be rewritten to use it (patches welcome).
825
825
826 Examples
826 Examples
827 --------
827 --------
828 ::
828 ::
829
829
830 In [1]: time 2**128
830 In [1]: time 2**128
831 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
831 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
832 Wall time: 0.00
832 Wall time: 0.00
833 Out[1]: 340282366920938463463374607431768211456L
833 Out[1]: 340282366920938463463374607431768211456L
834
834
835 In [2]: n = 1000000
835 In [2]: n = 1000000
836
836
837 In [3]: time sum(range(n))
837 In [3]: time sum(range(n))
838 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
838 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
839 Wall time: 1.37
839 Wall time: 1.37
840 Out[3]: 499999500000L
840 Out[3]: 499999500000L
841
841
842 In [4]: time print 'hello world'
842 In [4]: time print 'hello world'
843 hello world
843 hello world
844 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
844 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
845 Wall time: 0.00
845 Wall time: 0.00
846
846
847 Note that the time needed by Python to compile the given expression
847 Note that the time needed by Python to compile the given expression
848 will be reported if it is more than 0.1s. In this example, the
848 will be reported if it is more than 0.1s. In this example, the
849 actual exponentiation is done by Python at compilation time, so while
849 actual exponentiation is done by Python at compilation time, so while
850 the expression can take a noticeable amount of time to compute, that
850 the expression can take a noticeable amount of time to compute, that
851 time is purely due to the compilation:
851 time is purely due to the compilation:
852
852
853 In [5]: time 3**9999;
853 In [5]: time 3**9999;
854 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
854 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
855 Wall time: 0.00 s
855 Wall time: 0.00 s
856
856
857 In [6]: time 3**999999;
857 In [6]: time 3**999999;
858 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
858 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
859 Wall time: 0.00 s
859 Wall time: 0.00 s
860 Compiler : 0.78 s
860 Compiler : 0.78 s
861 """
861 """
862
862
863 # fail immediately if the given expression can't be compiled
863 # fail immediately if the given expression can't be compiled
864
864
865 expr = self.shell.prefilter(parameter_s,False)
865 expr = self.shell.prefilter(parameter_s,False)
866
866
867 # Minimum time above which compilation time will be reported
867 # Minimum time above which compilation time will be reported
868 tc_min = 0.1
868 tc_min = 0.1
869
869
870 try:
870 try:
871 mode = 'eval'
871 mode = 'eval'
872 t0 = clock()
872 t0 = clock()
873 code = compile(expr,'<timed eval>',mode)
873 code = compile(expr,'<timed eval>',mode)
874 tc = clock()-t0
874 tc = clock()-t0
875 except SyntaxError:
875 except SyntaxError:
876 mode = 'exec'
876 mode = 'exec'
877 t0 = clock()
877 t0 = clock()
878 code = compile(expr,'<timed exec>',mode)
878 code = compile(expr,'<timed exec>',mode)
879 tc = clock()-t0
879 tc = clock()-t0
880 # skew measurement as little as possible
880 # skew measurement as little as possible
881 glob = self.shell.user_ns
881 glob = self.shell.user_ns
882 wtime = time.time
882 wtime = time.time
883 # time execution
883 # time execution
884 wall_st = wtime()
884 wall_st = wtime()
885 if mode=='eval':
885 if mode=='eval':
886 st = clock2()
886 st = clock2()
887 out = eval(code, glob, user_locals)
887 out = eval(code, glob, local_ns)
888 end = clock2()
888 end = clock2()
889 else:
889 else:
890 st = clock2()
890 st = clock2()
891 exec code in glob, user_locals
891 exec code in glob, local_ns
892 end = clock2()
892 end = clock2()
893 out = None
893 out = None
894 wall_end = wtime()
894 wall_end = wtime()
895 # Compute actual times and report
895 # Compute actual times and report
896 wall_time = wall_end-wall_st
896 wall_time = wall_end-wall_st
897 cpu_user = end[0]-st[0]
897 cpu_user = end[0]-st[0]
898 cpu_sys = end[1]-st[1]
898 cpu_sys = end[1]-st[1]
899 cpu_tot = cpu_user+cpu_sys
899 cpu_tot = cpu_user+cpu_sys
900 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
900 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
901 (cpu_user,cpu_sys,cpu_tot)
901 (cpu_user,cpu_sys,cpu_tot)
902 print "Wall time: %.2f s" % wall_time
902 print "Wall time: %.2f s" % wall_time
903 if tc > tc_min:
903 if tc > tc_min:
904 print "Compiler : %.2f s" % tc
904 print "Compiler : %.2f s" % tc
905 return out
905 return out
906
906
907 @skip_doctest
907 @skip_doctest
908 @line_magic
908 @line_magic
909 def macro(self, parameter_s=''):
909 def macro(self, parameter_s=''):
910 """Define a macro for future re-execution. It accepts ranges of history,
910 """Define a macro for future re-execution. It accepts ranges of history,
911 filenames or string objects.
911 filenames or string objects.
912
912
913 Usage:\\
913 Usage:\\
914 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
914 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
915
915
916 Options:
916 Options:
917
917
918 -r: use 'raw' input. By default, the 'processed' history is used,
918 -r: use 'raw' input. By default, the 'processed' history is used,
919 so that magics are loaded in their transformed version to valid
919 so that magics are loaded in their transformed version to valid
920 Python. If this option is given, the raw input as typed as the
920 Python. If this option is given, the raw input as typed as the
921 command line is used instead.
921 command line is used instead.
922
922
923 This will define a global variable called `name` which is a string
923 This will define a global variable called `name` which is a string
924 made of joining the slices and lines you specify (n1,n2,... numbers
924 made of joining the slices and lines you specify (n1,n2,... numbers
925 above) from your input history into a single string. This variable
925 above) from your input history into a single string. This variable
926 acts like an automatic function which re-executes those lines as if
926 acts like an automatic function which re-executes those lines as if
927 you had typed them. You just type 'name' at the prompt and the code
927 you had typed them. You just type 'name' at the prompt and the code
928 executes.
928 executes.
929
929
930 The syntax for indicating input ranges is described in %history.
930 The syntax for indicating input ranges is described in %history.
931
931
932 Note: as a 'hidden' feature, you can also use traditional python slice
932 Note: as a 'hidden' feature, you can also use traditional python slice
933 notation, where N:M means numbers N through M-1.
933 notation, where N:M means numbers N through M-1.
934
934
935 For example, if your history contains (%hist prints it)::
935 For example, if your history contains (%hist prints it)::
936
936
937 44: x=1
937 44: x=1
938 45: y=3
938 45: y=3
939 46: z=x+y
939 46: z=x+y
940 47: print x
940 47: print x
941 48: a=5
941 48: a=5
942 49: print 'x',x,'y',y
942 49: print 'x',x,'y',y
943
943
944 you can create a macro with lines 44 through 47 (included) and line 49
944 you can create a macro with lines 44 through 47 (included) and line 49
945 called my_macro with::
945 called my_macro with::
946
946
947 In [55]: %macro my_macro 44-47 49
947 In [55]: %macro my_macro 44-47 49
948
948
949 Now, typing `my_macro` (without quotes) will re-execute all this code
949 Now, typing `my_macro` (without quotes) will re-execute all this code
950 in one pass.
950 in one pass.
951
951
952 You don't need to give the line-numbers in order, and any given line
952 You don't need to give the line-numbers in order, and any given line
953 number can appear multiple times. You can assemble macros with any
953 number can appear multiple times. You can assemble macros with any
954 lines from your input history in any order.
954 lines from your input history in any order.
955
955
956 The macro is a simple object which holds its value in an attribute,
956 The macro is a simple object which holds its value in an attribute,
957 but IPython's display system checks for macros and executes them as
957 but IPython's display system checks for macros and executes them as
958 code instead of printing them when you type their name.
958 code instead of printing them when you type their name.
959
959
960 You can view a macro's contents by explicitly printing it with::
960 You can view a macro's contents by explicitly printing it with::
961
961
962 print macro_name
962 print macro_name
963
963
964 """
964 """
965 opts,args = self.parse_options(parameter_s,'r',mode='list')
965 opts,args = self.parse_options(parameter_s,'r',mode='list')
966 if not args: # List existing macros
966 if not args: # List existing macros
967 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
967 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
968 isinstance(v, Macro))
968 isinstance(v, Macro))
969 if len(args) == 1:
969 if len(args) == 1:
970 raise UsageError(
970 raise UsageError(
971 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
971 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
972 name, codefrom = args[0], " ".join(args[1:])
972 name, codefrom = args[0], " ".join(args[1:])
973
973
974 #print 'rng',ranges # dbg
974 #print 'rng',ranges # dbg
975 try:
975 try:
976 lines = self.shell.find_user_code(codefrom, 'r' in opts)
976 lines = self.shell.find_user_code(codefrom, 'r' in opts)
977 except (ValueError, TypeError) as e:
977 except (ValueError, TypeError) as e:
978 print e.args[0]
978 print e.args[0]
979 return
979 return
980 macro = Macro(lines)
980 macro = Macro(lines)
981 self.shell.define_macro(name, macro)
981 self.shell.define_macro(name, macro)
982 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
982 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
983 print '=== Macro contents: ==='
983 print '=== Macro contents: ==='
984 print macro,
984 print macro,
985
985
986 @magic_arguments.magic_arguments()
986 @magic_arguments.magic_arguments()
987 @magic_arguments.argument('output', type=str, default='', nargs='?',
987 @magic_arguments.argument('output', type=str, default='', nargs='?',
988 help="""The name of the variable in which to store output.
988 help="""The name of the variable in which to store output.
989 This is a utils.io.CapturedIO object with stdout/err attributes
989 This is a utils.io.CapturedIO object with stdout/err attributes
990 for the text of the captured output.
990 for the text of the captured output.
991
991
992 CapturedOutput also has a show() method for displaying the output,
992 CapturedOutput also has a show() method for displaying the output,
993 and __call__ as well, so you can use that to quickly display the
993 and __call__ as well, so you can use that to quickly display the
994 output.
994 output.
995
995
996 If unspecified, captured output is discarded.
996 If unspecified, captured output is discarded.
997 """
997 """
998 )
998 )
999 @magic_arguments.argument('--no-stderr', action="store_true",
999 @magic_arguments.argument('--no-stderr', action="store_true",
1000 help="""Don't capture stderr."""
1000 help="""Don't capture stderr."""
1001 )
1001 )
1002 @magic_arguments.argument('--no-stdout', action="store_true",
1002 @magic_arguments.argument('--no-stdout', action="store_true",
1003 help="""Don't capture stdout."""
1003 help="""Don't capture stdout."""
1004 )
1004 )
1005 @cell_magic
1005 @cell_magic
1006 def capture(self, line, cell):
1006 def capture(self, line, cell):
1007 """run the cell, capturing stdout/err"""
1007 """run the cell, capturing stdout/err"""
1008 args = magic_arguments.parse_argstring(self.capture, line)
1008 args = magic_arguments.parse_argstring(self.capture, line)
1009 out = not args.no_stdout
1009 out = not args.no_stdout
1010 err = not args.no_stderr
1010 err = not args.no_stderr
1011 with capture_output(out, err) as io:
1011 with capture_output(out, err) as io:
1012 self.shell.run_cell(cell)
1012 self.shell.run_cell(cell)
1013 if args.output:
1013 if args.output:
1014 self.shell.user_ns[args.output] = io
1014 self.shell.user_ns[args.output] = io
@@ -1,364 +1,371 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 ===========
3 ===========
4 octavemagic
4 octavemagic
5 ===========
5 ===========
6
6
7 Magics for interacting with Octave via oct2py.
7 Magics for interacting with Octave via oct2py.
8
8
9 .. note::
9 .. note::
10
10
11 The ``oct2py`` module needs to be installed separately and
11 The ``oct2py`` module needs to be installed separately and
12 can be obtained using ``easy_install`` or ``pip``.
12 can be obtained using ``easy_install`` or ``pip``.
13
13
14 Usage
14 Usage
15 =====
15 =====
16
16
17 ``%octave``
17 ``%octave``
18
18
19 {OCTAVE_DOC}
19 {OCTAVE_DOC}
20
20
21 ``%octave_push``
21 ``%octave_push``
22
22
23 {OCTAVE_PUSH_DOC}
23 {OCTAVE_PUSH_DOC}
24
24
25 ``%octave_pull``
25 ``%octave_pull``
26
26
27 {OCTAVE_PULL_DOC}
27 {OCTAVE_PULL_DOC}
28
28
29 """
29 """
30
30
31 #-----------------------------------------------------------------------------
31 #-----------------------------------------------------------------------------
32 # Copyright (C) 2012 The IPython Development Team
32 # Copyright (C) 2012 The IPython Development Team
33 #
33 #
34 # Distributed under the terms of the BSD License. The full license is in
34 # Distributed under the terms of the BSD License. The full license is in
35 # the file COPYING, distributed as part of this software.
35 # the file COPYING, distributed as part of this software.
36 #-----------------------------------------------------------------------------
36 #-----------------------------------------------------------------------------
37
37
38 import tempfile
38 import tempfile
39 from glob import glob
39 from glob import glob
40 from shutil import rmtree
40 from shutil import rmtree
41
41
42 import numpy as np
42 import numpy as np
43 import oct2py
43 import oct2py
44 from xml.dom import minidom
44 from xml.dom import minidom
45
45
46 from IPython.core.displaypub import publish_display_data
46 from IPython.core.displaypub import publish_display_data
47 from IPython.core.magic import (Magics, magics_class, line_magic,
47 from IPython.core.magic import (Magics, magics_class, line_magic,
48 line_cell_magic)
48 line_cell_magic, needs_local_scope)
49 from IPython.testing.skipdoctest import skip_doctest
49 from IPython.testing.skipdoctest import skip_doctest
50 from IPython.core.magic_arguments import (
50 from IPython.core.magic_arguments import (
51 argument, magic_arguments, parse_argstring
51 argument, magic_arguments, parse_argstring
52 )
52 )
53 from IPython.utils.py3compat import unicode_to_str
53 from IPython.utils.py3compat import unicode_to_str
54
54
55 class OctaveMagicError(oct2py.Oct2PyError):
55 class OctaveMagicError(oct2py.Oct2PyError):
56 pass
56 pass
57
57
58 _mimetypes = {'png' : 'image/png',
58 _mimetypes = {'png' : 'image/png',
59 'svg' : 'image/svg+xml',
59 'svg' : 'image/svg+xml',
60 'jpg' : 'image/jpeg',
60 'jpg' : 'image/jpeg',
61 'jpeg': 'image/jpeg'}
61 'jpeg': 'image/jpeg'}
62
62
63 @magics_class
63 @magics_class
64 class OctaveMagics(Magics):
64 class OctaveMagics(Magics):
65 """A set of magics useful for interactive work with Octave via oct2py.
65 """A set of magics useful for interactive work with Octave via oct2py.
66 """
66 """
67 def __init__(self, shell):
67 def __init__(self, shell):
68 """
68 """
69 Parameters
69 Parameters
70 ----------
70 ----------
71 shell : IPython shell
71 shell : IPython shell
72
72
73 """
73 """
74 super(OctaveMagics, self).__init__(shell)
74 super(OctaveMagics, self).__init__(shell)
75 self._oct = oct2py.Oct2Py()
75 self._oct = oct2py.Oct2Py()
76 self._plot_format = 'png'
76 self._plot_format = 'png'
77
77
78 # Allow publish_display_data to be overridden for
78 # Allow publish_display_data to be overridden for
79 # testing purposes.
79 # testing purposes.
80 self._publish_display_data = publish_display_data
80 self._publish_display_data = publish_display_data
81
81
82
82
83 def _fix_gnuplot_svg_size(self, image, size=None):
83 def _fix_gnuplot_svg_size(self, image, size=None):
84 """
84 """
85 GnuPlot SVGs do not have height/width attributes. Set
85 GnuPlot SVGs do not have height/width attributes. Set
86 these to be the same as the viewBox, so that the browser
86 these to be the same as the viewBox, so that the browser
87 scales the image correctly.
87 scales the image correctly.
88
88
89 Parameters
89 Parameters
90 ----------
90 ----------
91 image : str
91 image : str
92 SVG data.
92 SVG data.
93 size : tuple of int
93 size : tuple of int
94 Image width, height.
94 Image width, height.
95
95
96 """
96 """
97 (svg,) = minidom.parseString(image).getElementsByTagName('svg')
97 (svg,) = minidom.parseString(image).getElementsByTagName('svg')
98 viewbox = svg.getAttribute('viewBox').split(' ')
98 viewbox = svg.getAttribute('viewBox').split(' ')
99
99
100 if size is not None:
100 if size is not None:
101 width, height = size
101 width, height = size
102 else:
102 else:
103 width, height = viewbox[2:]
103 width, height = viewbox[2:]
104
104
105 svg.setAttribute('width', '%dpx' % width)
105 svg.setAttribute('width', '%dpx' % width)
106 svg.setAttribute('height', '%dpx' % height)
106 svg.setAttribute('height', '%dpx' % height)
107 return svg.toxml()
107 return svg.toxml()
108
108
109
109
110 @skip_doctest
110 @skip_doctest
111 @line_magic
111 @line_magic
112 def octave_push(self, line):
112 def octave_push(self, line):
113 '''
113 '''
114 Line-level magic that pushes a variable to Octave.
114 Line-level magic that pushes a variable to Octave.
115
115
116 `line` should be made up of whitespace separated variable names in the
116 `line` should be made up of whitespace separated variable names in the
117 IPython namespace::
117 IPython namespace::
118
118
119 In [7]: import numpy as np
119 In [7]: import numpy as np
120
120
121 In [8]: X = np.arange(5)
121 In [8]: X = np.arange(5)
122
122
123 In [9]: X.mean()
123 In [9]: X.mean()
124 Out[9]: 2.0
124 Out[9]: 2.0
125
125
126 In [10]: %octave_push X
126 In [10]: %octave_push X
127
127
128 In [11]: %octave mean(X)
128 In [11]: %octave mean(X)
129 Out[11]: 2.0
129 Out[11]: 2.0
130
130
131 '''
131 '''
132 inputs = line.split(' ')
132 inputs = line.split(' ')
133 for input in inputs:
133 for input in inputs:
134 input = unicode_to_str(input)
134 input = unicode_to_str(input)
135 self._oct.put(input, self.shell.user_ns[input])
135 self._oct.put(input, self.shell.user_ns[input])
136
136
137
137
138 @skip_doctest
138 @skip_doctest
139 @line_magic
139 @line_magic
140 def octave_pull(self, line):
140 def octave_pull(self, line):
141 '''
141 '''
142 Line-level magic that pulls a variable from Octave.
142 Line-level magic that pulls a variable from Octave.
143
143
144 In [18]: _ = %octave x = [1 2; 3 4]; y = 'hello'
144 In [18]: _ = %octave x = [1 2; 3 4]; y = 'hello'
145
145
146 In [19]: %octave_pull x y
146 In [19]: %octave_pull x y
147
147
148 In [20]: x
148 In [20]: x
149 Out[20]:
149 Out[20]:
150 array([[ 1., 2.],
150 array([[ 1., 2.],
151 [ 3., 4.]])
151 [ 3., 4.]])
152
152
153 In [21]: y
153 In [21]: y
154 Out[21]: 'hello'
154 Out[21]: 'hello'
155
155
156 '''
156 '''
157 outputs = line.split(' ')
157 outputs = line.split(' ')
158 for output in outputs:
158 for output in outputs:
159 output = unicode_to_str(output)
159 output = unicode_to_str(output)
160 self.shell.push({output: self._oct.get(output)})
160 self.shell.push({output: self._oct.get(output)})
161
161
162
162
163 @skip_doctest
163 @skip_doctest
164 @magic_arguments()
164 @magic_arguments()
165 @argument(
165 @argument(
166 '-i', '--input', action='append',
166 '-i', '--input', action='append',
167 help='Names of input variables to be pushed to Octave. Multiple names '
167 help='Names of input variables to be pushed to Octave. Multiple names '
168 'can be passed, separated by commas with no whitespace.'
168 'can be passed, separated by commas with no whitespace.'
169 )
169 )
170 @argument(
170 @argument(
171 '-o', '--output', action='append',
171 '-o', '--output', action='append',
172 help='Names of variables to be pulled from Octave after executing cell '
172 help='Names of variables to be pulled from Octave after executing cell '
173 'body. Multiple names can be passed, separated by commas with no '
173 'body. Multiple names can be passed, separated by commas with no '
174 'whitespace.'
174 'whitespace.'
175 )
175 )
176 @argument(
176 @argument(
177 '-s', '--size', action='store',
177 '-s', '--size', action='store',
178 help='Pixel size of plots, "width,height". Default is "-s 400,250".'
178 help='Pixel size of plots, "width,height". Default is "-s 400,250".'
179 )
179 )
180 @argument(
180 @argument(
181 '-f', '--format', action='store',
181 '-f', '--format', action='store',
182 help='Plot format (png, svg or jpg).'
182 help='Plot format (png, svg or jpg).'
183 )
183 )
184
184
185 @needs_local_scope
185 @argument(
186 @argument(
186 'code',
187 'code',
187 nargs='*',
188 nargs='*',
188 )
189 )
189 @line_cell_magic
190 @line_cell_magic
190 def octave(self, line, cell=None):
191 def octave(self, line, cell=None, local_ns=None):
191 '''
192 '''
192 Execute code in Octave, and pull some of the results back into the
193 Execute code in Octave, and pull some of the results back into the
193 Python namespace.
194 Python namespace.
194
195
195 In [9]: %octave X = [1 2; 3 4]; mean(X)
196 In [9]: %octave X = [1 2; 3 4]; mean(X)
196 Out[9]: array([[ 2., 3.]])
197 Out[9]: array([[ 2., 3.]])
197
198
198 As a cell, this will run a block of Octave code, without returning any
199 As a cell, this will run a block of Octave code, without returning any
199 value::
200 value::
200
201
201 In [10]: %%octave
202 In [10]: %%octave
202 ....: p = [-2, -1, 0, 1, 2]
203 ....: p = [-2, -1, 0, 1, 2]
203 ....: polyout(p, 'x')
204 ....: polyout(p, 'x')
204
205
205 -2*x^4 - 1*x^3 + 0*x^2 + 1*x^1 + 2
206 -2*x^4 - 1*x^3 + 0*x^2 + 1*x^1 + 2
206
207
207 In the notebook, plots are published as the output of the cell, e.g.
208 In the notebook, plots are published as the output of the cell, e.g.
208
209
209 %octave plot([1 2 3], [4 5 6])
210 %octave plot([1 2 3], [4 5 6])
210
211
211 will create a line plot.
212 will create a line plot.
212
213
213 Objects can be passed back and forth between Octave and IPython via the
214 Objects can be passed back and forth between Octave and IPython via the
214 -i and -o flags in line::
215 -i and -o flags in line::
215
216
216 In [14]: Z = np.array([1, 4, 5, 10])
217 In [14]: Z = np.array([1, 4, 5, 10])
217
218
218 In [15]: %octave -i Z mean(Z)
219 In [15]: %octave -i Z mean(Z)
219 Out[15]: array([ 5.])
220 Out[15]: array([ 5.])
220
221
221
222
222 In [16]: %octave -o W W = Z * mean(Z)
223 In [16]: %octave -o W W = Z * mean(Z)
223 Out[16]: array([ 5., 20., 25., 50.])
224 Out[16]: array([ 5., 20., 25., 50.])
224
225
225 In [17]: W
226 In [17]: W
226 Out[17]: array([ 5., 20., 25., 50.])
227 Out[17]: array([ 5., 20., 25., 50.])
227
228
228 The size and format of output plots can be specified::
229 The size and format of output plots can be specified::
229
230
230 In [18]: %%octave -s 600,800 -f svg
231 In [18]: %%octave -s 600,800 -f svg
231 ...: plot([1, 2, 3]);
232 ...: plot([1, 2, 3]);
232
233
233 '''
234 '''
234 args = parse_argstring(self.octave, line)
235 args = parse_argstring(self.octave, line)
235
236
236 # arguments 'code' in line are prepended to the cell lines
237 # arguments 'code' in line are prepended to the cell lines
237 if cell is None:
238 if cell is None:
238 code = ''
239 code = ''
239 return_output = True
240 return_output = True
240 line_mode = True
241 else:
241 else:
242 code = cell
242 code = cell
243 return_output = False
243 return_output = False
244 line_mode = False
245
244
246 code = ' '.join(args.code) + code
245 code = ' '.join(args.code) + code
247
246
247 # if there is no local namespace then default to an empty dict
248 if local_ns is None:
249 local_ns = {}
250
248 if args.input:
251 if args.input:
249 for input in ','.join(args.input).split(','):
252 for input in ','.join(args.input).split(','):
250 input = unicode_to_str(input)
253 input = unicode_to_str(input)
251 self._oct.put(input, self.shell.user_ns[input])
254 try:
255 val = local_ns[input]
256 except KeyError:
257 val = self.shell.user_ns[input]
258 self._oct.put(input, val)
252
259
253 # generate plots in a temporary directory
260 # generate plots in a temporary directory
254 plot_dir = tempfile.mkdtemp()
261 plot_dir = tempfile.mkdtemp()
255 if args.size is not None:
262 if args.size is not None:
256 size = args.size
263 size = args.size
257 else:
264 else:
258 size = '400,240'
265 size = '400,240'
259
266
260 if args.format is not None:
267 if args.format is not None:
261 plot_format = args.format
268 plot_format = args.format
262 else:
269 else:
263 plot_format = 'png'
270 plot_format = 'png'
264
271
265 pre_call = '''
272 pre_call = '''
266 global __ipy_figures = [];
273 global __ipy_figures = [];
267 page_screen_output(0);
274 page_screen_output(0);
268
275
269 function fig_create(src, event)
276 function fig_create(src, event)
270 global __ipy_figures;
277 global __ipy_figures;
271 __ipy_figures(size(__ipy_figures) + 1) = src;
278 __ipy_figures(size(__ipy_figures) + 1) = src;
272 set(src, "visible", "off");
279 set(src, "visible", "off");
273 end
280 end
274
281
275 set(0, 'DefaultFigureCreateFcn', @fig_create);
282 set(0, 'DefaultFigureCreateFcn', @fig_create);
276
283
277 close all;
284 close all;
278 clear ans;
285 clear ans;
279
286
280 # ___<end_pre_call>___ #
287 # ___<end_pre_call>___ #
281 '''
288 '''
282
289
283 post_call = '''
290 post_call = '''
284 # ___<start_post_call>___ #
291 # ___<start_post_call>___ #
285
292
286 # Save output of the last execution
293 # Save output of the last execution
287 if exist("ans") == 1
294 if exist("ans") == 1
288 _ = ans;
295 _ = ans;
289 else
296 else
290 _ = nan;
297 _ = nan;
291 end
298 end
292
299
293 for f = __ipy_figures
300 for f = __ipy_figures
294 outfile = sprintf('%(plot_dir)s/__ipy_oct_fig_%%03d.png', f);
301 outfile = sprintf('%(plot_dir)s/__ipy_oct_fig_%%03d.png', f);
295 try
302 try
296 print(f, outfile, '-d%(plot_format)s', '-tight', '-S%(size)s');
303 print(f, outfile, '-d%(plot_format)s', '-tight', '-S%(size)s');
297 end
304 end
298 end
305 end
299
306
300 ''' % locals()
307 ''' % locals()
301
308
302 code = ' '.join((pre_call, code, post_call))
309 code = ' '.join((pre_call, code, post_call))
303 try:
310 try:
304 text_output = self._oct.run(code, verbose=False)
311 text_output = self._oct.run(code, verbose=False)
305 except (oct2py.Oct2PyError) as exception:
312 except (oct2py.Oct2PyError) as exception:
306 msg = exception.message
313 msg = exception.message
307 msg = msg.split('# ___<end_pre_call>___ #')[1]
314 msg = msg.split('# ___<end_pre_call>___ #')[1]
308 msg = msg.split('# ___<start_post_call>___ #')[0]
315 msg = msg.split('# ___<start_post_call>___ #')[0]
309 raise OctaveMagicError('Octave could not complete execution. '
316 raise OctaveMagicError('Octave could not complete execution. '
310 'Traceback (currently broken in oct2py): %s'
317 'Traceback (currently broken in oct2py): %s'
311 % msg)
318 % msg)
312
319
313 key = 'OctaveMagic.Octave'
320 key = 'OctaveMagic.Octave'
314 display_data = []
321 display_data = []
315
322
316 # Publish text output
323 # Publish text output
317 if text_output:
324 if text_output:
318 display_data.append((key, {'text/plain': text_output}))
325 display_data.append((key, {'text/plain': text_output}))
319
326
320 # Publish images
327 # Publish images
321 images = [open(imgfile, 'rb').read() for imgfile in \
328 images = [open(imgfile, 'rb').read() for imgfile in \
322 glob("%s/*" % plot_dir)]
329 glob("%s/*" % plot_dir)]
323 rmtree(plot_dir)
330 rmtree(plot_dir)
324
331
325 plot_mime_type = _mimetypes.get(plot_format, 'image/png')
332 plot_mime_type = _mimetypes.get(plot_format, 'image/png')
326 width, height = [int(s) for s in size.split(',')]
333 width, height = [int(s) for s in size.split(',')]
327 for image in images:
334 for image in images:
328 if plot_format == 'svg':
335 if plot_format == 'svg':
329 image = self._fix_gnuplot_svg_size(image, size=(width, height))
336 image = self._fix_gnuplot_svg_size(image, size=(width, height))
330 display_data.append((key, {plot_mime_type: image}))
337 display_data.append((key, {plot_mime_type: image}))
331
338
332 if args.output:
339 if args.output:
333 for output in ','.join(args.output).split(','):
340 for output in ','.join(args.output).split(','):
334 output = unicode_to_str(output)
341 output = unicode_to_str(output)
335 self.shell.push({output: self._oct.get(output)})
342 self.shell.push({output: self._oct.get(output)})
336
343
337 for source, data in display_data:
344 for source, data in display_data:
338 self._publish_display_data(source, data)
345 self._publish_display_data(source, data)
339
346
340 if return_output:
347 if return_output:
341 ans = self._oct.get('_')
348 ans = self._oct.get('_')
342
349
343 # Unfortunately, Octave doesn't have a "None" object,
350 # Unfortunately, Octave doesn't have a "None" object,
344 # so we can't return any NaN outputs
351 # so we can't return any NaN outputs
345 if np.isscalar(ans) and np.isnan(ans):
352 if np.isscalar(ans) and np.isnan(ans):
346 ans = None
353 ans = None
347
354
348 return ans
355 return ans
349
356
350
357
351 __doc__ = __doc__.format(
358 __doc__ = __doc__.format(
352 OCTAVE_DOC = ' '*8 + OctaveMagics.octave.__doc__,
359 OCTAVE_DOC = ' '*8 + OctaveMagics.octave.__doc__,
353 OCTAVE_PUSH_DOC = ' '*8 + OctaveMagics.octave_push.__doc__,
360 OCTAVE_PUSH_DOC = ' '*8 + OctaveMagics.octave_push.__doc__,
354 OCTAVE_PULL_DOC = ' '*8 + OctaveMagics.octave_pull.__doc__
361 OCTAVE_PULL_DOC = ' '*8 + OctaveMagics.octave_pull.__doc__
355 )
362 )
356
363
357
364
358 _loaded = False
365 _loaded = False
359 def load_ipython_extension(ip):
366 def load_ipython_extension(ip):
360 """Load the extension in IPython."""
367 """Load the extension in IPython."""
361 global _loaded
368 global _loaded
362 if not _loaded:
369 if not _loaded:
363 ip.register_magics(OctaveMagics)
370 ip.register_magics(OctaveMagics)
364 _loaded = True
371 _loaded = True
@@ -1,587 +1,597 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 ======
3 ======
4 Rmagic
4 Rmagic
5 ======
5 ======
6
6
7 Magic command interface for interactive work with R via rpy2
7 Magic command interface for interactive work with R via rpy2
8
8
9 Usage
9 Usage
10 =====
10 =====
11
11
12 ``%R``
12 ``%R``
13
13
14 {R_DOC}
14 {R_DOC}
15
15
16 ``%Rpush``
16 ``%Rpush``
17
17
18 {RPUSH_DOC}
18 {RPUSH_DOC}
19
19
20 ``%Rpull``
20 ``%Rpull``
21
21
22 {RPULL_DOC}
22 {RPULL_DOC}
23
23
24 ``%Rget``
24 ``%Rget``
25
25
26 {RGET_DOC}
26 {RGET_DOC}
27
27
28 """
28 """
29
29
30 #-----------------------------------------------------------------------------
30 #-----------------------------------------------------------------------------
31 # Copyright (C) 2012 The IPython Development Team
31 # Copyright (C) 2012 The IPython Development Team
32 #
32 #
33 # Distributed under the terms of the BSD License. The full license is in
33 # Distributed under the terms of the BSD License. The full license is in
34 # the file COPYING, distributed as part of this software.
34 # the file COPYING, distributed as part of this software.
35 #-----------------------------------------------------------------------------
35 #-----------------------------------------------------------------------------
36
36
37 import sys
37 import sys
38 import tempfile
38 import tempfile
39 from glob import glob
39 from glob import glob
40 from shutil import rmtree
40 from shutil import rmtree
41 from getopt import getopt
41 from getopt import getopt
42
42
43 # numpy and rpy2 imports
43 # numpy and rpy2 imports
44
44
45 import numpy as np
45 import numpy as np
46
46
47 import rpy2.rinterface as ri
47 import rpy2.rinterface as ri
48 import rpy2.robjects as ro
48 import rpy2.robjects as ro
49 from rpy2.robjects.numpy2ri import numpy2ri
49 from rpy2.robjects.numpy2ri import numpy2ri
50 ro.conversion.py2ri = numpy2ri
50 ro.conversion.py2ri = numpy2ri
51
51
52 # IPython imports
52 # IPython imports
53
53
54 from IPython.core.displaypub import publish_display_data
54 from IPython.core.displaypub import publish_display_data
55 from IPython.core.magic import (Magics, magics_class, cell_magic, line_magic,
55 from IPython.core.magic import (Magics, magics_class, cell_magic, line_magic,
56 line_cell_magic)
56 line_cell_magic, needs_local_scope)
57 from IPython.testing.skipdoctest import skip_doctest
57 from IPython.testing.skipdoctest import skip_doctest
58 from IPython.core.magic_arguments import (
58 from IPython.core.magic_arguments import (
59 argument, magic_arguments, parse_argstring
59 argument, magic_arguments, parse_argstring
60 )
60 )
61 from IPython.utils.py3compat import str_to_unicode, unicode_to_str, PY3
61 from IPython.utils.py3compat import str_to_unicode, unicode_to_str, PY3
62
62
63 class RInterpreterError(ri.RRuntimeError):
63 class RInterpreterError(ri.RRuntimeError):
64 """An error when running R code in a %%R magic cell."""
64 """An error when running R code in a %%R magic cell."""
65 def __init__(self, line, err, stdout):
65 def __init__(self, line, err, stdout):
66 self.line = line
66 self.line = line
67 self.err = err.rstrip()
67 self.err = err.rstrip()
68 self.stdout = stdout.rstrip()
68 self.stdout = stdout.rstrip()
69
69
70 def __unicode__(self):
70 def __unicode__(self):
71 s = 'Failed to parse and evaluate line %r.\nR error message: %r' % \
71 s = 'Failed to parse and evaluate line %r.\nR error message: %r' % \
72 (self.line, self.err)
72 (self.line, self.err)
73 if self.stdout and (self.stdout != self.err):
73 if self.stdout and (self.stdout != self.err):
74 s += '\nR stdout:\n' + self.stdout
74 s += '\nR stdout:\n' + self.stdout
75 return s
75 return s
76
76
77 if PY3:
77 if PY3:
78 __str__ = __unicode__
78 __str__ = __unicode__
79 else:
79 else:
80 def __str__(self):
80 def __str__(self):
81 return unicode_to_str(unicode(self), 'utf-8')
81 return unicode_to_str(unicode(self), 'utf-8')
82
82
83 def Rconverter(Robj, dataframe=False):
83 def Rconverter(Robj, dataframe=False):
84 """
84 """
85 Convert an object in R's namespace to one suitable
85 Convert an object in R's namespace to one suitable
86 for ipython's namespace.
86 for ipython's namespace.
87
87
88 For a data.frame, it tries to return a structured array.
88 For a data.frame, it tries to return a structured array.
89 It first checks for colnames, then names.
89 It first checks for colnames, then names.
90 If all are NULL, it returns np.asarray(Robj), else
90 If all are NULL, it returns np.asarray(Robj), else
91 it tries to construct a recarray
91 it tries to construct a recarray
92
92
93 Parameters
93 Parameters
94 ----------
94 ----------
95
95
96 Robj: an R object returned from rpy2
96 Robj: an R object returned from rpy2
97 """
97 """
98 is_data_frame = ro.r('is.data.frame')
98 is_data_frame = ro.r('is.data.frame')
99 colnames = ro.r('colnames')
99 colnames = ro.r('colnames')
100 rownames = ro.r('rownames') # with pandas, these could be used for the index
100 rownames = ro.r('rownames') # with pandas, these could be used for the index
101 names = ro.r('names')
101 names = ro.r('names')
102
102
103 if dataframe:
103 if dataframe:
104 as_data_frame = ro.r('as.data.frame')
104 as_data_frame = ro.r('as.data.frame')
105 cols = colnames(Robj)
105 cols = colnames(Robj)
106 _names = names(Robj)
106 _names = names(Robj)
107 if cols != ri.NULL:
107 if cols != ri.NULL:
108 Robj = as_data_frame(Robj)
108 Robj = as_data_frame(Robj)
109 names = tuple(np.array(cols))
109 names = tuple(np.array(cols))
110 elif _names != ri.NULL:
110 elif _names != ri.NULL:
111 names = tuple(np.array(_names))
111 names = tuple(np.array(_names))
112 else: # failed to find names
112 else: # failed to find names
113 return np.asarray(Robj)
113 return np.asarray(Robj)
114 Robj = np.rec.fromarrays(Robj, names = names)
114 Robj = np.rec.fromarrays(Robj, names = names)
115 return np.asarray(Robj)
115 return np.asarray(Robj)
116
116
117 @magics_class
117 @magics_class
118 class RMagics(Magics):
118 class RMagics(Magics):
119 """A set of magics useful for interactive work with R via rpy2.
119 """A set of magics useful for interactive work with R via rpy2.
120 """
120 """
121
121
122 def __init__(self, shell, Rconverter=Rconverter,
122 def __init__(self, shell, Rconverter=Rconverter,
123 pyconverter=np.asarray,
123 pyconverter=np.asarray,
124 cache_display_data=False):
124 cache_display_data=False):
125 """
125 """
126 Parameters
126 Parameters
127 ----------
127 ----------
128
128
129 shell : IPython shell
129 shell : IPython shell
130
130
131 pyconverter : callable
131 pyconverter : callable
132 To be called on values in ipython namespace before
132 To be called on values in ipython namespace before
133 assigning to variables in rpy2.
133 assigning to variables in rpy2.
134
134
135 cache_display_data : bool
135 cache_display_data : bool
136 If True, the published results of the final call to R are
136 If True, the published results of the final call to R are
137 cached in the variable 'display_cache'.
137 cached in the variable 'display_cache'.
138
138
139 """
139 """
140 super(RMagics, self).__init__(shell)
140 super(RMagics, self).__init__(shell)
141 self.cache_display_data = cache_display_data
141 self.cache_display_data = cache_display_data
142
142
143 self.r = ro.R()
143 self.r = ro.R()
144
144
145 self.Rstdout_cache = []
145 self.Rstdout_cache = []
146 self.pyconverter = pyconverter
146 self.pyconverter = pyconverter
147 self.Rconverter = Rconverter
147 self.Rconverter = Rconverter
148
148
149 def eval(self, line):
149 def eval(self, line):
150 '''
150 '''
151 Parse and evaluate a line with rpy2.
151 Parse and evaluate a line with rpy2.
152 Returns the output to R's stdout() connection
152 Returns the output to R's stdout() connection
153 and the value of eval(parse(line)).
153 and the value of eval(parse(line)).
154 '''
154 '''
155 old_writeconsole = ri.get_writeconsole()
155 old_writeconsole = ri.get_writeconsole()
156 ri.set_writeconsole(self.write_console)
156 ri.set_writeconsole(self.write_console)
157 try:
157 try:
158 value = ri.baseenv['eval'](ri.parse(line))
158 value = ri.baseenv['eval'](ri.parse(line))
159 except (ri.RRuntimeError, ValueError) as exception:
159 except (ri.RRuntimeError, ValueError) as exception:
160 warning_or_other_msg = self.flush() # otherwise next return seems to have copy of error
160 warning_or_other_msg = self.flush() # otherwise next return seems to have copy of error
161 raise RInterpreterError(line, str_to_unicode(str(exception)), warning_or_other_msg)
161 raise RInterpreterError(line, str_to_unicode(str(exception)), warning_or_other_msg)
162 text_output = self.flush()
162 text_output = self.flush()
163 ri.set_writeconsole(old_writeconsole)
163 ri.set_writeconsole(old_writeconsole)
164 return text_output, value
164 return text_output, value
165
165
166 def write_console(self, output):
166 def write_console(self, output):
167 '''
167 '''
168 A hook to capture R's stdout in a cache.
168 A hook to capture R's stdout in a cache.
169 '''
169 '''
170 self.Rstdout_cache.append(output)
170 self.Rstdout_cache.append(output)
171
171
172 def flush(self):
172 def flush(self):
173 '''
173 '''
174 Flush R's stdout cache to a string, returning the string.
174 Flush R's stdout cache to a string, returning the string.
175 '''
175 '''
176 value = ''.join([str_to_unicode(s, 'utf-8') for s in self.Rstdout_cache])
176 value = ''.join([str_to_unicode(s, 'utf-8') for s in self.Rstdout_cache])
177 self.Rstdout_cache = []
177 self.Rstdout_cache = []
178 return value
178 return value
179
179
180 @skip_doctest
180 @skip_doctest
181 @line_magic
181 @line_magic
182 def Rpush(self, line):
182 def Rpush(self, line):
183 '''
183 '''
184 A line-level magic for R that pushes
184 A line-level magic for R that pushes
185 variables from python to rpy2. The line should be made up
185 variables from python to rpy2. The line should be made up
186 of whitespace separated variable names in the IPython
186 of whitespace separated variable names in the IPython
187 namespace::
187 namespace::
188
188
189 In [7]: import numpy as np
189 In [7]: import numpy as np
190
190
191 In [8]: X = np.array([4.5,6.3,7.9])
191 In [8]: X = np.array([4.5,6.3,7.9])
192
192
193 In [9]: X.mean()
193 In [9]: X.mean()
194 Out[9]: 6.2333333333333343
194 Out[9]: 6.2333333333333343
195
195
196 In [10]: %Rpush X
196 In [10]: %Rpush X
197
197
198 In [11]: %R mean(X)
198 In [11]: %R mean(X)
199 Out[11]: array([ 6.23333333])
199 Out[11]: array([ 6.23333333])
200
200
201 '''
201 '''
202
202
203 inputs = line.split(' ')
203 inputs = line.split(' ')
204 for input in inputs:
204 for input in inputs:
205 self.r.assign(input, self.pyconverter(self.shell.user_ns[input]))
205 self.r.assign(input, self.pyconverter(self.shell.user_ns[input]))
206
206
207 @skip_doctest
207 @skip_doctest
208 @magic_arguments()
208 @magic_arguments()
209 @argument(
209 @argument(
210 '-d', '--as_dataframe', action='store_true',
210 '-d', '--as_dataframe', action='store_true',
211 default=False,
211 default=False,
212 help='Convert objects to data.frames before returning to ipython.'
212 help='Convert objects to data.frames before returning to ipython.'
213 )
213 )
214 @argument(
214 @argument(
215 'outputs',
215 'outputs',
216 nargs='*',
216 nargs='*',
217 )
217 )
218 @line_magic
218 @line_magic
219 def Rpull(self, line):
219 def Rpull(self, line):
220 '''
220 '''
221 A line-level magic for R that pulls
221 A line-level magic for R that pulls
222 variables from python to rpy2::
222 variables from python to rpy2::
223
223
224 In [18]: _ = %R x = c(3,4,6.7); y = c(4,6,7); z = c('a',3,4)
224 In [18]: _ = %R x = c(3,4,6.7); y = c(4,6,7); z = c('a',3,4)
225
225
226 In [19]: %Rpull x y z
226 In [19]: %Rpull x y z
227
227
228 In [20]: x
228 In [20]: x
229 Out[20]: array([ 3. , 4. , 6.7])
229 Out[20]: array([ 3. , 4. , 6.7])
230
230
231 In [21]: y
231 In [21]: y
232 Out[21]: array([ 4., 6., 7.])
232 Out[21]: array([ 4., 6., 7.])
233
233
234 In [22]: z
234 In [22]: z
235 Out[22]:
235 Out[22]:
236 array(['a', '3', '4'],
236 array(['a', '3', '4'],
237 dtype='|S1')
237 dtype='|S1')
238
238
239
239
240 If --as_dataframe, then each object is returned as a structured array
240 If --as_dataframe, then each object is returned as a structured array
241 after first passed through "as.data.frame" in R before
241 after first passed through "as.data.frame" in R before
242 being calling self.Rconverter.
242 being calling self.Rconverter.
243 This is useful when a structured array is desired as output, or
243 This is useful when a structured array is desired as output, or
244 when the object in R has mixed data types.
244 when the object in R has mixed data types.
245 See the %%R docstring for more examples.
245 See the %%R docstring for more examples.
246
246
247 Notes
247 Notes
248 -----
248 -----
249
249
250 Beware that R names can have '.' so this is not fool proof.
250 Beware that R names can have '.' so this is not fool proof.
251 To avoid this, don't name your R objects with '.'s...
251 To avoid this, don't name your R objects with '.'s...
252
252
253 '''
253 '''
254 args = parse_argstring(self.Rpull, line)
254 args = parse_argstring(self.Rpull, line)
255 outputs = args.outputs
255 outputs = args.outputs
256 for output in outputs:
256 for output in outputs:
257 self.shell.push({output:self.Rconverter(self.r(output),dataframe=args.as_dataframe)})
257 self.shell.push({output:self.Rconverter(self.r(output),dataframe=args.as_dataframe)})
258
258
259 @skip_doctest
259 @skip_doctest
260 @magic_arguments()
260 @magic_arguments()
261 @argument(
261 @argument(
262 '-d', '--as_dataframe', action='store_true',
262 '-d', '--as_dataframe', action='store_true',
263 default=False,
263 default=False,
264 help='Convert objects to data.frames before returning to ipython.'
264 help='Convert objects to data.frames before returning to ipython.'
265 )
265 )
266 @argument(
266 @argument(
267 'output',
267 'output',
268 nargs=1,
268 nargs=1,
269 type=str,
269 type=str,
270 )
270 )
271 @line_magic
271 @line_magic
272 def Rget(self, line):
272 def Rget(self, line):
273 '''
273 '''
274 Return an object from rpy2, possibly as a structured array (if possible).
274 Return an object from rpy2, possibly as a structured array (if possible).
275 Similar to Rpull except only one argument is accepted and the value is
275 Similar to Rpull except only one argument is accepted and the value is
276 returned rather than pushed to self.shell.user_ns::
276 returned rather than pushed to self.shell.user_ns::
277
277
278 In [3]: dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')]
278 In [3]: dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')]
279
279
280 In [4]: datapy = np.array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5, 'e')], dtype=dtype)
280 In [4]: datapy = np.array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5, 'e')], dtype=dtype)
281
281
282 In [5]: %R -i datapy
282 In [5]: %R -i datapy
283
283
284 In [6]: %Rget datapy
284 In [6]: %Rget datapy
285 Out[6]:
285 Out[6]:
286 array([['1', '2', '3', '4'],
286 array([['1', '2', '3', '4'],
287 ['2', '3', '2', '5'],
287 ['2', '3', '2', '5'],
288 ['a', 'b', 'c', 'e']],
288 ['a', 'b', 'c', 'e']],
289 dtype='|S1')
289 dtype='|S1')
290
290
291 In [7]: %Rget -d datapy
291 In [7]: %Rget -d datapy
292 Out[7]:
292 Out[7]:
293 array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5.0, 'e')],
293 array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5.0, 'e')],
294 dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')])
294 dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')])
295
295
296 '''
296 '''
297 args = parse_argstring(self.Rget, line)
297 args = parse_argstring(self.Rget, line)
298 output = args.output
298 output = args.output
299 return self.Rconverter(self.r(output[0]),dataframe=args.as_dataframe)
299 return self.Rconverter(self.r(output[0]),dataframe=args.as_dataframe)
300
300
301
301
302 @skip_doctest
302 @skip_doctest
303 @magic_arguments()
303 @magic_arguments()
304 @argument(
304 @argument(
305 '-i', '--input', action='append',
305 '-i', '--input', action='append',
306 help='Names of input variable from shell.user_ns to be assigned to R variables of the same names after calling self.pyconverter. Multiple names can be passed separated only by commas with no whitespace.'
306 help='Names of input variable from shell.user_ns to be assigned to R variables of the same names after calling self.pyconverter. Multiple names can be passed separated only by commas with no whitespace.'
307 )
307 )
308 @argument(
308 @argument(
309 '-o', '--output', action='append',
309 '-o', '--output', action='append',
310 help='Names of variables to be pushed from rpy2 to shell.user_ns after executing cell body and applying self.Rconverter. Multiple names can be passed separated only by commas with no whitespace.'
310 help='Names of variables to be pushed from rpy2 to shell.user_ns after executing cell body and applying self.Rconverter. Multiple names can be passed separated only by commas with no whitespace.'
311 )
311 )
312 @argument(
312 @argument(
313 '-w', '--width', type=int,
313 '-w', '--width', type=int,
314 help='Width of png plotting device sent as an argument to *png* in R.'
314 help='Width of png plotting device sent as an argument to *png* in R.'
315 )
315 )
316 @argument(
316 @argument(
317 '-h', '--height', type=int,
317 '-h', '--height', type=int,
318 help='Height of png plotting device sent as an argument to *png* in R.'
318 help='Height of png plotting device sent as an argument to *png* in R.'
319 )
319 )
320
320
321 @argument(
321 @argument(
322 '-d', '--dataframe', action='append',
322 '-d', '--dataframe', action='append',
323 help='Convert these objects to data.frames and return as structured arrays.'
323 help='Convert these objects to data.frames and return as structured arrays.'
324 )
324 )
325 @argument(
325 @argument(
326 '-u', '--units', type=int,
326 '-u', '--units', type=int,
327 help='Units of png plotting device sent as an argument to *png* in R. One of ["px", "in", "cm", "mm"].'
327 help='Units of png plotting device sent as an argument to *png* in R. One of ["px", "in", "cm", "mm"].'
328 )
328 )
329 @argument(
329 @argument(
330 '-p', '--pointsize', type=int,
330 '-p', '--pointsize', type=int,
331 help='Pointsize of png plotting device sent as an argument to *png* in R.'
331 help='Pointsize of png plotting device sent as an argument to *png* in R.'
332 )
332 )
333 @argument(
333 @argument(
334 '-b', '--bg',
334 '-b', '--bg',
335 help='Background of png plotting device sent as an argument to *png* in R.'
335 help='Background of png plotting device sent as an argument to *png* in R.'
336 )
336 )
337 @argument(
337 @argument(
338 '-n', '--noreturn',
338 '-n', '--noreturn',
339 help='Force the magic to not return anything.',
339 help='Force the magic to not return anything.',
340 action='store_true',
340 action='store_true',
341 default=False
341 default=False
342 )
342 )
343 @argument(
343 @argument(
344 'code',
344 'code',
345 nargs='*',
345 nargs='*',
346 )
346 )
347 @needs_local_scope
347 @line_cell_magic
348 @line_cell_magic
348 def R(self, line, cell=None):
349 def R(self, line, cell=None, local_ns=None):
349 '''
350 '''
350 Execute code in R, and pull some of the results back into the Python namespace.
351 Execute code in R, and pull some of the results back into the Python namespace.
351
352
352 In line mode, this will evaluate an expression and convert the returned value to a Python object.
353 In line mode, this will evaluate an expression and convert the returned value to a Python object.
353 The return value is determined by rpy2's behaviour of returning the result of evaluating the
354 The return value is determined by rpy2's behaviour of returning the result of evaluating the
354 final line.
355 final line.
355
356
356 Multiple R lines can be executed by joining them with semicolons::
357 Multiple R lines can be executed by joining them with semicolons::
357
358
358 In [9]: %R X=c(1,4,5,7); sd(X); mean(X)
359 In [9]: %R X=c(1,4,5,7); sd(X); mean(X)
359 Out[9]: array([ 4.25])
360 Out[9]: array([ 4.25])
360
361
361 As a cell, this will run a block of R code, without bringing anything back by default::
362 As a cell, this will run a block of R code, without bringing anything back by default::
362
363
363 In [10]: %%R
364 In [10]: %%R
364 ....: Y = c(2,4,3,9)
365 ....: Y = c(2,4,3,9)
365 ....: print(summary(lm(Y~X)))
366 ....: print(summary(lm(Y~X)))
366 ....:
367 ....:
367
368
368 Call:
369 Call:
369 lm(formula = Y ~ X)
370 lm(formula = Y ~ X)
370
371
371 Residuals:
372 Residuals:
372 1 2 3 4
373 1 2 3 4
373 0.88 -0.24 -2.28 1.64
374 0.88 -0.24 -2.28 1.64
374
375
375 Coefficients:
376 Coefficients:
376 Estimate Std. Error t value Pr(>|t|)
377 Estimate Std. Error t value Pr(>|t|)
377 (Intercept) 0.0800 2.3000 0.035 0.975
378 (Intercept) 0.0800 2.3000 0.035 0.975
378 X 1.0400 0.4822 2.157 0.164
379 X 1.0400 0.4822 2.157 0.164
379
380
380 Residual standard error: 2.088 on 2 degrees of freedom
381 Residual standard error: 2.088 on 2 degrees of freedom
381 Multiple R-squared: 0.6993,Adjusted R-squared: 0.549
382 Multiple R-squared: 0.6993,Adjusted R-squared: 0.549
382 F-statistic: 4.651 on 1 and 2 DF, p-value: 0.1638
383 F-statistic: 4.651 on 1 and 2 DF, p-value: 0.1638
383
384
384 In the notebook, plots are published as the output of the cell.
385 In the notebook, plots are published as the output of the cell.
385
386
386 %R plot(X, Y)
387 %R plot(X, Y)
387
388
388 will create a scatter plot of X bs Y.
389 will create a scatter plot of X bs Y.
389
390
390 If cell is not None and line has some R code, it is prepended to
391 If cell is not None and line has some R code, it is prepended to
391 the R code in cell.
392 the R code in cell.
392
393
393 Objects can be passed back and forth between rpy2 and python via the -i -o flags in line::
394 Objects can be passed back and forth between rpy2 and python via the -i -o flags in line::
394
395
395 In [14]: Z = np.array([1,4,5,10])
396 In [14]: Z = np.array([1,4,5,10])
396
397
397 In [15]: %R -i Z mean(Z)
398 In [15]: %R -i Z mean(Z)
398 Out[15]: array([ 5.])
399 Out[15]: array([ 5.])
399
400
400
401
401 In [16]: %R -o W W=Z*mean(Z)
402 In [16]: %R -o W W=Z*mean(Z)
402 Out[16]: array([ 5., 20., 25., 50.])
403 Out[16]: array([ 5., 20., 25., 50.])
403
404
404 In [17]: W
405 In [17]: W
405 Out[17]: array([ 5., 20., 25., 50.])
406 Out[17]: array([ 5., 20., 25., 50.])
406
407
407 The return value is determined by these rules:
408 The return value is determined by these rules:
408
409
409 * If the cell is not None, the magic returns None.
410 * If the cell is not None, the magic returns None.
410
411
411 * If the cell evaluates as False, the resulting value is returned
412 * If the cell evaluates as False, the resulting value is returned
412 unless the final line prints something to the console, in
413 unless the final line prints something to the console, in
413 which case None is returned.
414 which case None is returned.
414
415
415 * If the final line results in a NULL value when evaluated
416 * If the final line results in a NULL value when evaluated
416 by rpy2, then None is returned.
417 by rpy2, then None is returned.
417
418
418 * No attempt is made to convert the final value to a structured array.
419 * No attempt is made to convert the final value to a structured array.
419 Use the --dataframe flag or %Rget to push / return a structured array.
420 Use the --dataframe flag or %Rget to push / return a structured array.
420
421
421 * If the -n flag is present, there is no return value.
422 * If the -n flag is present, there is no return value.
422
423
423 * A trailing ';' will also result in no return value as the last
424 * A trailing ';' will also result in no return value as the last
424 value in the line is an empty string.
425 value in the line is an empty string.
425
426
426 The --dataframe argument will attempt to return structured arrays.
427 The --dataframe argument will attempt to return structured arrays.
427 This is useful for dataframes with
428 This is useful for dataframes with
428 mixed data types. Note also that for a data.frame,
429 mixed data types. Note also that for a data.frame,
429 if it is returned as an ndarray, it is transposed::
430 if it is returned as an ndarray, it is transposed::
430
431
431 In [18]: dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')]
432 In [18]: dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')]
432
433
433 In [19]: datapy = np.array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5, 'e')], dtype=dtype)
434 In [19]: datapy = np.array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5, 'e')], dtype=dtype)
434
435
435 In [20]: %%R -o datar
436 In [20]: %%R -o datar
436 datar = datapy
437 datar = datapy
437 ....:
438 ....:
438
439
439 In [21]: datar
440 In [21]: datar
440 Out[21]:
441 Out[21]:
441 array([['1', '2', '3', '4'],
442 array([['1', '2', '3', '4'],
442 ['2', '3', '2', '5'],
443 ['2', '3', '2', '5'],
443 ['a', 'b', 'c', 'e']],
444 ['a', 'b', 'c', 'e']],
444 dtype='|S1')
445 dtype='|S1')
445
446
446 In [22]: %%R -d datar
447 In [22]: %%R -d datar
447 datar = datapy
448 datar = datapy
448 ....:
449 ....:
449
450
450 In [23]: datar
451 In [23]: datar
451 Out[23]:
452 Out[23]:
452 array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5.0, 'e')],
453 array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5.0, 'e')],
453 dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')])
454 dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')])
454
455
455 The --dataframe argument first tries colnames, then names.
456 The --dataframe argument first tries colnames, then names.
456 If both are NULL, it returns an ndarray (i.e. unstructured)::
457 If both are NULL, it returns an ndarray (i.e. unstructured)::
457
458
458 In [1]: %R mydata=c(4,6,8.3); NULL
459 In [1]: %R mydata=c(4,6,8.3); NULL
459
460
460 In [2]: %R -d mydata
461 In [2]: %R -d mydata
461
462
462 In [3]: mydata
463 In [3]: mydata
463 Out[3]: array([ 4. , 6. , 8.3])
464 Out[3]: array([ 4. , 6. , 8.3])
464
465
465 In [4]: %R names(mydata) = c('a','b','c'); NULL
466 In [4]: %R names(mydata) = c('a','b','c'); NULL
466
467
467 In [5]: %R -d mydata
468 In [5]: %R -d mydata
468
469
469 In [6]: mydata
470 In [6]: mydata
470 Out[6]:
471 Out[6]:
471 array((4.0, 6.0, 8.3),
472 array((4.0, 6.0, 8.3),
472 dtype=[('a', '<f8'), ('b', '<f8'), ('c', '<f8')])
473 dtype=[('a', '<f8'), ('b', '<f8'), ('c', '<f8')])
473
474
474 In [7]: %R -o mydata
475 In [7]: %R -o mydata
475
476
476 In [8]: mydata
477 In [8]: mydata
477 Out[8]: array([ 4. , 6. , 8.3])
478 Out[8]: array([ 4. , 6. , 8.3])
478
479
479 '''
480 '''
480
481
481 args = parse_argstring(self.R, line)
482 args = parse_argstring(self.R, line)
482
483
483 # arguments 'code' in line are prepended to
484 # arguments 'code' in line are prepended to
484 # the cell lines
485 # the cell lines
485 if not cell:
486
487 if cell is None:
486 code = ''
488 code = ''
487 return_output = True
489 return_output = True
488 line_mode = True
490 line_mode = True
489 else:
491 else:
490 code = cell
492 code = cell
491 return_output = False
493 return_output = False
492 line_mode = False
494 line_mode = False
493
495
494 code = ' '.join(args.code) + code
496 code = ' '.join(args.code) + code
495
497
498 # if there is no local namespace then default to an empty dict
499 if local_ns is None:
500 local_ns = {}
501
496 if args.input:
502 if args.input:
497 for input in ','.join(args.input).split(','):
503 for input in ','.join(args.input).split(','):
498 self.r.assign(input, self.pyconverter(self.shell.user_ns[input]))
504 try:
505 val = local_ns[input]
506 except KeyError:
507 val = self.shell.user_ns[input]
508 self.r.assign(input, self.pyconverter(val))
499
509
500 png_argdict = dict([(n, getattr(args, n)) for n in ['units', 'height', 'width', 'bg', 'pointsize']])
510 png_argdict = dict([(n, getattr(args, n)) for n in ['units', 'height', 'width', 'bg', 'pointsize']])
501 png_args = ','.join(['%s=%s' % (o,v) for o, v in png_argdict.items() if v is not None])
511 png_args = ','.join(['%s=%s' % (o,v) for o, v in png_argdict.items() if v is not None])
502 # execute the R code in a temporary directory
512 # execute the R code in a temporary directory
503
513
504 tmpd = tempfile.mkdtemp()
514 tmpd = tempfile.mkdtemp()
505 self.r('png("%s/Rplots%%03d.png",%s)' % (tmpd, png_args))
515 self.r('png("%s/Rplots%%03d.png",%s)' % (tmpd, png_args))
506
516
507 text_output = ''
517 text_output = ''
508 if line_mode:
518 if line_mode:
509 for line in code.split(';'):
519 for line in code.split(';'):
510 text_result, result = self.eval(line)
520 text_result, result = self.eval(line)
511 text_output += text_result
521 text_output += text_result
512 if text_result:
522 if text_result:
513 # the last line printed something to the console so we won't return it
523 # the last line printed something to the console so we won't return it
514 return_output = False
524 return_output = False
515 else:
525 else:
516 text_result, result = self.eval(code)
526 text_result, result = self.eval(code)
517 text_output += text_result
527 text_output += text_result
518
528
519 self.r('dev.off()')
529 self.r('dev.off()')
520
530
521 # read out all the saved .png files
531 # read out all the saved .png files
522
532
523 images = [open(imgfile, 'rb').read() for imgfile in glob("%s/Rplots*png" % tmpd)]
533 images = [open(imgfile, 'rb').read() for imgfile in glob("%s/Rplots*png" % tmpd)]
524
534
525 # now publish the images
535 # now publish the images
526 # mimicking IPython/zmq/pylab/backend_inline.py
536 # mimicking IPython/zmq/pylab/backend_inline.py
527 fmt = 'png'
537 fmt = 'png'
528 mimetypes = { 'png' : 'image/png', 'svg' : 'image/svg+xml' }
538 mimetypes = { 'png' : 'image/png', 'svg' : 'image/svg+xml' }
529 mime = mimetypes[fmt]
539 mime = mimetypes[fmt]
530
540
531 # publish the printed R objects, if any
541 # publish the printed R objects, if any
532
542
533 display_data = []
543 display_data = []
534 if text_output:
544 if text_output:
535 display_data.append(('RMagic.R', {'text/plain':text_output}))
545 display_data.append(('RMagic.R', {'text/plain':text_output}))
536
546
537 # flush text streams before sending figures, helps a little with output
547 # flush text streams before sending figures, helps a little with output
538 for image in images:
548 for image in images:
539 # synchronization in the console (though it's a bandaid, not a real sln)
549 # synchronization in the console (though it's a bandaid, not a real sln)
540 sys.stdout.flush(); sys.stderr.flush()
550 sys.stdout.flush(); sys.stderr.flush()
541 display_data.append(('RMagic.R', {mime: image}))
551 display_data.append(('RMagic.R', {mime: image}))
542
552
543 # kill the temporary directory
553 # kill the temporary directory
544 rmtree(tmpd)
554 rmtree(tmpd)
545
555
546 # try to turn every output into a numpy array
556 # try to turn every output into a numpy array
547 # this means that output are assumed to be castable
557 # this means that output are assumed to be castable
548 # as numpy arrays
558 # as numpy arrays
549
559
550 if args.output:
560 if args.output:
551 for output in ','.join(args.output).split(','):
561 for output in ','.join(args.output).split(','):
552 self.shell.push({output:self.Rconverter(self.r(output), dataframe=False)})
562 self.shell.push({output:self.Rconverter(self.r(output), dataframe=False)})
553
563
554 if args.dataframe:
564 if args.dataframe:
555 for output in ','.join(args.dataframe).split(','):
565 for output in ','.join(args.dataframe).split(','):
556 self.shell.push({output:self.Rconverter(self.r(output), dataframe=True)})
566 self.shell.push({output:self.Rconverter(self.r(output), dataframe=True)})
557
567
558 for tag, disp_d in display_data:
568 for tag, disp_d in display_data:
559 publish_display_data(tag, disp_d)
569 publish_display_data(tag, disp_d)
560
570
561 # this will keep a reference to the display_data
571 # this will keep a reference to the display_data
562 # which might be useful to other objects who happen to use
572 # which might be useful to other objects who happen to use
563 # this method
573 # this method
564
574
565 if self.cache_display_data:
575 if self.cache_display_data:
566 self.display_cache = display_data
576 self.display_cache = display_data
567
577
568 # if in line mode and return_output, return the result as an ndarray
578 # if in line mode and return_output, return the result as an ndarray
569 if return_output and not args.noreturn:
579 if return_output and not args.noreturn:
570 if result != ri.NULL:
580 if result != ri.NULL:
571 return self.Rconverter(result, dataframe=False)
581 return self.Rconverter(result, dataframe=False)
572
582
573 __doc__ = __doc__.format(
583 __doc__ = __doc__.format(
574 R_DOC = ' '*8 + RMagics.R.__doc__,
584 R_DOC = ' '*8 + RMagics.R.__doc__,
575 RPUSH_DOC = ' '*8 + RMagics.Rpush.__doc__,
585 RPUSH_DOC = ' '*8 + RMagics.Rpush.__doc__,
576 RPULL_DOC = ' '*8 + RMagics.Rpull.__doc__,
586 RPULL_DOC = ' '*8 + RMagics.Rpull.__doc__,
577 RGET_DOC = ' '*8 + RMagics.Rget.__doc__
587 RGET_DOC = ' '*8 + RMagics.Rget.__doc__
578 )
588 )
579
589
580
590
581 _loaded = False
591 _loaded = False
582 def load_ipython_extension(ip):
592 def load_ipython_extension(ip):
583 """Load the extension in IPython."""
593 """Load the extension in IPython."""
584 global _loaded
594 global _loaded
585 if not _loaded:
595 if not _loaded:
586 ip.register_magics(RMagics)
596 ip.register_magics(RMagics)
587 _loaded = True
597 _loaded = True
@@ -1,64 +1,85 b''
1 """Tests for Octave magics extension."""
1 """Tests for Octave magics extension."""
2
2
3 import nose.tools as nt
3 import nose.tools as nt
4
4
5 try:
5 try:
6 import oct2py
6 import oct2py
7 import numpy as np
7 import numpy as np
8 import numpy.testing as npt
8 import numpy.testing as npt
9
9
10 from IPython.extensions import octavemagic
10 from IPython.extensions import octavemagic
11 except Exception as e:
11 except Exception as e:
12 __test__ = False
12 __test__ = False
13
13
14 global octave
14 global octave
15
15
16 def setup():
16 def setup():
17 ip = get_ipython()
17 ip = get_ipython()
18 global octave
18 global octave
19
19
20 octave = octavemagic.OctaveMagics(ip)
20 octave = octavemagic.OctaveMagics(ip)
21 ip.register_magics(octave)
21 ip.register_magics(octave)
22
22
23 ip.ex('import numpy as np')
23 ip.ex('import numpy as np')
24
24
25 def test_octave_inline():
25 def test_octave_inline():
26 ip = get_ipython()
26 ip = get_ipython()
27 result = ip.run_line_magic('octave', '[1, 2, 3] + 1;')
27 result = ip.run_line_magic('octave', '[1, 2, 3] + 1;')
28 npt.assert_array_equal(result, [[2, 3, 4]])
28 npt.assert_array_equal(result, [[2, 3, 4]])
29
29
30 def test_octave_roundtrip():
30 def test_octave_roundtrip():
31 ip = get_ipython()
31 ip = get_ipython()
32 ip.ex('x = np.arange(3); y = 4.5')
32 ip.ex('x = np.arange(3); y = 4.5')
33 ip.run_line_magic('octave_push', 'x y')
33 ip.run_line_magic('octave_push', 'x y')
34 ip.run_line_magic('octave', 'x = x + 1; y = y + 1;')
34 ip.run_line_magic('octave', 'x = x + 1; y = y + 1;')
35 ip.run_line_magic('octave_pull', 'x y')
35 ip.run_line_magic('octave_pull', 'x y')
36
36
37 npt.assert_array_equal(ip.user_ns['x'], [[1, 2, 3]])
37 npt.assert_array_equal(ip.user_ns['x'], [[1, 2, 3]])
38 nt.assert_equal(ip.user_ns['y'], 5.5)
38 nt.assert_equal(ip.user_ns['y'], 5.5)
39
39
40 def test_octave_cell_magic():
40 def test_octave_cell_magic():
41 ip = get_ipython()
41 ip = get_ipython()
42 ip.ex('x = 3; y = [1, 2]')
42 ip.ex('x = 3; y = [1, 2]')
43 ip.run_cell_magic('octave', '-f png -s 400,400 -i x,y -o z',
43 ip.run_cell_magic('octave', '-f png -s 400,400 -i x,y -o z',
44 'z = x + y;')
44 'z = x + y;')
45 npt.assert_array_equal(ip.user_ns['z'], [[4, 5]])
45 npt.assert_array_equal(ip.user_ns['z'], [[4, 5]])
46
46
47
47
48 def verify_publish_data(source, data):
48 def verify_publish_data(source, data):
49 if 'image/svg+xml' in data:
49 if 'image/svg+xml' in data:
50 svg = data['image/svg+xml']
50 svg = data['image/svg+xml']
51 assert 'height="500px"' in svg
51 assert 'height="500px"' in svg
52 assert 'width="400px"' in svg
52 assert 'width="400px"' in svg
53
53
54 test_octave_plot.svgs_generated += 1
54 test_octave_plot.svgs_generated += 1
55
55
56 def test_octave_plot():
56 def test_octave_plot():
57 octave._publish_display_data = verify_publish_data
57 octave._publish_display_data = verify_publish_data
58 test_octave_plot.svgs_generated = 0
58 test_octave_plot.svgs_generated = 0
59
59
60 ip = get_ipython()
60 ip = get_ipython()
61 ip.run_cell_magic('octave', '-f svg -s 400,500',
61 ip.run_cell_magic('octave', '-f svg -s 400,500',
62 'plot([1, 2, 3]); figure; plot([4, 5, 6]);')
62 'plot([1, 2, 3]); figure; plot([4, 5, 6]);')
63
63
64 nt.assert_equal(test_octave_plot.svgs_generated, 2)
64 nt.assert_equal(test_octave_plot.svgs_generated, 2)
65
66 def test_octavemagic_localscope():
67 ip = get_ipython()
68 ip.magic('load_ext octavemagic')
69 ip.push({'x':0})
70 ip.run_line_magic('octave', '-i x -o result result = x+1')
71 result = ip.user_ns['result']
72 nt.assert_equal(result, 1)
73
74 ip.run_cell('''def octavemagic_addone(u):
75 %octave -i u -o result result = u+1
76 return result''')
77 ip.run_cell('result = octavemagic_addone(1)')
78 result = ip.user_ns['result']
79 nt.assert_equal(result, 2)
80
81 nt.assert_raises(
82 KeyError,
83 ip.run_line_magic,
84 "octave",
85 "-i var_not_defined 1+1")
@@ -1,62 +1,82 b''
1 import numpy as np
1 import numpy as np
2 from IPython.core.interactiveshell import InteractiveShell
2 from IPython.core.interactiveshell import InteractiveShell
3 from IPython.extensions import rmagic
3 from IPython.extensions import rmagic
4 import nose.tools as nt
4 import nose.tools as nt
5
5
6 ip = get_ipython()
6 ip = get_ipython()
7 ip.magic('load_ext rmagic')
7 ip.magic('load_ext rmagic')
8
8
9
9
10 def test_push():
10 def test_push():
11 rm = rmagic.RMagics(ip)
11 rm = rmagic.RMagics(ip)
12 ip.push({'X':np.arange(5), 'Y':np.array([3,5,4,6,7])})
12 ip.push({'X':np.arange(5), 'Y':np.array([3,5,4,6,7])})
13 ip.run_line_magic('Rpush', 'X Y')
13 ip.run_line_magic('Rpush', 'X Y')
14 np.testing.assert_almost_equal(np.asarray(rm.r('X')), ip.user_ns['X'])
14 np.testing.assert_almost_equal(np.asarray(rm.r('X')), ip.user_ns['X'])
15 np.testing.assert_almost_equal(np.asarray(rm.r('Y')), ip.user_ns['Y'])
15 np.testing.assert_almost_equal(np.asarray(rm.r('Y')), ip.user_ns['Y'])
16
16
17 def test_pull():
17 def test_pull():
18 rm = rmagic.RMagics(ip)
18 rm = rmagic.RMagics(ip)
19 rm.r('Z=c(11:20)')
19 rm.r('Z=c(11:20)')
20 ip.run_line_magic('Rpull', 'Z')
20 ip.run_line_magic('Rpull', 'Z')
21 np.testing.assert_almost_equal(np.asarray(rm.r('Z')), ip.user_ns['Z'])
21 np.testing.assert_almost_equal(np.asarray(rm.r('Z')), ip.user_ns['Z'])
22 np.testing.assert_almost_equal(ip.user_ns['Z'], np.arange(11,21))
22 np.testing.assert_almost_equal(ip.user_ns['Z'], np.arange(11,21))
23
23
24 def test_Rconverter():
24 def test_Rconverter():
25 datapy= np.array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c')],
25 datapy= np.array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c')],
26 dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')])
26 dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')])
27 ip.user_ns['datapy'] = datapy
27 ip.user_ns['datapy'] = datapy
28 ip.run_line_magic('Rpush', 'datapy')
28 ip.run_line_magic('Rpush', 'datapy')
29
29
30 # test to see if a copy is being made
30 # test to see if a copy is being made
31 v = ip.run_line_magic('Rget', '-d datapy')
31 v = ip.run_line_magic('Rget', '-d datapy')
32 w = ip.run_line_magic('Rget', '-d datapy')
32 w = ip.run_line_magic('Rget', '-d datapy')
33 np.testing.assert_almost_equal(w['x'], v['x'])
33 np.testing.assert_almost_equal(w['x'], v['x'])
34 np.testing.assert_almost_equal(w['y'], v['y'])
34 np.testing.assert_almost_equal(w['y'], v['y'])
35 nt.assert_true(np.all(w['z'] == v['z']))
35 nt.assert_true(np.all(w['z'] == v['z']))
36 np.testing.assert_equal(id(w.data), id(v.data))
36 np.testing.assert_equal(id(w.data), id(v.data))
37 nt.assert_equal(w.dtype, v.dtype)
37 nt.assert_equal(w.dtype, v.dtype)
38
38
39 ip.run_cell_magic('R', ' -d datar datar=datapy', '')
39 ip.run_cell_magic('R', ' -d datar datar=datapy', '')
40
40
41 u = ip.run_line_magic('Rget', ' -d datar')
41 u = ip.run_line_magic('Rget', ' -d datar')
42 np.testing.assert_almost_equal(u['x'], v['x'])
42 np.testing.assert_almost_equal(u['x'], v['x'])
43 np.testing.assert_almost_equal(u['y'], v['y'])
43 np.testing.assert_almost_equal(u['y'], v['y'])
44 nt.assert_true(np.all(u['z'] == v['z']))
44 nt.assert_true(np.all(u['z'] == v['z']))
45 np.testing.assert_equal(id(u.data), id(v.data))
45 np.testing.assert_equal(id(u.data), id(v.data))
46 nt.assert_equal(u.dtype, v.dtype)
46 nt.assert_equal(u.dtype, v.dtype)
47
47
48
48
49 def test_cell_magic():
49 def test_cell_magic():
50
50
51 ip.push({'x':np.arange(5), 'y':np.array([3,5,4,6,7])})
51 ip.push({'x':np.arange(5), 'y':np.array([3,5,4,6,7])})
52 snippet = '''
52 snippet = '''
53 print(summary(a))
53 print(summary(a))
54 plot(x, y, pch=23, bg='orange', cex=2)
54 plot(x, y, pch=23, bg='orange', cex=2)
55 plot(x, x)
55 plot(x, x)
56 print(summary(x))
56 print(summary(x))
57 r = resid(a)
57 r = resid(a)
58 xc = coef(a)
58 xc = coef(a)
59 '''
59 '''
60 ip.run_cell_magic('R', '-i x,y -o r,xc a=lm(y~x)', snippet)
60 ip.run_cell_magic('R', '-i x,y -o r,xc a=lm(y~x)', snippet)
61 np.testing.assert_almost_equal(ip.user_ns['xc'], [3.2, 0.9])
61 np.testing.assert_almost_equal(ip.user_ns['xc'], [3.2, 0.9])
62 np.testing.assert_almost_equal(ip.user_ns['r'], np.array([-0.2, 0.9, -1. , 0.1, 0.2]))
62 np.testing.assert_almost_equal(ip.user_ns['r'], np.array([-0.2, 0.9, -1. , 0.1, 0.2]))
63
64
65 def test_rmagic_localscope():
66 ip.push({'x':0})
67 ip.run_line_magic('R', '-i x -o result result <-x+1')
68 result = ip.user_ns['result']
69 nt.assert_equal(result[0], 1)
70
71 ip.run_cell('''def rmagic_addone(u):
72 %R -i u -o result result <- u+1
73 return result[0]''')
74 ip.run_cell('result = rmagic_addone(1)')
75 result = ip.user_ns['result']
76 nt.assert_equal(result, 2)
77
78 nt.assert_raises(
79 KeyError,
80 ip.run_line_magic,
81 "R",
82 "-i var_not_defined 1+1")
General Comments 0
You need to be logged in to leave comments. Login now