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