##// END OF EJS Templates
Paging using payloads now works.
Brian Granger -
Show More
@@ -0,0 +1,50
1 #!/usr/bin/env python
2 # encoding: utf-8
3 """
4 A payload based version of page.
5
6 Authors:
7
8 * Brian Granger
9 * Fernando Perez
10 """
11
12 #-----------------------------------------------------------------------------
13 # Copyright (C) 2008-2010 The IPython Development Team
14 #
15 # Distributed under the terms of the BSD License. The full license is in
16 # the file COPYING, distributed as part of this software.
17 #-----------------------------------------------------------------------------
18
19 #-----------------------------------------------------------------------------
20 # Imports
21 #-----------------------------------------------------------------------------
22
23 from IPython.core.interactiveshell import InteractiveShell
24
25 #-----------------------------------------------------------------------------
26 # Classes and functions
27 #-----------------------------------------------------------------------------
28
29 def page(strng, start=0, screen_lines=0, pager_cmd=None):
30 """Print a string, piping through a pager.
31
32 This version ignores the screen_lines and pager_cmd arguments and uses
33 IPython's payload system instead.
34 """
35
36 # Some routines may auto-compute start offsets incorrectly and pass a
37 # negative value. Offset to 0 for robustness.
38 start = max(0, start)
39 shell = InteractiveShell.instance()
40 payload = dict(
41 source='IPython.zmq.page.page',
42 data=strng,
43 start_line_number=start
44 )
45 shell.payload_manager.write_payload(payload)
46
47 def install_payload_page():
48 """Install this version of page as IPython.core.page.page."""
49 from IPython.core import page as corepage
50 corepage.page = page
@@ -1,2130 +1,2127
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Main IPython class."""
2 """Main IPython class."""
3
3
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 # Copyright (C) 2008-2010 The IPython Development Team
7 # Copyright (C) 2008-2010 The IPython Development Team
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import with_statement
17 from __future__ import with_statement
18 from __future__ import absolute_import
18 from __future__ import absolute_import
19
19
20 import __builtin__
20 import __builtin__
21 import abc
21 import abc
22 import codeop
22 import codeop
23 import exceptions
23 import exceptions
24 import new
24 import new
25 import os
25 import os
26 import re
26 import re
27 import string
27 import string
28 import sys
28 import sys
29 import tempfile
29 import tempfile
30 from contextlib import nested
30 from contextlib import nested
31
31
32 from IPython.core import debugger, oinspect
32 from IPython.core import debugger, oinspect
33 from IPython.core import history as ipcorehist
33 from IPython.core import history as ipcorehist
34 from IPython.core import prefilter
34 from IPython.core import prefilter
35 from IPython.core import shadowns
35 from IPython.core import shadowns
36 from IPython.core import ultratb
36 from IPython.core import ultratb
37 from IPython.core.alias import AliasManager
37 from IPython.core.alias import AliasManager
38 from IPython.core.builtin_trap import BuiltinTrap
38 from IPython.core.builtin_trap import BuiltinTrap
39 from IPython.config.configurable import Configurable
39 from IPython.config.configurable import Configurable
40 from IPython.core.display_trap import DisplayTrap
40 from IPython.core.display_trap import DisplayTrap
41 from IPython.core.error import UsageError
41 from IPython.core.error import UsageError
42 from IPython.core.extensions import ExtensionManager
42 from IPython.core.extensions import ExtensionManager
43 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
43 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
44 from IPython.core.inputlist import InputList
44 from IPython.core.inputlist import InputList
45 from IPython.core.logger import Logger
45 from IPython.core.logger import Logger
46 from IPython.core.magic import Magic
46 from IPython.core.magic import Magic
47 from IPython.core.payload import PayloadManager
47 from IPython.core.payload import PayloadManager
48 from IPython.core.plugin import PluginManager
48 from IPython.core.plugin import PluginManager
49 from IPython.core.prefilter import PrefilterManager
49 from IPython.core.prefilter import PrefilterManager
50 from IPython.core.displayhook import DisplayHook
50 from IPython.core.displayhook import DisplayHook
51 import IPython.core.hooks
51 import IPython.core.hooks
52 from IPython.external.Itpl import ItplNS
52 from IPython.external.Itpl import ItplNS
53 from IPython.utils import PyColorize
53 from IPython.utils import PyColorize
54 from IPython.utils import pickleshare
54 from IPython.utils import pickleshare
55 from IPython.utils.doctestreload import doctest_reload
55 from IPython.utils.doctestreload import doctest_reload
56 from IPython.utils.ipstruct import Struct
56 from IPython.utils.ipstruct import Struct
57 import IPython.utils.io
57 import IPython.utils.io
58 from IPython.utils.io import ask_yes_no
58 from IPython.utils.io import ask_yes_no
59 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
59 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
60 from IPython.utils.process import getoutput, getoutputerror
60 from IPython.utils.process import getoutput, getoutputerror
61 from IPython.utils.strdispatch import StrDispatch
61 from IPython.utils.strdispatch import StrDispatch
62 from IPython.utils.syspathcontext import prepended_to_syspath
62 from IPython.utils.syspathcontext import prepended_to_syspath
63 from IPython.utils.text import num_ini_spaces
63 from IPython.utils.text import num_ini_spaces
64 from IPython.utils.warn import warn, error, fatal
64 from IPython.utils.warn import warn, error, fatal
65 from IPython.utils.traitlets import (
65 from IPython.utils.traitlets import (
66 Int, Str, CBool, CaselessStrEnum, Enum, List, Unicode, Instance, Type
66 Int, Str, CBool, CaselessStrEnum, Enum, List, Unicode, Instance, Type
67 )
67 )
68
68
69 # from IPython.utils import growl
69 # from IPython.utils import growl
70 # growl.start("IPython")
70 # growl.start("IPython")
71
71
72 #-----------------------------------------------------------------------------
72 #-----------------------------------------------------------------------------
73 # Globals
73 # Globals
74 #-----------------------------------------------------------------------------
74 #-----------------------------------------------------------------------------
75
75
76 # compiled regexps for autoindent management
76 # compiled regexps for autoindent management
77 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
77 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
78
78
79 #-----------------------------------------------------------------------------
79 #-----------------------------------------------------------------------------
80 # Utilities
80 # Utilities
81 #-----------------------------------------------------------------------------
81 #-----------------------------------------------------------------------------
82
82
83 # store the builtin raw_input globally, and use this always, in case user code
83 # store the builtin raw_input globally, and use this always, in case user code
84 # overwrites it (like wx.py.PyShell does)
84 # overwrites it (like wx.py.PyShell does)
85 raw_input_original = raw_input
85 raw_input_original = raw_input
86
86
87 def softspace(file, newvalue):
87 def softspace(file, newvalue):
88 """Copied from code.py, to remove the dependency"""
88 """Copied from code.py, to remove the dependency"""
89
89
90 oldvalue = 0
90 oldvalue = 0
91 try:
91 try:
92 oldvalue = file.softspace
92 oldvalue = file.softspace
93 except AttributeError:
93 except AttributeError:
94 pass
94 pass
95 try:
95 try:
96 file.softspace = newvalue
96 file.softspace = newvalue
97 except (AttributeError, TypeError):
97 except (AttributeError, TypeError):
98 # "attribute-less object" or "read-only attributes"
98 # "attribute-less object" or "read-only attributes"
99 pass
99 pass
100 return oldvalue
100 return oldvalue
101
101
102
102
103 def no_op(*a, **kw): pass
103 def no_op(*a, **kw): pass
104
104
105 class SpaceInInput(exceptions.Exception): pass
105 class SpaceInInput(exceptions.Exception): pass
106
106
107 class Bunch: pass
107 class Bunch: pass
108
108
109
109
110 def get_default_colors():
110 def get_default_colors():
111 if sys.platform=='darwin':
111 if sys.platform=='darwin':
112 return "LightBG"
112 return "LightBG"
113 elif os.name=='nt':
113 elif os.name=='nt':
114 return 'Linux'
114 return 'Linux'
115 else:
115 else:
116 return 'Linux'
116 return 'Linux'
117
117
118
118
119 class SeparateStr(Str):
119 class SeparateStr(Str):
120 """A Str subclass to validate separate_in, separate_out, etc.
120 """A Str subclass to validate separate_in, separate_out, etc.
121
121
122 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
122 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
123 """
123 """
124
124
125 def validate(self, obj, value):
125 def validate(self, obj, value):
126 if value == '0': value = ''
126 if value == '0': value = ''
127 value = value.replace('\\n','\n')
127 value = value.replace('\\n','\n')
128 return super(SeparateStr, self).validate(obj, value)
128 return super(SeparateStr, self).validate(obj, value)
129
129
130 class MultipleInstanceError(Exception):
130 class MultipleInstanceError(Exception):
131 pass
131 pass
132
132
133
133
134 #-----------------------------------------------------------------------------
134 #-----------------------------------------------------------------------------
135 # Main IPython class
135 # Main IPython class
136 #-----------------------------------------------------------------------------
136 #-----------------------------------------------------------------------------
137
137
138
138
139 class InteractiveShell(Configurable, Magic):
139 class InteractiveShell(Configurable, Magic):
140 """An enhanced, interactive shell for Python."""
140 """An enhanced, interactive shell for Python."""
141
141
142 _instance = None
142 _instance = None
143 autocall = Enum((0,1,2), default_value=1, config=True)
143 autocall = Enum((0,1,2), default_value=1, config=True)
144 # TODO: remove all autoindent logic and put into frontends.
144 # TODO: remove all autoindent logic and put into frontends.
145 # We can't do this yet because even runlines uses the autoindent.
145 # We can't do this yet because even runlines uses the autoindent.
146 autoindent = CBool(True, config=True)
146 autoindent = CBool(True, config=True)
147 automagic = CBool(True, config=True)
147 automagic = CBool(True, config=True)
148 cache_size = Int(1000, config=True)
148 cache_size = Int(1000, config=True)
149 color_info = CBool(True, config=True)
149 color_info = CBool(True, config=True)
150 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
150 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
151 default_value=get_default_colors(), config=True)
151 default_value=get_default_colors(), config=True)
152 debug = CBool(False, config=True)
152 debug = CBool(False, config=True)
153 deep_reload = CBool(False, config=True)
153 deep_reload = CBool(False, config=True)
154 displayhook_class = Type(DisplayHook)
154 displayhook_class = Type(DisplayHook)
155 filename = Str("<ipython console>")
155 filename = Str("<ipython console>")
156 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
156 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
157 logstart = CBool(False, config=True)
157 logstart = CBool(False, config=True)
158 logfile = Str('', config=True)
158 logfile = Str('', config=True)
159 logappend = Str('', config=True)
159 logappend = Str('', config=True)
160 object_info_string_level = Enum((0,1,2), default_value=0,
160 object_info_string_level = Enum((0,1,2), default_value=0,
161 config=True)
161 config=True)
162 pdb = CBool(False, config=True)
162 pdb = CBool(False, config=True)
163 pprint = CBool(True, config=True)
163 pprint = CBool(True, config=True)
164 profile = Str('', config=True)
164 profile = Str('', config=True)
165 prompt_in1 = Str('In [\\#]: ', config=True)
165 prompt_in1 = Str('In [\\#]: ', config=True)
166 prompt_in2 = Str(' .\\D.: ', config=True)
166 prompt_in2 = Str(' .\\D.: ', config=True)
167 prompt_out = Str('Out[\\#]: ', config=True)
167 prompt_out = Str('Out[\\#]: ', config=True)
168 prompts_pad_left = CBool(True, config=True)
168 prompts_pad_left = CBool(True, config=True)
169 quiet = CBool(False, config=True)
169 quiet = CBool(False, config=True)
170
170
171 # The readline stuff will eventually be moved to the terminal subclass
171 # The readline stuff will eventually be moved to the terminal subclass
172 # but for now, we can't do that as readline is welded in everywhere.
172 # but for now, we can't do that as readline is welded in everywhere.
173 readline_use = CBool(True, config=True)
173 readline_use = CBool(True, config=True)
174 readline_merge_completions = CBool(True, config=True)
174 readline_merge_completions = CBool(True, config=True)
175 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
175 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
176 readline_remove_delims = Str('-/~', config=True)
176 readline_remove_delims = Str('-/~', config=True)
177 readline_parse_and_bind = List([
177 readline_parse_and_bind = List([
178 'tab: complete',
178 'tab: complete',
179 '"\C-l": clear-screen',
179 '"\C-l": clear-screen',
180 'set show-all-if-ambiguous on',
180 'set show-all-if-ambiguous on',
181 '"\C-o": tab-insert',
181 '"\C-o": tab-insert',
182 '"\M-i": " "',
182 '"\M-i": " "',
183 '"\M-o": "\d\d\d\d"',
183 '"\M-o": "\d\d\d\d"',
184 '"\M-I": "\d\d\d\d"',
184 '"\M-I": "\d\d\d\d"',
185 '"\C-r": reverse-search-history',
185 '"\C-r": reverse-search-history',
186 '"\C-s": forward-search-history',
186 '"\C-s": forward-search-history',
187 '"\C-p": history-search-backward',
187 '"\C-p": history-search-backward',
188 '"\C-n": history-search-forward',
188 '"\C-n": history-search-forward',
189 '"\e[A": history-search-backward',
189 '"\e[A": history-search-backward',
190 '"\e[B": history-search-forward',
190 '"\e[B": history-search-forward',
191 '"\C-k": kill-line',
191 '"\C-k": kill-line',
192 '"\C-u": unix-line-discard',
192 '"\C-u": unix-line-discard',
193 ], allow_none=False, config=True)
193 ], allow_none=False, config=True)
194
194
195 # TODO: this part of prompt management should be moved to the frontends.
195 # TODO: this part of prompt management should be moved to the frontends.
196 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
196 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
197 separate_in = SeparateStr('\n', config=True)
197 separate_in = SeparateStr('\n', config=True)
198 separate_out = SeparateStr('\n', config=True)
198 separate_out = SeparateStr('\n', config=True)
199 separate_out2 = SeparateStr('\n', config=True)
199 separate_out2 = SeparateStr('\n', config=True)
200 system_header = Str('IPython system call: ', config=True)
200 system_header = Str('IPython system call: ', config=True)
201 system_verbose = CBool(False, config=True)
201 system_verbose = CBool(False, config=True)
202 wildcards_case_sensitive = CBool(True, config=True)
202 wildcards_case_sensitive = CBool(True, config=True)
203 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
203 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
204 default_value='Context', config=True)
204 default_value='Context', config=True)
205
205
206 # Subcomponents of InteractiveShell
206 # Subcomponents of InteractiveShell
207 alias_manager = Instance('IPython.core.alias.AliasManager')
207 alias_manager = Instance('IPython.core.alias.AliasManager')
208 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
208 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
209 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
209 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
210 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
210 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
211 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
211 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
212 plugin_manager = Instance('IPython.core.plugin.PluginManager')
212 plugin_manager = Instance('IPython.core.plugin.PluginManager')
213 payload_manager = Instance('IPython.core.payload.PayloadManager')
213 payload_manager = Instance('IPython.core.payload.PayloadManager')
214
214
215 def __init__(self, config=None, ipython_dir=None,
215 def __init__(self, config=None, ipython_dir=None,
216 user_ns=None, user_global_ns=None,
216 user_ns=None, user_global_ns=None,
217 custom_exceptions=((),None)):
217 custom_exceptions=((),None)):
218
218
219 # This is where traits with a config_key argument are updated
219 # This is where traits with a config_key argument are updated
220 # from the values on config.
220 # from the values on config.
221 super(InteractiveShell, self).__init__(config=config)
221 super(InteractiveShell, self).__init__(config=config)
222
222
223 # These are relatively independent and stateless
223 # These are relatively independent and stateless
224 self.init_ipython_dir(ipython_dir)
224 self.init_ipython_dir(ipython_dir)
225 self.init_instance_attrs()
225 self.init_instance_attrs()
226
226
227 # Create namespaces (user_ns, user_global_ns, etc.)
227 # Create namespaces (user_ns, user_global_ns, etc.)
228 self.init_create_namespaces(user_ns, user_global_ns)
228 self.init_create_namespaces(user_ns, user_global_ns)
229 # This has to be done after init_create_namespaces because it uses
229 # This has to be done after init_create_namespaces because it uses
230 # something in self.user_ns, but before init_sys_modules, which
230 # something in self.user_ns, but before init_sys_modules, which
231 # is the first thing to modify sys.
231 # is the first thing to modify sys.
232 # TODO: When we override sys.stdout and sys.stderr before this class
232 # TODO: When we override sys.stdout and sys.stderr before this class
233 # is created, we are saving the overridden ones here. Not sure if this
233 # is created, we are saving the overridden ones here. Not sure if this
234 # is what we want to do.
234 # is what we want to do.
235 self.save_sys_module_state()
235 self.save_sys_module_state()
236 self.init_sys_modules()
236 self.init_sys_modules()
237
237
238 self.init_history()
238 self.init_history()
239 self.init_encoding()
239 self.init_encoding()
240 self.init_prefilter()
240 self.init_prefilter()
241
241
242 Magic.__init__(self, self)
242 Magic.__init__(self, self)
243
243
244 self.init_syntax_highlighting()
244 self.init_syntax_highlighting()
245 self.init_hooks()
245 self.init_hooks()
246 self.init_pushd_popd_magic()
246 self.init_pushd_popd_magic()
247 # self.init_traceback_handlers use to be here, but we moved it below
247 # self.init_traceback_handlers use to be here, but we moved it below
248 # because it and init_io have to come after init_readline.
248 # because it and init_io have to come after init_readline.
249 self.init_user_ns()
249 self.init_user_ns()
250 self.init_logger()
250 self.init_logger()
251 self.init_alias()
251 self.init_alias()
252 self.init_builtins()
252 self.init_builtins()
253
253
254 # pre_config_initialization
254 # pre_config_initialization
255 self.init_shadow_hist()
255 self.init_shadow_hist()
256
256
257 # The next section should contain averything that was in ipmaker.
257 # The next section should contain averything that was in ipmaker.
258 self.init_logstart()
258 self.init_logstart()
259
259
260 # The following was in post_config_initialization
260 # The following was in post_config_initialization
261 self.init_inspector()
261 self.init_inspector()
262 # init_readline() must come before init_io(), because init_io uses
262 # init_readline() must come before init_io(), because init_io uses
263 # readline related things.
263 # readline related things.
264 self.init_readline()
264 self.init_readline()
265 # TODO: init_io() needs to happen before init_traceback handlers
265 # TODO: init_io() needs to happen before init_traceback handlers
266 # because the traceback handlers hardcode the stdout/stderr streams.
266 # because the traceback handlers hardcode the stdout/stderr streams.
267 # This logic in in debugger.Pdb and should eventually be changed.
267 # This logic in in debugger.Pdb and should eventually be changed.
268 self.init_io()
268 self.init_io()
269 self.init_traceback_handlers(custom_exceptions)
269 self.init_traceback_handlers(custom_exceptions)
270 self.init_prompts()
270 self.init_prompts()
271 self.init_displayhook()
271 self.init_displayhook()
272 self.init_reload_doctest()
272 self.init_reload_doctest()
273 self.init_magics()
273 self.init_magics()
274 self.init_pdb()
274 self.init_pdb()
275 self.init_extension_manager()
275 self.init_extension_manager()
276 self.init_plugin_manager()
276 self.init_plugin_manager()
277 self.init_payload()
277 self.init_payload()
278 self.hooks.late_startup_hook()
278 self.hooks.late_startup_hook()
279
279
280 @classmethod
280 @classmethod
281 def instance(cls, *args, **kwargs):
281 def instance(cls, *args, **kwargs):
282 """Returns a global InteractiveShell instance."""
282 """Returns a global InteractiveShell instance."""
283 if cls._instance is None:
283 if cls._instance is None:
284 inst = cls(*args, **kwargs)
284 inst = cls(*args, **kwargs)
285 # Now make sure that the instance will also be returned by
285 # Now make sure that the instance will also be returned by
286 # the subclasses instance attribute.
286 # the subclasses instance attribute.
287 for subclass in cls.mro():
287 for subclass in cls.mro():
288 if issubclass(cls, subclass) and issubclass(subclass, InteractiveShell):
288 if issubclass(cls, subclass) and issubclass(subclass, InteractiveShell):
289 subclass._instance = inst
289 subclass._instance = inst
290 else:
290 else:
291 break
291 break
292 if isinstance(cls._instance, cls):
292 if isinstance(cls._instance, cls):
293 return cls._instance
293 return cls._instance
294 else:
294 else:
295 raise MultipleInstanceError(
295 raise MultipleInstanceError(
296 'Multiple incompatible subclass instances of '
296 'Multiple incompatible subclass instances of '
297 'InteractiveShell are being created.'
297 'InteractiveShell are being created.'
298 )
298 )
299
299
300 @classmethod
300 @classmethod
301 def initialized(cls):
301 def initialized(cls):
302 return hasattr(cls, "_instance")
302 return hasattr(cls, "_instance")
303
303
304 def get_ipython(self):
304 def get_ipython(self):
305 """Return the currently running IPython instance."""
305 """Return the currently running IPython instance."""
306 return self
306 return self
307
307
308 #-------------------------------------------------------------------------
308 #-------------------------------------------------------------------------
309 # Trait changed handlers
309 # Trait changed handlers
310 #-------------------------------------------------------------------------
310 #-------------------------------------------------------------------------
311
311
312 def _ipython_dir_changed(self, name, new):
312 def _ipython_dir_changed(self, name, new):
313 if not os.path.isdir(new):
313 if not os.path.isdir(new):
314 os.makedirs(new, mode = 0777)
314 os.makedirs(new, mode = 0777)
315
315
316 def set_autoindent(self,value=None):
316 def set_autoindent(self,value=None):
317 """Set the autoindent flag, checking for readline support.
317 """Set the autoindent flag, checking for readline support.
318
318
319 If called with no arguments, it acts as a toggle."""
319 If called with no arguments, it acts as a toggle."""
320
320
321 if not self.has_readline:
321 if not self.has_readline:
322 if os.name == 'posix':
322 if os.name == 'posix':
323 warn("The auto-indent feature requires the readline library")
323 warn("The auto-indent feature requires the readline library")
324 self.autoindent = 0
324 self.autoindent = 0
325 return
325 return
326 if value is None:
326 if value is None:
327 self.autoindent = not self.autoindent
327 self.autoindent = not self.autoindent
328 else:
328 else:
329 self.autoindent = value
329 self.autoindent = value
330
330
331 #-------------------------------------------------------------------------
331 #-------------------------------------------------------------------------
332 # init_* methods called by __init__
332 # init_* methods called by __init__
333 #-------------------------------------------------------------------------
333 #-------------------------------------------------------------------------
334
334
335 def init_ipython_dir(self, ipython_dir):
335 def init_ipython_dir(self, ipython_dir):
336 if ipython_dir is not None:
336 if ipython_dir is not None:
337 self.ipython_dir = ipython_dir
337 self.ipython_dir = ipython_dir
338 self.config.Global.ipython_dir = self.ipython_dir
338 self.config.Global.ipython_dir = self.ipython_dir
339 return
339 return
340
340
341 if hasattr(self.config.Global, 'ipython_dir'):
341 if hasattr(self.config.Global, 'ipython_dir'):
342 self.ipython_dir = self.config.Global.ipython_dir
342 self.ipython_dir = self.config.Global.ipython_dir
343 else:
343 else:
344 self.ipython_dir = get_ipython_dir()
344 self.ipython_dir = get_ipython_dir()
345
345
346 # All children can just read this
346 # All children can just read this
347 self.config.Global.ipython_dir = self.ipython_dir
347 self.config.Global.ipython_dir = self.ipython_dir
348
348
349 def init_instance_attrs(self):
349 def init_instance_attrs(self):
350 self.more = False
350 self.more = False
351
351
352 # command compiler
352 # command compiler
353 self.compile = codeop.CommandCompiler()
353 self.compile = codeop.CommandCompiler()
354
354
355 # User input buffer
355 # User input buffer
356 self.buffer = []
356 self.buffer = []
357
357
358 # Make an empty namespace, which extension writers can rely on both
358 # Make an empty namespace, which extension writers can rely on both
359 # existing and NEVER being used by ipython itself. This gives them a
359 # existing and NEVER being used by ipython itself. This gives them a
360 # convenient location for storing additional information and state
360 # convenient location for storing additional information and state
361 # their extensions may require, without fear of collisions with other
361 # their extensions may require, without fear of collisions with other
362 # ipython names that may develop later.
362 # ipython names that may develop later.
363 self.meta = Struct()
363 self.meta = Struct()
364
364
365 # Object variable to store code object waiting execution. This is
365 # Object variable to store code object waiting execution. This is
366 # used mainly by the multithreaded shells, but it can come in handy in
366 # used mainly by the multithreaded shells, but it can come in handy in
367 # other situations. No need to use a Queue here, since it's a single
367 # other situations. No need to use a Queue here, since it's a single
368 # item which gets cleared once run.
368 # item which gets cleared once run.
369 self.code_to_run = None
369 self.code_to_run = None
370
370
371 # Temporary files used for various purposes. Deleted at exit.
371 # Temporary files used for various purposes. Deleted at exit.
372 self.tempfiles = []
372 self.tempfiles = []
373
373
374 # Keep track of readline usage (later set by init_readline)
374 # Keep track of readline usage (later set by init_readline)
375 self.has_readline = False
375 self.has_readline = False
376
376
377 # keep track of where we started running (mainly for crash post-mortem)
377 # keep track of where we started running (mainly for crash post-mortem)
378 # This is not being used anywhere currently.
378 # This is not being used anywhere currently.
379 self.starting_dir = os.getcwd()
379 self.starting_dir = os.getcwd()
380
380
381 # Indentation management
381 # Indentation management
382 self.indent_current_nsp = 0
382 self.indent_current_nsp = 0
383
383
384 def init_encoding(self):
384 def init_encoding(self):
385 # Get system encoding at startup time. Certain terminals (like Emacs
385 # Get system encoding at startup time. Certain terminals (like Emacs
386 # under Win32 have it set to None, and we need to have a known valid
386 # under Win32 have it set to None, and we need to have a known valid
387 # encoding to use in the raw_input() method
387 # encoding to use in the raw_input() method
388 try:
388 try:
389 self.stdin_encoding = sys.stdin.encoding or 'ascii'
389 self.stdin_encoding = sys.stdin.encoding or 'ascii'
390 except AttributeError:
390 except AttributeError:
391 self.stdin_encoding = 'ascii'
391 self.stdin_encoding = 'ascii'
392
392
393 def init_syntax_highlighting(self):
393 def init_syntax_highlighting(self):
394 # Python source parser/formatter for syntax highlighting
394 # Python source parser/formatter for syntax highlighting
395 pyformat = PyColorize.Parser().format
395 pyformat = PyColorize.Parser().format
396 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
396 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
397
397
398 def init_pushd_popd_magic(self):
398 def init_pushd_popd_magic(self):
399 # for pushd/popd management
399 # for pushd/popd management
400 try:
400 try:
401 self.home_dir = get_home_dir()
401 self.home_dir = get_home_dir()
402 except HomeDirError, msg:
402 except HomeDirError, msg:
403 fatal(msg)
403 fatal(msg)
404
404
405 self.dir_stack = []
405 self.dir_stack = []
406
406
407 def init_logger(self):
407 def init_logger(self):
408 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
408 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
409 # local shortcut, this is used a LOT
409 # local shortcut, this is used a LOT
410 self.log = self.logger.log
410 self.log = self.logger.log
411
411
412 def init_logstart(self):
412 def init_logstart(self):
413 if self.logappend:
413 if self.logappend:
414 self.magic_logstart(self.logappend + ' append')
414 self.magic_logstart(self.logappend + ' append')
415 elif self.logfile:
415 elif self.logfile:
416 self.magic_logstart(self.logfile)
416 self.magic_logstart(self.logfile)
417 elif self.logstart:
417 elif self.logstart:
418 self.magic_logstart()
418 self.magic_logstart()
419
419
420 def init_builtins(self):
420 def init_builtins(self):
421 self.builtin_trap = BuiltinTrap(shell=self)
421 self.builtin_trap = BuiltinTrap(shell=self)
422
422
423 def init_inspector(self):
423 def init_inspector(self):
424 # Object inspector
424 # Object inspector
425 self.inspector = oinspect.Inspector(oinspect.InspectColors,
425 self.inspector = oinspect.Inspector(oinspect.InspectColors,
426 PyColorize.ANSICodeColors,
426 PyColorize.ANSICodeColors,
427 'NoColor',
427 'NoColor',
428 self.object_info_string_level)
428 self.object_info_string_level)
429
429
430 def init_io(self):
430 def init_io(self):
431 import IPython.utils.io
431 import IPython.utils.io
432 if sys.platform == 'win32' and self.has_readline:
432 if sys.platform == 'win32' and self.has_readline:
433 Term = IPython.utils.io.IOTerm(
433 Term = IPython.utils.io.IOTerm(
434 cout=self.readline._outputfile,cerr=self.readline._outputfile
434 cout=self.readline._outputfile,cerr=self.readline._outputfile
435 )
435 )
436 else:
436 else:
437 Term = IPython.utils.io.IOTerm()
437 Term = IPython.utils.io.IOTerm()
438 IPython.utils.io.Term = Term
438 IPython.utils.io.Term = Term
439
439
440 def init_prompts(self):
440 def init_prompts(self):
441 # TODO: This is a pass for now because the prompts are managed inside
441 # TODO: This is a pass for now because the prompts are managed inside
442 # the DisplayHook. Once there is a separate prompt manager, this
442 # the DisplayHook. Once there is a separate prompt manager, this
443 # will initialize that object and all prompt related information.
443 # will initialize that object and all prompt related information.
444 pass
444 pass
445
445
446 def init_displayhook(self):
446 def init_displayhook(self):
447 # Initialize displayhook, set in/out prompts and printing system
447 # Initialize displayhook, set in/out prompts and printing system
448 self.displayhook = self.displayhook_class(
448 self.displayhook = self.displayhook_class(
449 shell=self,
449 shell=self,
450 cache_size=self.cache_size,
450 cache_size=self.cache_size,
451 input_sep = self.separate_in,
451 input_sep = self.separate_in,
452 output_sep = self.separate_out,
452 output_sep = self.separate_out,
453 output_sep2 = self.separate_out2,
453 output_sep2 = self.separate_out2,
454 ps1 = self.prompt_in1,
454 ps1 = self.prompt_in1,
455 ps2 = self.prompt_in2,
455 ps2 = self.prompt_in2,
456 ps_out = self.prompt_out,
456 ps_out = self.prompt_out,
457 pad_left = self.prompts_pad_left
457 pad_left = self.prompts_pad_left
458 )
458 )
459 # This is a context manager that installs/revmoes the displayhook at
459 # This is a context manager that installs/revmoes the displayhook at
460 # the appropriate time.
460 # the appropriate time.
461 self.display_trap = DisplayTrap(hook=self.displayhook)
461 self.display_trap = DisplayTrap(hook=self.displayhook)
462
462
463 def init_reload_doctest(self):
463 def init_reload_doctest(self):
464 # Do a proper resetting of doctest, including the necessary displayhook
464 # Do a proper resetting of doctest, including the necessary displayhook
465 # monkeypatching
465 # monkeypatching
466 try:
466 try:
467 doctest_reload()
467 doctest_reload()
468 except ImportError:
468 except ImportError:
469 warn("doctest module does not exist.")
469 warn("doctest module does not exist.")
470
470
471 #-------------------------------------------------------------------------
471 #-------------------------------------------------------------------------
472 # Things related to injections into the sys module
472 # Things related to injections into the sys module
473 #-------------------------------------------------------------------------
473 #-------------------------------------------------------------------------
474
474
475 def save_sys_module_state(self):
475 def save_sys_module_state(self):
476 """Save the state of hooks in the sys module.
476 """Save the state of hooks in the sys module.
477
477
478 This has to be called after self.user_ns is created.
478 This has to be called after self.user_ns is created.
479 """
479 """
480 self._orig_sys_module_state = {}
480 self._orig_sys_module_state = {}
481 self._orig_sys_module_state['stdin'] = sys.stdin
481 self._orig_sys_module_state['stdin'] = sys.stdin
482 self._orig_sys_module_state['stdout'] = sys.stdout
482 self._orig_sys_module_state['stdout'] = sys.stdout
483 self._orig_sys_module_state['stderr'] = sys.stderr
483 self._orig_sys_module_state['stderr'] = sys.stderr
484 self._orig_sys_module_state['excepthook'] = sys.excepthook
484 self._orig_sys_module_state['excepthook'] = sys.excepthook
485 try:
485 try:
486 self._orig_sys_modules_main_name = self.user_ns['__name__']
486 self._orig_sys_modules_main_name = self.user_ns['__name__']
487 except KeyError:
487 except KeyError:
488 pass
488 pass
489
489
490 def restore_sys_module_state(self):
490 def restore_sys_module_state(self):
491 """Restore the state of the sys module."""
491 """Restore the state of the sys module."""
492 try:
492 try:
493 for k, v in self._orig_sys_module_state.items():
493 for k, v in self._orig_sys_module_state.items():
494 setattr(sys, k, v)
494 setattr(sys, k, v)
495 except AttributeError:
495 except AttributeError:
496 pass
496 pass
497 try:
497 try:
498 delattr(sys, 'ipcompleter')
498 delattr(sys, 'ipcompleter')
499 except AttributeError:
499 except AttributeError:
500 pass
500 pass
501 # Reset what what done in self.init_sys_modules
501 # Reset what what done in self.init_sys_modules
502 try:
502 try:
503 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
503 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
504 except (AttributeError, KeyError):
504 except (AttributeError, KeyError):
505 pass
505 pass
506
506
507 #-------------------------------------------------------------------------
507 #-------------------------------------------------------------------------
508 # Things related to hooks
508 # Things related to hooks
509 #-------------------------------------------------------------------------
509 #-------------------------------------------------------------------------
510
510
511 def init_hooks(self):
511 def init_hooks(self):
512 # hooks holds pointers used for user-side customizations
512 # hooks holds pointers used for user-side customizations
513 self.hooks = Struct()
513 self.hooks = Struct()
514
514
515 self.strdispatchers = {}
515 self.strdispatchers = {}
516
516
517 # Set all default hooks, defined in the IPython.hooks module.
517 # Set all default hooks, defined in the IPython.hooks module.
518 hooks = IPython.core.hooks
518 hooks = IPython.core.hooks
519 for hook_name in hooks.__all__:
519 for hook_name in hooks.__all__:
520 # default hooks have priority 100, i.e. low; user hooks should have
520 # default hooks have priority 100, i.e. low; user hooks should have
521 # 0-100 priority
521 # 0-100 priority
522 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
522 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
523
523
524 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
524 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
525 """set_hook(name,hook) -> sets an internal IPython hook.
525 """set_hook(name,hook) -> sets an internal IPython hook.
526
526
527 IPython exposes some of its internal API as user-modifiable hooks. By
527 IPython exposes some of its internal API as user-modifiable hooks. By
528 adding your function to one of these hooks, you can modify IPython's
528 adding your function to one of these hooks, you can modify IPython's
529 behavior to call at runtime your own routines."""
529 behavior to call at runtime your own routines."""
530
530
531 # At some point in the future, this should validate the hook before it
531 # At some point in the future, this should validate the hook before it
532 # accepts it. Probably at least check that the hook takes the number
532 # accepts it. Probably at least check that the hook takes the number
533 # of args it's supposed to.
533 # of args it's supposed to.
534
534
535 f = new.instancemethod(hook,self,self.__class__)
535 f = new.instancemethod(hook,self,self.__class__)
536
536
537 # check if the hook is for strdispatcher first
537 # check if the hook is for strdispatcher first
538 if str_key is not None:
538 if str_key is not None:
539 sdp = self.strdispatchers.get(name, StrDispatch())
539 sdp = self.strdispatchers.get(name, StrDispatch())
540 sdp.add_s(str_key, f, priority )
540 sdp.add_s(str_key, f, priority )
541 self.strdispatchers[name] = sdp
541 self.strdispatchers[name] = sdp
542 return
542 return
543 if re_key is not None:
543 if re_key is not None:
544 sdp = self.strdispatchers.get(name, StrDispatch())
544 sdp = self.strdispatchers.get(name, StrDispatch())
545 sdp.add_re(re.compile(re_key), f, priority )
545 sdp.add_re(re.compile(re_key), f, priority )
546 self.strdispatchers[name] = sdp
546 self.strdispatchers[name] = sdp
547 return
547 return
548
548
549 dp = getattr(self.hooks, name, None)
549 dp = getattr(self.hooks, name, None)
550 if name not in IPython.core.hooks.__all__:
550 if name not in IPython.core.hooks.__all__:
551 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
551 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
552 if not dp:
552 if not dp:
553 dp = IPython.core.hooks.CommandChainDispatcher()
553 dp = IPython.core.hooks.CommandChainDispatcher()
554
554
555 try:
555 try:
556 dp.add(f,priority)
556 dp.add(f,priority)
557 except AttributeError:
557 except AttributeError:
558 # it was not commandchain, plain old func - replace
558 # it was not commandchain, plain old func - replace
559 dp = f
559 dp = f
560
560
561 setattr(self.hooks,name, dp)
561 setattr(self.hooks,name, dp)
562
562
563 #-------------------------------------------------------------------------
563 #-------------------------------------------------------------------------
564 # Things related to the "main" module
564 # Things related to the "main" module
565 #-------------------------------------------------------------------------
565 #-------------------------------------------------------------------------
566
566
567 def new_main_mod(self,ns=None):
567 def new_main_mod(self,ns=None):
568 """Return a new 'main' module object for user code execution.
568 """Return a new 'main' module object for user code execution.
569 """
569 """
570 main_mod = self._user_main_module
570 main_mod = self._user_main_module
571 init_fakemod_dict(main_mod,ns)
571 init_fakemod_dict(main_mod,ns)
572 return main_mod
572 return main_mod
573
573
574 def cache_main_mod(self,ns,fname):
574 def cache_main_mod(self,ns,fname):
575 """Cache a main module's namespace.
575 """Cache a main module's namespace.
576
576
577 When scripts are executed via %run, we must keep a reference to the
577 When scripts are executed via %run, we must keep a reference to the
578 namespace of their __main__ module (a FakeModule instance) around so
578 namespace of their __main__ module (a FakeModule instance) around so
579 that Python doesn't clear it, rendering objects defined therein
579 that Python doesn't clear it, rendering objects defined therein
580 useless.
580 useless.
581
581
582 This method keeps said reference in a private dict, keyed by the
582 This method keeps said reference in a private dict, keyed by the
583 absolute path of the module object (which corresponds to the script
583 absolute path of the module object (which corresponds to the script
584 path). This way, for multiple executions of the same script we only
584 path). This way, for multiple executions of the same script we only
585 keep one copy of the namespace (the last one), thus preventing memory
585 keep one copy of the namespace (the last one), thus preventing memory
586 leaks from old references while allowing the objects from the last
586 leaks from old references while allowing the objects from the last
587 execution to be accessible.
587 execution to be accessible.
588
588
589 Note: we can not allow the actual FakeModule instances to be deleted,
589 Note: we can not allow the actual FakeModule instances to be deleted,
590 because of how Python tears down modules (it hard-sets all their
590 because of how Python tears down modules (it hard-sets all their
591 references to None without regard for reference counts). This method
591 references to None without regard for reference counts). This method
592 must therefore make a *copy* of the given namespace, to allow the
592 must therefore make a *copy* of the given namespace, to allow the
593 original module's __dict__ to be cleared and reused.
593 original module's __dict__ to be cleared and reused.
594
594
595
595
596 Parameters
596 Parameters
597 ----------
597 ----------
598 ns : a namespace (a dict, typically)
598 ns : a namespace (a dict, typically)
599
599
600 fname : str
600 fname : str
601 Filename associated with the namespace.
601 Filename associated with the namespace.
602
602
603 Examples
603 Examples
604 --------
604 --------
605
605
606 In [10]: import IPython
606 In [10]: import IPython
607
607
608 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
608 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
609
609
610 In [12]: IPython.__file__ in _ip._main_ns_cache
610 In [12]: IPython.__file__ in _ip._main_ns_cache
611 Out[12]: True
611 Out[12]: True
612 """
612 """
613 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
613 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
614
614
615 def clear_main_mod_cache(self):
615 def clear_main_mod_cache(self):
616 """Clear the cache of main modules.
616 """Clear the cache of main modules.
617
617
618 Mainly for use by utilities like %reset.
618 Mainly for use by utilities like %reset.
619
619
620 Examples
620 Examples
621 --------
621 --------
622
622
623 In [15]: import IPython
623 In [15]: import IPython
624
624
625 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
625 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
626
626
627 In [17]: len(_ip._main_ns_cache) > 0
627 In [17]: len(_ip._main_ns_cache) > 0
628 Out[17]: True
628 Out[17]: True
629
629
630 In [18]: _ip.clear_main_mod_cache()
630 In [18]: _ip.clear_main_mod_cache()
631
631
632 In [19]: len(_ip._main_ns_cache) == 0
632 In [19]: len(_ip._main_ns_cache) == 0
633 Out[19]: True
633 Out[19]: True
634 """
634 """
635 self._main_ns_cache.clear()
635 self._main_ns_cache.clear()
636
636
637 #-------------------------------------------------------------------------
637 #-------------------------------------------------------------------------
638 # Things related to debugging
638 # Things related to debugging
639 #-------------------------------------------------------------------------
639 #-------------------------------------------------------------------------
640
640
641 def init_pdb(self):
641 def init_pdb(self):
642 # Set calling of pdb on exceptions
642 # Set calling of pdb on exceptions
643 # self.call_pdb is a property
643 # self.call_pdb is a property
644 self.call_pdb = self.pdb
644 self.call_pdb = self.pdb
645
645
646 def _get_call_pdb(self):
646 def _get_call_pdb(self):
647 return self._call_pdb
647 return self._call_pdb
648
648
649 def _set_call_pdb(self,val):
649 def _set_call_pdb(self,val):
650
650
651 if val not in (0,1,False,True):
651 if val not in (0,1,False,True):
652 raise ValueError,'new call_pdb value must be boolean'
652 raise ValueError,'new call_pdb value must be boolean'
653
653
654 # store value in instance
654 # store value in instance
655 self._call_pdb = val
655 self._call_pdb = val
656
656
657 # notify the actual exception handlers
657 # notify the actual exception handlers
658 self.InteractiveTB.call_pdb = val
658 self.InteractiveTB.call_pdb = val
659
659
660 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
660 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
661 'Control auto-activation of pdb at exceptions')
661 'Control auto-activation of pdb at exceptions')
662
662
663 def debugger(self,force=False):
663 def debugger(self,force=False):
664 """Call the pydb/pdb debugger.
664 """Call the pydb/pdb debugger.
665
665
666 Keywords:
666 Keywords:
667
667
668 - force(False): by default, this routine checks the instance call_pdb
668 - force(False): by default, this routine checks the instance call_pdb
669 flag and does not actually invoke the debugger if the flag is false.
669 flag and does not actually invoke the debugger if the flag is false.
670 The 'force' option forces the debugger to activate even if the flag
670 The 'force' option forces the debugger to activate even if the flag
671 is false.
671 is false.
672 """
672 """
673
673
674 if not (force or self.call_pdb):
674 if not (force or self.call_pdb):
675 return
675 return
676
676
677 if not hasattr(sys,'last_traceback'):
677 if not hasattr(sys,'last_traceback'):
678 error('No traceback has been produced, nothing to debug.')
678 error('No traceback has been produced, nothing to debug.')
679 return
679 return
680
680
681 # use pydb if available
681 # use pydb if available
682 if debugger.has_pydb:
682 if debugger.has_pydb:
683 from pydb import pm
683 from pydb import pm
684 else:
684 else:
685 # fallback to our internal debugger
685 # fallback to our internal debugger
686 pm = lambda : self.InteractiveTB.debugger(force=True)
686 pm = lambda : self.InteractiveTB.debugger(force=True)
687 self.history_saving_wrapper(pm)()
687 self.history_saving_wrapper(pm)()
688
688
689 #-------------------------------------------------------------------------
689 #-------------------------------------------------------------------------
690 # Things related to IPython's various namespaces
690 # Things related to IPython's various namespaces
691 #-------------------------------------------------------------------------
691 #-------------------------------------------------------------------------
692
692
693 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
693 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
694 # Create the namespace where the user will operate. user_ns is
694 # Create the namespace where the user will operate. user_ns is
695 # normally the only one used, and it is passed to the exec calls as
695 # normally the only one used, and it is passed to the exec calls as
696 # the locals argument. But we do carry a user_global_ns namespace
696 # the locals argument. But we do carry a user_global_ns namespace
697 # given as the exec 'globals' argument, This is useful in embedding
697 # given as the exec 'globals' argument, This is useful in embedding
698 # situations where the ipython shell opens in a context where the
698 # situations where the ipython shell opens in a context where the
699 # distinction between locals and globals is meaningful. For
699 # distinction between locals and globals is meaningful. For
700 # non-embedded contexts, it is just the same object as the user_ns dict.
700 # non-embedded contexts, it is just the same object as the user_ns dict.
701
701
702 # FIXME. For some strange reason, __builtins__ is showing up at user
702 # FIXME. For some strange reason, __builtins__ is showing up at user
703 # level as a dict instead of a module. This is a manual fix, but I
703 # level as a dict instead of a module. This is a manual fix, but I
704 # should really track down where the problem is coming from. Alex
704 # should really track down where the problem is coming from. Alex
705 # Schmolck reported this problem first.
705 # Schmolck reported this problem first.
706
706
707 # A useful post by Alex Martelli on this topic:
707 # A useful post by Alex Martelli on this topic:
708 # Re: inconsistent value from __builtins__
708 # Re: inconsistent value from __builtins__
709 # Von: Alex Martelli <aleaxit@yahoo.com>
709 # Von: Alex Martelli <aleaxit@yahoo.com>
710 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
710 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
711 # Gruppen: comp.lang.python
711 # Gruppen: comp.lang.python
712
712
713 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
713 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
714 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
714 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
715 # > <type 'dict'>
715 # > <type 'dict'>
716 # > >>> print type(__builtins__)
716 # > >>> print type(__builtins__)
717 # > <type 'module'>
717 # > <type 'module'>
718 # > Is this difference in return value intentional?
718 # > Is this difference in return value intentional?
719
719
720 # Well, it's documented that '__builtins__' can be either a dictionary
720 # Well, it's documented that '__builtins__' can be either a dictionary
721 # or a module, and it's been that way for a long time. Whether it's
721 # or a module, and it's been that way for a long time. Whether it's
722 # intentional (or sensible), I don't know. In any case, the idea is
722 # intentional (or sensible), I don't know. In any case, the idea is
723 # that if you need to access the built-in namespace directly, you
723 # that if you need to access the built-in namespace directly, you
724 # should start with "import __builtin__" (note, no 's') which will
724 # should start with "import __builtin__" (note, no 's') which will
725 # definitely give you a module. Yeah, it's somewhat confusing:-(.
725 # definitely give you a module. Yeah, it's somewhat confusing:-(.
726
726
727 # These routines return properly built dicts as needed by the rest of
727 # These routines return properly built dicts as needed by the rest of
728 # the code, and can also be used by extension writers to generate
728 # the code, and can also be used by extension writers to generate
729 # properly initialized namespaces.
729 # properly initialized namespaces.
730 user_ns, user_global_ns = self.make_user_namespaces(user_ns, user_global_ns)
730 user_ns, user_global_ns = self.make_user_namespaces(user_ns, user_global_ns)
731
731
732 # Assign namespaces
732 # Assign namespaces
733 # This is the namespace where all normal user variables live
733 # This is the namespace where all normal user variables live
734 self.user_ns = user_ns
734 self.user_ns = user_ns
735 self.user_global_ns = user_global_ns
735 self.user_global_ns = user_global_ns
736
736
737 # An auxiliary namespace that checks what parts of the user_ns were
737 # An auxiliary namespace that checks what parts of the user_ns were
738 # loaded at startup, so we can list later only variables defined in
738 # loaded at startup, so we can list later only variables defined in
739 # actual interactive use. Since it is always a subset of user_ns, it
739 # actual interactive use. Since it is always a subset of user_ns, it
740 # doesn't need to be separately tracked in the ns_table.
740 # doesn't need to be separately tracked in the ns_table.
741 self.user_ns_hidden = {}
741 self.user_ns_hidden = {}
742
742
743 # A namespace to keep track of internal data structures to prevent
743 # A namespace to keep track of internal data structures to prevent
744 # them from cluttering user-visible stuff. Will be updated later
744 # them from cluttering user-visible stuff. Will be updated later
745 self.internal_ns = {}
745 self.internal_ns = {}
746
746
747 # Now that FakeModule produces a real module, we've run into a nasty
747 # Now that FakeModule produces a real module, we've run into a nasty
748 # problem: after script execution (via %run), the module where the user
748 # problem: after script execution (via %run), the module where the user
749 # code ran is deleted. Now that this object is a true module (needed
749 # code ran is deleted. Now that this object is a true module (needed
750 # so docetst and other tools work correctly), the Python module
750 # so docetst and other tools work correctly), the Python module
751 # teardown mechanism runs over it, and sets to None every variable
751 # teardown mechanism runs over it, and sets to None every variable
752 # present in that module. Top-level references to objects from the
752 # present in that module. Top-level references to objects from the
753 # script survive, because the user_ns is updated with them. However,
753 # script survive, because the user_ns is updated with them. However,
754 # calling functions defined in the script that use other things from
754 # calling functions defined in the script that use other things from
755 # the script will fail, because the function's closure had references
755 # the script will fail, because the function's closure had references
756 # to the original objects, which are now all None. So we must protect
756 # to the original objects, which are now all None. So we must protect
757 # these modules from deletion by keeping a cache.
757 # these modules from deletion by keeping a cache.
758 #
758 #
759 # To avoid keeping stale modules around (we only need the one from the
759 # To avoid keeping stale modules around (we only need the one from the
760 # last run), we use a dict keyed with the full path to the script, so
760 # last run), we use a dict keyed with the full path to the script, so
761 # only the last version of the module is held in the cache. Note,
761 # only the last version of the module is held in the cache. Note,
762 # however, that we must cache the module *namespace contents* (their
762 # however, that we must cache the module *namespace contents* (their
763 # __dict__). Because if we try to cache the actual modules, old ones
763 # __dict__). Because if we try to cache the actual modules, old ones
764 # (uncached) could be destroyed while still holding references (such as
764 # (uncached) could be destroyed while still holding references (such as
765 # those held by GUI objects that tend to be long-lived)>
765 # those held by GUI objects that tend to be long-lived)>
766 #
766 #
767 # The %reset command will flush this cache. See the cache_main_mod()
767 # The %reset command will flush this cache. See the cache_main_mod()
768 # and clear_main_mod_cache() methods for details on use.
768 # and clear_main_mod_cache() methods for details on use.
769
769
770 # This is the cache used for 'main' namespaces
770 # This is the cache used for 'main' namespaces
771 self._main_ns_cache = {}
771 self._main_ns_cache = {}
772 # And this is the single instance of FakeModule whose __dict__ we keep
772 # And this is the single instance of FakeModule whose __dict__ we keep
773 # copying and clearing for reuse on each %run
773 # copying and clearing for reuse on each %run
774 self._user_main_module = FakeModule()
774 self._user_main_module = FakeModule()
775
775
776 # A table holding all the namespaces IPython deals with, so that
776 # A table holding all the namespaces IPython deals with, so that
777 # introspection facilities can search easily.
777 # introspection facilities can search easily.
778 self.ns_table = {'user':user_ns,
778 self.ns_table = {'user':user_ns,
779 'user_global':user_global_ns,
779 'user_global':user_global_ns,
780 'internal':self.internal_ns,
780 'internal':self.internal_ns,
781 'builtin':__builtin__.__dict__
781 'builtin':__builtin__.__dict__
782 }
782 }
783
783
784 # Similarly, track all namespaces where references can be held and that
784 # Similarly, track all namespaces where references can be held and that
785 # we can safely clear (so it can NOT include builtin). This one can be
785 # we can safely clear (so it can NOT include builtin). This one can be
786 # a simple list.
786 # a simple list.
787 self.ns_refs_table = [ user_ns, user_global_ns, self.user_ns_hidden,
787 self.ns_refs_table = [ user_ns, user_global_ns, self.user_ns_hidden,
788 self.internal_ns, self._main_ns_cache ]
788 self.internal_ns, self._main_ns_cache ]
789
789
790 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
790 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
791 """Return a valid local and global user interactive namespaces.
791 """Return a valid local and global user interactive namespaces.
792
792
793 This builds a dict with the minimal information needed to operate as a
793 This builds a dict with the minimal information needed to operate as a
794 valid IPython user namespace, which you can pass to the various
794 valid IPython user namespace, which you can pass to the various
795 embedding classes in ipython. The default implementation returns the
795 embedding classes in ipython. The default implementation returns the
796 same dict for both the locals and the globals to allow functions to
796 same dict for both the locals and the globals to allow functions to
797 refer to variables in the namespace. Customized implementations can
797 refer to variables in the namespace. Customized implementations can
798 return different dicts. The locals dictionary can actually be anything
798 return different dicts. The locals dictionary can actually be anything
799 following the basic mapping protocol of a dict, but the globals dict
799 following the basic mapping protocol of a dict, but the globals dict
800 must be a true dict, not even a subclass. It is recommended that any
800 must be a true dict, not even a subclass. It is recommended that any
801 custom object for the locals namespace synchronize with the globals
801 custom object for the locals namespace synchronize with the globals
802 dict somehow.
802 dict somehow.
803
803
804 Raises TypeError if the provided globals namespace is not a true dict.
804 Raises TypeError if the provided globals namespace is not a true dict.
805
805
806 Parameters
806 Parameters
807 ----------
807 ----------
808 user_ns : dict-like, optional
808 user_ns : dict-like, optional
809 The current user namespace. The items in this namespace should
809 The current user namespace. The items in this namespace should
810 be included in the output. If None, an appropriate blank
810 be included in the output. If None, an appropriate blank
811 namespace should be created.
811 namespace should be created.
812 user_global_ns : dict, optional
812 user_global_ns : dict, optional
813 The current user global namespace. The items in this namespace
813 The current user global namespace. The items in this namespace
814 should be included in the output. If None, an appropriate
814 should be included in the output. If None, an appropriate
815 blank namespace should be created.
815 blank namespace should be created.
816
816
817 Returns
817 Returns
818 -------
818 -------
819 A pair of dictionary-like object to be used as the local namespace
819 A pair of dictionary-like object to be used as the local namespace
820 of the interpreter and a dict to be used as the global namespace.
820 of the interpreter and a dict to be used as the global namespace.
821 """
821 """
822
822
823
823
824 # We must ensure that __builtin__ (without the final 's') is always
824 # We must ensure that __builtin__ (without the final 's') is always
825 # available and pointing to the __builtin__ *module*. For more details:
825 # available and pointing to the __builtin__ *module*. For more details:
826 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
826 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
827
827
828 if user_ns is None:
828 if user_ns is None:
829 # Set __name__ to __main__ to better match the behavior of the
829 # Set __name__ to __main__ to better match the behavior of the
830 # normal interpreter.
830 # normal interpreter.
831 user_ns = {'__name__' :'__main__',
831 user_ns = {'__name__' :'__main__',
832 '__builtin__' : __builtin__,
832 '__builtin__' : __builtin__,
833 '__builtins__' : __builtin__,
833 '__builtins__' : __builtin__,
834 }
834 }
835 else:
835 else:
836 user_ns.setdefault('__name__','__main__')
836 user_ns.setdefault('__name__','__main__')
837 user_ns.setdefault('__builtin__',__builtin__)
837 user_ns.setdefault('__builtin__',__builtin__)
838 user_ns.setdefault('__builtins__',__builtin__)
838 user_ns.setdefault('__builtins__',__builtin__)
839
839
840 if user_global_ns is None:
840 if user_global_ns is None:
841 user_global_ns = user_ns
841 user_global_ns = user_ns
842 if type(user_global_ns) is not dict:
842 if type(user_global_ns) is not dict:
843 raise TypeError("user_global_ns must be a true dict; got %r"
843 raise TypeError("user_global_ns must be a true dict; got %r"
844 % type(user_global_ns))
844 % type(user_global_ns))
845
845
846 return user_ns, user_global_ns
846 return user_ns, user_global_ns
847
847
848 def init_sys_modules(self):
848 def init_sys_modules(self):
849 # We need to insert into sys.modules something that looks like a
849 # We need to insert into sys.modules something that looks like a
850 # module but which accesses the IPython namespace, for shelve and
850 # module but which accesses the IPython namespace, for shelve and
851 # pickle to work interactively. Normally they rely on getting
851 # pickle to work interactively. Normally they rely on getting
852 # everything out of __main__, but for embedding purposes each IPython
852 # everything out of __main__, but for embedding purposes each IPython
853 # instance has its own private namespace, so we can't go shoving
853 # instance has its own private namespace, so we can't go shoving
854 # everything into __main__.
854 # everything into __main__.
855
855
856 # note, however, that we should only do this for non-embedded
856 # note, however, that we should only do this for non-embedded
857 # ipythons, which really mimic the __main__.__dict__ with their own
857 # ipythons, which really mimic the __main__.__dict__ with their own
858 # namespace. Embedded instances, on the other hand, should not do
858 # namespace. Embedded instances, on the other hand, should not do
859 # this because they need to manage the user local/global namespaces
859 # this because they need to manage the user local/global namespaces
860 # only, but they live within a 'normal' __main__ (meaning, they
860 # only, but they live within a 'normal' __main__ (meaning, they
861 # shouldn't overtake the execution environment of the script they're
861 # shouldn't overtake the execution environment of the script they're
862 # embedded in).
862 # embedded in).
863
863
864 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
864 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
865
865
866 try:
866 try:
867 main_name = self.user_ns['__name__']
867 main_name = self.user_ns['__name__']
868 except KeyError:
868 except KeyError:
869 raise KeyError('user_ns dictionary MUST have a "__name__" key')
869 raise KeyError('user_ns dictionary MUST have a "__name__" key')
870 else:
870 else:
871 sys.modules[main_name] = FakeModule(self.user_ns)
871 sys.modules[main_name] = FakeModule(self.user_ns)
872
872
873 def init_user_ns(self):
873 def init_user_ns(self):
874 """Initialize all user-visible namespaces to their minimum defaults.
874 """Initialize all user-visible namespaces to their minimum defaults.
875
875
876 Certain history lists are also initialized here, as they effectively
876 Certain history lists are also initialized here, as they effectively
877 act as user namespaces.
877 act as user namespaces.
878
878
879 Notes
879 Notes
880 -----
880 -----
881 All data structures here are only filled in, they are NOT reset by this
881 All data structures here are only filled in, they are NOT reset by this
882 method. If they were not empty before, data will simply be added to
882 method. If they were not empty before, data will simply be added to
883 therm.
883 therm.
884 """
884 """
885 # This function works in two parts: first we put a few things in
885 # This function works in two parts: first we put a few things in
886 # user_ns, and we sync that contents into user_ns_hidden so that these
886 # user_ns, and we sync that contents into user_ns_hidden so that these
887 # initial variables aren't shown by %who. After the sync, we add the
887 # initial variables aren't shown by %who. After the sync, we add the
888 # rest of what we *do* want the user to see with %who even on a new
888 # rest of what we *do* want the user to see with %who even on a new
889 # session (probably nothing, so theye really only see their own stuff)
889 # session (probably nothing, so theye really only see their own stuff)
890
890
891 # The user dict must *always* have a __builtin__ reference to the
891 # The user dict must *always* have a __builtin__ reference to the
892 # Python standard __builtin__ namespace, which must be imported.
892 # Python standard __builtin__ namespace, which must be imported.
893 # This is so that certain operations in prompt evaluation can be
893 # This is so that certain operations in prompt evaluation can be
894 # reliably executed with builtins. Note that we can NOT use
894 # reliably executed with builtins. Note that we can NOT use
895 # __builtins__ (note the 's'), because that can either be a dict or a
895 # __builtins__ (note the 's'), because that can either be a dict or a
896 # module, and can even mutate at runtime, depending on the context
896 # module, and can even mutate at runtime, depending on the context
897 # (Python makes no guarantees on it). In contrast, __builtin__ is
897 # (Python makes no guarantees on it). In contrast, __builtin__ is
898 # always a module object, though it must be explicitly imported.
898 # always a module object, though it must be explicitly imported.
899
899
900 # For more details:
900 # For more details:
901 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
901 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
902 ns = dict(__builtin__ = __builtin__)
902 ns = dict(__builtin__ = __builtin__)
903
903
904 # Put 'help' in the user namespace
904 # Put 'help' in the user namespace
905 try:
905 try:
906 from site import _Helper
906 from site import _Helper
907 ns['help'] = _Helper()
907 ns['help'] = _Helper()
908 except ImportError:
908 except ImportError:
909 warn('help() not available - check site.py')
909 warn('help() not available - check site.py')
910
910
911 # make global variables for user access to the histories
911 # make global variables for user access to the histories
912 ns['_ih'] = self.input_hist
912 ns['_ih'] = self.input_hist
913 ns['_oh'] = self.output_hist
913 ns['_oh'] = self.output_hist
914 ns['_dh'] = self.dir_hist
914 ns['_dh'] = self.dir_hist
915
915
916 ns['_sh'] = shadowns
916 ns['_sh'] = shadowns
917
917
918 # user aliases to input and output histories. These shouldn't show up
918 # user aliases to input and output histories. These shouldn't show up
919 # in %who, as they can have very large reprs.
919 # in %who, as they can have very large reprs.
920 ns['In'] = self.input_hist
920 ns['In'] = self.input_hist
921 ns['Out'] = self.output_hist
921 ns['Out'] = self.output_hist
922
922
923 # Store myself as the public api!!!
923 # Store myself as the public api!!!
924 ns['get_ipython'] = self.get_ipython
924 ns['get_ipython'] = self.get_ipython
925
925
926 # Sync what we've added so far to user_ns_hidden so these aren't seen
926 # Sync what we've added so far to user_ns_hidden so these aren't seen
927 # by %who
927 # by %who
928 self.user_ns_hidden.update(ns)
928 self.user_ns_hidden.update(ns)
929
929
930 # Anything put into ns now would show up in %who. Think twice before
930 # Anything put into ns now would show up in %who. Think twice before
931 # putting anything here, as we really want %who to show the user their
931 # putting anything here, as we really want %who to show the user their
932 # stuff, not our variables.
932 # stuff, not our variables.
933
933
934 # Finally, update the real user's namespace
934 # Finally, update the real user's namespace
935 self.user_ns.update(ns)
935 self.user_ns.update(ns)
936
936
937
937
938 def reset(self):
938 def reset(self):
939 """Clear all internal namespaces.
939 """Clear all internal namespaces.
940
940
941 Note that this is much more aggressive than %reset, since it clears
941 Note that this is much more aggressive than %reset, since it clears
942 fully all namespaces, as well as all input/output lists.
942 fully all namespaces, as well as all input/output lists.
943 """
943 """
944 for ns in self.ns_refs_table:
944 for ns in self.ns_refs_table:
945 ns.clear()
945 ns.clear()
946
946
947 self.alias_manager.clear_aliases()
947 self.alias_manager.clear_aliases()
948
948
949 # Clear input and output histories
949 # Clear input and output histories
950 self.input_hist[:] = []
950 self.input_hist[:] = []
951 self.input_hist_raw[:] = []
951 self.input_hist_raw[:] = []
952 self.output_hist.clear()
952 self.output_hist.clear()
953
953
954 # Restore the user namespaces to minimal usability
954 # Restore the user namespaces to minimal usability
955 self.init_user_ns()
955 self.init_user_ns()
956
956
957 # Restore the default and user aliases
957 # Restore the default and user aliases
958 self.alias_manager.init_aliases()
958 self.alias_manager.init_aliases()
959
959
960 def reset_selective(self, regex=None):
960 def reset_selective(self, regex=None):
961 """Clear selective variables from internal namespaces based on a specified regular expression.
961 """Clear selective variables from internal namespaces based on a specified regular expression.
962
962
963 Parameters
963 Parameters
964 ----------
964 ----------
965 regex : string or compiled pattern, optional
965 regex : string or compiled pattern, optional
966 A regular expression pattern that will be used in searching variable names in the users
966 A regular expression pattern that will be used in searching variable names in the users
967 namespaces.
967 namespaces.
968 """
968 """
969 if regex is not None:
969 if regex is not None:
970 try:
970 try:
971 m = re.compile(regex)
971 m = re.compile(regex)
972 except TypeError:
972 except TypeError:
973 raise TypeError('regex must be a string or compiled pattern')
973 raise TypeError('regex must be a string or compiled pattern')
974 # Search for keys in each namespace that match the given regex
974 # Search for keys in each namespace that match the given regex
975 # If a match is found, delete the key/value pair.
975 # If a match is found, delete the key/value pair.
976 for ns in self.ns_refs_table:
976 for ns in self.ns_refs_table:
977 for var in ns:
977 for var in ns:
978 if m.search(var):
978 if m.search(var):
979 del ns[var]
979 del ns[var]
980
980
981 def push(self, variables, interactive=True):
981 def push(self, variables, interactive=True):
982 """Inject a group of variables into the IPython user namespace.
982 """Inject a group of variables into the IPython user namespace.
983
983
984 Parameters
984 Parameters
985 ----------
985 ----------
986 variables : dict, str or list/tuple of str
986 variables : dict, str or list/tuple of str
987 The variables to inject into the user's namespace. If a dict,
987 The variables to inject into the user's namespace. If a dict,
988 a simple update is done. If a str, the string is assumed to
988 a simple update is done. If a str, the string is assumed to
989 have variable names separated by spaces. A list/tuple of str
989 have variable names separated by spaces. A list/tuple of str
990 can also be used to give the variable names. If just the variable
990 can also be used to give the variable names. If just the variable
991 names are give (list/tuple/str) then the variable values looked
991 names are give (list/tuple/str) then the variable values looked
992 up in the callers frame.
992 up in the callers frame.
993 interactive : bool
993 interactive : bool
994 If True (default), the variables will be listed with the ``who``
994 If True (default), the variables will be listed with the ``who``
995 magic.
995 magic.
996 """
996 """
997 vdict = None
997 vdict = None
998
998
999 # We need a dict of name/value pairs to do namespace updates.
999 # We need a dict of name/value pairs to do namespace updates.
1000 if isinstance(variables, dict):
1000 if isinstance(variables, dict):
1001 vdict = variables
1001 vdict = variables
1002 elif isinstance(variables, (basestring, list, tuple)):
1002 elif isinstance(variables, (basestring, list, tuple)):
1003 if isinstance(variables, basestring):
1003 if isinstance(variables, basestring):
1004 vlist = variables.split()
1004 vlist = variables.split()
1005 else:
1005 else:
1006 vlist = variables
1006 vlist = variables
1007 vdict = {}
1007 vdict = {}
1008 cf = sys._getframe(1)
1008 cf = sys._getframe(1)
1009 for name in vlist:
1009 for name in vlist:
1010 try:
1010 try:
1011 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1011 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1012 except:
1012 except:
1013 print ('Could not get variable %s from %s' %
1013 print ('Could not get variable %s from %s' %
1014 (name,cf.f_code.co_name))
1014 (name,cf.f_code.co_name))
1015 else:
1015 else:
1016 raise ValueError('variables must be a dict/str/list/tuple')
1016 raise ValueError('variables must be a dict/str/list/tuple')
1017
1017
1018 # Propagate variables to user namespace
1018 # Propagate variables to user namespace
1019 self.user_ns.update(vdict)
1019 self.user_ns.update(vdict)
1020
1020
1021 # And configure interactive visibility
1021 # And configure interactive visibility
1022 config_ns = self.user_ns_hidden
1022 config_ns = self.user_ns_hidden
1023 if interactive:
1023 if interactive:
1024 for name, val in vdict.iteritems():
1024 for name, val in vdict.iteritems():
1025 config_ns.pop(name, None)
1025 config_ns.pop(name, None)
1026 else:
1026 else:
1027 for name,val in vdict.iteritems():
1027 for name,val in vdict.iteritems():
1028 config_ns[name] = val
1028 config_ns[name] = val
1029
1029
1030 #-------------------------------------------------------------------------
1030 #-------------------------------------------------------------------------
1031 # Things related to history management
1031 # Things related to history management
1032 #-------------------------------------------------------------------------
1032 #-------------------------------------------------------------------------
1033
1033
1034 def init_history(self):
1034 def init_history(self):
1035 # List of input with multi-line handling.
1035 # List of input with multi-line handling.
1036 self.input_hist = InputList()
1036 self.input_hist = InputList()
1037 # This one will hold the 'raw' input history, without any
1037 # This one will hold the 'raw' input history, without any
1038 # pre-processing. This will allow users to retrieve the input just as
1038 # pre-processing. This will allow users to retrieve the input just as
1039 # it was exactly typed in by the user, with %hist -r.
1039 # it was exactly typed in by the user, with %hist -r.
1040 self.input_hist_raw = InputList()
1040 self.input_hist_raw = InputList()
1041
1041
1042 # list of visited directories
1042 # list of visited directories
1043 try:
1043 try:
1044 self.dir_hist = [os.getcwd()]
1044 self.dir_hist = [os.getcwd()]
1045 except OSError:
1045 except OSError:
1046 self.dir_hist = []
1046 self.dir_hist = []
1047
1047
1048 # dict of output history
1048 # dict of output history
1049 self.output_hist = {}
1049 self.output_hist = {}
1050
1050
1051 # Now the history file
1051 # Now the history file
1052 if self.profile:
1052 if self.profile:
1053 histfname = 'history-%s' % self.profile
1053 histfname = 'history-%s' % self.profile
1054 else:
1054 else:
1055 histfname = 'history'
1055 histfname = 'history'
1056 self.histfile = os.path.join(self.ipython_dir, histfname)
1056 self.histfile = os.path.join(self.ipython_dir, histfname)
1057
1057
1058 # Fill the history zero entry, user counter starts at 1
1058 # Fill the history zero entry, user counter starts at 1
1059 self.input_hist.append('\n')
1059 self.input_hist.append('\n')
1060 self.input_hist_raw.append('\n')
1060 self.input_hist_raw.append('\n')
1061
1061
1062 def init_shadow_hist(self):
1062 def init_shadow_hist(self):
1063 try:
1063 try:
1064 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1064 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1065 except exceptions.UnicodeDecodeError:
1065 except exceptions.UnicodeDecodeError:
1066 print "Your ipython_dir can't be decoded to unicode!"
1066 print "Your ipython_dir can't be decoded to unicode!"
1067 print "Please set HOME environment variable to something that"
1067 print "Please set HOME environment variable to something that"
1068 print r"only has ASCII characters, e.g. c:\home"
1068 print r"only has ASCII characters, e.g. c:\home"
1069 print "Now it is", self.ipython_dir
1069 print "Now it is", self.ipython_dir
1070 sys.exit()
1070 sys.exit()
1071 self.shadowhist = ipcorehist.ShadowHist(self.db)
1071 self.shadowhist = ipcorehist.ShadowHist(self.db)
1072
1072
1073 def savehist(self):
1073 def savehist(self):
1074 """Save input history to a file (via readline library)."""
1074 """Save input history to a file (via readline library)."""
1075
1075
1076 try:
1076 try:
1077 self.readline.write_history_file(self.histfile)
1077 self.readline.write_history_file(self.histfile)
1078 except:
1078 except:
1079 print 'Unable to save IPython command history to file: ' + \
1079 print 'Unable to save IPython command history to file: ' + \
1080 `self.histfile`
1080 `self.histfile`
1081
1081
1082 def reloadhist(self):
1082 def reloadhist(self):
1083 """Reload the input history from disk file."""
1083 """Reload the input history from disk file."""
1084
1084
1085 try:
1085 try:
1086 self.readline.clear_history()
1086 self.readline.clear_history()
1087 self.readline.read_history_file(self.shell.histfile)
1087 self.readline.read_history_file(self.shell.histfile)
1088 except AttributeError:
1088 except AttributeError:
1089 pass
1089 pass
1090
1090
1091 def history_saving_wrapper(self, func):
1091 def history_saving_wrapper(self, func):
1092 """ Wrap func for readline history saving
1092 """ Wrap func for readline history saving
1093
1093
1094 Convert func into callable that saves & restores
1094 Convert func into callable that saves & restores
1095 history around the call """
1095 history around the call """
1096
1096
1097 if self.has_readline:
1097 if self.has_readline:
1098 from IPython.utils import rlineimpl as readline
1098 from IPython.utils import rlineimpl as readline
1099 else:
1099 else:
1100 return func
1100 return func
1101
1101
1102 def wrapper():
1102 def wrapper():
1103 self.savehist()
1103 self.savehist()
1104 try:
1104 try:
1105 func()
1105 func()
1106 finally:
1106 finally:
1107 readline.read_history_file(self.histfile)
1107 readline.read_history_file(self.histfile)
1108 return wrapper
1108 return wrapper
1109
1109
1110 def get_history(self, index=None, raw=False, output=True):
1110 def get_history(self, index=None, raw=False, output=True):
1111 """Get the history list.
1111 """Get the history list.
1112
1112
1113 Get the input and output history.
1113 Get the input and output history.
1114
1114
1115 Parameters
1115 Parameters
1116 ----------
1116 ----------
1117 index : n or (n1, n2) or None
1117 index : n or (n1, n2) or None
1118 If n, then the last entries. If a tuple, then all in
1118 If n, then the last entries. If a tuple, then all in
1119 range(n1, n2). If None, then all entries. Raises IndexError if
1119 range(n1, n2). If None, then all entries. Raises IndexError if
1120 the format of index is incorrect.
1120 the format of index is incorrect.
1121 raw : bool
1121 raw : bool
1122 If True, return the raw input.
1122 If True, return the raw input.
1123 output : bool
1123 output : bool
1124 If True, then return the output as well.
1124 If True, then return the output as well.
1125
1125
1126 Returns
1126 Returns
1127 -------
1127 -------
1128 If output is True, then return a dict of tuples, keyed by the prompt
1128 If output is True, then return a dict of tuples, keyed by the prompt
1129 numbers and with values of (input, output). If output is False, then
1129 numbers and with values of (input, output). If output is False, then
1130 a dict, keyed by the prompt number with the values of input. Raises
1130 a dict, keyed by the prompt number with the values of input. Raises
1131 IndexError if no history is found.
1131 IndexError if no history is found.
1132 """
1132 """
1133 if raw:
1133 if raw:
1134 input_hist = self.input_hist_raw
1134 input_hist = self.input_hist_raw
1135 else:
1135 else:
1136 input_hist = self.input_hist
1136 input_hist = self.input_hist
1137 if output:
1137 if output:
1138 output_hist = self.user_ns['Out']
1138 output_hist = self.user_ns['Out']
1139 n = len(input_hist)
1139 n = len(input_hist)
1140 if index is None:
1140 if index is None:
1141 start=0; stop=n
1141 start=0; stop=n
1142 elif isinstance(index, int):
1142 elif isinstance(index, int):
1143 start=n-index; stop=n
1143 start=n-index; stop=n
1144 elif isinstance(index, tuple) and len(index) == 2:
1144 elif isinstance(index, tuple) and len(index) == 2:
1145 start=index[0]; stop=index[1]
1145 start=index[0]; stop=index[1]
1146 else:
1146 else:
1147 raise IndexError('Not a valid index for the input history: %r' % index)
1147 raise IndexError('Not a valid index for the input history: %r' % index)
1148 hist = {}
1148 hist = {}
1149 for i in range(start, stop):
1149 for i in range(start, stop):
1150 if output:
1150 if output:
1151 hist[i] = (input_hist[i], output_hist.get(i))
1151 hist[i] = (input_hist[i], output_hist.get(i))
1152 else:
1152 else:
1153 hist[i] = input_hist[i]
1153 hist[i] = input_hist[i]
1154 if len(hist)==0:
1154 if len(hist)==0:
1155 raise IndexError('No history for range of indices: %r' % index)
1155 raise IndexError('No history for range of indices: %r' % index)
1156 return hist
1156 return hist
1157
1157
1158 #-------------------------------------------------------------------------
1158 #-------------------------------------------------------------------------
1159 # Things related to exception handling and tracebacks (not debugging)
1159 # Things related to exception handling and tracebacks (not debugging)
1160 #-------------------------------------------------------------------------
1160 #-------------------------------------------------------------------------
1161
1161
1162 def init_traceback_handlers(self, custom_exceptions):
1162 def init_traceback_handlers(self, custom_exceptions):
1163 # Syntax error handler.
1163 # Syntax error handler.
1164 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1164 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1165
1165
1166 # The interactive one is initialized with an offset, meaning we always
1166 # The interactive one is initialized with an offset, meaning we always
1167 # want to remove the topmost item in the traceback, which is our own
1167 # want to remove the topmost item in the traceback, which is our own
1168 # internal code. Valid modes: ['Plain','Context','Verbose']
1168 # internal code. Valid modes: ['Plain','Context','Verbose']
1169 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1169 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1170 color_scheme='NoColor',
1170 color_scheme='NoColor',
1171 tb_offset = 1)
1171 tb_offset = 1)
1172
1172
1173 # The instance will store a pointer to the system-wide exception hook,
1173 # The instance will store a pointer to the system-wide exception hook,
1174 # so that runtime code (such as magics) can access it. This is because
1174 # so that runtime code (such as magics) can access it. This is because
1175 # during the read-eval loop, it may get temporarily overwritten.
1175 # during the read-eval loop, it may get temporarily overwritten.
1176 self.sys_excepthook = sys.excepthook
1176 self.sys_excepthook = sys.excepthook
1177
1177
1178 # and add any custom exception handlers the user may have specified
1178 # and add any custom exception handlers the user may have specified
1179 self.set_custom_exc(*custom_exceptions)
1179 self.set_custom_exc(*custom_exceptions)
1180
1180
1181 # Set the exception mode
1181 # Set the exception mode
1182 self.InteractiveTB.set_mode(mode=self.xmode)
1182 self.InteractiveTB.set_mode(mode=self.xmode)
1183
1183
1184 def set_custom_exc(self,exc_tuple,handler):
1184 def set_custom_exc(self,exc_tuple,handler):
1185 """set_custom_exc(exc_tuple,handler)
1185 """set_custom_exc(exc_tuple,handler)
1186
1186
1187 Set a custom exception handler, which will be called if any of the
1187 Set a custom exception handler, which will be called if any of the
1188 exceptions in exc_tuple occur in the mainloop (specifically, in the
1188 exceptions in exc_tuple occur in the mainloop (specifically, in the
1189 runcode() method.
1189 runcode() method.
1190
1190
1191 Inputs:
1191 Inputs:
1192
1192
1193 - exc_tuple: a *tuple* of valid exceptions to call the defined
1193 - exc_tuple: a *tuple* of valid exceptions to call the defined
1194 handler for. It is very important that you use a tuple, and NOT A
1194 handler for. It is very important that you use a tuple, and NOT A
1195 LIST here, because of the way Python's except statement works. If
1195 LIST here, because of the way Python's except statement works. If
1196 you only want to trap a single exception, use a singleton tuple:
1196 you only want to trap a single exception, use a singleton tuple:
1197
1197
1198 exc_tuple == (MyCustomException,)
1198 exc_tuple == (MyCustomException,)
1199
1199
1200 - handler: this must be defined as a function with the following
1200 - handler: this must be defined as a function with the following
1201 basic interface: def my_handler(self,etype,value,tb).
1201 basic interface: def my_handler(self,etype,value,tb).
1202
1202
1203 This will be made into an instance method (via new.instancemethod)
1203 This will be made into an instance method (via new.instancemethod)
1204 of IPython itself, and it will be called if any of the exceptions
1204 of IPython itself, and it will be called if any of the exceptions
1205 listed in the exc_tuple are caught. If the handler is None, an
1205 listed in the exc_tuple are caught. If the handler is None, an
1206 internal basic one is used, which just prints basic info.
1206 internal basic one is used, which just prints basic info.
1207
1207
1208 WARNING: by putting in your own exception handler into IPython's main
1208 WARNING: by putting in your own exception handler into IPython's main
1209 execution loop, you run a very good chance of nasty crashes. This
1209 execution loop, you run a very good chance of nasty crashes. This
1210 facility should only be used if you really know what you are doing."""
1210 facility should only be used if you really know what you are doing."""
1211
1211
1212 assert type(exc_tuple)==type(()) , \
1212 assert type(exc_tuple)==type(()) , \
1213 "The custom exceptions must be given AS A TUPLE."
1213 "The custom exceptions must be given AS A TUPLE."
1214
1214
1215 def dummy_handler(self,etype,value,tb):
1215 def dummy_handler(self,etype,value,tb):
1216 print '*** Simple custom exception handler ***'
1216 print '*** Simple custom exception handler ***'
1217 print 'Exception type :',etype
1217 print 'Exception type :',etype
1218 print 'Exception value:',value
1218 print 'Exception value:',value
1219 print 'Traceback :',tb
1219 print 'Traceback :',tb
1220 print 'Source code :','\n'.join(self.buffer)
1220 print 'Source code :','\n'.join(self.buffer)
1221
1221
1222 if handler is None: handler = dummy_handler
1222 if handler is None: handler = dummy_handler
1223
1223
1224 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1224 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1225 self.custom_exceptions = exc_tuple
1225 self.custom_exceptions = exc_tuple
1226
1226
1227 def excepthook(self, etype, value, tb):
1227 def excepthook(self, etype, value, tb):
1228 """One more defense for GUI apps that call sys.excepthook.
1228 """One more defense for GUI apps that call sys.excepthook.
1229
1229
1230 GUI frameworks like wxPython trap exceptions and call
1230 GUI frameworks like wxPython trap exceptions and call
1231 sys.excepthook themselves. I guess this is a feature that
1231 sys.excepthook themselves. I guess this is a feature that
1232 enables them to keep running after exceptions that would
1232 enables them to keep running after exceptions that would
1233 otherwise kill their mainloop. This is a bother for IPython
1233 otherwise kill their mainloop. This is a bother for IPython
1234 which excepts to catch all of the program exceptions with a try:
1234 which excepts to catch all of the program exceptions with a try:
1235 except: statement.
1235 except: statement.
1236
1236
1237 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1237 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1238 any app directly invokes sys.excepthook, it will look to the user like
1238 any app directly invokes sys.excepthook, it will look to the user like
1239 IPython crashed. In order to work around this, we can disable the
1239 IPython crashed. In order to work around this, we can disable the
1240 CrashHandler and replace it with this excepthook instead, which prints a
1240 CrashHandler and replace it with this excepthook instead, which prints a
1241 regular traceback using our InteractiveTB. In this fashion, apps which
1241 regular traceback using our InteractiveTB. In this fashion, apps which
1242 call sys.excepthook will generate a regular-looking exception from
1242 call sys.excepthook will generate a regular-looking exception from
1243 IPython, and the CrashHandler will only be triggered by real IPython
1243 IPython, and the CrashHandler will only be triggered by real IPython
1244 crashes.
1244 crashes.
1245
1245
1246 This hook should be used sparingly, only in places which are not likely
1246 This hook should be used sparingly, only in places which are not likely
1247 to be true IPython errors.
1247 to be true IPython errors.
1248 """
1248 """
1249 self.showtraceback((etype,value,tb),tb_offset=0)
1249 self.showtraceback((etype,value,tb),tb_offset=0)
1250
1250
1251 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1251 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1252 exception_only=False):
1252 exception_only=False):
1253 """Display the exception that just occurred.
1253 """Display the exception that just occurred.
1254
1254
1255 If nothing is known about the exception, this is the method which
1255 If nothing is known about the exception, this is the method which
1256 should be used throughout the code for presenting user tracebacks,
1256 should be used throughout the code for presenting user tracebacks,
1257 rather than directly invoking the InteractiveTB object.
1257 rather than directly invoking the InteractiveTB object.
1258
1258
1259 A specific showsyntaxerror() also exists, but this method can take
1259 A specific showsyntaxerror() also exists, but this method can take
1260 care of calling it if needed, so unless you are explicitly catching a
1260 care of calling it if needed, so unless you are explicitly catching a
1261 SyntaxError exception, don't try to analyze the stack manually and
1261 SyntaxError exception, don't try to analyze the stack manually and
1262 simply call this method."""
1262 simply call this method."""
1263
1263
1264 try:
1264 try:
1265 if exc_tuple is None:
1265 if exc_tuple is None:
1266 etype, value, tb = sys.exc_info()
1266 etype, value, tb = sys.exc_info()
1267 else:
1267 else:
1268 etype, value, tb = exc_tuple
1268 etype, value, tb = exc_tuple
1269
1269
1270 if etype is None:
1270 if etype is None:
1271 if hasattr(sys, 'last_type'):
1271 if hasattr(sys, 'last_type'):
1272 etype, value, tb = sys.last_type, sys.last_value, \
1272 etype, value, tb = sys.last_type, sys.last_value, \
1273 sys.last_traceback
1273 sys.last_traceback
1274 else:
1274 else:
1275 self.write('No traceback available to show.\n')
1275 self.write('No traceback available to show.\n')
1276 return
1276 return
1277
1277
1278 if etype is SyntaxError:
1278 if etype is SyntaxError:
1279 # Though this won't be called by syntax errors in the input
1279 # Though this won't be called by syntax errors in the input
1280 # line, there may be SyntaxError cases whith imported code.
1280 # line, there may be SyntaxError cases whith imported code.
1281 self.showsyntaxerror(filename)
1281 self.showsyntaxerror(filename)
1282 elif etype is UsageError:
1282 elif etype is UsageError:
1283 print "UsageError:", value
1283 print "UsageError:", value
1284 else:
1284 else:
1285 # WARNING: these variables are somewhat deprecated and not
1285 # WARNING: these variables are somewhat deprecated and not
1286 # necessarily safe to use in a threaded environment, but tools
1286 # necessarily safe to use in a threaded environment, but tools
1287 # like pdb depend on their existence, so let's set them. If we
1287 # like pdb depend on their existence, so let's set them. If we
1288 # find problems in the field, we'll need to revisit their use.
1288 # find problems in the field, we'll need to revisit their use.
1289 sys.last_type = etype
1289 sys.last_type = etype
1290 sys.last_value = value
1290 sys.last_value = value
1291 sys.last_traceback = tb
1291 sys.last_traceback = tb
1292
1292
1293 if etype in self.custom_exceptions:
1293 if etype in self.custom_exceptions:
1294 self.CustomTB(etype,value,tb)
1294 self.CustomTB(etype,value,tb)
1295 else:
1295 else:
1296 if exception_only:
1296 if exception_only:
1297 m = ('An exception has occurred, use %tb to see the '
1297 m = ('An exception has occurred, use %tb to see the '
1298 'full traceback.')
1298 'full traceback.')
1299 print m
1299 print m
1300 self.InteractiveTB.show_exception_only(etype, value)
1300 self.InteractiveTB.show_exception_only(etype, value)
1301 else:
1301 else:
1302 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1302 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1303 if self.InteractiveTB.call_pdb:
1303 if self.InteractiveTB.call_pdb:
1304 # pdb mucks up readline, fix it back
1304 # pdb mucks up readline, fix it back
1305 self.set_completer()
1305 self.set_completer()
1306
1306
1307 except KeyboardInterrupt:
1307 except KeyboardInterrupt:
1308 self.write("\nKeyboardInterrupt\n")
1308 self.write("\nKeyboardInterrupt\n")
1309
1309
1310
1310
1311 def showsyntaxerror(self, filename=None):
1311 def showsyntaxerror(self, filename=None):
1312 """Display the syntax error that just occurred.
1312 """Display the syntax error that just occurred.
1313
1313
1314 This doesn't display a stack trace because there isn't one.
1314 This doesn't display a stack trace because there isn't one.
1315
1315
1316 If a filename is given, it is stuffed in the exception instead
1316 If a filename is given, it is stuffed in the exception instead
1317 of what was there before (because Python's parser always uses
1317 of what was there before (because Python's parser always uses
1318 "<string>" when reading from a string).
1318 "<string>" when reading from a string).
1319 """
1319 """
1320 etype, value, last_traceback = sys.exc_info()
1320 etype, value, last_traceback = sys.exc_info()
1321
1321
1322 # See note about these variables in showtraceback() above
1322 # See note about these variables in showtraceback() above
1323 sys.last_type = etype
1323 sys.last_type = etype
1324 sys.last_value = value
1324 sys.last_value = value
1325 sys.last_traceback = last_traceback
1325 sys.last_traceback = last_traceback
1326
1326
1327 if filename and etype is SyntaxError:
1327 if filename and etype is SyntaxError:
1328 # Work hard to stuff the correct filename in the exception
1328 # Work hard to stuff the correct filename in the exception
1329 try:
1329 try:
1330 msg, (dummy_filename, lineno, offset, line) = value
1330 msg, (dummy_filename, lineno, offset, line) = value
1331 except:
1331 except:
1332 # Not the format we expect; leave it alone
1332 # Not the format we expect; leave it alone
1333 pass
1333 pass
1334 else:
1334 else:
1335 # Stuff in the right filename
1335 # Stuff in the right filename
1336 try:
1336 try:
1337 # Assume SyntaxError is a class exception
1337 # Assume SyntaxError is a class exception
1338 value = SyntaxError(msg, (filename, lineno, offset, line))
1338 value = SyntaxError(msg, (filename, lineno, offset, line))
1339 except:
1339 except:
1340 # If that failed, assume SyntaxError is a string
1340 # If that failed, assume SyntaxError is a string
1341 value = msg, (filename, lineno, offset, line)
1341 value = msg, (filename, lineno, offset, line)
1342 self.SyntaxTB(etype,value,[])
1342 self.SyntaxTB(etype,value,[])
1343
1343
1344 #-------------------------------------------------------------------------
1344 #-------------------------------------------------------------------------
1345 # Things related to tab completion
1345 # Things related to tab completion
1346 #-------------------------------------------------------------------------
1346 #-------------------------------------------------------------------------
1347
1347
1348 def complete(self, text):
1348 def complete(self, text):
1349 """Return a sorted list of all possible completions on text.
1349 """Return a sorted list of all possible completions on text.
1350
1350
1351 Inputs:
1351 Inputs:
1352
1352
1353 - text: a string of text to be completed on.
1353 - text: a string of text to be completed on.
1354
1354
1355 This is a wrapper around the completion mechanism, similar to what
1355 This is a wrapper around the completion mechanism, similar to what
1356 readline does at the command line when the TAB key is hit. By
1356 readline does at the command line when the TAB key is hit. By
1357 exposing it as a method, it can be used by other non-readline
1357 exposing it as a method, it can be used by other non-readline
1358 environments (such as GUIs) for text completion.
1358 environments (such as GUIs) for text completion.
1359
1359
1360 Simple usage example:
1360 Simple usage example:
1361
1361
1362 In [7]: x = 'hello'
1362 In [7]: x = 'hello'
1363
1363
1364 In [8]: x
1364 In [8]: x
1365 Out[8]: 'hello'
1365 Out[8]: 'hello'
1366
1366
1367 In [9]: print x
1367 In [9]: print x
1368 hello
1368 hello
1369
1369
1370 In [10]: _ip.complete('x.l')
1370 In [10]: _ip.complete('x.l')
1371 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1371 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1372 """
1372 """
1373
1373
1374 # Inject names into __builtin__ so we can complete on the added names.
1374 # Inject names into __builtin__ so we can complete on the added names.
1375 with self.builtin_trap:
1375 with self.builtin_trap:
1376 complete = self.Completer.complete
1376 complete = self.Completer.complete
1377 state = 0
1377 state = 0
1378 # use a dict so we get unique keys, since ipyhton's multiple
1378 # use a dict so we get unique keys, since ipyhton's multiple
1379 # completers can return duplicates. When we make 2.4 a requirement,
1379 # completers can return duplicates. When we make 2.4 a requirement,
1380 # start using sets instead, which are faster.
1380 # start using sets instead, which are faster.
1381 comps = {}
1381 comps = {}
1382 while True:
1382 while True:
1383 newcomp = complete(text,state,line_buffer=text)
1383 newcomp = complete(text,state,line_buffer=text)
1384 if newcomp is None:
1384 if newcomp is None:
1385 break
1385 break
1386 comps[newcomp] = 1
1386 comps[newcomp] = 1
1387 state += 1
1387 state += 1
1388 outcomps = comps.keys()
1388 outcomps = comps.keys()
1389 outcomps.sort()
1389 outcomps.sort()
1390 #print "T:",text,"OC:",outcomps # dbg
1390 #print "T:",text,"OC:",outcomps # dbg
1391 #print "vars:",self.user_ns.keys()
1391 #print "vars:",self.user_ns.keys()
1392 return outcomps
1392 return outcomps
1393
1393
1394 def set_custom_completer(self,completer,pos=0):
1394 def set_custom_completer(self,completer,pos=0):
1395 """Adds a new custom completer function.
1395 """Adds a new custom completer function.
1396
1396
1397 The position argument (defaults to 0) is the index in the completers
1397 The position argument (defaults to 0) is the index in the completers
1398 list where you want the completer to be inserted."""
1398 list where you want the completer to be inserted."""
1399
1399
1400 newcomp = new.instancemethod(completer,self.Completer,
1400 newcomp = new.instancemethod(completer,self.Completer,
1401 self.Completer.__class__)
1401 self.Completer.__class__)
1402 self.Completer.matchers.insert(pos,newcomp)
1402 self.Completer.matchers.insert(pos,newcomp)
1403
1403
1404 def set_completer(self):
1404 def set_completer(self):
1405 """Reset readline's completer to be our own."""
1405 """Reset readline's completer to be our own."""
1406 self.readline.set_completer(self.Completer.complete)
1406 self.readline.set_completer(self.Completer.complete)
1407
1407
1408 def set_completer_frame(self, frame=None):
1408 def set_completer_frame(self, frame=None):
1409 """Set the frame of the completer."""
1409 """Set the frame of the completer."""
1410 if frame:
1410 if frame:
1411 self.Completer.namespace = frame.f_locals
1411 self.Completer.namespace = frame.f_locals
1412 self.Completer.global_namespace = frame.f_globals
1412 self.Completer.global_namespace = frame.f_globals
1413 else:
1413 else:
1414 self.Completer.namespace = self.user_ns
1414 self.Completer.namespace = self.user_ns
1415 self.Completer.global_namespace = self.user_global_ns
1415 self.Completer.global_namespace = self.user_global_ns
1416
1416
1417 #-------------------------------------------------------------------------
1417 #-------------------------------------------------------------------------
1418 # Things related to readline
1418 # Things related to readline
1419 #-------------------------------------------------------------------------
1419 #-------------------------------------------------------------------------
1420
1420
1421 def init_readline(self):
1421 def init_readline(self):
1422 """Command history completion/saving/reloading."""
1422 """Command history completion/saving/reloading."""
1423
1423
1424 if self.readline_use:
1424 if self.readline_use:
1425 import IPython.utils.rlineimpl as readline
1425 import IPython.utils.rlineimpl as readline
1426
1426
1427 self.rl_next_input = None
1427 self.rl_next_input = None
1428 self.rl_do_indent = False
1428 self.rl_do_indent = False
1429
1429
1430 if not self.readline_use or not readline.have_readline:
1430 if not self.readline_use or not readline.have_readline:
1431 self.has_readline = False
1431 self.has_readline = False
1432 self.readline = None
1432 self.readline = None
1433 # Set a number of methods that depend on readline to be no-op
1433 # Set a number of methods that depend on readline to be no-op
1434 self.savehist = no_op
1434 self.savehist = no_op
1435 self.reloadhist = no_op
1435 self.reloadhist = no_op
1436 self.set_completer = no_op
1436 self.set_completer = no_op
1437 self.set_custom_completer = no_op
1437 self.set_custom_completer = no_op
1438 self.set_completer_frame = no_op
1438 self.set_completer_frame = no_op
1439 warn('Readline services not available or not loaded.')
1439 warn('Readline services not available or not loaded.')
1440 else:
1440 else:
1441 self.has_readline = True
1441 self.has_readline = True
1442 self.readline = readline
1442 self.readline = readline
1443 sys.modules['readline'] = readline
1443 sys.modules['readline'] = readline
1444 import atexit
1444 import atexit
1445 from IPython.core.completer import IPCompleter
1445 from IPython.core.completer import IPCompleter
1446 self.Completer = IPCompleter(self,
1446 self.Completer = IPCompleter(self,
1447 self.user_ns,
1447 self.user_ns,
1448 self.user_global_ns,
1448 self.user_global_ns,
1449 self.readline_omit__names,
1449 self.readline_omit__names,
1450 self.alias_manager.alias_table)
1450 self.alias_manager.alias_table)
1451 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1451 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1452 self.strdispatchers['complete_command'] = sdisp
1452 self.strdispatchers['complete_command'] = sdisp
1453 self.Completer.custom_completers = sdisp
1453 self.Completer.custom_completers = sdisp
1454 # Platform-specific configuration
1454 # Platform-specific configuration
1455 if os.name == 'nt':
1455 if os.name == 'nt':
1456 self.readline_startup_hook = readline.set_pre_input_hook
1456 self.readline_startup_hook = readline.set_pre_input_hook
1457 else:
1457 else:
1458 self.readline_startup_hook = readline.set_startup_hook
1458 self.readline_startup_hook = readline.set_startup_hook
1459
1459
1460 # Load user's initrc file (readline config)
1460 # Load user's initrc file (readline config)
1461 # Or if libedit is used, load editrc.
1461 # Or if libedit is used, load editrc.
1462 inputrc_name = os.environ.get('INPUTRC')
1462 inputrc_name = os.environ.get('INPUTRC')
1463 if inputrc_name is None:
1463 if inputrc_name is None:
1464 home_dir = get_home_dir()
1464 home_dir = get_home_dir()
1465 if home_dir is not None:
1465 if home_dir is not None:
1466 inputrc_name = '.inputrc'
1466 inputrc_name = '.inputrc'
1467 if readline.uses_libedit:
1467 if readline.uses_libedit:
1468 inputrc_name = '.editrc'
1468 inputrc_name = '.editrc'
1469 inputrc_name = os.path.join(home_dir, inputrc_name)
1469 inputrc_name = os.path.join(home_dir, inputrc_name)
1470 if os.path.isfile(inputrc_name):
1470 if os.path.isfile(inputrc_name):
1471 try:
1471 try:
1472 readline.read_init_file(inputrc_name)
1472 readline.read_init_file(inputrc_name)
1473 except:
1473 except:
1474 warn('Problems reading readline initialization file <%s>'
1474 warn('Problems reading readline initialization file <%s>'
1475 % inputrc_name)
1475 % inputrc_name)
1476
1476
1477 # save this in sys so embedded copies can restore it properly
1477 # save this in sys so embedded copies can restore it properly
1478 sys.ipcompleter = self.Completer.complete
1478 sys.ipcompleter = self.Completer.complete
1479 self.set_completer()
1479 self.set_completer()
1480
1480
1481 # Configure readline according to user's prefs
1481 # Configure readline according to user's prefs
1482 # This is only done if GNU readline is being used. If libedit
1482 # This is only done if GNU readline is being used. If libedit
1483 # is being used (as on Leopard) the readline config is
1483 # is being used (as on Leopard) the readline config is
1484 # not run as the syntax for libedit is different.
1484 # not run as the syntax for libedit is different.
1485 if not readline.uses_libedit:
1485 if not readline.uses_libedit:
1486 for rlcommand in self.readline_parse_and_bind:
1486 for rlcommand in self.readline_parse_and_bind:
1487 #print "loading rl:",rlcommand # dbg
1487 #print "loading rl:",rlcommand # dbg
1488 readline.parse_and_bind(rlcommand)
1488 readline.parse_and_bind(rlcommand)
1489
1489
1490 # Remove some chars from the delimiters list. If we encounter
1490 # Remove some chars from the delimiters list. If we encounter
1491 # unicode chars, discard them.
1491 # unicode chars, discard them.
1492 delims = readline.get_completer_delims().encode("ascii", "ignore")
1492 delims = readline.get_completer_delims().encode("ascii", "ignore")
1493 delims = delims.translate(string._idmap,
1493 delims = delims.translate(string._idmap,
1494 self.readline_remove_delims)
1494 self.readline_remove_delims)
1495 readline.set_completer_delims(delims)
1495 readline.set_completer_delims(delims)
1496 # otherwise we end up with a monster history after a while:
1496 # otherwise we end up with a monster history after a while:
1497 readline.set_history_length(1000)
1497 readline.set_history_length(1000)
1498 try:
1498 try:
1499 #print '*** Reading readline history' # dbg
1499 #print '*** Reading readline history' # dbg
1500 readline.read_history_file(self.histfile)
1500 readline.read_history_file(self.histfile)
1501 except IOError:
1501 except IOError:
1502 pass # It doesn't exist yet.
1502 pass # It doesn't exist yet.
1503
1503
1504 atexit.register(self.atexit_operations)
1504 atexit.register(self.atexit_operations)
1505 del atexit
1505 del atexit
1506
1506
1507 # Configure auto-indent for all platforms
1507 # Configure auto-indent for all platforms
1508 self.set_autoindent(self.autoindent)
1508 self.set_autoindent(self.autoindent)
1509
1509
1510 def set_next_input(self, s):
1510 def set_next_input(self, s):
1511 """ Sets the 'default' input string for the next command line.
1511 """ Sets the 'default' input string for the next command line.
1512
1512
1513 Requires readline.
1513 Requires readline.
1514
1514
1515 Example:
1515 Example:
1516
1516
1517 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1517 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1518 [D:\ipython]|2> Hello Word_ # cursor is here
1518 [D:\ipython]|2> Hello Word_ # cursor is here
1519 """
1519 """
1520
1520
1521 self.rl_next_input = s
1521 self.rl_next_input = s
1522
1522
1523 # Maybe move this to the terminal subclass?
1523 # Maybe move this to the terminal subclass?
1524 def pre_readline(self):
1524 def pre_readline(self):
1525 """readline hook to be used at the start of each line.
1525 """readline hook to be used at the start of each line.
1526
1526
1527 Currently it handles auto-indent only."""
1527 Currently it handles auto-indent only."""
1528
1528
1529 if self.rl_do_indent:
1529 if self.rl_do_indent:
1530 self.readline.insert_text(self._indent_current_str())
1530 self.readline.insert_text(self._indent_current_str())
1531 if self.rl_next_input is not None:
1531 if self.rl_next_input is not None:
1532 self.readline.insert_text(self.rl_next_input)
1532 self.readline.insert_text(self.rl_next_input)
1533 self.rl_next_input = None
1533 self.rl_next_input = None
1534
1534
1535 def _indent_current_str(self):
1535 def _indent_current_str(self):
1536 """return the current level of indentation as a string"""
1536 """return the current level of indentation as a string"""
1537 return self.indent_current_nsp * ' '
1537 return self.indent_current_nsp * ' '
1538
1538
1539 #-------------------------------------------------------------------------
1539 #-------------------------------------------------------------------------
1540 # Things related to magics
1540 # Things related to magics
1541 #-------------------------------------------------------------------------
1541 #-------------------------------------------------------------------------
1542
1542
1543 def init_magics(self):
1543 def init_magics(self):
1544 # FIXME: Move the color initialization to the DisplayHook, which
1544 # FIXME: Move the color initialization to the DisplayHook, which
1545 # should be split into a prompt manager and displayhook. We probably
1545 # should be split into a prompt manager and displayhook. We probably
1546 # even need a centralize colors management object.
1546 # even need a centralize colors management object.
1547 self.magic_colors(self.colors)
1547 self.magic_colors(self.colors)
1548 # History was moved to a separate module
1548 # History was moved to a separate module
1549 from . import history
1549 from . import history
1550 history.init_ipython(self)
1550 history.init_ipython(self)
1551
1551
1552 def magic(self,arg_s):
1552 def magic(self,arg_s):
1553 """Call a magic function by name.
1553 """Call a magic function by name.
1554
1554
1555 Input: a string containing the name of the magic function to call and any
1555 Input: a string containing the name of the magic function to call and any
1556 additional arguments to be passed to the magic.
1556 additional arguments to be passed to the magic.
1557
1557
1558 magic('name -opt foo bar') is equivalent to typing at the ipython
1558 magic('name -opt foo bar') is equivalent to typing at the ipython
1559 prompt:
1559 prompt:
1560
1560
1561 In[1]: %name -opt foo bar
1561 In[1]: %name -opt foo bar
1562
1562
1563 To call a magic without arguments, simply use magic('name').
1563 To call a magic without arguments, simply use magic('name').
1564
1564
1565 This provides a proper Python function to call IPython's magics in any
1565 This provides a proper Python function to call IPython's magics in any
1566 valid Python code you can type at the interpreter, including loops and
1566 valid Python code you can type at the interpreter, including loops and
1567 compound statements.
1567 compound statements.
1568 """
1568 """
1569 args = arg_s.split(' ',1)
1569 args = arg_s.split(' ',1)
1570 magic_name = args[0]
1570 magic_name = args[0]
1571 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1571 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1572
1572
1573 try:
1573 try:
1574 magic_args = args[1]
1574 magic_args = args[1]
1575 except IndexError:
1575 except IndexError:
1576 magic_args = ''
1576 magic_args = ''
1577 fn = getattr(self,'magic_'+magic_name,None)
1577 fn = getattr(self,'magic_'+magic_name,None)
1578 if fn is None:
1578 if fn is None:
1579 error("Magic function `%s` not found." % magic_name)
1579 error("Magic function `%s` not found." % magic_name)
1580 else:
1580 else:
1581 magic_args = self.var_expand(magic_args,1)
1581 magic_args = self.var_expand(magic_args,1)
1582 with nested(self.builtin_trap,):
1582 with nested(self.builtin_trap,):
1583 result = fn(magic_args)
1583 result = fn(magic_args)
1584 return result
1584 return result
1585
1585
1586 def define_magic(self, magicname, func):
1586 def define_magic(self, magicname, func):
1587 """Expose own function as magic function for ipython
1587 """Expose own function as magic function for ipython
1588
1588
1589 def foo_impl(self,parameter_s=''):
1589 def foo_impl(self,parameter_s=''):
1590 'My very own magic!. (Use docstrings, IPython reads them).'
1590 'My very own magic!. (Use docstrings, IPython reads them).'
1591 print 'Magic function. Passed parameter is between < >:'
1591 print 'Magic function. Passed parameter is between < >:'
1592 print '<%s>' % parameter_s
1592 print '<%s>' % parameter_s
1593 print 'The self object is:',self
1593 print 'The self object is:',self
1594
1594
1595 self.define_magic('foo',foo_impl)
1595 self.define_magic('foo',foo_impl)
1596 """
1596 """
1597
1597
1598 import new
1598 import new
1599 im = new.instancemethod(func,self, self.__class__)
1599 im = new.instancemethod(func,self, self.__class__)
1600 old = getattr(self, "magic_" + magicname, None)
1600 old = getattr(self, "magic_" + magicname, None)
1601 setattr(self, "magic_" + magicname, im)
1601 setattr(self, "magic_" + magicname, im)
1602 return old
1602 return old
1603
1603
1604 #-------------------------------------------------------------------------
1604 #-------------------------------------------------------------------------
1605 # Things related to macros
1605 # Things related to macros
1606 #-------------------------------------------------------------------------
1606 #-------------------------------------------------------------------------
1607
1607
1608 def define_macro(self, name, themacro):
1608 def define_macro(self, name, themacro):
1609 """Define a new macro
1609 """Define a new macro
1610
1610
1611 Parameters
1611 Parameters
1612 ----------
1612 ----------
1613 name : str
1613 name : str
1614 The name of the macro.
1614 The name of the macro.
1615 themacro : str or Macro
1615 themacro : str or Macro
1616 The action to do upon invoking the macro. If a string, a new
1616 The action to do upon invoking the macro. If a string, a new
1617 Macro object is created by passing the string to it.
1617 Macro object is created by passing the string to it.
1618 """
1618 """
1619
1619
1620 from IPython.core import macro
1620 from IPython.core import macro
1621
1621
1622 if isinstance(themacro, basestring):
1622 if isinstance(themacro, basestring):
1623 themacro = macro.Macro(themacro)
1623 themacro = macro.Macro(themacro)
1624 if not isinstance(themacro, macro.Macro):
1624 if not isinstance(themacro, macro.Macro):
1625 raise ValueError('A macro must be a string or a Macro instance.')
1625 raise ValueError('A macro must be a string or a Macro instance.')
1626 self.user_ns[name] = themacro
1626 self.user_ns[name] = themacro
1627
1627
1628 #-------------------------------------------------------------------------
1628 #-------------------------------------------------------------------------
1629 # Things related to the running of system commands
1629 # Things related to the running of system commands
1630 #-------------------------------------------------------------------------
1630 #-------------------------------------------------------------------------
1631
1631
1632 def system(self, cmd):
1632 def system(self, cmd):
1633 """Make a system call, using IPython."""
1633 """Make a system call, using IPython."""
1634 return self.hooks.shell_hook(self.var_expand(cmd, depth=2))
1634 return self.hooks.shell_hook(self.var_expand(cmd, depth=2))
1635
1635
1636 #-------------------------------------------------------------------------
1636 #-------------------------------------------------------------------------
1637 # Things related to aliases
1637 # Things related to aliases
1638 #-------------------------------------------------------------------------
1638 #-------------------------------------------------------------------------
1639
1639
1640 def init_alias(self):
1640 def init_alias(self):
1641 self.alias_manager = AliasManager(shell=self, config=self.config)
1641 self.alias_manager = AliasManager(shell=self, config=self.config)
1642 self.ns_table['alias'] = self.alias_manager.alias_table,
1642 self.ns_table['alias'] = self.alias_manager.alias_table,
1643
1643
1644 #-------------------------------------------------------------------------
1644 #-------------------------------------------------------------------------
1645 # Things related to extensions and plugins
1645 # Things related to extensions and plugins
1646 #-------------------------------------------------------------------------
1646 #-------------------------------------------------------------------------
1647
1647
1648 def init_extension_manager(self):
1648 def init_extension_manager(self):
1649 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1649 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1650
1650
1651 def init_plugin_manager(self):
1651 def init_plugin_manager(self):
1652 self.plugin_manager = PluginManager(config=self.config)
1652 self.plugin_manager = PluginManager(config=self.config)
1653
1653
1654 #-------------------------------------------------------------------------
1654 #-------------------------------------------------------------------------
1655 # Things related to payloads
1655 # Things related to payloads
1656 #-------------------------------------------------------------------------
1656 #-------------------------------------------------------------------------
1657
1657
1658 def init_payload(self):
1658 def init_payload(self):
1659 self.payload_manager = PayloadManager(config=self.config)
1659 self.payload_manager = PayloadManager(config=self.config)
1660
1660
1661 #-------------------------------------------------------------------------
1661 #-------------------------------------------------------------------------
1662 # Things related to the prefilter
1662 # Things related to the prefilter
1663 #-------------------------------------------------------------------------
1663 #-------------------------------------------------------------------------
1664
1664
1665 def init_prefilter(self):
1665 def init_prefilter(self):
1666 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1666 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1667 # Ultimately this will be refactored in the new interpreter code, but
1667 # Ultimately this will be refactored in the new interpreter code, but
1668 # for now, we should expose the main prefilter method (there's legacy
1668 # for now, we should expose the main prefilter method (there's legacy
1669 # code out there that may rely on this).
1669 # code out there that may rely on this).
1670 self.prefilter = self.prefilter_manager.prefilter_lines
1670 self.prefilter = self.prefilter_manager.prefilter_lines
1671
1671
1672 #-------------------------------------------------------------------------
1672 #-------------------------------------------------------------------------
1673 # Things related to the running of code
1673 # Things related to the running of code
1674 #-------------------------------------------------------------------------
1674 #-------------------------------------------------------------------------
1675
1675
1676 def ex(self, cmd):
1676 def ex(self, cmd):
1677 """Execute a normal python statement in user namespace."""
1677 """Execute a normal python statement in user namespace."""
1678 with nested(self.builtin_trap,):
1678 with nested(self.builtin_trap,):
1679 exec cmd in self.user_global_ns, self.user_ns
1679 exec cmd in self.user_global_ns, self.user_ns
1680
1680
1681 def ev(self, expr):
1681 def ev(self, expr):
1682 """Evaluate python expression expr in user namespace.
1682 """Evaluate python expression expr in user namespace.
1683
1683
1684 Returns the result of evaluation
1684 Returns the result of evaluation
1685 """
1685 """
1686 with nested(self.builtin_trap,):
1686 with nested(self.builtin_trap,):
1687 return eval(expr, self.user_global_ns, self.user_ns)
1687 return eval(expr, self.user_global_ns, self.user_ns)
1688
1688
1689 def safe_execfile(self, fname, *where, **kw):
1689 def safe_execfile(self, fname, *where, **kw):
1690 """A safe version of the builtin execfile().
1690 """A safe version of the builtin execfile().
1691
1691
1692 This version will never throw an exception, but instead print
1692 This version will never throw an exception, but instead print
1693 helpful error messages to the screen. This only works on pure
1693 helpful error messages to the screen. This only works on pure
1694 Python files with the .py extension.
1694 Python files with the .py extension.
1695
1695
1696 Parameters
1696 Parameters
1697 ----------
1697 ----------
1698 fname : string
1698 fname : string
1699 The name of the file to be executed.
1699 The name of the file to be executed.
1700 where : tuple
1700 where : tuple
1701 One or two namespaces, passed to execfile() as (globals,locals).
1701 One or two namespaces, passed to execfile() as (globals,locals).
1702 If only one is given, it is passed as both.
1702 If only one is given, it is passed as both.
1703 exit_ignore : bool (False)
1703 exit_ignore : bool (False)
1704 If True, then silence SystemExit for non-zero status (it is always
1704 If True, then silence SystemExit for non-zero status (it is always
1705 silenced for zero status, as it is so common).
1705 silenced for zero status, as it is so common).
1706 """
1706 """
1707 kw.setdefault('exit_ignore', False)
1707 kw.setdefault('exit_ignore', False)
1708
1708
1709 fname = os.path.abspath(os.path.expanduser(fname))
1709 fname = os.path.abspath(os.path.expanduser(fname))
1710
1710
1711 # Make sure we have a .py file
1711 # Make sure we have a .py file
1712 if not fname.endswith('.py'):
1712 if not fname.endswith('.py'):
1713 warn('File must end with .py to be run using execfile: <%s>' % fname)
1713 warn('File must end with .py to be run using execfile: <%s>' % fname)
1714
1714
1715 # Make sure we can open the file
1715 # Make sure we can open the file
1716 try:
1716 try:
1717 with open(fname) as thefile:
1717 with open(fname) as thefile:
1718 pass
1718 pass
1719 except:
1719 except:
1720 warn('Could not open file <%s> for safe execution.' % fname)
1720 warn('Could not open file <%s> for safe execution.' % fname)
1721 return
1721 return
1722
1722
1723 # Find things also in current directory. This is needed to mimic the
1723 # Find things also in current directory. This is needed to mimic the
1724 # behavior of running a script from the system command line, where
1724 # behavior of running a script from the system command line, where
1725 # Python inserts the script's directory into sys.path
1725 # Python inserts the script's directory into sys.path
1726 dname = os.path.dirname(fname)
1726 dname = os.path.dirname(fname)
1727
1727
1728 with prepended_to_syspath(dname):
1728 with prepended_to_syspath(dname):
1729 try:
1729 try:
1730 execfile(fname,*where)
1730 execfile(fname,*where)
1731 except SystemExit, status:
1731 except SystemExit, status:
1732 # If the call was made with 0 or None exit status (sys.exit(0)
1732 # If the call was made with 0 or None exit status (sys.exit(0)
1733 # or sys.exit() ), don't bother showing a traceback, as both of
1733 # or sys.exit() ), don't bother showing a traceback, as both of
1734 # these are considered normal by the OS:
1734 # these are considered normal by the OS:
1735 # > python -c'import sys;sys.exit(0)'; echo $?
1735 # > python -c'import sys;sys.exit(0)'; echo $?
1736 # 0
1736 # 0
1737 # > python -c'import sys;sys.exit()'; echo $?
1737 # > python -c'import sys;sys.exit()'; echo $?
1738 # 0
1738 # 0
1739 # For other exit status, we show the exception unless
1739 # For other exit status, we show the exception unless
1740 # explicitly silenced, but only in short form.
1740 # explicitly silenced, but only in short form.
1741 if status.code not in (0, None) and not kw['exit_ignore']:
1741 if status.code not in (0, None) and not kw['exit_ignore']:
1742 self.showtraceback(exception_only=True)
1742 self.showtraceback(exception_only=True)
1743 except:
1743 except:
1744 self.showtraceback()
1744 self.showtraceback()
1745
1745
1746 def safe_execfile_ipy(self, fname):
1746 def safe_execfile_ipy(self, fname):
1747 """Like safe_execfile, but for .ipy files with IPython syntax.
1747 """Like safe_execfile, but for .ipy files with IPython syntax.
1748
1748
1749 Parameters
1749 Parameters
1750 ----------
1750 ----------
1751 fname : str
1751 fname : str
1752 The name of the file to execute. The filename must have a
1752 The name of the file to execute. The filename must have a
1753 .ipy extension.
1753 .ipy extension.
1754 """
1754 """
1755 fname = os.path.abspath(os.path.expanduser(fname))
1755 fname = os.path.abspath(os.path.expanduser(fname))
1756
1756
1757 # Make sure we have a .py file
1757 # Make sure we have a .py file
1758 if not fname.endswith('.ipy'):
1758 if not fname.endswith('.ipy'):
1759 warn('File must end with .py to be run using execfile: <%s>' % fname)
1759 warn('File must end with .py to be run using execfile: <%s>' % fname)
1760
1760
1761 # Make sure we can open the file
1761 # Make sure we can open the file
1762 try:
1762 try:
1763 with open(fname) as thefile:
1763 with open(fname) as thefile:
1764 pass
1764 pass
1765 except:
1765 except:
1766 warn('Could not open file <%s> for safe execution.' % fname)
1766 warn('Could not open file <%s> for safe execution.' % fname)
1767 return
1767 return
1768
1768
1769 # Find things also in current directory. This is needed to mimic the
1769 # Find things also in current directory. This is needed to mimic the
1770 # behavior of running a script from the system command line, where
1770 # behavior of running a script from the system command line, where
1771 # Python inserts the script's directory into sys.path
1771 # Python inserts the script's directory into sys.path
1772 dname = os.path.dirname(fname)
1772 dname = os.path.dirname(fname)
1773
1773
1774 with prepended_to_syspath(dname):
1774 with prepended_to_syspath(dname):
1775 try:
1775 try:
1776 with open(fname) as thefile:
1776 with open(fname) as thefile:
1777 script = thefile.read()
1777 script = thefile.read()
1778 # self.runlines currently captures all exceptions
1778 # self.runlines currently captures all exceptions
1779 # raise in user code. It would be nice if there were
1779 # raise in user code. It would be nice if there were
1780 # versions of runlines, execfile that did raise, so
1780 # versions of runlines, execfile that did raise, so
1781 # we could catch the errors.
1781 # we could catch the errors.
1782 self.runlines(script, clean=True)
1782 self.runlines(script, clean=True)
1783 except:
1783 except:
1784 self.showtraceback()
1784 self.showtraceback()
1785 warn('Unknown failure executing file: <%s>' % fname)
1785 warn('Unknown failure executing file: <%s>' % fname)
1786
1786
1787 def runlines(self, lines, clean=False):
1787 def runlines(self, lines, clean=False):
1788 """Run a string of one or more lines of source.
1788 """Run a string of one or more lines of source.
1789
1789
1790 This method is capable of running a string containing multiple source
1790 This method is capable of running a string containing multiple source
1791 lines, as if they had been entered at the IPython prompt. Since it
1791 lines, as if they had been entered at the IPython prompt. Since it
1792 exposes IPython's processing machinery, the given strings can contain
1792 exposes IPython's processing machinery, the given strings can contain
1793 magic calls (%magic), special shell access (!cmd), etc.
1793 magic calls (%magic), special shell access (!cmd), etc.
1794 """
1794 """
1795
1795
1796 if isinstance(lines, (list, tuple)):
1796 if isinstance(lines, (list, tuple)):
1797 lines = '\n'.join(lines)
1797 lines = '\n'.join(lines)
1798
1798
1799 if clean:
1799 if clean:
1800 lines = self._cleanup_ipy_script(lines)
1800 lines = self._cleanup_ipy_script(lines)
1801
1801
1802 # We must start with a clean buffer, in case this is run from an
1802 # We must start with a clean buffer, in case this is run from an
1803 # interactive IPython session (via a magic, for example).
1803 # interactive IPython session (via a magic, for example).
1804 self.resetbuffer()
1804 self.resetbuffer()
1805 lines = lines.splitlines()
1805 lines = lines.splitlines()
1806 more = 0
1806 more = 0
1807
1807
1808 with nested(self.builtin_trap, self.display_trap):
1808 with nested(self.builtin_trap, self.display_trap):
1809 for line in lines:
1809 for line in lines:
1810 # skip blank lines so we don't mess up the prompt counter, but do
1810 # skip blank lines so we don't mess up the prompt counter, but do
1811 # NOT skip even a blank line if we are in a code block (more is
1811 # NOT skip even a blank line if we are in a code block (more is
1812 # true)
1812 # true)
1813
1813
1814 if line or more:
1814 if line or more:
1815 # push to raw history, so hist line numbers stay in sync
1815 # push to raw history, so hist line numbers stay in sync
1816 self.input_hist_raw.append("# " + line + "\n")
1816 self.input_hist_raw.append("# " + line + "\n")
1817 prefiltered = self.prefilter_manager.prefilter_lines(line,more)
1817 prefiltered = self.prefilter_manager.prefilter_lines(line,more)
1818 more = self.push_line(prefiltered)
1818 more = self.push_line(prefiltered)
1819 # IPython's runsource returns None if there was an error
1819 # IPython's runsource returns None if there was an error
1820 # compiling the code. This allows us to stop processing right
1820 # compiling the code. This allows us to stop processing right
1821 # away, so the user gets the error message at the right place.
1821 # away, so the user gets the error message at the right place.
1822 if more is None:
1822 if more is None:
1823 break
1823 break
1824 else:
1824 else:
1825 self.input_hist_raw.append("\n")
1825 self.input_hist_raw.append("\n")
1826 # final newline in case the input didn't have it, so that the code
1826 # final newline in case the input didn't have it, so that the code
1827 # actually does get executed
1827 # actually does get executed
1828 if more:
1828 if more:
1829 self.push_line('\n')
1829 self.push_line('\n')
1830
1830
1831 def runsource(self, source, filename='<input>', symbol='single'):
1831 def runsource(self, source, filename='<input>', symbol='single'):
1832 """Compile and run some source in the interpreter.
1832 """Compile and run some source in the interpreter.
1833
1833
1834 Arguments are as for compile_command().
1834 Arguments are as for compile_command().
1835
1835
1836 One several things can happen:
1836 One several things can happen:
1837
1837
1838 1) The input is incorrect; compile_command() raised an
1838 1) The input is incorrect; compile_command() raised an
1839 exception (SyntaxError or OverflowError). A syntax traceback
1839 exception (SyntaxError or OverflowError). A syntax traceback
1840 will be printed by calling the showsyntaxerror() method.
1840 will be printed by calling the showsyntaxerror() method.
1841
1841
1842 2) The input is incomplete, and more input is required;
1842 2) The input is incomplete, and more input is required;
1843 compile_command() returned None. Nothing happens.
1843 compile_command() returned None. Nothing happens.
1844
1844
1845 3) The input is complete; compile_command() returned a code
1845 3) The input is complete; compile_command() returned a code
1846 object. The code is executed by calling self.runcode() (which
1846 object. The code is executed by calling self.runcode() (which
1847 also handles run-time exceptions, except for SystemExit).
1847 also handles run-time exceptions, except for SystemExit).
1848
1848
1849 The return value is:
1849 The return value is:
1850
1850
1851 - True in case 2
1851 - True in case 2
1852
1852
1853 - False in the other cases, unless an exception is raised, where
1853 - False in the other cases, unless an exception is raised, where
1854 None is returned instead. This can be used by external callers to
1854 None is returned instead. This can be used by external callers to
1855 know whether to continue feeding input or not.
1855 know whether to continue feeding input or not.
1856
1856
1857 The return value can be used to decide whether to use sys.ps1 or
1857 The return value can be used to decide whether to use sys.ps1 or
1858 sys.ps2 to prompt the next line."""
1858 sys.ps2 to prompt the next line."""
1859
1859
1860 # if the source code has leading blanks, add 'if 1:\n' to it
1860 # if the source code has leading blanks, add 'if 1:\n' to it
1861 # this allows execution of indented pasted code. It is tempting
1861 # this allows execution of indented pasted code. It is tempting
1862 # to add '\n' at the end of source to run commands like ' a=1'
1862 # to add '\n' at the end of source to run commands like ' a=1'
1863 # directly, but this fails for more complicated scenarios
1863 # directly, but this fails for more complicated scenarios
1864 source=source.encode(self.stdin_encoding)
1864 source=source.encode(self.stdin_encoding)
1865 if source[:1] in [' ', '\t']:
1865 if source[:1] in [' ', '\t']:
1866 source = 'if 1:\n%s' % source
1866 source = 'if 1:\n%s' % source
1867
1867
1868 try:
1868 try:
1869 code = self.compile(source,filename,symbol)
1869 code = self.compile(source,filename,symbol)
1870 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
1870 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
1871 # Case 1
1871 # Case 1
1872 self.showsyntaxerror(filename)
1872 self.showsyntaxerror(filename)
1873 return None
1873 return None
1874
1874
1875 if code is None:
1875 if code is None:
1876 # Case 2
1876 # Case 2
1877 return True
1877 return True
1878
1878
1879 # Case 3
1879 # Case 3
1880 # We store the code object so that threaded shells and
1880 # We store the code object so that threaded shells and
1881 # custom exception handlers can access all this info if needed.
1881 # custom exception handlers can access all this info if needed.
1882 # The source corresponding to this can be obtained from the
1882 # The source corresponding to this can be obtained from the
1883 # buffer attribute as '\n'.join(self.buffer).
1883 # buffer attribute as '\n'.join(self.buffer).
1884 self.code_to_run = code
1884 self.code_to_run = code
1885 # now actually execute the code object
1885 # now actually execute the code object
1886 if self.runcode(code) == 0:
1886 if self.runcode(code) == 0:
1887 return False
1887 return False
1888 else:
1888 else:
1889 return None
1889 return None
1890
1890
1891 def runcode(self,code_obj):
1891 def runcode(self,code_obj):
1892 """Execute a code object.
1892 """Execute a code object.
1893
1893
1894 When an exception occurs, self.showtraceback() is called to display a
1894 When an exception occurs, self.showtraceback() is called to display a
1895 traceback.
1895 traceback.
1896
1896
1897 Return value: a flag indicating whether the code to be run completed
1897 Return value: a flag indicating whether the code to be run completed
1898 successfully:
1898 successfully:
1899
1899
1900 - 0: successful execution.
1900 - 0: successful execution.
1901 - 1: an error occurred.
1901 - 1: an error occurred.
1902 """
1902 """
1903
1903
1904 # Clear the payload before executing new code.
1905 self.payload_manager.clear_payload()
1906
1907 # Set our own excepthook in case the user code tries to call it
1904 # Set our own excepthook in case the user code tries to call it
1908 # directly, so that the IPython crash handler doesn't get triggered
1905 # directly, so that the IPython crash handler doesn't get triggered
1909 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1906 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1910
1907
1911 # we save the original sys.excepthook in the instance, in case config
1908 # we save the original sys.excepthook in the instance, in case config
1912 # code (such as magics) needs access to it.
1909 # code (such as magics) needs access to it.
1913 self.sys_excepthook = old_excepthook
1910 self.sys_excepthook = old_excepthook
1914 outflag = 1 # happens in more places, so it's easier as default
1911 outflag = 1 # happens in more places, so it's easier as default
1915 try:
1912 try:
1916 try:
1913 try:
1917 self.hooks.pre_runcode_hook()
1914 self.hooks.pre_runcode_hook()
1918 exec code_obj in self.user_global_ns, self.user_ns
1915 exec code_obj in self.user_global_ns, self.user_ns
1919 finally:
1916 finally:
1920 # Reset our crash handler in place
1917 # Reset our crash handler in place
1921 sys.excepthook = old_excepthook
1918 sys.excepthook = old_excepthook
1922 except SystemExit:
1919 except SystemExit:
1923 self.resetbuffer()
1920 self.resetbuffer()
1924 self.showtraceback(exception_only=True)
1921 self.showtraceback(exception_only=True)
1925 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
1922 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
1926 except self.custom_exceptions:
1923 except self.custom_exceptions:
1927 etype,value,tb = sys.exc_info()
1924 etype,value,tb = sys.exc_info()
1928 self.CustomTB(etype,value,tb)
1925 self.CustomTB(etype,value,tb)
1929 except:
1926 except:
1930 self.showtraceback()
1927 self.showtraceback()
1931 else:
1928 else:
1932 outflag = 0
1929 outflag = 0
1933 if softspace(sys.stdout, 0):
1930 if softspace(sys.stdout, 0):
1934 print
1931 print
1935 # Flush out code object which has been run (and source)
1932 # Flush out code object which has been run (and source)
1936 self.code_to_run = None
1933 self.code_to_run = None
1937 return outflag
1934 return outflag
1938
1935
1939 def push_line(self, line):
1936 def push_line(self, line):
1940 """Push a line to the interpreter.
1937 """Push a line to the interpreter.
1941
1938
1942 The line should not have a trailing newline; it may have
1939 The line should not have a trailing newline; it may have
1943 internal newlines. The line is appended to a buffer and the
1940 internal newlines. The line is appended to a buffer and the
1944 interpreter's runsource() method is called with the
1941 interpreter's runsource() method is called with the
1945 concatenated contents of the buffer as source. If this
1942 concatenated contents of the buffer as source. If this
1946 indicates that the command was executed or invalid, the buffer
1943 indicates that the command was executed or invalid, the buffer
1947 is reset; otherwise, the command is incomplete, and the buffer
1944 is reset; otherwise, the command is incomplete, and the buffer
1948 is left as it was after the line was appended. The return
1945 is left as it was after the line was appended. The return
1949 value is 1 if more input is required, 0 if the line was dealt
1946 value is 1 if more input is required, 0 if the line was dealt
1950 with in some way (this is the same as runsource()).
1947 with in some way (this is the same as runsource()).
1951 """
1948 """
1952
1949
1953 # autoindent management should be done here, and not in the
1950 # autoindent management should be done here, and not in the
1954 # interactive loop, since that one is only seen by keyboard input. We
1951 # interactive loop, since that one is only seen by keyboard input. We
1955 # need this done correctly even for code run via runlines (which uses
1952 # need this done correctly even for code run via runlines (which uses
1956 # push).
1953 # push).
1957
1954
1958 #print 'push line: <%s>' % line # dbg
1955 #print 'push line: <%s>' % line # dbg
1959 for subline in line.splitlines():
1956 for subline in line.splitlines():
1960 self._autoindent_update(subline)
1957 self._autoindent_update(subline)
1961 self.buffer.append(line)
1958 self.buffer.append(line)
1962 more = self.runsource('\n'.join(self.buffer), self.filename)
1959 more = self.runsource('\n'.join(self.buffer), self.filename)
1963 if not more:
1960 if not more:
1964 self.resetbuffer()
1961 self.resetbuffer()
1965 return more
1962 return more
1966
1963
1967 def resetbuffer(self):
1964 def resetbuffer(self):
1968 """Reset the input buffer."""
1965 """Reset the input buffer."""
1969 self.buffer[:] = []
1966 self.buffer[:] = []
1970
1967
1971 def _is_secondary_block_start(self, s):
1968 def _is_secondary_block_start(self, s):
1972 if not s.endswith(':'):
1969 if not s.endswith(':'):
1973 return False
1970 return False
1974 if (s.startswith('elif') or
1971 if (s.startswith('elif') or
1975 s.startswith('else') or
1972 s.startswith('else') or
1976 s.startswith('except') or
1973 s.startswith('except') or
1977 s.startswith('finally')):
1974 s.startswith('finally')):
1978 return True
1975 return True
1979
1976
1980 def _cleanup_ipy_script(self, script):
1977 def _cleanup_ipy_script(self, script):
1981 """Make a script safe for self.runlines()
1978 """Make a script safe for self.runlines()
1982
1979
1983 Currently, IPython is lines based, with blocks being detected by
1980 Currently, IPython is lines based, with blocks being detected by
1984 empty lines. This is a problem for block based scripts that may
1981 empty lines. This is a problem for block based scripts that may
1985 not have empty lines after blocks. This script adds those empty
1982 not have empty lines after blocks. This script adds those empty
1986 lines to make scripts safe for running in the current line based
1983 lines to make scripts safe for running in the current line based
1987 IPython.
1984 IPython.
1988 """
1985 """
1989 res = []
1986 res = []
1990 lines = script.splitlines()
1987 lines = script.splitlines()
1991 level = 0
1988 level = 0
1992
1989
1993 for l in lines:
1990 for l in lines:
1994 lstripped = l.lstrip()
1991 lstripped = l.lstrip()
1995 stripped = l.strip()
1992 stripped = l.strip()
1996 if not stripped:
1993 if not stripped:
1997 continue
1994 continue
1998 newlevel = len(l) - len(lstripped)
1995 newlevel = len(l) - len(lstripped)
1999 if level > 0 and newlevel == 0 and \
1996 if level > 0 and newlevel == 0 and \
2000 not self._is_secondary_block_start(stripped):
1997 not self._is_secondary_block_start(stripped):
2001 # add empty line
1998 # add empty line
2002 res.append('')
1999 res.append('')
2003 res.append(l)
2000 res.append(l)
2004 level = newlevel
2001 level = newlevel
2005
2002
2006 return '\n'.join(res) + '\n'
2003 return '\n'.join(res) + '\n'
2007
2004
2008 def _autoindent_update(self,line):
2005 def _autoindent_update(self,line):
2009 """Keep track of the indent level."""
2006 """Keep track of the indent level."""
2010
2007
2011 #debugx('line')
2008 #debugx('line')
2012 #debugx('self.indent_current_nsp')
2009 #debugx('self.indent_current_nsp')
2013 if self.autoindent:
2010 if self.autoindent:
2014 if line:
2011 if line:
2015 inisp = num_ini_spaces(line)
2012 inisp = num_ini_spaces(line)
2016 if inisp < self.indent_current_nsp:
2013 if inisp < self.indent_current_nsp:
2017 self.indent_current_nsp = inisp
2014 self.indent_current_nsp = inisp
2018
2015
2019 if line[-1] == ':':
2016 if line[-1] == ':':
2020 self.indent_current_nsp += 4
2017 self.indent_current_nsp += 4
2021 elif dedent_re.match(line):
2018 elif dedent_re.match(line):
2022 self.indent_current_nsp -= 4
2019 self.indent_current_nsp -= 4
2023 else:
2020 else:
2024 self.indent_current_nsp = 0
2021 self.indent_current_nsp = 0
2025
2022
2026 #-------------------------------------------------------------------------
2023 #-------------------------------------------------------------------------
2027 # Things related to GUI support and pylab
2024 # Things related to GUI support and pylab
2028 #-------------------------------------------------------------------------
2025 #-------------------------------------------------------------------------
2029
2026
2030 def enable_pylab(self, gui=None):
2027 def enable_pylab(self, gui=None):
2031 raise NotImplementedError('Implement enable_pylab in a subclass')
2028 raise NotImplementedError('Implement enable_pylab in a subclass')
2032
2029
2033 #-------------------------------------------------------------------------
2030 #-------------------------------------------------------------------------
2034 # Utilities
2031 # Utilities
2035 #-------------------------------------------------------------------------
2032 #-------------------------------------------------------------------------
2036
2033
2037 def getoutput(self, cmd):
2034 def getoutput(self, cmd):
2038 return getoutput(self.var_expand(cmd,depth=2),
2035 return getoutput(self.var_expand(cmd,depth=2),
2039 header=self.system_header,
2036 header=self.system_header,
2040 verbose=self.system_verbose)
2037 verbose=self.system_verbose)
2041
2038
2042 def getoutputerror(self, cmd):
2039 def getoutputerror(self, cmd):
2043 return getoutputerror(self.var_expand(cmd,depth=2),
2040 return getoutputerror(self.var_expand(cmd,depth=2),
2044 header=self.system_header,
2041 header=self.system_header,
2045 verbose=self.system_verbose)
2042 verbose=self.system_verbose)
2046
2043
2047 def var_expand(self,cmd,depth=0):
2044 def var_expand(self,cmd,depth=0):
2048 """Expand python variables in a string.
2045 """Expand python variables in a string.
2049
2046
2050 The depth argument indicates how many frames above the caller should
2047 The depth argument indicates how many frames above the caller should
2051 be walked to look for the local namespace where to expand variables.
2048 be walked to look for the local namespace where to expand variables.
2052
2049
2053 The global namespace for expansion is always the user's interactive
2050 The global namespace for expansion is always the user's interactive
2054 namespace.
2051 namespace.
2055 """
2052 """
2056
2053
2057 return str(ItplNS(cmd,
2054 return str(ItplNS(cmd,
2058 self.user_ns, # globals
2055 self.user_ns, # globals
2059 # Skip our own frame in searching for locals:
2056 # Skip our own frame in searching for locals:
2060 sys._getframe(depth+1).f_locals # locals
2057 sys._getframe(depth+1).f_locals # locals
2061 ))
2058 ))
2062
2059
2063 def mktempfile(self,data=None):
2060 def mktempfile(self,data=None):
2064 """Make a new tempfile and return its filename.
2061 """Make a new tempfile and return its filename.
2065
2062
2066 This makes a call to tempfile.mktemp, but it registers the created
2063 This makes a call to tempfile.mktemp, but it registers the created
2067 filename internally so ipython cleans it up at exit time.
2064 filename internally so ipython cleans it up at exit time.
2068
2065
2069 Optional inputs:
2066 Optional inputs:
2070
2067
2071 - data(None): if data is given, it gets written out to the temp file
2068 - data(None): if data is given, it gets written out to the temp file
2072 immediately, and the file is closed again."""
2069 immediately, and the file is closed again."""
2073
2070
2074 filename = tempfile.mktemp('.py','ipython_edit_')
2071 filename = tempfile.mktemp('.py','ipython_edit_')
2075 self.tempfiles.append(filename)
2072 self.tempfiles.append(filename)
2076
2073
2077 if data:
2074 if data:
2078 tmp_file = open(filename,'w')
2075 tmp_file = open(filename,'w')
2079 tmp_file.write(data)
2076 tmp_file.write(data)
2080 tmp_file.close()
2077 tmp_file.close()
2081 return filename
2078 return filename
2082
2079
2083 # TODO: This should be removed when Term is refactored.
2080 # TODO: This should be removed when Term is refactored.
2084 def write(self,data):
2081 def write(self,data):
2085 """Write a string to the default output"""
2082 """Write a string to the default output"""
2086 IPython.utils.io.Term.cout.write(data)
2083 IPython.utils.io.Term.cout.write(data)
2087
2084
2088 # TODO: This should be removed when Term is refactored.
2085 # TODO: This should be removed when Term is refactored.
2089 def write_err(self,data):
2086 def write_err(self,data):
2090 """Write a string to the default error output"""
2087 """Write a string to the default error output"""
2091 IPython.utils.io.Term.cerr.write(data)
2088 IPython.utils.io.Term.cerr.write(data)
2092
2089
2093 def ask_yes_no(self,prompt,default=True):
2090 def ask_yes_no(self,prompt,default=True):
2094 if self.quiet:
2091 if self.quiet:
2095 return True
2092 return True
2096 return ask_yes_no(prompt,default)
2093 return ask_yes_no(prompt,default)
2097
2094
2098 #-------------------------------------------------------------------------
2095 #-------------------------------------------------------------------------
2099 # Things related to IPython exiting
2096 # Things related to IPython exiting
2100 #-------------------------------------------------------------------------
2097 #-------------------------------------------------------------------------
2101
2098
2102 def atexit_operations(self):
2099 def atexit_operations(self):
2103 """This will be executed at the time of exit.
2100 """This will be executed at the time of exit.
2104
2101
2105 Saving of persistent data should be performed here.
2102 Saving of persistent data should be performed here.
2106 """
2103 """
2107 self.savehist()
2104 self.savehist()
2108
2105
2109 # Cleanup all tempfiles left around
2106 # Cleanup all tempfiles left around
2110 for tfile in self.tempfiles:
2107 for tfile in self.tempfiles:
2111 try:
2108 try:
2112 os.unlink(tfile)
2109 os.unlink(tfile)
2113 except OSError:
2110 except OSError:
2114 pass
2111 pass
2115
2112
2116 # Clear all user namespaces to release all references cleanly.
2113 # Clear all user namespaces to release all references cleanly.
2117 self.reset()
2114 self.reset()
2118
2115
2119 # Run user hooks
2116 # Run user hooks
2120 self.hooks.shutdown_hook()
2117 self.hooks.shutdown_hook()
2121
2118
2122 def cleanup(self):
2119 def cleanup(self):
2123 self.restore_sys_module_state()
2120 self.restore_sys_module_state()
2124
2121
2125
2122
2126 class InteractiveShellABC(object):
2123 class InteractiveShellABC(object):
2127 """An abstract base class for InteractiveShell."""
2124 """An abstract base class for InteractiveShell."""
2128 __metaclass__ = abc.ABCMeta
2125 __metaclass__ = abc.ABCMeta
2129
2126
2130 InteractiveShellABC.register(InteractiveShell)
2127 InteractiveShellABC.register(InteractiveShell)
@@ -1,3652 +1,3652
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-2007 Fernando Perez <fperez@colorado.edu>
7 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
8 # Copyright (C) 2008-2009 The IPython Development Team
8 # Copyright (C) 2008-2009 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
17
18 import __builtin__
18 import __builtin__
19 import __future__
19 import __future__
20 import bdb
20 import bdb
21 import inspect
21 import inspect
22 import os
22 import os
23 import sys
23 import sys
24 import shutil
24 import shutil
25 import re
25 import re
26 import time
26 import time
27 import textwrap
27 import textwrap
28 import types
28 import types
29 from cStringIO import StringIO
29 from cStringIO import StringIO
30 from getopt import getopt,GetoptError
30 from getopt import getopt,GetoptError
31 from pprint import pformat
31 from pprint import pformat
32
32
33 # cProfile was added in Python2.5
33 # cProfile was added in Python2.5
34 try:
34 try:
35 import cProfile as profile
35 import cProfile as profile
36 import pstats
36 import pstats
37 except ImportError:
37 except ImportError:
38 # profile isn't bundled by default in Debian for license reasons
38 # profile isn't bundled by default in Debian for license reasons
39 try:
39 try:
40 import profile,pstats
40 import profile,pstats
41 except ImportError:
41 except ImportError:
42 profile = pstats = None
42 profile = pstats = None
43
43
44 # print_function was added to __future__ in Python2.6, remove this when we drop
44 # print_function was added to __future__ in Python2.6, remove this when we drop
45 # 2.5 compatibility
45 # 2.5 compatibility
46 if not hasattr(__future__,'CO_FUTURE_PRINT_FUNCTION'):
46 if not hasattr(__future__,'CO_FUTURE_PRINT_FUNCTION'):
47 __future__.CO_FUTURE_PRINT_FUNCTION = 65536
47 __future__.CO_FUTURE_PRINT_FUNCTION = 65536
48
48
49 import IPython
49 import IPython
50 from IPython.core import debugger, oinspect
50 from IPython.core import debugger, oinspect
51 from IPython.core.error import TryNext
51 from IPython.core.error import TryNext
52 from IPython.core.error import UsageError
52 from IPython.core.error import UsageError
53 from IPython.core.fakemodule import FakeModule
53 from IPython.core.fakemodule import FakeModule
54 from IPython.core.macro import Macro
54 from IPython.core.macro import Macro
55 from IPython.core.page import page
55 from IPython.core import page
56 from IPython.core.prefilter import ESC_MAGIC
56 from IPython.core.prefilter import ESC_MAGIC
57 from IPython.lib.pylabtools import mpl_runner
57 from IPython.lib.pylabtools import mpl_runner
58 from IPython.lib.inputhook import enable_gui
58 from IPython.lib.inputhook import enable_gui
59 from IPython.external.Itpl import itpl, printpl
59 from IPython.external.Itpl import itpl, printpl
60 from IPython.testing import decorators as testdec
60 from IPython.testing import decorators as testdec
61 from IPython.utils.io import file_read, nlprint
61 from IPython.utils.io import file_read, nlprint
62 import IPython.utils.io
62 import IPython.utils.io
63 from IPython.utils.path import get_py_filename
63 from IPython.utils.path import get_py_filename
64 from IPython.utils.process import arg_split, abbrev_cwd
64 from IPython.utils.process import arg_split, abbrev_cwd
65 from IPython.utils.terminal import set_term_title
65 from IPython.utils.terminal import set_term_title
66 from IPython.utils.text import LSString, SList, StringTypes
66 from IPython.utils.text import LSString, SList, StringTypes
67 from IPython.utils.timing import clock, clock2
67 from IPython.utils.timing import clock, clock2
68 from IPython.utils.warn import warn, error
68 from IPython.utils.warn import warn, error
69 from IPython.utils.ipstruct import Struct
69 from IPython.utils.ipstruct import Struct
70 import IPython.utils.generics
70 import IPython.utils.generics
71
71
72 #-----------------------------------------------------------------------------
72 #-----------------------------------------------------------------------------
73 # Utility functions
73 # Utility functions
74 #-----------------------------------------------------------------------------
74 #-----------------------------------------------------------------------------
75
75
76 def on_off(tag):
76 def on_off(tag):
77 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
77 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
78 return ['OFF','ON'][tag]
78 return ['OFF','ON'][tag]
79
79
80 class Bunch: pass
80 class Bunch: pass
81
81
82 def compress_dhist(dh):
82 def compress_dhist(dh):
83 head, tail = dh[:-10], dh[-10:]
83 head, tail = dh[:-10], dh[-10:]
84
84
85 newhead = []
85 newhead = []
86 done = set()
86 done = set()
87 for h in head:
87 for h in head:
88 if h in done:
88 if h in done:
89 continue
89 continue
90 newhead.append(h)
90 newhead.append(h)
91 done.add(h)
91 done.add(h)
92
92
93 return newhead + tail
93 return newhead + tail
94
94
95
95
96 #***************************************************************************
96 #***************************************************************************
97 # Main class implementing Magic functionality
97 # Main class implementing Magic functionality
98
98
99 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
99 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
100 # on construction of the main InteractiveShell object. Something odd is going
100 # on construction of the main InteractiveShell object. Something odd is going
101 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
101 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
102 # eventually this needs to be clarified.
102 # eventually this needs to be clarified.
103 # BG: This is because InteractiveShell inherits from this, but is itself a
103 # BG: This is because InteractiveShell inherits from this, but is itself a
104 # Configurable. This messes up the MRO in some way. The fix is that we need to
104 # Configurable. This messes up the MRO in some way. The fix is that we need to
105 # make Magic a configurable that InteractiveShell does not subclass.
105 # make Magic a configurable that InteractiveShell does not subclass.
106
106
107 class Magic:
107 class Magic:
108 """Magic functions for InteractiveShell.
108 """Magic functions for InteractiveShell.
109
109
110 Shell functions which can be reached as %function_name. All magic
110 Shell functions which can be reached as %function_name. All magic
111 functions should accept a string, which they can parse for their own
111 functions should accept a string, which they can parse for their own
112 needs. This can make some functions easier to type, eg `%cd ../`
112 needs. This can make some functions easier to type, eg `%cd ../`
113 vs. `%cd("../")`
113 vs. `%cd("../")`
114
114
115 ALL definitions MUST begin with the prefix magic_. The user won't need it
115 ALL definitions MUST begin with the prefix magic_. The user won't need it
116 at the command line, but it is is needed in the definition. """
116 at the command line, but it is is needed in the definition. """
117
117
118 # class globals
118 # class globals
119 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
119 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
120 'Automagic is ON, % prefix NOT needed for magic functions.']
120 'Automagic is ON, % prefix NOT needed for magic functions.']
121
121
122 #......................................................................
122 #......................................................................
123 # some utility functions
123 # some utility functions
124
124
125 def __init__(self,shell):
125 def __init__(self,shell):
126
126
127 self.options_table = {}
127 self.options_table = {}
128 if profile is None:
128 if profile is None:
129 self.magic_prun = self.profile_missing_notice
129 self.magic_prun = self.profile_missing_notice
130 self.shell = shell
130 self.shell = shell
131
131
132 # namespace for holding state we may need
132 # namespace for holding state we may need
133 self._magic_state = Bunch()
133 self._magic_state = Bunch()
134
134
135 def profile_missing_notice(self, *args, **kwargs):
135 def profile_missing_notice(self, *args, **kwargs):
136 error("""\
136 error("""\
137 The profile module could not be found. It has been removed from the standard
137 The profile module could not be found. It has been removed from the standard
138 python packages because of its non-free license. To use profiling, install the
138 python packages because of its non-free license. To use profiling, install the
139 python-profiler package from non-free.""")
139 python-profiler package from non-free.""")
140
140
141 def default_option(self,fn,optstr):
141 def default_option(self,fn,optstr):
142 """Make an entry in the options_table for fn, with value optstr"""
142 """Make an entry in the options_table for fn, with value optstr"""
143
143
144 if fn not in self.lsmagic():
144 if fn not in self.lsmagic():
145 error("%s is not a magic function" % fn)
145 error("%s is not a magic function" % fn)
146 self.options_table[fn] = optstr
146 self.options_table[fn] = optstr
147
147
148 def lsmagic(self):
148 def lsmagic(self):
149 """Return a list of currently available magic functions.
149 """Return a list of currently available magic functions.
150
150
151 Gives a list of the bare names after mangling (['ls','cd', ...], not
151 Gives a list of the bare names after mangling (['ls','cd', ...], not
152 ['magic_ls','magic_cd',...]"""
152 ['magic_ls','magic_cd',...]"""
153
153
154 # FIXME. This needs a cleanup, in the way the magics list is built.
154 # FIXME. This needs a cleanup, in the way the magics list is built.
155
155
156 # magics in class definition
156 # magics in class definition
157 class_magic = lambda fn: fn.startswith('magic_') and \
157 class_magic = lambda fn: fn.startswith('magic_') and \
158 callable(Magic.__dict__[fn])
158 callable(Magic.__dict__[fn])
159 # in instance namespace (run-time user additions)
159 # in instance namespace (run-time user additions)
160 inst_magic = lambda fn: fn.startswith('magic_') and \
160 inst_magic = lambda fn: fn.startswith('magic_') and \
161 callable(self.__dict__[fn])
161 callable(self.__dict__[fn])
162 # and bound magics by user (so they can access self):
162 # and bound magics by user (so they can access self):
163 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
163 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
164 callable(self.__class__.__dict__[fn])
164 callable(self.__class__.__dict__[fn])
165 magics = filter(class_magic,Magic.__dict__.keys()) + \
165 magics = filter(class_magic,Magic.__dict__.keys()) + \
166 filter(inst_magic,self.__dict__.keys()) + \
166 filter(inst_magic,self.__dict__.keys()) + \
167 filter(inst_bound_magic,self.__class__.__dict__.keys())
167 filter(inst_bound_magic,self.__class__.__dict__.keys())
168 out = []
168 out = []
169 for fn in set(magics):
169 for fn in set(magics):
170 out.append(fn.replace('magic_','',1))
170 out.append(fn.replace('magic_','',1))
171 out.sort()
171 out.sort()
172 return out
172 return out
173
173
174 def extract_input_slices(self,slices,raw=False):
174 def extract_input_slices(self,slices,raw=False):
175 """Return as a string a set of input history slices.
175 """Return as a string a set of input history slices.
176
176
177 Inputs:
177 Inputs:
178
178
179 - slices: the set of slices is given as a list of strings (like
179 - slices: the set of slices is given as a list of strings (like
180 ['1','4:8','9'], since this function is for use by magic functions
180 ['1','4:8','9'], since this function is for use by magic functions
181 which get their arguments as strings.
181 which get their arguments as strings.
182
182
183 Optional inputs:
183 Optional inputs:
184
184
185 - raw(False): by default, the processed input is used. If this is
185 - raw(False): by default, the processed input is used. If this is
186 true, the raw input history is used instead.
186 true, the raw input history is used instead.
187
187
188 Note that slices can be called with two notations:
188 Note that slices can be called with two notations:
189
189
190 N:M -> standard python form, means including items N...(M-1).
190 N:M -> standard python form, means including items N...(M-1).
191
191
192 N-M -> include items N..M (closed endpoint)."""
192 N-M -> include items N..M (closed endpoint)."""
193
193
194 if raw:
194 if raw:
195 hist = self.shell.input_hist_raw
195 hist = self.shell.input_hist_raw
196 else:
196 else:
197 hist = self.shell.input_hist
197 hist = self.shell.input_hist
198
198
199 cmds = []
199 cmds = []
200 for chunk in slices:
200 for chunk in slices:
201 if ':' in chunk:
201 if ':' in chunk:
202 ini,fin = map(int,chunk.split(':'))
202 ini,fin = map(int,chunk.split(':'))
203 elif '-' in chunk:
203 elif '-' in chunk:
204 ini,fin = map(int,chunk.split('-'))
204 ini,fin = map(int,chunk.split('-'))
205 fin += 1
205 fin += 1
206 else:
206 else:
207 ini = int(chunk)
207 ini = int(chunk)
208 fin = ini+1
208 fin = ini+1
209 cmds.append(hist[ini:fin])
209 cmds.append(hist[ini:fin])
210 return cmds
210 return cmds
211
211
212 def _ofind(self, oname, namespaces=None):
212 def _ofind(self, oname, namespaces=None):
213 """Find an object in the available namespaces.
213 """Find an object in the available namespaces.
214
214
215 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
215 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
216
216
217 Has special code to detect magic functions.
217 Has special code to detect magic functions.
218 """
218 """
219 oname = oname.strip()
219 oname = oname.strip()
220 alias_ns = None
220 alias_ns = None
221 if namespaces is None:
221 if namespaces is None:
222 # Namespaces to search in:
222 # Namespaces to search in:
223 # Put them in a list. The order is important so that we
223 # Put them in a list. The order is important so that we
224 # find things in the same order that Python finds them.
224 # find things in the same order that Python finds them.
225 namespaces = [ ('Interactive', self.shell.user_ns),
225 namespaces = [ ('Interactive', self.shell.user_ns),
226 ('IPython internal', self.shell.internal_ns),
226 ('IPython internal', self.shell.internal_ns),
227 ('Python builtin', __builtin__.__dict__),
227 ('Python builtin', __builtin__.__dict__),
228 ('Alias', self.shell.alias_manager.alias_table),
228 ('Alias', self.shell.alias_manager.alias_table),
229 ]
229 ]
230 alias_ns = self.shell.alias_manager.alias_table
230 alias_ns = self.shell.alias_manager.alias_table
231
231
232 # initialize results to 'null'
232 # initialize results to 'null'
233 found = False; obj = None; ospace = None; ds = None;
233 found = False; obj = None; ospace = None; ds = None;
234 ismagic = False; isalias = False; parent = None
234 ismagic = False; isalias = False; parent = None
235
235
236 # We need to special-case 'print', which as of python2.6 registers as a
236 # We need to special-case 'print', which as of python2.6 registers as a
237 # function but should only be treated as one if print_function was
237 # function but should only be treated as one if print_function was
238 # loaded with a future import. In this case, just bail.
238 # loaded with a future import. In this case, just bail.
239 if (oname == 'print' and not (self.shell.compile.compiler.flags &
239 if (oname == 'print' and not (self.shell.compile.compiler.flags &
240 __future__.CO_FUTURE_PRINT_FUNCTION)):
240 __future__.CO_FUTURE_PRINT_FUNCTION)):
241 return {'found':found, 'obj':obj, 'namespace':ospace,
241 return {'found':found, 'obj':obj, 'namespace':ospace,
242 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
242 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
243
243
244 # Look for the given name by splitting it in parts. If the head is
244 # Look for the given name by splitting it in parts. If the head is
245 # found, then we look for all the remaining parts as members, and only
245 # found, then we look for all the remaining parts as members, and only
246 # declare success if we can find them all.
246 # declare success if we can find them all.
247 oname_parts = oname.split('.')
247 oname_parts = oname.split('.')
248 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
248 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
249 for nsname,ns in namespaces:
249 for nsname,ns in namespaces:
250 try:
250 try:
251 obj = ns[oname_head]
251 obj = ns[oname_head]
252 except KeyError:
252 except KeyError:
253 continue
253 continue
254 else:
254 else:
255 #print 'oname_rest:', oname_rest # dbg
255 #print 'oname_rest:', oname_rest # dbg
256 for part in oname_rest:
256 for part in oname_rest:
257 try:
257 try:
258 parent = obj
258 parent = obj
259 obj = getattr(obj,part)
259 obj = getattr(obj,part)
260 except:
260 except:
261 # Blanket except b/c some badly implemented objects
261 # Blanket except b/c some badly implemented objects
262 # allow __getattr__ to raise exceptions other than
262 # allow __getattr__ to raise exceptions other than
263 # AttributeError, which then crashes IPython.
263 # AttributeError, which then crashes IPython.
264 break
264 break
265 else:
265 else:
266 # If we finish the for loop (no break), we got all members
266 # If we finish the for loop (no break), we got all members
267 found = True
267 found = True
268 ospace = nsname
268 ospace = nsname
269 if ns == alias_ns:
269 if ns == alias_ns:
270 isalias = True
270 isalias = True
271 break # namespace loop
271 break # namespace loop
272
272
273 # Try to see if it's magic
273 # Try to see if it's magic
274 if not found:
274 if not found:
275 if oname.startswith(ESC_MAGIC):
275 if oname.startswith(ESC_MAGIC):
276 oname = oname[1:]
276 oname = oname[1:]
277 obj = getattr(self,'magic_'+oname,None)
277 obj = getattr(self,'magic_'+oname,None)
278 if obj is not None:
278 if obj is not None:
279 found = True
279 found = True
280 ospace = 'IPython internal'
280 ospace = 'IPython internal'
281 ismagic = True
281 ismagic = True
282
282
283 # Last try: special-case some literals like '', [], {}, etc:
283 # Last try: special-case some literals like '', [], {}, etc:
284 if not found and oname_head in ["''",'""','[]','{}','()']:
284 if not found and oname_head in ["''",'""','[]','{}','()']:
285 obj = eval(oname_head)
285 obj = eval(oname_head)
286 found = True
286 found = True
287 ospace = 'Interactive'
287 ospace = 'Interactive'
288
288
289 return {'found':found, 'obj':obj, 'namespace':ospace,
289 return {'found':found, 'obj':obj, 'namespace':ospace,
290 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
290 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
291
291
292 def arg_err(self,func):
292 def arg_err(self,func):
293 """Print docstring if incorrect arguments were passed"""
293 """Print docstring if incorrect arguments were passed"""
294 print 'Error in arguments:'
294 print 'Error in arguments:'
295 print oinspect.getdoc(func)
295 print oinspect.getdoc(func)
296
296
297 def format_latex(self,strng):
297 def format_latex(self,strng):
298 """Format a string for latex inclusion."""
298 """Format a string for latex inclusion."""
299
299
300 # Characters that need to be escaped for latex:
300 # Characters that need to be escaped for latex:
301 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
301 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
302 # Magic command names as headers:
302 # Magic command names as headers:
303 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
303 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
304 re.MULTILINE)
304 re.MULTILINE)
305 # Magic commands
305 # Magic commands
306 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
306 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
307 re.MULTILINE)
307 re.MULTILINE)
308 # Paragraph continue
308 # Paragraph continue
309 par_re = re.compile(r'\\$',re.MULTILINE)
309 par_re = re.compile(r'\\$',re.MULTILINE)
310
310
311 # The "\n" symbol
311 # The "\n" symbol
312 newline_re = re.compile(r'\\n')
312 newline_re = re.compile(r'\\n')
313
313
314 # Now build the string for output:
314 # Now build the string for output:
315 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
315 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
316 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
316 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
317 strng)
317 strng)
318 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
318 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
319 strng = par_re.sub(r'\\\\',strng)
319 strng = par_re.sub(r'\\\\',strng)
320 strng = escape_re.sub(r'\\\1',strng)
320 strng = escape_re.sub(r'\\\1',strng)
321 strng = newline_re.sub(r'\\textbackslash{}n',strng)
321 strng = newline_re.sub(r'\\textbackslash{}n',strng)
322 return strng
322 return strng
323
323
324 def format_screen(self,strng):
324 def format_screen(self,strng):
325 """Format a string for screen printing.
325 """Format a string for screen printing.
326
326
327 This removes some latex-type format codes."""
327 This removes some latex-type format codes."""
328 # Paragraph continue
328 # Paragraph continue
329 par_re = re.compile(r'\\$',re.MULTILINE)
329 par_re = re.compile(r'\\$',re.MULTILINE)
330 strng = par_re.sub('',strng)
330 strng = par_re.sub('',strng)
331 return strng
331 return strng
332
332
333 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
333 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
334 """Parse options passed to an argument string.
334 """Parse options passed to an argument string.
335
335
336 The interface is similar to that of getopt(), but it returns back a
336 The interface is similar to that of getopt(), but it returns back a
337 Struct with the options as keys and the stripped argument string still
337 Struct with the options as keys and the stripped argument string still
338 as a string.
338 as a string.
339
339
340 arg_str is quoted as a true sys.argv vector by using shlex.split.
340 arg_str is quoted as a true sys.argv vector by using shlex.split.
341 This allows us to easily expand variables, glob files, quote
341 This allows us to easily expand variables, glob files, quote
342 arguments, etc.
342 arguments, etc.
343
343
344 Options:
344 Options:
345 -mode: default 'string'. If given as 'list', the argument string is
345 -mode: default 'string'. If given as 'list', the argument string is
346 returned as a list (split on whitespace) instead of a string.
346 returned as a list (split on whitespace) instead of a string.
347
347
348 -list_all: put all option values in lists. Normally only options
348 -list_all: put all option values in lists. Normally only options
349 appearing more than once are put in a list.
349 appearing more than once are put in a list.
350
350
351 -posix (True): whether to split the input line in POSIX mode or not,
351 -posix (True): whether to split the input line in POSIX mode or not,
352 as per the conventions outlined in the shlex module from the
352 as per the conventions outlined in the shlex module from the
353 standard library."""
353 standard library."""
354
354
355 # inject default options at the beginning of the input line
355 # inject default options at the beginning of the input line
356 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
356 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
357 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
357 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
358
358
359 mode = kw.get('mode','string')
359 mode = kw.get('mode','string')
360 if mode not in ['string','list']:
360 if mode not in ['string','list']:
361 raise ValueError,'incorrect mode given: %s' % mode
361 raise ValueError,'incorrect mode given: %s' % mode
362 # Get options
362 # Get options
363 list_all = kw.get('list_all',0)
363 list_all = kw.get('list_all',0)
364 posix = kw.get('posix', os.name == 'posix')
364 posix = kw.get('posix', os.name == 'posix')
365
365
366 # Check if we have more than one argument to warrant extra processing:
366 # Check if we have more than one argument to warrant extra processing:
367 odict = {} # Dictionary with options
367 odict = {} # Dictionary with options
368 args = arg_str.split()
368 args = arg_str.split()
369 if len(args) >= 1:
369 if len(args) >= 1:
370 # If the list of inputs only has 0 or 1 thing in it, there's no
370 # If the list of inputs only has 0 or 1 thing in it, there's no
371 # need to look for options
371 # need to look for options
372 argv = arg_split(arg_str,posix)
372 argv = arg_split(arg_str,posix)
373 # Do regular option processing
373 # Do regular option processing
374 try:
374 try:
375 opts,args = getopt(argv,opt_str,*long_opts)
375 opts,args = getopt(argv,opt_str,*long_opts)
376 except GetoptError,e:
376 except GetoptError,e:
377 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
377 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
378 " ".join(long_opts)))
378 " ".join(long_opts)))
379 for o,a in opts:
379 for o,a in opts:
380 if o.startswith('--'):
380 if o.startswith('--'):
381 o = o[2:]
381 o = o[2:]
382 else:
382 else:
383 o = o[1:]
383 o = o[1:]
384 try:
384 try:
385 odict[o].append(a)
385 odict[o].append(a)
386 except AttributeError:
386 except AttributeError:
387 odict[o] = [odict[o],a]
387 odict[o] = [odict[o],a]
388 except KeyError:
388 except KeyError:
389 if list_all:
389 if list_all:
390 odict[o] = [a]
390 odict[o] = [a]
391 else:
391 else:
392 odict[o] = a
392 odict[o] = a
393
393
394 # Prepare opts,args for return
394 # Prepare opts,args for return
395 opts = Struct(odict)
395 opts = Struct(odict)
396 if mode == 'string':
396 if mode == 'string':
397 args = ' '.join(args)
397 args = ' '.join(args)
398
398
399 return opts,args
399 return opts,args
400
400
401 #......................................................................
401 #......................................................................
402 # And now the actual magic functions
402 # And now the actual magic functions
403
403
404 # Functions for IPython shell work (vars,funcs, config, etc)
404 # Functions for IPython shell work (vars,funcs, config, etc)
405 def magic_lsmagic(self, parameter_s = ''):
405 def magic_lsmagic(self, parameter_s = ''):
406 """List currently available magic functions."""
406 """List currently available magic functions."""
407 mesc = ESC_MAGIC
407 mesc = ESC_MAGIC
408 print 'Available magic functions:\n'+mesc+\
408 print 'Available magic functions:\n'+mesc+\
409 (' '+mesc).join(self.lsmagic())
409 (' '+mesc).join(self.lsmagic())
410 print '\n' + Magic.auto_status[self.shell.automagic]
410 print '\n' + Magic.auto_status[self.shell.automagic]
411 return None
411 return None
412
412
413 def magic_magic(self, parameter_s = ''):
413 def magic_magic(self, parameter_s = ''):
414 """Print information about the magic function system.
414 """Print information about the magic function system.
415
415
416 Supported formats: -latex, -brief, -rest
416 Supported formats: -latex, -brief, -rest
417 """
417 """
418
418
419 mode = ''
419 mode = ''
420 try:
420 try:
421 if parameter_s.split()[0] == '-latex':
421 if parameter_s.split()[0] == '-latex':
422 mode = 'latex'
422 mode = 'latex'
423 if parameter_s.split()[0] == '-brief':
423 if parameter_s.split()[0] == '-brief':
424 mode = 'brief'
424 mode = 'brief'
425 if parameter_s.split()[0] == '-rest':
425 if parameter_s.split()[0] == '-rest':
426 mode = 'rest'
426 mode = 'rest'
427 rest_docs = []
427 rest_docs = []
428 except:
428 except:
429 pass
429 pass
430
430
431 magic_docs = []
431 magic_docs = []
432 for fname in self.lsmagic():
432 for fname in self.lsmagic():
433 mname = 'magic_' + fname
433 mname = 'magic_' + fname
434 for space in (Magic,self,self.__class__):
434 for space in (Magic,self,self.__class__):
435 try:
435 try:
436 fn = space.__dict__[mname]
436 fn = space.__dict__[mname]
437 except KeyError:
437 except KeyError:
438 pass
438 pass
439 else:
439 else:
440 break
440 break
441 if mode == 'brief':
441 if mode == 'brief':
442 # only first line
442 # only first line
443 if fn.__doc__:
443 if fn.__doc__:
444 fndoc = fn.__doc__.split('\n',1)[0]
444 fndoc = fn.__doc__.split('\n',1)[0]
445 else:
445 else:
446 fndoc = 'No documentation'
446 fndoc = 'No documentation'
447 else:
447 else:
448 if fn.__doc__:
448 if fn.__doc__:
449 fndoc = fn.__doc__.rstrip()
449 fndoc = fn.__doc__.rstrip()
450 else:
450 else:
451 fndoc = 'No documentation'
451 fndoc = 'No documentation'
452
452
453
453
454 if mode == 'rest':
454 if mode == 'rest':
455 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
455 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
456 fname,fndoc))
456 fname,fndoc))
457
457
458 else:
458 else:
459 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
459 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
460 fname,fndoc))
460 fname,fndoc))
461
461
462 magic_docs = ''.join(magic_docs)
462 magic_docs = ''.join(magic_docs)
463
463
464 if mode == 'rest':
464 if mode == 'rest':
465 return "".join(rest_docs)
465 return "".join(rest_docs)
466
466
467 if mode == 'latex':
467 if mode == 'latex':
468 print self.format_latex(magic_docs)
468 print self.format_latex(magic_docs)
469 return
469 return
470 else:
470 else:
471 magic_docs = self.format_screen(magic_docs)
471 magic_docs = self.format_screen(magic_docs)
472 if mode == 'brief':
472 if mode == 'brief':
473 return magic_docs
473 return magic_docs
474
474
475 outmsg = """
475 outmsg = """
476 IPython's 'magic' functions
476 IPython's 'magic' functions
477 ===========================
477 ===========================
478
478
479 The magic function system provides a series of functions which allow you to
479 The magic function system provides a series of functions which allow you to
480 control the behavior of IPython itself, plus a lot of system-type
480 control the behavior of IPython itself, plus a lot of system-type
481 features. All these functions are prefixed with a % character, but parameters
481 features. All these functions are prefixed with a % character, but parameters
482 are given without parentheses or quotes.
482 are given without parentheses or quotes.
483
483
484 NOTE: If you have 'automagic' enabled (via the command line option or with the
484 NOTE: If you have 'automagic' enabled (via the command line option or with the
485 %automagic function), you don't need to type in the % explicitly. By default,
485 %automagic function), you don't need to type in the % explicitly. By default,
486 IPython ships with automagic on, so you should only rarely need the % escape.
486 IPython ships with automagic on, so you should only rarely need the % escape.
487
487
488 Example: typing '%cd mydir' (without the quotes) changes you working directory
488 Example: typing '%cd mydir' (without the quotes) changes you working directory
489 to 'mydir', if it exists.
489 to 'mydir', if it exists.
490
490
491 You can define your own magic functions to extend the system. See the supplied
491 You can define your own magic functions to extend the system. See the supplied
492 ipythonrc and example-magic.py files for details (in your ipython
492 ipythonrc and example-magic.py files for details (in your ipython
493 configuration directory, typically $HOME/.ipython/).
493 configuration directory, typically $HOME/.ipython/).
494
494
495 You can also define your own aliased names for magic functions. In your
495 You can also define your own aliased names for magic functions. In your
496 ipythonrc file, placing a line like:
496 ipythonrc file, placing a line like:
497
497
498 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
498 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
499
499
500 will define %pf as a new name for %profile.
500 will define %pf as a new name for %profile.
501
501
502 You can also call magics in code using the magic() function, which IPython
502 You can also call magics in code using the magic() function, which IPython
503 automatically adds to the builtin namespace. Type 'magic?' for details.
503 automatically adds to the builtin namespace. Type 'magic?' for details.
504
504
505 For a list of the available magic functions, use %lsmagic. For a description
505 For a list of the available magic functions, use %lsmagic. For a description
506 of any of them, type %magic_name?, e.g. '%cd?'.
506 of any of them, type %magic_name?, e.g. '%cd?'.
507
507
508 Currently the magic system has the following functions:\n"""
508 Currently the magic system has the following functions:\n"""
509
509
510 mesc = ESC_MAGIC
510 mesc = ESC_MAGIC
511 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
511 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
512 "\n\n%s%s\n\n%s" % (outmsg,
512 "\n\n%s%s\n\n%s" % (outmsg,
513 magic_docs,mesc,mesc,
513 magic_docs,mesc,mesc,
514 (' '+mesc).join(self.lsmagic()),
514 (' '+mesc).join(self.lsmagic()),
515 Magic.auto_status[self.shell.automagic] ) )
515 Magic.auto_status[self.shell.automagic] ) )
516
516
517 page(outmsg,screen_lines=self.shell.usable_screen_length)
517 page.page(outmsg,screen_lines=self.shell.usable_screen_length)
518
518
519
519
520 def magic_autoindent(self, parameter_s = ''):
520 def magic_autoindent(self, parameter_s = ''):
521 """Toggle autoindent on/off (if available)."""
521 """Toggle autoindent on/off (if available)."""
522
522
523 self.shell.set_autoindent()
523 self.shell.set_autoindent()
524 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
524 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
525
525
526
526
527 def magic_automagic(self, parameter_s = ''):
527 def magic_automagic(self, parameter_s = ''):
528 """Make magic functions callable without having to type the initial %.
528 """Make magic functions callable without having to type the initial %.
529
529
530 Without argumentsl toggles on/off (when off, you must call it as
530 Without argumentsl toggles on/off (when off, you must call it as
531 %automagic, of course). With arguments it sets the value, and you can
531 %automagic, of course). With arguments it sets the value, and you can
532 use any of (case insensitive):
532 use any of (case insensitive):
533
533
534 - on,1,True: to activate
534 - on,1,True: to activate
535
535
536 - off,0,False: to deactivate.
536 - off,0,False: to deactivate.
537
537
538 Note that magic functions have lowest priority, so if there's a
538 Note that magic functions have lowest priority, so if there's a
539 variable whose name collides with that of a magic fn, automagic won't
539 variable whose name collides with that of a magic fn, automagic won't
540 work for that function (you get the variable instead). However, if you
540 work for that function (you get the variable instead). However, if you
541 delete the variable (del var), the previously shadowed magic function
541 delete the variable (del var), the previously shadowed magic function
542 becomes visible to automagic again."""
542 becomes visible to automagic again."""
543
543
544 arg = parameter_s.lower()
544 arg = parameter_s.lower()
545 if parameter_s in ('on','1','true'):
545 if parameter_s in ('on','1','true'):
546 self.shell.automagic = True
546 self.shell.automagic = True
547 elif parameter_s in ('off','0','false'):
547 elif parameter_s in ('off','0','false'):
548 self.shell.automagic = False
548 self.shell.automagic = False
549 else:
549 else:
550 self.shell.automagic = not self.shell.automagic
550 self.shell.automagic = not self.shell.automagic
551 print '\n' + Magic.auto_status[self.shell.automagic]
551 print '\n' + Magic.auto_status[self.shell.automagic]
552
552
553 @testdec.skip_doctest
553 @testdec.skip_doctest
554 def magic_autocall(self, parameter_s = ''):
554 def magic_autocall(self, parameter_s = ''):
555 """Make functions callable without having to type parentheses.
555 """Make functions callable without having to type parentheses.
556
556
557 Usage:
557 Usage:
558
558
559 %autocall [mode]
559 %autocall [mode]
560
560
561 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
561 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
562 value is toggled on and off (remembering the previous state).
562 value is toggled on and off (remembering the previous state).
563
563
564 In more detail, these values mean:
564 In more detail, these values mean:
565
565
566 0 -> fully disabled
566 0 -> fully disabled
567
567
568 1 -> active, but do not apply if there are no arguments on the line.
568 1 -> active, but do not apply if there are no arguments on the line.
569
569
570 In this mode, you get:
570 In this mode, you get:
571
571
572 In [1]: callable
572 In [1]: callable
573 Out[1]: <built-in function callable>
573 Out[1]: <built-in function callable>
574
574
575 In [2]: callable 'hello'
575 In [2]: callable 'hello'
576 ------> callable('hello')
576 ------> callable('hello')
577 Out[2]: False
577 Out[2]: False
578
578
579 2 -> Active always. Even if no arguments are present, the callable
579 2 -> Active always. Even if no arguments are present, the callable
580 object is called:
580 object is called:
581
581
582 In [2]: float
582 In [2]: float
583 ------> float()
583 ------> float()
584 Out[2]: 0.0
584 Out[2]: 0.0
585
585
586 Note that even with autocall off, you can still use '/' at the start of
586 Note that even with autocall off, you can still use '/' at the start of
587 a line to treat the first argument on the command line as a function
587 a line to treat the first argument on the command line as a function
588 and add parentheses to it:
588 and add parentheses to it:
589
589
590 In [8]: /str 43
590 In [8]: /str 43
591 ------> str(43)
591 ------> str(43)
592 Out[8]: '43'
592 Out[8]: '43'
593
593
594 # all-random (note for auto-testing)
594 # all-random (note for auto-testing)
595 """
595 """
596
596
597 if parameter_s:
597 if parameter_s:
598 arg = int(parameter_s)
598 arg = int(parameter_s)
599 else:
599 else:
600 arg = 'toggle'
600 arg = 'toggle'
601
601
602 if not arg in (0,1,2,'toggle'):
602 if not arg in (0,1,2,'toggle'):
603 error('Valid modes: (0->Off, 1->Smart, 2->Full')
603 error('Valid modes: (0->Off, 1->Smart, 2->Full')
604 return
604 return
605
605
606 if arg in (0,1,2):
606 if arg in (0,1,2):
607 self.shell.autocall = arg
607 self.shell.autocall = arg
608 else: # toggle
608 else: # toggle
609 if self.shell.autocall:
609 if self.shell.autocall:
610 self._magic_state.autocall_save = self.shell.autocall
610 self._magic_state.autocall_save = self.shell.autocall
611 self.shell.autocall = 0
611 self.shell.autocall = 0
612 else:
612 else:
613 try:
613 try:
614 self.shell.autocall = self._magic_state.autocall_save
614 self.shell.autocall = self._magic_state.autocall_save
615 except AttributeError:
615 except AttributeError:
616 self.shell.autocall = self._magic_state.autocall_save = 1
616 self.shell.autocall = self._magic_state.autocall_save = 1
617
617
618 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
618 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
619
619
620 def magic_system_verbose(self, parameter_s = ''):
620 def magic_system_verbose(self, parameter_s = ''):
621 """Set verbose printing of system calls.
621 """Set verbose printing of system calls.
622
622
623 If called without an argument, act as a toggle"""
623 If called without an argument, act as a toggle"""
624
624
625 if parameter_s:
625 if parameter_s:
626 val = bool(eval(parameter_s))
626 val = bool(eval(parameter_s))
627 else:
627 else:
628 val = None
628 val = None
629
629
630 if self.shell.system_verbose:
630 if self.shell.system_verbose:
631 self.shell.system_verbose = False
631 self.shell.system_verbose = False
632 else:
632 else:
633 self.shell.system_verbose = True
633 self.shell.system_verbose = True
634 print "System verbose printing is:",\
634 print "System verbose printing is:",\
635 ['OFF','ON'][self.shell.system_verbose]
635 ['OFF','ON'][self.shell.system_verbose]
636
636
637
637
638 def magic_page(self, parameter_s=''):
638 def magic_page(self, parameter_s=''):
639 """Pretty print the object and display it through a pager.
639 """Pretty print the object and display it through a pager.
640
640
641 %page [options] OBJECT
641 %page [options] OBJECT
642
642
643 If no object is given, use _ (last output).
643 If no object is given, use _ (last output).
644
644
645 Options:
645 Options:
646
646
647 -r: page str(object), don't pretty-print it."""
647 -r: page str(object), don't pretty-print it."""
648
648
649 # After a function contributed by Olivier Aubert, slightly modified.
649 # After a function contributed by Olivier Aubert, slightly modified.
650
650
651 # Process options/args
651 # Process options/args
652 opts,args = self.parse_options(parameter_s,'r')
652 opts,args = self.parse_options(parameter_s,'r')
653 raw = 'r' in opts
653 raw = 'r' in opts
654
654
655 oname = args and args or '_'
655 oname = args and args or '_'
656 info = self._ofind(oname)
656 info = self._ofind(oname)
657 if info['found']:
657 if info['found']:
658 txt = (raw and str or pformat)( info['obj'] )
658 txt = (raw and str or pformat)( info['obj'] )
659 page(txt)
659 page.page(txt)
660 else:
660 else:
661 print 'Object `%s` not found' % oname
661 print 'Object `%s` not found' % oname
662
662
663 def magic_profile(self, parameter_s=''):
663 def magic_profile(self, parameter_s=''):
664 """Print your currently active IPython profile."""
664 """Print your currently active IPython profile."""
665 if self.shell.profile:
665 if self.shell.profile:
666 printpl('Current IPython profile: $self.shell.profile.')
666 printpl('Current IPython profile: $self.shell.profile.')
667 else:
667 else:
668 print 'No profile active.'
668 print 'No profile active.'
669
669
670 def magic_pinfo(self, parameter_s='', namespaces=None):
670 def magic_pinfo(self, parameter_s='', namespaces=None):
671 """Provide detailed information about an object.
671 """Provide detailed information about an object.
672
672
673 '%pinfo object' is just a synonym for object? or ?object."""
673 '%pinfo object' is just a synonym for object? or ?object."""
674
674
675 #print 'pinfo par: <%s>' % parameter_s # dbg
675 #print 'pinfo par: <%s>' % parameter_s # dbg
676
676
677
677
678 # detail_level: 0 -> obj? , 1 -> obj??
678 # detail_level: 0 -> obj? , 1 -> obj??
679 detail_level = 0
679 detail_level = 0
680 # We need to detect if we got called as 'pinfo pinfo foo', which can
680 # We need to detect if we got called as 'pinfo pinfo foo', which can
681 # happen if the user types 'pinfo foo?' at the cmd line.
681 # happen if the user types 'pinfo foo?' at the cmd line.
682 pinfo,qmark1,oname,qmark2 = \
682 pinfo,qmark1,oname,qmark2 = \
683 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
683 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
684 if pinfo or qmark1 or qmark2:
684 if pinfo or qmark1 or qmark2:
685 detail_level = 1
685 detail_level = 1
686 if "*" in oname:
686 if "*" in oname:
687 self.magic_psearch(oname)
687 self.magic_psearch(oname)
688 else:
688 else:
689 self._inspect('pinfo', oname, detail_level=detail_level,
689 self._inspect('pinfo', oname, detail_level=detail_level,
690 namespaces=namespaces)
690 namespaces=namespaces)
691
691
692 def magic_pdef(self, parameter_s='', namespaces=None):
692 def magic_pdef(self, parameter_s='', namespaces=None):
693 """Print the definition header for any callable object.
693 """Print the definition header for any callable object.
694
694
695 If the object is a class, print the constructor information."""
695 If the object is a class, print the constructor information."""
696 self._inspect('pdef',parameter_s, namespaces)
696 self._inspect('pdef',parameter_s, namespaces)
697
697
698 def magic_pdoc(self, parameter_s='', namespaces=None):
698 def magic_pdoc(self, parameter_s='', namespaces=None):
699 """Print the docstring for an object.
699 """Print the docstring for an object.
700
700
701 If the given object is a class, it will print both the class and the
701 If the given object is a class, it will print both the class and the
702 constructor docstrings."""
702 constructor docstrings."""
703 self._inspect('pdoc',parameter_s, namespaces)
703 self._inspect('pdoc',parameter_s, namespaces)
704
704
705 def magic_psource(self, parameter_s='', namespaces=None):
705 def magic_psource(self, parameter_s='', namespaces=None):
706 """Print (or run through pager) the source code for an object."""
706 """Print (or run through pager) the source code for an object."""
707 self._inspect('psource',parameter_s, namespaces)
707 self._inspect('psource',parameter_s, namespaces)
708
708
709 def magic_pfile(self, parameter_s=''):
709 def magic_pfile(self, parameter_s=''):
710 """Print (or run through pager) the file where an object is defined.
710 """Print (or run through pager) the file where an object is defined.
711
711
712 The file opens at the line where the object definition begins. IPython
712 The file opens at the line where the object definition begins. IPython
713 will honor the environment variable PAGER if set, and otherwise will
713 will honor the environment variable PAGER if set, and otherwise will
714 do its best to print the file in a convenient form.
714 do its best to print the file in a convenient form.
715
715
716 If the given argument is not an object currently defined, IPython will
716 If the given argument is not an object currently defined, IPython will
717 try to interpret it as a filename (automatically adding a .py extension
717 try to interpret it as a filename (automatically adding a .py extension
718 if needed). You can thus use %pfile as a syntax highlighting code
718 if needed). You can thus use %pfile as a syntax highlighting code
719 viewer."""
719 viewer."""
720
720
721 # first interpret argument as an object name
721 # first interpret argument as an object name
722 out = self._inspect('pfile',parameter_s)
722 out = self._inspect('pfile',parameter_s)
723 # if not, try the input as a filename
723 # if not, try the input as a filename
724 if out == 'not found':
724 if out == 'not found':
725 try:
725 try:
726 filename = get_py_filename(parameter_s)
726 filename = get_py_filename(parameter_s)
727 except IOError,msg:
727 except IOError,msg:
728 print msg
728 print msg
729 return
729 return
730 page(self.shell.inspector.format(file(filename).read()))
730 page.page(self.shell.inspector.format(file(filename).read()))
731
731
732 def _inspect(self,meth,oname,namespaces=None,**kw):
732 def _inspect(self,meth,oname,namespaces=None,**kw):
733 """Generic interface to the inspector system.
733 """Generic interface to the inspector system.
734
734
735 This function is meant to be called by pdef, pdoc & friends."""
735 This function is meant to be called by pdef, pdoc & friends."""
736
736
737 #oname = oname.strip()
737 #oname = oname.strip()
738 #print '1- oname: <%r>' % oname # dbg
738 #print '1- oname: <%r>' % oname # dbg
739 try:
739 try:
740 oname = oname.strip().encode('ascii')
740 oname = oname.strip().encode('ascii')
741 #print '2- oname: <%r>' % oname # dbg
741 #print '2- oname: <%r>' % oname # dbg
742 except UnicodeEncodeError:
742 except UnicodeEncodeError:
743 print 'Python identifiers can only contain ascii characters.'
743 print 'Python identifiers can only contain ascii characters.'
744 return 'not found'
744 return 'not found'
745
745
746 info = Struct(self._ofind(oname, namespaces))
746 info = Struct(self._ofind(oname, namespaces))
747
747
748 if info.found:
748 if info.found:
749 try:
749 try:
750 IPython.utils.generics.inspect_object(info.obj)
750 IPython.utils.generics.inspect_object(info.obj)
751 return
751 return
752 except TryNext:
752 except TryNext:
753 pass
753 pass
754 # Get the docstring of the class property if it exists.
754 # Get the docstring of the class property if it exists.
755 path = oname.split('.')
755 path = oname.split('.')
756 root = '.'.join(path[:-1])
756 root = '.'.join(path[:-1])
757 if info.parent is not None:
757 if info.parent is not None:
758 try:
758 try:
759 target = getattr(info.parent, '__class__')
759 target = getattr(info.parent, '__class__')
760 # The object belongs to a class instance.
760 # The object belongs to a class instance.
761 try:
761 try:
762 target = getattr(target, path[-1])
762 target = getattr(target, path[-1])
763 # The class defines the object.
763 # The class defines the object.
764 if isinstance(target, property):
764 if isinstance(target, property):
765 oname = root + '.__class__.' + path[-1]
765 oname = root + '.__class__.' + path[-1]
766 info = Struct(self._ofind(oname))
766 info = Struct(self._ofind(oname))
767 except AttributeError: pass
767 except AttributeError: pass
768 except AttributeError: pass
768 except AttributeError: pass
769
769
770 pmethod = getattr(self.shell.inspector,meth)
770 pmethod = getattr(self.shell.inspector,meth)
771 formatter = info.ismagic and self.format_screen or None
771 formatter = info.ismagic and self.format_screen or None
772 if meth == 'pdoc':
772 if meth == 'pdoc':
773 pmethod(info.obj,oname,formatter)
773 pmethod(info.obj,oname,formatter)
774 elif meth == 'pinfo':
774 elif meth == 'pinfo':
775 pmethod(info.obj,oname,formatter,info,**kw)
775 pmethod(info.obj,oname,formatter,info,**kw)
776 else:
776 else:
777 pmethod(info.obj,oname)
777 pmethod(info.obj,oname)
778 else:
778 else:
779 print 'Object `%s` not found.' % oname
779 print 'Object `%s` not found.' % oname
780 return 'not found' # so callers can take other action
780 return 'not found' # so callers can take other action
781
781
782 def magic_psearch(self, parameter_s=''):
782 def magic_psearch(self, parameter_s=''):
783 """Search for object in namespaces by wildcard.
783 """Search for object in namespaces by wildcard.
784
784
785 %psearch [options] PATTERN [OBJECT TYPE]
785 %psearch [options] PATTERN [OBJECT TYPE]
786
786
787 Note: ? can be used as a synonym for %psearch, at the beginning or at
787 Note: ? can be used as a synonym for %psearch, at the beginning or at
788 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
788 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
789 rest of the command line must be unchanged (options come first), so
789 rest of the command line must be unchanged (options come first), so
790 for example the following forms are equivalent
790 for example the following forms are equivalent
791
791
792 %psearch -i a* function
792 %psearch -i a* function
793 -i a* function?
793 -i a* function?
794 ?-i a* function
794 ?-i a* function
795
795
796 Arguments:
796 Arguments:
797
797
798 PATTERN
798 PATTERN
799
799
800 where PATTERN is a string containing * as a wildcard similar to its
800 where PATTERN is a string containing * as a wildcard similar to its
801 use in a shell. The pattern is matched in all namespaces on the
801 use in a shell. The pattern is matched in all namespaces on the
802 search path. By default objects starting with a single _ are not
802 search path. By default objects starting with a single _ are not
803 matched, many IPython generated objects have a single
803 matched, many IPython generated objects have a single
804 underscore. The default is case insensitive matching. Matching is
804 underscore. The default is case insensitive matching. Matching is
805 also done on the attributes of objects and not only on the objects
805 also done on the attributes of objects and not only on the objects
806 in a module.
806 in a module.
807
807
808 [OBJECT TYPE]
808 [OBJECT TYPE]
809
809
810 Is the name of a python type from the types module. The name is
810 Is the name of a python type from the types module. The name is
811 given in lowercase without the ending type, ex. StringType is
811 given in lowercase without the ending type, ex. StringType is
812 written string. By adding a type here only objects matching the
812 written string. By adding a type here only objects matching the
813 given type are matched. Using all here makes the pattern match all
813 given type are matched. Using all here makes the pattern match all
814 types (this is the default).
814 types (this is the default).
815
815
816 Options:
816 Options:
817
817
818 -a: makes the pattern match even objects whose names start with a
818 -a: makes the pattern match even objects whose names start with a
819 single underscore. These names are normally ommitted from the
819 single underscore. These names are normally ommitted from the
820 search.
820 search.
821
821
822 -i/-c: make the pattern case insensitive/sensitive. If neither of
822 -i/-c: make the pattern case insensitive/sensitive. If neither of
823 these options is given, the default is read from your ipythonrc
823 these options is given, the default is read from your ipythonrc
824 file. The option name which sets this value is
824 file. The option name which sets this value is
825 'wildcards_case_sensitive'. If this option is not specified in your
825 'wildcards_case_sensitive'. If this option is not specified in your
826 ipythonrc file, IPython's internal default is to do a case sensitive
826 ipythonrc file, IPython's internal default is to do a case sensitive
827 search.
827 search.
828
828
829 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
829 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
830 specifiy can be searched in any of the following namespaces:
830 specifiy can be searched in any of the following namespaces:
831 'builtin', 'user', 'user_global','internal', 'alias', where
831 'builtin', 'user', 'user_global','internal', 'alias', where
832 'builtin' and 'user' are the search defaults. Note that you should
832 'builtin' and 'user' are the search defaults. Note that you should
833 not use quotes when specifying namespaces.
833 not use quotes when specifying namespaces.
834
834
835 'Builtin' contains the python module builtin, 'user' contains all
835 'Builtin' contains the python module builtin, 'user' contains all
836 user data, 'alias' only contain the shell aliases and no python
836 user data, 'alias' only contain the shell aliases and no python
837 objects, 'internal' contains objects used by IPython. The
837 objects, 'internal' contains objects used by IPython. The
838 'user_global' namespace is only used by embedded IPython instances,
838 'user_global' namespace is only used by embedded IPython instances,
839 and it contains module-level globals. You can add namespaces to the
839 and it contains module-level globals. You can add namespaces to the
840 search with -s or exclude them with -e (these options can be given
840 search with -s or exclude them with -e (these options can be given
841 more than once).
841 more than once).
842
842
843 Examples:
843 Examples:
844
844
845 %psearch a* -> objects beginning with an a
845 %psearch a* -> objects beginning with an a
846 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
846 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
847 %psearch a* function -> all functions beginning with an a
847 %psearch a* function -> all functions beginning with an a
848 %psearch re.e* -> objects beginning with an e in module re
848 %psearch re.e* -> objects beginning with an e in module re
849 %psearch r*.e* -> objects that start with e in modules starting in r
849 %psearch r*.e* -> objects that start with e in modules starting in r
850 %psearch r*.* string -> all strings in modules beginning with r
850 %psearch r*.* string -> all strings in modules beginning with r
851
851
852 Case sensitve search:
852 Case sensitve search:
853
853
854 %psearch -c a* list all object beginning with lower case a
854 %psearch -c a* list all object beginning with lower case a
855
855
856 Show objects beginning with a single _:
856 Show objects beginning with a single _:
857
857
858 %psearch -a _* list objects beginning with a single underscore"""
858 %psearch -a _* list objects beginning with a single underscore"""
859 try:
859 try:
860 parameter_s = parameter_s.encode('ascii')
860 parameter_s = parameter_s.encode('ascii')
861 except UnicodeEncodeError:
861 except UnicodeEncodeError:
862 print 'Python identifiers can only contain ascii characters.'
862 print 'Python identifiers can only contain ascii characters.'
863 return
863 return
864
864
865 # default namespaces to be searched
865 # default namespaces to be searched
866 def_search = ['user','builtin']
866 def_search = ['user','builtin']
867
867
868 # Process options/args
868 # Process options/args
869 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
869 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
870 opt = opts.get
870 opt = opts.get
871 shell = self.shell
871 shell = self.shell
872 psearch = shell.inspector.psearch
872 psearch = shell.inspector.psearch
873
873
874 # select case options
874 # select case options
875 if opts.has_key('i'):
875 if opts.has_key('i'):
876 ignore_case = True
876 ignore_case = True
877 elif opts.has_key('c'):
877 elif opts.has_key('c'):
878 ignore_case = False
878 ignore_case = False
879 else:
879 else:
880 ignore_case = not shell.wildcards_case_sensitive
880 ignore_case = not shell.wildcards_case_sensitive
881
881
882 # Build list of namespaces to search from user options
882 # Build list of namespaces to search from user options
883 def_search.extend(opt('s',[]))
883 def_search.extend(opt('s',[]))
884 ns_exclude = ns_exclude=opt('e',[])
884 ns_exclude = ns_exclude=opt('e',[])
885 ns_search = [nm for nm in def_search if nm not in ns_exclude]
885 ns_search = [nm for nm in def_search if nm not in ns_exclude]
886
886
887 # Call the actual search
887 # Call the actual search
888 try:
888 try:
889 psearch(args,shell.ns_table,ns_search,
889 psearch(args,shell.ns_table,ns_search,
890 show_all=opt('a'),ignore_case=ignore_case)
890 show_all=opt('a'),ignore_case=ignore_case)
891 except:
891 except:
892 shell.showtraceback()
892 shell.showtraceback()
893
893
894 def magic_who_ls(self, parameter_s=''):
894 def magic_who_ls(self, parameter_s=''):
895 """Return a sorted list of all interactive variables.
895 """Return a sorted list of all interactive variables.
896
896
897 If arguments are given, only variables of types matching these
897 If arguments are given, only variables of types matching these
898 arguments are returned."""
898 arguments are returned."""
899
899
900 user_ns = self.shell.user_ns
900 user_ns = self.shell.user_ns
901 internal_ns = self.shell.internal_ns
901 internal_ns = self.shell.internal_ns
902 user_ns_hidden = self.shell.user_ns_hidden
902 user_ns_hidden = self.shell.user_ns_hidden
903 out = [ i for i in user_ns
903 out = [ i for i in user_ns
904 if not i.startswith('_') \
904 if not i.startswith('_') \
905 and not (i in internal_ns or i in user_ns_hidden) ]
905 and not (i in internal_ns or i in user_ns_hidden) ]
906
906
907 typelist = parameter_s.split()
907 typelist = parameter_s.split()
908 if typelist:
908 if typelist:
909 typeset = set(typelist)
909 typeset = set(typelist)
910 out = [i for i in out if type(i).__name__ in typeset]
910 out = [i for i in out if type(i).__name__ in typeset]
911
911
912 out.sort()
912 out.sort()
913 return out
913 return out
914
914
915 def magic_who(self, parameter_s=''):
915 def magic_who(self, parameter_s=''):
916 """Print all interactive variables, with some minimal formatting.
916 """Print all interactive variables, with some minimal formatting.
917
917
918 If any arguments are given, only variables whose type matches one of
918 If any arguments are given, only variables whose type matches one of
919 these are printed. For example:
919 these are printed. For example:
920
920
921 %who function str
921 %who function str
922
922
923 will only list functions and strings, excluding all other types of
923 will only list functions and strings, excluding all other types of
924 variables. To find the proper type names, simply use type(var) at a
924 variables. To find the proper type names, simply use type(var) at a
925 command line to see how python prints type names. For example:
925 command line to see how python prints type names. For example:
926
926
927 In [1]: type('hello')\\
927 In [1]: type('hello')\\
928 Out[1]: <type 'str'>
928 Out[1]: <type 'str'>
929
929
930 indicates that the type name for strings is 'str'.
930 indicates that the type name for strings is 'str'.
931
931
932 %who always excludes executed names loaded through your configuration
932 %who always excludes executed names loaded through your configuration
933 file and things which are internal to IPython.
933 file and things which are internal to IPython.
934
934
935 This is deliberate, as typically you may load many modules and the
935 This is deliberate, as typically you may load many modules and the
936 purpose of %who is to show you only what you've manually defined."""
936 purpose of %who is to show you only what you've manually defined."""
937
937
938 varlist = self.magic_who_ls(parameter_s)
938 varlist = self.magic_who_ls(parameter_s)
939 if not varlist:
939 if not varlist:
940 if parameter_s:
940 if parameter_s:
941 print 'No variables match your requested type.'
941 print 'No variables match your requested type.'
942 else:
942 else:
943 print 'Interactive namespace is empty.'
943 print 'Interactive namespace is empty.'
944 return
944 return
945
945
946 # if we have variables, move on...
946 # if we have variables, move on...
947 count = 0
947 count = 0
948 for i in varlist:
948 for i in varlist:
949 print i+'\t',
949 print i+'\t',
950 count += 1
950 count += 1
951 if count > 8:
951 if count > 8:
952 count = 0
952 count = 0
953 print
953 print
954 print
954 print
955
955
956 def magic_whos(self, parameter_s=''):
956 def magic_whos(self, parameter_s=''):
957 """Like %who, but gives some extra information about each variable.
957 """Like %who, but gives some extra information about each variable.
958
958
959 The same type filtering of %who can be applied here.
959 The same type filtering of %who can be applied here.
960
960
961 For all variables, the type is printed. Additionally it prints:
961 For all variables, the type is printed. Additionally it prints:
962
962
963 - For {},[],(): their length.
963 - For {},[],(): their length.
964
964
965 - For numpy and Numeric arrays, a summary with shape, number of
965 - For numpy and Numeric arrays, a summary with shape, number of
966 elements, typecode and size in memory.
966 elements, typecode and size in memory.
967
967
968 - Everything else: a string representation, snipping their middle if
968 - Everything else: a string representation, snipping their middle if
969 too long."""
969 too long."""
970
970
971 varnames = self.magic_who_ls(parameter_s)
971 varnames = self.magic_who_ls(parameter_s)
972 if not varnames:
972 if not varnames:
973 if parameter_s:
973 if parameter_s:
974 print 'No variables match your requested type.'
974 print 'No variables match your requested type.'
975 else:
975 else:
976 print 'Interactive namespace is empty.'
976 print 'Interactive namespace is empty.'
977 return
977 return
978
978
979 # if we have variables, move on...
979 # if we have variables, move on...
980
980
981 # for these types, show len() instead of data:
981 # for these types, show len() instead of data:
982 seq_types = [types.DictType,types.ListType,types.TupleType]
982 seq_types = [types.DictType,types.ListType,types.TupleType]
983
983
984 # for numpy/Numeric arrays, display summary info
984 # for numpy/Numeric arrays, display summary info
985 try:
985 try:
986 import numpy
986 import numpy
987 except ImportError:
987 except ImportError:
988 ndarray_type = None
988 ndarray_type = None
989 else:
989 else:
990 ndarray_type = numpy.ndarray.__name__
990 ndarray_type = numpy.ndarray.__name__
991 try:
991 try:
992 import Numeric
992 import Numeric
993 except ImportError:
993 except ImportError:
994 array_type = None
994 array_type = None
995 else:
995 else:
996 array_type = Numeric.ArrayType.__name__
996 array_type = Numeric.ArrayType.__name__
997
997
998 # Find all variable names and types so we can figure out column sizes
998 # Find all variable names and types so we can figure out column sizes
999 def get_vars(i):
999 def get_vars(i):
1000 return self.shell.user_ns[i]
1000 return self.shell.user_ns[i]
1001
1001
1002 # some types are well known and can be shorter
1002 # some types are well known and can be shorter
1003 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
1003 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
1004 def type_name(v):
1004 def type_name(v):
1005 tn = type(v).__name__
1005 tn = type(v).__name__
1006 return abbrevs.get(tn,tn)
1006 return abbrevs.get(tn,tn)
1007
1007
1008 varlist = map(get_vars,varnames)
1008 varlist = map(get_vars,varnames)
1009
1009
1010 typelist = []
1010 typelist = []
1011 for vv in varlist:
1011 for vv in varlist:
1012 tt = type_name(vv)
1012 tt = type_name(vv)
1013
1013
1014 if tt=='instance':
1014 if tt=='instance':
1015 typelist.append( abbrevs.get(str(vv.__class__),
1015 typelist.append( abbrevs.get(str(vv.__class__),
1016 str(vv.__class__)))
1016 str(vv.__class__)))
1017 else:
1017 else:
1018 typelist.append(tt)
1018 typelist.append(tt)
1019
1019
1020 # column labels and # of spaces as separator
1020 # column labels and # of spaces as separator
1021 varlabel = 'Variable'
1021 varlabel = 'Variable'
1022 typelabel = 'Type'
1022 typelabel = 'Type'
1023 datalabel = 'Data/Info'
1023 datalabel = 'Data/Info'
1024 colsep = 3
1024 colsep = 3
1025 # variable format strings
1025 # variable format strings
1026 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1026 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1027 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1027 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1028 aformat = "%s: %s elems, type `%s`, %s bytes"
1028 aformat = "%s: %s elems, type `%s`, %s bytes"
1029 # find the size of the columns to format the output nicely
1029 # find the size of the columns to format the output nicely
1030 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1030 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1031 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1031 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1032 # table header
1032 # table header
1033 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1033 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1034 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1034 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1035 # and the table itself
1035 # and the table itself
1036 kb = 1024
1036 kb = 1024
1037 Mb = 1048576 # kb**2
1037 Mb = 1048576 # kb**2
1038 for vname,var,vtype in zip(varnames,varlist,typelist):
1038 for vname,var,vtype in zip(varnames,varlist,typelist):
1039 print itpl(vformat),
1039 print itpl(vformat),
1040 if vtype in seq_types:
1040 if vtype in seq_types:
1041 print len(var)
1041 print len(var)
1042 elif vtype in [array_type,ndarray_type]:
1042 elif vtype in [array_type,ndarray_type]:
1043 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1043 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1044 if vtype==ndarray_type:
1044 if vtype==ndarray_type:
1045 # numpy
1045 # numpy
1046 vsize = var.size
1046 vsize = var.size
1047 vbytes = vsize*var.itemsize
1047 vbytes = vsize*var.itemsize
1048 vdtype = var.dtype
1048 vdtype = var.dtype
1049 else:
1049 else:
1050 # Numeric
1050 # Numeric
1051 vsize = Numeric.size(var)
1051 vsize = Numeric.size(var)
1052 vbytes = vsize*var.itemsize()
1052 vbytes = vsize*var.itemsize()
1053 vdtype = var.typecode()
1053 vdtype = var.typecode()
1054
1054
1055 if vbytes < 100000:
1055 if vbytes < 100000:
1056 print aformat % (vshape,vsize,vdtype,vbytes)
1056 print aformat % (vshape,vsize,vdtype,vbytes)
1057 else:
1057 else:
1058 print aformat % (vshape,vsize,vdtype,vbytes),
1058 print aformat % (vshape,vsize,vdtype,vbytes),
1059 if vbytes < Mb:
1059 if vbytes < Mb:
1060 print '(%s kb)' % (vbytes/kb,)
1060 print '(%s kb)' % (vbytes/kb,)
1061 else:
1061 else:
1062 print '(%s Mb)' % (vbytes/Mb,)
1062 print '(%s Mb)' % (vbytes/Mb,)
1063 else:
1063 else:
1064 try:
1064 try:
1065 vstr = str(var)
1065 vstr = str(var)
1066 except UnicodeEncodeError:
1066 except UnicodeEncodeError:
1067 vstr = unicode(var).encode(sys.getdefaultencoding(),
1067 vstr = unicode(var).encode(sys.getdefaultencoding(),
1068 'backslashreplace')
1068 'backslashreplace')
1069 vstr = vstr.replace('\n','\\n')
1069 vstr = vstr.replace('\n','\\n')
1070 if len(vstr) < 50:
1070 if len(vstr) < 50:
1071 print vstr
1071 print vstr
1072 else:
1072 else:
1073 printpl(vfmt_short)
1073 printpl(vfmt_short)
1074
1074
1075 def magic_reset(self, parameter_s=''):
1075 def magic_reset(self, parameter_s=''):
1076 """Resets the namespace by removing all names defined by the user.
1076 """Resets the namespace by removing all names defined by the user.
1077
1077
1078 Input/Output history are left around in case you need them.
1078 Input/Output history are left around in case you need them.
1079
1079
1080 Parameters
1080 Parameters
1081 ----------
1081 ----------
1082 -y : force reset without asking for confirmation.
1082 -y : force reset without asking for confirmation.
1083
1083
1084 Examples
1084 Examples
1085 --------
1085 --------
1086 In [6]: a = 1
1086 In [6]: a = 1
1087
1087
1088 In [7]: a
1088 In [7]: a
1089 Out[7]: 1
1089 Out[7]: 1
1090
1090
1091 In [8]: 'a' in _ip.user_ns
1091 In [8]: 'a' in _ip.user_ns
1092 Out[8]: True
1092 Out[8]: True
1093
1093
1094 In [9]: %reset -f
1094 In [9]: %reset -f
1095
1095
1096 In [10]: 'a' in _ip.user_ns
1096 In [10]: 'a' in _ip.user_ns
1097 Out[10]: False
1097 Out[10]: False
1098 """
1098 """
1099
1099
1100 if parameter_s == '-f':
1100 if parameter_s == '-f':
1101 ans = True
1101 ans = True
1102 else:
1102 else:
1103 ans = self.shell.ask_yes_no(
1103 ans = self.shell.ask_yes_no(
1104 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1104 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1105 if not ans:
1105 if not ans:
1106 print 'Nothing done.'
1106 print 'Nothing done.'
1107 return
1107 return
1108 user_ns = self.shell.user_ns
1108 user_ns = self.shell.user_ns
1109 for i in self.magic_who_ls():
1109 for i in self.magic_who_ls():
1110 del(user_ns[i])
1110 del(user_ns[i])
1111
1111
1112 # Also flush the private list of module references kept for script
1112 # Also flush the private list of module references kept for script
1113 # execution protection
1113 # execution protection
1114 self.shell.clear_main_mod_cache()
1114 self.shell.clear_main_mod_cache()
1115
1115
1116 def magic_reset_selective(self, parameter_s=''):
1116 def magic_reset_selective(self, parameter_s=''):
1117 """Resets the namespace by removing names defined by the user.
1117 """Resets the namespace by removing names defined by the user.
1118
1118
1119 Input/Output history are left around in case you need them.
1119 Input/Output history are left around in case you need them.
1120
1120
1121 %reset_selective [-f] regex
1121 %reset_selective [-f] regex
1122
1122
1123 No action is taken if regex is not included
1123 No action is taken if regex is not included
1124
1124
1125 Options
1125 Options
1126 -f : force reset without asking for confirmation.
1126 -f : force reset without asking for confirmation.
1127
1127
1128 Examples
1128 Examples
1129 --------
1129 --------
1130
1130
1131 We first fully reset the namespace so your output looks identical to
1131 We first fully reset the namespace so your output looks identical to
1132 this example for pedagogical reasons; in practice you do not need a
1132 this example for pedagogical reasons; in practice you do not need a
1133 full reset.
1133 full reset.
1134
1134
1135 In [1]: %reset -f
1135 In [1]: %reset -f
1136
1136
1137 Now, with a clean namespace we can make a few variables and use
1137 Now, with a clean namespace we can make a few variables and use
1138 %reset_selective to only delete names that match our regexp:
1138 %reset_selective to only delete names that match our regexp:
1139
1139
1140 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1140 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1141
1141
1142 In [3]: who_ls
1142 In [3]: who_ls
1143 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1143 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1144
1144
1145 In [4]: %reset_selective -f b[2-3]m
1145 In [4]: %reset_selective -f b[2-3]m
1146
1146
1147 In [5]: who_ls
1147 In [5]: who_ls
1148 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1148 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1149
1149
1150 In [6]: %reset_selective -f d
1150 In [6]: %reset_selective -f d
1151
1151
1152 In [7]: who_ls
1152 In [7]: who_ls
1153 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1153 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1154
1154
1155 In [8]: %reset_selective -f c
1155 In [8]: %reset_selective -f c
1156
1156
1157 In [9]: who_ls
1157 In [9]: who_ls
1158 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1158 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1159
1159
1160 In [10]: %reset_selective -f b
1160 In [10]: %reset_selective -f b
1161
1161
1162 In [11]: who_ls
1162 In [11]: who_ls
1163 Out[11]: ['a']
1163 Out[11]: ['a']
1164 """
1164 """
1165
1165
1166 opts, regex = self.parse_options(parameter_s,'f')
1166 opts, regex = self.parse_options(parameter_s,'f')
1167
1167
1168 if opts.has_key('f'):
1168 if opts.has_key('f'):
1169 ans = True
1169 ans = True
1170 else:
1170 else:
1171 ans = self.shell.ask_yes_no(
1171 ans = self.shell.ask_yes_no(
1172 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1172 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1173 if not ans:
1173 if not ans:
1174 print 'Nothing done.'
1174 print 'Nothing done.'
1175 return
1175 return
1176 user_ns = self.shell.user_ns
1176 user_ns = self.shell.user_ns
1177 if not regex:
1177 if not regex:
1178 print 'No regex pattern specified. Nothing done.'
1178 print 'No regex pattern specified. Nothing done.'
1179 return
1179 return
1180 else:
1180 else:
1181 try:
1181 try:
1182 m = re.compile(regex)
1182 m = re.compile(regex)
1183 except TypeError:
1183 except TypeError:
1184 raise TypeError('regex must be a string or compiled pattern')
1184 raise TypeError('regex must be a string or compiled pattern')
1185 for i in self.magic_who_ls():
1185 for i in self.magic_who_ls():
1186 if m.search(i):
1186 if m.search(i):
1187 del(user_ns[i])
1187 del(user_ns[i])
1188
1188
1189 def magic_logstart(self,parameter_s=''):
1189 def magic_logstart(self,parameter_s=''):
1190 """Start logging anywhere in a session.
1190 """Start logging anywhere in a session.
1191
1191
1192 %logstart [-o|-r|-t] [log_name [log_mode]]
1192 %logstart [-o|-r|-t] [log_name [log_mode]]
1193
1193
1194 If no name is given, it defaults to a file named 'ipython_log.py' in your
1194 If no name is given, it defaults to a file named 'ipython_log.py' in your
1195 current directory, in 'rotate' mode (see below).
1195 current directory, in 'rotate' mode (see below).
1196
1196
1197 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1197 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1198 history up to that point and then continues logging.
1198 history up to that point and then continues logging.
1199
1199
1200 %logstart takes a second optional parameter: logging mode. This can be one
1200 %logstart takes a second optional parameter: logging mode. This can be one
1201 of (note that the modes are given unquoted):\\
1201 of (note that the modes are given unquoted):\\
1202 append: well, that says it.\\
1202 append: well, that says it.\\
1203 backup: rename (if exists) to name~ and start name.\\
1203 backup: rename (if exists) to name~ and start name.\\
1204 global: single logfile in your home dir, appended to.\\
1204 global: single logfile in your home dir, appended to.\\
1205 over : overwrite existing log.\\
1205 over : overwrite existing log.\\
1206 rotate: create rotating logs name.1~, name.2~, etc.
1206 rotate: create rotating logs name.1~, name.2~, etc.
1207
1207
1208 Options:
1208 Options:
1209
1209
1210 -o: log also IPython's output. In this mode, all commands which
1210 -o: log also IPython's output. In this mode, all commands which
1211 generate an Out[NN] prompt are recorded to the logfile, right after
1211 generate an Out[NN] prompt are recorded to the logfile, right after
1212 their corresponding input line. The output lines are always
1212 their corresponding input line. The output lines are always
1213 prepended with a '#[Out]# ' marker, so that the log remains valid
1213 prepended with a '#[Out]# ' marker, so that the log remains valid
1214 Python code.
1214 Python code.
1215
1215
1216 Since this marker is always the same, filtering only the output from
1216 Since this marker is always the same, filtering only the output from
1217 a log is very easy, using for example a simple awk call:
1217 a log is very easy, using for example a simple awk call:
1218
1218
1219 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1219 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1220
1220
1221 -r: log 'raw' input. Normally, IPython's logs contain the processed
1221 -r: log 'raw' input. Normally, IPython's logs contain the processed
1222 input, so that user lines are logged in their final form, converted
1222 input, so that user lines are logged in their final form, converted
1223 into valid Python. For example, %Exit is logged as
1223 into valid Python. For example, %Exit is logged as
1224 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1224 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1225 exactly as typed, with no transformations applied.
1225 exactly as typed, with no transformations applied.
1226
1226
1227 -t: put timestamps before each input line logged (these are put in
1227 -t: put timestamps before each input line logged (these are put in
1228 comments)."""
1228 comments)."""
1229
1229
1230 opts,par = self.parse_options(parameter_s,'ort')
1230 opts,par = self.parse_options(parameter_s,'ort')
1231 log_output = 'o' in opts
1231 log_output = 'o' in opts
1232 log_raw_input = 'r' in opts
1232 log_raw_input = 'r' in opts
1233 timestamp = 't' in opts
1233 timestamp = 't' in opts
1234
1234
1235 logger = self.shell.logger
1235 logger = self.shell.logger
1236
1236
1237 # if no args are given, the defaults set in the logger constructor by
1237 # if no args are given, the defaults set in the logger constructor by
1238 # ipytohn remain valid
1238 # ipytohn remain valid
1239 if par:
1239 if par:
1240 try:
1240 try:
1241 logfname,logmode = par.split()
1241 logfname,logmode = par.split()
1242 except:
1242 except:
1243 logfname = par
1243 logfname = par
1244 logmode = 'backup'
1244 logmode = 'backup'
1245 else:
1245 else:
1246 logfname = logger.logfname
1246 logfname = logger.logfname
1247 logmode = logger.logmode
1247 logmode = logger.logmode
1248 # put logfname into rc struct as if it had been called on the command
1248 # put logfname into rc struct as if it had been called on the command
1249 # line, so it ends up saved in the log header Save it in case we need
1249 # line, so it ends up saved in the log header Save it in case we need
1250 # to restore it...
1250 # to restore it...
1251 old_logfile = self.shell.logfile
1251 old_logfile = self.shell.logfile
1252 if logfname:
1252 if logfname:
1253 logfname = os.path.expanduser(logfname)
1253 logfname = os.path.expanduser(logfname)
1254 self.shell.logfile = logfname
1254 self.shell.logfile = logfname
1255
1255
1256 loghead = '# IPython log file\n\n'
1256 loghead = '# IPython log file\n\n'
1257 try:
1257 try:
1258 started = logger.logstart(logfname,loghead,logmode,
1258 started = logger.logstart(logfname,loghead,logmode,
1259 log_output,timestamp,log_raw_input)
1259 log_output,timestamp,log_raw_input)
1260 except:
1260 except:
1261 self.shell.logfile = old_logfile
1261 self.shell.logfile = old_logfile
1262 warn("Couldn't start log: %s" % sys.exc_info()[1])
1262 warn("Couldn't start log: %s" % sys.exc_info()[1])
1263 else:
1263 else:
1264 # log input history up to this point, optionally interleaving
1264 # log input history up to this point, optionally interleaving
1265 # output if requested
1265 # output if requested
1266
1266
1267 if timestamp:
1267 if timestamp:
1268 # disable timestamping for the previous history, since we've
1268 # disable timestamping for the previous history, since we've
1269 # lost those already (no time machine here).
1269 # lost those already (no time machine here).
1270 logger.timestamp = False
1270 logger.timestamp = False
1271
1271
1272 if log_raw_input:
1272 if log_raw_input:
1273 input_hist = self.shell.input_hist_raw
1273 input_hist = self.shell.input_hist_raw
1274 else:
1274 else:
1275 input_hist = self.shell.input_hist
1275 input_hist = self.shell.input_hist
1276
1276
1277 if log_output:
1277 if log_output:
1278 log_write = logger.log_write
1278 log_write = logger.log_write
1279 output_hist = self.shell.output_hist
1279 output_hist = self.shell.output_hist
1280 for n in range(1,len(input_hist)-1):
1280 for n in range(1,len(input_hist)-1):
1281 log_write(input_hist[n].rstrip())
1281 log_write(input_hist[n].rstrip())
1282 if n in output_hist:
1282 if n in output_hist:
1283 log_write(repr(output_hist[n]),'output')
1283 log_write(repr(output_hist[n]),'output')
1284 else:
1284 else:
1285 logger.log_write(input_hist[1:])
1285 logger.log_write(input_hist[1:])
1286 if timestamp:
1286 if timestamp:
1287 # re-enable timestamping
1287 # re-enable timestamping
1288 logger.timestamp = True
1288 logger.timestamp = True
1289
1289
1290 print ('Activating auto-logging. '
1290 print ('Activating auto-logging. '
1291 'Current session state plus future input saved.')
1291 'Current session state plus future input saved.')
1292 logger.logstate()
1292 logger.logstate()
1293
1293
1294 def magic_logstop(self,parameter_s=''):
1294 def magic_logstop(self,parameter_s=''):
1295 """Fully stop logging and close log file.
1295 """Fully stop logging and close log file.
1296
1296
1297 In order to start logging again, a new %logstart call needs to be made,
1297 In order to start logging again, a new %logstart call needs to be made,
1298 possibly (though not necessarily) with a new filename, mode and other
1298 possibly (though not necessarily) with a new filename, mode and other
1299 options."""
1299 options."""
1300 self.logger.logstop()
1300 self.logger.logstop()
1301
1301
1302 def magic_logoff(self,parameter_s=''):
1302 def magic_logoff(self,parameter_s=''):
1303 """Temporarily stop logging.
1303 """Temporarily stop logging.
1304
1304
1305 You must have previously started logging."""
1305 You must have previously started logging."""
1306 self.shell.logger.switch_log(0)
1306 self.shell.logger.switch_log(0)
1307
1307
1308 def magic_logon(self,parameter_s=''):
1308 def magic_logon(self,parameter_s=''):
1309 """Restart logging.
1309 """Restart logging.
1310
1310
1311 This function is for restarting logging which you've temporarily
1311 This function is for restarting logging which you've temporarily
1312 stopped with %logoff. For starting logging for the first time, you
1312 stopped with %logoff. For starting logging for the first time, you
1313 must use the %logstart function, which allows you to specify an
1313 must use the %logstart function, which allows you to specify an
1314 optional log filename."""
1314 optional log filename."""
1315
1315
1316 self.shell.logger.switch_log(1)
1316 self.shell.logger.switch_log(1)
1317
1317
1318 def magic_logstate(self,parameter_s=''):
1318 def magic_logstate(self,parameter_s=''):
1319 """Print the status of the logging system."""
1319 """Print the status of the logging system."""
1320
1320
1321 self.shell.logger.logstate()
1321 self.shell.logger.logstate()
1322
1322
1323 def magic_pdb(self, parameter_s=''):
1323 def magic_pdb(self, parameter_s=''):
1324 """Control the automatic calling of the pdb interactive debugger.
1324 """Control the automatic calling of the pdb interactive debugger.
1325
1325
1326 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1326 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1327 argument it works as a toggle.
1327 argument it works as a toggle.
1328
1328
1329 When an exception is triggered, IPython can optionally call the
1329 When an exception is triggered, IPython can optionally call the
1330 interactive pdb debugger after the traceback printout. %pdb toggles
1330 interactive pdb debugger after the traceback printout. %pdb toggles
1331 this feature on and off.
1331 this feature on and off.
1332
1332
1333 The initial state of this feature is set in your ipythonrc
1333 The initial state of this feature is set in your ipythonrc
1334 configuration file (the variable is called 'pdb').
1334 configuration file (the variable is called 'pdb').
1335
1335
1336 If you want to just activate the debugger AFTER an exception has fired,
1336 If you want to just activate the debugger AFTER an exception has fired,
1337 without having to type '%pdb on' and rerunning your code, you can use
1337 without having to type '%pdb on' and rerunning your code, you can use
1338 the %debug magic."""
1338 the %debug magic."""
1339
1339
1340 par = parameter_s.strip().lower()
1340 par = parameter_s.strip().lower()
1341
1341
1342 if par:
1342 if par:
1343 try:
1343 try:
1344 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1344 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1345 except KeyError:
1345 except KeyError:
1346 print ('Incorrect argument. Use on/1, off/0, '
1346 print ('Incorrect argument. Use on/1, off/0, '
1347 'or nothing for a toggle.')
1347 'or nothing for a toggle.')
1348 return
1348 return
1349 else:
1349 else:
1350 # toggle
1350 # toggle
1351 new_pdb = not self.shell.call_pdb
1351 new_pdb = not self.shell.call_pdb
1352
1352
1353 # set on the shell
1353 # set on the shell
1354 self.shell.call_pdb = new_pdb
1354 self.shell.call_pdb = new_pdb
1355 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1355 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1356
1356
1357 def magic_debug(self, parameter_s=''):
1357 def magic_debug(self, parameter_s=''):
1358 """Activate the interactive debugger in post-mortem mode.
1358 """Activate the interactive debugger in post-mortem mode.
1359
1359
1360 If an exception has just occurred, this lets you inspect its stack
1360 If an exception has just occurred, this lets you inspect its stack
1361 frames interactively. Note that this will always work only on the last
1361 frames interactively. Note that this will always work only on the last
1362 traceback that occurred, so you must call this quickly after an
1362 traceback that occurred, so you must call this quickly after an
1363 exception that you wish to inspect has fired, because if another one
1363 exception that you wish to inspect has fired, because if another one
1364 occurs, it clobbers the previous one.
1364 occurs, it clobbers the previous one.
1365
1365
1366 If you want IPython to automatically do this on every exception, see
1366 If you want IPython to automatically do this on every exception, see
1367 the %pdb magic for more details.
1367 the %pdb magic for more details.
1368 """
1368 """
1369 self.shell.debugger(force=True)
1369 self.shell.debugger(force=True)
1370
1370
1371 @testdec.skip_doctest
1371 @testdec.skip_doctest
1372 def magic_prun(self, parameter_s ='',user_mode=1,
1372 def magic_prun(self, parameter_s ='',user_mode=1,
1373 opts=None,arg_lst=None,prog_ns=None):
1373 opts=None,arg_lst=None,prog_ns=None):
1374
1374
1375 """Run a statement through the python code profiler.
1375 """Run a statement through the python code profiler.
1376
1376
1377 Usage:
1377 Usage:
1378 %prun [options] statement
1378 %prun [options] statement
1379
1379
1380 The given statement (which doesn't require quote marks) is run via the
1380 The given statement (which doesn't require quote marks) is run via the
1381 python profiler in a manner similar to the profile.run() function.
1381 python profiler in a manner similar to the profile.run() function.
1382 Namespaces are internally managed to work correctly; profile.run
1382 Namespaces are internally managed to work correctly; profile.run
1383 cannot be used in IPython because it makes certain assumptions about
1383 cannot be used in IPython because it makes certain assumptions about
1384 namespaces which do not hold under IPython.
1384 namespaces which do not hold under IPython.
1385
1385
1386 Options:
1386 Options:
1387
1387
1388 -l <limit>: you can place restrictions on what or how much of the
1388 -l <limit>: you can place restrictions on what or how much of the
1389 profile gets printed. The limit value can be:
1389 profile gets printed. The limit value can be:
1390
1390
1391 * A string: only information for function names containing this string
1391 * A string: only information for function names containing this string
1392 is printed.
1392 is printed.
1393
1393
1394 * An integer: only these many lines are printed.
1394 * An integer: only these many lines are printed.
1395
1395
1396 * A float (between 0 and 1): this fraction of the report is printed
1396 * A float (between 0 and 1): this fraction of the report is printed
1397 (for example, use a limit of 0.4 to see the topmost 40% only).
1397 (for example, use a limit of 0.4 to see the topmost 40% only).
1398
1398
1399 You can combine several limits with repeated use of the option. For
1399 You can combine several limits with repeated use of the option. For
1400 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1400 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1401 information about class constructors.
1401 information about class constructors.
1402
1402
1403 -r: return the pstats.Stats object generated by the profiling. This
1403 -r: return the pstats.Stats object generated by the profiling. This
1404 object has all the information about the profile in it, and you can
1404 object has all the information about the profile in it, and you can
1405 later use it for further analysis or in other functions.
1405 later use it for further analysis or in other functions.
1406
1406
1407 -s <key>: sort profile by given key. You can provide more than one key
1407 -s <key>: sort profile by given key. You can provide more than one key
1408 by using the option several times: '-s key1 -s key2 -s key3...'. The
1408 by using the option several times: '-s key1 -s key2 -s key3...'. The
1409 default sorting key is 'time'.
1409 default sorting key is 'time'.
1410
1410
1411 The following is copied verbatim from the profile documentation
1411 The following is copied verbatim from the profile documentation
1412 referenced below:
1412 referenced below:
1413
1413
1414 When more than one key is provided, additional keys are used as
1414 When more than one key is provided, additional keys are used as
1415 secondary criteria when the there is equality in all keys selected
1415 secondary criteria when the there is equality in all keys selected
1416 before them.
1416 before them.
1417
1417
1418 Abbreviations can be used for any key names, as long as the
1418 Abbreviations can be used for any key names, as long as the
1419 abbreviation is unambiguous. The following are the keys currently
1419 abbreviation is unambiguous. The following are the keys currently
1420 defined:
1420 defined:
1421
1421
1422 Valid Arg Meaning
1422 Valid Arg Meaning
1423 "calls" call count
1423 "calls" call count
1424 "cumulative" cumulative time
1424 "cumulative" cumulative time
1425 "file" file name
1425 "file" file name
1426 "module" file name
1426 "module" file name
1427 "pcalls" primitive call count
1427 "pcalls" primitive call count
1428 "line" line number
1428 "line" line number
1429 "name" function name
1429 "name" function name
1430 "nfl" name/file/line
1430 "nfl" name/file/line
1431 "stdname" standard name
1431 "stdname" standard name
1432 "time" internal time
1432 "time" internal time
1433
1433
1434 Note that all sorts on statistics are in descending order (placing
1434 Note that all sorts on statistics are in descending order (placing
1435 most time consuming items first), where as name, file, and line number
1435 most time consuming items first), where as name, file, and line number
1436 searches are in ascending order (i.e., alphabetical). The subtle
1436 searches are in ascending order (i.e., alphabetical). The subtle
1437 distinction between "nfl" and "stdname" is that the standard name is a
1437 distinction between "nfl" and "stdname" is that the standard name is a
1438 sort of the name as printed, which means that the embedded line
1438 sort of the name as printed, which means that the embedded line
1439 numbers get compared in an odd way. For example, lines 3, 20, and 40
1439 numbers get compared in an odd way. For example, lines 3, 20, and 40
1440 would (if the file names were the same) appear in the string order
1440 would (if the file names were the same) appear in the string order
1441 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1441 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1442 line numbers. In fact, sort_stats("nfl") is the same as
1442 line numbers. In fact, sort_stats("nfl") is the same as
1443 sort_stats("name", "file", "line").
1443 sort_stats("name", "file", "line").
1444
1444
1445 -T <filename>: save profile results as shown on screen to a text
1445 -T <filename>: save profile results as shown on screen to a text
1446 file. The profile is still shown on screen.
1446 file. The profile is still shown on screen.
1447
1447
1448 -D <filename>: save (via dump_stats) profile statistics to given
1448 -D <filename>: save (via dump_stats) profile statistics to given
1449 filename. This data is in a format understod by the pstats module, and
1449 filename. This data is in a format understod by the pstats module, and
1450 is generated by a call to the dump_stats() method of profile
1450 is generated by a call to the dump_stats() method of profile
1451 objects. The profile is still shown on screen.
1451 objects. The profile is still shown on screen.
1452
1452
1453 If you want to run complete programs under the profiler's control, use
1453 If you want to run complete programs under the profiler's control, use
1454 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1454 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1455 contains profiler specific options as described here.
1455 contains profiler specific options as described here.
1456
1456
1457 You can read the complete documentation for the profile module with::
1457 You can read the complete documentation for the profile module with::
1458
1458
1459 In [1]: import profile; profile.help()
1459 In [1]: import profile; profile.help()
1460 """
1460 """
1461
1461
1462 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1462 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1463 # protect user quote marks
1463 # protect user quote marks
1464 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1464 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1465
1465
1466 if user_mode: # regular user call
1466 if user_mode: # regular user call
1467 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1467 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1468 list_all=1)
1468 list_all=1)
1469 namespace = self.shell.user_ns
1469 namespace = self.shell.user_ns
1470 else: # called to run a program by %run -p
1470 else: # called to run a program by %run -p
1471 try:
1471 try:
1472 filename = get_py_filename(arg_lst[0])
1472 filename = get_py_filename(arg_lst[0])
1473 except IOError,msg:
1473 except IOError,msg:
1474 error(msg)
1474 error(msg)
1475 return
1475 return
1476
1476
1477 arg_str = 'execfile(filename,prog_ns)'
1477 arg_str = 'execfile(filename,prog_ns)'
1478 namespace = locals()
1478 namespace = locals()
1479
1479
1480 opts.merge(opts_def)
1480 opts.merge(opts_def)
1481
1481
1482 prof = profile.Profile()
1482 prof = profile.Profile()
1483 try:
1483 try:
1484 prof = prof.runctx(arg_str,namespace,namespace)
1484 prof = prof.runctx(arg_str,namespace,namespace)
1485 sys_exit = ''
1485 sys_exit = ''
1486 except SystemExit:
1486 except SystemExit:
1487 sys_exit = """*** SystemExit exception caught in code being profiled."""
1487 sys_exit = """*** SystemExit exception caught in code being profiled."""
1488
1488
1489 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1489 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1490
1490
1491 lims = opts.l
1491 lims = opts.l
1492 if lims:
1492 if lims:
1493 lims = [] # rebuild lims with ints/floats/strings
1493 lims = [] # rebuild lims with ints/floats/strings
1494 for lim in opts.l:
1494 for lim in opts.l:
1495 try:
1495 try:
1496 lims.append(int(lim))
1496 lims.append(int(lim))
1497 except ValueError:
1497 except ValueError:
1498 try:
1498 try:
1499 lims.append(float(lim))
1499 lims.append(float(lim))
1500 except ValueError:
1500 except ValueError:
1501 lims.append(lim)
1501 lims.append(lim)
1502
1502
1503 # Trap output.
1503 # Trap output.
1504 stdout_trap = StringIO()
1504 stdout_trap = StringIO()
1505
1505
1506 if hasattr(stats,'stream'):
1506 if hasattr(stats,'stream'):
1507 # In newer versions of python, the stats object has a 'stream'
1507 # In newer versions of python, the stats object has a 'stream'
1508 # attribute to write into.
1508 # attribute to write into.
1509 stats.stream = stdout_trap
1509 stats.stream = stdout_trap
1510 stats.print_stats(*lims)
1510 stats.print_stats(*lims)
1511 else:
1511 else:
1512 # For older versions, we manually redirect stdout during printing
1512 # For older versions, we manually redirect stdout during printing
1513 sys_stdout = sys.stdout
1513 sys_stdout = sys.stdout
1514 try:
1514 try:
1515 sys.stdout = stdout_trap
1515 sys.stdout = stdout_trap
1516 stats.print_stats(*lims)
1516 stats.print_stats(*lims)
1517 finally:
1517 finally:
1518 sys.stdout = sys_stdout
1518 sys.stdout = sys_stdout
1519
1519
1520 output = stdout_trap.getvalue()
1520 output = stdout_trap.getvalue()
1521 output = output.rstrip()
1521 output = output.rstrip()
1522
1522
1523 page(output,screen_lines=self.shell.usable_screen_length)
1523 page.page(output,screen_lines=self.shell.usable_screen_length)
1524 print sys_exit,
1524 print sys_exit,
1525
1525
1526 dump_file = opts.D[0]
1526 dump_file = opts.D[0]
1527 text_file = opts.T[0]
1527 text_file = opts.T[0]
1528 if dump_file:
1528 if dump_file:
1529 prof.dump_stats(dump_file)
1529 prof.dump_stats(dump_file)
1530 print '\n*** Profile stats marshalled to file',\
1530 print '\n*** Profile stats marshalled to file',\
1531 `dump_file`+'.',sys_exit
1531 `dump_file`+'.',sys_exit
1532 if text_file:
1532 if text_file:
1533 pfile = file(text_file,'w')
1533 pfile = file(text_file,'w')
1534 pfile.write(output)
1534 pfile.write(output)
1535 pfile.close()
1535 pfile.close()
1536 print '\n*** Profile printout saved to text file',\
1536 print '\n*** Profile printout saved to text file',\
1537 `text_file`+'.',sys_exit
1537 `text_file`+'.',sys_exit
1538
1538
1539 if opts.has_key('r'):
1539 if opts.has_key('r'):
1540 return stats
1540 return stats
1541 else:
1541 else:
1542 return None
1542 return None
1543
1543
1544 @testdec.skip_doctest
1544 @testdec.skip_doctest
1545 def magic_run(self, parameter_s ='',runner=None,
1545 def magic_run(self, parameter_s ='',runner=None,
1546 file_finder=get_py_filename):
1546 file_finder=get_py_filename):
1547 """Run the named file inside IPython as a program.
1547 """Run the named file inside IPython as a program.
1548
1548
1549 Usage:\\
1549 Usage:\\
1550 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1550 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1551
1551
1552 Parameters after the filename are passed as command-line arguments to
1552 Parameters after the filename are passed as command-line arguments to
1553 the program (put in sys.argv). Then, control returns to IPython's
1553 the program (put in sys.argv). Then, control returns to IPython's
1554 prompt.
1554 prompt.
1555
1555
1556 This is similar to running at a system prompt:\\
1556 This is similar to running at a system prompt:\\
1557 $ python file args\\
1557 $ python file args\\
1558 but with the advantage of giving you IPython's tracebacks, and of
1558 but with the advantage of giving you IPython's tracebacks, and of
1559 loading all variables into your interactive namespace for further use
1559 loading all variables into your interactive namespace for further use
1560 (unless -p is used, see below).
1560 (unless -p is used, see below).
1561
1561
1562 The file is executed in a namespace initially consisting only of
1562 The file is executed in a namespace initially consisting only of
1563 __name__=='__main__' and sys.argv constructed as indicated. It thus
1563 __name__=='__main__' and sys.argv constructed as indicated. It thus
1564 sees its environment as if it were being run as a stand-alone program
1564 sees its environment as if it were being run as a stand-alone program
1565 (except for sharing global objects such as previously imported
1565 (except for sharing global objects such as previously imported
1566 modules). But after execution, the IPython interactive namespace gets
1566 modules). But after execution, the IPython interactive namespace gets
1567 updated with all variables defined in the program (except for __name__
1567 updated with all variables defined in the program (except for __name__
1568 and sys.argv). This allows for very convenient loading of code for
1568 and sys.argv). This allows for very convenient loading of code for
1569 interactive work, while giving each program a 'clean sheet' to run in.
1569 interactive work, while giving each program a 'clean sheet' to run in.
1570
1570
1571 Options:
1571 Options:
1572
1572
1573 -n: __name__ is NOT set to '__main__', but to the running file's name
1573 -n: __name__ is NOT set to '__main__', but to the running file's name
1574 without extension (as python does under import). This allows running
1574 without extension (as python does under import). This allows running
1575 scripts and reloading the definitions in them without calling code
1575 scripts and reloading the definitions in them without calling code
1576 protected by an ' if __name__ == "__main__" ' clause.
1576 protected by an ' if __name__ == "__main__" ' clause.
1577
1577
1578 -i: run the file in IPython's namespace instead of an empty one. This
1578 -i: run the file in IPython's namespace instead of an empty one. This
1579 is useful if you are experimenting with code written in a text editor
1579 is useful if you are experimenting with code written in a text editor
1580 which depends on variables defined interactively.
1580 which depends on variables defined interactively.
1581
1581
1582 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1582 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1583 being run. This is particularly useful if IPython is being used to
1583 being run. This is particularly useful if IPython is being used to
1584 run unittests, which always exit with a sys.exit() call. In such
1584 run unittests, which always exit with a sys.exit() call. In such
1585 cases you are interested in the output of the test results, not in
1585 cases you are interested in the output of the test results, not in
1586 seeing a traceback of the unittest module.
1586 seeing a traceback of the unittest module.
1587
1587
1588 -t: print timing information at the end of the run. IPython will give
1588 -t: print timing information at the end of the run. IPython will give
1589 you an estimated CPU time consumption for your script, which under
1589 you an estimated CPU time consumption for your script, which under
1590 Unix uses the resource module to avoid the wraparound problems of
1590 Unix uses the resource module to avoid the wraparound problems of
1591 time.clock(). Under Unix, an estimate of time spent on system tasks
1591 time.clock(). Under Unix, an estimate of time spent on system tasks
1592 is also given (for Windows platforms this is reported as 0.0).
1592 is also given (for Windows platforms this is reported as 0.0).
1593
1593
1594 If -t is given, an additional -N<N> option can be given, where <N>
1594 If -t is given, an additional -N<N> option can be given, where <N>
1595 must be an integer indicating how many times you want the script to
1595 must be an integer indicating how many times you want the script to
1596 run. The final timing report will include total and per run results.
1596 run. The final timing report will include total and per run results.
1597
1597
1598 For example (testing the script uniq_stable.py):
1598 For example (testing the script uniq_stable.py):
1599
1599
1600 In [1]: run -t uniq_stable
1600 In [1]: run -t uniq_stable
1601
1601
1602 IPython CPU timings (estimated):\\
1602 IPython CPU timings (estimated):\\
1603 User : 0.19597 s.\\
1603 User : 0.19597 s.\\
1604 System: 0.0 s.\\
1604 System: 0.0 s.\\
1605
1605
1606 In [2]: run -t -N5 uniq_stable
1606 In [2]: run -t -N5 uniq_stable
1607
1607
1608 IPython CPU timings (estimated):\\
1608 IPython CPU timings (estimated):\\
1609 Total runs performed: 5\\
1609 Total runs performed: 5\\
1610 Times : Total Per run\\
1610 Times : Total Per run\\
1611 User : 0.910862 s, 0.1821724 s.\\
1611 User : 0.910862 s, 0.1821724 s.\\
1612 System: 0.0 s, 0.0 s.
1612 System: 0.0 s, 0.0 s.
1613
1613
1614 -d: run your program under the control of pdb, the Python debugger.
1614 -d: run your program under the control of pdb, the Python debugger.
1615 This allows you to execute your program step by step, watch variables,
1615 This allows you to execute your program step by step, watch variables,
1616 etc. Internally, what IPython does is similar to calling:
1616 etc. Internally, what IPython does is similar to calling:
1617
1617
1618 pdb.run('execfile("YOURFILENAME")')
1618 pdb.run('execfile("YOURFILENAME")')
1619
1619
1620 with a breakpoint set on line 1 of your file. You can change the line
1620 with a breakpoint set on line 1 of your file. You can change the line
1621 number for this automatic breakpoint to be <N> by using the -bN option
1621 number for this automatic breakpoint to be <N> by using the -bN option
1622 (where N must be an integer). For example:
1622 (where N must be an integer). For example:
1623
1623
1624 %run -d -b40 myscript
1624 %run -d -b40 myscript
1625
1625
1626 will set the first breakpoint at line 40 in myscript.py. Note that
1626 will set the first breakpoint at line 40 in myscript.py. Note that
1627 the first breakpoint must be set on a line which actually does
1627 the first breakpoint must be set on a line which actually does
1628 something (not a comment or docstring) for it to stop execution.
1628 something (not a comment or docstring) for it to stop execution.
1629
1629
1630 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1630 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1631 first enter 'c' (without qoutes) to start execution up to the first
1631 first enter 'c' (without qoutes) to start execution up to the first
1632 breakpoint.
1632 breakpoint.
1633
1633
1634 Entering 'help' gives information about the use of the debugger. You
1634 Entering 'help' gives information about the use of the debugger. You
1635 can easily see pdb's full documentation with "import pdb;pdb.help()"
1635 can easily see pdb's full documentation with "import pdb;pdb.help()"
1636 at a prompt.
1636 at a prompt.
1637
1637
1638 -p: run program under the control of the Python profiler module (which
1638 -p: run program under the control of the Python profiler module (which
1639 prints a detailed report of execution times, function calls, etc).
1639 prints a detailed report of execution times, function calls, etc).
1640
1640
1641 You can pass other options after -p which affect the behavior of the
1641 You can pass other options after -p which affect the behavior of the
1642 profiler itself. See the docs for %prun for details.
1642 profiler itself. See the docs for %prun for details.
1643
1643
1644 In this mode, the program's variables do NOT propagate back to the
1644 In this mode, the program's variables do NOT propagate back to the
1645 IPython interactive namespace (because they remain in the namespace
1645 IPython interactive namespace (because they remain in the namespace
1646 where the profiler executes them).
1646 where the profiler executes them).
1647
1647
1648 Internally this triggers a call to %prun, see its documentation for
1648 Internally this triggers a call to %prun, see its documentation for
1649 details on the options available specifically for profiling.
1649 details on the options available specifically for profiling.
1650
1650
1651 There is one special usage for which the text above doesn't apply:
1651 There is one special usage for which the text above doesn't apply:
1652 if the filename ends with .ipy, the file is run as ipython script,
1652 if the filename ends with .ipy, the file is run as ipython script,
1653 just as if the commands were written on IPython prompt.
1653 just as if the commands were written on IPython prompt.
1654 """
1654 """
1655
1655
1656 # get arguments and set sys.argv for program to be run.
1656 # get arguments and set sys.argv for program to be run.
1657 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1657 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1658 mode='list',list_all=1)
1658 mode='list',list_all=1)
1659
1659
1660 try:
1660 try:
1661 filename = file_finder(arg_lst[0])
1661 filename = file_finder(arg_lst[0])
1662 except IndexError:
1662 except IndexError:
1663 warn('you must provide at least a filename.')
1663 warn('you must provide at least a filename.')
1664 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1664 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1665 return
1665 return
1666 except IOError,msg:
1666 except IOError,msg:
1667 error(msg)
1667 error(msg)
1668 return
1668 return
1669
1669
1670 if filename.lower().endswith('.ipy'):
1670 if filename.lower().endswith('.ipy'):
1671 self.shell.safe_execfile_ipy(filename)
1671 self.shell.safe_execfile_ipy(filename)
1672 return
1672 return
1673
1673
1674 # Control the response to exit() calls made by the script being run
1674 # Control the response to exit() calls made by the script being run
1675 exit_ignore = opts.has_key('e')
1675 exit_ignore = opts.has_key('e')
1676
1676
1677 # Make sure that the running script gets a proper sys.argv as if it
1677 # Make sure that the running script gets a proper sys.argv as if it
1678 # were run from a system shell.
1678 # were run from a system shell.
1679 save_argv = sys.argv # save it for later restoring
1679 save_argv = sys.argv # save it for later restoring
1680 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1680 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1681
1681
1682 if opts.has_key('i'):
1682 if opts.has_key('i'):
1683 # Run in user's interactive namespace
1683 # Run in user's interactive namespace
1684 prog_ns = self.shell.user_ns
1684 prog_ns = self.shell.user_ns
1685 __name__save = self.shell.user_ns['__name__']
1685 __name__save = self.shell.user_ns['__name__']
1686 prog_ns['__name__'] = '__main__'
1686 prog_ns['__name__'] = '__main__'
1687 main_mod = self.shell.new_main_mod(prog_ns)
1687 main_mod = self.shell.new_main_mod(prog_ns)
1688 else:
1688 else:
1689 # Run in a fresh, empty namespace
1689 # Run in a fresh, empty namespace
1690 if opts.has_key('n'):
1690 if opts.has_key('n'):
1691 name = os.path.splitext(os.path.basename(filename))[0]
1691 name = os.path.splitext(os.path.basename(filename))[0]
1692 else:
1692 else:
1693 name = '__main__'
1693 name = '__main__'
1694
1694
1695 main_mod = self.shell.new_main_mod()
1695 main_mod = self.shell.new_main_mod()
1696 prog_ns = main_mod.__dict__
1696 prog_ns = main_mod.__dict__
1697 prog_ns['__name__'] = name
1697 prog_ns['__name__'] = name
1698
1698
1699 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1699 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1700 # set the __file__ global in the script's namespace
1700 # set the __file__ global in the script's namespace
1701 prog_ns['__file__'] = filename
1701 prog_ns['__file__'] = filename
1702
1702
1703 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1703 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1704 # that, if we overwrite __main__, we replace it at the end
1704 # that, if we overwrite __main__, we replace it at the end
1705 main_mod_name = prog_ns['__name__']
1705 main_mod_name = prog_ns['__name__']
1706
1706
1707 if main_mod_name == '__main__':
1707 if main_mod_name == '__main__':
1708 restore_main = sys.modules['__main__']
1708 restore_main = sys.modules['__main__']
1709 else:
1709 else:
1710 restore_main = False
1710 restore_main = False
1711
1711
1712 # This needs to be undone at the end to prevent holding references to
1712 # This needs to be undone at the end to prevent holding references to
1713 # every single object ever created.
1713 # every single object ever created.
1714 sys.modules[main_mod_name] = main_mod
1714 sys.modules[main_mod_name] = main_mod
1715
1715
1716 stats = None
1716 stats = None
1717 try:
1717 try:
1718 self.shell.savehist()
1718 self.shell.savehist()
1719
1719
1720 if opts.has_key('p'):
1720 if opts.has_key('p'):
1721 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1721 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1722 else:
1722 else:
1723 if opts.has_key('d'):
1723 if opts.has_key('d'):
1724 deb = debugger.Pdb(self.shell.colors)
1724 deb = debugger.Pdb(self.shell.colors)
1725 # reset Breakpoint state, which is moronically kept
1725 # reset Breakpoint state, which is moronically kept
1726 # in a class
1726 # in a class
1727 bdb.Breakpoint.next = 1
1727 bdb.Breakpoint.next = 1
1728 bdb.Breakpoint.bplist = {}
1728 bdb.Breakpoint.bplist = {}
1729 bdb.Breakpoint.bpbynumber = [None]
1729 bdb.Breakpoint.bpbynumber = [None]
1730 # Set an initial breakpoint to stop execution
1730 # Set an initial breakpoint to stop execution
1731 maxtries = 10
1731 maxtries = 10
1732 bp = int(opts.get('b',[1])[0])
1732 bp = int(opts.get('b',[1])[0])
1733 checkline = deb.checkline(filename,bp)
1733 checkline = deb.checkline(filename,bp)
1734 if not checkline:
1734 if not checkline:
1735 for bp in range(bp+1,bp+maxtries+1):
1735 for bp in range(bp+1,bp+maxtries+1):
1736 if deb.checkline(filename,bp):
1736 if deb.checkline(filename,bp):
1737 break
1737 break
1738 else:
1738 else:
1739 msg = ("\nI failed to find a valid line to set "
1739 msg = ("\nI failed to find a valid line to set "
1740 "a breakpoint\n"
1740 "a breakpoint\n"
1741 "after trying up to line: %s.\n"
1741 "after trying up to line: %s.\n"
1742 "Please set a valid breakpoint manually "
1742 "Please set a valid breakpoint manually "
1743 "with the -b option." % bp)
1743 "with the -b option." % bp)
1744 error(msg)
1744 error(msg)
1745 return
1745 return
1746 # if we find a good linenumber, set the breakpoint
1746 # if we find a good linenumber, set the breakpoint
1747 deb.do_break('%s:%s' % (filename,bp))
1747 deb.do_break('%s:%s' % (filename,bp))
1748 # Start file run
1748 # Start file run
1749 print "NOTE: Enter 'c' at the",
1749 print "NOTE: Enter 'c' at the",
1750 print "%s prompt to start your script." % deb.prompt
1750 print "%s prompt to start your script." % deb.prompt
1751 try:
1751 try:
1752 deb.run('execfile("%s")' % filename,prog_ns)
1752 deb.run('execfile("%s")' % filename,prog_ns)
1753
1753
1754 except:
1754 except:
1755 etype, value, tb = sys.exc_info()
1755 etype, value, tb = sys.exc_info()
1756 # Skip three frames in the traceback: the %run one,
1756 # Skip three frames in the traceback: the %run one,
1757 # one inside bdb.py, and the command-line typed by the
1757 # one inside bdb.py, and the command-line typed by the
1758 # user (run by exec in pdb itself).
1758 # user (run by exec in pdb itself).
1759 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1759 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1760 else:
1760 else:
1761 if runner is None:
1761 if runner is None:
1762 runner = self.shell.safe_execfile
1762 runner = self.shell.safe_execfile
1763 if opts.has_key('t'):
1763 if opts.has_key('t'):
1764 # timed execution
1764 # timed execution
1765 try:
1765 try:
1766 nruns = int(opts['N'][0])
1766 nruns = int(opts['N'][0])
1767 if nruns < 1:
1767 if nruns < 1:
1768 error('Number of runs must be >=1')
1768 error('Number of runs must be >=1')
1769 return
1769 return
1770 except (KeyError):
1770 except (KeyError):
1771 nruns = 1
1771 nruns = 1
1772 if nruns == 1:
1772 if nruns == 1:
1773 t0 = clock2()
1773 t0 = clock2()
1774 runner(filename,prog_ns,prog_ns,
1774 runner(filename,prog_ns,prog_ns,
1775 exit_ignore=exit_ignore)
1775 exit_ignore=exit_ignore)
1776 t1 = clock2()
1776 t1 = clock2()
1777 t_usr = t1[0]-t0[0]
1777 t_usr = t1[0]-t0[0]
1778 t_sys = t1[1]-t0[1]
1778 t_sys = t1[1]-t0[1]
1779 print "\nIPython CPU timings (estimated):"
1779 print "\nIPython CPU timings (estimated):"
1780 print " User : %10s s." % t_usr
1780 print " User : %10s s." % t_usr
1781 print " System: %10s s." % t_sys
1781 print " System: %10s s." % t_sys
1782 else:
1782 else:
1783 runs = range(nruns)
1783 runs = range(nruns)
1784 t0 = clock2()
1784 t0 = clock2()
1785 for nr in runs:
1785 for nr in runs:
1786 runner(filename,prog_ns,prog_ns,
1786 runner(filename,prog_ns,prog_ns,
1787 exit_ignore=exit_ignore)
1787 exit_ignore=exit_ignore)
1788 t1 = clock2()
1788 t1 = clock2()
1789 t_usr = t1[0]-t0[0]
1789 t_usr = t1[0]-t0[0]
1790 t_sys = t1[1]-t0[1]
1790 t_sys = t1[1]-t0[1]
1791 print "\nIPython CPU timings (estimated):"
1791 print "\nIPython CPU timings (estimated):"
1792 print "Total runs performed:",nruns
1792 print "Total runs performed:",nruns
1793 print " Times : %10s %10s" % ('Total','Per run')
1793 print " Times : %10s %10s" % ('Total','Per run')
1794 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1794 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1795 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1795 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1796
1796
1797 else:
1797 else:
1798 # regular execution
1798 # regular execution
1799 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1799 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1800
1800
1801 if opts.has_key('i'):
1801 if opts.has_key('i'):
1802 self.shell.user_ns['__name__'] = __name__save
1802 self.shell.user_ns['__name__'] = __name__save
1803 else:
1803 else:
1804 # The shell MUST hold a reference to prog_ns so after %run
1804 # The shell MUST hold a reference to prog_ns so after %run
1805 # exits, the python deletion mechanism doesn't zero it out
1805 # exits, the python deletion mechanism doesn't zero it out
1806 # (leaving dangling references).
1806 # (leaving dangling references).
1807 self.shell.cache_main_mod(prog_ns,filename)
1807 self.shell.cache_main_mod(prog_ns,filename)
1808 # update IPython interactive namespace
1808 # update IPython interactive namespace
1809
1809
1810 # Some forms of read errors on the file may mean the
1810 # Some forms of read errors on the file may mean the
1811 # __name__ key was never set; using pop we don't have to
1811 # __name__ key was never set; using pop we don't have to
1812 # worry about a possible KeyError.
1812 # worry about a possible KeyError.
1813 prog_ns.pop('__name__', None)
1813 prog_ns.pop('__name__', None)
1814
1814
1815 self.shell.user_ns.update(prog_ns)
1815 self.shell.user_ns.update(prog_ns)
1816 finally:
1816 finally:
1817 # It's a bit of a mystery why, but __builtins__ can change from
1817 # It's a bit of a mystery why, but __builtins__ can change from
1818 # being a module to becoming a dict missing some key data after
1818 # being a module to becoming a dict missing some key data after
1819 # %run. As best I can see, this is NOT something IPython is doing
1819 # %run. As best I can see, this is NOT something IPython is doing
1820 # at all, and similar problems have been reported before:
1820 # at all, and similar problems have been reported before:
1821 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1821 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1822 # Since this seems to be done by the interpreter itself, the best
1822 # Since this seems to be done by the interpreter itself, the best
1823 # we can do is to at least restore __builtins__ for the user on
1823 # we can do is to at least restore __builtins__ for the user on
1824 # exit.
1824 # exit.
1825 self.shell.user_ns['__builtins__'] = __builtin__
1825 self.shell.user_ns['__builtins__'] = __builtin__
1826
1826
1827 # Ensure key global structures are restored
1827 # Ensure key global structures are restored
1828 sys.argv = save_argv
1828 sys.argv = save_argv
1829 if restore_main:
1829 if restore_main:
1830 sys.modules['__main__'] = restore_main
1830 sys.modules['__main__'] = restore_main
1831 else:
1831 else:
1832 # Remove from sys.modules the reference to main_mod we'd
1832 # Remove from sys.modules the reference to main_mod we'd
1833 # added. Otherwise it will trap references to objects
1833 # added. Otherwise it will trap references to objects
1834 # contained therein.
1834 # contained therein.
1835 del sys.modules[main_mod_name]
1835 del sys.modules[main_mod_name]
1836
1836
1837 self.shell.reloadhist()
1837 self.shell.reloadhist()
1838
1838
1839 return stats
1839 return stats
1840
1840
1841 @testdec.skip_doctest
1841 @testdec.skip_doctest
1842 def magic_timeit(self, parameter_s =''):
1842 def magic_timeit(self, parameter_s =''):
1843 """Time execution of a Python statement or expression
1843 """Time execution of a Python statement or expression
1844
1844
1845 Usage:\\
1845 Usage:\\
1846 %timeit [-n<N> -r<R> [-t|-c]] statement
1846 %timeit [-n<N> -r<R> [-t|-c]] statement
1847
1847
1848 Time execution of a Python statement or expression using the timeit
1848 Time execution of a Python statement or expression using the timeit
1849 module.
1849 module.
1850
1850
1851 Options:
1851 Options:
1852 -n<N>: execute the given statement <N> times in a loop. If this value
1852 -n<N>: execute the given statement <N> times in a loop. If this value
1853 is not given, a fitting value is chosen.
1853 is not given, a fitting value is chosen.
1854
1854
1855 -r<R>: repeat the loop iteration <R> times and take the best result.
1855 -r<R>: repeat the loop iteration <R> times and take the best result.
1856 Default: 3
1856 Default: 3
1857
1857
1858 -t: use time.time to measure the time, which is the default on Unix.
1858 -t: use time.time to measure the time, which is the default on Unix.
1859 This function measures wall time.
1859 This function measures wall time.
1860
1860
1861 -c: use time.clock to measure the time, which is the default on
1861 -c: use time.clock to measure the time, which is the default on
1862 Windows and measures wall time. On Unix, resource.getrusage is used
1862 Windows and measures wall time. On Unix, resource.getrusage is used
1863 instead and returns the CPU user time.
1863 instead and returns the CPU user time.
1864
1864
1865 -p<P>: use a precision of <P> digits to display the timing result.
1865 -p<P>: use a precision of <P> digits to display the timing result.
1866 Default: 3
1866 Default: 3
1867
1867
1868
1868
1869 Examples:
1869 Examples:
1870
1870
1871 In [1]: %timeit pass
1871 In [1]: %timeit pass
1872 10000000 loops, best of 3: 53.3 ns per loop
1872 10000000 loops, best of 3: 53.3 ns per loop
1873
1873
1874 In [2]: u = None
1874 In [2]: u = None
1875
1875
1876 In [3]: %timeit u is None
1876 In [3]: %timeit u is None
1877 10000000 loops, best of 3: 184 ns per loop
1877 10000000 loops, best of 3: 184 ns per loop
1878
1878
1879 In [4]: %timeit -r 4 u == None
1879 In [4]: %timeit -r 4 u == None
1880 1000000 loops, best of 4: 242 ns per loop
1880 1000000 loops, best of 4: 242 ns per loop
1881
1881
1882 In [5]: import time
1882 In [5]: import time
1883
1883
1884 In [6]: %timeit -n1 time.sleep(2)
1884 In [6]: %timeit -n1 time.sleep(2)
1885 1 loops, best of 3: 2 s per loop
1885 1 loops, best of 3: 2 s per loop
1886
1886
1887
1887
1888 The times reported by %timeit will be slightly higher than those
1888 The times reported by %timeit will be slightly higher than those
1889 reported by the timeit.py script when variables are accessed. This is
1889 reported by the timeit.py script when variables are accessed. This is
1890 due to the fact that %timeit executes the statement in the namespace
1890 due to the fact that %timeit executes the statement in the namespace
1891 of the shell, compared with timeit.py, which uses a single setup
1891 of the shell, compared with timeit.py, which uses a single setup
1892 statement to import function or create variables. Generally, the bias
1892 statement to import function or create variables. Generally, the bias
1893 does not matter as long as results from timeit.py are not mixed with
1893 does not matter as long as results from timeit.py are not mixed with
1894 those from %timeit."""
1894 those from %timeit."""
1895
1895
1896 import timeit
1896 import timeit
1897 import math
1897 import math
1898
1898
1899 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1899 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1900 # certain terminals. Until we figure out a robust way of
1900 # certain terminals. Until we figure out a robust way of
1901 # auto-detecting if the terminal can deal with it, use plain 'us' for
1901 # auto-detecting if the terminal can deal with it, use plain 'us' for
1902 # microseconds. I am really NOT happy about disabling the proper
1902 # microseconds. I am really NOT happy about disabling the proper
1903 # 'micro' prefix, but crashing is worse... If anyone knows what the
1903 # 'micro' prefix, but crashing is worse... If anyone knows what the
1904 # right solution for this is, I'm all ears...
1904 # right solution for this is, I'm all ears...
1905 #
1905 #
1906 # Note: using
1906 # Note: using
1907 #
1907 #
1908 # s = u'\xb5'
1908 # s = u'\xb5'
1909 # s.encode(sys.getdefaultencoding())
1909 # s.encode(sys.getdefaultencoding())
1910 #
1910 #
1911 # is not sufficient, as I've seen terminals where that fails but
1911 # is not sufficient, as I've seen terminals where that fails but
1912 # print s
1912 # print s
1913 #
1913 #
1914 # succeeds
1914 # succeeds
1915 #
1915 #
1916 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1916 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1917
1917
1918 #units = [u"s", u"ms",u'\xb5',"ns"]
1918 #units = [u"s", u"ms",u'\xb5',"ns"]
1919 units = [u"s", u"ms",u'us',"ns"]
1919 units = [u"s", u"ms",u'us',"ns"]
1920
1920
1921 scaling = [1, 1e3, 1e6, 1e9]
1921 scaling = [1, 1e3, 1e6, 1e9]
1922
1922
1923 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1923 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1924 posix=False)
1924 posix=False)
1925 if stmt == "":
1925 if stmt == "":
1926 return
1926 return
1927 timefunc = timeit.default_timer
1927 timefunc = timeit.default_timer
1928 number = int(getattr(opts, "n", 0))
1928 number = int(getattr(opts, "n", 0))
1929 repeat = int(getattr(opts, "r", timeit.default_repeat))
1929 repeat = int(getattr(opts, "r", timeit.default_repeat))
1930 precision = int(getattr(opts, "p", 3))
1930 precision = int(getattr(opts, "p", 3))
1931 if hasattr(opts, "t"):
1931 if hasattr(opts, "t"):
1932 timefunc = time.time
1932 timefunc = time.time
1933 if hasattr(opts, "c"):
1933 if hasattr(opts, "c"):
1934 timefunc = clock
1934 timefunc = clock
1935
1935
1936 timer = timeit.Timer(timer=timefunc)
1936 timer = timeit.Timer(timer=timefunc)
1937 # this code has tight coupling to the inner workings of timeit.Timer,
1937 # this code has tight coupling to the inner workings of timeit.Timer,
1938 # but is there a better way to achieve that the code stmt has access
1938 # but is there a better way to achieve that the code stmt has access
1939 # to the shell namespace?
1939 # to the shell namespace?
1940
1940
1941 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1941 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1942 'setup': "pass"}
1942 'setup': "pass"}
1943 # Track compilation time so it can be reported if too long
1943 # Track compilation time so it can be reported if too long
1944 # Minimum time above which compilation time will be reported
1944 # Minimum time above which compilation time will be reported
1945 tc_min = 0.1
1945 tc_min = 0.1
1946
1946
1947 t0 = clock()
1947 t0 = clock()
1948 code = compile(src, "<magic-timeit>", "exec")
1948 code = compile(src, "<magic-timeit>", "exec")
1949 tc = clock()-t0
1949 tc = clock()-t0
1950
1950
1951 ns = {}
1951 ns = {}
1952 exec code in self.shell.user_ns, ns
1952 exec code in self.shell.user_ns, ns
1953 timer.inner = ns["inner"]
1953 timer.inner = ns["inner"]
1954
1954
1955 if number == 0:
1955 if number == 0:
1956 # determine number so that 0.2 <= total time < 2.0
1956 # determine number so that 0.2 <= total time < 2.0
1957 number = 1
1957 number = 1
1958 for i in range(1, 10):
1958 for i in range(1, 10):
1959 if timer.timeit(number) >= 0.2:
1959 if timer.timeit(number) >= 0.2:
1960 break
1960 break
1961 number *= 10
1961 number *= 10
1962
1962
1963 best = min(timer.repeat(repeat, number)) / number
1963 best = min(timer.repeat(repeat, number)) / number
1964
1964
1965 if best > 0.0 and best < 1000.0:
1965 if best > 0.0 and best < 1000.0:
1966 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1966 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1967 elif best >= 1000.0:
1967 elif best >= 1000.0:
1968 order = 0
1968 order = 0
1969 else:
1969 else:
1970 order = 3
1970 order = 3
1971 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1971 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1972 precision,
1972 precision,
1973 best * scaling[order],
1973 best * scaling[order],
1974 units[order])
1974 units[order])
1975 if tc > tc_min:
1975 if tc > tc_min:
1976 print "Compiler time: %.2f s" % tc
1976 print "Compiler time: %.2f s" % tc
1977
1977
1978 @testdec.skip_doctest
1978 @testdec.skip_doctest
1979 def magic_time(self,parameter_s = ''):
1979 def magic_time(self,parameter_s = ''):
1980 """Time execution of a Python statement or expression.
1980 """Time execution of a Python statement or expression.
1981
1981
1982 The CPU and wall clock times are printed, and the value of the
1982 The CPU and wall clock times are printed, and the value of the
1983 expression (if any) is returned. Note that under Win32, system time
1983 expression (if any) is returned. Note that under Win32, system time
1984 is always reported as 0, since it can not be measured.
1984 is always reported as 0, since it can not be measured.
1985
1985
1986 This function provides very basic timing functionality. In Python
1986 This function provides very basic timing functionality. In Python
1987 2.3, the timeit module offers more control and sophistication, so this
1987 2.3, the timeit module offers more control and sophistication, so this
1988 could be rewritten to use it (patches welcome).
1988 could be rewritten to use it (patches welcome).
1989
1989
1990 Some examples:
1990 Some examples:
1991
1991
1992 In [1]: time 2**128
1992 In [1]: time 2**128
1993 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1993 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1994 Wall time: 0.00
1994 Wall time: 0.00
1995 Out[1]: 340282366920938463463374607431768211456L
1995 Out[1]: 340282366920938463463374607431768211456L
1996
1996
1997 In [2]: n = 1000000
1997 In [2]: n = 1000000
1998
1998
1999 In [3]: time sum(range(n))
1999 In [3]: time sum(range(n))
2000 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
2000 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
2001 Wall time: 1.37
2001 Wall time: 1.37
2002 Out[3]: 499999500000L
2002 Out[3]: 499999500000L
2003
2003
2004 In [4]: time print 'hello world'
2004 In [4]: time print 'hello world'
2005 hello world
2005 hello world
2006 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2006 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2007 Wall time: 0.00
2007 Wall time: 0.00
2008
2008
2009 Note that the time needed by Python to compile the given expression
2009 Note that the time needed by Python to compile the given expression
2010 will be reported if it is more than 0.1s. In this example, the
2010 will be reported if it is more than 0.1s. In this example, the
2011 actual exponentiation is done by Python at compilation time, so while
2011 actual exponentiation is done by Python at compilation time, so while
2012 the expression can take a noticeable amount of time to compute, that
2012 the expression can take a noticeable amount of time to compute, that
2013 time is purely due to the compilation:
2013 time is purely due to the compilation:
2014
2014
2015 In [5]: time 3**9999;
2015 In [5]: time 3**9999;
2016 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2016 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2017 Wall time: 0.00 s
2017 Wall time: 0.00 s
2018
2018
2019 In [6]: time 3**999999;
2019 In [6]: time 3**999999;
2020 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2020 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2021 Wall time: 0.00 s
2021 Wall time: 0.00 s
2022 Compiler : 0.78 s
2022 Compiler : 0.78 s
2023 """
2023 """
2024
2024
2025 # fail immediately if the given expression can't be compiled
2025 # fail immediately if the given expression can't be compiled
2026
2026
2027 expr = self.shell.prefilter(parameter_s,False)
2027 expr = self.shell.prefilter(parameter_s,False)
2028
2028
2029 # Minimum time above which compilation time will be reported
2029 # Minimum time above which compilation time will be reported
2030 tc_min = 0.1
2030 tc_min = 0.1
2031
2031
2032 try:
2032 try:
2033 mode = 'eval'
2033 mode = 'eval'
2034 t0 = clock()
2034 t0 = clock()
2035 code = compile(expr,'<timed eval>',mode)
2035 code = compile(expr,'<timed eval>',mode)
2036 tc = clock()-t0
2036 tc = clock()-t0
2037 except SyntaxError:
2037 except SyntaxError:
2038 mode = 'exec'
2038 mode = 'exec'
2039 t0 = clock()
2039 t0 = clock()
2040 code = compile(expr,'<timed exec>',mode)
2040 code = compile(expr,'<timed exec>',mode)
2041 tc = clock()-t0
2041 tc = clock()-t0
2042 # skew measurement as little as possible
2042 # skew measurement as little as possible
2043 glob = self.shell.user_ns
2043 glob = self.shell.user_ns
2044 clk = clock2
2044 clk = clock2
2045 wtime = time.time
2045 wtime = time.time
2046 # time execution
2046 # time execution
2047 wall_st = wtime()
2047 wall_st = wtime()
2048 if mode=='eval':
2048 if mode=='eval':
2049 st = clk()
2049 st = clk()
2050 out = eval(code,glob)
2050 out = eval(code,glob)
2051 end = clk()
2051 end = clk()
2052 else:
2052 else:
2053 st = clk()
2053 st = clk()
2054 exec code in glob
2054 exec code in glob
2055 end = clk()
2055 end = clk()
2056 out = None
2056 out = None
2057 wall_end = wtime()
2057 wall_end = wtime()
2058 # Compute actual times and report
2058 # Compute actual times and report
2059 wall_time = wall_end-wall_st
2059 wall_time = wall_end-wall_st
2060 cpu_user = end[0]-st[0]
2060 cpu_user = end[0]-st[0]
2061 cpu_sys = end[1]-st[1]
2061 cpu_sys = end[1]-st[1]
2062 cpu_tot = cpu_user+cpu_sys
2062 cpu_tot = cpu_user+cpu_sys
2063 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2063 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2064 (cpu_user,cpu_sys,cpu_tot)
2064 (cpu_user,cpu_sys,cpu_tot)
2065 print "Wall time: %.2f s" % wall_time
2065 print "Wall time: %.2f s" % wall_time
2066 if tc > tc_min:
2066 if tc > tc_min:
2067 print "Compiler : %.2f s" % tc
2067 print "Compiler : %.2f s" % tc
2068 return out
2068 return out
2069
2069
2070 @testdec.skip_doctest
2070 @testdec.skip_doctest
2071 def magic_macro(self,parameter_s = ''):
2071 def magic_macro(self,parameter_s = ''):
2072 """Define a set of input lines as a macro for future re-execution.
2072 """Define a set of input lines as a macro for future re-execution.
2073
2073
2074 Usage:\\
2074 Usage:\\
2075 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2075 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2076
2076
2077 Options:
2077 Options:
2078
2078
2079 -r: use 'raw' input. By default, the 'processed' history is used,
2079 -r: use 'raw' input. By default, the 'processed' history is used,
2080 so that magics are loaded in their transformed version to valid
2080 so that magics are loaded in their transformed version to valid
2081 Python. If this option is given, the raw input as typed as the
2081 Python. If this option is given, the raw input as typed as the
2082 command line is used instead.
2082 command line is used instead.
2083
2083
2084 This will define a global variable called `name` which is a string
2084 This will define a global variable called `name` which is a string
2085 made of joining the slices and lines you specify (n1,n2,... numbers
2085 made of joining the slices and lines you specify (n1,n2,... numbers
2086 above) from your input history into a single string. This variable
2086 above) from your input history into a single string. This variable
2087 acts like an automatic function which re-executes those lines as if
2087 acts like an automatic function which re-executes those lines as if
2088 you had typed them. You just type 'name' at the prompt and the code
2088 you had typed them. You just type 'name' at the prompt and the code
2089 executes.
2089 executes.
2090
2090
2091 The notation for indicating number ranges is: n1-n2 means 'use line
2091 The notation for indicating number ranges is: n1-n2 means 'use line
2092 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2092 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2093 using the lines numbered 5,6 and 7.
2093 using the lines numbered 5,6 and 7.
2094
2094
2095 Note: as a 'hidden' feature, you can also use traditional python slice
2095 Note: as a 'hidden' feature, you can also use traditional python slice
2096 notation, where N:M means numbers N through M-1.
2096 notation, where N:M means numbers N through M-1.
2097
2097
2098 For example, if your history contains (%hist prints it):
2098 For example, if your history contains (%hist prints it):
2099
2099
2100 44: x=1
2100 44: x=1
2101 45: y=3
2101 45: y=3
2102 46: z=x+y
2102 46: z=x+y
2103 47: print x
2103 47: print x
2104 48: a=5
2104 48: a=5
2105 49: print 'x',x,'y',y
2105 49: print 'x',x,'y',y
2106
2106
2107 you can create a macro with lines 44 through 47 (included) and line 49
2107 you can create a macro with lines 44 through 47 (included) and line 49
2108 called my_macro with:
2108 called my_macro with:
2109
2109
2110 In [55]: %macro my_macro 44-47 49
2110 In [55]: %macro my_macro 44-47 49
2111
2111
2112 Now, typing `my_macro` (without quotes) will re-execute all this code
2112 Now, typing `my_macro` (without quotes) will re-execute all this code
2113 in one pass.
2113 in one pass.
2114
2114
2115 You don't need to give the line-numbers in order, and any given line
2115 You don't need to give the line-numbers in order, and any given line
2116 number can appear multiple times. You can assemble macros with any
2116 number can appear multiple times. You can assemble macros with any
2117 lines from your input history in any order.
2117 lines from your input history in any order.
2118
2118
2119 The macro is a simple object which holds its value in an attribute,
2119 The macro is a simple object which holds its value in an attribute,
2120 but IPython's display system checks for macros and executes them as
2120 but IPython's display system checks for macros and executes them as
2121 code instead of printing them when you type their name.
2121 code instead of printing them when you type their name.
2122
2122
2123 You can view a macro's contents by explicitly printing it with:
2123 You can view a macro's contents by explicitly printing it with:
2124
2124
2125 'print macro_name'.
2125 'print macro_name'.
2126
2126
2127 For one-off cases which DON'T contain magic function calls in them you
2127 For one-off cases which DON'T contain magic function calls in them you
2128 can obtain similar results by explicitly executing slices from your
2128 can obtain similar results by explicitly executing slices from your
2129 input history with:
2129 input history with:
2130
2130
2131 In [60]: exec In[44:48]+In[49]"""
2131 In [60]: exec In[44:48]+In[49]"""
2132
2132
2133 opts,args = self.parse_options(parameter_s,'r',mode='list')
2133 opts,args = self.parse_options(parameter_s,'r',mode='list')
2134 if not args:
2134 if not args:
2135 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2135 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2136 macs.sort()
2136 macs.sort()
2137 return macs
2137 return macs
2138 if len(args) == 1:
2138 if len(args) == 1:
2139 raise UsageError(
2139 raise UsageError(
2140 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2140 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2141 name,ranges = args[0], args[1:]
2141 name,ranges = args[0], args[1:]
2142
2142
2143 #print 'rng',ranges # dbg
2143 #print 'rng',ranges # dbg
2144 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2144 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2145 macro = Macro(lines)
2145 macro = Macro(lines)
2146 self.shell.define_macro(name, macro)
2146 self.shell.define_macro(name, macro)
2147 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2147 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2148 print 'Macro contents:'
2148 print 'Macro contents:'
2149 print macro,
2149 print macro,
2150
2150
2151 def magic_save(self,parameter_s = ''):
2151 def magic_save(self,parameter_s = ''):
2152 """Save a set of lines to a given filename.
2152 """Save a set of lines to a given filename.
2153
2153
2154 Usage:\\
2154 Usage:\\
2155 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2155 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2156
2156
2157 Options:
2157 Options:
2158
2158
2159 -r: use 'raw' input. By default, the 'processed' history is used,
2159 -r: use 'raw' input. By default, the 'processed' history is used,
2160 so that magics are loaded in their transformed version to valid
2160 so that magics are loaded in their transformed version to valid
2161 Python. If this option is given, the raw input as typed as the
2161 Python. If this option is given, the raw input as typed as the
2162 command line is used instead.
2162 command line is used instead.
2163
2163
2164 This function uses the same syntax as %macro for line extraction, but
2164 This function uses the same syntax as %macro for line extraction, but
2165 instead of creating a macro it saves the resulting string to the
2165 instead of creating a macro it saves the resulting string to the
2166 filename you specify.
2166 filename you specify.
2167
2167
2168 It adds a '.py' extension to the file if you don't do so yourself, and
2168 It adds a '.py' extension to the file if you don't do so yourself, and
2169 it asks for confirmation before overwriting existing files."""
2169 it asks for confirmation before overwriting existing files."""
2170
2170
2171 opts,args = self.parse_options(parameter_s,'r',mode='list')
2171 opts,args = self.parse_options(parameter_s,'r',mode='list')
2172 fname,ranges = args[0], args[1:]
2172 fname,ranges = args[0], args[1:]
2173 if not fname.endswith('.py'):
2173 if not fname.endswith('.py'):
2174 fname += '.py'
2174 fname += '.py'
2175 if os.path.isfile(fname):
2175 if os.path.isfile(fname):
2176 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2176 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2177 if ans.lower() not in ['y','yes']:
2177 if ans.lower() not in ['y','yes']:
2178 print 'Operation cancelled.'
2178 print 'Operation cancelled.'
2179 return
2179 return
2180 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2180 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2181 f = file(fname,'w')
2181 f = file(fname,'w')
2182 f.write(cmds)
2182 f.write(cmds)
2183 f.close()
2183 f.close()
2184 print 'The following commands were written to file `%s`:' % fname
2184 print 'The following commands were written to file `%s`:' % fname
2185 print cmds
2185 print cmds
2186
2186
2187 def _edit_macro(self,mname,macro):
2187 def _edit_macro(self,mname,macro):
2188 """open an editor with the macro data in a file"""
2188 """open an editor with the macro data in a file"""
2189 filename = self.shell.mktempfile(macro.value)
2189 filename = self.shell.mktempfile(macro.value)
2190 self.shell.hooks.editor(filename)
2190 self.shell.hooks.editor(filename)
2191
2191
2192 # and make a new macro object, to replace the old one
2192 # and make a new macro object, to replace the old one
2193 mfile = open(filename)
2193 mfile = open(filename)
2194 mvalue = mfile.read()
2194 mvalue = mfile.read()
2195 mfile.close()
2195 mfile.close()
2196 self.shell.user_ns[mname] = Macro(mvalue)
2196 self.shell.user_ns[mname] = Macro(mvalue)
2197
2197
2198 def magic_ed(self,parameter_s=''):
2198 def magic_ed(self,parameter_s=''):
2199 """Alias to %edit."""
2199 """Alias to %edit."""
2200 return self.magic_edit(parameter_s)
2200 return self.magic_edit(parameter_s)
2201
2201
2202 @testdec.skip_doctest
2202 @testdec.skip_doctest
2203 def magic_edit(self,parameter_s='',last_call=['','']):
2203 def magic_edit(self,parameter_s='',last_call=['','']):
2204 """Bring up an editor and execute the resulting code.
2204 """Bring up an editor and execute the resulting code.
2205
2205
2206 Usage:
2206 Usage:
2207 %edit [options] [args]
2207 %edit [options] [args]
2208
2208
2209 %edit runs IPython's editor hook. The default version of this hook is
2209 %edit runs IPython's editor hook. The default version of this hook is
2210 set to call the __IPYTHON__.rc.editor command. This is read from your
2210 set to call the __IPYTHON__.rc.editor command. This is read from your
2211 environment variable $EDITOR. If this isn't found, it will default to
2211 environment variable $EDITOR. If this isn't found, it will default to
2212 vi under Linux/Unix and to notepad under Windows. See the end of this
2212 vi under Linux/Unix and to notepad under Windows. See the end of this
2213 docstring for how to change the editor hook.
2213 docstring for how to change the editor hook.
2214
2214
2215 You can also set the value of this editor via the command line option
2215 You can also set the value of this editor via the command line option
2216 '-editor' or in your ipythonrc file. This is useful if you wish to use
2216 '-editor' or in your ipythonrc file. This is useful if you wish to use
2217 specifically for IPython an editor different from your typical default
2217 specifically for IPython an editor different from your typical default
2218 (and for Windows users who typically don't set environment variables).
2218 (and for Windows users who typically don't set environment variables).
2219
2219
2220 This command allows you to conveniently edit multi-line code right in
2220 This command allows you to conveniently edit multi-line code right in
2221 your IPython session.
2221 your IPython session.
2222
2222
2223 If called without arguments, %edit opens up an empty editor with a
2223 If called without arguments, %edit opens up an empty editor with a
2224 temporary file and will execute the contents of this file when you
2224 temporary file and will execute the contents of this file when you
2225 close it (don't forget to save it!).
2225 close it (don't forget to save it!).
2226
2226
2227
2227
2228 Options:
2228 Options:
2229
2229
2230 -n <number>: open the editor at a specified line number. By default,
2230 -n <number>: open the editor at a specified line number. By default,
2231 the IPython editor hook uses the unix syntax 'editor +N filename', but
2231 the IPython editor hook uses the unix syntax 'editor +N filename', but
2232 you can configure this by providing your own modified hook if your
2232 you can configure this by providing your own modified hook if your
2233 favorite editor supports line-number specifications with a different
2233 favorite editor supports line-number specifications with a different
2234 syntax.
2234 syntax.
2235
2235
2236 -p: this will call the editor with the same data as the previous time
2236 -p: this will call the editor with the same data as the previous time
2237 it was used, regardless of how long ago (in your current session) it
2237 it was used, regardless of how long ago (in your current session) it
2238 was.
2238 was.
2239
2239
2240 -r: use 'raw' input. This option only applies to input taken from the
2240 -r: use 'raw' input. This option only applies to input taken from the
2241 user's history. By default, the 'processed' history is used, so that
2241 user's history. By default, the 'processed' history is used, so that
2242 magics are loaded in their transformed version to valid Python. If
2242 magics are loaded in their transformed version to valid Python. If
2243 this option is given, the raw input as typed as the command line is
2243 this option is given, the raw input as typed as the command line is
2244 used instead. When you exit the editor, it will be executed by
2244 used instead. When you exit the editor, it will be executed by
2245 IPython's own processor.
2245 IPython's own processor.
2246
2246
2247 -x: do not execute the edited code immediately upon exit. This is
2247 -x: do not execute the edited code immediately upon exit. This is
2248 mainly useful if you are editing programs which need to be called with
2248 mainly useful if you are editing programs which need to be called with
2249 command line arguments, which you can then do using %run.
2249 command line arguments, which you can then do using %run.
2250
2250
2251
2251
2252 Arguments:
2252 Arguments:
2253
2253
2254 If arguments are given, the following possibilites exist:
2254 If arguments are given, the following possibilites exist:
2255
2255
2256 - The arguments are numbers or pairs of colon-separated numbers (like
2256 - The arguments are numbers or pairs of colon-separated numbers (like
2257 1 4:8 9). These are interpreted as lines of previous input to be
2257 1 4:8 9). These are interpreted as lines of previous input to be
2258 loaded into the editor. The syntax is the same of the %macro command.
2258 loaded into the editor. The syntax is the same of the %macro command.
2259
2259
2260 - If the argument doesn't start with a number, it is evaluated as a
2260 - If the argument doesn't start with a number, it is evaluated as a
2261 variable and its contents loaded into the editor. You can thus edit
2261 variable and its contents loaded into the editor. You can thus edit
2262 any string which contains python code (including the result of
2262 any string which contains python code (including the result of
2263 previous edits).
2263 previous edits).
2264
2264
2265 - If the argument is the name of an object (other than a string),
2265 - If the argument is the name of an object (other than a string),
2266 IPython will try to locate the file where it was defined and open the
2266 IPython will try to locate the file where it was defined and open the
2267 editor at the point where it is defined. You can use `%edit function`
2267 editor at the point where it is defined. You can use `%edit function`
2268 to load an editor exactly at the point where 'function' is defined,
2268 to load an editor exactly at the point where 'function' is defined,
2269 edit it and have the file be executed automatically.
2269 edit it and have the file be executed automatically.
2270
2270
2271 If the object is a macro (see %macro for details), this opens up your
2271 If the object is a macro (see %macro for details), this opens up your
2272 specified editor with a temporary file containing the macro's data.
2272 specified editor with a temporary file containing the macro's data.
2273 Upon exit, the macro is reloaded with the contents of the file.
2273 Upon exit, the macro is reloaded with the contents of the file.
2274
2274
2275 Note: opening at an exact line is only supported under Unix, and some
2275 Note: opening at an exact line is only supported under Unix, and some
2276 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2276 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2277 '+NUMBER' parameter necessary for this feature. Good editors like
2277 '+NUMBER' parameter necessary for this feature. Good editors like
2278 (X)Emacs, vi, jed, pico and joe all do.
2278 (X)Emacs, vi, jed, pico and joe all do.
2279
2279
2280 - If the argument is not found as a variable, IPython will look for a
2280 - If the argument is not found as a variable, IPython will look for a
2281 file with that name (adding .py if necessary) and load it into the
2281 file with that name (adding .py if necessary) and load it into the
2282 editor. It will execute its contents with execfile() when you exit,
2282 editor. It will execute its contents with execfile() when you exit,
2283 loading any code in the file into your interactive namespace.
2283 loading any code in the file into your interactive namespace.
2284
2284
2285 After executing your code, %edit will return as output the code you
2285 After executing your code, %edit will return as output the code you
2286 typed in the editor (except when it was an existing file). This way
2286 typed in the editor (except when it was an existing file). This way
2287 you can reload the code in further invocations of %edit as a variable,
2287 you can reload the code in further invocations of %edit as a variable,
2288 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2288 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2289 the output.
2289 the output.
2290
2290
2291 Note that %edit is also available through the alias %ed.
2291 Note that %edit is also available through the alias %ed.
2292
2292
2293 This is an example of creating a simple function inside the editor and
2293 This is an example of creating a simple function inside the editor and
2294 then modifying it. First, start up the editor:
2294 then modifying it. First, start up the editor:
2295
2295
2296 In [1]: ed
2296 In [1]: ed
2297 Editing... done. Executing edited code...
2297 Editing... done. Executing edited code...
2298 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2298 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2299
2299
2300 We can then call the function foo():
2300 We can then call the function foo():
2301
2301
2302 In [2]: foo()
2302 In [2]: foo()
2303 foo() was defined in an editing session
2303 foo() was defined in an editing session
2304
2304
2305 Now we edit foo. IPython automatically loads the editor with the
2305 Now we edit foo. IPython automatically loads the editor with the
2306 (temporary) file where foo() was previously defined:
2306 (temporary) file where foo() was previously defined:
2307
2307
2308 In [3]: ed foo
2308 In [3]: ed foo
2309 Editing... done. Executing edited code...
2309 Editing... done. Executing edited code...
2310
2310
2311 And if we call foo() again we get the modified version:
2311 And if we call foo() again we get the modified version:
2312
2312
2313 In [4]: foo()
2313 In [4]: foo()
2314 foo() has now been changed!
2314 foo() has now been changed!
2315
2315
2316 Here is an example of how to edit a code snippet successive
2316 Here is an example of how to edit a code snippet successive
2317 times. First we call the editor:
2317 times. First we call the editor:
2318
2318
2319 In [5]: ed
2319 In [5]: ed
2320 Editing... done. Executing edited code...
2320 Editing... done. Executing edited code...
2321 hello
2321 hello
2322 Out[5]: "print 'hello'n"
2322 Out[5]: "print 'hello'n"
2323
2323
2324 Now we call it again with the previous output (stored in _):
2324 Now we call it again with the previous output (stored in _):
2325
2325
2326 In [6]: ed _
2326 In [6]: ed _
2327 Editing... done. Executing edited code...
2327 Editing... done. Executing edited code...
2328 hello world
2328 hello world
2329 Out[6]: "print 'hello world'n"
2329 Out[6]: "print 'hello world'n"
2330
2330
2331 Now we call it with the output #8 (stored in _8, also as Out[8]):
2331 Now we call it with the output #8 (stored in _8, also as Out[8]):
2332
2332
2333 In [7]: ed _8
2333 In [7]: ed _8
2334 Editing... done. Executing edited code...
2334 Editing... done. Executing edited code...
2335 hello again
2335 hello again
2336 Out[7]: "print 'hello again'n"
2336 Out[7]: "print 'hello again'n"
2337
2337
2338
2338
2339 Changing the default editor hook:
2339 Changing the default editor hook:
2340
2340
2341 If you wish to write your own editor hook, you can put it in a
2341 If you wish to write your own editor hook, you can put it in a
2342 configuration file which you load at startup time. The default hook
2342 configuration file which you load at startup time. The default hook
2343 is defined in the IPython.core.hooks module, and you can use that as a
2343 is defined in the IPython.core.hooks module, and you can use that as a
2344 starting example for further modifications. That file also has
2344 starting example for further modifications. That file also has
2345 general instructions on how to set a new hook for use once you've
2345 general instructions on how to set a new hook for use once you've
2346 defined it."""
2346 defined it."""
2347
2347
2348 # FIXME: This function has become a convoluted mess. It needs a
2348 # FIXME: This function has become a convoluted mess. It needs a
2349 # ground-up rewrite with clean, simple logic.
2349 # ground-up rewrite with clean, simple logic.
2350
2350
2351 def make_filename(arg):
2351 def make_filename(arg):
2352 "Make a filename from the given args"
2352 "Make a filename from the given args"
2353 try:
2353 try:
2354 filename = get_py_filename(arg)
2354 filename = get_py_filename(arg)
2355 except IOError:
2355 except IOError:
2356 if args.endswith('.py'):
2356 if args.endswith('.py'):
2357 filename = arg
2357 filename = arg
2358 else:
2358 else:
2359 filename = None
2359 filename = None
2360 return filename
2360 return filename
2361
2361
2362 # custom exceptions
2362 # custom exceptions
2363 class DataIsObject(Exception): pass
2363 class DataIsObject(Exception): pass
2364
2364
2365 opts,args = self.parse_options(parameter_s,'prxn:')
2365 opts,args = self.parse_options(parameter_s,'prxn:')
2366 # Set a few locals from the options for convenience:
2366 # Set a few locals from the options for convenience:
2367 opts_p = opts.has_key('p')
2367 opts_p = opts.has_key('p')
2368 opts_r = opts.has_key('r')
2368 opts_r = opts.has_key('r')
2369
2369
2370 # Default line number value
2370 # Default line number value
2371 lineno = opts.get('n',None)
2371 lineno = opts.get('n',None)
2372
2372
2373 if opts_p:
2373 if opts_p:
2374 args = '_%s' % last_call[0]
2374 args = '_%s' % last_call[0]
2375 if not self.shell.user_ns.has_key(args):
2375 if not self.shell.user_ns.has_key(args):
2376 args = last_call[1]
2376 args = last_call[1]
2377
2377
2378 # use last_call to remember the state of the previous call, but don't
2378 # use last_call to remember the state of the previous call, but don't
2379 # let it be clobbered by successive '-p' calls.
2379 # let it be clobbered by successive '-p' calls.
2380 try:
2380 try:
2381 last_call[0] = self.shell.displayhook.prompt_count
2381 last_call[0] = self.shell.displayhook.prompt_count
2382 if not opts_p:
2382 if not opts_p:
2383 last_call[1] = parameter_s
2383 last_call[1] = parameter_s
2384 except:
2384 except:
2385 pass
2385 pass
2386
2386
2387 # by default this is done with temp files, except when the given
2387 # by default this is done with temp files, except when the given
2388 # arg is a filename
2388 # arg is a filename
2389 use_temp = 1
2389 use_temp = 1
2390
2390
2391 if re.match(r'\d',args):
2391 if re.match(r'\d',args):
2392 # Mode where user specifies ranges of lines, like in %macro.
2392 # Mode where user specifies ranges of lines, like in %macro.
2393 # This means that you can't edit files whose names begin with
2393 # This means that you can't edit files whose names begin with
2394 # numbers this way. Tough.
2394 # numbers this way. Tough.
2395 ranges = args.split()
2395 ranges = args.split()
2396 data = ''.join(self.extract_input_slices(ranges,opts_r))
2396 data = ''.join(self.extract_input_slices(ranges,opts_r))
2397 elif args.endswith('.py'):
2397 elif args.endswith('.py'):
2398 filename = make_filename(args)
2398 filename = make_filename(args)
2399 data = ''
2399 data = ''
2400 use_temp = 0
2400 use_temp = 0
2401 elif args:
2401 elif args:
2402 try:
2402 try:
2403 # Load the parameter given as a variable. If not a string,
2403 # Load the parameter given as a variable. If not a string,
2404 # process it as an object instead (below)
2404 # process it as an object instead (below)
2405
2405
2406 #print '*** args',args,'type',type(args) # dbg
2406 #print '*** args',args,'type',type(args) # dbg
2407 data = eval(args,self.shell.user_ns)
2407 data = eval(args,self.shell.user_ns)
2408 if not type(data) in StringTypes:
2408 if not type(data) in StringTypes:
2409 raise DataIsObject
2409 raise DataIsObject
2410
2410
2411 except (NameError,SyntaxError):
2411 except (NameError,SyntaxError):
2412 # given argument is not a variable, try as a filename
2412 # given argument is not a variable, try as a filename
2413 filename = make_filename(args)
2413 filename = make_filename(args)
2414 if filename is None:
2414 if filename is None:
2415 warn("Argument given (%s) can't be found as a variable "
2415 warn("Argument given (%s) can't be found as a variable "
2416 "or as a filename." % args)
2416 "or as a filename." % args)
2417 return
2417 return
2418
2418
2419 data = ''
2419 data = ''
2420 use_temp = 0
2420 use_temp = 0
2421 except DataIsObject:
2421 except DataIsObject:
2422
2422
2423 # macros have a special edit function
2423 # macros have a special edit function
2424 if isinstance(data,Macro):
2424 if isinstance(data,Macro):
2425 self._edit_macro(args,data)
2425 self._edit_macro(args,data)
2426 return
2426 return
2427
2427
2428 # For objects, try to edit the file where they are defined
2428 # For objects, try to edit the file where they are defined
2429 try:
2429 try:
2430 filename = inspect.getabsfile(data)
2430 filename = inspect.getabsfile(data)
2431 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2431 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2432 # class created by %edit? Try to find source
2432 # class created by %edit? Try to find source
2433 # by looking for method definitions instead, the
2433 # by looking for method definitions instead, the
2434 # __module__ in those classes is FakeModule.
2434 # __module__ in those classes is FakeModule.
2435 attrs = [getattr(data, aname) for aname in dir(data)]
2435 attrs = [getattr(data, aname) for aname in dir(data)]
2436 for attr in attrs:
2436 for attr in attrs:
2437 if not inspect.ismethod(attr):
2437 if not inspect.ismethod(attr):
2438 continue
2438 continue
2439 filename = inspect.getabsfile(attr)
2439 filename = inspect.getabsfile(attr)
2440 if filename and 'fakemodule' not in filename.lower():
2440 if filename and 'fakemodule' not in filename.lower():
2441 # change the attribute to be the edit target instead
2441 # change the attribute to be the edit target instead
2442 data = attr
2442 data = attr
2443 break
2443 break
2444
2444
2445 datafile = 1
2445 datafile = 1
2446 except TypeError:
2446 except TypeError:
2447 filename = make_filename(args)
2447 filename = make_filename(args)
2448 datafile = 1
2448 datafile = 1
2449 warn('Could not find file where `%s` is defined.\n'
2449 warn('Could not find file where `%s` is defined.\n'
2450 'Opening a file named `%s`' % (args,filename))
2450 'Opening a file named `%s`' % (args,filename))
2451 # Now, make sure we can actually read the source (if it was in
2451 # Now, make sure we can actually read the source (if it was in
2452 # a temp file it's gone by now).
2452 # a temp file it's gone by now).
2453 if datafile:
2453 if datafile:
2454 try:
2454 try:
2455 if lineno is None:
2455 if lineno is None:
2456 lineno = inspect.getsourcelines(data)[1]
2456 lineno = inspect.getsourcelines(data)[1]
2457 except IOError:
2457 except IOError:
2458 filename = make_filename(args)
2458 filename = make_filename(args)
2459 if filename is None:
2459 if filename is None:
2460 warn('The file `%s` where `%s` was defined cannot '
2460 warn('The file `%s` where `%s` was defined cannot '
2461 'be read.' % (filename,data))
2461 'be read.' % (filename,data))
2462 return
2462 return
2463 use_temp = 0
2463 use_temp = 0
2464 else:
2464 else:
2465 data = ''
2465 data = ''
2466
2466
2467 if use_temp:
2467 if use_temp:
2468 filename = self.shell.mktempfile(data)
2468 filename = self.shell.mktempfile(data)
2469 print 'IPython will make a temporary file named:',filename
2469 print 'IPython will make a temporary file named:',filename
2470
2470
2471 # do actual editing here
2471 # do actual editing here
2472 print 'Editing...',
2472 print 'Editing...',
2473 sys.stdout.flush()
2473 sys.stdout.flush()
2474 try:
2474 try:
2475 # Quote filenames that may have spaces in them
2475 # Quote filenames that may have spaces in them
2476 if ' ' in filename:
2476 if ' ' in filename:
2477 filename = "%s" % filename
2477 filename = "%s" % filename
2478 self.shell.hooks.editor(filename,lineno)
2478 self.shell.hooks.editor(filename,lineno)
2479 except TryNext:
2479 except TryNext:
2480 warn('Could not open editor')
2480 warn('Could not open editor')
2481 return
2481 return
2482
2482
2483 # XXX TODO: should this be generalized for all string vars?
2483 # XXX TODO: should this be generalized for all string vars?
2484 # For now, this is special-cased to blocks created by cpaste
2484 # For now, this is special-cased to blocks created by cpaste
2485 if args.strip() == 'pasted_block':
2485 if args.strip() == 'pasted_block':
2486 self.shell.user_ns['pasted_block'] = file_read(filename)
2486 self.shell.user_ns['pasted_block'] = file_read(filename)
2487
2487
2488 if opts.has_key('x'): # -x prevents actual execution
2488 if opts.has_key('x'): # -x prevents actual execution
2489 print
2489 print
2490 else:
2490 else:
2491 print 'done. Executing edited code...'
2491 print 'done. Executing edited code...'
2492 if opts_r:
2492 if opts_r:
2493 self.shell.runlines(file_read(filename))
2493 self.shell.runlines(file_read(filename))
2494 else:
2494 else:
2495 self.shell.safe_execfile(filename,self.shell.user_ns,
2495 self.shell.safe_execfile(filename,self.shell.user_ns,
2496 self.shell.user_ns)
2496 self.shell.user_ns)
2497
2497
2498
2498
2499 if use_temp:
2499 if use_temp:
2500 try:
2500 try:
2501 return open(filename).read()
2501 return open(filename).read()
2502 except IOError,msg:
2502 except IOError,msg:
2503 if msg.filename == filename:
2503 if msg.filename == filename:
2504 warn('File not found. Did you forget to save?')
2504 warn('File not found. Did you forget to save?')
2505 return
2505 return
2506 else:
2506 else:
2507 self.shell.showtraceback()
2507 self.shell.showtraceback()
2508
2508
2509 def magic_xmode(self,parameter_s = ''):
2509 def magic_xmode(self,parameter_s = ''):
2510 """Switch modes for the exception handlers.
2510 """Switch modes for the exception handlers.
2511
2511
2512 Valid modes: Plain, Context and Verbose.
2512 Valid modes: Plain, Context and Verbose.
2513
2513
2514 If called without arguments, acts as a toggle."""
2514 If called without arguments, acts as a toggle."""
2515
2515
2516 def xmode_switch_err(name):
2516 def xmode_switch_err(name):
2517 warn('Error changing %s exception modes.\n%s' %
2517 warn('Error changing %s exception modes.\n%s' %
2518 (name,sys.exc_info()[1]))
2518 (name,sys.exc_info()[1]))
2519
2519
2520 shell = self.shell
2520 shell = self.shell
2521 new_mode = parameter_s.strip().capitalize()
2521 new_mode = parameter_s.strip().capitalize()
2522 try:
2522 try:
2523 shell.InteractiveTB.set_mode(mode=new_mode)
2523 shell.InteractiveTB.set_mode(mode=new_mode)
2524 print 'Exception reporting mode:',shell.InteractiveTB.mode
2524 print 'Exception reporting mode:',shell.InteractiveTB.mode
2525 except:
2525 except:
2526 xmode_switch_err('user')
2526 xmode_switch_err('user')
2527
2527
2528 def magic_colors(self,parameter_s = ''):
2528 def magic_colors(self,parameter_s = ''):
2529 """Switch color scheme for prompts, info system and exception handlers.
2529 """Switch color scheme for prompts, info system and exception handlers.
2530
2530
2531 Currently implemented schemes: NoColor, Linux, LightBG.
2531 Currently implemented schemes: NoColor, Linux, LightBG.
2532
2532
2533 Color scheme names are not case-sensitive."""
2533 Color scheme names are not case-sensitive."""
2534
2534
2535 def color_switch_err(name):
2535 def color_switch_err(name):
2536 warn('Error changing %s color schemes.\n%s' %
2536 warn('Error changing %s color schemes.\n%s' %
2537 (name,sys.exc_info()[1]))
2537 (name,sys.exc_info()[1]))
2538
2538
2539
2539
2540 new_scheme = parameter_s.strip()
2540 new_scheme = parameter_s.strip()
2541 if not new_scheme:
2541 if not new_scheme:
2542 raise UsageError(
2542 raise UsageError(
2543 "%colors: you must specify a color scheme. See '%colors?'")
2543 "%colors: you must specify a color scheme. See '%colors?'")
2544 return
2544 return
2545 # local shortcut
2545 # local shortcut
2546 shell = self.shell
2546 shell = self.shell
2547
2547
2548 import IPython.utils.rlineimpl as readline
2548 import IPython.utils.rlineimpl as readline
2549
2549
2550 if not readline.have_readline and sys.platform == "win32":
2550 if not readline.have_readline and sys.platform == "win32":
2551 msg = """\
2551 msg = """\
2552 Proper color support under MS Windows requires the pyreadline library.
2552 Proper color support under MS Windows requires the pyreadline library.
2553 You can find it at:
2553 You can find it at:
2554 http://ipython.scipy.org/moin/PyReadline/Intro
2554 http://ipython.scipy.org/moin/PyReadline/Intro
2555 Gary's readline needs the ctypes module, from:
2555 Gary's readline needs the ctypes module, from:
2556 http://starship.python.net/crew/theller/ctypes
2556 http://starship.python.net/crew/theller/ctypes
2557 (Note that ctypes is already part of Python versions 2.5 and newer).
2557 (Note that ctypes is already part of Python versions 2.5 and newer).
2558
2558
2559 Defaulting color scheme to 'NoColor'"""
2559 Defaulting color scheme to 'NoColor'"""
2560 new_scheme = 'NoColor'
2560 new_scheme = 'NoColor'
2561 warn(msg)
2561 warn(msg)
2562
2562
2563 # readline option is 0
2563 # readline option is 0
2564 if not shell.has_readline:
2564 if not shell.has_readline:
2565 new_scheme = 'NoColor'
2565 new_scheme = 'NoColor'
2566
2566
2567 # Set prompt colors
2567 # Set prompt colors
2568 try:
2568 try:
2569 shell.displayhook.set_colors(new_scheme)
2569 shell.displayhook.set_colors(new_scheme)
2570 except:
2570 except:
2571 color_switch_err('prompt')
2571 color_switch_err('prompt')
2572 else:
2572 else:
2573 shell.colors = \
2573 shell.colors = \
2574 shell.displayhook.color_table.active_scheme_name
2574 shell.displayhook.color_table.active_scheme_name
2575 # Set exception colors
2575 # Set exception colors
2576 try:
2576 try:
2577 shell.InteractiveTB.set_colors(scheme = new_scheme)
2577 shell.InteractiveTB.set_colors(scheme = new_scheme)
2578 shell.SyntaxTB.set_colors(scheme = new_scheme)
2578 shell.SyntaxTB.set_colors(scheme = new_scheme)
2579 except:
2579 except:
2580 color_switch_err('exception')
2580 color_switch_err('exception')
2581
2581
2582 # Set info (for 'object?') colors
2582 # Set info (for 'object?') colors
2583 if shell.color_info:
2583 if shell.color_info:
2584 try:
2584 try:
2585 shell.inspector.set_active_scheme(new_scheme)
2585 shell.inspector.set_active_scheme(new_scheme)
2586 except:
2586 except:
2587 color_switch_err('object inspector')
2587 color_switch_err('object inspector')
2588 else:
2588 else:
2589 shell.inspector.set_active_scheme('NoColor')
2589 shell.inspector.set_active_scheme('NoColor')
2590
2590
2591 def magic_color_info(self,parameter_s = ''):
2591 def magic_color_info(self,parameter_s = ''):
2592 """Toggle color_info.
2592 """Toggle color_info.
2593
2593
2594 The color_info configuration parameter controls whether colors are
2594 The color_info configuration parameter controls whether colors are
2595 used for displaying object details (by things like %psource, %pfile or
2595 used for displaying object details (by things like %psource, %pfile or
2596 the '?' system). This function toggles this value with each call.
2596 the '?' system). This function toggles this value with each call.
2597
2597
2598 Note that unless you have a fairly recent pager (less works better
2598 Note that unless you have a fairly recent pager (less works better
2599 than more) in your system, using colored object information displays
2599 than more) in your system, using colored object information displays
2600 will not work properly. Test it and see."""
2600 will not work properly. Test it and see."""
2601
2601
2602 self.shell.color_info = not self.shell.color_info
2602 self.shell.color_info = not self.shell.color_info
2603 self.magic_colors(self.shell.colors)
2603 self.magic_colors(self.shell.colors)
2604 print 'Object introspection functions have now coloring:',
2604 print 'Object introspection functions have now coloring:',
2605 print ['OFF','ON'][int(self.shell.color_info)]
2605 print ['OFF','ON'][int(self.shell.color_info)]
2606
2606
2607 def magic_Pprint(self, parameter_s=''):
2607 def magic_Pprint(self, parameter_s=''):
2608 """Toggle pretty printing on/off."""
2608 """Toggle pretty printing on/off."""
2609
2609
2610 self.shell.pprint = 1 - self.shell.pprint
2610 self.shell.pprint = 1 - self.shell.pprint
2611 print 'Pretty printing has been turned', \
2611 print 'Pretty printing has been turned', \
2612 ['OFF','ON'][self.shell.pprint]
2612 ['OFF','ON'][self.shell.pprint]
2613
2613
2614 def magic_Exit(self, parameter_s=''):
2614 def magic_Exit(self, parameter_s=''):
2615 """Exit IPython without confirmation."""
2615 """Exit IPython without confirmation."""
2616
2616
2617 self.shell.ask_exit()
2617 self.shell.ask_exit()
2618
2618
2619 # Add aliases as magics so all common forms work: exit, quit, Exit, Quit.
2619 # Add aliases as magics so all common forms work: exit, quit, Exit, Quit.
2620 magic_exit = magic_quit = magic_Quit = magic_Exit
2620 magic_exit = magic_quit = magic_Quit = magic_Exit
2621
2621
2622 #......................................................................
2622 #......................................................................
2623 # Functions to implement unix shell-type things
2623 # Functions to implement unix shell-type things
2624
2624
2625 @testdec.skip_doctest
2625 @testdec.skip_doctest
2626 def magic_alias(self, parameter_s = ''):
2626 def magic_alias(self, parameter_s = ''):
2627 """Define an alias for a system command.
2627 """Define an alias for a system command.
2628
2628
2629 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2629 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2630
2630
2631 Then, typing 'alias_name params' will execute the system command 'cmd
2631 Then, typing 'alias_name params' will execute the system command 'cmd
2632 params' (from your underlying operating system).
2632 params' (from your underlying operating system).
2633
2633
2634 Aliases have lower precedence than magic functions and Python normal
2634 Aliases have lower precedence than magic functions and Python normal
2635 variables, so if 'foo' is both a Python variable and an alias, the
2635 variables, so if 'foo' is both a Python variable and an alias, the
2636 alias can not be executed until 'del foo' removes the Python variable.
2636 alias can not be executed until 'del foo' removes the Python variable.
2637
2637
2638 You can use the %l specifier in an alias definition to represent the
2638 You can use the %l specifier in an alias definition to represent the
2639 whole line when the alias is called. For example:
2639 whole line when the alias is called. For example:
2640
2640
2641 In [2]: alias all echo "Input in brackets: <%l>"
2641 In [2]: alias all echo "Input in brackets: <%l>"
2642 In [3]: all hello world
2642 In [3]: all hello world
2643 Input in brackets: <hello world>
2643 Input in brackets: <hello world>
2644
2644
2645 You can also define aliases with parameters using %s specifiers (one
2645 You can also define aliases with parameters using %s specifiers (one
2646 per parameter):
2646 per parameter):
2647
2647
2648 In [1]: alias parts echo first %s second %s
2648 In [1]: alias parts echo first %s second %s
2649 In [2]: %parts A B
2649 In [2]: %parts A B
2650 first A second B
2650 first A second B
2651 In [3]: %parts A
2651 In [3]: %parts A
2652 Incorrect number of arguments: 2 expected.
2652 Incorrect number of arguments: 2 expected.
2653 parts is an alias to: 'echo first %s second %s'
2653 parts is an alias to: 'echo first %s second %s'
2654
2654
2655 Note that %l and %s are mutually exclusive. You can only use one or
2655 Note that %l and %s are mutually exclusive. You can only use one or
2656 the other in your aliases.
2656 the other in your aliases.
2657
2657
2658 Aliases expand Python variables just like system calls using ! or !!
2658 Aliases expand Python variables just like system calls using ! or !!
2659 do: all expressions prefixed with '$' get expanded. For details of
2659 do: all expressions prefixed with '$' get expanded. For details of
2660 the semantic rules, see PEP-215:
2660 the semantic rules, see PEP-215:
2661 http://www.python.org/peps/pep-0215.html. This is the library used by
2661 http://www.python.org/peps/pep-0215.html. This is the library used by
2662 IPython for variable expansion. If you want to access a true shell
2662 IPython for variable expansion. If you want to access a true shell
2663 variable, an extra $ is necessary to prevent its expansion by IPython:
2663 variable, an extra $ is necessary to prevent its expansion by IPython:
2664
2664
2665 In [6]: alias show echo
2665 In [6]: alias show echo
2666 In [7]: PATH='A Python string'
2666 In [7]: PATH='A Python string'
2667 In [8]: show $PATH
2667 In [8]: show $PATH
2668 A Python string
2668 A Python string
2669 In [9]: show $$PATH
2669 In [9]: show $$PATH
2670 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2670 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2671
2671
2672 You can use the alias facility to acess all of $PATH. See the %rehash
2672 You can use the alias facility to acess all of $PATH. See the %rehash
2673 and %rehashx functions, which automatically create aliases for the
2673 and %rehashx functions, which automatically create aliases for the
2674 contents of your $PATH.
2674 contents of your $PATH.
2675
2675
2676 If called with no parameters, %alias prints the current alias table."""
2676 If called with no parameters, %alias prints the current alias table."""
2677
2677
2678 par = parameter_s.strip()
2678 par = parameter_s.strip()
2679 if not par:
2679 if not par:
2680 stored = self.db.get('stored_aliases', {} )
2680 stored = self.db.get('stored_aliases', {} )
2681 aliases = sorted(self.shell.alias_manager.aliases)
2681 aliases = sorted(self.shell.alias_manager.aliases)
2682 # for k, v in stored:
2682 # for k, v in stored:
2683 # atab.append(k, v[0])
2683 # atab.append(k, v[0])
2684
2684
2685 print "Total number of aliases:", len(aliases)
2685 print "Total number of aliases:", len(aliases)
2686 return aliases
2686 return aliases
2687
2687
2688 # Now try to define a new one
2688 # Now try to define a new one
2689 try:
2689 try:
2690 alias,cmd = par.split(None, 1)
2690 alias,cmd = par.split(None, 1)
2691 except:
2691 except:
2692 print oinspect.getdoc(self.magic_alias)
2692 print oinspect.getdoc(self.magic_alias)
2693 else:
2693 else:
2694 self.shell.alias_manager.soft_define_alias(alias, cmd)
2694 self.shell.alias_manager.soft_define_alias(alias, cmd)
2695 # end magic_alias
2695 # end magic_alias
2696
2696
2697 def magic_unalias(self, parameter_s = ''):
2697 def magic_unalias(self, parameter_s = ''):
2698 """Remove an alias"""
2698 """Remove an alias"""
2699
2699
2700 aname = parameter_s.strip()
2700 aname = parameter_s.strip()
2701 self.shell.alias_manager.undefine_alias(aname)
2701 self.shell.alias_manager.undefine_alias(aname)
2702 stored = self.db.get('stored_aliases', {} )
2702 stored = self.db.get('stored_aliases', {} )
2703 if aname in stored:
2703 if aname in stored:
2704 print "Removing %stored alias",aname
2704 print "Removing %stored alias",aname
2705 del stored[aname]
2705 del stored[aname]
2706 self.db['stored_aliases'] = stored
2706 self.db['stored_aliases'] = stored
2707
2707
2708
2708
2709 def magic_rehashx(self, parameter_s = ''):
2709 def magic_rehashx(self, parameter_s = ''):
2710 """Update the alias table with all executable files in $PATH.
2710 """Update the alias table with all executable files in $PATH.
2711
2711
2712 This version explicitly checks that every entry in $PATH is a file
2712 This version explicitly checks that every entry in $PATH is a file
2713 with execute access (os.X_OK), so it is much slower than %rehash.
2713 with execute access (os.X_OK), so it is much slower than %rehash.
2714
2714
2715 Under Windows, it checks executability as a match agains a
2715 Under Windows, it checks executability as a match agains a
2716 '|'-separated string of extensions, stored in the IPython config
2716 '|'-separated string of extensions, stored in the IPython config
2717 variable win_exec_ext. This defaults to 'exe|com|bat'.
2717 variable win_exec_ext. This defaults to 'exe|com|bat'.
2718
2718
2719 This function also resets the root module cache of module completer,
2719 This function also resets the root module cache of module completer,
2720 used on slow filesystems.
2720 used on slow filesystems.
2721 """
2721 """
2722 from IPython.core.alias import InvalidAliasError
2722 from IPython.core.alias import InvalidAliasError
2723
2723
2724 # for the benefit of module completer in ipy_completers.py
2724 # for the benefit of module completer in ipy_completers.py
2725 del self.db['rootmodules']
2725 del self.db['rootmodules']
2726
2726
2727 path = [os.path.abspath(os.path.expanduser(p)) for p in
2727 path = [os.path.abspath(os.path.expanduser(p)) for p in
2728 os.environ.get('PATH','').split(os.pathsep)]
2728 os.environ.get('PATH','').split(os.pathsep)]
2729 path = filter(os.path.isdir,path)
2729 path = filter(os.path.isdir,path)
2730
2730
2731 syscmdlist = []
2731 syscmdlist = []
2732 # Now define isexec in a cross platform manner.
2732 # Now define isexec in a cross platform manner.
2733 if os.name == 'posix':
2733 if os.name == 'posix':
2734 isexec = lambda fname:os.path.isfile(fname) and \
2734 isexec = lambda fname:os.path.isfile(fname) and \
2735 os.access(fname,os.X_OK)
2735 os.access(fname,os.X_OK)
2736 else:
2736 else:
2737 try:
2737 try:
2738 winext = os.environ['pathext'].replace(';','|').replace('.','')
2738 winext = os.environ['pathext'].replace(';','|').replace('.','')
2739 except KeyError:
2739 except KeyError:
2740 winext = 'exe|com|bat|py'
2740 winext = 'exe|com|bat|py'
2741 if 'py' not in winext:
2741 if 'py' not in winext:
2742 winext += '|py'
2742 winext += '|py'
2743 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2743 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2744 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2744 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2745 savedir = os.getcwd()
2745 savedir = os.getcwd()
2746
2746
2747 # Now walk the paths looking for executables to alias.
2747 # Now walk the paths looking for executables to alias.
2748 try:
2748 try:
2749 # write the whole loop for posix/Windows so we don't have an if in
2749 # write the whole loop for posix/Windows so we don't have an if in
2750 # the innermost part
2750 # the innermost part
2751 if os.name == 'posix':
2751 if os.name == 'posix':
2752 for pdir in path:
2752 for pdir in path:
2753 os.chdir(pdir)
2753 os.chdir(pdir)
2754 for ff in os.listdir(pdir):
2754 for ff in os.listdir(pdir):
2755 if isexec(ff):
2755 if isexec(ff):
2756 try:
2756 try:
2757 # Removes dots from the name since ipython
2757 # Removes dots from the name since ipython
2758 # will assume names with dots to be python.
2758 # will assume names with dots to be python.
2759 self.shell.alias_manager.define_alias(
2759 self.shell.alias_manager.define_alias(
2760 ff.replace('.',''), ff)
2760 ff.replace('.',''), ff)
2761 except InvalidAliasError:
2761 except InvalidAliasError:
2762 pass
2762 pass
2763 else:
2763 else:
2764 syscmdlist.append(ff)
2764 syscmdlist.append(ff)
2765 else:
2765 else:
2766 no_alias = self.shell.alias_manager.no_alias
2766 no_alias = self.shell.alias_manager.no_alias
2767 for pdir in path:
2767 for pdir in path:
2768 os.chdir(pdir)
2768 os.chdir(pdir)
2769 for ff in os.listdir(pdir):
2769 for ff in os.listdir(pdir):
2770 base, ext = os.path.splitext(ff)
2770 base, ext = os.path.splitext(ff)
2771 if isexec(ff) and base.lower() not in no_alias:
2771 if isexec(ff) and base.lower() not in no_alias:
2772 if ext.lower() == '.exe':
2772 if ext.lower() == '.exe':
2773 ff = base
2773 ff = base
2774 try:
2774 try:
2775 # Removes dots from the name since ipython
2775 # Removes dots from the name since ipython
2776 # will assume names with dots to be python.
2776 # will assume names with dots to be python.
2777 self.shell.alias_manager.define_alias(
2777 self.shell.alias_manager.define_alias(
2778 base.lower().replace('.',''), ff)
2778 base.lower().replace('.',''), ff)
2779 except InvalidAliasError:
2779 except InvalidAliasError:
2780 pass
2780 pass
2781 syscmdlist.append(ff)
2781 syscmdlist.append(ff)
2782 db = self.db
2782 db = self.db
2783 db['syscmdlist'] = syscmdlist
2783 db['syscmdlist'] = syscmdlist
2784 finally:
2784 finally:
2785 os.chdir(savedir)
2785 os.chdir(savedir)
2786
2786
2787 def magic_pwd(self, parameter_s = ''):
2787 def magic_pwd(self, parameter_s = ''):
2788 """Return the current working directory path."""
2788 """Return the current working directory path."""
2789 return os.getcwd()
2789 return os.getcwd()
2790
2790
2791 def magic_cd(self, parameter_s=''):
2791 def magic_cd(self, parameter_s=''):
2792 """Change the current working directory.
2792 """Change the current working directory.
2793
2793
2794 This command automatically maintains an internal list of directories
2794 This command automatically maintains an internal list of directories
2795 you visit during your IPython session, in the variable _dh. The
2795 you visit during your IPython session, in the variable _dh. The
2796 command %dhist shows this history nicely formatted. You can also
2796 command %dhist shows this history nicely formatted. You can also
2797 do 'cd -<tab>' to see directory history conveniently.
2797 do 'cd -<tab>' to see directory history conveniently.
2798
2798
2799 Usage:
2799 Usage:
2800
2800
2801 cd 'dir': changes to directory 'dir'.
2801 cd 'dir': changes to directory 'dir'.
2802
2802
2803 cd -: changes to the last visited directory.
2803 cd -: changes to the last visited directory.
2804
2804
2805 cd -<n>: changes to the n-th directory in the directory history.
2805 cd -<n>: changes to the n-th directory in the directory history.
2806
2806
2807 cd --foo: change to directory that matches 'foo' in history
2807 cd --foo: change to directory that matches 'foo' in history
2808
2808
2809 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2809 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2810 (note: cd <bookmark_name> is enough if there is no
2810 (note: cd <bookmark_name> is enough if there is no
2811 directory <bookmark_name>, but a bookmark with the name exists.)
2811 directory <bookmark_name>, but a bookmark with the name exists.)
2812 'cd -b <tab>' allows you to tab-complete bookmark names.
2812 'cd -b <tab>' allows you to tab-complete bookmark names.
2813
2813
2814 Options:
2814 Options:
2815
2815
2816 -q: quiet. Do not print the working directory after the cd command is
2816 -q: quiet. Do not print the working directory after the cd command is
2817 executed. By default IPython's cd command does print this directory,
2817 executed. By default IPython's cd command does print this directory,
2818 since the default prompts do not display path information.
2818 since the default prompts do not display path information.
2819
2819
2820 Note that !cd doesn't work for this purpose because the shell where
2820 Note that !cd doesn't work for this purpose because the shell where
2821 !command runs is immediately discarded after executing 'command'."""
2821 !command runs is immediately discarded after executing 'command'."""
2822
2822
2823 parameter_s = parameter_s.strip()
2823 parameter_s = parameter_s.strip()
2824 #bkms = self.shell.persist.get("bookmarks",{})
2824 #bkms = self.shell.persist.get("bookmarks",{})
2825
2825
2826 oldcwd = os.getcwd()
2826 oldcwd = os.getcwd()
2827 numcd = re.match(r'(-)(\d+)$',parameter_s)
2827 numcd = re.match(r'(-)(\d+)$',parameter_s)
2828 # jump in directory history by number
2828 # jump in directory history by number
2829 if numcd:
2829 if numcd:
2830 nn = int(numcd.group(2))
2830 nn = int(numcd.group(2))
2831 try:
2831 try:
2832 ps = self.shell.user_ns['_dh'][nn]
2832 ps = self.shell.user_ns['_dh'][nn]
2833 except IndexError:
2833 except IndexError:
2834 print 'The requested directory does not exist in history.'
2834 print 'The requested directory does not exist in history.'
2835 return
2835 return
2836 else:
2836 else:
2837 opts = {}
2837 opts = {}
2838 elif parameter_s.startswith('--'):
2838 elif parameter_s.startswith('--'):
2839 ps = None
2839 ps = None
2840 fallback = None
2840 fallback = None
2841 pat = parameter_s[2:]
2841 pat = parameter_s[2:]
2842 dh = self.shell.user_ns['_dh']
2842 dh = self.shell.user_ns['_dh']
2843 # first search only by basename (last component)
2843 # first search only by basename (last component)
2844 for ent in reversed(dh):
2844 for ent in reversed(dh):
2845 if pat in os.path.basename(ent) and os.path.isdir(ent):
2845 if pat in os.path.basename(ent) and os.path.isdir(ent):
2846 ps = ent
2846 ps = ent
2847 break
2847 break
2848
2848
2849 if fallback is None and pat in ent and os.path.isdir(ent):
2849 if fallback is None and pat in ent and os.path.isdir(ent):
2850 fallback = ent
2850 fallback = ent
2851
2851
2852 # if we have no last part match, pick the first full path match
2852 # if we have no last part match, pick the first full path match
2853 if ps is None:
2853 if ps is None:
2854 ps = fallback
2854 ps = fallback
2855
2855
2856 if ps is None:
2856 if ps is None:
2857 print "No matching entry in directory history"
2857 print "No matching entry in directory history"
2858 return
2858 return
2859 else:
2859 else:
2860 opts = {}
2860 opts = {}
2861
2861
2862
2862
2863 else:
2863 else:
2864 #turn all non-space-escaping backslashes to slashes,
2864 #turn all non-space-escaping backslashes to slashes,
2865 # for c:\windows\directory\names\
2865 # for c:\windows\directory\names\
2866 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2866 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2867 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2867 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2868 # jump to previous
2868 # jump to previous
2869 if ps == '-':
2869 if ps == '-':
2870 try:
2870 try:
2871 ps = self.shell.user_ns['_dh'][-2]
2871 ps = self.shell.user_ns['_dh'][-2]
2872 except IndexError:
2872 except IndexError:
2873 raise UsageError('%cd -: No previous directory to change to.')
2873 raise UsageError('%cd -: No previous directory to change to.')
2874 # jump to bookmark if needed
2874 # jump to bookmark if needed
2875 else:
2875 else:
2876 if not os.path.isdir(ps) or opts.has_key('b'):
2876 if not os.path.isdir(ps) or opts.has_key('b'):
2877 bkms = self.db.get('bookmarks', {})
2877 bkms = self.db.get('bookmarks', {})
2878
2878
2879 if bkms.has_key(ps):
2879 if bkms.has_key(ps):
2880 target = bkms[ps]
2880 target = bkms[ps]
2881 print '(bookmark:%s) -> %s' % (ps,target)
2881 print '(bookmark:%s) -> %s' % (ps,target)
2882 ps = target
2882 ps = target
2883 else:
2883 else:
2884 if opts.has_key('b'):
2884 if opts.has_key('b'):
2885 raise UsageError("Bookmark '%s' not found. "
2885 raise UsageError("Bookmark '%s' not found. "
2886 "Use '%%bookmark -l' to see your bookmarks." % ps)
2886 "Use '%%bookmark -l' to see your bookmarks." % ps)
2887
2887
2888 # at this point ps should point to the target dir
2888 # at this point ps should point to the target dir
2889 if ps:
2889 if ps:
2890 try:
2890 try:
2891 os.chdir(os.path.expanduser(ps))
2891 os.chdir(os.path.expanduser(ps))
2892 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2892 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2893 set_term_title('IPython: ' + abbrev_cwd())
2893 set_term_title('IPython: ' + abbrev_cwd())
2894 except OSError:
2894 except OSError:
2895 print sys.exc_info()[1]
2895 print sys.exc_info()[1]
2896 else:
2896 else:
2897 cwd = os.getcwd()
2897 cwd = os.getcwd()
2898 dhist = self.shell.user_ns['_dh']
2898 dhist = self.shell.user_ns['_dh']
2899 if oldcwd != cwd:
2899 if oldcwd != cwd:
2900 dhist.append(cwd)
2900 dhist.append(cwd)
2901 self.db['dhist'] = compress_dhist(dhist)[-100:]
2901 self.db['dhist'] = compress_dhist(dhist)[-100:]
2902
2902
2903 else:
2903 else:
2904 os.chdir(self.shell.home_dir)
2904 os.chdir(self.shell.home_dir)
2905 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2905 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2906 set_term_title('IPython: ' + '~')
2906 set_term_title('IPython: ' + '~')
2907 cwd = os.getcwd()
2907 cwd = os.getcwd()
2908 dhist = self.shell.user_ns['_dh']
2908 dhist = self.shell.user_ns['_dh']
2909
2909
2910 if oldcwd != cwd:
2910 if oldcwd != cwd:
2911 dhist.append(cwd)
2911 dhist.append(cwd)
2912 self.db['dhist'] = compress_dhist(dhist)[-100:]
2912 self.db['dhist'] = compress_dhist(dhist)[-100:]
2913 if not 'q' in opts and self.shell.user_ns['_dh']:
2913 if not 'q' in opts and self.shell.user_ns['_dh']:
2914 print self.shell.user_ns['_dh'][-1]
2914 print self.shell.user_ns['_dh'][-1]
2915
2915
2916
2916
2917 def magic_env(self, parameter_s=''):
2917 def magic_env(self, parameter_s=''):
2918 """List environment variables."""
2918 """List environment variables."""
2919
2919
2920 return os.environ.data
2920 return os.environ.data
2921
2921
2922 def magic_pushd(self, parameter_s=''):
2922 def magic_pushd(self, parameter_s=''):
2923 """Place the current dir on stack and change directory.
2923 """Place the current dir on stack and change directory.
2924
2924
2925 Usage:\\
2925 Usage:\\
2926 %pushd ['dirname']
2926 %pushd ['dirname']
2927 """
2927 """
2928
2928
2929 dir_s = self.shell.dir_stack
2929 dir_s = self.shell.dir_stack
2930 tgt = os.path.expanduser(parameter_s)
2930 tgt = os.path.expanduser(parameter_s)
2931 cwd = os.getcwd().replace(self.home_dir,'~')
2931 cwd = os.getcwd().replace(self.home_dir,'~')
2932 if tgt:
2932 if tgt:
2933 self.magic_cd(parameter_s)
2933 self.magic_cd(parameter_s)
2934 dir_s.insert(0,cwd)
2934 dir_s.insert(0,cwd)
2935 return self.magic_dirs()
2935 return self.magic_dirs()
2936
2936
2937 def magic_popd(self, parameter_s=''):
2937 def magic_popd(self, parameter_s=''):
2938 """Change to directory popped off the top of the stack.
2938 """Change to directory popped off the top of the stack.
2939 """
2939 """
2940 if not self.shell.dir_stack:
2940 if not self.shell.dir_stack:
2941 raise UsageError("%popd on empty stack")
2941 raise UsageError("%popd on empty stack")
2942 top = self.shell.dir_stack.pop(0)
2942 top = self.shell.dir_stack.pop(0)
2943 self.magic_cd(top)
2943 self.magic_cd(top)
2944 print "popd ->",top
2944 print "popd ->",top
2945
2945
2946 def magic_dirs(self, parameter_s=''):
2946 def magic_dirs(self, parameter_s=''):
2947 """Return the current directory stack."""
2947 """Return the current directory stack."""
2948
2948
2949 return self.shell.dir_stack
2949 return self.shell.dir_stack
2950
2950
2951 def magic_dhist(self, parameter_s=''):
2951 def magic_dhist(self, parameter_s=''):
2952 """Print your history of visited directories.
2952 """Print your history of visited directories.
2953
2953
2954 %dhist -> print full history\\
2954 %dhist -> print full history\\
2955 %dhist n -> print last n entries only\\
2955 %dhist n -> print last n entries only\\
2956 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2956 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2957
2957
2958 This history is automatically maintained by the %cd command, and
2958 This history is automatically maintained by the %cd command, and
2959 always available as the global list variable _dh. You can use %cd -<n>
2959 always available as the global list variable _dh. You can use %cd -<n>
2960 to go to directory number <n>.
2960 to go to directory number <n>.
2961
2961
2962 Note that most of time, you should view directory history by entering
2962 Note that most of time, you should view directory history by entering
2963 cd -<TAB>.
2963 cd -<TAB>.
2964
2964
2965 """
2965 """
2966
2966
2967 dh = self.shell.user_ns['_dh']
2967 dh = self.shell.user_ns['_dh']
2968 if parameter_s:
2968 if parameter_s:
2969 try:
2969 try:
2970 args = map(int,parameter_s.split())
2970 args = map(int,parameter_s.split())
2971 except:
2971 except:
2972 self.arg_err(Magic.magic_dhist)
2972 self.arg_err(Magic.magic_dhist)
2973 return
2973 return
2974 if len(args) == 1:
2974 if len(args) == 1:
2975 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2975 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2976 elif len(args) == 2:
2976 elif len(args) == 2:
2977 ini,fin = args
2977 ini,fin = args
2978 else:
2978 else:
2979 self.arg_err(Magic.magic_dhist)
2979 self.arg_err(Magic.magic_dhist)
2980 return
2980 return
2981 else:
2981 else:
2982 ini,fin = 0,len(dh)
2982 ini,fin = 0,len(dh)
2983 nlprint(dh,
2983 nlprint(dh,
2984 header = 'Directory history (kept in _dh)',
2984 header = 'Directory history (kept in _dh)',
2985 start=ini,stop=fin)
2985 start=ini,stop=fin)
2986
2986
2987 @testdec.skip_doctest
2987 @testdec.skip_doctest
2988 def magic_sc(self, parameter_s=''):
2988 def magic_sc(self, parameter_s=''):
2989 """Shell capture - execute a shell command and capture its output.
2989 """Shell capture - execute a shell command and capture its output.
2990
2990
2991 DEPRECATED. Suboptimal, retained for backwards compatibility.
2991 DEPRECATED. Suboptimal, retained for backwards compatibility.
2992
2992
2993 You should use the form 'var = !command' instead. Example:
2993 You should use the form 'var = !command' instead. Example:
2994
2994
2995 "%sc -l myfiles = ls ~" should now be written as
2995 "%sc -l myfiles = ls ~" should now be written as
2996
2996
2997 "myfiles = !ls ~"
2997 "myfiles = !ls ~"
2998
2998
2999 myfiles.s, myfiles.l and myfiles.n still apply as documented
2999 myfiles.s, myfiles.l and myfiles.n still apply as documented
3000 below.
3000 below.
3001
3001
3002 --
3002 --
3003 %sc [options] varname=command
3003 %sc [options] varname=command
3004
3004
3005 IPython will run the given command using commands.getoutput(), and
3005 IPython will run the given command using commands.getoutput(), and
3006 will then update the user's interactive namespace with a variable
3006 will then update the user's interactive namespace with a variable
3007 called varname, containing the value of the call. Your command can
3007 called varname, containing the value of the call. Your command can
3008 contain shell wildcards, pipes, etc.
3008 contain shell wildcards, pipes, etc.
3009
3009
3010 The '=' sign in the syntax is mandatory, and the variable name you
3010 The '=' sign in the syntax is mandatory, and the variable name you
3011 supply must follow Python's standard conventions for valid names.
3011 supply must follow Python's standard conventions for valid names.
3012
3012
3013 (A special format without variable name exists for internal use)
3013 (A special format without variable name exists for internal use)
3014
3014
3015 Options:
3015 Options:
3016
3016
3017 -l: list output. Split the output on newlines into a list before
3017 -l: list output. Split the output on newlines into a list before
3018 assigning it to the given variable. By default the output is stored
3018 assigning it to the given variable. By default the output is stored
3019 as a single string.
3019 as a single string.
3020
3020
3021 -v: verbose. Print the contents of the variable.
3021 -v: verbose. Print the contents of the variable.
3022
3022
3023 In most cases you should not need to split as a list, because the
3023 In most cases you should not need to split as a list, because the
3024 returned value is a special type of string which can automatically
3024 returned value is a special type of string which can automatically
3025 provide its contents either as a list (split on newlines) or as a
3025 provide its contents either as a list (split on newlines) or as a
3026 space-separated string. These are convenient, respectively, either
3026 space-separated string. These are convenient, respectively, either
3027 for sequential processing or to be passed to a shell command.
3027 for sequential processing or to be passed to a shell command.
3028
3028
3029 For example:
3029 For example:
3030
3030
3031 # all-random
3031 # all-random
3032
3032
3033 # Capture into variable a
3033 # Capture into variable a
3034 In [1]: sc a=ls *py
3034 In [1]: sc a=ls *py
3035
3035
3036 # a is a string with embedded newlines
3036 # a is a string with embedded newlines
3037 In [2]: a
3037 In [2]: a
3038 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3038 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3039
3039
3040 # which can be seen as a list:
3040 # which can be seen as a list:
3041 In [3]: a.l
3041 In [3]: a.l
3042 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3042 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3043
3043
3044 # or as a whitespace-separated string:
3044 # or as a whitespace-separated string:
3045 In [4]: a.s
3045 In [4]: a.s
3046 Out[4]: 'setup.py win32_manual_post_install.py'
3046 Out[4]: 'setup.py win32_manual_post_install.py'
3047
3047
3048 # a.s is useful to pass as a single command line:
3048 # a.s is useful to pass as a single command line:
3049 In [5]: !wc -l $a.s
3049 In [5]: !wc -l $a.s
3050 146 setup.py
3050 146 setup.py
3051 130 win32_manual_post_install.py
3051 130 win32_manual_post_install.py
3052 276 total
3052 276 total
3053
3053
3054 # while the list form is useful to loop over:
3054 # while the list form is useful to loop over:
3055 In [6]: for f in a.l:
3055 In [6]: for f in a.l:
3056 ...: !wc -l $f
3056 ...: !wc -l $f
3057 ...:
3057 ...:
3058 146 setup.py
3058 146 setup.py
3059 130 win32_manual_post_install.py
3059 130 win32_manual_post_install.py
3060
3060
3061 Similiarly, the lists returned by the -l option are also special, in
3061 Similiarly, the lists returned by the -l option are also special, in
3062 the sense that you can equally invoke the .s attribute on them to
3062 the sense that you can equally invoke the .s attribute on them to
3063 automatically get a whitespace-separated string from their contents:
3063 automatically get a whitespace-separated string from their contents:
3064
3064
3065 In [7]: sc -l b=ls *py
3065 In [7]: sc -l b=ls *py
3066
3066
3067 In [8]: b
3067 In [8]: b
3068 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3068 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3069
3069
3070 In [9]: b.s
3070 In [9]: b.s
3071 Out[9]: 'setup.py win32_manual_post_install.py'
3071 Out[9]: 'setup.py win32_manual_post_install.py'
3072
3072
3073 In summary, both the lists and strings used for ouptut capture have
3073 In summary, both the lists and strings used for ouptut capture have
3074 the following special attributes:
3074 the following special attributes:
3075
3075
3076 .l (or .list) : value as list.
3076 .l (or .list) : value as list.
3077 .n (or .nlstr): value as newline-separated string.
3077 .n (or .nlstr): value as newline-separated string.
3078 .s (or .spstr): value as space-separated string.
3078 .s (or .spstr): value as space-separated string.
3079 """
3079 """
3080
3080
3081 opts,args = self.parse_options(parameter_s,'lv')
3081 opts,args = self.parse_options(parameter_s,'lv')
3082 # Try to get a variable name and command to run
3082 # Try to get a variable name and command to run
3083 try:
3083 try:
3084 # the variable name must be obtained from the parse_options
3084 # the variable name must be obtained from the parse_options
3085 # output, which uses shlex.split to strip options out.
3085 # output, which uses shlex.split to strip options out.
3086 var,_ = args.split('=',1)
3086 var,_ = args.split('=',1)
3087 var = var.strip()
3087 var = var.strip()
3088 # But the the command has to be extracted from the original input
3088 # But the the command has to be extracted from the original input
3089 # parameter_s, not on what parse_options returns, to avoid the
3089 # parameter_s, not on what parse_options returns, to avoid the
3090 # quote stripping which shlex.split performs on it.
3090 # quote stripping which shlex.split performs on it.
3091 _,cmd = parameter_s.split('=',1)
3091 _,cmd = parameter_s.split('=',1)
3092 except ValueError:
3092 except ValueError:
3093 var,cmd = '',''
3093 var,cmd = '',''
3094 # If all looks ok, proceed
3094 # If all looks ok, proceed
3095 out,err = self.shell.getoutputerror(cmd)
3095 out,err = self.shell.getoutputerror(cmd)
3096 if err:
3096 if err:
3097 print >> IPython.utils.io.Term.cerr, err
3097 print >> IPython.utils.io.Term.cerr, err
3098 if opts.has_key('l'):
3098 if opts.has_key('l'):
3099 out = SList(out.split('\n'))
3099 out = SList(out.split('\n'))
3100 else:
3100 else:
3101 out = LSString(out)
3101 out = LSString(out)
3102 if opts.has_key('v'):
3102 if opts.has_key('v'):
3103 print '%s ==\n%s' % (var,pformat(out))
3103 print '%s ==\n%s' % (var,pformat(out))
3104 if var:
3104 if var:
3105 self.shell.user_ns.update({var:out})
3105 self.shell.user_ns.update({var:out})
3106 else:
3106 else:
3107 return out
3107 return out
3108
3108
3109 def magic_sx(self, parameter_s=''):
3109 def magic_sx(self, parameter_s=''):
3110 """Shell execute - run a shell command and capture its output.
3110 """Shell execute - run a shell command and capture its output.
3111
3111
3112 %sx command
3112 %sx command
3113
3113
3114 IPython will run the given command using commands.getoutput(), and
3114 IPython will run the given command using commands.getoutput(), and
3115 return the result formatted as a list (split on '\\n'). Since the
3115 return the result formatted as a list (split on '\\n'). Since the
3116 output is _returned_, it will be stored in ipython's regular output
3116 output is _returned_, it will be stored in ipython's regular output
3117 cache Out[N] and in the '_N' automatic variables.
3117 cache Out[N] and in the '_N' automatic variables.
3118
3118
3119 Notes:
3119 Notes:
3120
3120
3121 1) If an input line begins with '!!', then %sx is automatically
3121 1) If an input line begins with '!!', then %sx is automatically
3122 invoked. That is, while:
3122 invoked. That is, while:
3123 !ls
3123 !ls
3124 causes ipython to simply issue system('ls'), typing
3124 causes ipython to simply issue system('ls'), typing
3125 !!ls
3125 !!ls
3126 is a shorthand equivalent to:
3126 is a shorthand equivalent to:
3127 %sx ls
3127 %sx ls
3128
3128
3129 2) %sx differs from %sc in that %sx automatically splits into a list,
3129 2) %sx differs from %sc in that %sx automatically splits into a list,
3130 like '%sc -l'. The reason for this is to make it as easy as possible
3130 like '%sc -l'. The reason for this is to make it as easy as possible
3131 to process line-oriented shell output via further python commands.
3131 to process line-oriented shell output via further python commands.
3132 %sc is meant to provide much finer control, but requires more
3132 %sc is meant to provide much finer control, but requires more
3133 typing.
3133 typing.
3134
3134
3135 3) Just like %sc -l, this is a list with special attributes:
3135 3) Just like %sc -l, this is a list with special attributes:
3136
3136
3137 .l (or .list) : value as list.
3137 .l (or .list) : value as list.
3138 .n (or .nlstr): value as newline-separated string.
3138 .n (or .nlstr): value as newline-separated string.
3139 .s (or .spstr): value as whitespace-separated string.
3139 .s (or .spstr): value as whitespace-separated string.
3140
3140
3141 This is very useful when trying to use such lists as arguments to
3141 This is very useful when trying to use such lists as arguments to
3142 system commands."""
3142 system commands."""
3143
3143
3144 if parameter_s:
3144 if parameter_s:
3145 out,err = self.shell.getoutputerror(parameter_s)
3145 out,err = self.shell.getoutputerror(parameter_s)
3146 if err:
3146 if err:
3147 print >> IPython.utils.io.Term.cerr, err
3147 print >> IPython.utils.io.Term.cerr, err
3148 return SList(out.split('\n'))
3148 return SList(out.split('\n'))
3149
3149
3150 def magic_r(self, parameter_s=''):
3150 def magic_r(self, parameter_s=''):
3151 """Repeat previous input.
3151 """Repeat previous input.
3152
3152
3153 Note: Consider using the more powerfull %rep instead!
3153 Note: Consider using the more powerfull %rep instead!
3154
3154
3155 If given an argument, repeats the previous command which starts with
3155 If given an argument, repeats the previous command which starts with
3156 the same string, otherwise it just repeats the previous input.
3156 the same string, otherwise it just repeats the previous input.
3157
3157
3158 Shell escaped commands (with ! as first character) are not recognized
3158 Shell escaped commands (with ! as first character) are not recognized
3159 by this system, only pure python code and magic commands.
3159 by this system, only pure python code and magic commands.
3160 """
3160 """
3161
3161
3162 start = parameter_s.strip()
3162 start = parameter_s.strip()
3163 esc_magic = ESC_MAGIC
3163 esc_magic = ESC_MAGIC
3164 # Identify magic commands even if automagic is on (which means
3164 # Identify magic commands even if automagic is on (which means
3165 # the in-memory version is different from that typed by the user).
3165 # the in-memory version is different from that typed by the user).
3166 if self.shell.automagic:
3166 if self.shell.automagic:
3167 start_magic = esc_magic+start
3167 start_magic = esc_magic+start
3168 else:
3168 else:
3169 start_magic = start
3169 start_magic = start
3170 # Look through the input history in reverse
3170 # Look through the input history in reverse
3171 for n in range(len(self.shell.input_hist)-2,0,-1):
3171 for n in range(len(self.shell.input_hist)-2,0,-1):
3172 input = self.shell.input_hist[n]
3172 input = self.shell.input_hist[n]
3173 # skip plain 'r' lines so we don't recurse to infinity
3173 # skip plain 'r' lines so we don't recurse to infinity
3174 if input != '_ip.magic("r")\n' and \
3174 if input != '_ip.magic("r")\n' and \
3175 (input.startswith(start) or input.startswith(start_magic)):
3175 (input.startswith(start) or input.startswith(start_magic)):
3176 #print 'match',`input` # dbg
3176 #print 'match',`input` # dbg
3177 print 'Executing:',input,
3177 print 'Executing:',input,
3178 self.shell.runlines(input)
3178 self.shell.runlines(input)
3179 return
3179 return
3180 print 'No previous input matching `%s` found.' % start
3180 print 'No previous input matching `%s` found.' % start
3181
3181
3182
3182
3183 def magic_bookmark(self, parameter_s=''):
3183 def magic_bookmark(self, parameter_s=''):
3184 """Manage IPython's bookmark system.
3184 """Manage IPython's bookmark system.
3185
3185
3186 %bookmark <name> - set bookmark to current dir
3186 %bookmark <name> - set bookmark to current dir
3187 %bookmark <name> <dir> - set bookmark to <dir>
3187 %bookmark <name> <dir> - set bookmark to <dir>
3188 %bookmark -l - list all bookmarks
3188 %bookmark -l - list all bookmarks
3189 %bookmark -d <name> - remove bookmark
3189 %bookmark -d <name> - remove bookmark
3190 %bookmark -r - remove all bookmarks
3190 %bookmark -r - remove all bookmarks
3191
3191
3192 You can later on access a bookmarked folder with:
3192 You can later on access a bookmarked folder with:
3193 %cd -b <name>
3193 %cd -b <name>
3194 or simply '%cd <name>' if there is no directory called <name> AND
3194 or simply '%cd <name>' if there is no directory called <name> AND
3195 there is such a bookmark defined.
3195 there is such a bookmark defined.
3196
3196
3197 Your bookmarks persist through IPython sessions, but they are
3197 Your bookmarks persist through IPython sessions, but they are
3198 associated with each profile."""
3198 associated with each profile."""
3199
3199
3200 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3200 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3201 if len(args) > 2:
3201 if len(args) > 2:
3202 raise UsageError("%bookmark: too many arguments")
3202 raise UsageError("%bookmark: too many arguments")
3203
3203
3204 bkms = self.db.get('bookmarks',{})
3204 bkms = self.db.get('bookmarks',{})
3205
3205
3206 if opts.has_key('d'):
3206 if opts.has_key('d'):
3207 try:
3207 try:
3208 todel = args[0]
3208 todel = args[0]
3209 except IndexError:
3209 except IndexError:
3210 raise UsageError(
3210 raise UsageError(
3211 "%bookmark -d: must provide a bookmark to delete")
3211 "%bookmark -d: must provide a bookmark to delete")
3212 else:
3212 else:
3213 try:
3213 try:
3214 del bkms[todel]
3214 del bkms[todel]
3215 except KeyError:
3215 except KeyError:
3216 raise UsageError(
3216 raise UsageError(
3217 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3217 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3218
3218
3219 elif opts.has_key('r'):
3219 elif opts.has_key('r'):
3220 bkms = {}
3220 bkms = {}
3221 elif opts.has_key('l'):
3221 elif opts.has_key('l'):
3222 bks = bkms.keys()
3222 bks = bkms.keys()
3223 bks.sort()
3223 bks.sort()
3224 if bks:
3224 if bks:
3225 size = max(map(len,bks))
3225 size = max(map(len,bks))
3226 else:
3226 else:
3227 size = 0
3227 size = 0
3228 fmt = '%-'+str(size)+'s -> %s'
3228 fmt = '%-'+str(size)+'s -> %s'
3229 print 'Current bookmarks:'
3229 print 'Current bookmarks:'
3230 for bk in bks:
3230 for bk in bks:
3231 print fmt % (bk,bkms[bk])
3231 print fmt % (bk,bkms[bk])
3232 else:
3232 else:
3233 if not args:
3233 if not args:
3234 raise UsageError("%bookmark: You must specify the bookmark name")
3234 raise UsageError("%bookmark: You must specify the bookmark name")
3235 elif len(args)==1:
3235 elif len(args)==1:
3236 bkms[args[0]] = os.getcwd()
3236 bkms[args[0]] = os.getcwd()
3237 elif len(args)==2:
3237 elif len(args)==2:
3238 bkms[args[0]] = args[1]
3238 bkms[args[0]] = args[1]
3239 self.db['bookmarks'] = bkms
3239 self.db['bookmarks'] = bkms
3240
3240
3241 def magic_pycat(self, parameter_s=''):
3241 def magic_pycat(self, parameter_s=''):
3242 """Show a syntax-highlighted file through a pager.
3242 """Show a syntax-highlighted file through a pager.
3243
3243
3244 This magic is similar to the cat utility, but it will assume the file
3244 This magic is similar to the cat utility, but it will assume the file
3245 to be Python source and will show it with syntax highlighting. """
3245 to be Python source and will show it with syntax highlighting. """
3246
3246
3247 try:
3247 try:
3248 filename = get_py_filename(parameter_s)
3248 filename = get_py_filename(parameter_s)
3249 cont = file_read(filename)
3249 cont = file_read(filename)
3250 except IOError:
3250 except IOError:
3251 try:
3251 try:
3252 cont = eval(parameter_s,self.user_ns)
3252 cont = eval(parameter_s,self.user_ns)
3253 except NameError:
3253 except NameError:
3254 cont = None
3254 cont = None
3255 if cont is None:
3255 if cont is None:
3256 print "Error: no such file or variable"
3256 print "Error: no such file or variable"
3257 return
3257 return
3258
3258
3259 page(self.shell.pycolorize(cont),
3259 page.page(self.shell.pycolorize(cont),
3260 screen_lines=self.shell.usable_screen_length)
3260 screen_lines=self.shell.usable_screen_length)
3261
3261
3262 def _rerun_pasted(self):
3262 def _rerun_pasted(self):
3263 """ Rerun a previously pasted command.
3263 """ Rerun a previously pasted command.
3264 """
3264 """
3265 b = self.user_ns.get('pasted_block', None)
3265 b = self.user_ns.get('pasted_block', None)
3266 if b is None:
3266 if b is None:
3267 raise UsageError('No previous pasted block available')
3267 raise UsageError('No previous pasted block available')
3268 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3268 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3269 exec b in self.user_ns
3269 exec b in self.user_ns
3270
3270
3271 def _get_pasted_lines(self, sentinel):
3271 def _get_pasted_lines(self, sentinel):
3272 """ Yield pasted lines until the user enters the given sentinel value.
3272 """ Yield pasted lines until the user enters the given sentinel value.
3273 """
3273 """
3274 from IPython.core import interactiveshell
3274 from IPython.core import interactiveshell
3275 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3275 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3276 while True:
3276 while True:
3277 l = interactiveshell.raw_input_original(':')
3277 l = interactiveshell.raw_input_original(':')
3278 if l == sentinel:
3278 if l == sentinel:
3279 return
3279 return
3280 else:
3280 else:
3281 yield l
3281 yield l
3282
3282
3283 def _strip_pasted_lines_for_code(self, raw_lines):
3283 def _strip_pasted_lines_for_code(self, raw_lines):
3284 """ Strip non-code parts of a sequence of lines to return a block of
3284 """ Strip non-code parts of a sequence of lines to return a block of
3285 code.
3285 code.
3286 """
3286 """
3287 # Regular expressions that declare text we strip from the input:
3287 # Regular expressions that declare text we strip from the input:
3288 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3288 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3289 r'^\s*(\s?>)+', # Python input prompt
3289 r'^\s*(\s?>)+', # Python input prompt
3290 r'^\s*\.{3,}', # Continuation prompts
3290 r'^\s*\.{3,}', # Continuation prompts
3291 r'^\++',
3291 r'^\++',
3292 ]
3292 ]
3293
3293
3294 strip_from_start = map(re.compile,strip_re)
3294 strip_from_start = map(re.compile,strip_re)
3295
3295
3296 lines = []
3296 lines = []
3297 for l in raw_lines:
3297 for l in raw_lines:
3298 for pat in strip_from_start:
3298 for pat in strip_from_start:
3299 l = pat.sub('',l)
3299 l = pat.sub('',l)
3300 lines.append(l)
3300 lines.append(l)
3301
3301
3302 block = "\n".join(lines) + '\n'
3302 block = "\n".join(lines) + '\n'
3303 #print "block:\n",block
3303 #print "block:\n",block
3304 return block
3304 return block
3305
3305
3306 def _execute_block(self, block, par):
3306 def _execute_block(self, block, par):
3307 """ Execute a block, or store it in a variable, per the user's request.
3307 """ Execute a block, or store it in a variable, per the user's request.
3308 """
3308 """
3309 if not par:
3309 if not par:
3310 b = textwrap.dedent(block)
3310 b = textwrap.dedent(block)
3311 self.user_ns['pasted_block'] = b
3311 self.user_ns['pasted_block'] = b
3312 exec b in self.user_ns
3312 exec b in self.user_ns
3313 else:
3313 else:
3314 self.user_ns[par] = SList(block.splitlines())
3314 self.user_ns[par] = SList(block.splitlines())
3315 print "Block assigned to '%s'" % par
3315 print "Block assigned to '%s'" % par
3316
3316
3317 def magic_cpaste(self, parameter_s=''):
3317 def magic_cpaste(self, parameter_s=''):
3318 """Allows you to paste & execute a pre-formatted code block from clipboard.
3318 """Allows you to paste & execute a pre-formatted code block from clipboard.
3319
3319
3320 You must terminate the block with '--' (two minus-signs) alone on the
3320 You must terminate the block with '--' (two minus-signs) alone on the
3321 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3321 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3322 is the new sentinel for this operation)
3322 is the new sentinel for this operation)
3323
3323
3324 The block is dedented prior to execution to enable execution of method
3324 The block is dedented prior to execution to enable execution of method
3325 definitions. '>' and '+' characters at the beginning of a line are
3325 definitions. '>' and '+' characters at the beginning of a line are
3326 ignored, to allow pasting directly from e-mails, diff files and
3326 ignored, to allow pasting directly from e-mails, diff files and
3327 doctests (the '...' continuation prompt is also stripped). The
3327 doctests (the '...' continuation prompt is also stripped). The
3328 executed block is also assigned to variable named 'pasted_block' for
3328 executed block is also assigned to variable named 'pasted_block' for
3329 later editing with '%edit pasted_block'.
3329 later editing with '%edit pasted_block'.
3330
3330
3331 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3331 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3332 This assigns the pasted block to variable 'foo' as string, without
3332 This assigns the pasted block to variable 'foo' as string, without
3333 dedenting or executing it (preceding >>> and + is still stripped)
3333 dedenting or executing it (preceding >>> and + is still stripped)
3334
3334
3335 '%cpaste -r' re-executes the block previously entered by cpaste.
3335 '%cpaste -r' re-executes the block previously entered by cpaste.
3336
3336
3337 Do not be alarmed by garbled output on Windows (it's a readline bug).
3337 Do not be alarmed by garbled output on Windows (it's a readline bug).
3338 Just press enter and type -- (and press enter again) and the block
3338 Just press enter and type -- (and press enter again) and the block
3339 will be what was just pasted.
3339 will be what was just pasted.
3340
3340
3341 IPython statements (magics, shell escapes) are not supported (yet).
3341 IPython statements (magics, shell escapes) are not supported (yet).
3342
3342
3343 See also
3343 See also
3344 --------
3344 --------
3345 paste: automatically pull code from clipboard.
3345 paste: automatically pull code from clipboard.
3346 """
3346 """
3347
3347
3348 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3348 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3349 par = args.strip()
3349 par = args.strip()
3350 if opts.has_key('r'):
3350 if opts.has_key('r'):
3351 self._rerun_pasted()
3351 self._rerun_pasted()
3352 return
3352 return
3353
3353
3354 sentinel = opts.get('s','--')
3354 sentinel = opts.get('s','--')
3355
3355
3356 block = self._strip_pasted_lines_for_code(
3356 block = self._strip_pasted_lines_for_code(
3357 self._get_pasted_lines(sentinel))
3357 self._get_pasted_lines(sentinel))
3358
3358
3359 self._execute_block(block, par)
3359 self._execute_block(block, par)
3360
3360
3361 def magic_paste(self, parameter_s=''):
3361 def magic_paste(self, parameter_s=''):
3362 """Allows you to paste & execute a pre-formatted code block from clipboard.
3362 """Allows you to paste & execute a pre-formatted code block from clipboard.
3363
3363
3364 The text is pulled directly from the clipboard without user
3364 The text is pulled directly from the clipboard without user
3365 intervention and printed back on the screen before execution (unless
3365 intervention and printed back on the screen before execution (unless
3366 the -q flag is given to force quiet mode).
3366 the -q flag is given to force quiet mode).
3367
3367
3368 The block is dedented prior to execution to enable execution of method
3368 The block is dedented prior to execution to enable execution of method
3369 definitions. '>' and '+' characters at the beginning of a line are
3369 definitions. '>' and '+' characters at the beginning of a line are
3370 ignored, to allow pasting directly from e-mails, diff files and
3370 ignored, to allow pasting directly from e-mails, diff files and
3371 doctests (the '...' continuation prompt is also stripped). The
3371 doctests (the '...' continuation prompt is also stripped). The
3372 executed block is also assigned to variable named 'pasted_block' for
3372 executed block is also assigned to variable named 'pasted_block' for
3373 later editing with '%edit pasted_block'.
3373 later editing with '%edit pasted_block'.
3374
3374
3375 You can also pass a variable name as an argument, e.g. '%paste foo'.
3375 You can also pass a variable name as an argument, e.g. '%paste foo'.
3376 This assigns the pasted block to variable 'foo' as string, without
3376 This assigns the pasted block to variable 'foo' as string, without
3377 dedenting or executing it (preceding >>> and + is still stripped)
3377 dedenting or executing it (preceding >>> and + is still stripped)
3378
3378
3379 Options
3379 Options
3380 -------
3380 -------
3381
3381
3382 -r: re-executes the block previously entered by cpaste.
3382 -r: re-executes the block previously entered by cpaste.
3383
3383
3384 -q: quiet mode: do not echo the pasted text back to the terminal.
3384 -q: quiet mode: do not echo the pasted text back to the terminal.
3385
3385
3386 IPython statements (magics, shell escapes) are not supported (yet).
3386 IPython statements (magics, shell escapes) are not supported (yet).
3387
3387
3388 See also
3388 See also
3389 --------
3389 --------
3390 cpaste: manually paste code into terminal until you mark its end.
3390 cpaste: manually paste code into terminal until you mark its end.
3391 """
3391 """
3392 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3392 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3393 par = args.strip()
3393 par = args.strip()
3394 if opts.has_key('r'):
3394 if opts.has_key('r'):
3395 self._rerun_pasted()
3395 self._rerun_pasted()
3396 return
3396 return
3397
3397
3398 text = self.shell.hooks.clipboard_get()
3398 text = self.shell.hooks.clipboard_get()
3399 block = self._strip_pasted_lines_for_code(text.splitlines())
3399 block = self._strip_pasted_lines_for_code(text.splitlines())
3400
3400
3401 # By default, echo back to terminal unless quiet mode is requested
3401 # By default, echo back to terminal unless quiet mode is requested
3402 if not opts.has_key('q'):
3402 if not opts.has_key('q'):
3403 write = self.shell.write
3403 write = self.shell.write
3404 write(self.shell.pycolorize(block))
3404 write(self.shell.pycolorize(block))
3405 if not block.endswith('\n'):
3405 if not block.endswith('\n'):
3406 write('\n')
3406 write('\n')
3407 write("## -- End pasted text --\n")
3407 write("## -- End pasted text --\n")
3408
3408
3409 self._execute_block(block, par)
3409 self._execute_block(block, par)
3410
3410
3411 def magic_quickref(self,arg):
3411 def magic_quickref(self,arg):
3412 """ Show a quick reference sheet """
3412 """ Show a quick reference sheet """
3413 import IPython.core.usage
3413 import IPython.core.usage
3414 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3414 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3415
3415
3416 page(qr)
3416 page.page(qr)
3417
3417
3418 def magic_doctest_mode(self,parameter_s=''):
3418 def magic_doctest_mode(self,parameter_s=''):
3419 """Toggle doctest mode on and off.
3419 """Toggle doctest mode on and off.
3420
3420
3421 This mode allows you to toggle the prompt behavior between normal
3421 This mode allows you to toggle the prompt behavior between normal
3422 IPython prompts and ones that are as similar to the default IPython
3422 IPython prompts and ones that are as similar to the default IPython
3423 interpreter as possible.
3423 interpreter as possible.
3424
3424
3425 It also supports the pasting of code snippets that have leading '>>>'
3425 It also supports the pasting of code snippets that have leading '>>>'
3426 and '...' prompts in them. This means that you can paste doctests from
3426 and '...' prompts in them. This means that you can paste doctests from
3427 files or docstrings (even if they have leading whitespace), and the
3427 files or docstrings (even if they have leading whitespace), and the
3428 code will execute correctly. You can then use '%history -tn' to see
3428 code will execute correctly. You can then use '%history -tn' to see
3429 the translated history without line numbers; this will give you the
3429 the translated history without line numbers; this will give you the
3430 input after removal of all the leading prompts and whitespace, which
3430 input after removal of all the leading prompts and whitespace, which
3431 can be pasted back into an editor.
3431 can be pasted back into an editor.
3432
3432
3433 With these features, you can switch into this mode easily whenever you
3433 With these features, you can switch into this mode easily whenever you
3434 need to do testing and changes to doctests, without having to leave
3434 need to do testing and changes to doctests, without having to leave
3435 your existing IPython session.
3435 your existing IPython session.
3436 """
3436 """
3437
3437
3438 from IPython.utils.ipstruct import Struct
3438 from IPython.utils.ipstruct import Struct
3439
3439
3440 # Shorthands
3440 # Shorthands
3441 shell = self.shell
3441 shell = self.shell
3442 oc = shell.displayhook
3442 oc = shell.displayhook
3443 meta = shell.meta
3443 meta = shell.meta
3444 # dstore is a data store kept in the instance metadata bag to track any
3444 # dstore is a data store kept in the instance metadata bag to track any
3445 # changes we make, so we can undo them later.
3445 # changes we make, so we can undo them later.
3446 dstore = meta.setdefault('doctest_mode',Struct())
3446 dstore = meta.setdefault('doctest_mode',Struct())
3447 save_dstore = dstore.setdefault
3447 save_dstore = dstore.setdefault
3448
3448
3449 # save a few values we'll need to recover later
3449 # save a few values we'll need to recover later
3450 mode = save_dstore('mode',False)
3450 mode = save_dstore('mode',False)
3451 save_dstore('rc_pprint',shell.pprint)
3451 save_dstore('rc_pprint',shell.pprint)
3452 save_dstore('xmode',shell.InteractiveTB.mode)
3452 save_dstore('xmode',shell.InteractiveTB.mode)
3453 save_dstore('rc_separate_out',shell.separate_out)
3453 save_dstore('rc_separate_out',shell.separate_out)
3454 save_dstore('rc_separate_out2',shell.separate_out2)
3454 save_dstore('rc_separate_out2',shell.separate_out2)
3455 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3455 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3456 save_dstore('rc_separate_in',shell.separate_in)
3456 save_dstore('rc_separate_in',shell.separate_in)
3457
3457
3458 if mode == False:
3458 if mode == False:
3459 # turn on
3459 # turn on
3460 oc.prompt1.p_template = '>>> '
3460 oc.prompt1.p_template = '>>> '
3461 oc.prompt2.p_template = '... '
3461 oc.prompt2.p_template = '... '
3462 oc.prompt_out.p_template = ''
3462 oc.prompt_out.p_template = ''
3463
3463
3464 # Prompt separators like plain python
3464 # Prompt separators like plain python
3465 oc.input_sep = oc.prompt1.sep = ''
3465 oc.input_sep = oc.prompt1.sep = ''
3466 oc.output_sep = ''
3466 oc.output_sep = ''
3467 oc.output_sep2 = ''
3467 oc.output_sep2 = ''
3468
3468
3469 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3469 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3470 oc.prompt_out.pad_left = False
3470 oc.prompt_out.pad_left = False
3471
3471
3472 shell.pprint = False
3472 shell.pprint = False
3473
3473
3474 shell.magic_xmode('Plain')
3474 shell.magic_xmode('Plain')
3475
3475
3476 else:
3476 else:
3477 # turn off
3477 # turn off
3478 oc.prompt1.p_template = shell.prompt_in1
3478 oc.prompt1.p_template = shell.prompt_in1
3479 oc.prompt2.p_template = shell.prompt_in2
3479 oc.prompt2.p_template = shell.prompt_in2
3480 oc.prompt_out.p_template = shell.prompt_out
3480 oc.prompt_out.p_template = shell.prompt_out
3481
3481
3482 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3482 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3483
3483
3484 oc.output_sep = dstore.rc_separate_out
3484 oc.output_sep = dstore.rc_separate_out
3485 oc.output_sep2 = dstore.rc_separate_out2
3485 oc.output_sep2 = dstore.rc_separate_out2
3486
3486
3487 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3487 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3488 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3488 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3489
3489
3490 shell.pprint = dstore.rc_pprint
3490 shell.pprint = dstore.rc_pprint
3491
3491
3492 shell.magic_xmode(dstore.xmode)
3492 shell.magic_xmode(dstore.xmode)
3493
3493
3494 # Store new mode and inform
3494 # Store new mode and inform
3495 dstore.mode = bool(1-int(mode))
3495 dstore.mode = bool(1-int(mode))
3496 print 'Doctest mode is:',
3496 print 'Doctest mode is:',
3497 print ['OFF','ON'][dstore.mode]
3497 print ['OFF','ON'][dstore.mode]
3498
3498
3499 def magic_gui(self, parameter_s=''):
3499 def magic_gui(self, parameter_s=''):
3500 """Enable or disable IPython GUI event loop integration.
3500 """Enable or disable IPython GUI event loop integration.
3501
3501
3502 %gui [-a] [GUINAME]
3502 %gui [-a] [GUINAME]
3503
3503
3504 This magic replaces IPython's threaded shells that were activated
3504 This magic replaces IPython's threaded shells that were activated
3505 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3505 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3506 can now be enabled, disabled and swtiched at runtime and keyboard
3506 can now be enabled, disabled and swtiched at runtime and keyboard
3507 interrupts should work without any problems. The following toolkits
3507 interrupts should work without any problems. The following toolkits
3508 are supported: wxPython, PyQt4, PyGTK, and Tk::
3508 are supported: wxPython, PyQt4, PyGTK, and Tk::
3509
3509
3510 %gui wx # enable wxPython event loop integration
3510 %gui wx # enable wxPython event loop integration
3511 %gui qt4|qt # enable PyQt4 event loop integration
3511 %gui qt4|qt # enable PyQt4 event loop integration
3512 %gui gtk # enable PyGTK event loop integration
3512 %gui gtk # enable PyGTK event loop integration
3513 %gui tk # enable Tk event loop integration
3513 %gui tk # enable Tk event loop integration
3514 %gui # disable all event loop integration
3514 %gui # disable all event loop integration
3515
3515
3516 WARNING: after any of these has been called you can simply create
3516 WARNING: after any of these has been called you can simply create
3517 an application object, but DO NOT start the event loop yourself, as
3517 an application object, but DO NOT start the event loop yourself, as
3518 we have already handled that.
3518 we have already handled that.
3519
3519
3520 If you want us to create an appropriate application object add the
3520 If you want us to create an appropriate application object add the
3521 "-a" flag to your command::
3521 "-a" flag to your command::
3522
3522
3523 %gui -a wx
3523 %gui -a wx
3524
3524
3525 This is highly recommended for most users.
3525 This is highly recommended for most users.
3526 """
3526 """
3527 opts, arg = self.parse_options(parameter_s,'a')
3527 opts, arg = self.parse_options(parameter_s,'a')
3528 if arg=='': arg = None
3528 if arg=='': arg = None
3529 return enable_gui(arg, 'a' in opts)
3529 return enable_gui(arg, 'a' in opts)
3530
3530
3531 def magic_load_ext(self, module_str):
3531 def magic_load_ext(self, module_str):
3532 """Load an IPython extension by its module name."""
3532 """Load an IPython extension by its module name."""
3533 return self.extension_manager.load_extension(module_str)
3533 return self.extension_manager.load_extension(module_str)
3534
3534
3535 def magic_unload_ext(self, module_str):
3535 def magic_unload_ext(self, module_str):
3536 """Unload an IPython extension by its module name."""
3536 """Unload an IPython extension by its module name."""
3537 self.extension_manager.unload_extension(module_str)
3537 self.extension_manager.unload_extension(module_str)
3538
3538
3539 def magic_reload_ext(self, module_str):
3539 def magic_reload_ext(self, module_str):
3540 """Reload an IPython extension by its module name."""
3540 """Reload an IPython extension by its module name."""
3541 self.extension_manager.reload_extension(module_str)
3541 self.extension_manager.reload_extension(module_str)
3542
3542
3543 @testdec.skip_doctest
3543 @testdec.skip_doctest
3544 def magic_install_profiles(self, s):
3544 def magic_install_profiles(self, s):
3545 """Install the default IPython profiles into the .ipython dir.
3545 """Install the default IPython profiles into the .ipython dir.
3546
3546
3547 If the default profiles have already been installed, they will not
3547 If the default profiles have already been installed, they will not
3548 be overwritten. You can force overwriting them by using the ``-o``
3548 be overwritten. You can force overwriting them by using the ``-o``
3549 option::
3549 option::
3550
3550
3551 In [1]: %install_profiles -o
3551 In [1]: %install_profiles -o
3552 """
3552 """
3553 if '-o' in s:
3553 if '-o' in s:
3554 overwrite = True
3554 overwrite = True
3555 else:
3555 else:
3556 overwrite = False
3556 overwrite = False
3557 from IPython.config import profile
3557 from IPython.config import profile
3558 profile_dir = os.path.split(profile.__file__)[0]
3558 profile_dir = os.path.split(profile.__file__)[0]
3559 ipython_dir = self.ipython_dir
3559 ipython_dir = self.ipython_dir
3560 files = os.listdir(profile_dir)
3560 files = os.listdir(profile_dir)
3561
3561
3562 to_install = []
3562 to_install = []
3563 for f in files:
3563 for f in files:
3564 if f.startswith('ipython_config'):
3564 if f.startswith('ipython_config'):
3565 src = os.path.join(profile_dir, f)
3565 src = os.path.join(profile_dir, f)
3566 dst = os.path.join(ipython_dir, f)
3566 dst = os.path.join(ipython_dir, f)
3567 if (not os.path.isfile(dst)) or overwrite:
3567 if (not os.path.isfile(dst)) or overwrite:
3568 to_install.append((f, src, dst))
3568 to_install.append((f, src, dst))
3569 if len(to_install)>0:
3569 if len(to_install)>0:
3570 print "Installing profiles to: ", ipython_dir
3570 print "Installing profiles to: ", ipython_dir
3571 for (f, src, dst) in to_install:
3571 for (f, src, dst) in to_install:
3572 shutil.copy(src, dst)
3572 shutil.copy(src, dst)
3573 print " %s" % f
3573 print " %s" % f
3574
3574
3575 def magic_install_default_config(self, s):
3575 def magic_install_default_config(self, s):
3576 """Install IPython's default config file into the .ipython dir.
3576 """Install IPython's default config file into the .ipython dir.
3577
3577
3578 If the default config file (:file:`ipython_config.py`) is already
3578 If the default config file (:file:`ipython_config.py`) is already
3579 installed, it will not be overwritten. You can force overwriting
3579 installed, it will not be overwritten. You can force overwriting
3580 by using the ``-o`` option::
3580 by using the ``-o`` option::
3581
3581
3582 In [1]: %install_default_config
3582 In [1]: %install_default_config
3583 """
3583 """
3584 if '-o' in s:
3584 if '-o' in s:
3585 overwrite = True
3585 overwrite = True
3586 else:
3586 else:
3587 overwrite = False
3587 overwrite = False
3588 from IPython.config import default
3588 from IPython.config import default
3589 config_dir = os.path.split(default.__file__)[0]
3589 config_dir = os.path.split(default.__file__)[0]
3590 ipython_dir = self.ipython_dir
3590 ipython_dir = self.ipython_dir
3591 default_config_file_name = 'ipython_config.py'
3591 default_config_file_name = 'ipython_config.py'
3592 src = os.path.join(config_dir, default_config_file_name)
3592 src = os.path.join(config_dir, default_config_file_name)
3593 dst = os.path.join(ipython_dir, default_config_file_name)
3593 dst = os.path.join(ipython_dir, default_config_file_name)
3594 if (not os.path.isfile(dst)) or overwrite:
3594 if (not os.path.isfile(dst)) or overwrite:
3595 shutil.copy(src, dst)
3595 shutil.copy(src, dst)
3596 print "Installing default config file: %s" % dst
3596 print "Installing default config file: %s" % dst
3597
3597
3598 # Pylab support: simple wrappers that activate pylab, load gui input
3598 # Pylab support: simple wrappers that activate pylab, load gui input
3599 # handling and modify slightly %run
3599 # handling and modify slightly %run
3600
3600
3601 @testdec.skip_doctest
3601 @testdec.skip_doctest
3602 def _pylab_magic_run(self, parameter_s=''):
3602 def _pylab_magic_run(self, parameter_s=''):
3603 Magic.magic_run(self, parameter_s,
3603 Magic.magic_run(self, parameter_s,
3604 runner=mpl_runner(self.shell.safe_execfile))
3604 runner=mpl_runner(self.shell.safe_execfile))
3605
3605
3606 _pylab_magic_run.__doc__ = magic_run.__doc__
3606 _pylab_magic_run.__doc__ = magic_run.__doc__
3607
3607
3608 @testdec.skip_doctest
3608 @testdec.skip_doctest
3609 def magic_pylab(self, s):
3609 def magic_pylab(self, s):
3610 """Load numpy and matplotlib to work interactively.
3610 """Load numpy and matplotlib to work interactively.
3611
3611
3612 %pylab [GUINAME]
3612 %pylab [GUINAME]
3613
3613
3614 This function lets you activate pylab (matplotlib, numpy and
3614 This function lets you activate pylab (matplotlib, numpy and
3615 interactive support) at any point during an IPython session.
3615 interactive support) at any point during an IPython session.
3616
3616
3617 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3617 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3618 pylab and mlab, as well as all names from numpy and pylab.
3618 pylab and mlab, as well as all names from numpy and pylab.
3619
3619
3620 Parameters
3620 Parameters
3621 ----------
3621 ----------
3622 guiname : optional
3622 guiname : optional
3623 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk' or
3623 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk' or
3624 'tk'). If given, the corresponding Matplotlib backend is used,
3624 'tk'). If given, the corresponding Matplotlib backend is used,
3625 otherwise matplotlib's default (which you can override in your
3625 otherwise matplotlib's default (which you can override in your
3626 matplotlib config file) is used.
3626 matplotlib config file) is used.
3627
3627
3628 Examples
3628 Examples
3629 --------
3629 --------
3630 In this case, where the MPL default is TkAgg:
3630 In this case, where the MPL default is TkAgg:
3631 In [2]: %pylab
3631 In [2]: %pylab
3632
3632
3633 Welcome to pylab, a matplotlib-based Python environment.
3633 Welcome to pylab, a matplotlib-based Python environment.
3634 Backend in use: TkAgg
3634 Backend in use: TkAgg
3635 For more information, type 'help(pylab)'.
3635 For more information, type 'help(pylab)'.
3636
3636
3637 But you can explicitly request a different backend:
3637 But you can explicitly request a different backend:
3638 In [3]: %pylab qt
3638 In [3]: %pylab qt
3639
3639
3640 Welcome to pylab, a matplotlib-based Python environment.
3640 Welcome to pylab, a matplotlib-based Python environment.
3641 Backend in use: Qt4Agg
3641 Backend in use: Qt4Agg
3642 For more information, type 'help(pylab)'.
3642 For more information, type 'help(pylab)'.
3643 """
3643 """
3644 self.shell.enable_pylab(s)
3644 self.shell.enable_pylab(s)
3645
3645
3646 def magic_tb(self, s):
3646 def magic_tb(self, s):
3647 """Print the last traceback with the currently active exception mode.
3647 """Print the last traceback with the currently active exception mode.
3648
3648
3649 See %xmode for changing exception reporting modes."""
3649 See %xmode for changing exception reporting modes."""
3650 self.shell.showtraceback()
3650 self.shell.showtraceback()
3651
3651
3652 # end Magic
3652 # end Magic
@@ -1,609 +1,609
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Tools for inspecting Python objects.
2 """Tools for inspecting Python objects.
3
3
4 Uses syntax highlighting for presenting the various information elements.
4 Uses syntax highlighting for presenting the various information elements.
5
5
6 Similar in spirit to the inspect module, but all calls take a name argument to
6 Similar in spirit to the inspect module, but all calls take a name argument to
7 reference the name under which an object is being read.
7 reference the name under which an object is being read.
8 """
8 """
9
9
10 #*****************************************************************************
10 #*****************************************************************************
11 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
11 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
12 #
12 #
13 # Distributed under the terms of the BSD License. The full license is in
13 # Distributed under the terms of the BSD License. The full license is in
14 # the file COPYING, distributed as part of this software.
14 # the file COPYING, distributed as part of this software.
15 #*****************************************************************************
15 #*****************************************************************************
16
16
17 __all__ = ['Inspector','InspectColors']
17 __all__ = ['Inspector','InspectColors']
18
18
19 # stdlib modules
19 # stdlib modules
20 import __builtin__
20 import __builtin__
21 import StringIO
21 import StringIO
22 import inspect
22 import inspect
23 import linecache
23 import linecache
24 import os
24 import os
25 import string
25 import string
26 import sys
26 import sys
27 import types
27 import types
28
28
29 # IPython's own
29 # IPython's own
30 from IPython.core.page import page
30 from IPython.core import page
31 from IPython.external.Itpl import itpl
31 from IPython.external.Itpl import itpl
32 from IPython.utils import PyColorize
32 from IPython.utils import PyColorize
33 import IPython.utils.io
33 import IPython.utils.io
34 from IPython.utils.text import indent
34 from IPython.utils.text import indent
35 from IPython.utils.wildcard import list_namespace
35 from IPython.utils.wildcard import list_namespace
36 from IPython.utils.coloransi import *
36 from IPython.utils.coloransi import *
37
37
38 #****************************************************************************
38 #****************************************************************************
39 # HACK!!! This is a crude fix for bugs in python 2.3's inspect module. We
39 # HACK!!! This is a crude fix for bugs in python 2.3's inspect module. We
40 # simply monkeypatch inspect with code copied from python 2.4.
40 # simply monkeypatch inspect with code copied from python 2.4.
41 if sys.version_info[:2] == (2,3):
41 if sys.version_info[:2] == (2,3):
42 from inspect import ismodule, getabsfile, modulesbyfile
42 from inspect import ismodule, getabsfile, modulesbyfile
43 def getmodule(object):
43 def getmodule(object):
44 """Return the module an object was defined in, or None if not found."""
44 """Return the module an object was defined in, or None if not found."""
45 if ismodule(object):
45 if ismodule(object):
46 return object
46 return object
47 if hasattr(object, '__module__'):
47 if hasattr(object, '__module__'):
48 return sys.modules.get(object.__module__)
48 return sys.modules.get(object.__module__)
49 try:
49 try:
50 file = getabsfile(object)
50 file = getabsfile(object)
51 except TypeError:
51 except TypeError:
52 return None
52 return None
53 if file in modulesbyfile:
53 if file in modulesbyfile:
54 return sys.modules.get(modulesbyfile[file])
54 return sys.modules.get(modulesbyfile[file])
55 for module in sys.modules.values():
55 for module in sys.modules.values():
56 if hasattr(module, '__file__'):
56 if hasattr(module, '__file__'):
57 modulesbyfile[
57 modulesbyfile[
58 os.path.realpath(
58 os.path.realpath(
59 getabsfile(module))] = module.__name__
59 getabsfile(module))] = module.__name__
60 if file in modulesbyfile:
60 if file in modulesbyfile:
61 return sys.modules.get(modulesbyfile[file])
61 return sys.modules.get(modulesbyfile[file])
62 main = sys.modules['__main__']
62 main = sys.modules['__main__']
63 if not hasattr(object, '__name__'):
63 if not hasattr(object, '__name__'):
64 return None
64 return None
65 if hasattr(main, object.__name__):
65 if hasattr(main, object.__name__):
66 mainobject = getattr(main, object.__name__)
66 mainobject = getattr(main, object.__name__)
67 if mainobject is object:
67 if mainobject is object:
68 return main
68 return main
69 builtin = sys.modules['__builtin__']
69 builtin = sys.modules['__builtin__']
70 if hasattr(builtin, object.__name__):
70 if hasattr(builtin, object.__name__):
71 builtinobject = getattr(builtin, object.__name__)
71 builtinobject = getattr(builtin, object.__name__)
72 if builtinobject is object:
72 if builtinobject is object:
73 return builtin
73 return builtin
74
74
75 inspect.getmodule = getmodule
75 inspect.getmodule = getmodule
76
76
77 #****************************************************************************
77 #****************************************************************************
78 # Builtin color schemes
78 # Builtin color schemes
79
79
80 Colors = TermColors # just a shorthand
80 Colors = TermColors # just a shorthand
81
81
82 # Build a few color schemes
82 # Build a few color schemes
83 NoColor = ColorScheme(
83 NoColor = ColorScheme(
84 'NoColor',{
84 'NoColor',{
85 'header' : Colors.NoColor,
85 'header' : Colors.NoColor,
86 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
86 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
87 } )
87 } )
88
88
89 LinuxColors = ColorScheme(
89 LinuxColors = ColorScheme(
90 'Linux',{
90 'Linux',{
91 'header' : Colors.LightRed,
91 'header' : Colors.LightRed,
92 'normal' : Colors.Normal # color off (usu. Colors.Normal)
92 'normal' : Colors.Normal # color off (usu. Colors.Normal)
93 } )
93 } )
94
94
95 LightBGColors = ColorScheme(
95 LightBGColors = ColorScheme(
96 'LightBG',{
96 'LightBG',{
97 'header' : Colors.Red,
97 'header' : Colors.Red,
98 'normal' : Colors.Normal # color off (usu. Colors.Normal)
98 'normal' : Colors.Normal # color off (usu. Colors.Normal)
99 } )
99 } )
100
100
101 # Build table of color schemes (needed by the parser)
101 # Build table of color schemes (needed by the parser)
102 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
102 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
103 'Linux')
103 'Linux')
104
104
105 #****************************************************************************
105 #****************************************************************************
106 # Auxiliary functions
106 # Auxiliary functions
107 def getdoc(obj):
107 def getdoc(obj):
108 """Stable wrapper around inspect.getdoc.
108 """Stable wrapper around inspect.getdoc.
109
109
110 This can't crash because of attribute problems.
110 This can't crash because of attribute problems.
111
111
112 It also attempts to call a getdoc() method on the given object. This
112 It also attempts to call a getdoc() method on the given object. This
113 allows objects which provide their docstrings via non-standard mechanisms
113 allows objects which provide their docstrings via non-standard mechanisms
114 (like Pyro proxies) to still be inspected by ipython's ? system."""
114 (like Pyro proxies) to still be inspected by ipython's ? system."""
115
115
116 ds = None # default return value
116 ds = None # default return value
117 try:
117 try:
118 ds = inspect.getdoc(obj)
118 ds = inspect.getdoc(obj)
119 except:
119 except:
120 # Harden against an inspect failure, which can occur with
120 # Harden against an inspect failure, which can occur with
121 # SWIG-wrapped extensions.
121 # SWIG-wrapped extensions.
122 pass
122 pass
123 # Allow objects to offer customized documentation via a getdoc method:
123 # Allow objects to offer customized documentation via a getdoc method:
124 try:
124 try:
125 ds2 = obj.getdoc()
125 ds2 = obj.getdoc()
126 except:
126 except:
127 pass
127 pass
128 else:
128 else:
129 # if we get extra info, we add it to the normal docstring.
129 # if we get extra info, we add it to the normal docstring.
130 if ds is None:
130 if ds is None:
131 ds = ds2
131 ds = ds2
132 else:
132 else:
133 ds = '%s\n%s' % (ds,ds2)
133 ds = '%s\n%s' % (ds,ds2)
134 return ds
134 return ds
135
135
136
136
137 def getsource(obj,is_binary=False):
137 def getsource(obj,is_binary=False):
138 """Wrapper around inspect.getsource.
138 """Wrapper around inspect.getsource.
139
139
140 This can be modified by other projects to provide customized source
140 This can be modified by other projects to provide customized source
141 extraction.
141 extraction.
142
142
143 Inputs:
143 Inputs:
144
144
145 - obj: an object whose source code we will attempt to extract.
145 - obj: an object whose source code we will attempt to extract.
146
146
147 Optional inputs:
147 Optional inputs:
148
148
149 - is_binary: whether the object is known to come from a binary source.
149 - is_binary: whether the object is known to come from a binary source.
150 This implementation will skip returning any output for binary objects, but
150 This implementation will skip returning any output for binary objects, but
151 custom extractors may know how to meaningfully process them."""
151 custom extractors may know how to meaningfully process them."""
152
152
153 if is_binary:
153 if is_binary:
154 return None
154 return None
155 else:
155 else:
156 try:
156 try:
157 src = inspect.getsource(obj)
157 src = inspect.getsource(obj)
158 except TypeError:
158 except TypeError:
159 if hasattr(obj,'__class__'):
159 if hasattr(obj,'__class__'):
160 src = inspect.getsource(obj.__class__)
160 src = inspect.getsource(obj.__class__)
161 return src
161 return src
162
162
163 def getargspec(obj):
163 def getargspec(obj):
164 """Get the names and default values of a function's arguments.
164 """Get the names and default values of a function's arguments.
165
165
166 A tuple of four things is returned: (args, varargs, varkw, defaults).
166 A tuple of four things is returned: (args, varargs, varkw, defaults).
167 'args' is a list of the argument names (it may contain nested lists).
167 'args' is a list of the argument names (it may contain nested lists).
168 'varargs' and 'varkw' are the names of the * and ** arguments or None.
168 'varargs' and 'varkw' are the names of the * and ** arguments or None.
169 'defaults' is an n-tuple of the default values of the last n arguments.
169 'defaults' is an n-tuple of the default values of the last n arguments.
170
170
171 Modified version of inspect.getargspec from the Python Standard
171 Modified version of inspect.getargspec from the Python Standard
172 Library."""
172 Library."""
173
173
174 if inspect.isfunction(obj):
174 if inspect.isfunction(obj):
175 func_obj = obj
175 func_obj = obj
176 elif inspect.ismethod(obj):
176 elif inspect.ismethod(obj):
177 func_obj = obj.im_func
177 func_obj = obj.im_func
178 else:
178 else:
179 raise TypeError, 'arg is not a Python function'
179 raise TypeError, 'arg is not a Python function'
180 args, varargs, varkw = inspect.getargs(func_obj.func_code)
180 args, varargs, varkw = inspect.getargs(func_obj.func_code)
181 return args, varargs, varkw, func_obj.func_defaults
181 return args, varargs, varkw, func_obj.func_defaults
182
182
183 #****************************************************************************
183 #****************************************************************************
184 # Class definitions
184 # Class definitions
185
185
186 class myStringIO(StringIO.StringIO):
186 class myStringIO(StringIO.StringIO):
187 """Adds a writeln method to normal StringIO."""
187 """Adds a writeln method to normal StringIO."""
188 def writeln(self,*arg,**kw):
188 def writeln(self,*arg,**kw):
189 """Does a write() and then a write('\n')"""
189 """Does a write() and then a write('\n')"""
190 self.write(*arg,**kw)
190 self.write(*arg,**kw)
191 self.write('\n')
191 self.write('\n')
192
192
193
193
194 class Inspector:
194 class Inspector:
195 def __init__(self,color_table,code_color_table,scheme,
195 def __init__(self,color_table,code_color_table,scheme,
196 str_detail_level=0):
196 str_detail_level=0):
197 self.color_table = color_table
197 self.color_table = color_table
198 self.parser = PyColorize.Parser(code_color_table,out='str')
198 self.parser = PyColorize.Parser(code_color_table,out='str')
199 self.format = self.parser.format
199 self.format = self.parser.format
200 self.str_detail_level = str_detail_level
200 self.str_detail_level = str_detail_level
201 self.set_active_scheme(scheme)
201 self.set_active_scheme(scheme)
202
202
203 def __getdef(self,obj,oname=''):
203 def __getdef(self,obj,oname=''):
204 """Return the definition header for any callable object.
204 """Return the definition header for any callable object.
205
205
206 If any exception is generated, None is returned instead and the
206 If any exception is generated, None is returned instead and the
207 exception is suppressed."""
207 exception is suppressed."""
208
208
209 try:
209 try:
210 return oname + inspect.formatargspec(*getargspec(obj))
210 return oname + inspect.formatargspec(*getargspec(obj))
211 except:
211 except:
212 return None
212 return None
213
213
214 def __head(self,h):
214 def __head(self,h):
215 """Return a header string with proper colors."""
215 """Return a header string with proper colors."""
216 return '%s%s%s' % (self.color_table.active_colors.header,h,
216 return '%s%s%s' % (self.color_table.active_colors.header,h,
217 self.color_table.active_colors.normal)
217 self.color_table.active_colors.normal)
218
218
219 def set_active_scheme(self,scheme):
219 def set_active_scheme(self,scheme):
220 self.color_table.set_active_scheme(scheme)
220 self.color_table.set_active_scheme(scheme)
221 self.parser.color_table.set_active_scheme(scheme)
221 self.parser.color_table.set_active_scheme(scheme)
222
222
223 def noinfo(self,msg,oname):
223 def noinfo(self,msg,oname):
224 """Generic message when no information is found."""
224 """Generic message when no information is found."""
225 print 'No %s found' % msg,
225 print 'No %s found' % msg,
226 if oname:
226 if oname:
227 print 'for %s' % oname
227 print 'for %s' % oname
228 else:
228 else:
229 print
229 print
230
230
231 def pdef(self,obj,oname=''):
231 def pdef(self,obj,oname=''):
232 """Print the definition header for any callable object.
232 """Print the definition header for any callable object.
233
233
234 If the object is a class, print the constructor information."""
234 If the object is a class, print the constructor information."""
235
235
236 if not callable(obj):
236 if not callable(obj):
237 print 'Object is not callable.'
237 print 'Object is not callable.'
238 return
238 return
239
239
240 header = ''
240 header = ''
241
241
242 if inspect.isclass(obj):
242 if inspect.isclass(obj):
243 header = self.__head('Class constructor information:\n')
243 header = self.__head('Class constructor information:\n')
244 obj = obj.__init__
244 obj = obj.__init__
245 elif type(obj) is types.InstanceType:
245 elif type(obj) is types.InstanceType:
246 obj = obj.__call__
246 obj = obj.__call__
247
247
248 output = self.__getdef(obj,oname)
248 output = self.__getdef(obj,oname)
249 if output is None:
249 if output is None:
250 self.noinfo('definition header',oname)
250 self.noinfo('definition header',oname)
251 else:
251 else:
252 print >>IPython.utils.io.Term.cout, header,self.format(output),
252 print >>IPython.utils.io.Term.cout, header,self.format(output),
253
253
254 def pdoc(self,obj,oname='',formatter = None):
254 def pdoc(self,obj,oname='',formatter = None):
255 """Print the docstring for any object.
255 """Print the docstring for any object.
256
256
257 Optional:
257 Optional:
258 -formatter: a function to run the docstring through for specially
258 -formatter: a function to run the docstring through for specially
259 formatted docstrings."""
259 formatted docstrings."""
260
260
261 head = self.__head # so that itpl can find it even if private
261 head = self.__head # so that itpl can find it even if private
262 ds = getdoc(obj)
262 ds = getdoc(obj)
263 if formatter:
263 if formatter:
264 ds = formatter(ds)
264 ds = formatter(ds)
265 if inspect.isclass(obj):
265 if inspect.isclass(obj):
266 init_ds = getdoc(obj.__init__)
266 init_ds = getdoc(obj.__init__)
267 output = itpl('$head("Class Docstring:")\n'
267 output = itpl('$head("Class Docstring:")\n'
268 '$indent(ds)\n'
268 '$indent(ds)\n'
269 '$head("Constructor Docstring"):\n'
269 '$head("Constructor Docstring"):\n'
270 '$indent(init_ds)')
270 '$indent(init_ds)')
271 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
271 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
272 and hasattr(obj,'__call__'):
272 and hasattr(obj,'__call__'):
273 call_ds = getdoc(obj.__call__)
273 call_ds = getdoc(obj.__call__)
274 if call_ds:
274 if call_ds:
275 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
275 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
276 '$head("Calling Docstring:")\n$indent(call_ds)')
276 '$head("Calling Docstring:")\n$indent(call_ds)')
277 else:
277 else:
278 output = ds
278 output = ds
279 else:
279 else:
280 output = ds
280 output = ds
281 if output is None:
281 if output is None:
282 self.noinfo('documentation',oname)
282 self.noinfo('documentation',oname)
283 return
283 return
284 page(output)
284 page.page(output)
285
285
286 def psource(self,obj,oname=''):
286 def psource(self,obj,oname=''):
287 """Print the source code for an object."""
287 """Print the source code for an object."""
288
288
289 # Flush the source cache because inspect can return out-of-date source
289 # Flush the source cache because inspect can return out-of-date source
290 linecache.checkcache()
290 linecache.checkcache()
291 try:
291 try:
292 src = getsource(obj)
292 src = getsource(obj)
293 except:
293 except:
294 self.noinfo('source',oname)
294 self.noinfo('source',oname)
295 else:
295 else:
296 page(self.format(src))
296 page.page(self.format(src))
297
297
298 def pfile(self,obj,oname=''):
298 def pfile(self,obj,oname=''):
299 """Show the whole file where an object was defined."""
299 """Show the whole file where an object was defined."""
300
300
301 try:
301 try:
302 try:
302 try:
303 lineno = inspect.getsourcelines(obj)[1]
303 lineno = inspect.getsourcelines(obj)[1]
304 except TypeError:
304 except TypeError:
305 # For instances, try the class object like getsource() does
305 # For instances, try the class object like getsource() does
306 if hasattr(obj,'__class__'):
306 if hasattr(obj,'__class__'):
307 lineno = inspect.getsourcelines(obj.__class__)[1]
307 lineno = inspect.getsourcelines(obj.__class__)[1]
308 # Adjust the inspected object so getabsfile() below works
308 # Adjust the inspected object so getabsfile() below works
309 obj = obj.__class__
309 obj = obj.__class__
310 except:
310 except:
311 self.noinfo('file',oname)
311 self.noinfo('file',oname)
312 return
312 return
313
313
314 # We only reach this point if object was successfully queried
314 # We only reach this point if object was successfully queried
315
315
316 # run contents of file through pager starting at line
316 # run contents of file through pager starting at line
317 # where the object is defined
317 # where the object is defined
318 ofile = inspect.getabsfile(obj)
318 ofile = inspect.getabsfile(obj)
319
319
320 if (ofile.endswith('.so') or ofile.endswith('.dll')):
320 if (ofile.endswith('.so') or ofile.endswith('.dll')):
321 print 'File %r is binary, not printing.' % ofile
321 print 'File %r is binary, not printing.' % ofile
322 elif not os.path.isfile(ofile):
322 elif not os.path.isfile(ofile):
323 print 'File %r does not exist, not printing.' % ofile
323 print 'File %r does not exist, not printing.' % ofile
324 else:
324 else:
325 # Print only text files, not extension binaries. Note that
325 # Print only text files, not extension binaries. Note that
326 # getsourcelines returns lineno with 1-offset and page() uses
326 # getsourcelines returns lineno with 1-offset and page() uses
327 # 0-offset, so we must adjust.
327 # 0-offset, so we must adjust.
328 page(self.format(open(ofile).read()),lineno-1)
328 page.page(self.format(open(ofile).read()),lineno-1)
329
329
330 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
330 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
331 """Show detailed information about an object.
331 """Show detailed information about an object.
332
332
333 Optional arguments:
333 Optional arguments:
334
334
335 - oname: name of the variable pointing to the object.
335 - oname: name of the variable pointing to the object.
336
336
337 - formatter: special formatter for docstrings (see pdoc)
337 - formatter: special formatter for docstrings (see pdoc)
338
338
339 - info: a structure with some information fields which may have been
339 - info: a structure with some information fields which may have been
340 precomputed already.
340 precomputed already.
341
341
342 - detail_level: if set to 1, more information is given.
342 - detail_level: if set to 1, more information is given.
343 """
343 """
344
344
345 obj_type = type(obj)
345 obj_type = type(obj)
346
346
347 header = self.__head
347 header = self.__head
348 if info is None:
348 if info is None:
349 ismagic = 0
349 ismagic = 0
350 isalias = 0
350 isalias = 0
351 ospace = ''
351 ospace = ''
352 else:
352 else:
353 ismagic = info.ismagic
353 ismagic = info.ismagic
354 isalias = info.isalias
354 isalias = info.isalias
355 ospace = info.namespace
355 ospace = info.namespace
356 # Get docstring, special-casing aliases:
356 # Get docstring, special-casing aliases:
357 if isalias:
357 if isalias:
358 if not callable(obj):
358 if not callable(obj):
359 try:
359 try:
360 ds = "Alias to the system command:\n %s" % obj[1]
360 ds = "Alias to the system command:\n %s" % obj[1]
361 except:
361 except:
362 ds = "Alias: " + str(obj)
362 ds = "Alias: " + str(obj)
363 else:
363 else:
364 ds = "Alias to " + str(obj)
364 ds = "Alias to " + str(obj)
365 if obj.__doc__:
365 if obj.__doc__:
366 ds += "\nDocstring:\n" + obj.__doc__
366 ds += "\nDocstring:\n" + obj.__doc__
367 else:
367 else:
368 ds = getdoc(obj)
368 ds = getdoc(obj)
369 if ds is None:
369 if ds is None:
370 ds = '<no docstring>'
370 ds = '<no docstring>'
371 if formatter is not None:
371 if formatter is not None:
372 ds = formatter(ds)
372 ds = formatter(ds)
373
373
374 # store output in a list which gets joined with \n at the end.
374 # store output in a list which gets joined with \n at the end.
375 out = myStringIO()
375 out = myStringIO()
376
376
377 string_max = 200 # max size of strings to show (snipped if longer)
377 string_max = 200 # max size of strings to show (snipped if longer)
378 shalf = int((string_max -5)/2)
378 shalf = int((string_max -5)/2)
379
379
380 if ismagic:
380 if ismagic:
381 obj_type_name = 'Magic function'
381 obj_type_name = 'Magic function'
382 elif isalias:
382 elif isalias:
383 obj_type_name = 'System alias'
383 obj_type_name = 'System alias'
384 else:
384 else:
385 obj_type_name = obj_type.__name__
385 obj_type_name = obj_type.__name__
386 out.writeln(header('Type:\t\t')+obj_type_name)
386 out.writeln(header('Type:\t\t')+obj_type_name)
387
387
388 try:
388 try:
389 bclass = obj.__class__
389 bclass = obj.__class__
390 out.writeln(header('Base Class:\t')+str(bclass))
390 out.writeln(header('Base Class:\t')+str(bclass))
391 except: pass
391 except: pass
392
392
393 # String form, but snip if too long in ? form (full in ??)
393 # String form, but snip if too long in ? form (full in ??)
394 if detail_level >= self.str_detail_level:
394 if detail_level >= self.str_detail_level:
395 try:
395 try:
396 ostr = str(obj)
396 ostr = str(obj)
397 str_head = 'String Form:'
397 str_head = 'String Form:'
398 if not detail_level and len(ostr)>string_max:
398 if not detail_level and len(ostr)>string_max:
399 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
399 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
400 ostr = ("\n" + " " * len(str_head.expandtabs())).\
400 ostr = ("\n" + " " * len(str_head.expandtabs())).\
401 join(map(string.strip,ostr.split("\n")))
401 join(map(string.strip,ostr.split("\n")))
402 if ostr.find('\n') > -1:
402 if ostr.find('\n') > -1:
403 # Print multi-line strings starting at the next line.
403 # Print multi-line strings starting at the next line.
404 str_sep = '\n'
404 str_sep = '\n'
405 else:
405 else:
406 str_sep = '\t'
406 str_sep = '\t'
407 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
407 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
408 except:
408 except:
409 pass
409 pass
410
410
411 if ospace:
411 if ospace:
412 out.writeln(header('Namespace:\t')+ospace)
412 out.writeln(header('Namespace:\t')+ospace)
413
413
414 # Length (for strings and lists)
414 # Length (for strings and lists)
415 try:
415 try:
416 length = str(len(obj))
416 length = str(len(obj))
417 out.writeln(header('Length:\t\t')+length)
417 out.writeln(header('Length:\t\t')+length)
418 except: pass
418 except: pass
419
419
420 # Filename where object was defined
420 # Filename where object was defined
421 binary_file = False
421 binary_file = False
422 try:
422 try:
423 try:
423 try:
424 fname = inspect.getabsfile(obj)
424 fname = inspect.getabsfile(obj)
425 except TypeError:
425 except TypeError:
426 # For an instance, the file that matters is where its class was
426 # For an instance, the file that matters is where its class was
427 # declared.
427 # declared.
428 if hasattr(obj,'__class__'):
428 if hasattr(obj,'__class__'):
429 fname = inspect.getabsfile(obj.__class__)
429 fname = inspect.getabsfile(obj.__class__)
430 if fname.endswith('<string>'):
430 if fname.endswith('<string>'):
431 fname = 'Dynamically generated function. No source code available.'
431 fname = 'Dynamically generated function. No source code available.'
432 if (fname.endswith('.so') or fname.endswith('.dll')):
432 if (fname.endswith('.so') or fname.endswith('.dll')):
433 binary_file = True
433 binary_file = True
434 out.writeln(header('File:\t\t')+fname)
434 out.writeln(header('File:\t\t')+fname)
435 except:
435 except:
436 # if anything goes wrong, we don't want to show source, so it's as
436 # if anything goes wrong, we don't want to show source, so it's as
437 # if the file was binary
437 # if the file was binary
438 binary_file = True
438 binary_file = True
439
439
440 # reconstruct the function definition and print it:
440 # reconstruct the function definition and print it:
441 defln = self.__getdef(obj,oname)
441 defln = self.__getdef(obj,oname)
442 if defln:
442 if defln:
443 out.write(header('Definition:\t')+self.format(defln))
443 out.write(header('Definition:\t')+self.format(defln))
444
444
445 # Docstrings only in detail 0 mode, since source contains them (we
445 # Docstrings only in detail 0 mode, since source contains them (we
446 # avoid repetitions). If source fails, we add them back, see below.
446 # avoid repetitions). If source fails, we add them back, see below.
447 if ds and detail_level == 0:
447 if ds and detail_level == 0:
448 out.writeln(header('Docstring:\n') + indent(ds))
448 out.writeln(header('Docstring:\n') + indent(ds))
449
449
450 # Original source code for any callable
450 # Original source code for any callable
451 if detail_level:
451 if detail_level:
452 # Flush the source cache because inspect can return out-of-date
452 # Flush the source cache because inspect can return out-of-date
453 # source
453 # source
454 linecache.checkcache()
454 linecache.checkcache()
455 source_success = False
455 source_success = False
456 try:
456 try:
457 try:
457 try:
458 src = getsource(obj,binary_file)
458 src = getsource(obj,binary_file)
459 except TypeError:
459 except TypeError:
460 if hasattr(obj,'__class__'):
460 if hasattr(obj,'__class__'):
461 src = getsource(obj.__class__,binary_file)
461 src = getsource(obj.__class__,binary_file)
462 if src is not None:
462 if src is not None:
463 source = self.format(src)
463 source = self.format(src)
464 out.write(header('Source:\n')+source.rstrip())
464 out.write(header('Source:\n')+source.rstrip())
465 source_success = True
465 source_success = True
466 except Exception, msg:
466 except Exception, msg:
467 pass
467 pass
468
468
469 if ds and not source_success:
469 if ds and not source_success:
470 out.writeln(header('Docstring [source file open failed]:\n')
470 out.writeln(header('Docstring [source file open failed]:\n')
471 + indent(ds))
471 + indent(ds))
472
472
473 # Constructor docstring for classes
473 # Constructor docstring for classes
474 if inspect.isclass(obj):
474 if inspect.isclass(obj):
475 # reconstruct the function definition and print it:
475 # reconstruct the function definition and print it:
476 try:
476 try:
477 obj_init = obj.__init__
477 obj_init = obj.__init__
478 except AttributeError:
478 except AttributeError:
479 init_def = init_ds = None
479 init_def = init_ds = None
480 else:
480 else:
481 init_def = self.__getdef(obj_init,oname)
481 init_def = self.__getdef(obj_init,oname)
482 init_ds = getdoc(obj_init)
482 init_ds = getdoc(obj_init)
483 # Skip Python's auto-generated docstrings
483 # Skip Python's auto-generated docstrings
484 if init_ds and \
484 if init_ds and \
485 init_ds.startswith('x.__init__(...) initializes'):
485 init_ds.startswith('x.__init__(...) initializes'):
486 init_ds = None
486 init_ds = None
487
487
488 if init_def or init_ds:
488 if init_def or init_ds:
489 out.writeln(header('\nConstructor information:'))
489 out.writeln(header('\nConstructor information:'))
490 if init_def:
490 if init_def:
491 out.write(header('Definition:\t')+ self.format(init_def))
491 out.write(header('Definition:\t')+ self.format(init_def))
492 if init_ds:
492 if init_ds:
493 out.writeln(header('Docstring:\n') + indent(init_ds))
493 out.writeln(header('Docstring:\n') + indent(init_ds))
494 # and class docstring for instances:
494 # and class docstring for instances:
495 elif obj_type is types.InstanceType or \
495 elif obj_type is types.InstanceType or \
496 isinstance(obj,object):
496 isinstance(obj,object):
497
497
498 # First, check whether the instance docstring is identical to the
498 # First, check whether the instance docstring is identical to the
499 # class one, and print it separately if they don't coincide. In
499 # class one, and print it separately if they don't coincide. In
500 # most cases they will, but it's nice to print all the info for
500 # most cases they will, but it's nice to print all the info for
501 # objects which use instance-customized docstrings.
501 # objects which use instance-customized docstrings.
502 if ds:
502 if ds:
503 try:
503 try:
504 cls = getattr(obj,'__class__')
504 cls = getattr(obj,'__class__')
505 except:
505 except:
506 class_ds = None
506 class_ds = None
507 else:
507 else:
508 class_ds = getdoc(cls)
508 class_ds = getdoc(cls)
509 # Skip Python's auto-generated docstrings
509 # Skip Python's auto-generated docstrings
510 if class_ds and \
510 if class_ds and \
511 (class_ds.startswith('function(code, globals[,') or \
511 (class_ds.startswith('function(code, globals[,') or \
512 class_ds.startswith('instancemethod(function, instance,') or \
512 class_ds.startswith('instancemethod(function, instance,') or \
513 class_ds.startswith('module(name[,') ):
513 class_ds.startswith('module(name[,') ):
514 class_ds = None
514 class_ds = None
515 if class_ds and ds != class_ds:
515 if class_ds and ds != class_ds:
516 out.writeln(header('Class Docstring:\n') +
516 out.writeln(header('Class Docstring:\n') +
517 indent(class_ds))
517 indent(class_ds))
518
518
519 # Next, try to show constructor docstrings
519 # Next, try to show constructor docstrings
520 try:
520 try:
521 init_ds = getdoc(obj.__init__)
521 init_ds = getdoc(obj.__init__)
522 # Skip Python's auto-generated docstrings
522 # Skip Python's auto-generated docstrings
523 if init_ds and \
523 if init_ds and \
524 init_ds.startswith('x.__init__(...) initializes'):
524 init_ds.startswith('x.__init__(...) initializes'):
525 init_ds = None
525 init_ds = None
526 except AttributeError:
526 except AttributeError:
527 init_ds = None
527 init_ds = None
528 if init_ds:
528 if init_ds:
529 out.writeln(header('Constructor Docstring:\n') +
529 out.writeln(header('Constructor Docstring:\n') +
530 indent(init_ds))
530 indent(init_ds))
531
531
532 # Call form docstring for callable instances
532 # Call form docstring for callable instances
533 if hasattr(obj,'__call__'):
533 if hasattr(obj,'__call__'):
534 #out.writeln(header('Callable:\t')+'Yes')
534 #out.writeln(header('Callable:\t')+'Yes')
535 call_def = self.__getdef(obj.__call__,oname)
535 call_def = self.__getdef(obj.__call__,oname)
536 #if call_def is None:
536 #if call_def is None:
537 # out.writeln(header('Call def:\t')+
537 # out.writeln(header('Call def:\t')+
538 # 'Calling definition not available.')
538 # 'Calling definition not available.')
539 if call_def is not None:
539 if call_def is not None:
540 out.writeln(header('Call def:\t')+self.format(call_def))
540 out.writeln(header('Call def:\t')+self.format(call_def))
541 call_ds = getdoc(obj.__call__)
541 call_ds = getdoc(obj.__call__)
542 # Skip Python's auto-generated docstrings
542 # Skip Python's auto-generated docstrings
543 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
543 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
544 call_ds = None
544 call_ds = None
545 if call_ds:
545 if call_ds:
546 out.writeln(header('Call docstring:\n') + indent(call_ds))
546 out.writeln(header('Call docstring:\n') + indent(call_ds))
547
547
548 # Finally send to printer/pager
548 # Finally send to printer/pager
549 output = out.getvalue()
549 output = out.getvalue()
550 if output:
550 if output:
551 page(output)
551 page.page(output)
552 # end pinfo
552 # end pinfo
553
553
554 def psearch(self,pattern,ns_table,ns_search=[],
554 def psearch(self,pattern,ns_table,ns_search=[],
555 ignore_case=False,show_all=False):
555 ignore_case=False,show_all=False):
556 """Search namespaces with wildcards for objects.
556 """Search namespaces with wildcards for objects.
557
557
558 Arguments:
558 Arguments:
559
559
560 - pattern: string containing shell-like wildcards to use in namespace
560 - pattern: string containing shell-like wildcards to use in namespace
561 searches and optionally a type specification to narrow the search to
561 searches and optionally a type specification to narrow the search to
562 objects of that type.
562 objects of that type.
563
563
564 - ns_table: dict of name->namespaces for search.
564 - ns_table: dict of name->namespaces for search.
565
565
566 Optional arguments:
566 Optional arguments:
567
567
568 - ns_search: list of namespace names to include in search.
568 - ns_search: list of namespace names to include in search.
569
569
570 - ignore_case(False): make the search case-insensitive.
570 - ignore_case(False): make the search case-insensitive.
571
571
572 - show_all(False): show all names, including those starting with
572 - show_all(False): show all names, including those starting with
573 underscores.
573 underscores.
574 """
574 """
575 #print 'ps pattern:<%r>' % pattern # dbg
575 #print 'ps pattern:<%r>' % pattern # dbg
576
576
577 # defaults
577 # defaults
578 type_pattern = 'all'
578 type_pattern = 'all'
579 filter = ''
579 filter = ''
580
580
581 cmds = pattern.split()
581 cmds = pattern.split()
582 len_cmds = len(cmds)
582 len_cmds = len(cmds)
583 if len_cmds == 1:
583 if len_cmds == 1:
584 # Only filter pattern given
584 # Only filter pattern given
585 filter = cmds[0]
585 filter = cmds[0]
586 elif len_cmds == 2:
586 elif len_cmds == 2:
587 # Both filter and type specified
587 # Both filter and type specified
588 filter,type_pattern = cmds
588 filter,type_pattern = cmds
589 else:
589 else:
590 raise ValueError('invalid argument string for psearch: <%s>' %
590 raise ValueError('invalid argument string for psearch: <%s>' %
591 pattern)
591 pattern)
592
592
593 # filter search namespaces
593 # filter search namespaces
594 for name in ns_search:
594 for name in ns_search:
595 if name not in ns_table:
595 if name not in ns_table:
596 raise ValueError('invalid namespace <%s>. Valid names: %s' %
596 raise ValueError('invalid namespace <%s>. Valid names: %s' %
597 (name,ns_table.keys()))
597 (name,ns_table.keys()))
598
598
599 #print 'type_pattern:',type_pattern # dbg
599 #print 'type_pattern:',type_pattern # dbg
600 search_result = []
600 search_result = []
601 for ns_name in ns_search:
601 for ns_name in ns_search:
602 ns = ns_table[ns_name]
602 ns = ns_table[ns_name]
603 tmp_res = list(list_namespace(ns,type_pattern,filter,
603 tmp_res = list(list_namespace(ns,type_pattern,filter,
604 ignore_case=ignore_case,
604 ignore_case=ignore_case,
605 show_all=show_all))
605 show_all=show_all))
606 search_result.extend(tmp_res)
606 search_result.extend(tmp_res)
607 search_result.sort()
607 search_result.sort()
608
608
609 page('\n'.join(search_result))
609 page.page('\n'.join(search_result))
@@ -1,1022 +1,1022
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 # encoding: utf-8
2 # encoding: utf-8
3 """
3 """
4 Prefiltering components.
4 Prefiltering components.
5
5
6 Prefilters transform user input before it is exec'd by Python. These
6 Prefilters transform user input before it is exec'd by Python. These
7 transforms are used to implement additional syntax such as !ls and %magic.
7 transforms are used to implement additional syntax such as !ls and %magic.
8
8
9 Authors:
9 Authors:
10
10
11 * Brian Granger
11 * Brian Granger
12 * Fernando Perez
12 * Fernando Perez
13 * Dan Milstein
13 * Dan Milstein
14 * Ville Vainio
14 * Ville Vainio
15 """
15 """
16
16
17 #-----------------------------------------------------------------------------
17 #-----------------------------------------------------------------------------
18 # Copyright (C) 2008-2009 The IPython Development Team
18 # Copyright (C) 2008-2009 The IPython Development Team
19 #
19 #
20 # Distributed under the terms of the BSD License. The full license is in
20 # Distributed under the terms of the BSD License. The full license is in
21 # the file COPYING, distributed as part of this software.
21 # the file COPYING, distributed as part of this software.
22 #-----------------------------------------------------------------------------
22 #-----------------------------------------------------------------------------
23
23
24 #-----------------------------------------------------------------------------
24 #-----------------------------------------------------------------------------
25 # Imports
25 # Imports
26 #-----------------------------------------------------------------------------
26 #-----------------------------------------------------------------------------
27
27
28 import __builtin__
28 import __builtin__
29 import codeop
29 import codeop
30 import re
30 import re
31
31
32 from IPython.core.alias import AliasManager
32 from IPython.core.alias import AliasManager
33 from IPython.core.autocall import IPyAutocall
33 from IPython.core.autocall import IPyAutocall
34 from IPython.config.configurable import Configurable
34 from IPython.config.configurable import Configurable
35 from IPython.core.splitinput import split_user_input
35 from IPython.core.splitinput import split_user_input
36 from IPython.core.page import page
36 from IPython.core import page
37
37
38 from IPython.utils.traitlets import List, Int, Any, Str, CBool, Bool, Instance
38 from IPython.utils.traitlets import List, Int, Any, Str, CBool, Bool, Instance
39 import IPython.utils.io
39 import IPython.utils.io
40 from IPython.utils.text import make_quoted_expr
40 from IPython.utils.text import make_quoted_expr
41 from IPython.utils.autoattr import auto_attr
41 from IPython.utils.autoattr import auto_attr
42
42
43 #-----------------------------------------------------------------------------
43 #-----------------------------------------------------------------------------
44 # Global utilities, errors and constants
44 # Global utilities, errors and constants
45 #-----------------------------------------------------------------------------
45 #-----------------------------------------------------------------------------
46
46
47 # Warning, these cannot be changed unless various regular expressions
47 # Warning, these cannot be changed unless various regular expressions
48 # are updated in a number of places. Not great, but at least we told you.
48 # are updated in a number of places. Not great, but at least we told you.
49 ESC_SHELL = '!'
49 ESC_SHELL = '!'
50 ESC_SH_CAP = '!!'
50 ESC_SH_CAP = '!!'
51 ESC_HELP = '?'
51 ESC_HELP = '?'
52 ESC_MAGIC = '%'
52 ESC_MAGIC = '%'
53 ESC_QUOTE = ','
53 ESC_QUOTE = ','
54 ESC_QUOTE2 = ';'
54 ESC_QUOTE2 = ';'
55 ESC_PAREN = '/'
55 ESC_PAREN = '/'
56
56
57
57
58 class PrefilterError(Exception):
58 class PrefilterError(Exception):
59 pass
59 pass
60
60
61
61
62 # RegExp to identify potential function names
62 # RegExp to identify potential function names
63 re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
63 re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
64
64
65 # RegExp to exclude strings with this start from autocalling. In
65 # RegExp to exclude strings with this start from autocalling. In
66 # particular, all binary operators should be excluded, so that if foo is
66 # particular, all binary operators should be excluded, so that if foo is
67 # callable, foo OP bar doesn't become foo(OP bar), which is invalid. The
67 # callable, foo OP bar doesn't become foo(OP bar), which is invalid. The
68 # characters '!=()' don't need to be checked for, as the checkPythonChars
68 # characters '!=()' don't need to be checked for, as the checkPythonChars
69 # routine explicitely does so, to catch direct calls and rebindings of
69 # routine explicitely does so, to catch direct calls and rebindings of
70 # existing names.
70 # existing names.
71
71
72 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
72 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
73 # it affects the rest of the group in square brackets.
73 # it affects the rest of the group in square brackets.
74 re_exclude_auto = re.compile(r'^[,&^\|\*/\+-]'
74 re_exclude_auto = re.compile(r'^[,&^\|\*/\+-]'
75 r'|^is |^not |^in |^and |^or ')
75 r'|^is |^not |^in |^and |^or ')
76
76
77 # try to catch also methods for stuff in lists/tuples/dicts: off
77 # try to catch also methods for stuff in lists/tuples/dicts: off
78 # (experimental). For this to work, the line_split regexp would need
78 # (experimental). For this to work, the line_split regexp would need
79 # to be modified so it wouldn't break things at '['. That line is
79 # to be modified so it wouldn't break things at '['. That line is
80 # nasty enough that I shouldn't change it until I can test it _well_.
80 # nasty enough that I shouldn't change it until I can test it _well_.
81 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
81 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
82
82
83
83
84 # Handler Check Utilities
84 # Handler Check Utilities
85 def is_shadowed(identifier, ip):
85 def is_shadowed(identifier, ip):
86 """Is the given identifier defined in one of the namespaces which shadow
86 """Is the given identifier defined in one of the namespaces which shadow
87 the alias and magic namespaces? Note that an identifier is different
87 the alias and magic namespaces? Note that an identifier is different
88 than ifun, because it can not contain a '.' character."""
88 than ifun, because it can not contain a '.' character."""
89 # This is much safer than calling ofind, which can change state
89 # This is much safer than calling ofind, which can change state
90 return (identifier in ip.user_ns \
90 return (identifier in ip.user_ns \
91 or identifier in ip.internal_ns \
91 or identifier in ip.internal_ns \
92 or identifier in ip.ns_table['builtin'])
92 or identifier in ip.ns_table['builtin'])
93
93
94
94
95 #-----------------------------------------------------------------------------
95 #-----------------------------------------------------------------------------
96 # The LineInfo class used throughout
96 # The LineInfo class used throughout
97 #-----------------------------------------------------------------------------
97 #-----------------------------------------------------------------------------
98
98
99
99
100 class LineInfo(object):
100 class LineInfo(object):
101 """A single line of input and associated info.
101 """A single line of input and associated info.
102
102
103 Includes the following as properties:
103 Includes the following as properties:
104
104
105 line
105 line
106 The original, raw line
106 The original, raw line
107
107
108 continue_prompt
108 continue_prompt
109 Is this line a continuation in a sequence of multiline input?
109 Is this line a continuation in a sequence of multiline input?
110
110
111 pre
111 pre
112 The initial esc character or whitespace.
112 The initial esc character or whitespace.
113
113
114 pre_char
114 pre_char
115 The escape character(s) in pre or the empty string if there isn't one.
115 The escape character(s) in pre or the empty string if there isn't one.
116 Note that '!!' is a possible value for pre_char. Otherwise it will
116 Note that '!!' is a possible value for pre_char. Otherwise it will
117 always be a single character.
117 always be a single character.
118
118
119 pre_whitespace
119 pre_whitespace
120 The leading whitespace from pre if it exists. If there is a pre_char,
120 The leading whitespace from pre if it exists. If there is a pre_char,
121 this is just ''.
121 this is just ''.
122
122
123 ifun
123 ifun
124 The 'function part', which is basically the maximal initial sequence
124 The 'function part', which is basically the maximal initial sequence
125 of valid python identifiers and the '.' character. This is what is
125 of valid python identifiers and the '.' character. This is what is
126 checked for alias and magic transformations, used for auto-calling,
126 checked for alias and magic transformations, used for auto-calling,
127 etc.
127 etc.
128
128
129 the_rest
129 the_rest
130 Everything else on the line.
130 Everything else on the line.
131 """
131 """
132 def __init__(self, line, continue_prompt):
132 def __init__(self, line, continue_prompt):
133 self.line = line
133 self.line = line
134 self.continue_prompt = continue_prompt
134 self.continue_prompt = continue_prompt
135 self.pre, self.ifun, self.the_rest = split_user_input(line)
135 self.pre, self.ifun, self.the_rest = split_user_input(line)
136
136
137 self.pre_char = self.pre.strip()
137 self.pre_char = self.pre.strip()
138 if self.pre_char:
138 if self.pre_char:
139 self.pre_whitespace = '' # No whitespace allowd before esc chars
139 self.pre_whitespace = '' # No whitespace allowd before esc chars
140 else:
140 else:
141 self.pre_whitespace = self.pre
141 self.pre_whitespace = self.pre
142
142
143 self._oinfo = None
143 self._oinfo = None
144
144
145 def ofind(self, ip):
145 def ofind(self, ip):
146 """Do a full, attribute-walking lookup of the ifun in the various
146 """Do a full, attribute-walking lookup of the ifun in the various
147 namespaces for the given IPython InteractiveShell instance.
147 namespaces for the given IPython InteractiveShell instance.
148
148
149 Return a dict with keys: found,obj,ospace,ismagic
149 Return a dict with keys: found,obj,ospace,ismagic
150
150
151 Note: can cause state changes because of calling getattr, but should
151 Note: can cause state changes because of calling getattr, but should
152 only be run if autocall is on and if the line hasn't matched any
152 only be run if autocall is on and if the line hasn't matched any
153 other, less dangerous handlers.
153 other, less dangerous handlers.
154
154
155 Does cache the results of the call, so can be called multiple times
155 Does cache the results of the call, so can be called multiple times
156 without worrying about *further* damaging state.
156 without worrying about *further* damaging state.
157 """
157 """
158 if not self._oinfo:
158 if not self._oinfo:
159 # ip.shell._ofind is actually on the Magic class!
159 # ip.shell._ofind is actually on the Magic class!
160 self._oinfo = ip.shell._ofind(self.ifun)
160 self._oinfo = ip.shell._ofind(self.ifun)
161 return self._oinfo
161 return self._oinfo
162
162
163 def __str__(self):
163 def __str__(self):
164 return "Lineinfo [%s|%s|%s]" %(self.pre, self.ifun, self.the_rest)
164 return "Lineinfo [%s|%s|%s]" %(self.pre, self.ifun, self.the_rest)
165
165
166
166
167 #-----------------------------------------------------------------------------
167 #-----------------------------------------------------------------------------
168 # Main Prefilter manager
168 # Main Prefilter manager
169 #-----------------------------------------------------------------------------
169 #-----------------------------------------------------------------------------
170
170
171
171
172 class PrefilterManager(Configurable):
172 class PrefilterManager(Configurable):
173 """Main prefilter component.
173 """Main prefilter component.
174
174
175 The IPython prefilter is run on all user input before it is run. The
175 The IPython prefilter is run on all user input before it is run. The
176 prefilter consumes lines of input and produces transformed lines of
176 prefilter consumes lines of input and produces transformed lines of
177 input.
177 input.
178
178
179 The iplementation consists of two phases:
179 The iplementation consists of two phases:
180
180
181 1. Transformers
181 1. Transformers
182 2. Checkers and handlers
182 2. Checkers and handlers
183
183
184 Over time, we plan on deprecating the checkers and handlers and doing
184 Over time, we plan on deprecating the checkers and handlers and doing
185 everything in the transformers.
185 everything in the transformers.
186
186
187 The transformers are instances of :class:`PrefilterTransformer` and have
187 The transformers are instances of :class:`PrefilterTransformer` and have
188 a single method :meth:`transform` that takes a line and returns a
188 a single method :meth:`transform` that takes a line and returns a
189 transformed line. The transformation can be accomplished using any
189 transformed line. The transformation can be accomplished using any
190 tool, but our current ones use regular expressions for speed. We also
190 tool, but our current ones use regular expressions for speed. We also
191 ship :mod:`pyparsing` in :mod:`IPython.external` for use in transformers.
191 ship :mod:`pyparsing` in :mod:`IPython.external` for use in transformers.
192
192
193 After all the transformers have been run, the line is fed to the checkers,
193 After all the transformers have been run, the line is fed to the checkers,
194 which are instances of :class:`PrefilterChecker`. The line is passed to
194 which are instances of :class:`PrefilterChecker`. The line is passed to
195 the :meth:`check` method, which either returns `None` or a
195 the :meth:`check` method, which either returns `None` or a
196 :class:`PrefilterHandler` instance. If `None` is returned, the other
196 :class:`PrefilterHandler` instance. If `None` is returned, the other
197 checkers are tried. If an :class:`PrefilterHandler` instance is returned,
197 checkers are tried. If an :class:`PrefilterHandler` instance is returned,
198 the line is passed to the :meth:`handle` method of the returned
198 the line is passed to the :meth:`handle` method of the returned
199 handler and no further checkers are tried.
199 handler and no further checkers are tried.
200
200
201 Both transformers and checkers have a `priority` attribute, that determines
201 Both transformers and checkers have a `priority` attribute, that determines
202 the order in which they are called. Smaller priorities are tried first.
202 the order in which they are called. Smaller priorities are tried first.
203
203
204 Both transformers and checkers also have `enabled` attribute, which is
204 Both transformers and checkers also have `enabled` attribute, which is
205 a boolean that determines if the instance is used.
205 a boolean that determines if the instance is used.
206
206
207 Users or developers can change the priority or enabled attribute of
207 Users or developers can change the priority or enabled attribute of
208 transformers or checkers, but they must call the :meth:`sort_checkers`
208 transformers or checkers, but they must call the :meth:`sort_checkers`
209 or :meth:`sort_transformers` method after changing the priority.
209 or :meth:`sort_transformers` method after changing the priority.
210 """
210 """
211
211
212 multi_line_specials = CBool(True, config=True)
212 multi_line_specials = CBool(True, config=True)
213 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
213 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
214
214
215 def __init__(self, shell=None, config=None):
215 def __init__(self, shell=None, config=None):
216 super(PrefilterManager, self).__init__(shell=shell, config=config)
216 super(PrefilterManager, self).__init__(shell=shell, config=config)
217 self.shell = shell
217 self.shell = shell
218 self.init_transformers()
218 self.init_transformers()
219 self.init_handlers()
219 self.init_handlers()
220 self.init_checkers()
220 self.init_checkers()
221
221
222 #-------------------------------------------------------------------------
222 #-------------------------------------------------------------------------
223 # API for managing transformers
223 # API for managing transformers
224 #-------------------------------------------------------------------------
224 #-------------------------------------------------------------------------
225
225
226 def init_transformers(self):
226 def init_transformers(self):
227 """Create the default transformers."""
227 """Create the default transformers."""
228 self._transformers = []
228 self._transformers = []
229 for transformer_cls in _default_transformers:
229 for transformer_cls in _default_transformers:
230 transformer_cls(
230 transformer_cls(
231 shell=self.shell, prefilter_manager=self, config=self.config
231 shell=self.shell, prefilter_manager=self, config=self.config
232 )
232 )
233
233
234 def sort_transformers(self):
234 def sort_transformers(self):
235 """Sort the transformers by priority.
235 """Sort the transformers by priority.
236
236
237 This must be called after the priority of a transformer is changed.
237 This must be called after the priority of a transformer is changed.
238 The :meth:`register_transformer` method calls this automatically.
238 The :meth:`register_transformer` method calls this automatically.
239 """
239 """
240 self._transformers.sort(cmp=lambda x,y: x.priority-y.priority)
240 self._transformers.sort(cmp=lambda x,y: x.priority-y.priority)
241
241
242 @property
242 @property
243 def transformers(self):
243 def transformers(self):
244 """Return a list of checkers, sorted by priority."""
244 """Return a list of checkers, sorted by priority."""
245 return self._transformers
245 return self._transformers
246
246
247 def register_transformer(self, transformer):
247 def register_transformer(self, transformer):
248 """Register a transformer instance."""
248 """Register a transformer instance."""
249 if transformer not in self._transformers:
249 if transformer not in self._transformers:
250 self._transformers.append(transformer)
250 self._transformers.append(transformer)
251 self.sort_transformers()
251 self.sort_transformers()
252
252
253 def unregister_transformer(self, transformer):
253 def unregister_transformer(self, transformer):
254 """Unregister a transformer instance."""
254 """Unregister a transformer instance."""
255 if transformer in self._transformers:
255 if transformer in self._transformers:
256 self._transformers.remove(transformer)
256 self._transformers.remove(transformer)
257
257
258 #-------------------------------------------------------------------------
258 #-------------------------------------------------------------------------
259 # API for managing checkers
259 # API for managing checkers
260 #-------------------------------------------------------------------------
260 #-------------------------------------------------------------------------
261
261
262 def init_checkers(self):
262 def init_checkers(self):
263 """Create the default checkers."""
263 """Create the default checkers."""
264 self._checkers = []
264 self._checkers = []
265 for checker in _default_checkers:
265 for checker in _default_checkers:
266 checker(
266 checker(
267 shell=self.shell, prefilter_manager=self, config=self.config
267 shell=self.shell, prefilter_manager=self, config=self.config
268 )
268 )
269
269
270 def sort_checkers(self):
270 def sort_checkers(self):
271 """Sort the checkers by priority.
271 """Sort the checkers by priority.
272
272
273 This must be called after the priority of a checker is changed.
273 This must be called after the priority of a checker is changed.
274 The :meth:`register_checker` method calls this automatically.
274 The :meth:`register_checker` method calls this automatically.
275 """
275 """
276 self._checkers.sort(cmp=lambda x,y: x.priority-y.priority)
276 self._checkers.sort(cmp=lambda x,y: x.priority-y.priority)
277
277
278 @property
278 @property
279 def checkers(self):
279 def checkers(self):
280 """Return a list of checkers, sorted by priority."""
280 """Return a list of checkers, sorted by priority."""
281 return self._checkers
281 return self._checkers
282
282
283 def register_checker(self, checker):
283 def register_checker(self, checker):
284 """Register a checker instance."""
284 """Register a checker instance."""
285 if checker not in self._checkers:
285 if checker not in self._checkers:
286 self._checkers.append(checker)
286 self._checkers.append(checker)
287 self.sort_checkers()
287 self.sort_checkers()
288
288
289 def unregister_checker(self, checker):
289 def unregister_checker(self, checker):
290 """Unregister a checker instance."""
290 """Unregister a checker instance."""
291 if checker in self._checkers:
291 if checker in self._checkers:
292 self._checkers.remove(checker)
292 self._checkers.remove(checker)
293
293
294 #-------------------------------------------------------------------------
294 #-------------------------------------------------------------------------
295 # API for managing checkers
295 # API for managing checkers
296 #-------------------------------------------------------------------------
296 #-------------------------------------------------------------------------
297
297
298 def init_handlers(self):
298 def init_handlers(self):
299 """Create the default handlers."""
299 """Create the default handlers."""
300 self._handlers = {}
300 self._handlers = {}
301 self._esc_handlers = {}
301 self._esc_handlers = {}
302 for handler in _default_handlers:
302 for handler in _default_handlers:
303 handler(
303 handler(
304 shell=self.shell, prefilter_manager=self, config=self.config
304 shell=self.shell, prefilter_manager=self, config=self.config
305 )
305 )
306
306
307 @property
307 @property
308 def handlers(self):
308 def handlers(self):
309 """Return a dict of all the handlers."""
309 """Return a dict of all the handlers."""
310 return self._handlers
310 return self._handlers
311
311
312 def register_handler(self, name, handler, esc_strings):
312 def register_handler(self, name, handler, esc_strings):
313 """Register a handler instance by name with esc_strings."""
313 """Register a handler instance by name with esc_strings."""
314 self._handlers[name] = handler
314 self._handlers[name] = handler
315 for esc_str in esc_strings:
315 for esc_str in esc_strings:
316 self._esc_handlers[esc_str] = handler
316 self._esc_handlers[esc_str] = handler
317
317
318 def unregister_handler(self, name, handler, esc_strings):
318 def unregister_handler(self, name, handler, esc_strings):
319 """Unregister a handler instance by name with esc_strings."""
319 """Unregister a handler instance by name with esc_strings."""
320 try:
320 try:
321 del self._handlers[name]
321 del self._handlers[name]
322 except KeyError:
322 except KeyError:
323 pass
323 pass
324 for esc_str in esc_strings:
324 for esc_str in esc_strings:
325 h = self._esc_handlers.get(esc_str)
325 h = self._esc_handlers.get(esc_str)
326 if h is handler:
326 if h is handler:
327 del self._esc_handlers[esc_str]
327 del self._esc_handlers[esc_str]
328
328
329 def get_handler_by_name(self, name):
329 def get_handler_by_name(self, name):
330 """Get a handler by its name."""
330 """Get a handler by its name."""
331 return self._handlers.get(name)
331 return self._handlers.get(name)
332
332
333 def get_handler_by_esc(self, esc_str):
333 def get_handler_by_esc(self, esc_str):
334 """Get a handler by its escape string."""
334 """Get a handler by its escape string."""
335 return self._esc_handlers.get(esc_str)
335 return self._esc_handlers.get(esc_str)
336
336
337 #-------------------------------------------------------------------------
337 #-------------------------------------------------------------------------
338 # Main prefiltering API
338 # Main prefiltering API
339 #-------------------------------------------------------------------------
339 #-------------------------------------------------------------------------
340
340
341 def prefilter_line_info(self, line_info):
341 def prefilter_line_info(self, line_info):
342 """Prefilter a line that has been converted to a LineInfo object.
342 """Prefilter a line that has been converted to a LineInfo object.
343
343
344 This implements the checker/handler part of the prefilter pipe.
344 This implements the checker/handler part of the prefilter pipe.
345 """
345 """
346 # print "prefilter_line_info: ", line_info
346 # print "prefilter_line_info: ", line_info
347 handler = self.find_handler(line_info)
347 handler = self.find_handler(line_info)
348 return handler.handle(line_info)
348 return handler.handle(line_info)
349
349
350 def find_handler(self, line_info):
350 def find_handler(self, line_info):
351 """Find a handler for the line_info by trying checkers."""
351 """Find a handler for the line_info by trying checkers."""
352 for checker in self.checkers:
352 for checker in self.checkers:
353 if checker.enabled:
353 if checker.enabled:
354 handler = checker.check(line_info)
354 handler = checker.check(line_info)
355 if handler:
355 if handler:
356 return handler
356 return handler
357 return self.get_handler_by_name('normal')
357 return self.get_handler_by_name('normal')
358
358
359 def transform_line(self, line, continue_prompt):
359 def transform_line(self, line, continue_prompt):
360 """Calls the enabled transformers in order of increasing priority."""
360 """Calls the enabled transformers in order of increasing priority."""
361 for transformer in self.transformers:
361 for transformer in self.transformers:
362 if transformer.enabled:
362 if transformer.enabled:
363 line = transformer.transform(line, continue_prompt)
363 line = transformer.transform(line, continue_prompt)
364 return line
364 return line
365
365
366 def prefilter_line(self, line, continue_prompt=False):
366 def prefilter_line(self, line, continue_prompt=False):
367 """Prefilter a single input line as text.
367 """Prefilter a single input line as text.
368
368
369 This method prefilters a single line of text by calling the
369 This method prefilters a single line of text by calling the
370 transformers and then the checkers/handlers.
370 transformers and then the checkers/handlers.
371 """
371 """
372
372
373 # print "prefilter_line: ", line, continue_prompt
373 # print "prefilter_line: ", line, continue_prompt
374 # All handlers *must* return a value, even if it's blank ('').
374 # All handlers *must* return a value, even if it's blank ('').
375
375
376 # Lines are NOT logged here. Handlers should process the line as
376 # Lines are NOT logged here. Handlers should process the line as
377 # needed, update the cache AND log it (so that the input cache array
377 # needed, update the cache AND log it (so that the input cache array
378 # stays synced).
378 # stays synced).
379
379
380 # save the line away in case we crash, so the post-mortem handler can
380 # save the line away in case we crash, so the post-mortem handler can
381 # record it
381 # record it
382 self.shell._last_input_line = line
382 self.shell._last_input_line = line
383
383
384 if not line:
384 if not line:
385 # Return immediately on purely empty lines, so that if the user
385 # Return immediately on purely empty lines, so that if the user
386 # previously typed some whitespace that started a continuation
386 # previously typed some whitespace that started a continuation
387 # prompt, he can break out of that loop with just an empty line.
387 # prompt, he can break out of that loop with just an empty line.
388 # This is how the default python prompt works.
388 # This is how the default python prompt works.
389
389
390 # Only return if the accumulated input buffer was just whitespace!
390 # Only return if the accumulated input buffer was just whitespace!
391 if ''.join(self.shell.buffer).isspace():
391 if ''.join(self.shell.buffer).isspace():
392 self.shell.buffer[:] = []
392 self.shell.buffer[:] = []
393 return ''
393 return ''
394
394
395 # At this point, we invoke our transformers.
395 # At this point, we invoke our transformers.
396 if not continue_prompt or (continue_prompt and self.multi_line_specials):
396 if not continue_prompt or (continue_prompt and self.multi_line_specials):
397 line = self.transform_line(line, continue_prompt)
397 line = self.transform_line(line, continue_prompt)
398
398
399 # Now we compute line_info for the checkers and handlers
399 # Now we compute line_info for the checkers and handlers
400 line_info = LineInfo(line, continue_prompt)
400 line_info = LineInfo(line, continue_prompt)
401
401
402 # the input history needs to track even empty lines
402 # the input history needs to track even empty lines
403 stripped = line.strip()
403 stripped = line.strip()
404
404
405 normal_handler = self.get_handler_by_name('normal')
405 normal_handler = self.get_handler_by_name('normal')
406 if not stripped:
406 if not stripped:
407 if not continue_prompt:
407 if not continue_prompt:
408 self.shell.displayhook.prompt_count -= 1
408 self.shell.displayhook.prompt_count -= 1
409
409
410 return normal_handler.handle(line_info)
410 return normal_handler.handle(line_info)
411
411
412 # special handlers are only allowed for single line statements
412 # special handlers are only allowed for single line statements
413 if continue_prompt and not self.multi_line_specials:
413 if continue_prompt and not self.multi_line_specials:
414 return normal_handler.handle(line_info)
414 return normal_handler.handle(line_info)
415
415
416 prefiltered = self.prefilter_line_info(line_info)
416 prefiltered = self.prefilter_line_info(line_info)
417 # print "prefiltered line: %r" % prefiltered
417 # print "prefiltered line: %r" % prefiltered
418 return prefiltered
418 return prefiltered
419
419
420 def prefilter_lines(self, lines, continue_prompt=False):
420 def prefilter_lines(self, lines, continue_prompt=False):
421 """Prefilter multiple input lines of text.
421 """Prefilter multiple input lines of text.
422
422
423 This is the main entry point for prefiltering multiple lines of
423 This is the main entry point for prefiltering multiple lines of
424 input. This simply calls :meth:`prefilter_line` for each line of
424 input. This simply calls :meth:`prefilter_line` for each line of
425 input.
425 input.
426
426
427 This covers cases where there are multiple lines in the user entry,
427 This covers cases where there are multiple lines in the user entry,
428 which is the case when the user goes back to a multiline history
428 which is the case when the user goes back to a multiline history
429 entry and presses enter.
429 entry and presses enter.
430 """
430 """
431 llines = lines.rstrip('\n').split('\n')
431 llines = lines.rstrip('\n').split('\n')
432 # We can get multiple lines in one shot, where multiline input 'blends'
432 # We can get multiple lines in one shot, where multiline input 'blends'
433 # into one line, in cases like recalling from the readline history
433 # into one line, in cases like recalling from the readline history
434 # buffer. We need to make sure that in such cases, we correctly
434 # buffer. We need to make sure that in such cases, we correctly
435 # communicate downstream which line is first and which are continuation
435 # communicate downstream which line is first and which are continuation
436 # ones.
436 # ones.
437 if len(llines) > 1:
437 if len(llines) > 1:
438 out = '\n'.join([self.prefilter_line(line, lnum>0)
438 out = '\n'.join([self.prefilter_line(line, lnum>0)
439 for lnum, line in enumerate(llines) ])
439 for lnum, line in enumerate(llines) ])
440 else:
440 else:
441 out = self.prefilter_line(llines[0], continue_prompt)
441 out = self.prefilter_line(llines[0], continue_prompt)
442
442
443 return out
443 return out
444
444
445 #-----------------------------------------------------------------------------
445 #-----------------------------------------------------------------------------
446 # Prefilter transformers
446 # Prefilter transformers
447 #-----------------------------------------------------------------------------
447 #-----------------------------------------------------------------------------
448
448
449
449
450 class PrefilterTransformer(Configurable):
450 class PrefilterTransformer(Configurable):
451 """Transform a line of user input."""
451 """Transform a line of user input."""
452
452
453 priority = Int(100, config=True)
453 priority = Int(100, config=True)
454 # Transformers don't currently use shell or prefilter_manager, but as we
454 # Transformers don't currently use shell or prefilter_manager, but as we
455 # move away from checkers and handlers, they will need them.
455 # move away from checkers and handlers, they will need them.
456 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
456 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
457 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
457 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
458 enabled = Bool(True, config=True)
458 enabled = Bool(True, config=True)
459
459
460 def __init__(self, shell=None, prefilter_manager=None, config=None):
460 def __init__(self, shell=None, prefilter_manager=None, config=None):
461 super(PrefilterTransformer, self).__init__(
461 super(PrefilterTransformer, self).__init__(
462 shell=shell, prefilter_manager=prefilter_manager, config=config
462 shell=shell, prefilter_manager=prefilter_manager, config=config
463 )
463 )
464 self.prefilter_manager.register_transformer(self)
464 self.prefilter_manager.register_transformer(self)
465
465
466 def transform(self, line, continue_prompt):
466 def transform(self, line, continue_prompt):
467 """Transform a line, returning the new one."""
467 """Transform a line, returning the new one."""
468 return None
468 return None
469
469
470 def __repr__(self):
470 def __repr__(self):
471 return "<%s(priority=%r, enabled=%r)>" % (
471 return "<%s(priority=%r, enabled=%r)>" % (
472 self.__class__.__name__, self.priority, self.enabled)
472 self.__class__.__name__, self.priority, self.enabled)
473
473
474
474
475 _assign_system_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
475 _assign_system_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
476 r'\s*=\s*!(?P<cmd>.*)')
476 r'\s*=\s*!(?P<cmd>.*)')
477
477
478
478
479 class AssignSystemTransformer(PrefilterTransformer):
479 class AssignSystemTransformer(PrefilterTransformer):
480 """Handle the `files = !ls` syntax."""
480 """Handle the `files = !ls` syntax."""
481
481
482 priority = Int(100, config=True)
482 priority = Int(100, config=True)
483
483
484 def transform(self, line, continue_prompt):
484 def transform(self, line, continue_prompt):
485 m = _assign_system_re.match(line)
485 m = _assign_system_re.match(line)
486 if m is not None:
486 if m is not None:
487 cmd = m.group('cmd')
487 cmd = m.group('cmd')
488 lhs = m.group('lhs')
488 lhs = m.group('lhs')
489 expr = make_quoted_expr("sc -l =%s" % cmd)
489 expr = make_quoted_expr("sc -l =%s" % cmd)
490 new_line = '%s = get_ipython().magic(%s)' % (lhs, expr)
490 new_line = '%s = get_ipython().magic(%s)' % (lhs, expr)
491 return new_line
491 return new_line
492 return line
492 return line
493
493
494
494
495 _assign_magic_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
495 _assign_magic_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
496 r'\s*=\s*%(?P<cmd>.*)')
496 r'\s*=\s*%(?P<cmd>.*)')
497
497
498 class AssignMagicTransformer(PrefilterTransformer):
498 class AssignMagicTransformer(PrefilterTransformer):
499 """Handle the `a = %who` syntax."""
499 """Handle the `a = %who` syntax."""
500
500
501 priority = Int(200, config=True)
501 priority = Int(200, config=True)
502
502
503 def transform(self, line, continue_prompt):
503 def transform(self, line, continue_prompt):
504 m = _assign_magic_re.match(line)
504 m = _assign_magic_re.match(line)
505 if m is not None:
505 if m is not None:
506 cmd = m.group('cmd')
506 cmd = m.group('cmd')
507 lhs = m.group('lhs')
507 lhs = m.group('lhs')
508 expr = make_quoted_expr(cmd)
508 expr = make_quoted_expr(cmd)
509 new_line = '%s = get_ipython().magic(%s)' % (lhs, expr)
509 new_line = '%s = get_ipython().magic(%s)' % (lhs, expr)
510 return new_line
510 return new_line
511 return line
511 return line
512
512
513
513
514 _classic_prompt_re = re.compile(r'(^[ \t]*>>> |^[ \t]*\.\.\. )')
514 _classic_prompt_re = re.compile(r'(^[ \t]*>>> |^[ \t]*\.\.\. )')
515
515
516 class PyPromptTransformer(PrefilterTransformer):
516 class PyPromptTransformer(PrefilterTransformer):
517 """Handle inputs that start with '>>> ' syntax."""
517 """Handle inputs that start with '>>> ' syntax."""
518
518
519 priority = Int(50, config=True)
519 priority = Int(50, config=True)
520
520
521 def transform(self, line, continue_prompt):
521 def transform(self, line, continue_prompt):
522
522
523 if not line or line.isspace() or line.strip() == '...':
523 if not line or line.isspace() or line.strip() == '...':
524 # This allows us to recognize multiple input prompts separated by
524 # This allows us to recognize multiple input prompts separated by
525 # blank lines and pasted in a single chunk, very common when
525 # blank lines and pasted in a single chunk, very common when
526 # pasting doctests or long tutorial passages.
526 # pasting doctests or long tutorial passages.
527 return ''
527 return ''
528 m = _classic_prompt_re.match(line)
528 m = _classic_prompt_re.match(line)
529 if m:
529 if m:
530 return line[len(m.group(0)):]
530 return line[len(m.group(0)):]
531 else:
531 else:
532 return line
532 return line
533
533
534
534
535 _ipy_prompt_re = re.compile(r'(^[ \t]*In \[\d+\]: |^[ \t]*\ \ \ \.\.\.+: )')
535 _ipy_prompt_re = re.compile(r'(^[ \t]*In \[\d+\]: |^[ \t]*\ \ \ \.\.\.+: )')
536
536
537 class IPyPromptTransformer(PrefilterTransformer):
537 class IPyPromptTransformer(PrefilterTransformer):
538 """Handle inputs that start classic IPython prompt syntax."""
538 """Handle inputs that start classic IPython prompt syntax."""
539
539
540 priority = Int(50, config=True)
540 priority = Int(50, config=True)
541
541
542 def transform(self, line, continue_prompt):
542 def transform(self, line, continue_prompt):
543
543
544 if not line or line.isspace() or line.strip() == '...':
544 if not line or line.isspace() or line.strip() == '...':
545 # This allows us to recognize multiple input prompts separated by
545 # This allows us to recognize multiple input prompts separated by
546 # blank lines and pasted in a single chunk, very common when
546 # blank lines and pasted in a single chunk, very common when
547 # pasting doctests or long tutorial passages.
547 # pasting doctests or long tutorial passages.
548 return ''
548 return ''
549 m = _ipy_prompt_re.match(line)
549 m = _ipy_prompt_re.match(line)
550 if m:
550 if m:
551 return line[len(m.group(0)):]
551 return line[len(m.group(0)):]
552 else:
552 else:
553 return line
553 return line
554
554
555 #-----------------------------------------------------------------------------
555 #-----------------------------------------------------------------------------
556 # Prefilter checkers
556 # Prefilter checkers
557 #-----------------------------------------------------------------------------
557 #-----------------------------------------------------------------------------
558
558
559
559
560 class PrefilterChecker(Configurable):
560 class PrefilterChecker(Configurable):
561 """Inspect an input line and return a handler for that line."""
561 """Inspect an input line and return a handler for that line."""
562
562
563 priority = Int(100, config=True)
563 priority = Int(100, config=True)
564 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
564 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
565 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
565 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
566 enabled = Bool(True, config=True)
566 enabled = Bool(True, config=True)
567
567
568 def __init__(self, shell=None, prefilter_manager=None, config=None):
568 def __init__(self, shell=None, prefilter_manager=None, config=None):
569 super(PrefilterChecker, self).__init__(
569 super(PrefilterChecker, self).__init__(
570 shell=shell, prefilter_manager=prefilter_manager, config=config
570 shell=shell, prefilter_manager=prefilter_manager, config=config
571 )
571 )
572 self.prefilter_manager.register_checker(self)
572 self.prefilter_manager.register_checker(self)
573
573
574 def check(self, line_info):
574 def check(self, line_info):
575 """Inspect line_info and return a handler instance or None."""
575 """Inspect line_info and return a handler instance or None."""
576 return None
576 return None
577
577
578 def __repr__(self):
578 def __repr__(self):
579 return "<%s(priority=%r, enabled=%r)>" % (
579 return "<%s(priority=%r, enabled=%r)>" % (
580 self.__class__.__name__, self.priority, self.enabled)
580 self.__class__.__name__, self.priority, self.enabled)
581
581
582
582
583 class EmacsChecker(PrefilterChecker):
583 class EmacsChecker(PrefilterChecker):
584
584
585 priority = Int(100, config=True)
585 priority = Int(100, config=True)
586 enabled = Bool(False, config=True)
586 enabled = Bool(False, config=True)
587
587
588 def check(self, line_info):
588 def check(self, line_info):
589 "Emacs ipython-mode tags certain input lines."
589 "Emacs ipython-mode tags certain input lines."
590 if line_info.line.endswith('# PYTHON-MODE'):
590 if line_info.line.endswith('# PYTHON-MODE'):
591 return self.prefilter_manager.get_handler_by_name('emacs')
591 return self.prefilter_manager.get_handler_by_name('emacs')
592 else:
592 else:
593 return None
593 return None
594
594
595
595
596 class ShellEscapeChecker(PrefilterChecker):
596 class ShellEscapeChecker(PrefilterChecker):
597
597
598 priority = Int(200, config=True)
598 priority = Int(200, config=True)
599
599
600 def check(self, line_info):
600 def check(self, line_info):
601 if line_info.line.lstrip().startswith(ESC_SHELL):
601 if line_info.line.lstrip().startswith(ESC_SHELL):
602 return self.prefilter_manager.get_handler_by_name('shell')
602 return self.prefilter_manager.get_handler_by_name('shell')
603
603
604
604
605 class IPyAutocallChecker(PrefilterChecker):
605 class IPyAutocallChecker(PrefilterChecker):
606
606
607 priority = Int(300, config=True)
607 priority = Int(300, config=True)
608
608
609 def check(self, line_info):
609 def check(self, line_info):
610 "Instances of IPyAutocall in user_ns get autocalled immediately"
610 "Instances of IPyAutocall in user_ns get autocalled immediately"
611 obj = self.shell.user_ns.get(line_info.ifun, None)
611 obj = self.shell.user_ns.get(line_info.ifun, None)
612 if isinstance(obj, IPyAutocall):
612 if isinstance(obj, IPyAutocall):
613 obj.set_ip(self.shell)
613 obj.set_ip(self.shell)
614 return self.prefilter_manager.get_handler_by_name('auto')
614 return self.prefilter_manager.get_handler_by_name('auto')
615 else:
615 else:
616 return None
616 return None
617
617
618
618
619 class MultiLineMagicChecker(PrefilterChecker):
619 class MultiLineMagicChecker(PrefilterChecker):
620
620
621 priority = Int(400, config=True)
621 priority = Int(400, config=True)
622
622
623 def check(self, line_info):
623 def check(self, line_info):
624 "Allow ! and !! in multi-line statements if multi_line_specials is on"
624 "Allow ! and !! in multi-line statements if multi_line_specials is on"
625 # Note that this one of the only places we check the first character of
625 # Note that this one of the only places we check the first character of
626 # ifun and *not* the pre_char. Also note that the below test matches
626 # ifun and *not* the pre_char. Also note that the below test matches
627 # both ! and !!.
627 # both ! and !!.
628 if line_info.continue_prompt \
628 if line_info.continue_prompt \
629 and self.prefilter_manager.multi_line_specials:
629 and self.prefilter_manager.multi_line_specials:
630 if line_info.ifun.startswith(ESC_MAGIC):
630 if line_info.ifun.startswith(ESC_MAGIC):
631 return self.prefilter_manager.get_handler_by_name('magic')
631 return self.prefilter_manager.get_handler_by_name('magic')
632 else:
632 else:
633 return None
633 return None
634
634
635
635
636 class EscCharsChecker(PrefilterChecker):
636 class EscCharsChecker(PrefilterChecker):
637
637
638 priority = Int(500, config=True)
638 priority = Int(500, config=True)
639
639
640 def check(self, line_info):
640 def check(self, line_info):
641 """Check for escape character and return either a handler to handle it,
641 """Check for escape character and return either a handler to handle it,
642 or None if there is no escape char."""
642 or None if there is no escape char."""
643 if line_info.line[-1] == ESC_HELP \
643 if line_info.line[-1] == ESC_HELP \
644 and line_info.pre_char != ESC_SHELL \
644 and line_info.pre_char != ESC_SHELL \
645 and line_info.pre_char != ESC_SH_CAP:
645 and line_info.pre_char != ESC_SH_CAP:
646 # the ? can be at the end, but *not* for either kind of shell escape,
646 # the ? can be at the end, but *not* for either kind of shell escape,
647 # because a ? can be a vaild final char in a shell cmd
647 # because a ? can be a vaild final char in a shell cmd
648 return self.prefilter_manager.get_handler_by_name('help')
648 return self.prefilter_manager.get_handler_by_name('help')
649 else:
649 else:
650 # This returns None like it should if no handler exists
650 # This returns None like it should if no handler exists
651 return self.prefilter_manager.get_handler_by_esc(line_info.pre_char)
651 return self.prefilter_manager.get_handler_by_esc(line_info.pre_char)
652
652
653
653
654 class AssignmentChecker(PrefilterChecker):
654 class AssignmentChecker(PrefilterChecker):
655
655
656 priority = Int(600, config=True)
656 priority = Int(600, config=True)
657
657
658 def check(self, line_info):
658 def check(self, line_info):
659 """Check to see if user is assigning to a var for the first time, in
659 """Check to see if user is assigning to a var for the first time, in
660 which case we want to avoid any sort of automagic / autocall games.
660 which case we want to avoid any sort of automagic / autocall games.
661
661
662 This allows users to assign to either alias or magic names true python
662 This allows users to assign to either alias or magic names true python
663 variables (the magic/alias systems always take second seat to true
663 variables (the magic/alias systems always take second seat to true
664 python code). E.g. ls='hi', or ls,that=1,2"""
664 python code). E.g. ls='hi', or ls,that=1,2"""
665 if line_info.the_rest:
665 if line_info.the_rest:
666 if line_info.the_rest[0] in '=,':
666 if line_info.the_rest[0] in '=,':
667 return self.prefilter_manager.get_handler_by_name('normal')
667 return self.prefilter_manager.get_handler_by_name('normal')
668 else:
668 else:
669 return None
669 return None
670
670
671
671
672 class AutoMagicChecker(PrefilterChecker):
672 class AutoMagicChecker(PrefilterChecker):
673
673
674 priority = Int(700, config=True)
674 priority = Int(700, config=True)
675
675
676 def check(self, line_info):
676 def check(self, line_info):
677 """If the ifun is magic, and automagic is on, run it. Note: normal,
677 """If the ifun is magic, and automagic is on, run it. Note: normal,
678 non-auto magic would already have been triggered via '%' in
678 non-auto magic would already have been triggered via '%' in
679 check_esc_chars. This just checks for automagic. Also, before
679 check_esc_chars. This just checks for automagic. Also, before
680 triggering the magic handler, make sure that there is nothing in the
680 triggering the magic handler, make sure that there is nothing in the
681 user namespace which could shadow it."""
681 user namespace which could shadow it."""
682 if not self.shell.automagic or not hasattr(self.shell,'magic_'+line_info.ifun):
682 if not self.shell.automagic or not hasattr(self.shell,'magic_'+line_info.ifun):
683 return None
683 return None
684
684
685 # We have a likely magic method. Make sure we should actually call it.
685 # We have a likely magic method. Make sure we should actually call it.
686 if line_info.continue_prompt and not self.prefilter_manager.multi_line_specials:
686 if line_info.continue_prompt and not self.prefilter_manager.multi_line_specials:
687 return None
687 return None
688
688
689 head = line_info.ifun.split('.',1)[0]
689 head = line_info.ifun.split('.',1)[0]
690 if is_shadowed(head, self.shell):
690 if is_shadowed(head, self.shell):
691 return None
691 return None
692
692
693 return self.prefilter_manager.get_handler_by_name('magic')
693 return self.prefilter_manager.get_handler_by_name('magic')
694
694
695
695
696 class AliasChecker(PrefilterChecker):
696 class AliasChecker(PrefilterChecker):
697
697
698 priority = Int(800, config=True)
698 priority = Int(800, config=True)
699
699
700 def check(self, line_info):
700 def check(self, line_info):
701 "Check if the initital identifier on the line is an alias."
701 "Check if the initital identifier on the line is an alias."
702 # Note: aliases can not contain '.'
702 # Note: aliases can not contain '.'
703 head = line_info.ifun.split('.',1)[0]
703 head = line_info.ifun.split('.',1)[0]
704 if line_info.ifun not in self.shell.alias_manager \
704 if line_info.ifun not in self.shell.alias_manager \
705 or head not in self.shell.alias_manager \
705 or head not in self.shell.alias_manager \
706 or is_shadowed(head, self.shell):
706 or is_shadowed(head, self.shell):
707 return None
707 return None
708
708
709 return self.prefilter_manager.get_handler_by_name('alias')
709 return self.prefilter_manager.get_handler_by_name('alias')
710
710
711
711
712 class PythonOpsChecker(PrefilterChecker):
712 class PythonOpsChecker(PrefilterChecker):
713
713
714 priority = Int(900, config=True)
714 priority = Int(900, config=True)
715
715
716 def check(self, line_info):
716 def check(self, line_info):
717 """If the 'rest' of the line begins with a function call or pretty much
717 """If the 'rest' of the line begins with a function call or pretty much
718 any python operator, we should simply execute the line (regardless of
718 any python operator, we should simply execute the line (regardless of
719 whether or not there's a possible autocall expansion). This avoids
719 whether or not there's a possible autocall expansion). This avoids
720 spurious (and very confusing) geattr() accesses."""
720 spurious (and very confusing) geattr() accesses."""
721 if line_info.the_rest and line_info.the_rest[0] in '!=()<>,+*/%^&|':
721 if line_info.the_rest and line_info.the_rest[0] in '!=()<>,+*/%^&|':
722 return self.prefilter_manager.get_handler_by_name('normal')
722 return self.prefilter_manager.get_handler_by_name('normal')
723 else:
723 else:
724 return None
724 return None
725
725
726
726
727 class AutocallChecker(PrefilterChecker):
727 class AutocallChecker(PrefilterChecker):
728
728
729 priority = Int(1000, config=True)
729 priority = Int(1000, config=True)
730
730
731 def check(self, line_info):
731 def check(self, line_info):
732 "Check if the initial word/function is callable and autocall is on."
732 "Check if the initial word/function is callable and autocall is on."
733 if not self.shell.autocall:
733 if not self.shell.autocall:
734 return None
734 return None
735
735
736 oinfo = line_info.ofind(self.shell) # This can mutate state via getattr
736 oinfo = line_info.ofind(self.shell) # This can mutate state via getattr
737 if not oinfo['found']:
737 if not oinfo['found']:
738 return None
738 return None
739
739
740 if callable(oinfo['obj']) \
740 if callable(oinfo['obj']) \
741 and (not re_exclude_auto.match(line_info.the_rest)) \
741 and (not re_exclude_auto.match(line_info.the_rest)) \
742 and re_fun_name.match(line_info.ifun):
742 and re_fun_name.match(line_info.ifun):
743 return self.prefilter_manager.get_handler_by_name('auto')
743 return self.prefilter_manager.get_handler_by_name('auto')
744 else:
744 else:
745 return None
745 return None
746
746
747
747
748 #-----------------------------------------------------------------------------
748 #-----------------------------------------------------------------------------
749 # Prefilter handlers
749 # Prefilter handlers
750 #-----------------------------------------------------------------------------
750 #-----------------------------------------------------------------------------
751
751
752
752
753 class PrefilterHandler(Configurable):
753 class PrefilterHandler(Configurable):
754
754
755 handler_name = Str('normal')
755 handler_name = Str('normal')
756 esc_strings = List([])
756 esc_strings = List([])
757 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
757 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
758 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
758 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
759
759
760 def __init__(self, shell=None, prefilter_manager=None, config=None):
760 def __init__(self, shell=None, prefilter_manager=None, config=None):
761 super(PrefilterHandler, self).__init__(
761 super(PrefilterHandler, self).__init__(
762 shell=shell, prefilter_manager=prefilter_manager, config=config
762 shell=shell, prefilter_manager=prefilter_manager, config=config
763 )
763 )
764 self.prefilter_manager.register_handler(
764 self.prefilter_manager.register_handler(
765 self.handler_name,
765 self.handler_name,
766 self,
766 self,
767 self.esc_strings
767 self.esc_strings
768 )
768 )
769
769
770 def handle(self, line_info):
770 def handle(self, line_info):
771 # print "normal: ", line_info
771 # print "normal: ", line_info
772 """Handle normal input lines. Use as a template for handlers."""
772 """Handle normal input lines. Use as a template for handlers."""
773
773
774 # With autoindent on, we need some way to exit the input loop, and I
774 # With autoindent on, we need some way to exit the input loop, and I
775 # don't want to force the user to have to backspace all the way to
775 # don't want to force the user to have to backspace all the way to
776 # clear the line. The rule will be in this case, that either two
776 # clear the line. The rule will be in this case, that either two
777 # lines of pure whitespace in a row, or a line of pure whitespace but
777 # lines of pure whitespace in a row, or a line of pure whitespace but
778 # of a size different to the indent level, will exit the input loop.
778 # of a size different to the indent level, will exit the input loop.
779 line = line_info.line
779 line = line_info.line
780 continue_prompt = line_info.continue_prompt
780 continue_prompt = line_info.continue_prompt
781
781
782 if (continue_prompt and
782 if (continue_prompt and
783 self.shell.autoindent and
783 self.shell.autoindent and
784 line.isspace() and
784 line.isspace() and
785
785
786 (0 < abs(len(line) - self.shell.indent_current_nsp) <= 2
786 (0 < abs(len(line) - self.shell.indent_current_nsp) <= 2
787 or
787 or
788 not self.shell.buffer
788 not self.shell.buffer
789 or
789 or
790 (self.shell.buffer[-1]).isspace()
790 (self.shell.buffer[-1]).isspace()
791 )
791 )
792 ):
792 ):
793 line = ''
793 line = ''
794
794
795 self.shell.log(line, line, continue_prompt)
795 self.shell.log(line, line, continue_prompt)
796 return line
796 return line
797
797
798 def __str__(self):
798 def __str__(self):
799 return "<%s(name=%s)>" % (self.__class__.__name__, self.handler_name)
799 return "<%s(name=%s)>" % (self.__class__.__name__, self.handler_name)
800
800
801
801
802 class AliasHandler(PrefilterHandler):
802 class AliasHandler(PrefilterHandler):
803
803
804 handler_name = Str('alias')
804 handler_name = Str('alias')
805
805
806 def handle(self, line_info):
806 def handle(self, line_info):
807 """Handle alias input lines. """
807 """Handle alias input lines. """
808 transformed = self.shell.alias_manager.expand_aliases(line_info.ifun,line_info.the_rest)
808 transformed = self.shell.alias_manager.expand_aliases(line_info.ifun,line_info.the_rest)
809 # pre is needed, because it carries the leading whitespace. Otherwise
809 # pre is needed, because it carries the leading whitespace. Otherwise
810 # aliases won't work in indented sections.
810 # aliases won't work in indented sections.
811 line_out = '%sget_ipython().system(%s)' % (line_info.pre_whitespace,
811 line_out = '%sget_ipython().system(%s)' % (line_info.pre_whitespace,
812 make_quoted_expr(transformed))
812 make_quoted_expr(transformed))
813
813
814 self.shell.log(line_info.line, line_out, line_info.continue_prompt)
814 self.shell.log(line_info.line, line_out, line_info.continue_prompt)
815 return line_out
815 return line_out
816
816
817
817
818 class ShellEscapeHandler(PrefilterHandler):
818 class ShellEscapeHandler(PrefilterHandler):
819
819
820 handler_name = Str('shell')
820 handler_name = Str('shell')
821 esc_strings = List([ESC_SHELL, ESC_SH_CAP])
821 esc_strings = List([ESC_SHELL, ESC_SH_CAP])
822
822
823 def handle(self, line_info):
823 def handle(self, line_info):
824 """Execute the line in a shell, empty return value"""
824 """Execute the line in a shell, empty return value"""
825 magic_handler = self.prefilter_manager.get_handler_by_name('magic')
825 magic_handler = self.prefilter_manager.get_handler_by_name('magic')
826
826
827 line = line_info.line
827 line = line_info.line
828 if line.lstrip().startswith(ESC_SH_CAP):
828 if line.lstrip().startswith(ESC_SH_CAP):
829 # rewrite LineInfo's line, ifun and the_rest to properly hold the
829 # rewrite LineInfo's line, ifun and the_rest to properly hold the
830 # call to %sx and the actual command to be executed, so
830 # call to %sx and the actual command to be executed, so
831 # handle_magic can work correctly. Note that this works even if
831 # handle_magic can work correctly. Note that this works even if
832 # the line is indented, so it handles multi_line_specials
832 # the line is indented, so it handles multi_line_specials
833 # properly.
833 # properly.
834 new_rest = line.lstrip()[2:]
834 new_rest = line.lstrip()[2:]
835 line_info.line = '%ssx %s' % (ESC_MAGIC, new_rest)
835 line_info.line = '%ssx %s' % (ESC_MAGIC, new_rest)
836 line_info.ifun = 'sx'
836 line_info.ifun = 'sx'
837 line_info.the_rest = new_rest
837 line_info.the_rest = new_rest
838 return magic_handler.handle(line_info)
838 return magic_handler.handle(line_info)
839 else:
839 else:
840 cmd = line.lstrip().lstrip(ESC_SHELL)
840 cmd = line.lstrip().lstrip(ESC_SHELL)
841 line_out = '%sget_ipython().system(%s)' % (line_info.pre_whitespace,
841 line_out = '%sget_ipython().system(%s)' % (line_info.pre_whitespace,
842 make_quoted_expr(cmd))
842 make_quoted_expr(cmd))
843 # update cache/log and return
843 # update cache/log and return
844 self.shell.log(line, line_out, line_info.continue_prompt)
844 self.shell.log(line, line_out, line_info.continue_prompt)
845 return line_out
845 return line_out
846
846
847
847
848 class MagicHandler(PrefilterHandler):
848 class MagicHandler(PrefilterHandler):
849
849
850 handler_name = Str('magic')
850 handler_name = Str('magic')
851 esc_strings = List([ESC_MAGIC])
851 esc_strings = List([ESC_MAGIC])
852
852
853 def handle(self, line_info):
853 def handle(self, line_info):
854 """Execute magic functions."""
854 """Execute magic functions."""
855 ifun = line_info.ifun
855 ifun = line_info.ifun
856 the_rest = line_info.the_rest
856 the_rest = line_info.the_rest
857 cmd = '%sget_ipython().magic(%s)' % (line_info.pre_whitespace,
857 cmd = '%sget_ipython().magic(%s)' % (line_info.pre_whitespace,
858 make_quoted_expr(ifun + " " + the_rest))
858 make_quoted_expr(ifun + " " + the_rest))
859 self.shell.log(line_info.line, cmd, line_info.continue_prompt)
859 self.shell.log(line_info.line, cmd, line_info.continue_prompt)
860 return cmd
860 return cmd
861
861
862
862
863 class AutoHandler(PrefilterHandler):
863 class AutoHandler(PrefilterHandler):
864
864
865 handler_name = Str('auto')
865 handler_name = Str('auto')
866 esc_strings = List([ESC_PAREN, ESC_QUOTE, ESC_QUOTE2])
866 esc_strings = List([ESC_PAREN, ESC_QUOTE, ESC_QUOTE2])
867
867
868 def handle(self, line_info):
868 def handle(self, line_info):
869 """Handle lines which can be auto-executed, quoting if requested."""
869 """Handle lines which can be auto-executed, quoting if requested."""
870 line = line_info.line
870 line = line_info.line
871 ifun = line_info.ifun
871 ifun = line_info.ifun
872 the_rest = line_info.the_rest
872 the_rest = line_info.the_rest
873 pre = line_info.pre
873 pre = line_info.pre
874 continue_prompt = line_info.continue_prompt
874 continue_prompt = line_info.continue_prompt
875 obj = line_info.ofind(self)['obj']
875 obj = line_info.ofind(self)['obj']
876 #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun,the_rest) # dbg
876 #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun,the_rest) # dbg
877
877
878 # This should only be active for single-line input!
878 # This should only be active for single-line input!
879 if continue_prompt:
879 if continue_prompt:
880 self.shell.log(line,line,continue_prompt)
880 self.shell.log(line,line,continue_prompt)
881 return line
881 return line
882
882
883 force_auto = isinstance(obj, IPyAutocall)
883 force_auto = isinstance(obj, IPyAutocall)
884 auto_rewrite = True
884 auto_rewrite = True
885
885
886 if pre == ESC_QUOTE:
886 if pre == ESC_QUOTE:
887 # Auto-quote splitting on whitespace
887 # Auto-quote splitting on whitespace
888 newcmd = '%s("%s")' % (ifun,'", "'.join(the_rest.split()) )
888 newcmd = '%s("%s")' % (ifun,'", "'.join(the_rest.split()) )
889 elif pre == ESC_QUOTE2:
889 elif pre == ESC_QUOTE2:
890 # Auto-quote whole string
890 # Auto-quote whole string
891 newcmd = '%s("%s")' % (ifun,the_rest)
891 newcmd = '%s("%s")' % (ifun,the_rest)
892 elif pre == ESC_PAREN:
892 elif pre == ESC_PAREN:
893 newcmd = '%s(%s)' % (ifun,",".join(the_rest.split()))
893 newcmd = '%s(%s)' % (ifun,",".join(the_rest.split()))
894 else:
894 else:
895 # Auto-paren.
895 # Auto-paren.
896 # We only apply it to argument-less calls if the autocall
896 # We only apply it to argument-less calls if the autocall
897 # parameter is set to 2. We only need to check that autocall is <
897 # parameter is set to 2. We only need to check that autocall is <
898 # 2, since this function isn't called unless it's at least 1.
898 # 2, since this function isn't called unless it's at least 1.
899 if not the_rest and (self.shell.autocall < 2) and not force_auto:
899 if not the_rest and (self.shell.autocall < 2) and not force_auto:
900 newcmd = '%s %s' % (ifun,the_rest)
900 newcmd = '%s %s' % (ifun,the_rest)
901 auto_rewrite = False
901 auto_rewrite = False
902 else:
902 else:
903 if not force_auto and the_rest.startswith('['):
903 if not force_auto and the_rest.startswith('['):
904 if hasattr(obj,'__getitem__'):
904 if hasattr(obj,'__getitem__'):
905 # Don't autocall in this case: item access for an object
905 # Don't autocall in this case: item access for an object
906 # which is BOTH callable and implements __getitem__.
906 # which is BOTH callable and implements __getitem__.
907 newcmd = '%s %s' % (ifun,the_rest)
907 newcmd = '%s %s' % (ifun,the_rest)
908 auto_rewrite = False
908 auto_rewrite = False
909 else:
909 else:
910 # if the object doesn't support [] access, go ahead and
910 # if the object doesn't support [] access, go ahead and
911 # autocall
911 # autocall
912 newcmd = '%s(%s)' % (ifun.rstrip(),the_rest)
912 newcmd = '%s(%s)' % (ifun.rstrip(),the_rest)
913 elif the_rest.endswith(';'):
913 elif the_rest.endswith(';'):
914 newcmd = '%s(%s);' % (ifun.rstrip(),the_rest[:-1])
914 newcmd = '%s(%s);' % (ifun.rstrip(),the_rest[:-1])
915 else:
915 else:
916 newcmd = '%s(%s)' % (ifun.rstrip(), the_rest)
916 newcmd = '%s(%s)' % (ifun.rstrip(), the_rest)
917
917
918 if auto_rewrite:
918 if auto_rewrite:
919 rw = self.shell.displayhook.prompt1.auto_rewrite() + newcmd
919 rw = self.shell.displayhook.prompt1.auto_rewrite() + newcmd
920
920
921 try:
921 try:
922 # plain ascii works better w/ pyreadline, on some machines, so
922 # plain ascii works better w/ pyreadline, on some machines, so
923 # we use it and only print uncolored rewrite if we have unicode
923 # we use it and only print uncolored rewrite if we have unicode
924 rw = str(rw)
924 rw = str(rw)
925 print >>IPython.utils.io.Term.cout, rw
925 print >>IPython.utils.io.Term.cout, rw
926 except UnicodeEncodeError:
926 except UnicodeEncodeError:
927 print "-------------->" + newcmd
927 print "-------------->" + newcmd
928
928
929 # log what is now valid Python, not the actual user input (without the
929 # log what is now valid Python, not the actual user input (without the
930 # final newline)
930 # final newline)
931 self.shell.log(line,newcmd,continue_prompt)
931 self.shell.log(line,newcmd,continue_prompt)
932 return newcmd
932 return newcmd
933
933
934
934
935 class HelpHandler(PrefilterHandler):
935 class HelpHandler(PrefilterHandler):
936
936
937 handler_name = Str('help')
937 handler_name = Str('help')
938 esc_strings = List([ESC_HELP])
938 esc_strings = List([ESC_HELP])
939
939
940 def handle(self, line_info):
940 def handle(self, line_info):
941 """Try to get some help for the object.
941 """Try to get some help for the object.
942
942
943 obj? or ?obj -> basic information.
943 obj? or ?obj -> basic information.
944 obj?? or ??obj -> more details.
944 obj?? or ??obj -> more details.
945 """
945 """
946 normal_handler = self.prefilter_manager.get_handler_by_name('normal')
946 normal_handler = self.prefilter_manager.get_handler_by_name('normal')
947 line = line_info.line
947 line = line_info.line
948 # We need to make sure that we don't process lines which would be
948 # We need to make sure that we don't process lines which would be
949 # otherwise valid python, such as "x=1 # what?"
949 # otherwise valid python, such as "x=1 # what?"
950 try:
950 try:
951 codeop.compile_command(line)
951 codeop.compile_command(line)
952 except SyntaxError:
952 except SyntaxError:
953 # We should only handle as help stuff which is NOT valid syntax
953 # We should only handle as help stuff which is NOT valid syntax
954 if line[0]==ESC_HELP:
954 if line[0]==ESC_HELP:
955 line = line[1:]
955 line = line[1:]
956 elif line[-1]==ESC_HELP:
956 elif line[-1]==ESC_HELP:
957 line = line[:-1]
957 line = line[:-1]
958 self.shell.log(line, '#?'+line, line_info.continue_prompt)
958 self.shell.log(line, '#?'+line, line_info.continue_prompt)
959 if line:
959 if line:
960 #print 'line:<%r>' % line # dbg
960 #print 'line:<%r>' % line # dbg
961 self.shell.magic_pinfo(line)
961 self.shell.magic_pinfo(line)
962 else:
962 else:
963 page(self.shell.usage, screen_lines=self.shell.usable_screen_length)
963 page.page(self.shell.usage, screen_lines=self.shell.usable_screen_length)
964 return '' # Empty string is needed here!
964 return '' # Empty string is needed here!
965 except:
965 except:
966 raise
966 raise
967 # Pass any other exceptions through to the normal handler
967 # Pass any other exceptions through to the normal handler
968 return normal_handler.handle(line_info)
968 return normal_handler.handle(line_info)
969 else:
969 else:
970 # If the code compiles ok, we should handle it normally
970 # If the code compiles ok, we should handle it normally
971 return normal_handler.handle(line_info)
971 return normal_handler.handle(line_info)
972
972
973
973
974 class EmacsHandler(PrefilterHandler):
974 class EmacsHandler(PrefilterHandler):
975
975
976 handler_name = Str('emacs')
976 handler_name = Str('emacs')
977 esc_strings = List([])
977 esc_strings = List([])
978
978
979 def handle(self, line_info):
979 def handle(self, line_info):
980 """Handle input lines marked by python-mode."""
980 """Handle input lines marked by python-mode."""
981
981
982 # Currently, nothing is done. Later more functionality can be added
982 # Currently, nothing is done. Later more functionality can be added
983 # here if needed.
983 # here if needed.
984
984
985 # The input cache shouldn't be updated
985 # The input cache shouldn't be updated
986 return line_info.line
986 return line_info.line
987
987
988
988
989 #-----------------------------------------------------------------------------
989 #-----------------------------------------------------------------------------
990 # Defaults
990 # Defaults
991 #-----------------------------------------------------------------------------
991 #-----------------------------------------------------------------------------
992
992
993
993
994 _default_transformers = [
994 _default_transformers = [
995 AssignSystemTransformer,
995 AssignSystemTransformer,
996 AssignMagicTransformer,
996 AssignMagicTransformer,
997 PyPromptTransformer,
997 PyPromptTransformer,
998 IPyPromptTransformer,
998 IPyPromptTransformer,
999 ]
999 ]
1000
1000
1001 _default_checkers = [
1001 _default_checkers = [
1002 EmacsChecker,
1002 EmacsChecker,
1003 ShellEscapeChecker,
1003 ShellEscapeChecker,
1004 IPyAutocallChecker,
1004 IPyAutocallChecker,
1005 MultiLineMagicChecker,
1005 MultiLineMagicChecker,
1006 EscCharsChecker,
1006 EscCharsChecker,
1007 AssignmentChecker,
1007 AssignmentChecker,
1008 AutoMagicChecker,
1008 AutoMagicChecker,
1009 AliasChecker,
1009 AliasChecker,
1010 PythonOpsChecker,
1010 PythonOpsChecker,
1011 AutocallChecker
1011 AutocallChecker
1012 ]
1012 ]
1013
1013
1014 _default_handlers = [
1014 _default_handlers = [
1015 PrefilterHandler,
1015 PrefilterHandler,
1016 AliasHandler,
1016 AliasHandler,
1017 ShellEscapeHandler,
1017 ShellEscapeHandler,
1018 MagicHandler,
1018 MagicHandler,
1019 AutoHandler,
1019 AutoHandler,
1020 HelpHandler,
1020 HelpHandler,
1021 EmacsHandler
1021 EmacsHandler
1022 ]
1022 ]
@@ -1,148 +1,148
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Interactive functions and magic functions for Gnuplot usage.
2 """Interactive functions and magic functions for Gnuplot usage.
3
3
4 This requires the Gnuplot.py module for interfacing python with Gnuplot, which
4 This requires the Gnuplot.py module for interfacing python with Gnuplot, which
5 can be downloaded from:
5 can be downloaded from:
6
6
7 http://gnuplot-py.sourceforge.net/
7 http://gnuplot-py.sourceforge.net/
8
8
9 See gphelp() below for details on the services offered by this module.
9 See gphelp() below for details on the services offered by this module.
10
10
11 Inspired by a suggestion/request from Arnd Baecker.
11 Inspired by a suggestion/request from Arnd Baecker.
12 """
12 """
13
13
14 __all__ = ['Gnuplot','gp','gp_new','plot','plot2','splot','replot',
14 __all__ = ['Gnuplot','gp','gp_new','plot','plot2','splot','replot',
15 'hardcopy','gpdata','gpfile','gpstring','gpfunc','gpgrid',
15 'hardcopy','gpdata','gpfile','gpstring','gpfunc','gpgrid',
16 'gphelp']
16 'gphelp']
17
17
18 import IPython.GnuplotRuntime as GRun
18 import IPython.GnuplotRuntime as GRun
19 from IPython.utils.genutils import warn
19 from IPython.utils.genutils import warn
20 from IPython.core.page import page
20 from IPython.core import page
21
21
22 # Set global names for interactive use
22 # Set global names for interactive use
23 Gnuplot = GRun.Gnuplot
23 Gnuplot = GRun.Gnuplot
24 gp_new = GRun.gp_new
24 gp_new = GRun.gp_new
25 gp = GRun.gp
25 gp = GRun.gp
26 plot = gp.plot
26 plot = gp.plot
27 plot2 = gp.plot2
27 plot2 = gp.plot2
28 splot = gp.splot
28 splot = gp.splot
29 replot = gp.replot
29 replot = gp.replot
30 hardcopy = gp.hardcopy
30 hardcopy = gp.hardcopy
31
31
32 # Accessors for the main plot object constructors:
32 # Accessors for the main plot object constructors:
33 gpdata = Gnuplot.Data
33 gpdata = Gnuplot.Data
34 gpfile = Gnuplot.File
34 gpfile = Gnuplot.File
35 gpstring = Gnuplot.String
35 gpstring = Gnuplot.String
36 gpfunc = Gnuplot.Func
36 gpfunc = Gnuplot.Func
37 gpgrid = Gnuplot.GridData
37 gpgrid = Gnuplot.GridData
38
38
39 def gphelp():
39 def gphelp():
40 """Print information about the Gnuplot facilities in IPython."""
40 """Print information about the Gnuplot facilities in IPython."""
41
41
42 page("""
42 page("""
43 IPython provides an interface to access the Gnuplot scientific plotting
43 IPython provides an interface to access the Gnuplot scientific plotting
44 system, in an environment similar to that of Mathematica or Matlab.
44 system, in an environment similar to that of Mathematica or Matlab.
45
45
46 New top-level global objects
46 New top-level global objects
47 ----------------------------
47 ----------------------------
48
48
49 Please see their respective docstrings for further details.
49 Please see their respective docstrings for further details.
50
50
51 - gp: a running Gnuplot instance. You can access its methods as
51 - gp: a running Gnuplot instance. You can access its methods as
52 gp.<method>. gp(`a string`) will execute the given string as if it had been
52 gp.<method>. gp(`a string`) will execute the given string as if it had been
53 typed in an interactive gnuplot window.
53 typed in an interactive gnuplot window.
54
54
55 - plot, splot, replot and hardcopy: aliases to the methods of the same name in
55 - plot, splot, replot and hardcopy: aliases to the methods of the same name in
56 the global running Gnuplot instance gp. These allow you to simply type:
56 the global running Gnuplot instance gp. These allow you to simply type:
57
57
58 In [1]: plot(x,sin(x),title='Sin(x)') # assuming x is a Numeric array
58 In [1]: plot(x,sin(x),title='Sin(x)') # assuming x is a Numeric array
59
59
60 and obtain a plot of sin(x) vs x with the title 'Sin(x)'.
60 and obtain a plot of sin(x) vs x with the title 'Sin(x)'.
61
61
62 - gp_new: a function which returns a new Gnuplot instance. This can be used to
62 - gp_new: a function which returns a new Gnuplot instance. This can be used to
63 have multiple Gnuplot instances running in your session to compare different
63 have multiple Gnuplot instances running in your session to compare different
64 plots, each in a separate window.
64 plots, each in a separate window.
65
65
66 - Gnuplot: alias to the Gnuplot2 module, an improved drop-in replacement for
66 - Gnuplot: alias to the Gnuplot2 module, an improved drop-in replacement for
67 the original Gnuplot.py. Gnuplot2 needs Gnuplot but redefines several of its
67 the original Gnuplot.py. Gnuplot2 needs Gnuplot but redefines several of its
68 functions with improved versions (Gnuplot2 comes with IPython).
68 functions with improved versions (Gnuplot2 comes with IPython).
69
69
70 - gpdata, gpfile, gpstring, gpfunc, gpgrid: aliases to Gnuplot.Data,
70 - gpdata, gpfile, gpstring, gpfunc, gpgrid: aliases to Gnuplot.Data,
71 Gnuplot.File, Gnuplot.String, Gnuplot.Func and Gnuplot.GridData
71 Gnuplot.File, Gnuplot.String, Gnuplot.Func and Gnuplot.GridData
72 respectively. These functions create objects which can then be passed to the
72 respectively. These functions create objects which can then be passed to the
73 plotting commands. See the Gnuplot.py documentation for details.
73 plotting commands. See the Gnuplot.py documentation for details.
74
74
75 Keep in mind that all commands passed to a Gnuplot instance are executed in
75 Keep in mind that all commands passed to a Gnuplot instance are executed in
76 the Gnuplot namespace, where no Python variables exist. For example, for
76 the Gnuplot namespace, where no Python variables exist. For example, for
77 plotting sin(x) vs x as above, typing
77 plotting sin(x) vs x as above, typing
78
78
79 In [2]: gp('plot x,sin(x)')
79 In [2]: gp('plot x,sin(x)')
80
80
81 would not work. Instead, you would get the plot of BOTH the functions 'x' and
81 would not work. Instead, you would get the plot of BOTH the functions 'x' and
82 'sin(x)', since Gnuplot doesn't know about the 'x' Python array. The plot()
82 'sin(x)', since Gnuplot doesn't know about the 'x' Python array. The plot()
83 method lives in python and does know about these variables.
83 method lives in python and does know about these variables.
84
84
85
85
86 New magic functions
86 New magic functions
87 -------------------
87 -------------------
88
88
89 %gpc: pass one command to Gnuplot and execute it or open a Gnuplot shell where
89 %gpc: pass one command to Gnuplot and execute it or open a Gnuplot shell where
90 each line of input is executed.
90 each line of input is executed.
91
91
92 %gp_set_default: reset the value of IPython's global Gnuplot instance.""")
92 %gp_set_default: reset the value of IPython's global Gnuplot instance.""")
93
93
94 # Code below is all for IPython use
94 # Code below is all for IPython use
95 # Define the magic functions for communicating with the above gnuplot instance.
95 # Define the magic functions for communicating with the above gnuplot instance.
96 def magic_gpc(self,parameter_s=''):
96 def magic_gpc(self,parameter_s=''):
97 """Execute a gnuplot command or open a gnuplot shell.
97 """Execute a gnuplot command or open a gnuplot shell.
98
98
99 Usage (omit the % if automagic is on). There are two ways to use it:
99 Usage (omit the % if automagic is on). There are two ways to use it:
100
100
101 1) %gpc 'command' -> passes 'command' directly to the gnuplot instance.
101 1) %gpc 'command' -> passes 'command' directly to the gnuplot instance.
102
102
103 2) %gpc -> will open up a prompt (gnuplot>>>) which takes input like the
103 2) %gpc -> will open up a prompt (gnuplot>>>) which takes input like the
104 standard gnuplot interactive prompt. If you need to type a multi-line
104 standard gnuplot interactive prompt. If you need to type a multi-line
105 command, use \\ at the end of each intermediate line.
105 command, use \\ at the end of each intermediate line.
106
106
107 Upon exiting of the gnuplot sub-shell, you return to your IPython
107 Upon exiting of the gnuplot sub-shell, you return to your IPython
108 session (the gnuplot sub-shell can be invoked as many times as needed).
108 session (the gnuplot sub-shell can be invoked as many times as needed).
109 """
109 """
110
110
111 if parameter_s.strip():
111 if parameter_s.strip():
112 self.shell.gnuplot(parameter_s)
112 self.shell.gnuplot(parameter_s)
113 else:
113 else:
114 self.shell.gnuplot.interact()
114 self.shell.gnuplot.interact()
115
115
116 def magic_gp_set_default(self,parameter_s=''):
116 def magic_gp_set_default(self,parameter_s=''):
117 """Set the default gnuplot instance accessed by the %gp magic function.
117 """Set the default gnuplot instance accessed by the %gp magic function.
118
118
119 %gp_set_default name
119 %gp_set_default name
120
120
121 Call with the name of the new instance at the command line. If you want to
121 Call with the name of the new instance at the command line. If you want to
122 set this instance in your own code (using an embedded IPython, for
122 set this instance in your own code (using an embedded IPython, for
123 example), simply set the variable __IPYTHON__.gnuplot to your own gnuplot
123 example), simply set the variable __IPYTHON__.gnuplot to your own gnuplot
124 instance object."""
124 instance object."""
125
125
126 gname = parameter_s.strip()
126 gname = parameter_s.strip()
127 G = eval(gname,self.shell.user_ns)
127 G = eval(gname,self.shell.user_ns)
128 self.shell.gnuplot = G
128 self.shell.gnuplot = G
129 self.shell.user_ns.update({'plot':G.plot,'splot':G.splot,'plot2':G.plot2,
129 self.shell.user_ns.update({'plot':G.plot,'splot':G.splot,'plot2':G.plot2,
130 'replot':G.replot,'hardcopy':G.hardcopy})
130 'replot':G.replot,'hardcopy':G.hardcopy})
131
131
132 try:
132 try:
133 __IPYTHON__
133 __IPYTHON__
134 except NameError:
134 except NameError:
135 pass
135 pass
136 else:
136 else:
137 # make the global Gnuplot instance known to IPython
137 # make the global Gnuplot instance known to IPython
138 __IPYTHON__.gnuplot = GRun.gp
138 __IPYTHON__.gnuplot = GRun.gp
139 __IPYTHON__.gnuplot.shell_first_time = 1
139 __IPYTHON__.gnuplot.shell_first_time = 1
140
140
141 print """*** Type `gphelp` for help on the Gnuplot integration features."""
141 print """*** Type `gphelp` for help on the Gnuplot integration features."""
142
142
143 # Add the new magic functions to the class dict
143 # Add the new magic functions to the class dict
144 from IPython.core.iplib import InteractiveShell
144 from IPython.core.iplib import InteractiveShell
145 InteractiveShell.magic_gpc = magic_gpc
145 InteractiveShell.magic_gpc = magic_gpc
146 InteractiveShell.magic_gp_set_default = magic_gp_set_default
146 InteractiveShell.magic_gp_set_default = magic_gp_set_default
147
147
148 #********************** End of file <GnuplotInteractive.py> *******************
148 #********************** End of file <GnuplotInteractive.py> *******************
@@ -1,147 +1,151
1 import os
1 import os
2
2
3 # System library imports
3 # System library imports
4 from PyQt4 import QtCore, QtGui
4 from PyQt4 import QtCore, QtGui
5
5
6 # Local imports
6 # Local imports
7 from IPython.frontend.qt.svg import save_svg, svg_to_clipboard, svg_to_image
7 from IPython.frontend.qt.svg import save_svg, svg_to_clipboard, svg_to_image
8 from ipython_widget import IPythonWidget
8 from ipython_widget import IPythonWidget
9
9
10
10
11 class RichIPythonWidget(IPythonWidget):
11 class RichIPythonWidget(IPythonWidget):
12 """ An IPythonWidget that supports rich text, including lists, images, and
12 """ An IPythonWidget that supports rich text, including lists, images, and
13 tables. Note that raw performance will be reduced compared to the plain
13 tables. Note that raw performance will be reduced compared to the plain
14 text version.
14 text version.
15 """
15 """
16
16
17 # Protected class variables.
17 # Protected class variables.
18 _svg_text_format_property = 1
18 _svg_text_format_property = 1
19
19
20 #---------------------------------------------------------------------------
20 #---------------------------------------------------------------------------
21 # 'object' interface
21 # 'object' interface
22 #---------------------------------------------------------------------------
22 #---------------------------------------------------------------------------
23
23
24 def __init__(self, *args, **kw):
24 def __init__(self, *args, **kw):
25 """ Create a RichIPythonWidget.
25 """ Create a RichIPythonWidget.
26 """
26 """
27 kw['kind'] = 'rich'
27 kw['kind'] = 'rich'
28 super(RichIPythonWidget, self).__init__(*args, **kw)
28 super(RichIPythonWidget, self).__init__(*args, **kw)
29
29
30 #---------------------------------------------------------------------------
30 #---------------------------------------------------------------------------
31 # 'ConsoleWidget' protected interface
31 # 'ConsoleWidget' protected interface
32 #---------------------------------------------------------------------------
32 #---------------------------------------------------------------------------
33
33
34 def _show_context_menu(self, pos):
34 def _show_context_menu(self, pos):
35 """ Reimplemented to show a custom context menu for images.
35 """ Reimplemented to show a custom context menu for images.
36 """
36 """
37 format = self._control.cursorForPosition(pos).charFormat()
37 format = self._control.cursorForPosition(pos).charFormat()
38 name = format.stringProperty(QtGui.QTextFormat.ImageName)
38 name = format.stringProperty(QtGui.QTextFormat.ImageName)
39 if name.isEmpty():
39 if name.isEmpty():
40 super(RichIPythonWidget, self)._show_context_menu(pos)
40 super(RichIPythonWidget, self)._show_context_menu(pos)
41 else:
41 else:
42 menu = QtGui.QMenu()
42 menu = QtGui.QMenu()
43
43
44 menu.addAction('Copy Image', lambda: self._copy_image(name))
44 menu.addAction('Copy Image', lambda: self._copy_image(name))
45 menu.addAction('Save Image As...', lambda: self._save_image(name))
45 menu.addAction('Save Image As...', lambda: self._save_image(name))
46 menu.addSeparator()
46 menu.addSeparator()
47
47
48 svg = format.stringProperty(self._svg_text_format_property)
48 svg = format.stringProperty(self._svg_text_format_property)
49 if not svg.isEmpty():
49 if not svg.isEmpty():
50 menu.addSeparator()
50 menu.addSeparator()
51 menu.addAction('Copy SVG', lambda: svg_to_clipboard(svg))
51 menu.addAction('Copy SVG', lambda: svg_to_clipboard(svg))
52 menu.addAction('Save SVG As...',
52 menu.addAction('Save SVG As...',
53 lambda: save_svg(svg, self._control))
53 lambda: save_svg(svg, self._control))
54
54
55 menu.exec_(self._control.mapToGlobal(pos))
55 menu.exec_(self._control.mapToGlobal(pos))
56
56
57 #---------------------------------------------------------------------------
57 #---------------------------------------------------------------------------
58 # 'FrontendWidget' protected interface
58 # 'FrontendWidget' protected interface
59 #---------------------------------------------------------------------------
59 #---------------------------------------------------------------------------
60
60
61 def _process_execute_ok(self, msg):
61 def _process_execute_ok(self, msg):
62 """ Reimplemented to handle matplotlib plot payloads.
62 """ Reimplemented to handle matplotlib plot payloads.
63 """
63 """
64 payload = msg['content']['payload']
64 payload = msg['content']['payload']
65 for item in payload:
65 for item in payload:
66 if item['source'] == 'IPython.zmq.pylab.backend_payload.add_plot_payload':
66 if item['source'] == 'IPython.zmq.pylab.backend_payload.add_plot_payload':
67 if item['format'] == 'svg':
67 if item['format'] == 'svg':
68 svg = item['data']
68 svg = item['data']
69 try:
69 try:
70 image = svg_to_image(svg)
70 image = svg_to_image(svg)
71 except ValueError:
71 except ValueError:
72 self._append_plain_text('Received invalid plot data.')
72 self._append_plain_text('Received invalid plot data.')
73 else:
73 else:
74 format = self._add_image(image)
74 format = self._add_image(image)
75 format.setProperty(self._svg_text_format_property, svg)
75 format.setProperty(self._svg_text_format_property, svg)
76 cursor = self._get_end_cursor()
76 cursor = self._get_end_cursor()
77 cursor.insertBlock()
77 cursor.insertBlock()
78 cursor.insertImage(format)
78 cursor.insertImage(format)
79 cursor.insertBlock()
79 cursor.insertBlock()
80 else:
80 else:
81 # Add other plot formats here!
81 # Add other plot formats here!
82 pass
82 pass
83 elif item['source'] == 'IPython.zmq.zmqshell.ZMQInteractiveShell.edit_magic':
83 elif item['source'] == 'IPython.zmq.zmqshell.ZMQInteractiveShell.edit_magic':
84 # TODO: I have implmented the logic for TextMate on the Mac.
84 # TODO: I have implmented the logic for TextMate on the Mac.
85 # But, we need to allow payload handlers on the non-rich
85 # But, we need to allow payload handlers on the non-rich
86 # text IPython widget as well. Furthermore, we should probably
86 # text IPython widget as well. Furthermore, we should probably
87 # move these handlers to separate methods. But, we need to
87 # move these handlers to separate methods. But, we need to
88 # be very careful to process the payload list in order. Thus,
88 # be very careful to process the payload list in order. Thus,
89 # we will probably need a _handle_payload method of the
89 # we will probably need a _handle_payload method of the
90 # base class that dispatches to the separate handler methods
90 # base class that dispatches to the separate handler methods
91 # for each payload source. If a particular subclass doesn't
91 # for each payload source. If a particular subclass doesn't
92 # have a handler for a payload source, it should at least
92 # have a handler for a payload source, it should at least
93 # print a nice message.
93 # print a nice message.
94 filename = item['filename']
94 filename = item['filename']
95 line_number = item['line_number']
95 line_number = item['line_number']
96 if line_number is None:
96 if line_number is None:
97 cmd = 'mate %s' % filename
97 cmd = 'mate %s' % filename
98 else:
98 else:
99 cmd = 'mate -l %s %s' % (line_number, filename)
99 cmd = 'mate -l %s %s' % (line_number, filename)
100 os.system(cmd)
100 os.system(cmd)
101 elif item['source'] == 'IPython.zmq.page.page':
102 # TODO: This is probably a good place to start, but Evan can
103 # add better paging capabilities.
104 self._append_plain_text(item['data'])
101 else:
105 else:
102 # Add other payload types here!
106 # Add other payload types here!
103 pass
107 pass
104 else:
108 else:
105 super(RichIPythonWidget, self)._process_execute_ok(msg)
109 super(RichIPythonWidget, self)._process_execute_ok(msg)
106
110
107 #---------------------------------------------------------------------------
111 #---------------------------------------------------------------------------
108 # 'RichIPythonWidget' protected interface
112 # 'RichIPythonWidget' protected interface
109 #---------------------------------------------------------------------------
113 #---------------------------------------------------------------------------
110
114
111 def _add_image(self, image):
115 def _add_image(self, image):
112 """ Adds the specified QImage to the document and returns a
116 """ Adds the specified QImage to the document and returns a
113 QTextImageFormat that references it.
117 QTextImageFormat that references it.
114 """
118 """
115 document = self._control.document()
119 document = self._control.document()
116 name = QtCore.QString.number(image.cacheKey())
120 name = QtCore.QString.number(image.cacheKey())
117 document.addResource(QtGui.QTextDocument.ImageResource,
121 document.addResource(QtGui.QTextDocument.ImageResource,
118 QtCore.QUrl(name), image)
122 QtCore.QUrl(name), image)
119 format = QtGui.QTextImageFormat()
123 format = QtGui.QTextImageFormat()
120 format.setName(name)
124 format.setName(name)
121 return format
125 return format
122
126
123 def _copy_image(self, name):
127 def _copy_image(self, name):
124 """ Copies the ImageResource with 'name' to the clipboard.
128 """ Copies the ImageResource with 'name' to the clipboard.
125 """
129 """
126 image = self._get_image(name)
130 image = self._get_image(name)
127 QtGui.QApplication.clipboard().setImage(image)
131 QtGui.QApplication.clipboard().setImage(image)
128
132
129 def _get_image(self, name):
133 def _get_image(self, name):
130 """ Returns the QImage stored as the ImageResource with 'name'.
134 """ Returns the QImage stored as the ImageResource with 'name'.
131 """
135 """
132 document = self._control.document()
136 document = self._control.document()
133 variant = document.resource(QtGui.QTextDocument.ImageResource,
137 variant = document.resource(QtGui.QTextDocument.ImageResource,
134 QtCore.QUrl(name))
138 QtCore.QUrl(name))
135 return variant.toPyObject()
139 return variant.toPyObject()
136
140
137 def _save_image(self, name, format='PNG'):
141 def _save_image(self, name, format='PNG'):
138 """ Shows a save dialog for the ImageResource with 'name'.
142 """ Shows a save dialog for the ImageResource with 'name'.
139 """
143 """
140 dialog = QtGui.QFileDialog(self._control, 'Save Image')
144 dialog = QtGui.QFileDialog(self._control, 'Save Image')
141 dialog.setAcceptMode(QtGui.QFileDialog.AcceptSave)
145 dialog.setAcceptMode(QtGui.QFileDialog.AcceptSave)
142 dialog.setDefaultSuffix(format.lower())
146 dialog.setDefaultSuffix(format.lower())
143 dialog.setNameFilter('%s file (*.%s)' % (format, format.lower()))
147 dialog.setNameFilter('%s file (*.%s)' % (format, format.lower()))
144 if dialog.exec_():
148 if dialog.exec_():
145 filename = dialog.selectedFiles()[0]
149 filename = dialog.selectedFiles()[0]
146 image = self._get_image(name)
150 image = self._get_image(name)
147 image.save(filename, format)
151 image.save(filename, format)
@@ -1,354 +1,359
1 import inspect
1 import inspect
2 import re
2 import re
3 import sys
3 import sys
4 from subprocess import Popen, PIPE
4 from subprocess import Popen, PIPE
5
5
6 from IPython.core.interactiveshell import (
6 from IPython.core.interactiveshell import (
7 InteractiveShell, InteractiveShellABC
7 InteractiveShell, InteractiveShellABC
8 )
8 )
9 from IPython.core.displayhook import DisplayHook
9 from IPython.core.displayhook import DisplayHook
10 from IPython.core.macro import Macro
10 from IPython.core.macro import Macro
11 from IPython.utils.path import get_py_filename
11 from IPython.utils.path import get_py_filename
12 from IPython.utils.text import StringTypes
12 from IPython.utils.text import StringTypes
13 from IPython.utils.traitlets import Instance, Type, Dict
13 from IPython.utils.traitlets import Instance, Type, Dict
14 from IPython.utils.warn import warn
14 from IPython.utils.warn import warn
15 from IPython.zmq.session import extract_header
15 from IPython.zmq.session import extract_header
16 from IPython.core.payloadpage import install_payload_page
17
18
19 # Install the payload version of page.
20 install_payload_page()
16
21
17
22
18 class ZMQDisplayHook(DisplayHook):
23 class ZMQDisplayHook(DisplayHook):
19
24
20 session = Instance('IPython.zmq.session.Session')
25 session = Instance('IPython.zmq.session.Session')
21 pub_socket = Instance('zmq.Socket')
26 pub_socket = Instance('zmq.Socket')
22 parent_header = Dict({})
27 parent_header = Dict({})
23
28
24 def set_parent(self, parent):
29 def set_parent(self, parent):
25 """Set the parent for outbound messages."""
30 """Set the parent for outbound messages."""
26 self.parent_header = extract_header(parent)
31 self.parent_header = extract_header(parent)
27
32
28 def start_displayhook(self):
33 def start_displayhook(self):
29 self.msg = self.session.msg(u'pyout', {}, parent=self.parent_header)
34 self.msg = self.session.msg(u'pyout', {}, parent=self.parent_header)
30
35
31 def write_output_prompt(self):
36 def write_output_prompt(self):
32 """Write the output prompt."""
37 """Write the output prompt."""
33 if self.do_full_cache:
38 if self.do_full_cache:
34 self.msg['content']['output_sep'] = self.output_sep
39 self.msg['content']['output_sep'] = self.output_sep
35 self.msg['content']['prompt_string'] = str(self.prompt_out)
40 self.msg['content']['prompt_string'] = str(self.prompt_out)
36 self.msg['content']['prompt_number'] = self.prompt_count
41 self.msg['content']['prompt_number'] = self.prompt_count
37 self.msg['content']['output_sep2'] = self.output_sep2
42 self.msg['content']['output_sep2'] = self.output_sep2
38
43
39 def write_result_repr(self, result_repr):
44 def write_result_repr(self, result_repr):
40 self.msg['content']['data'] = result_repr
45 self.msg['content']['data'] = result_repr
41
46
42 def finish_displayhook(self):
47 def finish_displayhook(self):
43 """Finish up all displayhook activities."""
48 """Finish up all displayhook activities."""
44 self.pub_socket.send_json(self.msg)
49 self.pub_socket.send_json(self.msg)
45 self.msg = None
50 self.msg = None
46
51
47
52
48 class ZMQInteractiveShell(InteractiveShell):
53 class ZMQInteractiveShell(InteractiveShell):
49 """A subclass of InteractiveShell for ZMQ."""
54 """A subclass of InteractiveShell for ZMQ."""
50
55
51 displayhook_class = Type(ZMQDisplayHook)
56 displayhook_class = Type(ZMQDisplayHook)
52
57
53 def system(self, cmd):
58 def system(self, cmd):
54 cmd = self.var_expand(cmd, depth=2)
59 cmd = self.var_expand(cmd, depth=2)
55 sys.stdout.flush()
60 sys.stdout.flush()
56 sys.stderr.flush()
61 sys.stderr.flush()
57 p = Popen(cmd, shell=True, stdout=PIPE, stderr=PIPE)
62 p = Popen(cmd, shell=True, stdout=PIPE, stderr=PIPE)
58 for line in p.stdout.read().split('\n'):
63 for line in p.stdout.read().split('\n'):
59 if len(line) > 0:
64 if len(line) > 0:
60 print line
65 print line
61 for line in p.stderr.read().split('\n'):
66 for line in p.stderr.read().split('\n'):
62 if len(line) > 0:
67 if len(line) > 0:
63 print line
68 print line
64 p.wait()
69 p.wait()
65
70
66 def init_io(self):
71 def init_io(self):
67 # This will just use sys.stdout and sys.stderr. If you want to
72 # This will just use sys.stdout and sys.stderr. If you want to
68 # override sys.stdout and sys.stderr themselves, you need to do that
73 # override sys.stdout and sys.stderr themselves, you need to do that
69 # *before* instantiating this class, because Term holds onto
74 # *before* instantiating this class, because Term holds onto
70 # references to the underlying streams.
75 # references to the underlying streams.
71 import IPython.utils.io
76 import IPython.utils.io
72 Term = IPython.utils.io.IOTerm()
77 Term = IPython.utils.io.IOTerm()
73 IPython.utils.io.Term = Term
78 IPython.utils.io.Term = Term
74
79
75 def magic_edit(self,parameter_s='',last_call=['','']):
80 def magic_edit(self,parameter_s='',last_call=['','']):
76 """Bring up an editor and execute the resulting code.
81 """Bring up an editor and execute the resulting code.
77
82
78 Usage:
83 Usage:
79 %edit [options] [args]
84 %edit [options] [args]
80
85
81 %edit runs IPython's editor hook. The default version of this hook is
86 %edit runs IPython's editor hook. The default version of this hook is
82 set to call the __IPYTHON__.rc.editor command. This is read from your
87 set to call the __IPYTHON__.rc.editor command. This is read from your
83 environment variable $EDITOR. If this isn't found, it will default to
88 environment variable $EDITOR. If this isn't found, it will default to
84 vi under Linux/Unix and to notepad under Windows. See the end of this
89 vi under Linux/Unix and to notepad under Windows. See the end of this
85 docstring for how to change the editor hook.
90 docstring for how to change the editor hook.
86
91
87 You can also set the value of this editor via the command line option
92 You can also set the value of this editor via the command line option
88 '-editor' or in your ipythonrc file. This is useful if you wish to use
93 '-editor' or in your ipythonrc file. This is useful if you wish to use
89 specifically for IPython an editor different from your typical default
94 specifically for IPython an editor different from your typical default
90 (and for Windows users who typically don't set environment variables).
95 (and for Windows users who typically don't set environment variables).
91
96
92 This command allows you to conveniently edit multi-line code right in
97 This command allows you to conveniently edit multi-line code right in
93 your IPython session.
98 your IPython session.
94
99
95 If called without arguments, %edit opens up an empty editor with a
100 If called without arguments, %edit opens up an empty editor with a
96 temporary file and will execute the contents of this file when you
101 temporary file and will execute the contents of this file when you
97 close it (don't forget to save it!).
102 close it (don't forget to save it!).
98
103
99
104
100 Options:
105 Options:
101
106
102 -n <number>: open the editor at a specified line number. By default,
107 -n <number>: open the editor at a specified line number. By default,
103 the IPython editor hook uses the unix syntax 'editor +N filename', but
108 the IPython editor hook uses the unix syntax 'editor +N filename', but
104 you can configure this by providing your own modified hook if your
109 you can configure this by providing your own modified hook if your
105 favorite editor supports line-number specifications with a different
110 favorite editor supports line-number specifications with a different
106 syntax.
111 syntax.
107
112
108 -p: this will call the editor with the same data as the previous time
113 -p: this will call the editor with the same data as the previous time
109 it was used, regardless of how long ago (in your current session) it
114 it was used, regardless of how long ago (in your current session) it
110 was.
115 was.
111
116
112 -r: use 'raw' input. This option only applies to input taken from the
117 -r: use 'raw' input. This option only applies to input taken from the
113 user's history. By default, the 'processed' history is used, so that
118 user's history. By default, the 'processed' history is used, so that
114 magics are loaded in their transformed version to valid Python. If
119 magics are loaded in their transformed version to valid Python. If
115 this option is given, the raw input as typed as the command line is
120 this option is given, the raw input as typed as the command line is
116 used instead. When you exit the editor, it will be executed by
121 used instead. When you exit the editor, it will be executed by
117 IPython's own processor.
122 IPython's own processor.
118
123
119 -x: do not execute the edited code immediately upon exit. This is
124 -x: do not execute the edited code immediately upon exit. This is
120 mainly useful if you are editing programs which need to be called with
125 mainly useful if you are editing programs which need to be called with
121 command line arguments, which you can then do using %run.
126 command line arguments, which you can then do using %run.
122
127
123
128
124 Arguments:
129 Arguments:
125
130
126 If arguments are given, the following possibilites exist:
131 If arguments are given, the following possibilites exist:
127
132
128 - The arguments are numbers or pairs of colon-separated numbers (like
133 - The arguments are numbers or pairs of colon-separated numbers (like
129 1 4:8 9). These are interpreted as lines of previous input to be
134 1 4:8 9). These are interpreted as lines of previous input to be
130 loaded into the editor. The syntax is the same of the %macro command.
135 loaded into the editor. The syntax is the same of the %macro command.
131
136
132 - If the argument doesn't start with a number, it is evaluated as a
137 - If the argument doesn't start with a number, it is evaluated as a
133 variable and its contents loaded into the editor. You can thus edit
138 variable and its contents loaded into the editor. You can thus edit
134 any string which contains python code (including the result of
139 any string which contains python code (including the result of
135 previous edits).
140 previous edits).
136
141
137 - If the argument is the name of an object (other than a string),
142 - If the argument is the name of an object (other than a string),
138 IPython will try to locate the file where it was defined and open the
143 IPython will try to locate the file where it was defined and open the
139 editor at the point where it is defined. You can use `%edit function`
144 editor at the point where it is defined. You can use `%edit function`
140 to load an editor exactly at the point where 'function' is defined,
145 to load an editor exactly at the point where 'function' is defined,
141 edit it and have the file be executed automatically.
146 edit it and have the file be executed automatically.
142
147
143 If the object is a macro (see %macro for details), this opens up your
148 If the object is a macro (see %macro for details), this opens up your
144 specified editor with a temporary file containing the macro's data.
149 specified editor with a temporary file containing the macro's data.
145 Upon exit, the macro is reloaded with the contents of the file.
150 Upon exit, the macro is reloaded with the contents of the file.
146
151
147 Note: opening at an exact line is only supported under Unix, and some
152 Note: opening at an exact line is only supported under Unix, and some
148 editors (like kedit and gedit up to Gnome 2.8) do not understand the
153 editors (like kedit and gedit up to Gnome 2.8) do not understand the
149 '+NUMBER' parameter necessary for this feature. Good editors like
154 '+NUMBER' parameter necessary for this feature. Good editors like
150 (X)Emacs, vi, jed, pico and joe all do.
155 (X)Emacs, vi, jed, pico and joe all do.
151
156
152 - If the argument is not found as a variable, IPython will look for a
157 - If the argument is not found as a variable, IPython will look for a
153 file with that name (adding .py if necessary) and load it into the
158 file with that name (adding .py if necessary) and load it into the
154 editor. It will execute its contents with execfile() when you exit,
159 editor. It will execute its contents with execfile() when you exit,
155 loading any code in the file into your interactive namespace.
160 loading any code in the file into your interactive namespace.
156
161
157 After executing your code, %edit will return as output the code you
162 After executing your code, %edit will return as output the code you
158 typed in the editor (except when it was an existing file). This way
163 typed in the editor (except when it was an existing file). This way
159 you can reload the code in further invocations of %edit as a variable,
164 you can reload the code in further invocations of %edit as a variable,
160 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
165 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
161 the output.
166 the output.
162
167
163 Note that %edit is also available through the alias %ed.
168 Note that %edit is also available through the alias %ed.
164
169
165 This is an example of creating a simple function inside the editor and
170 This is an example of creating a simple function inside the editor and
166 then modifying it. First, start up the editor:
171 then modifying it. First, start up the editor:
167
172
168 In [1]: ed
173 In [1]: ed
169 Editing... done. Executing edited code...
174 Editing... done. Executing edited code...
170 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
175 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
171
176
172 We can then call the function foo():
177 We can then call the function foo():
173
178
174 In [2]: foo()
179 In [2]: foo()
175 foo() was defined in an editing session
180 foo() was defined in an editing session
176
181
177 Now we edit foo. IPython automatically loads the editor with the
182 Now we edit foo. IPython automatically loads the editor with the
178 (temporary) file where foo() was previously defined:
183 (temporary) file where foo() was previously defined:
179
184
180 In [3]: ed foo
185 In [3]: ed foo
181 Editing... done. Executing edited code...
186 Editing... done. Executing edited code...
182
187
183 And if we call foo() again we get the modified version:
188 And if we call foo() again we get the modified version:
184
189
185 In [4]: foo()
190 In [4]: foo()
186 foo() has now been changed!
191 foo() has now been changed!
187
192
188 Here is an example of how to edit a code snippet successive
193 Here is an example of how to edit a code snippet successive
189 times. First we call the editor:
194 times. First we call the editor:
190
195
191 In [5]: ed
196 In [5]: ed
192 Editing... done. Executing edited code...
197 Editing... done. Executing edited code...
193 hello
198 hello
194 Out[5]: "print 'hello'n"
199 Out[5]: "print 'hello'n"
195
200
196 Now we call it again with the previous output (stored in _):
201 Now we call it again with the previous output (stored in _):
197
202
198 In [6]: ed _
203 In [6]: ed _
199 Editing... done. Executing edited code...
204 Editing... done. Executing edited code...
200 hello world
205 hello world
201 Out[6]: "print 'hello world'n"
206 Out[6]: "print 'hello world'n"
202
207
203 Now we call it with the output #8 (stored in _8, also as Out[8]):
208 Now we call it with the output #8 (stored in _8, also as Out[8]):
204
209
205 In [7]: ed _8
210 In [7]: ed _8
206 Editing... done. Executing edited code...
211 Editing... done. Executing edited code...
207 hello again
212 hello again
208 Out[7]: "print 'hello again'n"
213 Out[7]: "print 'hello again'n"
209
214
210
215
211 Changing the default editor hook:
216 Changing the default editor hook:
212
217
213 If you wish to write your own editor hook, you can put it in a
218 If you wish to write your own editor hook, you can put it in a
214 configuration file which you load at startup time. The default hook
219 configuration file which you load at startup time. The default hook
215 is defined in the IPython.core.hooks module, and you can use that as a
220 is defined in the IPython.core.hooks module, and you can use that as a
216 starting example for further modifications. That file also has
221 starting example for further modifications. That file also has
217 general instructions on how to set a new hook for use once you've
222 general instructions on how to set a new hook for use once you've
218 defined it."""
223 defined it."""
219
224
220 # FIXME: This function has become a convoluted mess. It needs a
225 # FIXME: This function has become a convoluted mess. It needs a
221 # ground-up rewrite with clean, simple logic.
226 # ground-up rewrite with clean, simple logic.
222
227
223 def make_filename(arg):
228 def make_filename(arg):
224 "Make a filename from the given args"
229 "Make a filename from the given args"
225 try:
230 try:
226 filename = get_py_filename(arg)
231 filename = get_py_filename(arg)
227 except IOError:
232 except IOError:
228 if args.endswith('.py'):
233 if args.endswith('.py'):
229 filename = arg
234 filename = arg
230 else:
235 else:
231 filename = None
236 filename = None
232 return filename
237 return filename
233
238
234 # custom exceptions
239 # custom exceptions
235 class DataIsObject(Exception): pass
240 class DataIsObject(Exception): pass
236
241
237 opts,args = self.parse_options(parameter_s,'prn:')
242 opts,args = self.parse_options(parameter_s,'prn:')
238 # Set a few locals from the options for convenience:
243 # Set a few locals from the options for convenience:
239 opts_p = opts.has_key('p')
244 opts_p = opts.has_key('p')
240 opts_r = opts.has_key('r')
245 opts_r = opts.has_key('r')
241
246
242 # Default line number value
247 # Default line number value
243 lineno = opts.get('n',None)
248 lineno = opts.get('n',None)
244
249
245 if opts_p:
250 if opts_p:
246 args = '_%s' % last_call[0]
251 args = '_%s' % last_call[0]
247 if not self.shell.user_ns.has_key(args):
252 if not self.shell.user_ns.has_key(args):
248 args = last_call[1]
253 args = last_call[1]
249
254
250 # use last_call to remember the state of the previous call, but don't
255 # use last_call to remember the state of the previous call, but don't
251 # let it be clobbered by successive '-p' calls.
256 # let it be clobbered by successive '-p' calls.
252 try:
257 try:
253 last_call[0] = self.shell.displayhook.prompt_count
258 last_call[0] = self.shell.displayhook.prompt_count
254 if not opts_p:
259 if not opts_p:
255 last_call[1] = parameter_s
260 last_call[1] = parameter_s
256 except:
261 except:
257 pass
262 pass
258
263
259 # by default this is done with temp files, except when the given
264 # by default this is done with temp files, except when the given
260 # arg is a filename
265 # arg is a filename
261 use_temp = 1
266 use_temp = 1
262
267
263 if re.match(r'\d',args):
268 if re.match(r'\d',args):
264 # Mode where user specifies ranges of lines, like in %macro.
269 # Mode where user specifies ranges of lines, like in %macro.
265 # This means that you can't edit files whose names begin with
270 # This means that you can't edit files whose names begin with
266 # numbers this way. Tough.
271 # numbers this way. Tough.
267 ranges = args.split()
272 ranges = args.split()
268 data = ''.join(self.extract_input_slices(ranges,opts_r))
273 data = ''.join(self.extract_input_slices(ranges,opts_r))
269 elif args.endswith('.py'):
274 elif args.endswith('.py'):
270 filename = make_filename(args)
275 filename = make_filename(args)
271 data = ''
276 data = ''
272 use_temp = 0
277 use_temp = 0
273 elif args:
278 elif args:
274 try:
279 try:
275 # Load the parameter given as a variable. If not a string,
280 # Load the parameter given as a variable. If not a string,
276 # process it as an object instead (below)
281 # process it as an object instead (below)
277
282
278 #print '*** args',args,'type',type(args) # dbg
283 #print '*** args',args,'type',type(args) # dbg
279 data = eval(args,self.shell.user_ns)
284 data = eval(args,self.shell.user_ns)
280 if not type(data) in StringTypes:
285 if not type(data) in StringTypes:
281 raise DataIsObject
286 raise DataIsObject
282
287
283 except (NameError,SyntaxError):
288 except (NameError,SyntaxError):
284 # given argument is not a variable, try as a filename
289 # given argument is not a variable, try as a filename
285 filename = make_filename(args)
290 filename = make_filename(args)
286 if filename is None:
291 if filename is None:
287 warn("Argument given (%s) can't be found as a variable "
292 warn("Argument given (%s) can't be found as a variable "
288 "or as a filename." % args)
293 "or as a filename." % args)
289 return
294 return
290
295
291 data = ''
296 data = ''
292 use_temp = 0
297 use_temp = 0
293 except DataIsObject:
298 except DataIsObject:
294
299
295 # macros have a special edit function
300 # macros have a special edit function
296 if isinstance(data,Macro):
301 if isinstance(data,Macro):
297 self._edit_macro(args,data)
302 self._edit_macro(args,data)
298 return
303 return
299
304
300 # For objects, try to edit the file where they are defined
305 # For objects, try to edit the file where they are defined
301 try:
306 try:
302 filename = inspect.getabsfile(data)
307 filename = inspect.getabsfile(data)
303 if 'fakemodule' in filename.lower() and inspect.isclass(data):
308 if 'fakemodule' in filename.lower() and inspect.isclass(data):
304 # class created by %edit? Try to find source
309 # class created by %edit? Try to find source
305 # by looking for method definitions instead, the
310 # by looking for method definitions instead, the
306 # __module__ in those classes is FakeModule.
311 # __module__ in those classes is FakeModule.
307 attrs = [getattr(data, aname) for aname in dir(data)]
312 attrs = [getattr(data, aname) for aname in dir(data)]
308 for attr in attrs:
313 for attr in attrs:
309 if not inspect.ismethod(attr):
314 if not inspect.ismethod(attr):
310 continue
315 continue
311 filename = inspect.getabsfile(attr)
316 filename = inspect.getabsfile(attr)
312 if filename and 'fakemodule' not in filename.lower():
317 if filename and 'fakemodule' not in filename.lower():
313 # change the attribute to be the edit target instead
318 # change the attribute to be the edit target instead
314 data = attr
319 data = attr
315 break
320 break
316
321
317 datafile = 1
322 datafile = 1
318 except TypeError:
323 except TypeError:
319 filename = make_filename(args)
324 filename = make_filename(args)
320 datafile = 1
325 datafile = 1
321 warn('Could not find file where `%s` is defined.\n'
326 warn('Could not find file where `%s` is defined.\n'
322 'Opening a file named `%s`' % (args,filename))
327 'Opening a file named `%s`' % (args,filename))
323 # Now, make sure we can actually read the source (if it was in
328 # Now, make sure we can actually read the source (if it was in
324 # a temp file it's gone by now).
329 # a temp file it's gone by now).
325 if datafile:
330 if datafile:
326 try:
331 try:
327 if lineno is None:
332 if lineno is None:
328 lineno = inspect.getsourcelines(data)[1]
333 lineno = inspect.getsourcelines(data)[1]
329 except IOError:
334 except IOError:
330 filename = make_filename(args)
335 filename = make_filename(args)
331 if filename is None:
336 if filename is None:
332 warn('The file `%s` where `%s` was defined cannot '
337 warn('The file `%s` where `%s` was defined cannot '
333 'be read.' % (filename,data))
338 'be read.' % (filename,data))
334 return
339 return
335 use_temp = 0
340 use_temp = 0
336 else:
341 else:
337 data = ''
342 data = ''
338
343
339 if use_temp:
344 if use_temp:
340 filename = self.shell.mktempfile(data)
345 filename = self.shell.mktempfile(data)
341 print 'IPython will make a temporary file named:',filename
346 print 'IPython will make a temporary file named:',filename
342
347
343 payload = {
348 payload = {
344 'source' : 'IPython.zmq.zmqshell.ZMQInteractiveShell.edit_magic',
349 'source' : 'IPython.zmq.zmqshell.ZMQInteractiveShell.edit_magic',
345 'filename' : filename,
350 'filename' : filename,
346 'line_number' : lineno
351 'line_number' : lineno
347 }
352 }
348 self.payload_manager.write_payload(payload)
353 self.payload_manager.write_payload(payload)
349
354
350
355
351 InteractiveShellABC.register(ZMQInteractiveShell)
356 InteractiveShellABC.register(ZMQInteractiveShell)
352
357
353
358
354
359
General Comments 0
You need to be logged in to leave comments. Login now