##// END OF EJS Templates
More work on InteractiveShell and ipmaker. It works!
Brian Granger -
Show More
@@ -1,316 +1,318 b''
1 1 #!/usr/bin/env python
2 2 # encoding: utf-8
3 3 """
4 4 The main IPython application object
5 5
6 6 Authors:
7 7
8 8 * Brian Granger
9 9 * Fernando Perez
10 10
11 11 Notes
12 12 -----
13 13 """
14 14
15 15 #-----------------------------------------------------------------------------
16 16 # Copyright (C) 2008-2009 The IPython Development Team
17 17 #
18 18 # Distributed under the terms of the BSD License. The full license is in
19 19 # the file COPYING, distributed as part of this software.
20 20 #-----------------------------------------------------------------------------
21 21
22 22 #-----------------------------------------------------------------------------
23 23 # Imports
24 24 #-----------------------------------------------------------------------------
25 25
26 26 import os
27 27 import sys
28 28 import warnings
29 29
30 30 from IPython.core.application import Application
31 31 from IPython.core import release
32 32 from IPython.core.iplib import InteractiveShell
33 33 from IPython.config.loader import IPythonArgParseConfigLoader, NoDefault
34 34
35 35 from IPython.utils.ipstruct import Struct
36 36
37 37
38 38 #-----------------------------------------------------------------------------
39 39 # Utilities and helpers
40 40 #-----------------------------------------------------------------------------
41 41
42 42
43 43 ipython_desc = """
44 44 A Python shell with automatic history (input and output), dynamic object
45 45 introspection, easier configuration, command completion, access to the system
46 46 shell and more.
47 47 """
48 48
49 49 def threaded_shell_warning():
50 50 msg = """
51 51
52 52 The IPython threaded shells and their associated command line
53 53 arguments (pylab/wthread/gthread/qthread/q4thread) have been
54 54 deprecated. See the %gui magic for information on the new interface.
55 55 """
56 56 warnings.warn(msg, category=DeprecationWarning, stacklevel=1)
57 57
58 58
59 59 #-----------------------------------------------------------------------------
60 60 # Main classes and functions
61 61 #-----------------------------------------------------------------------------
62 62
63 63 cl_args = (
64 64 (('-autocall',), dict(
65 65 type=int, dest='AUTOCALL', default=NoDefault,
66 66 help='Set the autocall value (0,1,2).')
67 67 ),
68 68 (('-autoindent',), dict(
69 69 action='store_true', dest='AUTOINDENT', default=NoDefault,
70 70 help='Turn on autoindenting.')
71 71 ),
72 72 (('-noautoindent',), dict(
73 73 action='store_false', dest='AUTOINDENT', default=NoDefault,
74 74 help='Turn off autoindenting.')
75 75 ),
76 76 (('-automagic',), dict(
77 77 action='store_true', dest='AUTOMAGIC', default=NoDefault,
78 78 help='Turn on the auto calling of magic commands.')
79 79 ),
80 80 (('-noautomagic',), dict(
81 81 action='store_false', dest='AUTOMAGIC', default=NoDefault,
82 82 help='Turn off the auto calling of magic commands.')
83 83 ),
84 84 (('-autoedit_syntax',), dict(
85 85 action='store_true', dest='AUTOEDIT_SYNTAX', default=NoDefault,
86 86 help='Turn on auto editing of files with syntax errors.')
87 87 ),
88 88 (('-noautoedit_syntax',), dict(
89 89 action='store_false', dest='AUTOEDIT_SYNTAX', default=NoDefault,
90 90 help='Turn off auto editing of files with syntax errors.')
91 91 ),
92 92 (('-banner',), dict(
93 93 action='store_true', dest='DISPLAY_BANNER', default=NoDefault,
94 94 help='Display a banner upon starting IPython.')
95 95 ),
96 96 (('-nobanner',), dict(
97 97 action='store_false', dest='DISPLAY_BANNER', default=NoDefault,
98 98 help="Don't display a banner upon starting IPython.")
99 99 ),
100 100 (('-c',), dict(
101 101 type=str, dest='C', default=NoDefault,
102 102 help="Execute the given command string.")
103 103 ),
104 104 (('-cache_size',), dict(
105 105 type=int, dest='CACHE_SIZE', default=NoDefault,
106 106 help="Set the size of the output cache.")
107 107 ),
108 108 (('-classic',), dict(
109 109 action='store_true', dest='CLASSIC', default=NoDefault,
110 110 help="Gives IPython a similar feel to the classic Python prompt.")
111 111 ),
112 112 (('-colors',), dict(
113 113 type=str, dest='COLORS', default=NoDefault,
114 114 help="Set the color scheme (NoColor, Linux, and LightBG).")
115 115 ),
116 116 (('-color_info',), dict(
117 117 action='store_true', dest='COLOR_INFO', default=NoDefault,
118 118 help="Enable using colors for info related things.")
119 119 ),
120 120 (('-nocolor_info',), dict(
121 121 action='store_false', dest='COLOR_INFO', default=NoDefault,
122 122 help="Disable using colors for info related things.")
123 123 ),
124 124 (('-confirm_exit',), dict(
125 125 action='store_true', dest='CONFIRM_EXIT', default=NoDefault,
126 126 help="Prompt the user when existing.")
127 127 ),
128 128 (('-noconfirm_exit',), dict(
129 129 action='store_false', dest='CONFIRM_EXIT', default=NoDefault,
130 130 help="Don't prompt the user when existing.")
131 131 ),
132 132 (('-deep_reload',), dict(
133 133 action='store_true', dest='DEEP_RELOAD', default=NoDefault,
134 134 help="Enable deep (recursive) reloading by default.")
135 135 ),
136 136 (('-nodeep_reload',), dict(
137 137 action='store_false', dest='DEEP_RELOAD', default=NoDefault,
138 138 help="Disable deep (recursive) reloading by default.")
139 139 ),
140 140 (('-editor',), dict(
141 141 type=str, dest='EDITOR', default=NoDefault,
142 142 help="Set the editor used by IPython (default to $EDITOR/vi/notepad).")
143 143 ),
144 144 (('-log','-l'), dict(
145 145 action='store_true', dest='LOGSTART', default=NoDefault,
146 146 help="Start logging to the default file (./ipython_log.py).")
147 147 ),
148 148 (('-logfile','-lf'), dict(
149 149 type=str, dest='LOGFILE', default=NoDefault,
150 150 help="Specify the name of your logfile.")
151 151 ),
152 152 (('-logplay','-lp'), dict(
153 153 type=str, dest='LOGPLAY', default=NoDefault,
154 154 help="Re-play a log file and then append to it.")
155 155 ),
156 156 (('-pdb',), dict(
157 157 action='store_true', dest='PDB', default=NoDefault,
158 158 help="Enable auto calling the pdb debugger after every exception.")
159 159 ),
160 160 (('-nopdb',), dict(
161 161 action='store_false', dest='PDB', default=NoDefault,
162 162 help="Disable auto calling the pdb debugger after every exception.")
163 163 ),
164 164 (('-pprint',), dict(
165 165 action='store_true', dest='PPRINT', default=NoDefault,
166 166 help="Enable auto pretty printing of results.")
167 167 ),
168 168 (('-nopprint',), dict(
169 169 action='store_false', dest='PPRINT', default=NoDefault,
170 170 help="Disable auto auto pretty printing of results.")
171 171 ),
172 172 (('-prompt_in1','-pi1'), dict(
173 173 type=str, dest='PROMPT_IN1', default=NoDefault,
174 174 help="Set the main input prompt ('In [\#]: ')")
175 175 ),
176 176 (('-prompt_in2','-pi2'), dict(
177 177 type=str, dest='PROMPT_IN2', default=NoDefault,
178 178 help="Set the secondary input prompt (' .\D.: ')")
179 179 ),
180 180 (('-prompt_out','-po'), dict(
181 181 type=str, dest='PROMPT_OUT', default=NoDefault,
182 182 help="Set the output prompt ('Out[\#]:')")
183 183 ),
184 184 (('-quick',), dict(
185 185 action='store_true', dest='QUICK', default=NoDefault,
186 186 help="Enable quick startup with no config files.")
187 187 ),
188 188 (('-readline',), dict(
189 189 action='store_true', dest='READLINE_USE', default=NoDefault,
190 190 help="Enable readline for command line usage.")
191 191 ),
192 192 (('-noreadline',), dict(
193 193 action='store_false', dest='READLINE_USE', default=NoDefault,
194 194 help="Disable readline for command line usage.")
195 195 ),
196 196 (('-screen_length','-sl'), dict(
197 197 type=int, dest='SCREEN_LENGTH', default=NoDefault,
198 198 help='Number of lines on screen, used to control printing of long strings.')
199 199 ),
200 200 (('-separate_in','-si'), dict(
201 201 type=str, dest='SEPARATE_IN', default=NoDefault,
202 202 help="Separator before input prompts. Default '\n'.")
203 203 ),
204 204 (('-separate_out','-so'), dict(
205 205 type=str, dest='SEPARATE_OUT', default=NoDefault,
206 206 help="Separator before output prompts. Default 0 (nothing).")
207 207 ),
208 208 (('-separate_out2','-so2'), dict(
209 209 type=str, dest='SEPARATE_OUT2', default=NoDefault,
210 210 help="Separator after output prompts. Default 0 (nonight).")
211 211 ),
212 212 (('-nosep',), dict(
213 213 action='store_true', dest='NOSEP', default=NoDefault,
214 214 help="Eliminate all spacing between prompts.")
215 215 ),
216 (('-term_title',), dict(
217 action='store_true', dest='TERM_TITLE', default=NoDefault,
218 help="Enable auto setting the terminal title.")
219 ),
220 (('-noterm_title',), dict(
221 action='store_false', dest='TERM_TITLE', default=NoDefault,
222 help="Disable auto setting the terminal title.")
223 ),
216 224 (('-xmode',), dict(
217 225 type=str, dest='XMODE', default=NoDefault,
218 226 help="Exception mode ('Plain','Context','Verbose')")
219 227 ),
228 # These are only here to get the proper deprecation warnings
229 (('-pylab','-wthread','-qthread','-q4thread','-gthread'), dict(
230 action='store_true', dest='THREADED_SHELL', default=NoDefault,
231 help="These command line flags are deprecated, see the 'gui' magic.")
232 ),
220 233 )
221 234
222 235
223 236 class IPythonAppCLConfigLoader(IPythonArgParseConfigLoader):
224 237
225 238 arguments = cl_args
226 239
227 240
228 241 class IPythonApp(Application):
229 242 name = 'ipython'
230 243 config_file_name = 'ipython_config.py'
231 244
232 245 def create_command_line_config(self):
233 246 """Create and return a command line config loader."""
234 247 return IPythonAppCLConfigLoader(
235 248 description=ipython_desc,
236 249 version=release.version)
237 250
238 251 def post_load_command_line_config(self):
239 252 """Do actions after loading cl config."""
240 253 clc = self.command_line_config
241 254
242 255 # This needs to be set here, the rest are set in pre_construct.
243 256 if hasattr(clc, 'CLASSIC'):
244 257 if clc.CLASSIC: clc.QUICK = 1
245 258
246 259 # Display the deprecation warnings about threaded shells
247 # if opts_all.pylab == 1: threaded_shell_warning()
248 # if opts_all.wthread == 1: threaded_shell_warning()
249 # if opts_all.qthread == 1: threaded_shell_warning()
250 # if opts_all.q4thread == 1: threaded_shell_warning()
251 # if opts_all.gthread == 1: threaded_shell_warning()
260 if hasattr(clc, 'THREADED_SHELL'):
261 threaded_shell_warning()
262 del clc['THREADED_SHELL']
252 263
253 264 def load_file_config(self):
254 265 if hasattr(self.command_line_config, 'QUICK'):
255 266 if self.command_line_config.QUICK:
256 267 self.file_config = Struct()
257 268 return
258 269 super(IPythonApp, self).load_file_config()
259 270
260 271 def post_load_file_config(self):
261 272 """Logic goes here."""
262 273
263 274 def pre_construct(self):
264 275 config = self.master_config
265 276
266 277 if hasattr(config, 'CLASSIC'):
267 278 if config.CLASSIC:
268 279 config.QUICK = 1
269 280 config.CACHE_SIZE = 0
270 281 config.PPRINT = 0
271 282 config.PROMPT_IN1 = '>>> '
272 283 config.PROMPT_IN2 = '... '
273 284 config.PROMPT_OUT = ''
274 285 config.SEPARATE_IN = config.SEPARATE_OUT = config.SEPARATE_OUT2 = ''
275 286 config.COLORS = 'NoColor'
276 287 config.XMODE = 'Plain'
277 288
278 289 # All this should be moved to traitlet handlers in InteractiveShell
290 # But, currently InteractiveShell doesn't have support for changing
291 # these values at runtime. Once we support that, this should
292 # be moved there!!!
279 293 if hasattr(config, 'NOSEP'):
280 294 if config.NOSEP:
281 295 config.SEPARATE_IN = config.SEPARATE_OUT = config.SEPARATE_OUT2 = '0'
282 296
283 if hasattr(config, 'SEPARATE_IN'):
284 if config.SEPARATE_IN == '0': config.SEPARATE_IN = ''
285 config.SEPARATE_IN = config.SEPARATE_IN.replace('\\n','\n')
286
287 if hasattr(config, 'SEPARATE_OUT'):
288 if config.SEPARATE_OUT == '0': config.SEPARATE_OUT = ''
289 config.SEPARATE_OUT = config.SEPARATE_OUT.replace('\\n','\n')
290
291 if hasattr(config, 'SEPARATE_OUT'):
292 if config.SEPARATE_OUT2 == '0': config.SEPARATE_OUT2 = ''
293 config.SEPARATE_OUT2 = config.SEPARATE_OUT2.replace('\\n','\n')
294
295 297 def construct(self):
296 298 # I am a little hesitant to put these into InteractiveShell itself.
297 299 # But that might be the place for them
298 300 sys.path.insert(0, '')
299 301 # add personal ipythondir to sys.path so that users can put things in
300 302 # there for customization
301 303 sys.path.append(os.path.abspath(self.ipythondir))
302 304
303 305 # Create an InteractiveShell instance
304 306 self.shell = InteractiveShell(
305 307 name='__IP',
306 308 parent=None,
307 309 config=self.master_config
308 310 )
309 311
310 312 def start_app(self):
311 313 self.shell.mainloop()
312 314
313 315
314 316 if __name__ == '__main__':
315 317 app = IPythonApp()
316 318 app.start() No newline at end of file
@@ -1,2809 +1,2840 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 Main IPython Component
4 4 """
5 5
6 6 #-----------------------------------------------------------------------------
7 7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
8 8 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
9 9 # Copyright (C) 2008-2009 The IPython Development Team
10 10 #
11 11 # Distributed under the terms of the BSD License. The full license is in
12 12 # the file COPYING, distributed as part of this software.
13 13 #-----------------------------------------------------------------------------
14 14
15 15 #-----------------------------------------------------------------------------
16 16 # Imports
17 17 #-----------------------------------------------------------------------------
18 18
19 19 import __main__
20 20 import __builtin__
21 21 import StringIO
22 22 import bdb
23 23 import codeop
24 24 import exceptions
25 25 import glob
26 26 import keyword
27 27 import new
28 28 import os
29 29 import re
30 30 import shutil
31 31 import string
32 32 import sys
33 33 import tempfile
34 34
35 35 from IPython.core import ultratb
36 36 from IPython.core import debugger, oinspect
37 37 from IPython.core import ipapi
38 38 from IPython.core import shadowns
39 39 from IPython.core import history as ipcorehist
40 40 from IPython.core import prefilter
41 41 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
42 42 from IPython.core.logger import Logger
43 43 from IPython.core.magic import Magic
44 44 from IPython.core.prompts import CachedOutput
45 45 from IPython.core.component import Component
46 46 from IPython.core.oldusersetup import user_setup
47 47 from IPython.core.usage import interactive_usage, default_banner
48 48
49 49 from IPython.extensions import pickleshare
50 50 from IPython.external.Itpl import ItplNS
51 51 from IPython.lib.backgroundjobs import BackgroundJobManager
52 52 from IPython.utils.ipstruct import Struct
53 53 from IPython.utils import PyColorize
54 54 from IPython.utils.genutils import *
55 55 from IPython.utils.strdispatch import StrDispatch
56 from IPython.utils.platutils import toggle_set_term_title, set_term_title
56 57
57 58 from IPython.utils.traitlets import (
58 Int, Float, Str, CBool, CaselessStrEnum, Enum
59 Int, Float, Str, CBool, CaselessStrEnum, Enum, List
59 60 )
60 61
61 62 #-----------------------------------------------------------------------------
62 63 # Globals
63 64 #-----------------------------------------------------------------------------
64 65
65 66
66 67 # store the builtin raw_input globally, and use this always, in case user code
67 68 # overwrites it (like wx.py.PyShell does)
68 69 raw_input_original = raw_input
69 70
70 71 # compiled regexps for autoindent management
71 72 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
72 73
73 74
74 75 #-----------------------------------------------------------------------------
75 76 # Utilities
76 77 #-----------------------------------------------------------------------------
77 78
78 79
79 80 ini_spaces_re = re.compile(r'^(\s+)')
80 81
81 82
82 83 def num_ini_spaces(strng):
83 84 """Return the number of initial spaces in a string"""
84 85
85 86 ini_spaces = ini_spaces_re.match(strng)
86 87 if ini_spaces:
87 88 return ini_spaces.end()
88 89 else:
89 90 return 0
90 91
91 92
92 93 def softspace(file, newvalue):
93 94 """Copied from code.py, to remove the dependency"""
94 95
95 96 oldvalue = 0
96 97 try:
97 98 oldvalue = file.softspace
98 99 except AttributeError:
99 100 pass
100 101 try:
101 102 file.softspace = newvalue
102 103 except (AttributeError, TypeError):
103 104 # "attribute-less object" or "read-only attributes"
104 105 pass
105 106 return oldvalue
106 107
107 108
108 109 class SpaceInInput(exceptions.Exception): pass
109 110
110 111 class Bunch: pass
111 112
112 113 class Undefined: pass
113 114
114 115 class Quitter(object):
115 116 """Simple class to handle exit, similar to Python 2.5's.
116 117
117 118 It handles exiting in an ipython-safe manner, which the one in Python 2.5
118 119 doesn't do (obviously, since it doesn't know about ipython)."""
119 120
120 121 def __init__(self,shell,name):
121 122 self.shell = shell
122 123 self.name = name
123 124
124 125 def __repr__(self):
125 126 return 'Type %s() to exit.' % self.name
126 127 __str__ = __repr__
127 128
128 129 def __call__(self):
129 130 self.shell.exit()
130 131
131 132 class InputList(list):
132 133 """Class to store user input.
133 134
134 135 It's basically a list, but slices return a string instead of a list, thus
135 136 allowing things like (assuming 'In' is an instance):
136 137
137 138 exec In[4:7]
138 139
139 140 or
140 141
141 142 exec In[5:9] + In[14] + In[21:25]"""
142 143
143 144 def __getslice__(self,i,j):
144 145 return ''.join(list.__getslice__(self,i,j))
145 146
146 147 class SyntaxTB(ultratb.ListTB):
147 148 """Extension which holds some state: the last exception value"""
148 149
149 150 def __init__(self,color_scheme = 'NoColor'):
150 151 ultratb.ListTB.__init__(self,color_scheme)
151 152 self.last_syntax_error = None
152 153
153 154 def __call__(self, etype, value, elist):
154 155 self.last_syntax_error = value
155 156 ultratb.ListTB.__call__(self,etype,value,elist)
156 157
157 158 def clear_err_state(self):
158 159 """Return the current error state and clear it"""
159 160 e = self.last_syntax_error
160 161 self.last_syntax_error = None
161 162 return e
162 163
163 164 def get_default_editor():
164 165 try:
165 166 ed = os.environ['EDITOR']
166 167 except KeyError:
167 168 if os.name == 'posix':
168 169 ed = 'vi' # the only one guaranteed to be there!
169 170 else:
170 171 ed = 'notepad' # same in Windows!
171 172 return ed
172 173
174
175 class SeparateStr(Str):
176 """A Str subclass to validate separate_in, separate_out, etc.
177
178 This is a Str based traitlet that converts '0'->'' and '\\n'->'\n'.
179 """
180
181 def validate(self, obj, value):
182 if value == '0': value = ''
183 value = value.replace('\\n','\n')
184 return super(SeparateStr, self).validate(obj, value)
185
186
173 187 #-----------------------------------------------------------------------------
174 188 # Main IPython class
175 189 #-----------------------------------------------------------------------------
176 190
177 191 # FIXME: the Magic class is a mixin for now, and will unfortunately remain so
178 192 # until a full rewrite is made. I've cleaned all cross-class uses of
179 193 # attributes and methods, but too much user code out there relies on the
180 194 # equlity %foo == __IP.magic_foo, so I can't actually remove the mixin usage.
181 195 #
182 196 # But at least now, all the pieces have been separated and we could, in
183 197 # principle, stop using the mixin. This will ease the transition to the
184 198 # chainsaw branch.
185 199
186 200 # For reference, the following is the list of 'self.foo' uses in the Magic
187 201 # class as of 2005-12-28. These are names we CAN'T use in the main ipython
188 202 # class, to prevent clashes.
189 203
190 204 # ['self.__class__', 'self.__dict__', 'self._inspect', 'self._ofind',
191 205 # 'self.arg_err', 'self.extract_input', 'self.format_', 'self.lsmagic',
192 206 # 'self.magic_', 'self.options_table', 'self.parse', 'self.shell',
193 207 # 'self.value']
194 208
195 209 class InteractiveShell(Component, Magic):
196 210 """An enhanced console for Python."""
197 211
198 alias = []
199 212 autocall = Enum((0,1,2), config_key='AUTOCALL')
200 213 autoedit_syntax = CBool(False, config_key='AUTOEDIT_SYNTAX')
201 214 autoindent = CBool(True, config_key='AUTOINDENT')
202 215 automagic = CBool(True, config_key='AUTOMAGIC')
203 autoexec = []
204 216 display_banner = CBool(True, config_key='DISPLAY_BANNER')
205 217 banner = Str('')
206 218 banner1 = Str(default_banner, config_key='BANNER1')
207 219 banner2 = Str('', config_key='BANNER2')
208 220 c = Str('', config_key='C')
209 221 cache_size = Int(1000, config_key='CACHE_SIZE')
210 222 classic = CBool(False, config_key='CLASSIC')
211 223 color_info = CBool(True, config_key='COLOR_INFO')
212 224 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
213 225 default_value='LightBG', config_key='COLORS')
214 226 confirm_exit = CBool(True, config_key='CONFIRM_EXIT')
215 debug = CBool(False)
227 debug = CBool(False, config_key='DEBUG')
216 228 deep_reload = CBool(False, config_key='DEEP_RELOAD')
217 229 embedded = CBool(False)
218 230 editor = Str(get_default_editor(), config_key='EDITOR')
219 231 filename = Str("<ipython console>")
220 help = CBool(False)
221 interactive = CBool(False)
232 interactive = CBool(False, config_key='INTERACTIVE')
222 233 logstart = CBool(False, config_key='LOGSTART')
223 234 logfile = Str('', config_key='LOGFILE')
224 235 logplay = Str('', config_key='LOGPLAY')
225 multi_line_specials = CBool(True)
226 object_info_string_level = Int(0)
227 pager = Str('less')
236 multi_line_specials = CBool(True, config_key='MULTI_LINE_SPECIALS')
237 object_info_string_level = Enum((0,1,2), default_value=0,
238 config_keys='OBJECT_INFO_STRING_LEVEL')
239 pager = Str('less', config_key='PAGER')
228 240 pdb = CBool(False, config_key='PDB')
229 241 pprint = CBool(True, config_key='PPRINT')
230 242 profile = Str('', config_key='PROFILE')
231 243 prompt_in1 = Str('In [\\#]: ', config_key='PROMPT_IN1')
232 244 prompt_in2 = Str(' .\\D.: ', config_key='PROMPT_IN2')
233 245 prompt_out = Str('Out[\\#]: ', config_key='PROMPT_OUT1')
234 prompts_pad_left = CBool(True)
235 pydb = CBool(False)
236 quiet = CBool(False)
246 prompts_pad_left = CBool(True, config_key='PROMPTS_PAD_LEFT')
247 quiet = CBool(False, config_key='QUIET')
237 248
238 249 readline_use = CBool(True, config_key='READLINE_USE')
239 readline_merge_completions = CBool(True)
240 readline_omit__names = Int(0)
241 readline_remove_delims = '-/~'
242 readline_parse_and_bind = [
250 readline_merge_completions = CBool(True,
251 config_key='READLINE_MERGE_COMPLETIONS')
252 readline_omit__names = Enum((0,1,2), default_value=0,
253 config_key='READLINE_OMIT_NAMES')
254 readline_remove_delims = Str('-/~', config_key='READLINE_REMOVE_DELIMS')
255 readline_parse_and_bind = List([
243 256 'tab: complete',
244 257 '"\C-l": possible-completions',
245 258 'set show-all-if-ambiguous on',
246 259 '"\C-o": tab-insert',
247 260 '"\M-i": " "',
248 261 '"\M-o": "\d\d\d\d"',
249 262 '"\M-I": "\d\d\d\d"',
250 263 '"\C-r": reverse-search-history',
251 264 '"\C-s": forward-search-history',
252 265 '"\C-p": history-search-backward',
253 266 '"\C-n": history-search-forward',
254 267 '"\e[A": history-search-backward',
255 268 '"\e[B": history-search-forward',
256 269 '"\C-k": kill-line',
257 270 '"\C-u": unix-line-discard',
258 ]
271 ], allow_none=False, config_key='READLINE_PARSE_AND_BIND'
272 )
259 273
260 274 screen_length = Int(0, config_key='SCREEN_LENGTH')
261 separate_in = Str('\n', config_key='SEPARATE_IN')
262 separate_out = Str('', config_key='SEPARATE_OUT')
263 separate_out2 = Str('', config_key='SEPARATE_OUT2')
264 system_header = Str('IPython system call: ')
265 system_verbose = CBool(False)
266 term_title = CBool(True)
267 wildcards_case_sensitive = CBool(True)
275
276 # Use custom TraitletTypes that convert '0'->'' and '\\n'->'\n'
277 separate_in = SeparateStr('\n', config_key='SEPARATE_IN')
278 separate_out = SeparateStr('', config_key='SEPARATE_OUT')
279 separate_out2 = SeparateStr('', config_key='SEPARATE_OUT2')
280
281 system_header = Str('IPython system call: ', config_key='SYSTEM_HEADER')
282 system_verbose = CBool(False, config_key='SYSTEM_VERBOSE')
283 term_title = CBool(False, config_key='TERM_TITLE')
284 wildcards_case_sensitive = CBool(True, config_key='WILDCARDS_CASE_SENSITIVE')
268 285 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
269 286 default_value='Context', config_key='XMODE')
270 magic_docstrings = CBool(False)
287
288 alias = List(allow_none=False, config_key='ALIAS')
289 autoexec = List(allow_none=False)
271 290
272 291 # class attribute to indicate whether the class supports threads or not.
273 292 # Subclasses with thread support should override this as needed.
274 293 isthreaded = False
275 294
276 295 def __init__(self, name, parent=None, config=None, usage=None,
277 296 user_ns=None, user_global_ns=None,
278 297 banner1='', banner2='',
279 298 custom_exceptions=((),None), embedded=False):
280 299
281 300 # This is where traitlets with a config_key argument are updated
282 301 # from the values on config.
283 302 # Ideally, from here on out, the config should only be used when
284 303 # passing it to children components.
285 304 super(InteractiveShell, self).__init__(parent, config=config, name=name)
286 305
287 306 self.init_instance_attrs()
307 self.init_term_title()
288 308 self.init_usage(usage)
289 309 self.init_banner(banner1, banner2)
290 310 self.init_embedded(embedded)
291 311 self.init_create_namespaces(user_ns, user_global_ns)
292 312 self.init_history()
293 313 self.init_encoding()
294 314 self.init_handlers()
295 315
296 316 Magic.__init__(self, self)
297 317
298 318 self.init_syntax_highlighting()
299 319 self.init_hooks()
300 320 self.init_pushd_popd_magic()
301 321 self.init_traceback_handlers(custom_exceptions)
302 322
303 323 # Produce a public API instance
304 324 self.api = ipapi.IPApi(self)
305 325
306 326 self.init_namespaces()
307 327 self.init_logger()
308 328 self.init_aliases()
309 329 self.init_builtins()
310 330
311 331 # pre_config_initialization
312 332 self.init_shadow_hist()
313 333
314 334 # The next section should contain averything that was in ipmaker.
315 335 self.init_logstart()
316 336
317 337 # The following was in post_config_initialization
318 338 self.init_inspector()
319 339 self.init_readline()
320 340 self.init_prompts()
321 341 self.init_displayhook()
322 342 self.init_reload_doctest()
323 343 self.init_magics()
324 344 self.init_pdb()
325 345 self.hooks.late_startup_hook()
326 346 self.init_exec_commands()
327 347
328 348 #-------------------------------------------------------------------------
329 349 # Traitlet changed handlers
330 350 #-------------------------------------------------------------------------
331 351
332 352 def _banner1_changed(self):
333 353 self.compute_banner()
334 354
335 355 def _banner2_changed(self):
336 356 self.compute_banner()
337 357
338 358 @property
339 359 def usable_screen_length(self):
340 360 if self.screen_length == 0:
341 361 return 0
342 362 else:
343 363 num_lines_bot = self.separate_in.count('\n')+1
344 364 return self.screen_length - num_lines_bot
345 365
366 def _term_title_changed(self, name, new_value):
367 self.init_term_title()
368
346 369 #-------------------------------------------------------------------------
347 370 # init_* methods called by __init__
348 371 #-------------------------------------------------------------------------
349 372
350 373 def init_instance_attrs(self):
351 374 self.jobs = BackgroundJobManager()
352 375 self.more = False
353 376
354 377 # command compiler
355 378 self.compile = codeop.CommandCompiler()
356 379
357 380 # User input buffer
358 381 self.buffer = []
359 382
360 383 # Make an empty namespace, which extension writers can rely on both
361 384 # existing and NEVER being used by ipython itself. This gives them a
362 385 # convenient location for storing additional information and state
363 386 # their extensions may require, without fear of collisions with other
364 387 # ipython names that may develop later.
365 388 self.meta = Struct()
366 389
367 390 # Object variable to store code object waiting execution. This is
368 391 # used mainly by the multithreaded shells, but it can come in handy in
369 392 # other situations. No need to use a Queue here, since it's a single
370 393 # item which gets cleared once run.
371 394 self.code_to_run = None
372 395
373 396 # Flag to mark unconditional exit
374 397 self.exit_now = False
375 398
376 399 # Temporary files used for various purposes. Deleted at exit.
377 400 self.tempfiles = []
378 401
379 402 # Keep track of readline usage (later set by init_readline)
380 403 self.has_readline = False
381 404
382 405 # keep track of where we started running (mainly for crash post-mortem)
383 406 # This is not being used anywhere currently.
384 407 self.starting_dir = os.getcwd()
385 408
386 409 # Indentation management
387 410 self.indent_current_nsp = 0
388 411
412 def init_term_title(self):
413 # Enable or disable the terminal title.
414 if self.term_title:
415 toggle_set_term_title(True)
416 set_term_title('IPython: ' + abbrev_cwd())
417 else:
418 toggle_set_term_title(False)
419
389 420 def init_usage(self, usage=None):
390 421 if usage is None:
391 422 self.usage = interactive_usage
392 423 else:
393 424 self.usage = usage
394 425
395 426 def init_banner(self, banner1, banner2):
396 427 if self.c: # regular python doesn't print the banner with -c
397 428 self.display_banner = False
398 429 if banner1:
399 430 self.banner1 = banner1
400 431 if banner2:
401 432 self.banner2 = banner2
402 433 self.compute_banner()
403 434
404 435 def compute_banner(self):
405 436 self.banner = self.banner1 + '\n'
406 437 if self.profile:
407 438 self.banner += '\nIPython profile: %s\n' % self.profile
408 439 if self.banner2:
409 440 self.banner += '\n' + self.banner2 + '\n'
410 441
411 442 def init_embedded(self, embedded):
412 443 # We need to know whether the instance is meant for embedding, since
413 444 # global/local namespaces need to be handled differently in that case
414 445 self.embedded = embedded
415 446 if embedded:
416 447 # Control variable so users can, from within the embedded instance,
417 448 # permanently deactivate it.
418 449 self.embedded_active = True
419 450
420 451 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
421 452 # Create the namespace where the user will operate. user_ns is
422 453 # normally the only one used, and it is passed to the exec calls as
423 454 # the locals argument. But we do carry a user_global_ns namespace
424 455 # given as the exec 'globals' argument, This is useful in embedding
425 456 # situations where the ipython shell opens in a context where the
426 457 # distinction between locals and globals is meaningful. For
427 458 # non-embedded contexts, it is just the same object as the user_ns dict.
428 459
429 460 # FIXME. For some strange reason, __builtins__ is showing up at user
430 461 # level as a dict instead of a module. This is a manual fix, but I
431 462 # should really track down where the problem is coming from. Alex
432 463 # Schmolck reported this problem first.
433 464
434 465 # A useful post by Alex Martelli on this topic:
435 466 # Re: inconsistent value from __builtins__
436 467 # Von: Alex Martelli <aleaxit@yahoo.com>
437 468 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
438 469 # Gruppen: comp.lang.python
439 470
440 471 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
441 472 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
442 473 # > <type 'dict'>
443 474 # > >>> print type(__builtins__)
444 475 # > <type 'module'>
445 476 # > Is this difference in return value intentional?
446 477
447 478 # Well, it's documented that '__builtins__' can be either a dictionary
448 479 # or a module, and it's been that way for a long time. Whether it's
449 480 # intentional (or sensible), I don't know. In any case, the idea is
450 481 # that if you need to access the built-in namespace directly, you
451 482 # should start with "import __builtin__" (note, no 's') which will
452 483 # definitely give you a module. Yeah, it's somewhat confusing:-(.
453 484
454 485 # These routines return properly built dicts as needed by the rest of
455 486 # the code, and can also be used by extension writers to generate
456 487 # properly initialized namespaces.
457 488 user_ns, user_global_ns = ipapi.make_user_namespaces(user_ns,
458 489 user_global_ns)
459 490
460 491 # Assign namespaces
461 492 # This is the namespace where all normal user variables live
462 493 self.user_ns = user_ns
463 494 self.user_global_ns = user_global_ns
464 495
465 496 # An auxiliary namespace that checks what parts of the user_ns were
466 497 # loaded at startup, so we can list later only variables defined in
467 498 # actual interactive use. Since it is always a subset of user_ns, it
468 499 # doesn't need to be seaparately tracked in the ns_table
469 500 self.user_config_ns = {}
470 501
471 502 # A namespace to keep track of internal data structures to prevent
472 503 # them from cluttering user-visible stuff. Will be updated later
473 504 self.internal_ns = {}
474 505
475 506 # Namespace of system aliases. Each entry in the alias
476 507 # table must be a 2-tuple of the form (N,name), where N is the number
477 508 # of positional arguments of the alias.
478 509 self.alias_table = {}
479 510
480 511 # Now that FakeModule produces a real module, we've run into a nasty
481 512 # problem: after script execution (via %run), the module where the user
482 513 # code ran is deleted. Now that this object is a true module (needed
483 514 # so docetst and other tools work correctly), the Python module
484 515 # teardown mechanism runs over it, and sets to None every variable
485 516 # present in that module. Top-level references to objects from the
486 517 # script survive, because the user_ns is updated with them. However,
487 518 # calling functions defined in the script that use other things from
488 519 # the script will fail, because the function's closure had references
489 520 # to the original objects, which are now all None. So we must protect
490 521 # these modules from deletion by keeping a cache.
491 522 #
492 523 # To avoid keeping stale modules around (we only need the one from the
493 524 # last run), we use a dict keyed with the full path to the script, so
494 525 # only the last version of the module is held in the cache. Note,
495 526 # however, that we must cache the module *namespace contents* (their
496 527 # __dict__). Because if we try to cache the actual modules, old ones
497 528 # (uncached) could be destroyed while still holding references (such as
498 529 # those held by GUI objects that tend to be long-lived)>
499 530 #
500 531 # The %reset command will flush this cache. See the cache_main_mod()
501 532 # and clear_main_mod_cache() methods for details on use.
502 533
503 534 # This is the cache used for 'main' namespaces
504 535 self._main_ns_cache = {}
505 536 # And this is the single instance of FakeModule whose __dict__ we keep
506 537 # copying and clearing for reuse on each %run
507 538 self._user_main_module = FakeModule()
508 539
509 540 # A table holding all the namespaces IPython deals with, so that
510 541 # introspection facilities can search easily.
511 542 self.ns_table = {'user':user_ns,
512 543 'user_global':user_global_ns,
513 544 'alias':self.alias_table,
514 545 'internal':self.internal_ns,
515 546 'builtin':__builtin__.__dict__
516 547 }
517 548
518 549 # Similarly, track all namespaces where references can be held and that
519 550 # we can safely clear (so it can NOT include builtin). This one can be
520 551 # a simple list.
521 552 self.ns_refs_table = [ user_ns, user_global_ns, self.user_config_ns,
522 553 self.alias_table, self.internal_ns,
523 554 self._main_ns_cache ]
524 555
525 556 # We need to insert into sys.modules something that looks like a
526 557 # module but which accesses the IPython namespace, for shelve and
527 558 # pickle to work interactively. Normally they rely on getting
528 559 # everything out of __main__, but for embedding purposes each IPython
529 560 # instance has its own private namespace, so we can't go shoving
530 561 # everything into __main__.
531 562
532 563 # note, however, that we should only do this for non-embedded
533 564 # ipythons, which really mimic the __main__.__dict__ with their own
534 565 # namespace. Embedded instances, on the other hand, should not do
535 566 # this because they need to manage the user local/global namespaces
536 567 # only, but they live within a 'normal' __main__ (meaning, they
537 568 # shouldn't overtake the execution environment of the script they're
538 569 # embedded in).
539 570
540 571 if not self.embedded:
541 572 try:
542 573 main_name = self.user_ns['__name__']
543 574 except KeyError:
544 575 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
545 576 else:
546 577 sys.modules[main_name] = FakeModule(self.user_ns)
547 578
548 579 def init_history(self):
549 580 # List of input with multi-line handling.
550 581 self.input_hist = InputList()
551 582 # This one will hold the 'raw' input history, without any
552 583 # pre-processing. This will allow users to retrieve the input just as
553 584 # it was exactly typed in by the user, with %hist -r.
554 585 self.input_hist_raw = InputList()
555 586
556 587 # list of visited directories
557 588 try:
558 589 self.dir_hist = [os.getcwd()]
559 590 except OSError:
560 591 self.dir_hist = []
561 592
562 593 # dict of output history
563 594 self.output_hist = {}
564 595
565 596 # Now the history file
566 597 try:
567 histfname = 'history-%s' % self.config.PROFILE
598 histfname = 'history-%s' % self.profile
568 599 except AttributeError:
569 600 histfname = 'history'
570 601 self.histfile = os.path.join(self.config.IPYTHONDIR, histfname)
571 602
572 603 # Fill the history zero entry, user counter starts at 1
573 604 self.input_hist.append('\n')
574 605 self.input_hist_raw.append('\n')
575 606
576 607 def init_encoding(self):
577 608 # Get system encoding at startup time. Certain terminals (like Emacs
578 609 # under Win32 have it set to None, and we need to have a known valid
579 610 # encoding to use in the raw_input() method
580 611 try:
581 612 self.stdin_encoding = sys.stdin.encoding or 'ascii'
582 613 except AttributeError:
583 614 self.stdin_encoding = 'ascii'
584 615
585 616 def init_handlers(self):
586 617 # escapes for automatic behavior on the command line
587 618 self.ESC_SHELL = '!'
588 619 self.ESC_SH_CAP = '!!'
589 620 self.ESC_HELP = '?'
590 621 self.ESC_MAGIC = '%'
591 622 self.ESC_QUOTE = ','
592 623 self.ESC_QUOTE2 = ';'
593 624 self.ESC_PAREN = '/'
594 625
595 626 # And their associated handlers
596 627 self.esc_handlers = {self.ESC_PAREN : self.handle_auto,
597 628 self.ESC_QUOTE : self.handle_auto,
598 629 self.ESC_QUOTE2 : self.handle_auto,
599 630 self.ESC_MAGIC : self.handle_magic,
600 631 self.ESC_HELP : self.handle_help,
601 632 self.ESC_SHELL : self.handle_shell_escape,
602 633 self.ESC_SH_CAP : self.handle_shell_escape,
603 634 }
604 635
605 636 def init_syntax_highlighting(self):
606 637 # Python source parser/formatter for syntax highlighting
607 638 pyformat = PyColorize.Parser().format
608 639 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
609 640
610 641 def init_hooks(self):
611 642 # hooks holds pointers used for user-side customizations
612 643 self.hooks = Struct()
613 644
614 645 self.strdispatchers = {}
615 646
616 647 # Set all default hooks, defined in the IPython.hooks module.
617 648 import IPython.core.hooks
618 649 hooks = IPython.core.hooks
619 650 for hook_name in hooks.__all__:
620 651 # default hooks have priority 100, i.e. low; user hooks should have
621 652 # 0-100 priority
622 653 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
623 654
624 655 def init_pushd_popd_magic(self):
625 656 # for pushd/popd management
626 657 try:
627 658 self.home_dir = get_home_dir()
628 659 except HomeDirError, msg:
629 660 fatal(msg)
630 661
631 662 self.dir_stack = []
632 663
633 664 def init_traceback_handlers(self, custom_exceptions):
634 665 # Syntax error handler.
635 666 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
636 667
637 668 # The interactive one is initialized with an offset, meaning we always
638 669 # want to remove the topmost item in the traceback, which is our own
639 670 # internal code. Valid modes: ['Plain','Context','Verbose']
640 671 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
641 672 color_scheme='NoColor',
642 673 tb_offset = 1)
643 674
644 675 # IPython itself shouldn't crash. This will produce a detailed
645 676 # post-mortem if it does. But we only install the crash handler for
646 677 # non-threaded shells, the threaded ones use a normal verbose reporter
647 678 # and lose the crash handler. This is because exceptions in the main
648 679 # thread (such as in GUI code) propagate directly to sys.excepthook,
649 680 # and there's no point in printing crash dumps for every user exception.
650 681 if self.isthreaded:
651 682 ipCrashHandler = ultratb.FormattedTB()
652 683 else:
653 684 from IPython.core import crashhandler
654 685 ipCrashHandler = crashhandler.IPythonCrashHandler(self)
655 686 self.set_crash_handler(ipCrashHandler)
656 687
657 688 # and add any custom exception handlers the user may have specified
658 689 self.set_custom_exc(*custom_exceptions)
659 690
660 691 def init_logger(self):
661 692 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
662 693 # local shortcut, this is used a LOT
663 694 self.log = self.logger.log
664 695 # template for logfile headers. It gets resolved at runtime by the
665 696 # logstart method.
666 697 self.loghead_tpl = \
667 698 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
668 699 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
669 700 #log# opts = %s
670 701 #log# args = %s
671 702 #log# It is safe to make manual edits below here.
672 703 #log#-----------------------------------------------------------------------
673 704 """
674 705
675 706 def init_logstart(self):
676 707 if self.logplay:
677 708 self.magic_logstart(self.logplay + ' append')
678 709 elif self.logfile:
679 710 self.magic_logstart(self.logfile)
680 711 elif self.logstart:
681 712 self.magic_logstart()
682 713
683 714 def init_aliases(self):
684 715 # dict of things NOT to alias (keywords, builtins and some magics)
685 716 no_alias = {}
686 717 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
687 718 for key in keyword.kwlist + no_alias_magics:
688 719 no_alias[key] = 1
689 720 no_alias.update(__builtin__.__dict__)
690 721 self.no_alias = no_alias
691 722
692 723 # Make some aliases automatically
693 724 # Prepare list of shell aliases to auto-define
694 725 if os.name == 'posix':
695 726 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
696 727 'mv mv -i','rm rm -i','cp cp -i',
697 728 'cat cat','less less','clear clear',
698 729 # a better ls
699 730 'ls ls -F',
700 731 # long ls
701 732 'll ls -lF')
702 733 # Extra ls aliases with color, which need special treatment on BSD
703 734 # variants
704 735 ls_extra = ( # color ls
705 736 'lc ls -F -o --color',
706 737 # ls normal files only
707 738 'lf ls -F -o --color %l | grep ^-',
708 739 # ls symbolic links
709 740 'lk ls -F -o --color %l | grep ^l',
710 741 # directories or links to directories,
711 742 'ldir ls -F -o --color %l | grep /$',
712 743 # things which are executable
713 744 'lx ls -F -o --color %l | grep ^-..x',
714 745 )
715 746 # The BSDs don't ship GNU ls, so they don't understand the
716 747 # --color switch out of the box
717 748 if 'bsd' in sys.platform:
718 749 ls_extra = ( # ls normal files only
719 750 'lf ls -lF | grep ^-',
720 751 # ls symbolic links
721 752 'lk ls -lF | grep ^l',
722 753 # directories or links to directories,
723 754 'ldir ls -lF | grep /$',
724 755 # things which are executable
725 756 'lx ls -lF | grep ^-..x',
726 757 )
727 758 auto_alias = auto_alias + ls_extra
728 759 elif os.name in ['nt','dos']:
729 760 auto_alias = ('ls dir /on',
730 761 'ddir dir /ad /on', 'ldir dir /ad /on',
731 762 'mkdir mkdir','rmdir rmdir','echo echo',
732 763 'ren ren','cls cls','copy copy')
733 764 else:
734 765 auto_alias = ()
735 766 self.auto_alias = [s.split(None,1) for s in auto_alias]
736 767
737 768 # Load default aliases
738 769 for alias, cmd in self.auto_alias:
739 770 self.define_alias(alias,cmd)
740 771
741 772 # Load user aliases
742 773 for alias in self.alias:
743 774 self.magic_alias(alias)
744 775
745 776 def init_builtins(self):
746 777 # track which builtins we add, so we can clean up later
747 778 self.builtins_added = {}
748 779 # This method will add the necessary builtins for operation, but
749 780 # tracking what it did via the builtins_added dict.
750 781
751 782 #TODO: remove this, redundant. I don't understand why this is
752 783 # redundant?
753 784 self.add_builtins()
754 785
755 786 def init_shadow_hist(self):
756 787 try:
757 788 self.db = pickleshare.PickleShareDB(self.config.IPYTHONDIR + "/db")
758 789 except exceptions.UnicodeDecodeError:
759 790 print "Your ipythondir can't be decoded to unicode!"
760 791 print "Please set HOME environment variable to something that"
761 792 print r"only has ASCII characters, e.g. c:\home"
762 793 print "Now it is", self.config.IPYTHONDIR
763 794 sys.exit()
764 795 self.shadowhist = ipcorehist.ShadowHist(self.db)
765 796
766 797 def init_inspector(self):
767 798 # Object inspector
768 799 self.inspector = oinspect.Inspector(oinspect.InspectColors,
769 800 PyColorize.ANSICodeColors,
770 801 'NoColor',
771 802 self.object_info_string_level)
772 803
773 804 def init_readline(self):
774 805 """Command history completion/saving/reloading."""
775 806
776 807 self.rl_next_input = None
777 808 self.rl_do_indent = False
778 809
779 810 if not self.readline_use:
780 811 return
781 812
782 813 import IPython.utils.rlineimpl as readline
783 814
784 815 if not readline.have_readline:
785 816 self.has_readline = 0
786 817 self.readline = None
787 818 # no point in bugging windows users with this every time:
788 819 warn('Readline services not available on this platform.')
789 820 else:
790 821 sys.modules['readline'] = readline
791 822 import atexit
792 823 from IPython.core.completer import IPCompleter
793 824 self.Completer = IPCompleter(self,
794 825 self.user_ns,
795 826 self.user_global_ns,
796 827 self.readline_omit__names,
797 828 self.alias_table)
798 829 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
799 830 self.strdispatchers['complete_command'] = sdisp
800 831 self.Completer.custom_completers = sdisp
801 832 # Platform-specific configuration
802 833 if os.name == 'nt':
803 834 self.readline_startup_hook = readline.set_pre_input_hook
804 835 else:
805 836 self.readline_startup_hook = readline.set_startup_hook
806 837
807 838 # Load user's initrc file (readline config)
808 839 # Or if libedit is used, load editrc.
809 840 inputrc_name = os.environ.get('INPUTRC')
810 841 if inputrc_name is None:
811 842 home_dir = get_home_dir()
812 843 if home_dir is not None:
813 844 inputrc_name = '.inputrc'
814 845 if readline.uses_libedit:
815 846 inputrc_name = '.editrc'
816 847 inputrc_name = os.path.join(home_dir, inputrc_name)
817 848 if os.path.isfile(inputrc_name):
818 849 try:
819 850 readline.read_init_file(inputrc_name)
820 851 except:
821 852 warn('Problems reading readline initialization file <%s>'
822 853 % inputrc_name)
823 854
824 855 self.has_readline = 1
825 856 self.readline = readline
826 857 # save this in sys so embedded copies can restore it properly
827 858 sys.ipcompleter = self.Completer.complete
828 859 self.set_completer()
829 860
830 861 # Configure readline according to user's prefs
831 862 # This is only done if GNU readline is being used. If libedit
832 863 # is being used (as on Leopard) the readline config is
833 864 # not run as the syntax for libedit is different.
834 865 if not readline.uses_libedit:
835 866 for rlcommand in self.readline_parse_and_bind:
836 867 #print "loading rl:",rlcommand # dbg
837 868 readline.parse_and_bind(rlcommand)
838 869
839 870 # Remove some chars from the delimiters list. If we encounter
840 871 # unicode chars, discard them.
841 872 delims = readline.get_completer_delims().encode("ascii", "ignore")
842 873 delims = delims.translate(string._idmap,
843 874 self.readline_remove_delims)
844 875 readline.set_completer_delims(delims)
845 876 # otherwise we end up with a monster history after a while:
846 877 readline.set_history_length(1000)
847 878 try:
848 879 #print '*** Reading readline history' # dbg
849 880 readline.read_history_file(self.histfile)
850 881 except IOError:
851 882 pass # It doesn't exist yet.
852 883
853 884 atexit.register(self.atexit_operations)
854 885 del atexit
855 886
856 887 # Configure auto-indent for all platforms
857 888 self.set_autoindent(self.autoindent)
858 889
859 890 def init_prompts(self):
860 891 # Initialize cache, set in/out prompts and printing system
861 892 self.outputcache = CachedOutput(self,
862 893 self.cache_size,
863 894 self.pprint,
864 895 input_sep = self.separate_in,
865 896 output_sep = self.separate_out,
866 897 output_sep2 = self.separate_out2,
867 898 ps1 = self.prompt_in1,
868 899 ps2 = self.prompt_in2,
869 900 ps_out = self.prompt_out,
870 901 pad_left = self.prompts_pad_left)
871 902
872 903 # user may have over-ridden the default print hook:
873 904 try:
874 905 self.outputcache.__class__.display = self.hooks.display
875 906 except AttributeError:
876 907 pass
877 908
878 909 def init_displayhook(self):
879 910 # I don't like assigning globally to sys, because it means when
880 911 # embedding instances, each embedded instance overrides the previous
881 912 # choice. But sys.displayhook seems to be called internally by exec,
882 913 # so I don't see a way around it. We first save the original and then
883 914 # overwrite it.
884 915 self.sys_displayhook = sys.displayhook
885 916 sys.displayhook = self.outputcache
886 917
887 918 def init_reload_doctest(self):
888 919 # Do a proper resetting of doctest, including the necessary displayhook
889 920 # monkeypatching
890 921 try:
891 922 doctest_reload()
892 923 except ImportError:
893 924 warn("doctest module does not exist.")
894 925
895 926 def init_magics(self):
896 927 # Set user colors (don't do it in the constructor above so that it
897 928 # doesn't crash if colors option is invalid)
898 929 self.magic_colors(self.colors)
899 930
900 931 def init_pdb(self):
901 932 # Set calling of pdb on exceptions
902 933 # self.call_pdb is a property
903 934 self.call_pdb = self.pdb
904 935
905 936 def init_exec_commands(self):
906 for cmd in self.autoexec:
907 #print "autoexec>",cmd #dbg
937 for cmd in self.config.EXECUTE:
938 print "execute:", cmd
908 939 self.api.runlines(cmd)
909 940
910 941 batchrun = False
911 942 if self.config.has_key('EXECFILE'):
912 943 for batchfile in [path(arg) for arg in self.config.EXECFILE
913 944 if arg.lower().endswith('.ipy')]:
914 945 if not batchfile.isfile():
915 946 print "No such batch file:", batchfile
916 947 continue
917 948 self.api.runlines(batchfile.text())
918 949 batchrun = True
919 950 # without -i option, exit after running the batch file
920 951 if batchrun and not self.interactive:
921 952 self.ask_exit()
922 953
923 954 def init_namespaces(self):
924 955 """Initialize all user-visible namespaces to their minimum defaults.
925 956
926 957 Certain history lists are also initialized here, as they effectively
927 958 act as user namespaces.
928 959
929 960 Notes
930 961 -----
931 962 All data structures here are only filled in, they are NOT reset by this
932 963 method. If they were not empty before, data will simply be added to
933 964 therm.
934 965 """
935 966 # The user namespace MUST have a pointer to the shell itself.
936 967 self.user_ns[self.name] = self
937 968
938 969 # Store the public api instance
939 970 self.user_ns['_ip'] = self.api
940 971
941 972 # make global variables for user access to the histories
942 973 self.user_ns['_ih'] = self.input_hist
943 974 self.user_ns['_oh'] = self.output_hist
944 975 self.user_ns['_dh'] = self.dir_hist
945 976
946 977 # user aliases to input and output histories
947 978 self.user_ns['In'] = self.input_hist
948 979 self.user_ns['Out'] = self.output_hist
949 980
950 981 self.user_ns['_sh'] = shadowns
951 982
952 983 # Put 'help' in the user namespace
953 984 try:
954 985 from site import _Helper
955 986 self.user_ns['help'] = _Helper()
956 987 except ImportError:
957 988 warn('help() not available - check site.py')
958 989
959 990 def add_builtins(self):
960 991 """Store ipython references into the builtin namespace.
961 992
962 993 Some parts of ipython operate via builtins injected here, which hold a
963 994 reference to IPython itself."""
964 995
965 996 # Install our own quitter instead of the builtins.
966 997 # This used to be in the __init__ method, but this is a better
967 998 # place for it. These can be incorporated to the logic below
968 999 # when it is refactored.
969 1000 __builtin__.exit = Quitter(self,'exit')
970 1001 __builtin__.quit = Quitter(self,'quit')
971 1002
972 1003 # Recursive reload
973 1004 try:
974 1005 from IPython.lib import deepreload
975 1006 if self.deep_reload:
976 1007 __builtin__.reload = deepreload.reload
977 1008 else:
978 1009 __builtin__.dreload = deepreload.reload
979 1010 del deepreload
980 1011 except ImportError:
981 1012 pass
982 1013
983 1014 # TODO: deprecate all of these, they are unsafe. Why though?
984 1015 builtins_new = dict(__IPYTHON__ = self,
985 1016 ip_set_hook = self.set_hook,
986 1017 jobs = self.jobs,
987 1018 ipmagic = wrap_deprecated(self.ipmagic,'_ip.magic()'),
988 1019 ipalias = wrap_deprecated(self.ipalias),
989 1020 ipsystem = wrap_deprecated(self.ipsystem,'_ip.system()'),
990 1021 #_ip = self.api
991 1022 )
992 1023 for biname,bival in builtins_new.items():
993 1024 try:
994 1025 # store the orignal value so we can restore it
995 1026 self.builtins_added[biname] = __builtin__.__dict__[biname]
996 1027 except KeyError:
997 1028 # or mark that it wasn't defined, and we'll just delete it at
998 1029 # cleanup
999 1030 self.builtins_added[biname] = Undefined
1000 1031 __builtin__.__dict__[biname] = bival
1001 1032
1002 1033 # Keep in the builtins a flag for when IPython is active. We set it
1003 1034 # with setdefault so that multiple nested IPythons don't clobber one
1004 1035 # another. Each will increase its value by one upon being activated,
1005 1036 # which also gives us a way to determine the nesting level.
1006 1037 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
1007 1038
1008 1039 def clean_builtins(self):
1009 1040 """Remove any builtins which might have been added by add_builtins, or
1010 1041 restore overwritten ones to their previous values."""
1011 1042 for biname,bival in self.builtins_added.items():
1012 1043 if bival is Undefined:
1013 1044 del __builtin__.__dict__[biname]
1014 1045 else:
1015 1046 __builtin__.__dict__[biname] = bival
1016 1047 self.builtins_added.clear()
1017 1048
1018 1049 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
1019 1050 """set_hook(name,hook) -> sets an internal IPython hook.
1020 1051
1021 1052 IPython exposes some of its internal API as user-modifiable hooks. By
1022 1053 adding your function to one of these hooks, you can modify IPython's
1023 1054 behavior to call at runtime your own routines."""
1024 1055
1025 1056 # At some point in the future, this should validate the hook before it
1026 1057 # accepts it. Probably at least check that the hook takes the number
1027 1058 # of args it's supposed to.
1028 1059
1029 1060 f = new.instancemethod(hook,self,self.__class__)
1030 1061
1031 1062 # check if the hook is for strdispatcher first
1032 1063 if str_key is not None:
1033 1064 sdp = self.strdispatchers.get(name, StrDispatch())
1034 1065 sdp.add_s(str_key, f, priority )
1035 1066 self.strdispatchers[name] = sdp
1036 1067 return
1037 1068 if re_key is not None:
1038 1069 sdp = self.strdispatchers.get(name, StrDispatch())
1039 1070 sdp.add_re(re.compile(re_key), f, priority )
1040 1071 self.strdispatchers[name] = sdp
1041 1072 return
1042 1073
1043 1074 dp = getattr(self.hooks, name, None)
1044 1075 if name not in IPython.core.hooks.__all__:
1045 1076 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
1046 1077 if not dp:
1047 1078 dp = IPython.core.hooks.CommandChainDispatcher()
1048 1079
1049 1080 try:
1050 1081 dp.add(f,priority)
1051 1082 except AttributeError:
1052 1083 # it was not commandchain, plain old func - replace
1053 1084 dp = f
1054 1085
1055 1086 setattr(self.hooks,name, dp)
1056 1087
1057 1088
1058 1089 #setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
1059 1090
1060 1091 def set_crash_handler(self,crashHandler):
1061 1092 """Set the IPython crash handler.
1062 1093
1063 1094 This must be a callable with a signature suitable for use as
1064 1095 sys.excepthook."""
1065 1096
1066 1097 # Install the given crash handler as the Python exception hook
1067 1098 sys.excepthook = crashHandler
1068 1099
1069 1100 # The instance will store a pointer to this, so that runtime code
1070 1101 # (such as magics) can access it. This is because during the
1071 1102 # read-eval loop, it gets temporarily overwritten (to deal with GUI
1072 1103 # frameworks).
1073 1104 self.sys_excepthook = sys.excepthook
1074 1105
1075 1106
1076 1107 def set_custom_exc(self,exc_tuple,handler):
1077 1108 """set_custom_exc(exc_tuple,handler)
1078 1109
1079 1110 Set a custom exception handler, which will be called if any of the
1080 1111 exceptions in exc_tuple occur in the mainloop (specifically, in the
1081 1112 runcode() method.
1082 1113
1083 1114 Inputs:
1084 1115
1085 1116 - exc_tuple: a *tuple* of valid exceptions to call the defined
1086 1117 handler for. It is very important that you use a tuple, and NOT A
1087 1118 LIST here, because of the way Python's except statement works. If
1088 1119 you only want to trap a single exception, use a singleton tuple:
1089 1120
1090 1121 exc_tuple == (MyCustomException,)
1091 1122
1092 1123 - handler: this must be defined as a function with the following
1093 1124 basic interface: def my_handler(self,etype,value,tb).
1094 1125
1095 1126 This will be made into an instance method (via new.instancemethod)
1096 1127 of IPython itself, and it will be called if any of the exceptions
1097 1128 listed in the exc_tuple are caught. If the handler is None, an
1098 1129 internal basic one is used, which just prints basic info.
1099 1130
1100 1131 WARNING: by putting in your own exception handler into IPython's main
1101 1132 execution loop, you run a very good chance of nasty crashes. This
1102 1133 facility should only be used if you really know what you are doing."""
1103 1134
1104 1135 assert type(exc_tuple)==type(()) , \
1105 1136 "The custom exceptions must be given AS A TUPLE."
1106 1137
1107 1138 def dummy_handler(self,etype,value,tb):
1108 1139 print '*** Simple custom exception handler ***'
1109 1140 print 'Exception type :',etype
1110 1141 print 'Exception value:',value
1111 1142 print 'Traceback :',tb
1112 1143 print 'Source code :','\n'.join(self.buffer)
1113 1144
1114 1145 if handler is None: handler = dummy_handler
1115 1146
1116 1147 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1117 1148 self.custom_exceptions = exc_tuple
1118 1149
1119 1150 def set_custom_completer(self,completer,pos=0):
1120 1151 """set_custom_completer(completer,pos=0)
1121 1152
1122 1153 Adds a new custom completer function.
1123 1154
1124 1155 The position argument (defaults to 0) is the index in the completers
1125 1156 list where you want the completer to be inserted."""
1126 1157
1127 1158 newcomp = new.instancemethod(completer,self.Completer,
1128 1159 self.Completer.__class__)
1129 1160 self.Completer.matchers.insert(pos,newcomp)
1130 1161
1131 1162 def set_completer(self):
1132 1163 """reset readline's completer to be our own."""
1133 1164 self.readline.set_completer(self.Completer.complete)
1134 1165
1135 1166 def _get_call_pdb(self):
1136 1167 return self._call_pdb
1137 1168
1138 1169 def _set_call_pdb(self,val):
1139 1170
1140 1171 if val not in (0,1,False,True):
1141 1172 raise ValueError,'new call_pdb value must be boolean'
1142 1173
1143 1174 # store value in instance
1144 1175 self._call_pdb = val
1145 1176
1146 1177 # notify the actual exception handlers
1147 1178 self.InteractiveTB.call_pdb = val
1148 1179 if self.isthreaded:
1149 1180 try:
1150 1181 self.sys_excepthook.call_pdb = val
1151 1182 except:
1152 1183 warn('Failed to activate pdb for threaded exception handler')
1153 1184
1154 1185 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1155 1186 'Control auto-activation of pdb at exceptions')
1156 1187
1157 1188 # These special functions get installed in the builtin namespace, to
1158 1189 # provide programmatic (pure python) access to magics, aliases and system
1159 1190 # calls. This is important for logging, user scripting, and more.
1160 1191
1161 1192 # We are basically exposing, via normal python functions, the three
1162 1193 # mechanisms in which ipython offers special call modes (magics for
1163 1194 # internal control, aliases for direct system access via pre-selected
1164 1195 # names, and !cmd for calling arbitrary system commands).
1165 1196
1166 1197 def ipmagic(self,arg_s):
1167 1198 """Call a magic function by name.
1168 1199
1169 1200 Input: a string containing the name of the magic function to call and any
1170 1201 additional arguments to be passed to the magic.
1171 1202
1172 1203 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
1173 1204 prompt:
1174 1205
1175 1206 In[1]: %name -opt foo bar
1176 1207
1177 1208 To call a magic without arguments, simply use ipmagic('name').
1178 1209
1179 1210 This provides a proper Python function to call IPython's magics in any
1180 1211 valid Python code you can type at the interpreter, including loops and
1181 1212 compound statements. It is added by IPython to the Python builtin
1182 1213 namespace upon initialization."""
1183 1214
1184 1215 args = arg_s.split(' ',1)
1185 1216 magic_name = args[0]
1186 1217 magic_name = magic_name.lstrip(self.ESC_MAGIC)
1187 1218
1188 1219 try:
1189 1220 magic_args = args[1]
1190 1221 except IndexError:
1191 1222 magic_args = ''
1192 1223 fn = getattr(self,'magic_'+magic_name,None)
1193 1224 if fn is None:
1194 1225 error("Magic function `%s` not found." % magic_name)
1195 1226 else:
1196 1227 magic_args = self.var_expand(magic_args,1)
1197 1228 return fn(magic_args)
1198 1229
1199 1230 def define_alias(self, name, cmd):
1200 1231 """ Define a new alias."""
1201 1232
1202 1233 if callable(cmd):
1203 1234 self.alias_table[name] = cmd
1204 1235 from IPython.core import shadowns
1205 1236 setattr(shadowns, name, cmd)
1206 1237 return
1207 1238
1208 1239 if isinstance(cmd, basestring):
1209 1240 nargs = cmd.count('%s')
1210 1241 if nargs>0 and cmd.find('%l')>=0:
1211 1242 raise Exception('The %s and %l specifiers are mutually '
1212 1243 'exclusive in alias definitions.')
1213 1244
1214 1245 self.alias_table[name] = (nargs,cmd)
1215 1246 return
1216 1247
1217 1248 self.alias_table[name] = cmd
1218 1249
1219 1250 def ipalias(self,arg_s):
1220 1251 """Call an alias by name.
1221 1252
1222 1253 Input: a string containing the name of the alias to call and any
1223 1254 additional arguments to be passed to the magic.
1224 1255
1225 1256 ipalias('name -opt foo bar') is equivalent to typing at the ipython
1226 1257 prompt:
1227 1258
1228 1259 In[1]: name -opt foo bar
1229 1260
1230 1261 To call an alias without arguments, simply use ipalias('name').
1231 1262
1232 1263 This provides a proper Python function to call IPython's aliases in any
1233 1264 valid Python code you can type at the interpreter, including loops and
1234 1265 compound statements. It is added by IPython to the Python builtin
1235 1266 namespace upon initialization."""
1236 1267
1237 1268 args = arg_s.split(' ',1)
1238 1269 alias_name = args[0]
1239 1270 try:
1240 1271 alias_args = args[1]
1241 1272 except IndexError:
1242 1273 alias_args = ''
1243 1274 if alias_name in self.alias_table:
1244 1275 self.call_alias(alias_name,alias_args)
1245 1276 else:
1246 1277 error("Alias `%s` not found." % alias_name)
1247 1278
1248 1279 def system(self, cmd):
1249 1280 """Make a system call, using IPython."""
1250 1281 return self.hooks.shell_hook(self.var_expand(cmd, depth=2))
1251 1282
1252 1283 ipsystem = system
1253 1284
1254 1285 def getoutput(self, cmd):
1255 1286 return getoutput(self.var_expand(cmd,depth=2),
1256 1287 header=self.system_header,
1257 1288 verbose=self.system_verbose)
1258 1289
1259 1290 def getoutputerror(self, cmd):
1260 1291 return getoutputerror(self.var_expand(cmd,depth=2),
1261 1292 header=self.system_header,
1262 1293 verbose=self.system_verbose)
1263 1294
1264 1295 def complete(self,text):
1265 1296 """Return a sorted list of all possible completions on text.
1266 1297
1267 1298 Inputs:
1268 1299
1269 1300 - text: a string of text to be completed on.
1270 1301
1271 1302 This is a wrapper around the completion mechanism, similar to what
1272 1303 readline does at the command line when the TAB key is hit. By
1273 1304 exposing it as a method, it can be used by other non-readline
1274 1305 environments (such as GUIs) for text completion.
1275 1306
1276 1307 Simple usage example:
1277 1308
1278 1309 In [7]: x = 'hello'
1279 1310
1280 1311 In [8]: x
1281 1312 Out[8]: 'hello'
1282 1313
1283 1314 In [9]: print x
1284 1315 hello
1285 1316
1286 1317 In [10]: _ip.IP.complete('x.l')
1287 1318 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1288 1319 """
1289 1320
1290 1321 complete = self.Completer.complete
1291 1322 state = 0
1292 1323 # use a dict so we get unique keys, since ipyhton's multiple
1293 1324 # completers can return duplicates. When we make 2.4 a requirement,
1294 1325 # start using sets instead, which are faster.
1295 1326 comps = {}
1296 1327 while True:
1297 1328 newcomp = complete(text,state,line_buffer=text)
1298 1329 if newcomp is None:
1299 1330 break
1300 1331 comps[newcomp] = 1
1301 1332 state += 1
1302 1333 outcomps = comps.keys()
1303 1334 outcomps.sort()
1304 1335 #print "T:",text,"OC:",outcomps # dbg
1305 1336 #print "vars:",self.user_ns.keys()
1306 1337 return outcomps
1307 1338
1308 1339 def set_completer_frame(self, frame=None):
1309 1340 if frame:
1310 1341 self.Completer.namespace = frame.f_locals
1311 1342 self.Completer.global_namespace = frame.f_globals
1312 1343 else:
1313 1344 self.Completer.namespace = self.user_ns
1314 1345 self.Completer.global_namespace = self.user_global_ns
1315 1346
1316 1347 def init_auto_alias(self):
1317 1348 """Define some aliases automatically.
1318 1349
1319 1350 These are ALL parameter-less aliases"""
1320 1351
1321 1352 for alias,cmd in self.auto_alias:
1322 1353 self.getapi().defalias(alias,cmd)
1323 1354
1324 1355
1325 1356 def alias_table_validate(self,verbose=0):
1326 1357 """Update information about the alias table.
1327 1358
1328 1359 In particular, make sure no Python keywords/builtins are in it."""
1329 1360
1330 1361 no_alias = self.no_alias
1331 1362 for k in self.alias_table.keys():
1332 1363 if k in no_alias:
1333 1364 del self.alias_table[k]
1334 1365 if verbose:
1335 1366 print ("Deleting alias <%s>, it's a Python "
1336 1367 "keyword or builtin." % k)
1337 1368
1338 1369 def set_autoindent(self,value=None):
1339 1370 """Set the autoindent flag, checking for readline support.
1340 1371
1341 1372 If called with no arguments, it acts as a toggle."""
1342 1373
1343 1374 if not self.has_readline:
1344 1375 if os.name == 'posix':
1345 1376 warn("The auto-indent feature requires the readline library")
1346 1377 self.autoindent = 0
1347 1378 return
1348 1379 if value is None:
1349 1380 self.autoindent = not self.autoindent
1350 1381 else:
1351 1382 self.autoindent = value
1352 1383
1353 1384 def atexit_operations(self):
1354 1385 """This will be executed at the time of exit.
1355 1386
1356 1387 Saving of persistent data should be performed here. """
1357 1388
1358 1389 #print '*** IPython exit cleanup ***' # dbg
1359 1390 # input history
1360 1391 self.savehist()
1361 1392
1362 1393 # Cleanup all tempfiles left around
1363 1394 for tfile in self.tempfiles:
1364 1395 try:
1365 1396 os.unlink(tfile)
1366 1397 except OSError:
1367 1398 pass
1368 1399
1369 1400 # Clear all user namespaces to release all references cleanly.
1370 1401 self.reset()
1371 1402
1372 1403 # Run user hooks
1373 1404 self.hooks.shutdown_hook()
1374 1405
1375 1406 def reset(self):
1376 1407 """Clear all internal namespaces.
1377 1408
1378 1409 Note that this is much more aggressive than %reset, since it clears
1379 1410 fully all namespaces, as well as all input/output lists.
1380 1411 """
1381 1412 for ns in self.ns_refs_table:
1382 1413 ns.clear()
1383 1414
1384 1415 # Clear input and output histories
1385 1416 self.input_hist[:] = []
1386 1417 self.input_hist_raw[:] = []
1387 1418 self.output_hist.clear()
1388 1419 # Restore the user namespaces to minimal usability
1389 1420 self.init_namespaces()
1390 1421
1391 1422 def savehist(self):
1392 1423 """Save input history to a file (via readline library)."""
1393 1424
1394 1425 if not self.has_readline:
1395 1426 return
1396 1427
1397 1428 try:
1398 1429 self.readline.write_history_file(self.histfile)
1399 1430 except:
1400 1431 print 'Unable to save IPython command history to file: ' + \
1401 1432 `self.histfile`
1402 1433
1403 1434 def reloadhist(self):
1404 1435 """Reload the input history from disk file."""
1405 1436
1406 1437 if self.has_readline:
1407 1438 try:
1408 1439 self.readline.clear_history()
1409 1440 self.readline.read_history_file(self.shell.histfile)
1410 1441 except AttributeError:
1411 1442 pass
1412 1443
1413 1444
1414 1445 def history_saving_wrapper(self, func):
1415 1446 """ Wrap func for readline history saving
1416 1447
1417 1448 Convert func into callable that saves & restores
1418 1449 history around the call """
1419 1450
1420 1451 if not self.has_readline:
1421 1452 return func
1422 1453
1423 1454 def wrapper():
1424 1455 self.savehist()
1425 1456 try:
1426 1457 func()
1427 1458 finally:
1428 1459 readline.read_history_file(self.histfile)
1429 1460 return wrapper
1430 1461
1431 1462 def pre_readline(self):
1432 1463 """readline hook to be used at the start of each line.
1433 1464
1434 1465 Currently it handles auto-indent only."""
1435 1466
1436 1467 #debugx('self.indent_current_nsp','pre_readline:')
1437 1468
1438 1469 if self.rl_do_indent:
1439 1470 self.readline.insert_text(self.indent_current_str())
1440 1471 if self.rl_next_input is not None:
1441 1472 self.readline.insert_text(self.rl_next_input)
1442 1473 self.rl_next_input = None
1443 1474
1444 1475 def ask_yes_no(self,prompt,default=True):
1445 1476 if self.quiet:
1446 1477 return True
1447 1478 return ask_yes_no(prompt,default)
1448 1479
1449 1480 def new_main_mod(self,ns=None):
1450 1481 """Return a new 'main' module object for user code execution.
1451 1482 """
1452 1483 main_mod = self._user_main_module
1453 1484 init_fakemod_dict(main_mod,ns)
1454 1485 return main_mod
1455 1486
1456 1487 def cache_main_mod(self,ns,fname):
1457 1488 """Cache a main module's namespace.
1458 1489
1459 1490 When scripts are executed via %run, we must keep a reference to the
1460 1491 namespace of their __main__ module (a FakeModule instance) around so
1461 1492 that Python doesn't clear it, rendering objects defined therein
1462 1493 useless.
1463 1494
1464 1495 This method keeps said reference in a private dict, keyed by the
1465 1496 absolute path of the module object (which corresponds to the script
1466 1497 path). This way, for multiple executions of the same script we only
1467 1498 keep one copy of the namespace (the last one), thus preventing memory
1468 1499 leaks from old references while allowing the objects from the last
1469 1500 execution to be accessible.
1470 1501
1471 1502 Note: we can not allow the actual FakeModule instances to be deleted,
1472 1503 because of how Python tears down modules (it hard-sets all their
1473 1504 references to None without regard for reference counts). This method
1474 1505 must therefore make a *copy* of the given namespace, to allow the
1475 1506 original module's __dict__ to be cleared and reused.
1476 1507
1477 1508
1478 1509 Parameters
1479 1510 ----------
1480 1511 ns : a namespace (a dict, typically)
1481 1512
1482 1513 fname : str
1483 1514 Filename associated with the namespace.
1484 1515
1485 1516 Examples
1486 1517 --------
1487 1518
1488 1519 In [10]: import IPython
1489 1520
1490 1521 In [11]: _ip.IP.cache_main_mod(IPython.__dict__,IPython.__file__)
1491 1522
1492 1523 In [12]: IPython.__file__ in _ip.IP._main_ns_cache
1493 1524 Out[12]: True
1494 1525 """
1495 1526 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
1496 1527
1497 1528 def clear_main_mod_cache(self):
1498 1529 """Clear the cache of main modules.
1499 1530
1500 1531 Mainly for use by utilities like %reset.
1501 1532
1502 1533 Examples
1503 1534 --------
1504 1535
1505 1536 In [15]: import IPython
1506 1537
1507 1538 In [16]: _ip.IP.cache_main_mod(IPython.__dict__,IPython.__file__)
1508 1539
1509 1540 In [17]: len(_ip.IP._main_ns_cache) > 0
1510 1541 Out[17]: True
1511 1542
1512 1543 In [18]: _ip.IP.clear_main_mod_cache()
1513 1544
1514 1545 In [19]: len(_ip.IP._main_ns_cache) == 0
1515 1546 Out[19]: True
1516 1547 """
1517 1548 self._main_ns_cache.clear()
1518 1549
1519 1550 def _should_recompile(self,e):
1520 1551 """Utility routine for edit_syntax_error"""
1521 1552
1522 1553 if e.filename in ('<ipython console>','<input>','<string>',
1523 1554 '<console>','<BackgroundJob compilation>',
1524 1555 None):
1525 1556
1526 1557 return False
1527 1558 try:
1528 1559 if (self.autoedit_syntax and
1529 1560 not self.ask_yes_no('Return to editor to correct syntax error? '
1530 1561 '[Y/n] ','y')):
1531 1562 return False
1532 1563 except EOFError:
1533 1564 return False
1534 1565
1535 1566 def int0(x):
1536 1567 try:
1537 1568 return int(x)
1538 1569 except TypeError:
1539 1570 return 0
1540 1571 # always pass integer line and offset values to editor hook
1541 1572 try:
1542 1573 self.hooks.fix_error_editor(e.filename,
1543 1574 int0(e.lineno),int0(e.offset),e.msg)
1544 1575 except ipapi.TryNext:
1545 1576 warn('Could not open editor')
1546 1577 return False
1547 1578 return True
1548 1579
1549 1580 def edit_syntax_error(self):
1550 1581 """The bottom half of the syntax error handler called in the main loop.
1551 1582
1552 1583 Loop until syntax error is fixed or user cancels.
1553 1584 """
1554 1585
1555 1586 while self.SyntaxTB.last_syntax_error:
1556 1587 # copy and clear last_syntax_error
1557 1588 err = self.SyntaxTB.clear_err_state()
1558 1589 if not self._should_recompile(err):
1559 1590 return
1560 1591 try:
1561 1592 # may set last_syntax_error again if a SyntaxError is raised
1562 1593 self.safe_execfile(err.filename,self.user_ns)
1563 1594 except:
1564 1595 self.showtraceback()
1565 1596 else:
1566 1597 try:
1567 1598 f = file(err.filename)
1568 1599 try:
1569 1600 sys.displayhook(f.read())
1570 1601 finally:
1571 1602 f.close()
1572 1603 except:
1573 1604 self.showtraceback()
1574 1605
1575 1606 def showsyntaxerror(self, filename=None):
1576 1607 """Display the syntax error that just occurred.
1577 1608
1578 1609 This doesn't display a stack trace because there isn't one.
1579 1610
1580 1611 If a filename is given, it is stuffed in the exception instead
1581 1612 of what was there before (because Python's parser always uses
1582 1613 "<string>" when reading from a string).
1583 1614 """
1584 1615 etype, value, last_traceback = sys.exc_info()
1585 1616
1586 1617 # See note about these variables in showtraceback() below
1587 1618 sys.last_type = etype
1588 1619 sys.last_value = value
1589 1620 sys.last_traceback = last_traceback
1590 1621
1591 1622 if filename and etype is SyntaxError:
1592 1623 # Work hard to stuff the correct filename in the exception
1593 1624 try:
1594 1625 msg, (dummy_filename, lineno, offset, line) = value
1595 1626 except:
1596 1627 # Not the format we expect; leave it alone
1597 1628 pass
1598 1629 else:
1599 1630 # Stuff in the right filename
1600 1631 try:
1601 1632 # Assume SyntaxError is a class exception
1602 1633 value = SyntaxError(msg, (filename, lineno, offset, line))
1603 1634 except:
1604 1635 # If that failed, assume SyntaxError is a string
1605 1636 value = msg, (filename, lineno, offset, line)
1606 1637 self.SyntaxTB(etype,value,[])
1607 1638
1608 1639 def debugger(self,force=False):
1609 1640 """Call the pydb/pdb debugger.
1610 1641
1611 1642 Keywords:
1612 1643
1613 1644 - force(False): by default, this routine checks the instance call_pdb
1614 1645 flag and does not actually invoke the debugger if the flag is false.
1615 1646 The 'force' option forces the debugger to activate even if the flag
1616 1647 is false.
1617 1648 """
1618 1649
1619 1650 if not (force or self.call_pdb):
1620 1651 return
1621 1652
1622 1653 if not hasattr(sys,'last_traceback'):
1623 1654 error('No traceback has been produced, nothing to debug.')
1624 1655 return
1625 1656
1626 1657 # use pydb if available
1627 1658 if debugger.has_pydb:
1628 1659 from pydb import pm
1629 1660 else:
1630 1661 # fallback to our internal debugger
1631 1662 pm = lambda : self.InteractiveTB.debugger(force=True)
1632 1663 self.history_saving_wrapper(pm)()
1633 1664
1634 1665 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1635 1666 """Display the exception that just occurred.
1636 1667
1637 1668 If nothing is known about the exception, this is the method which
1638 1669 should be used throughout the code for presenting user tracebacks,
1639 1670 rather than directly invoking the InteractiveTB object.
1640 1671
1641 1672 A specific showsyntaxerror() also exists, but this method can take
1642 1673 care of calling it if needed, so unless you are explicitly catching a
1643 1674 SyntaxError exception, don't try to analyze the stack manually and
1644 1675 simply call this method."""
1645 1676
1646 1677
1647 1678 # Though this won't be called by syntax errors in the input line,
1648 1679 # there may be SyntaxError cases whith imported code.
1649 1680
1650 1681 try:
1651 1682 if exc_tuple is None:
1652 1683 etype, value, tb = sys.exc_info()
1653 1684 else:
1654 1685 etype, value, tb = exc_tuple
1655 1686
1656 1687 if etype is SyntaxError:
1657 1688 self.showsyntaxerror(filename)
1658 1689 elif etype is ipapi.UsageError:
1659 1690 print "UsageError:", value
1660 1691 else:
1661 1692 # WARNING: these variables are somewhat deprecated and not
1662 1693 # necessarily safe to use in a threaded environment, but tools
1663 1694 # like pdb depend on their existence, so let's set them. If we
1664 1695 # find problems in the field, we'll need to revisit their use.
1665 1696 sys.last_type = etype
1666 1697 sys.last_value = value
1667 1698 sys.last_traceback = tb
1668 1699
1669 1700 if etype in self.custom_exceptions:
1670 1701 self.CustomTB(etype,value,tb)
1671 1702 else:
1672 1703 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1673 1704 if self.InteractiveTB.call_pdb and self.has_readline:
1674 1705 # pdb mucks up readline, fix it back
1675 1706 self.set_completer()
1676 1707 except KeyboardInterrupt:
1677 1708 self.write("\nKeyboardInterrupt\n")
1678 1709
1679 1710 def mainloop(self, banner=None):
1680 1711 """Start the mainloop.
1681 1712
1682 1713 If an optional banner argument is given, it will override the
1683 1714 internally created default banner.
1684 1715 """
1685 1716 if self.c: # Emulate Python's -c option
1686 1717 self.exec_init_cmd()
1687 1718
1688 1719 if self.display_banner:
1689 1720 if banner is None:
1690 1721 banner = self.banner
1691 1722
1692 1723 # if you run stuff with -c <cmd>, raw hist is not updated
1693 1724 # ensure that it's in sync
1694 1725 if len(self.input_hist) != len (self.input_hist_raw):
1695 1726 self.input_hist_raw = InputList(self.input_hist)
1696 1727
1697 1728 while 1:
1698 1729 try:
1699 1730 self.interact()
1700 1731 #self.interact_with_readline()
1701 1732 # XXX for testing of a readline-decoupled repl loop, call
1702 1733 # interact_with_readline above
1703 1734 break
1704 1735 except KeyboardInterrupt:
1705 1736 # this should not be necessary, but KeyboardInterrupt
1706 1737 # handling seems rather unpredictable...
1707 1738 self.write("\nKeyboardInterrupt in interact()\n")
1708 1739
1709 1740 def exec_init_cmd(self):
1710 1741 """Execute a command given at the command line.
1711 1742
1712 1743 This emulates Python's -c option."""
1713 1744
1714 1745 #sys.argv = ['-c']
1715 1746 self.push(self.prefilter(self.c, False))
1716 1747 if not self.interactive:
1717 1748 self.ask_exit()
1718 1749
1719 1750 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1720 1751 """Embeds IPython into a running python program.
1721 1752
1722 1753 Input:
1723 1754
1724 1755 - header: An optional header message can be specified.
1725 1756
1726 1757 - local_ns, global_ns: working namespaces. If given as None, the
1727 1758 IPython-initialized one is updated with __main__.__dict__, so that
1728 1759 program variables become visible but user-specific configuration
1729 1760 remains possible.
1730 1761
1731 1762 - stack_depth: specifies how many levels in the stack to go to
1732 1763 looking for namespaces (when local_ns and global_ns are None). This
1733 1764 allows an intermediate caller to make sure that this function gets
1734 1765 the namespace from the intended level in the stack. By default (0)
1735 1766 it will get its locals and globals from the immediate caller.
1736 1767
1737 1768 Warning: it's possible to use this in a program which is being run by
1738 1769 IPython itself (via %run), but some funny things will happen (a few
1739 1770 globals get overwritten). In the future this will be cleaned up, as
1740 1771 there is no fundamental reason why it can't work perfectly."""
1741 1772
1742 1773 # Get locals and globals from caller
1743 1774 if local_ns is None or global_ns is None:
1744 1775 call_frame = sys._getframe(stack_depth).f_back
1745 1776
1746 1777 if local_ns is None:
1747 1778 local_ns = call_frame.f_locals
1748 1779 if global_ns is None:
1749 1780 global_ns = call_frame.f_globals
1750 1781
1751 1782 # Update namespaces and fire up interpreter
1752 1783
1753 1784 # The global one is easy, we can just throw it in
1754 1785 self.user_global_ns = global_ns
1755 1786
1756 1787 # but the user/local one is tricky: ipython needs it to store internal
1757 1788 # data, but we also need the locals. We'll copy locals in the user
1758 1789 # one, but will track what got copied so we can delete them at exit.
1759 1790 # This is so that a later embedded call doesn't see locals from a
1760 1791 # previous call (which most likely existed in a separate scope).
1761 1792 local_varnames = local_ns.keys()
1762 1793 self.user_ns.update(local_ns)
1763 1794 #self.user_ns['local_ns'] = local_ns # dbg
1764 1795
1765 1796 # Patch for global embedding to make sure that things don't overwrite
1766 1797 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1767 1798 # FIXME. Test this a bit more carefully (the if.. is new)
1768 1799 if local_ns is None and global_ns is None:
1769 1800 self.user_global_ns.update(__main__.__dict__)
1770 1801
1771 1802 # make sure the tab-completer has the correct frame information, so it
1772 1803 # actually completes using the frame's locals/globals
1773 1804 self.set_completer_frame()
1774 1805
1775 1806 # before activating the interactive mode, we need to make sure that
1776 1807 # all names in the builtin namespace needed by ipython point to
1777 1808 # ourselves, and not to other instances.
1778 1809 self.add_builtins()
1779 1810
1780 1811 self.interact(header)
1781 1812
1782 1813 # now, purge out the user namespace from anything we might have added
1783 1814 # from the caller's local namespace
1784 1815 delvar = self.user_ns.pop
1785 1816 for var in local_varnames:
1786 1817 delvar(var,None)
1787 1818 # and clean builtins we may have overridden
1788 1819 self.clean_builtins()
1789 1820
1790 1821 def interact_prompt(self):
1791 1822 """ Print the prompt (in read-eval-print loop)
1792 1823
1793 1824 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1794 1825 used in standard IPython flow.
1795 1826 """
1796 1827 if self.more:
1797 1828 try:
1798 1829 prompt = self.hooks.generate_prompt(True)
1799 1830 except:
1800 1831 self.showtraceback()
1801 1832 if self.autoindent:
1802 1833 self.rl_do_indent = True
1803 1834
1804 1835 else:
1805 1836 try:
1806 1837 prompt = self.hooks.generate_prompt(False)
1807 1838 except:
1808 1839 self.showtraceback()
1809 1840 self.write(prompt)
1810 1841
1811 1842 def interact_handle_input(self,line):
1812 1843 """ Handle the input line (in read-eval-print loop)
1813 1844
1814 1845 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1815 1846 used in standard IPython flow.
1816 1847 """
1817 1848 if line.lstrip() == line:
1818 1849 self.shadowhist.add(line.strip())
1819 1850 lineout = self.prefilter(line,self.more)
1820 1851
1821 1852 if line.strip():
1822 1853 if self.more:
1823 1854 self.input_hist_raw[-1] += '%s\n' % line
1824 1855 else:
1825 1856 self.input_hist_raw.append('%s\n' % line)
1826 1857
1827 1858
1828 1859 self.more = self.push(lineout)
1829 1860 if (self.SyntaxTB.last_syntax_error and
1830 1861 self.autoedit_syntax):
1831 1862 self.edit_syntax_error()
1832 1863
1833 1864 def interact_with_readline(self):
1834 1865 """ Demo of using interact_handle_input, interact_prompt
1835 1866
1836 1867 This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
1837 1868 it should work like this.
1838 1869 """
1839 1870 self.readline_startup_hook(self.pre_readline)
1840 1871 while not self.exit_now:
1841 1872 self.interact_prompt()
1842 1873 if self.more:
1843 1874 self.rl_do_indent = True
1844 1875 else:
1845 1876 self.rl_do_indent = False
1846 1877 line = raw_input_original().decode(self.stdin_encoding)
1847 1878 self.interact_handle_input(line)
1848 1879
1849 1880 def interact(self, banner=None):
1850 1881 """Closely emulate the interactive Python console."""
1851 1882
1852 1883 # batch run -> do not interact
1853 1884 if self.exit_now:
1854 1885 return
1855 1886
1856 1887 if self.display_banner:
1857 1888 if banner is None:
1858 1889 banner = self.banner
1859 1890 self.write(banner)
1860 1891
1861 1892 more = 0
1862 1893
1863 1894 # Mark activity in the builtins
1864 1895 __builtin__.__dict__['__IPYTHON__active'] += 1
1865 1896
1866 1897 if self.has_readline:
1867 1898 self.readline_startup_hook(self.pre_readline)
1868 1899 # exit_now is set by a call to %Exit or %Quit, through the
1869 1900 # ask_exit callback.
1870 1901
1871 1902 while not self.exit_now:
1872 1903 self.hooks.pre_prompt_hook()
1873 1904 if more:
1874 1905 try:
1875 1906 prompt = self.hooks.generate_prompt(True)
1876 1907 except:
1877 1908 self.showtraceback()
1878 1909 if self.autoindent:
1879 1910 self.rl_do_indent = True
1880 1911
1881 1912 else:
1882 1913 try:
1883 1914 prompt = self.hooks.generate_prompt(False)
1884 1915 except:
1885 1916 self.showtraceback()
1886 1917 try:
1887 1918 line = self.raw_input(prompt, more)
1888 1919 if self.exit_now:
1889 1920 # quick exit on sys.std[in|out] close
1890 1921 break
1891 1922 if self.autoindent:
1892 1923 self.rl_do_indent = False
1893 1924
1894 1925 except KeyboardInterrupt:
1895 1926 #double-guard against keyboardinterrupts during kbdint handling
1896 1927 try:
1897 1928 self.write('\nKeyboardInterrupt\n')
1898 1929 self.resetbuffer()
1899 1930 # keep cache in sync with the prompt counter:
1900 1931 self.outputcache.prompt_count -= 1
1901 1932
1902 1933 if self.autoindent:
1903 1934 self.indent_current_nsp = 0
1904 1935 more = 0
1905 1936 except KeyboardInterrupt:
1906 1937 pass
1907 1938 except EOFError:
1908 1939 if self.autoindent:
1909 1940 self.rl_do_indent = False
1910 1941 self.readline_startup_hook(None)
1911 1942 self.write('\n')
1912 1943 self.exit()
1913 1944 except bdb.BdbQuit:
1914 1945 warn('The Python debugger has exited with a BdbQuit exception.\n'
1915 1946 'Because of how pdb handles the stack, it is impossible\n'
1916 1947 'for IPython to properly format this particular exception.\n'
1917 1948 'IPython will resume normal operation.')
1918 1949 except:
1919 1950 # exceptions here are VERY RARE, but they can be triggered
1920 1951 # asynchronously by signal handlers, for example.
1921 1952 self.showtraceback()
1922 1953 else:
1923 1954 more = self.push(line)
1924 1955 if (self.SyntaxTB.last_syntax_error and
1925 1956 self.autoedit_syntax):
1926 1957 self.edit_syntax_error()
1927 1958
1928 1959 # We are off again...
1929 1960 __builtin__.__dict__['__IPYTHON__active'] -= 1
1930 1961
1931 1962 def excepthook(self, etype, value, tb):
1932 1963 """One more defense for GUI apps that call sys.excepthook.
1933 1964
1934 1965 GUI frameworks like wxPython trap exceptions and call
1935 1966 sys.excepthook themselves. I guess this is a feature that
1936 1967 enables them to keep running after exceptions that would
1937 1968 otherwise kill their mainloop. This is a bother for IPython
1938 1969 which excepts to catch all of the program exceptions with a try:
1939 1970 except: statement.
1940 1971
1941 1972 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1942 1973 any app directly invokes sys.excepthook, it will look to the user like
1943 1974 IPython crashed. In order to work around this, we can disable the
1944 1975 CrashHandler and replace it with this excepthook instead, which prints a
1945 1976 regular traceback using our InteractiveTB. In this fashion, apps which
1946 1977 call sys.excepthook will generate a regular-looking exception from
1947 1978 IPython, and the CrashHandler will only be triggered by real IPython
1948 1979 crashes.
1949 1980
1950 1981 This hook should be used sparingly, only in places which are not likely
1951 1982 to be true IPython errors.
1952 1983 """
1953 1984 self.showtraceback((etype,value,tb),tb_offset=0)
1954 1985
1955 1986 def expand_aliases(self,fn,rest):
1956 1987 """ Expand multiple levels of aliases:
1957 1988
1958 1989 if:
1959 1990
1960 1991 alias foo bar /tmp
1961 1992 alias baz foo
1962 1993
1963 1994 then:
1964 1995
1965 1996 baz huhhahhei -> bar /tmp huhhahhei
1966 1997
1967 1998 """
1968 1999 line = fn + " " + rest
1969 2000
1970 2001 done = set()
1971 2002 while 1:
1972 2003 pre,fn,rest = prefilter.splitUserInput(line,
1973 2004 prefilter.shell_line_split)
1974 2005 if fn in self.alias_table:
1975 2006 if fn in done:
1976 2007 warn("Cyclic alias definition, repeated '%s'" % fn)
1977 2008 return ""
1978 2009 done.add(fn)
1979 2010
1980 2011 l2 = self.transform_alias(fn,rest)
1981 2012 # dir -> dir
1982 2013 # print "alias",line, "->",l2 #dbg
1983 2014 if l2 == line:
1984 2015 break
1985 2016 # ls -> ls -F should not recurse forever
1986 2017 if l2.split(None,1)[0] == line.split(None,1)[0]:
1987 2018 line = l2
1988 2019 break
1989 2020
1990 2021 line=l2
1991 2022
1992 2023
1993 2024 # print "al expand to",line #dbg
1994 2025 else:
1995 2026 break
1996 2027
1997 2028 return line
1998 2029
1999 2030 def transform_alias(self, alias,rest=''):
2000 2031 """ Transform alias to system command string.
2001 2032 """
2002 2033 trg = self.alias_table[alias]
2003 2034
2004 2035 nargs,cmd = trg
2005 2036 # print trg #dbg
2006 2037 if ' ' in cmd and os.path.isfile(cmd):
2007 2038 cmd = '"%s"' % cmd
2008 2039
2009 2040 # Expand the %l special to be the user's input line
2010 2041 if cmd.find('%l') >= 0:
2011 2042 cmd = cmd.replace('%l',rest)
2012 2043 rest = ''
2013 2044 if nargs==0:
2014 2045 # Simple, argument-less aliases
2015 2046 cmd = '%s %s' % (cmd,rest)
2016 2047 else:
2017 2048 # Handle aliases with positional arguments
2018 2049 args = rest.split(None,nargs)
2019 2050 if len(args)< nargs:
2020 2051 error('Alias <%s> requires %s arguments, %s given.' %
2021 2052 (alias,nargs,len(args)))
2022 2053 return None
2023 2054 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
2024 2055 # Now call the macro, evaluating in the user's namespace
2025 2056 #print 'new command: <%r>' % cmd # dbg
2026 2057 return cmd
2027 2058
2028 2059 def call_alias(self,alias,rest=''):
2029 2060 """Call an alias given its name and the rest of the line.
2030 2061
2031 2062 This is only used to provide backwards compatibility for users of
2032 2063 ipalias(), use of which is not recommended for anymore."""
2033 2064
2034 2065 # Now call the macro, evaluating in the user's namespace
2035 2066 cmd = self.transform_alias(alias, rest)
2036 2067 try:
2037 2068 self.system(cmd)
2038 2069 except:
2039 2070 self.showtraceback()
2040 2071
2041 2072 def indent_current_str(self):
2042 2073 """return the current level of indentation as a string"""
2043 2074 return self.indent_current_nsp * ' '
2044 2075
2045 2076 def autoindent_update(self,line):
2046 2077 """Keep track of the indent level."""
2047 2078
2048 2079 #debugx('line')
2049 2080 #debugx('self.indent_current_nsp')
2050 2081 if self.autoindent:
2051 2082 if line:
2052 2083 inisp = num_ini_spaces(line)
2053 2084 if inisp < self.indent_current_nsp:
2054 2085 self.indent_current_nsp = inisp
2055 2086
2056 2087 if line[-1] == ':':
2057 2088 self.indent_current_nsp += 4
2058 2089 elif dedent_re.match(line):
2059 2090 self.indent_current_nsp -= 4
2060 2091 else:
2061 2092 self.indent_current_nsp = 0
2062 2093
2063 2094 def runlines(self,lines):
2064 2095 """Run a string of one or more lines of source.
2065 2096
2066 2097 This method is capable of running a string containing multiple source
2067 2098 lines, as if they had been entered at the IPython prompt. Since it
2068 2099 exposes IPython's processing machinery, the given strings can contain
2069 2100 magic calls (%magic), special shell access (!cmd), etc."""
2070 2101
2071 2102 # We must start with a clean buffer, in case this is run from an
2072 2103 # interactive IPython session (via a magic, for example).
2073 2104 self.resetbuffer()
2074 2105 lines = lines.split('\n')
2075 2106 more = 0
2076 2107
2077 2108 for line in lines:
2078 2109 # skip blank lines so we don't mess up the prompt counter, but do
2079 2110 # NOT skip even a blank line if we are in a code block (more is
2080 2111 # true)
2081 2112
2082 2113 if line or more:
2083 2114 # push to raw history, so hist line numbers stay in sync
2084 2115 self.input_hist_raw.append("# " + line + "\n")
2085 2116 more = self.push(self.prefilter(line,more))
2086 2117 # IPython's runsource returns None if there was an error
2087 2118 # compiling the code. This allows us to stop processing right
2088 2119 # away, so the user gets the error message at the right place.
2089 2120 if more is None:
2090 2121 break
2091 2122 else:
2092 2123 self.input_hist_raw.append("\n")
2093 2124 # final newline in case the input didn't have it, so that the code
2094 2125 # actually does get executed
2095 2126 if more:
2096 2127 self.push('\n')
2097 2128
2098 2129 def runsource(self, source, filename='<input>', symbol='single'):
2099 2130 """Compile and run some source in the interpreter.
2100 2131
2101 2132 Arguments are as for compile_command().
2102 2133
2103 2134 One several things can happen:
2104 2135
2105 2136 1) The input is incorrect; compile_command() raised an
2106 2137 exception (SyntaxError or OverflowError). A syntax traceback
2107 2138 will be printed by calling the showsyntaxerror() method.
2108 2139
2109 2140 2) The input is incomplete, and more input is required;
2110 2141 compile_command() returned None. Nothing happens.
2111 2142
2112 2143 3) The input is complete; compile_command() returned a code
2113 2144 object. The code is executed by calling self.runcode() (which
2114 2145 also handles run-time exceptions, except for SystemExit).
2115 2146
2116 2147 The return value is:
2117 2148
2118 2149 - True in case 2
2119 2150
2120 2151 - False in the other cases, unless an exception is raised, where
2121 2152 None is returned instead. This can be used by external callers to
2122 2153 know whether to continue feeding input or not.
2123 2154
2124 2155 The return value can be used to decide whether to use sys.ps1 or
2125 2156 sys.ps2 to prompt the next line."""
2126 2157
2127 2158 # if the source code has leading blanks, add 'if 1:\n' to it
2128 2159 # this allows execution of indented pasted code. It is tempting
2129 2160 # to add '\n' at the end of source to run commands like ' a=1'
2130 2161 # directly, but this fails for more complicated scenarios
2131 2162 source=source.encode(self.stdin_encoding)
2132 2163 if source[:1] in [' ', '\t']:
2133 2164 source = 'if 1:\n%s' % source
2134 2165
2135 2166 try:
2136 2167 code = self.compile(source,filename,symbol)
2137 2168 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2138 2169 # Case 1
2139 2170 self.showsyntaxerror(filename)
2140 2171 return None
2141 2172
2142 2173 if code is None:
2143 2174 # Case 2
2144 2175 return True
2145 2176
2146 2177 # Case 3
2147 2178 # We store the code object so that threaded shells and
2148 2179 # custom exception handlers can access all this info if needed.
2149 2180 # The source corresponding to this can be obtained from the
2150 2181 # buffer attribute as '\n'.join(self.buffer).
2151 2182 self.code_to_run = code
2152 2183 # now actually execute the code object
2153 2184 if self.runcode(code) == 0:
2154 2185 return False
2155 2186 else:
2156 2187 return None
2157 2188
2158 2189 def runcode(self,code_obj):
2159 2190 """Execute a code object.
2160 2191
2161 2192 When an exception occurs, self.showtraceback() is called to display a
2162 2193 traceback.
2163 2194
2164 2195 Return value: a flag indicating whether the code to be run completed
2165 2196 successfully:
2166 2197
2167 2198 - 0: successful execution.
2168 2199 - 1: an error occurred.
2169 2200 """
2170 2201
2171 2202 # Set our own excepthook in case the user code tries to call it
2172 2203 # directly, so that the IPython crash handler doesn't get triggered
2173 2204 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2174 2205
2175 2206 # we save the original sys.excepthook in the instance, in case config
2176 2207 # code (such as magics) needs access to it.
2177 2208 self.sys_excepthook = old_excepthook
2178 2209 outflag = 1 # happens in more places, so it's easier as default
2179 2210 try:
2180 2211 try:
2181 2212 self.hooks.pre_runcode_hook()
2182 2213 exec code_obj in self.user_global_ns, self.user_ns
2183 2214 finally:
2184 2215 # Reset our crash handler in place
2185 2216 sys.excepthook = old_excepthook
2186 2217 except SystemExit:
2187 2218 self.resetbuffer()
2188 2219 self.showtraceback()
2189 2220 warn("Type %exit or %quit to exit IPython "
2190 2221 "(%Exit or %Quit do so unconditionally).",level=1)
2191 2222 except self.custom_exceptions:
2192 2223 etype,value,tb = sys.exc_info()
2193 2224 self.CustomTB(etype,value,tb)
2194 2225 except:
2195 2226 self.showtraceback()
2196 2227 else:
2197 2228 outflag = 0
2198 2229 if softspace(sys.stdout, 0):
2199 2230 print
2200 2231 # Flush out code object which has been run (and source)
2201 2232 self.code_to_run = None
2202 2233 return outflag
2203 2234
2204 2235 def push(self, line):
2205 2236 """Push a line to the interpreter.
2206 2237
2207 2238 The line should not have a trailing newline; it may have
2208 2239 internal newlines. The line is appended to a buffer and the
2209 2240 interpreter's runsource() method is called with the
2210 2241 concatenated contents of the buffer as source. If this
2211 2242 indicates that the command was executed or invalid, the buffer
2212 2243 is reset; otherwise, the command is incomplete, and the buffer
2213 2244 is left as it was after the line was appended. The return
2214 2245 value is 1 if more input is required, 0 if the line was dealt
2215 2246 with in some way (this is the same as runsource()).
2216 2247 """
2217 2248
2218 2249 # autoindent management should be done here, and not in the
2219 2250 # interactive loop, since that one is only seen by keyboard input. We
2220 2251 # need this done correctly even for code run via runlines (which uses
2221 2252 # push).
2222 2253
2223 2254 #print 'push line: <%s>' % line # dbg
2224 2255 for subline in line.splitlines():
2225 2256 self.autoindent_update(subline)
2226 2257 self.buffer.append(line)
2227 2258 more = self.runsource('\n'.join(self.buffer), self.filename)
2228 2259 if not more:
2229 2260 self.resetbuffer()
2230 2261 return more
2231 2262
2232 2263 def split_user_input(self, line):
2233 2264 # This is really a hold-over to support ipapi and some extensions
2234 2265 return prefilter.splitUserInput(line)
2235 2266
2236 2267 def resetbuffer(self):
2237 2268 """Reset the input buffer."""
2238 2269 self.buffer[:] = []
2239 2270
2240 2271 def raw_input(self,prompt='',continue_prompt=False):
2241 2272 """Write a prompt and read a line.
2242 2273
2243 2274 The returned line does not include the trailing newline.
2244 2275 When the user enters the EOF key sequence, EOFError is raised.
2245 2276
2246 2277 Optional inputs:
2247 2278
2248 2279 - prompt(''): a string to be printed to prompt the user.
2249 2280
2250 2281 - continue_prompt(False): whether this line is the first one or a
2251 2282 continuation in a sequence of inputs.
2252 2283 """
2253 2284
2254 2285 # Code run by the user may have modified the readline completer state.
2255 2286 # We must ensure that our completer is back in place.
2256 2287 if self.has_readline:
2257 2288 self.set_completer()
2258 2289
2259 2290 try:
2260 2291 line = raw_input_original(prompt).decode(self.stdin_encoding)
2261 2292 except ValueError:
2262 2293 warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
2263 2294 " or sys.stdout.close()!\nExiting IPython!")
2264 2295 self.ask_exit()
2265 2296 return ""
2266 2297
2267 2298 # Try to be reasonably smart about not re-indenting pasted input more
2268 2299 # than necessary. We do this by trimming out the auto-indent initial
2269 2300 # spaces, if the user's actual input started itself with whitespace.
2270 2301 #debugx('self.buffer[-1]')
2271 2302
2272 2303 if self.autoindent:
2273 2304 if num_ini_spaces(line) > self.indent_current_nsp:
2274 2305 line = line[self.indent_current_nsp:]
2275 2306 self.indent_current_nsp = 0
2276 2307
2277 2308 # store the unfiltered input before the user has any chance to modify
2278 2309 # it.
2279 2310 if line.strip():
2280 2311 if continue_prompt:
2281 2312 self.input_hist_raw[-1] += '%s\n' % line
2282 2313 if self.has_readline: # and some config option is set?
2283 2314 try:
2284 2315 histlen = self.readline.get_current_history_length()
2285 2316 if histlen > 1:
2286 2317 newhist = self.input_hist_raw[-1].rstrip()
2287 2318 self.readline.remove_history_item(histlen-1)
2288 2319 self.readline.replace_history_item(histlen-2,
2289 2320 newhist.encode(self.stdin_encoding))
2290 2321 except AttributeError:
2291 2322 pass # re{move,place}_history_item are new in 2.4.
2292 2323 else:
2293 2324 self.input_hist_raw.append('%s\n' % line)
2294 2325 # only entries starting at first column go to shadow history
2295 2326 if line.lstrip() == line:
2296 2327 self.shadowhist.add(line.strip())
2297 2328 elif not continue_prompt:
2298 2329 self.input_hist_raw.append('\n')
2299 2330 try:
2300 2331 lineout = self.prefilter(line,continue_prompt)
2301 2332 except:
2302 2333 # blanket except, in case a user-defined prefilter crashes, so it
2303 2334 # can't take all of ipython with it.
2304 2335 self.showtraceback()
2305 2336 return ''
2306 2337 else:
2307 2338 return lineout
2308 2339
2309 2340 def _prefilter(self, line, continue_prompt):
2310 2341 """Calls different preprocessors, depending on the form of line."""
2311 2342
2312 2343 # All handlers *must* return a value, even if it's blank ('').
2313 2344
2314 2345 # Lines are NOT logged here. Handlers should process the line as
2315 2346 # needed, update the cache AND log it (so that the input cache array
2316 2347 # stays synced).
2317 2348
2318 2349 #.....................................................................
2319 2350 # Code begins
2320 2351
2321 2352 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
2322 2353
2323 2354 # save the line away in case we crash, so the post-mortem handler can
2324 2355 # record it
2325 2356 self._last_input_line = line
2326 2357
2327 2358 #print '***line: <%s>' % line # dbg
2328 2359
2329 2360 if not line:
2330 2361 # Return immediately on purely empty lines, so that if the user
2331 2362 # previously typed some whitespace that started a continuation
2332 2363 # prompt, he can break out of that loop with just an empty line.
2333 2364 # This is how the default python prompt works.
2334 2365
2335 2366 # Only return if the accumulated input buffer was just whitespace!
2336 2367 if ''.join(self.buffer).isspace():
2337 2368 self.buffer[:] = []
2338 2369 return ''
2339 2370
2340 2371 line_info = prefilter.LineInfo(line, continue_prompt)
2341 2372
2342 2373 # the input history needs to track even empty lines
2343 2374 stripped = line.strip()
2344 2375
2345 2376 if not stripped:
2346 2377 if not continue_prompt:
2347 2378 self.outputcache.prompt_count -= 1
2348 2379 return self.handle_normal(line_info)
2349 2380
2350 2381 # print '***cont',continue_prompt # dbg
2351 2382 # special handlers are only allowed for single line statements
2352 2383 if continue_prompt and not self.multi_line_specials:
2353 2384 return self.handle_normal(line_info)
2354 2385
2355 2386
2356 2387 # See whether any pre-existing handler can take care of it
2357 2388 rewritten = self.hooks.input_prefilter(stripped)
2358 2389 if rewritten != stripped: # ok, some prefilter did something
2359 2390 rewritten = line_info.pre + rewritten # add indentation
2360 2391 return self.handle_normal(prefilter.LineInfo(rewritten,
2361 2392 continue_prompt))
2362 2393
2363 2394 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2364 2395
2365 2396 return prefilter.prefilter(line_info, self)
2366 2397
2367 2398
2368 2399 def _prefilter_dumb(self, line, continue_prompt):
2369 2400 """simple prefilter function, for debugging"""
2370 2401 return self.handle_normal(line,continue_prompt)
2371 2402
2372 2403
2373 2404 def multiline_prefilter(self, line, continue_prompt):
2374 2405 """ Run _prefilter for each line of input
2375 2406
2376 2407 Covers cases where there are multiple lines in the user entry,
2377 2408 which is the case when the user goes back to a multiline history
2378 2409 entry and presses enter.
2379 2410
2380 2411 """
2381 2412 out = []
2382 2413 for l in line.rstrip('\n').split('\n'):
2383 2414 out.append(self._prefilter(l, continue_prompt))
2384 2415 return '\n'.join(out)
2385 2416
2386 2417 # Set the default prefilter() function (this can be user-overridden)
2387 2418 prefilter = multiline_prefilter
2388 2419
2389 2420 def handle_normal(self,line_info):
2390 2421 """Handle normal input lines. Use as a template for handlers."""
2391 2422
2392 2423 # With autoindent on, we need some way to exit the input loop, and I
2393 2424 # don't want to force the user to have to backspace all the way to
2394 2425 # clear the line. The rule will be in this case, that either two
2395 2426 # lines of pure whitespace in a row, or a line of pure whitespace but
2396 2427 # of a size different to the indent level, will exit the input loop.
2397 2428 line = line_info.line
2398 2429 continue_prompt = line_info.continue_prompt
2399 2430
2400 2431 if (continue_prompt and self.autoindent and line.isspace() and
2401 2432 (0 < abs(len(line) - self.indent_current_nsp) <= 2 or
2402 2433 (self.buffer[-1]).isspace() )):
2403 2434 line = ''
2404 2435
2405 2436 self.log(line,line,continue_prompt)
2406 2437 return line
2407 2438
2408 2439 def handle_alias(self,line_info):
2409 2440 """Handle alias input lines. """
2410 2441 tgt = self.alias_table[line_info.iFun]
2411 2442 # print "=>",tgt #dbg
2412 2443 if callable(tgt):
2413 2444 if '$' in line_info.line:
2414 2445 call_meth = '(_ip, _ip.itpl(%s))'
2415 2446 else:
2416 2447 call_meth = '(_ip,%s)'
2417 2448 line_out = ("%s_sh.%s" + call_meth) % (line_info.preWhitespace,
2418 2449 line_info.iFun,
2419 2450 make_quoted_expr(line_info.line))
2420 2451 else:
2421 2452 transformed = self.expand_aliases(line_info.iFun,line_info.theRest)
2422 2453
2423 2454 # pre is needed, because it carries the leading whitespace. Otherwise
2424 2455 # aliases won't work in indented sections.
2425 2456 line_out = '%s_ip.system(%s)' % (line_info.preWhitespace,
2426 2457 make_quoted_expr( transformed ))
2427 2458
2428 2459 self.log(line_info.line,line_out,line_info.continue_prompt)
2429 2460 #print 'line out:',line_out # dbg
2430 2461 return line_out
2431 2462
2432 2463 def handle_shell_escape(self, line_info):
2433 2464 """Execute the line in a shell, empty return value"""
2434 2465 #print 'line in :', `line` # dbg
2435 2466 line = line_info.line
2436 2467 if line.lstrip().startswith('!!'):
2437 2468 # rewrite LineInfo's line, iFun and theRest to properly hold the
2438 2469 # call to %sx and the actual command to be executed, so
2439 2470 # handle_magic can work correctly. Note that this works even if
2440 2471 # the line is indented, so it handles multi_line_specials
2441 2472 # properly.
2442 2473 new_rest = line.lstrip()[2:]
2443 2474 line_info.line = '%ssx %s' % (self.ESC_MAGIC,new_rest)
2444 2475 line_info.iFun = 'sx'
2445 2476 line_info.theRest = new_rest
2446 2477 return self.handle_magic(line_info)
2447 2478 else:
2448 2479 cmd = line.lstrip().lstrip('!')
2449 2480 line_out = '%s_ip.system(%s)' % (line_info.preWhitespace,
2450 2481 make_quoted_expr(cmd))
2451 2482 # update cache/log and return
2452 2483 self.log(line,line_out,line_info.continue_prompt)
2453 2484 return line_out
2454 2485
2455 2486 def handle_magic(self, line_info):
2456 2487 """Execute magic functions."""
2457 2488 iFun = line_info.iFun
2458 2489 theRest = line_info.theRest
2459 2490 cmd = '%s_ip.magic(%s)' % (line_info.preWhitespace,
2460 2491 make_quoted_expr(iFun + " " + theRest))
2461 2492 self.log(line_info.line,cmd,line_info.continue_prompt)
2462 2493 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
2463 2494 return cmd
2464 2495
2465 2496 def handle_auto(self, line_info):
2466 2497 """Hande lines which can be auto-executed, quoting if requested."""
2467 2498
2468 2499 line = line_info.line
2469 2500 iFun = line_info.iFun
2470 2501 theRest = line_info.theRest
2471 2502 pre = line_info.pre
2472 2503 continue_prompt = line_info.continue_prompt
2473 2504 obj = line_info.ofind(self)['obj']
2474 2505
2475 2506 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2476 2507
2477 2508 # This should only be active for single-line input!
2478 2509 if continue_prompt:
2479 2510 self.log(line,line,continue_prompt)
2480 2511 return line
2481 2512
2482 2513 force_auto = isinstance(obj, ipapi.IPyAutocall)
2483 2514 auto_rewrite = True
2484 2515
2485 2516 if pre == self.ESC_QUOTE:
2486 2517 # Auto-quote splitting on whitespace
2487 2518 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
2488 2519 elif pre == self.ESC_QUOTE2:
2489 2520 # Auto-quote whole string
2490 2521 newcmd = '%s("%s")' % (iFun,theRest)
2491 2522 elif pre == self.ESC_PAREN:
2492 2523 newcmd = '%s(%s)' % (iFun,",".join(theRest.split()))
2493 2524 else:
2494 2525 # Auto-paren.
2495 2526 # We only apply it to argument-less calls if the autocall
2496 2527 # parameter is set to 2. We only need to check that autocall is <
2497 2528 # 2, since this function isn't called unless it's at least 1.
2498 2529 if not theRest and (self.autocall < 2) and not force_auto:
2499 2530 newcmd = '%s %s' % (iFun,theRest)
2500 2531 auto_rewrite = False
2501 2532 else:
2502 2533 if not force_auto and theRest.startswith('['):
2503 2534 if hasattr(obj,'__getitem__'):
2504 2535 # Don't autocall in this case: item access for an object
2505 2536 # which is BOTH callable and implements __getitem__.
2506 2537 newcmd = '%s %s' % (iFun,theRest)
2507 2538 auto_rewrite = False
2508 2539 else:
2509 2540 # if the object doesn't support [] access, go ahead and
2510 2541 # autocall
2511 2542 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
2512 2543 elif theRest.endswith(';'):
2513 2544 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
2514 2545 else:
2515 2546 newcmd = '%s(%s)' % (iFun.rstrip(), theRest)
2516 2547
2517 2548 if auto_rewrite:
2518 2549 rw = self.outputcache.prompt1.auto_rewrite() + newcmd
2519 2550
2520 2551 try:
2521 2552 # plain ascii works better w/ pyreadline, on some machines, so
2522 2553 # we use it and only print uncolored rewrite if we have unicode
2523 2554 rw = str(rw)
2524 2555 print >>Term.cout, rw
2525 2556 except UnicodeEncodeError:
2526 2557 print "-------------->" + newcmd
2527 2558
2528 2559 # log what is now valid Python, not the actual user input (without the
2529 2560 # final newline)
2530 2561 self.log(line,newcmd,continue_prompt)
2531 2562 return newcmd
2532 2563
2533 2564 def handle_help(self, line_info):
2534 2565 """Try to get some help for the object.
2535 2566
2536 2567 obj? or ?obj -> basic information.
2537 2568 obj?? or ??obj -> more details.
2538 2569 """
2539 2570
2540 2571 line = line_info.line
2541 2572 # We need to make sure that we don't process lines which would be
2542 2573 # otherwise valid python, such as "x=1 # what?"
2543 2574 try:
2544 2575 codeop.compile_command(line)
2545 2576 except SyntaxError:
2546 2577 # We should only handle as help stuff which is NOT valid syntax
2547 2578 if line[0]==self.ESC_HELP:
2548 2579 line = line[1:]
2549 2580 elif line[-1]==self.ESC_HELP:
2550 2581 line = line[:-1]
2551 2582 self.log(line,'#?'+line,line_info.continue_prompt)
2552 2583 if line:
2553 2584 #print 'line:<%r>' % line # dbg
2554 2585 self.magic_pinfo(line)
2555 2586 else:
2556 2587 page(self.usage,screen_lines=self.usable_screen_length)
2557 2588 return '' # Empty string is needed here!
2558 2589 except:
2559 2590 # Pass any other exceptions through to the normal handler
2560 2591 return self.handle_normal(line_info)
2561 2592 else:
2562 2593 # If the code compiles ok, we should handle it normally
2563 2594 return self.handle_normal(line_info)
2564 2595
2565 2596 def getapi(self):
2566 2597 """ Get an IPApi object for this shell instance
2567 2598
2568 2599 Getting an IPApi object is always preferable to accessing the shell
2569 2600 directly, but this holds true especially for extensions.
2570 2601
2571 2602 It should always be possible to implement an extension with IPApi
2572 2603 alone. If not, contact maintainer to request an addition.
2573 2604
2574 2605 """
2575 2606 return self.api
2576 2607
2577 2608 def handle_emacs(self, line_info):
2578 2609 """Handle input lines marked by python-mode."""
2579 2610
2580 2611 # Currently, nothing is done. Later more functionality can be added
2581 2612 # here if needed.
2582 2613
2583 2614 # The input cache shouldn't be updated
2584 2615 return line_info.line
2585 2616
2586 2617 def var_expand(self,cmd,depth=0):
2587 2618 """Expand python variables in a string.
2588 2619
2589 2620 The depth argument indicates how many frames above the caller should
2590 2621 be walked to look for the local namespace where to expand variables.
2591 2622
2592 2623 The global namespace for expansion is always the user's interactive
2593 2624 namespace.
2594 2625 """
2595 2626
2596 2627 return str(ItplNS(cmd,
2597 2628 self.user_ns, # globals
2598 2629 # Skip our own frame in searching for locals:
2599 2630 sys._getframe(depth+1).f_locals # locals
2600 2631 ))
2601 2632
2602 2633 def mktempfile(self,data=None):
2603 2634 """Make a new tempfile and return its filename.
2604 2635
2605 2636 This makes a call to tempfile.mktemp, but it registers the created
2606 2637 filename internally so ipython cleans it up at exit time.
2607 2638
2608 2639 Optional inputs:
2609 2640
2610 2641 - data(None): if data is given, it gets written out to the temp file
2611 2642 immediately, and the file is closed again."""
2612 2643
2613 2644 filename = tempfile.mktemp('.py','ipython_edit_')
2614 2645 self.tempfiles.append(filename)
2615 2646
2616 2647 if data:
2617 2648 tmp_file = open(filename,'w')
2618 2649 tmp_file.write(data)
2619 2650 tmp_file.close()
2620 2651 return filename
2621 2652
2622 2653 def write(self,data):
2623 2654 """Write a string to the default output"""
2624 2655 Term.cout.write(data)
2625 2656
2626 2657 def write_err(self,data):
2627 2658 """Write a string to the default error output"""
2628 2659 Term.cerr.write(data)
2629 2660
2630 2661 def ask_exit(self):
2631 2662 """ Call for exiting. Can be overiden and used as a callback. """
2632 2663 self.exit_now = True
2633 2664
2634 2665 def exit(self):
2635 2666 """Handle interactive exit.
2636 2667
2637 2668 This method calls the ask_exit callback."""
2638 2669 if self.confirm_exit:
2639 2670 if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2640 2671 self.ask_exit()
2641 2672 else:
2642 2673 self.ask_exit()
2643 2674
2644 2675 def safe_execfile(self,fname,*where,**kw):
2645 2676 """A safe version of the builtin execfile().
2646 2677
2647 2678 This version will never throw an exception, and knows how to handle
2648 2679 ipython logs as well.
2649 2680
2650 2681 :Parameters:
2651 2682 fname : string
2652 2683 Name of the file to be executed.
2653 2684
2654 2685 where : tuple
2655 2686 One or two namespaces, passed to execfile() as (globals,locals).
2656 2687 If only one is given, it is passed as both.
2657 2688
2658 2689 :Keywords:
2659 2690 islog : boolean (False)
2660 2691
2661 2692 quiet : boolean (True)
2662 2693
2663 2694 exit_ignore : boolean (False)
2664 2695 """
2665 2696
2666 2697 def syspath_cleanup():
2667 2698 """Internal cleanup routine for sys.path."""
2668 2699 if add_dname:
2669 2700 try:
2670 2701 sys.path.remove(dname)
2671 2702 except ValueError:
2672 2703 # For some reason the user has already removed it, ignore.
2673 2704 pass
2674 2705
2675 2706 fname = os.path.expanduser(fname)
2676 2707
2677 2708 # Find things also in current directory. This is needed to mimic the
2678 2709 # behavior of running a script from the system command line, where
2679 2710 # Python inserts the script's directory into sys.path
2680 2711 dname = os.path.dirname(os.path.abspath(fname))
2681 2712 add_dname = False
2682 2713 if dname not in sys.path:
2683 2714 sys.path.insert(0,dname)
2684 2715 add_dname = True
2685 2716
2686 2717 try:
2687 2718 xfile = open(fname)
2688 2719 except:
2689 2720 print >> Term.cerr, \
2690 2721 'Could not open file <%s> for safe execution.' % fname
2691 2722 syspath_cleanup()
2692 2723 return None
2693 2724
2694 2725 kw.setdefault('islog',0)
2695 2726 kw.setdefault('quiet',1)
2696 2727 kw.setdefault('exit_ignore',0)
2697 2728
2698 2729 first = xfile.readline()
2699 2730 loghead = str(self.loghead_tpl).split('\n',1)[0].strip()
2700 2731 xfile.close()
2701 2732 # line by line execution
2702 2733 if first.startswith(loghead) or kw['islog']:
2703 2734 print 'Loading log file <%s> one line at a time...' % fname
2704 2735 if kw['quiet']:
2705 2736 stdout_save = sys.stdout
2706 2737 sys.stdout = StringIO.StringIO()
2707 2738 try:
2708 2739 globs,locs = where[0:2]
2709 2740 except:
2710 2741 try:
2711 2742 globs = locs = where[0]
2712 2743 except:
2713 2744 globs = locs = globals()
2714 2745 badblocks = []
2715 2746
2716 2747 # we also need to identify indented blocks of code when replaying
2717 2748 # logs and put them together before passing them to an exec
2718 2749 # statement. This takes a bit of regexp and look-ahead work in the
2719 2750 # file. It's easiest if we swallow the whole thing in memory
2720 2751 # first, and manually walk through the lines list moving the
2721 2752 # counter ourselves.
2722 2753 indent_re = re.compile('\s+\S')
2723 2754 xfile = open(fname)
2724 2755 filelines = xfile.readlines()
2725 2756 xfile.close()
2726 2757 nlines = len(filelines)
2727 2758 lnum = 0
2728 2759 while lnum < nlines:
2729 2760 line = filelines[lnum]
2730 2761 lnum += 1
2731 2762 # don't re-insert logger status info into cache
2732 2763 if line.startswith('#log#'):
2733 2764 continue
2734 2765 else:
2735 2766 # build a block of code (maybe a single line) for execution
2736 2767 block = line
2737 2768 try:
2738 2769 next = filelines[lnum] # lnum has already incremented
2739 2770 except:
2740 2771 next = None
2741 2772 while next and indent_re.match(next):
2742 2773 block += next
2743 2774 lnum += 1
2744 2775 try:
2745 2776 next = filelines[lnum]
2746 2777 except:
2747 2778 next = None
2748 2779 # now execute the block of one or more lines
2749 2780 try:
2750 2781 exec block in globs,locs
2751 2782 except SystemExit:
2752 2783 pass
2753 2784 except:
2754 2785 badblocks.append(block.rstrip())
2755 2786 if kw['quiet']: # restore stdout
2756 2787 sys.stdout.close()
2757 2788 sys.stdout = stdout_save
2758 2789 print 'Finished replaying log file <%s>' % fname
2759 2790 if badblocks:
2760 2791 print >> sys.stderr, ('\nThe following lines/blocks in file '
2761 2792 '<%s> reported errors:' % fname)
2762 2793
2763 2794 for badline in badblocks:
2764 2795 print >> sys.stderr, badline
2765 2796 else: # regular file execution
2766 2797 try:
2767 2798 if sys.platform == 'win32' and sys.version_info < (2,5,1):
2768 2799 # Work around a bug in Python for Windows. The bug was
2769 2800 # fixed in in Python 2.5 r54159 and 54158, but that's still
2770 2801 # SVN Python as of March/07. For details, see:
2771 2802 # http://projects.scipy.org/ipython/ipython/ticket/123
2772 2803 try:
2773 2804 globs,locs = where[0:2]
2774 2805 except:
2775 2806 try:
2776 2807 globs = locs = where[0]
2777 2808 except:
2778 2809 globs = locs = globals()
2779 2810 exec file(fname) in globs,locs
2780 2811 else:
2781 2812 execfile(fname,*where)
2782 2813 except SyntaxError:
2783 2814 self.showsyntaxerror()
2784 2815 warn('Failure executing file: <%s>' % fname)
2785 2816 except SystemExit,status:
2786 2817 # Code that correctly sets the exit status flag to success (0)
2787 2818 # shouldn't be bothered with a traceback. Note that a plain
2788 2819 # sys.exit() does NOT set the message to 0 (it's empty) so that
2789 2820 # will still get a traceback. Note that the structure of the
2790 2821 # SystemExit exception changed between Python 2.4 and 2.5, so
2791 2822 # the checks must be done in a version-dependent way.
2792 2823 show = False
2793 2824
2794 2825 if sys.version_info[:2] > (2,5):
2795 2826 if status.message!=0 and not kw['exit_ignore']:
2796 2827 show = True
2797 2828 else:
2798 2829 if status.code and not kw['exit_ignore']:
2799 2830 show = True
2800 2831 if show:
2801 2832 self.showtraceback()
2802 2833 warn('Failure executing file: <%s>' % fname)
2803 2834 except:
2804 2835 self.showtraceback()
2805 2836 warn('Failure executing file: <%s>' % fname)
2806 2837
2807 2838 syspath_cleanup()
2808 2839
2809 2840 #************************* end of file <iplib.py> *****************************
@@ -1,3588 +1,3587 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Magic functions for InteractiveShell.
3 3 """
4 4
5 5 #*****************************************************************************
6 6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
8 8 #
9 9 # Distributed under the terms of the BSD License. The full license is in
10 10 # the file COPYING, distributed as part of this software.
11 11 #*****************************************************************************
12 12
13 13 #****************************************************************************
14 14 # Modules and globals
15 15
16 16 # Python standard modules
17 17 import __builtin__
18 18 import bdb
19 19 import inspect
20 20 import os
21 21 import pdb
22 22 import pydoc
23 23 import sys
24 24 import re
25 25 import tempfile
26 26 import time
27 27 import cPickle as pickle
28 28 import textwrap
29 29 from cStringIO import StringIO
30 30 from getopt import getopt,GetoptError
31 31 from pprint import pprint, pformat
32 32
33 33 # cProfile was added in Python2.5
34 34 try:
35 35 import cProfile as profile
36 36 import pstats
37 37 except ImportError:
38 38 # profile isn't bundled by default in Debian for license reasons
39 39 try:
40 40 import profile,pstats
41 41 except ImportError:
42 42 profile = pstats = None
43 43
44 44 # Homebrewed
45 45 import IPython
46 46 from IPython.utils import wildcard
47 47 from IPython.core import debugger, oinspect
48 48 from IPython.core.fakemodule import FakeModule
49 49 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
50 50 from IPython.utils.PyColorize import Parser
51 51 from IPython.utils.ipstruct import Struct
52 52 from IPython.core.macro import Macro
53 53 from IPython.utils.genutils import *
54 54 from IPython.utils import platutils
55 55 import IPython.utils.generics
56 56 from IPython.core import ipapi
57 57 from IPython.core.ipapi import UsageError
58 58 from IPython.testing import decorators as testdec
59 59
60 60 #***************************************************************************
61 61 # Utility functions
62 62 def on_off(tag):
63 63 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
64 64 return ['OFF','ON'][tag]
65 65
66 66 class Bunch: pass
67 67
68 68 def compress_dhist(dh):
69 69 head, tail = dh[:-10], dh[-10:]
70 70
71 71 newhead = []
72 72 done = set()
73 73 for h in head:
74 74 if h in done:
75 75 continue
76 76 newhead.append(h)
77 77 done.add(h)
78 78
79 79 return newhead + tail
80 80
81 81
82 82 #***************************************************************************
83 83 # Main class implementing Magic functionality
84 84 class Magic:
85 85 """Magic functions for InteractiveShell.
86 86
87 87 Shell functions which can be reached as %function_name. All magic
88 88 functions should accept a string, which they can parse for their own
89 89 needs. This can make some functions easier to type, eg `%cd ../`
90 90 vs. `%cd("../")`
91 91
92 92 ALL definitions MUST begin with the prefix magic_. The user won't need it
93 93 at the command line, but it is is needed in the definition. """
94 94
95 95 # class globals
96 96 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
97 97 'Automagic is ON, % prefix NOT needed for magic functions.']
98 98
99 99 #......................................................................
100 100 # some utility functions
101 101
102 102 def __init__(self,shell):
103 103
104 104 self.options_table = {}
105 105 if profile is None:
106 106 self.magic_prun = self.profile_missing_notice
107 107 self.shell = shell
108 108
109 109 # namespace for holding state we may need
110 110 self._magic_state = Bunch()
111 111
112 112 def profile_missing_notice(self, *args, **kwargs):
113 113 error("""\
114 114 The profile module could not be found. It has been removed from the standard
115 115 python packages because of its non-free license. To use profiling, install the
116 116 python-profiler package from non-free.""")
117 117
118 118 def default_option(self,fn,optstr):
119 119 """Make an entry in the options_table for fn, with value optstr"""
120 120
121 121 if fn not in self.lsmagic():
122 122 error("%s is not a magic function" % fn)
123 123 self.options_table[fn] = optstr
124 124
125 125 def lsmagic(self):
126 126 """Return a list of currently available magic functions.
127 127
128 128 Gives a list of the bare names after mangling (['ls','cd', ...], not
129 129 ['magic_ls','magic_cd',...]"""
130 130
131 131 # FIXME. This needs a cleanup, in the way the magics list is built.
132 132
133 133 # magics in class definition
134 134 class_magic = lambda fn: fn.startswith('magic_') and \
135 135 callable(Magic.__dict__[fn])
136 136 # in instance namespace (run-time user additions)
137 137 inst_magic = lambda fn: fn.startswith('magic_') and \
138 138 callable(self.__dict__[fn])
139 139 # and bound magics by user (so they can access self):
140 140 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
141 141 callable(self.__class__.__dict__[fn])
142 142 magics = filter(class_magic,Magic.__dict__.keys()) + \
143 143 filter(inst_magic,self.__dict__.keys()) + \
144 144 filter(inst_bound_magic,self.__class__.__dict__.keys())
145 145 out = []
146 146 for fn in set(magics):
147 147 out.append(fn.replace('magic_','',1))
148 148 out.sort()
149 149 return out
150 150
151 151 def extract_input_slices(self,slices,raw=False):
152 152 """Return as a string a set of input history slices.
153 153
154 154 Inputs:
155 155
156 156 - slices: the set of slices is given as a list of strings (like
157 157 ['1','4:8','9'], since this function is for use by magic functions
158 158 which get their arguments as strings.
159 159
160 160 Optional inputs:
161 161
162 162 - raw(False): by default, the processed input is used. If this is
163 163 true, the raw input history is used instead.
164 164
165 165 Note that slices can be called with two notations:
166 166
167 167 N:M -> standard python form, means including items N...(M-1).
168 168
169 169 N-M -> include items N..M (closed endpoint)."""
170 170
171 171 if raw:
172 172 hist = self.shell.input_hist_raw
173 173 else:
174 174 hist = self.shell.input_hist
175 175
176 176 cmds = []
177 177 for chunk in slices:
178 178 if ':' in chunk:
179 179 ini,fin = map(int,chunk.split(':'))
180 180 elif '-' in chunk:
181 181 ini,fin = map(int,chunk.split('-'))
182 182 fin += 1
183 183 else:
184 184 ini = int(chunk)
185 185 fin = ini+1
186 186 cmds.append(hist[ini:fin])
187 187 return cmds
188 188
189 189 def _ofind(self, oname, namespaces=None):
190 190 """Find an object in the available namespaces.
191 191
192 192 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
193 193
194 194 Has special code to detect magic functions.
195 195 """
196 196
197 197 oname = oname.strip()
198 198
199 199 alias_ns = None
200 200 if namespaces is None:
201 201 # Namespaces to search in:
202 202 # Put them in a list. The order is important so that we
203 203 # find things in the same order that Python finds them.
204 204 namespaces = [ ('Interactive', self.shell.user_ns),
205 205 ('IPython internal', self.shell.internal_ns),
206 206 ('Python builtin', __builtin__.__dict__),
207 207 ('Alias', self.shell.alias_table),
208 208 ]
209 209 alias_ns = self.shell.alias_table
210 210
211 211 # initialize results to 'null'
212 212 found = 0; obj = None; ospace = None; ds = None;
213 213 ismagic = 0; isalias = 0; parent = None
214 214
215 215 # Look for the given name by splitting it in parts. If the head is
216 216 # found, then we look for all the remaining parts as members, and only
217 217 # declare success if we can find them all.
218 218 oname_parts = oname.split('.')
219 219 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
220 220 for nsname,ns in namespaces:
221 221 try:
222 222 obj = ns[oname_head]
223 223 except KeyError:
224 224 continue
225 225 else:
226 226 #print 'oname_rest:', oname_rest # dbg
227 227 for part in oname_rest:
228 228 try:
229 229 parent = obj
230 230 obj = getattr(obj,part)
231 231 except:
232 232 # Blanket except b/c some badly implemented objects
233 233 # allow __getattr__ to raise exceptions other than
234 234 # AttributeError, which then crashes IPython.
235 235 break
236 236 else:
237 237 # If we finish the for loop (no break), we got all members
238 238 found = 1
239 239 ospace = nsname
240 240 if ns == alias_ns:
241 241 isalias = 1
242 242 break # namespace loop
243 243
244 244 # Try to see if it's magic
245 245 if not found:
246 246 if oname.startswith(self.shell.ESC_MAGIC):
247 247 oname = oname[1:]
248 248 obj = getattr(self,'magic_'+oname,None)
249 249 if obj is not None:
250 250 found = 1
251 251 ospace = 'IPython internal'
252 252 ismagic = 1
253 253
254 254 # Last try: special-case some literals like '', [], {}, etc:
255 255 if not found and oname_head in ["''",'""','[]','{}','()']:
256 256 obj = eval(oname_head)
257 257 found = 1
258 258 ospace = 'Interactive'
259 259
260 260 return {'found':found, 'obj':obj, 'namespace':ospace,
261 261 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
262 262
263 263 def arg_err(self,func):
264 264 """Print docstring if incorrect arguments were passed"""
265 265 print 'Error in arguments:'
266 266 print OInspect.getdoc(func)
267 267
268 268 def format_latex(self,strng):
269 269 """Format a string for latex inclusion."""
270 270
271 271 # Characters that need to be escaped for latex:
272 272 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
273 273 # Magic command names as headers:
274 274 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
275 275 re.MULTILINE)
276 276 # Magic commands
277 277 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
278 278 re.MULTILINE)
279 279 # Paragraph continue
280 280 par_re = re.compile(r'\\$',re.MULTILINE)
281 281
282 282 # The "\n" symbol
283 283 newline_re = re.compile(r'\\n')
284 284
285 285 # Now build the string for output:
286 286 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
287 287 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
288 288 strng)
289 289 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
290 290 strng = par_re.sub(r'\\\\',strng)
291 291 strng = escape_re.sub(r'\\\1',strng)
292 292 strng = newline_re.sub(r'\\textbackslash{}n',strng)
293 293 return strng
294 294
295 295 def format_screen(self,strng):
296 296 """Format a string for screen printing.
297 297
298 298 This removes some latex-type format codes."""
299 299 # Paragraph continue
300 300 par_re = re.compile(r'\\$',re.MULTILINE)
301 301 strng = par_re.sub('',strng)
302 302 return strng
303 303
304 304 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
305 305 """Parse options passed to an argument string.
306 306
307 307 The interface is similar to that of getopt(), but it returns back a
308 308 Struct with the options as keys and the stripped argument string still
309 309 as a string.
310 310
311 311 arg_str is quoted as a true sys.argv vector by using shlex.split.
312 312 This allows us to easily expand variables, glob files, quote
313 313 arguments, etc.
314 314
315 315 Options:
316 316 -mode: default 'string'. If given as 'list', the argument string is
317 317 returned as a list (split on whitespace) instead of a string.
318 318
319 319 -list_all: put all option values in lists. Normally only options
320 320 appearing more than once are put in a list.
321 321
322 322 -posix (True): whether to split the input line in POSIX mode or not,
323 323 as per the conventions outlined in the shlex module from the
324 324 standard library."""
325 325
326 326 # inject default options at the beginning of the input line
327 327 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
328 328 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
329 329
330 330 mode = kw.get('mode','string')
331 331 if mode not in ['string','list']:
332 332 raise ValueError,'incorrect mode given: %s' % mode
333 333 # Get options
334 334 list_all = kw.get('list_all',0)
335 335 posix = kw.get('posix',True)
336 336
337 337 # Check if we have more than one argument to warrant extra processing:
338 338 odict = {} # Dictionary with options
339 339 args = arg_str.split()
340 340 if len(args) >= 1:
341 341 # If the list of inputs only has 0 or 1 thing in it, there's no
342 342 # need to look for options
343 343 argv = arg_split(arg_str,posix)
344 344 # Do regular option processing
345 345 try:
346 346 opts,args = getopt(argv,opt_str,*long_opts)
347 347 except GetoptError,e:
348 348 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
349 349 " ".join(long_opts)))
350 350 for o,a in opts:
351 351 if o.startswith('--'):
352 352 o = o[2:]
353 353 else:
354 354 o = o[1:]
355 355 try:
356 356 odict[o].append(a)
357 357 except AttributeError:
358 358 odict[o] = [odict[o],a]
359 359 except KeyError:
360 360 if list_all:
361 361 odict[o] = [a]
362 362 else:
363 363 odict[o] = a
364 364
365 365 # Prepare opts,args for return
366 366 opts = Struct(odict)
367 367 if mode == 'string':
368 368 args = ' '.join(args)
369 369
370 370 return opts,args
371 371
372 372 #......................................................................
373 373 # And now the actual magic functions
374 374
375 375 # Functions for IPython shell work (vars,funcs, config, etc)
376 376 def magic_lsmagic(self, parameter_s = ''):
377 377 """List currently available magic functions."""
378 378 mesc = self.shell.ESC_MAGIC
379 379 print 'Available magic functions:\n'+mesc+\
380 380 (' '+mesc).join(self.lsmagic())
381 381 print '\n' + Magic.auto_status[self.shell.automagic]
382 382 return None
383 383
384 384 def magic_magic(self, parameter_s = ''):
385 385 """Print information about the magic function system.
386 386
387 387 Supported formats: -latex, -brief, -rest
388 388 """
389 389
390 390 mode = ''
391 391 try:
392 392 if parameter_s.split()[0] == '-latex':
393 393 mode = 'latex'
394 394 if parameter_s.split()[0] == '-brief':
395 395 mode = 'brief'
396 396 if parameter_s.split()[0] == '-rest':
397 397 mode = 'rest'
398 398 rest_docs = []
399 399 except:
400 400 pass
401 401
402 402 magic_docs = []
403 403 for fname in self.lsmagic():
404 404 mname = 'magic_' + fname
405 405 for space in (Magic,self,self.__class__):
406 406 try:
407 407 fn = space.__dict__[mname]
408 408 except KeyError:
409 409 pass
410 410 else:
411 411 break
412 412 if mode == 'brief':
413 413 # only first line
414 414 if fn.__doc__:
415 415 fndoc = fn.__doc__.split('\n',1)[0]
416 416 else:
417 417 fndoc = 'No documentation'
418 418 else:
419 419 if fn.__doc__:
420 420 fndoc = fn.__doc__.rstrip()
421 421 else:
422 422 fndoc = 'No documentation'
423 423
424 424
425 425 if mode == 'rest':
426 426 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
427 427 fname,fndoc))
428 428
429 429 else:
430 430 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
431 431 fname,fndoc))
432 432
433 433 magic_docs = ''.join(magic_docs)
434 434
435 435 if mode == 'rest':
436 436 return "".join(rest_docs)
437 437
438 438 if mode == 'latex':
439 439 print self.format_latex(magic_docs)
440 440 return
441 441 else:
442 442 magic_docs = self.format_screen(magic_docs)
443 443 if mode == 'brief':
444 444 return magic_docs
445 445
446 446 outmsg = """
447 447 IPython's 'magic' functions
448 448 ===========================
449 449
450 450 The magic function system provides a series of functions which allow you to
451 451 control the behavior of IPython itself, plus a lot of system-type
452 452 features. All these functions are prefixed with a % character, but parameters
453 453 are given without parentheses or quotes.
454 454
455 455 NOTE: If you have 'automagic' enabled (via the command line option or with the
456 456 %automagic function), you don't need to type in the % explicitly. By default,
457 457 IPython ships with automagic on, so you should only rarely need the % escape.
458 458
459 459 Example: typing '%cd mydir' (without the quotes) changes you working directory
460 460 to 'mydir', if it exists.
461 461
462 462 You can define your own magic functions to extend the system. See the supplied
463 463 ipythonrc and example-magic.py files for details (in your ipython
464 464 configuration directory, typically $HOME/.ipython/).
465 465
466 466 You can also define your own aliased names for magic functions. In your
467 467 ipythonrc file, placing a line like:
468 468
469 469 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
470 470
471 471 will define %pf as a new name for %profile.
472 472
473 473 You can also call magics in code using the ipmagic() function, which IPython
474 474 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
475 475
476 476 For a list of the available magic functions, use %lsmagic. For a description
477 477 of any of them, type %magic_name?, e.g. '%cd?'.
478 478
479 479 Currently the magic system has the following functions:\n"""
480 480
481 481 mesc = self.shell.ESC_MAGIC
482 482 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
483 483 "\n\n%s%s\n\n%s" % (outmsg,
484 484 magic_docs,mesc,mesc,
485 485 (' '+mesc).join(self.lsmagic()),
486 486 Magic.auto_status[self.shell.automagic] ) )
487 487
488 488 page(outmsg,screen_lines=self.shell.usable_screen_length)
489 489
490 490
491 491 def magic_autoindent(self, parameter_s = ''):
492 492 """Toggle autoindent on/off (if available)."""
493 493
494 494 self.shell.set_autoindent()
495 495 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
496 496
497 497
498 498 def magic_automagic(self, parameter_s = ''):
499 499 """Make magic functions callable without having to type the initial %.
500 500
501 501 Without argumentsl toggles on/off (when off, you must call it as
502 502 %automagic, of course). With arguments it sets the value, and you can
503 503 use any of (case insensitive):
504 504
505 505 - on,1,True: to activate
506 506
507 507 - off,0,False: to deactivate.
508 508
509 509 Note that magic functions have lowest priority, so if there's a
510 510 variable whose name collides with that of a magic fn, automagic won't
511 511 work for that function (you get the variable instead). However, if you
512 512 delete the variable (del var), the previously shadowed magic function
513 513 becomes visible to automagic again."""
514 514
515 515 arg = parameter_s.lower()
516 516 if parameter_s in ('on','1','true'):
517 517 self.shell.automagic = True
518 518 elif parameter_s in ('off','0','false'):
519 519 self.shell.automagic = False
520 520 else:
521 521 self.shell.automagic = not self.shell.automagic
522 522 print '\n' + Magic.auto_status[self.shell.automagic]
523 523
524 524 @testdec.skip_doctest
525 525 def magic_autocall(self, parameter_s = ''):
526 526 """Make functions callable without having to type parentheses.
527 527
528 528 Usage:
529 529
530 530 %autocall [mode]
531 531
532 532 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
533 533 value is toggled on and off (remembering the previous state).
534 534
535 535 In more detail, these values mean:
536 536
537 537 0 -> fully disabled
538 538
539 539 1 -> active, but do not apply if there are no arguments on the line.
540 540
541 541 In this mode, you get:
542 542
543 543 In [1]: callable
544 544 Out[1]: <built-in function callable>
545 545
546 546 In [2]: callable 'hello'
547 547 ------> callable('hello')
548 548 Out[2]: False
549 549
550 550 2 -> Active always. Even if no arguments are present, the callable
551 551 object is called:
552 552
553 553 In [2]: float
554 554 ------> float()
555 555 Out[2]: 0.0
556 556
557 557 Note that even with autocall off, you can still use '/' at the start of
558 558 a line to treat the first argument on the command line as a function
559 559 and add parentheses to it:
560 560
561 561 In [8]: /str 43
562 562 ------> str(43)
563 563 Out[8]: '43'
564 564
565 565 # all-random (note for auto-testing)
566 566 """
567 567
568 568 if parameter_s:
569 569 arg = int(parameter_s)
570 570 else:
571 571 arg = 'toggle'
572 572
573 573 if not arg in (0,1,2,'toggle'):
574 574 error('Valid modes: (0->Off, 1->Smart, 2->Full')
575 575 return
576 576
577 577 if arg in (0,1,2):
578 578 self.shell.autocall = arg
579 579 else: # toggle
580 580 if self.shell.autocall:
581 581 self._magic_state.autocall_save = self.shell.autocall
582 582 self.shell.autocall = 0
583 583 else:
584 584 try:
585 585 self.shell.autocall = self._magic_state.autocall_save
586 586 except AttributeError:
587 587 self.shell.autocall = self._magic_state.autocall_save = 1
588 588
589 589 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
590 590
591 591 def magic_system_verbose(self, parameter_s = ''):
592 592 """Set verbose printing of system calls.
593 593
594 594 If called without an argument, act as a toggle"""
595 595
596 596 if parameter_s:
597 597 val = bool(eval(parameter_s))
598 598 else:
599 599 val = None
600 600
601 601 if self.shell.system_verbose:
602 602 self.shell.system_verbose = False
603 603 else:
604 604 self.shell.system_verbose = True
605 605 print "System verbose printing is:",\
606 606 ['OFF','ON'][self.shell.system_verbose]
607 607
608 608
609 609 def magic_page(self, parameter_s=''):
610 610 """Pretty print the object and display it through a pager.
611 611
612 612 %page [options] OBJECT
613 613
614 614 If no object is given, use _ (last output).
615 615
616 616 Options:
617 617
618 618 -r: page str(object), don't pretty-print it."""
619 619
620 620 # After a function contributed by Olivier Aubert, slightly modified.
621 621
622 622 # Process options/args
623 623 opts,args = self.parse_options(parameter_s,'r')
624 624 raw = 'r' in opts
625 625
626 626 oname = args and args or '_'
627 627 info = self._ofind(oname)
628 628 if info['found']:
629 629 txt = (raw and str or pformat)( info['obj'] )
630 630 page(txt)
631 631 else:
632 632 print 'Object `%s` not found' % oname
633 633
634 634 def magic_profile(self, parameter_s=''):
635 635 """Print your currently active IPyhton profile."""
636 636 if self.shell.profile:
637 637 printpl('Current IPython profile: $self.shell.profile.')
638 638 else:
639 639 print 'No profile active.'
640 640
641 641 def magic_pinfo(self, parameter_s='', namespaces=None):
642 642 """Provide detailed information about an object.
643 643
644 644 '%pinfo object' is just a synonym for object? or ?object."""
645 645
646 646 #print 'pinfo par: <%s>' % parameter_s # dbg
647 647
648 648
649 649 # detail_level: 0 -> obj? , 1 -> obj??
650 650 detail_level = 0
651 651 # We need to detect if we got called as 'pinfo pinfo foo', which can
652 652 # happen if the user types 'pinfo foo?' at the cmd line.
653 653 pinfo,qmark1,oname,qmark2 = \
654 654 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
655 655 if pinfo or qmark1 or qmark2:
656 656 detail_level = 1
657 657 if "*" in oname:
658 658 self.magic_psearch(oname)
659 659 else:
660 660 self._inspect('pinfo', oname, detail_level=detail_level,
661 661 namespaces=namespaces)
662 662
663 663 def magic_pdef(self, parameter_s='', namespaces=None):
664 664 """Print the definition header for any callable object.
665 665
666 666 If the object is a class, print the constructor information."""
667 667 self._inspect('pdef',parameter_s, namespaces)
668 668
669 669 def magic_pdoc(self, parameter_s='', namespaces=None):
670 670 """Print the docstring for an object.
671 671
672 672 If the given object is a class, it will print both the class and the
673 673 constructor docstrings."""
674 674 self._inspect('pdoc',parameter_s, namespaces)
675 675
676 676 def magic_psource(self, parameter_s='', namespaces=None):
677 677 """Print (or run through pager) the source code for an object."""
678 678 self._inspect('psource',parameter_s, namespaces)
679 679
680 680 def magic_pfile(self, parameter_s=''):
681 681 """Print (or run through pager) the file where an object is defined.
682 682
683 683 The file opens at the line where the object definition begins. IPython
684 684 will honor the environment variable PAGER if set, and otherwise will
685 685 do its best to print the file in a convenient form.
686 686
687 687 If the given argument is not an object currently defined, IPython will
688 688 try to interpret it as a filename (automatically adding a .py extension
689 689 if needed). You can thus use %pfile as a syntax highlighting code
690 690 viewer."""
691 691
692 692 # first interpret argument as an object name
693 693 out = self._inspect('pfile',parameter_s)
694 694 # if not, try the input as a filename
695 695 if out == 'not found':
696 696 try:
697 697 filename = get_py_filename(parameter_s)
698 698 except IOError,msg:
699 699 print msg
700 700 return
701 701 page(self.shell.inspector.format(file(filename).read()))
702 702
703 703 def _inspect(self,meth,oname,namespaces=None,**kw):
704 704 """Generic interface to the inspector system.
705 705
706 706 This function is meant to be called by pdef, pdoc & friends."""
707 707
708 708 #oname = oname.strip()
709 709 #print '1- oname: <%r>' % oname # dbg
710 710 try:
711 711 oname = oname.strip().encode('ascii')
712 712 #print '2- oname: <%r>' % oname # dbg
713 713 except UnicodeEncodeError:
714 714 print 'Python identifiers can only contain ascii characters.'
715 715 return 'not found'
716 716
717 717 info = Struct(self._ofind(oname, namespaces))
718 718
719 719 if info.found:
720 720 try:
721 721 IPython.utils.generics.inspect_object(info.obj)
722 722 return
723 723 except ipapi.TryNext:
724 724 pass
725 725 # Get the docstring of the class property if it exists.
726 726 path = oname.split('.')
727 727 root = '.'.join(path[:-1])
728 728 if info.parent is not None:
729 729 try:
730 730 target = getattr(info.parent, '__class__')
731 731 # The object belongs to a class instance.
732 732 try:
733 733 target = getattr(target, path[-1])
734 734 # The class defines the object.
735 735 if isinstance(target, property):
736 736 oname = root + '.__class__.' + path[-1]
737 737 info = Struct(self._ofind(oname))
738 738 except AttributeError: pass
739 739 except AttributeError: pass
740 740
741 741 pmethod = getattr(self.shell.inspector,meth)
742 742 formatter = info.ismagic and self.format_screen or None
743 743 if meth == 'pdoc':
744 744 pmethod(info.obj,oname,formatter)
745 745 elif meth == 'pinfo':
746 746 pmethod(info.obj,oname,formatter,info,**kw)
747 747 else:
748 748 pmethod(info.obj,oname)
749 749 else:
750 750 print 'Object `%s` not found.' % oname
751 751 return 'not found' # so callers can take other action
752 752
753 753 def magic_psearch(self, parameter_s=''):
754 754 """Search for object in namespaces by wildcard.
755 755
756 756 %psearch [options] PATTERN [OBJECT TYPE]
757 757
758 758 Note: ? can be used as a synonym for %psearch, at the beginning or at
759 759 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
760 760 rest of the command line must be unchanged (options come first), so
761 761 for example the following forms are equivalent
762 762
763 763 %psearch -i a* function
764 764 -i a* function?
765 765 ?-i a* function
766 766
767 767 Arguments:
768 768
769 769 PATTERN
770 770
771 771 where PATTERN is a string containing * as a wildcard similar to its
772 772 use in a shell. The pattern is matched in all namespaces on the
773 773 search path. By default objects starting with a single _ are not
774 774 matched, many IPython generated objects have a single
775 775 underscore. The default is case insensitive matching. Matching is
776 776 also done on the attributes of objects and not only on the objects
777 777 in a module.
778 778
779 779 [OBJECT TYPE]
780 780
781 781 Is the name of a python type from the types module. The name is
782 782 given in lowercase without the ending type, ex. StringType is
783 783 written string. By adding a type here only objects matching the
784 784 given type are matched. Using all here makes the pattern match all
785 785 types (this is the default).
786 786
787 787 Options:
788 788
789 789 -a: makes the pattern match even objects whose names start with a
790 790 single underscore. These names are normally ommitted from the
791 791 search.
792 792
793 793 -i/-c: make the pattern case insensitive/sensitive. If neither of
794 794 these options is given, the default is read from your ipythonrc
795 795 file. The option name which sets this value is
796 796 'wildcards_case_sensitive'. If this option is not specified in your
797 797 ipythonrc file, IPython's internal default is to do a case sensitive
798 798 search.
799 799
800 800 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
801 801 specifiy can be searched in any of the following namespaces:
802 802 'builtin', 'user', 'user_global','internal', 'alias', where
803 803 'builtin' and 'user' are the search defaults. Note that you should
804 804 not use quotes when specifying namespaces.
805 805
806 806 'Builtin' contains the python module builtin, 'user' contains all
807 807 user data, 'alias' only contain the shell aliases and no python
808 808 objects, 'internal' contains objects used by IPython. The
809 809 'user_global' namespace is only used by embedded IPython instances,
810 810 and it contains module-level globals. You can add namespaces to the
811 811 search with -s or exclude them with -e (these options can be given
812 812 more than once).
813 813
814 814 Examples:
815 815
816 816 %psearch a* -> objects beginning with an a
817 817 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
818 818 %psearch a* function -> all functions beginning with an a
819 819 %psearch re.e* -> objects beginning with an e in module re
820 820 %psearch r*.e* -> objects that start with e in modules starting in r
821 821 %psearch r*.* string -> all strings in modules beginning with r
822 822
823 823 Case sensitve search:
824 824
825 825 %psearch -c a* list all object beginning with lower case a
826 826
827 827 Show objects beginning with a single _:
828 828
829 829 %psearch -a _* list objects beginning with a single underscore"""
830 830 try:
831 831 parameter_s = parameter_s.encode('ascii')
832 832 except UnicodeEncodeError:
833 833 print 'Python identifiers can only contain ascii characters.'
834 834 return
835 835
836 836 # default namespaces to be searched
837 837 def_search = ['user','builtin']
838 838
839 839 # Process options/args
840 840 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
841 841 opt = opts.get
842 842 shell = self.shell
843 843 psearch = shell.inspector.psearch
844 844
845 845 # select case options
846 846 if opts.has_key('i'):
847 847 ignore_case = True
848 848 elif opts.has_key('c'):
849 849 ignore_case = False
850 850 else:
851 851 ignore_case = not shell.wildcards_case_sensitive
852 852
853 853 # Build list of namespaces to search from user options
854 854 def_search.extend(opt('s',[]))
855 855 ns_exclude = ns_exclude=opt('e',[])
856 856 ns_search = [nm for nm in def_search if nm not in ns_exclude]
857 857
858 858 # Call the actual search
859 859 try:
860 860 psearch(args,shell.ns_table,ns_search,
861 861 show_all=opt('a'),ignore_case=ignore_case)
862 862 except:
863 863 shell.showtraceback()
864 864
865 865 def magic_who_ls(self, parameter_s=''):
866 866 """Return a sorted list of all interactive variables.
867 867
868 868 If arguments are given, only variables of types matching these
869 869 arguments are returned."""
870 870
871 871 user_ns = self.shell.user_ns
872 872 internal_ns = self.shell.internal_ns
873 873 user_config_ns = self.shell.user_config_ns
874 874 out = []
875 875 typelist = parameter_s.split()
876 876
877 877 for i in user_ns:
878 878 if not (i.startswith('_') or i.startswith('_i')) \
879 879 and not (i in internal_ns or i in user_config_ns):
880 880 if typelist:
881 881 if type(user_ns[i]).__name__ in typelist:
882 882 out.append(i)
883 883 else:
884 884 out.append(i)
885 885 out.sort()
886 886 return out
887 887
888 888 def magic_who(self, parameter_s=''):
889 889 """Print all interactive variables, with some minimal formatting.
890 890
891 891 If any arguments are given, only variables whose type matches one of
892 892 these are printed. For example:
893 893
894 894 %who function str
895 895
896 896 will only list functions and strings, excluding all other types of
897 897 variables. To find the proper type names, simply use type(var) at a
898 898 command line to see how python prints type names. For example:
899 899
900 900 In [1]: type('hello')\\
901 901 Out[1]: <type 'str'>
902 902
903 903 indicates that the type name for strings is 'str'.
904 904
905 905 %who always excludes executed names loaded through your configuration
906 906 file and things which are internal to IPython.
907 907
908 908 This is deliberate, as typically you may load many modules and the
909 909 purpose of %who is to show you only what you've manually defined."""
910 910
911 911 varlist = self.magic_who_ls(parameter_s)
912 912 if not varlist:
913 913 if parameter_s:
914 914 print 'No variables match your requested type.'
915 915 else:
916 916 print 'Interactive namespace is empty.'
917 917 return
918 918
919 919 # if we have variables, move on...
920 920 count = 0
921 921 for i in varlist:
922 922 print i+'\t',
923 923 count += 1
924 924 if count > 8:
925 925 count = 0
926 926 print
927 927 print
928 928
929 929 def magic_whos(self, parameter_s=''):
930 930 """Like %who, but gives some extra information about each variable.
931 931
932 932 The same type filtering of %who can be applied here.
933 933
934 934 For all variables, the type is printed. Additionally it prints:
935 935
936 936 - For {},[],(): their length.
937 937
938 938 - For numpy and Numeric arrays, a summary with shape, number of
939 939 elements, typecode and size in memory.
940 940
941 941 - Everything else: a string representation, snipping their middle if
942 942 too long."""
943 943
944 944 varnames = self.magic_who_ls(parameter_s)
945 945 if not varnames:
946 946 if parameter_s:
947 947 print 'No variables match your requested type.'
948 948 else:
949 949 print 'Interactive namespace is empty.'
950 950 return
951 951
952 952 # if we have variables, move on...
953 953
954 954 # for these types, show len() instead of data:
955 955 seq_types = [types.DictType,types.ListType,types.TupleType]
956 956
957 957 # for numpy/Numeric arrays, display summary info
958 958 try:
959 959 import numpy
960 960 except ImportError:
961 961 ndarray_type = None
962 962 else:
963 963 ndarray_type = numpy.ndarray.__name__
964 964 try:
965 965 import Numeric
966 966 except ImportError:
967 967 array_type = None
968 968 else:
969 969 array_type = Numeric.ArrayType.__name__
970 970
971 971 # Find all variable names and types so we can figure out column sizes
972 972 def get_vars(i):
973 973 return self.shell.user_ns[i]
974 974
975 975 # some types are well known and can be shorter
976 976 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
977 977 def type_name(v):
978 978 tn = type(v).__name__
979 979 return abbrevs.get(tn,tn)
980 980
981 981 varlist = map(get_vars,varnames)
982 982
983 983 typelist = []
984 984 for vv in varlist:
985 985 tt = type_name(vv)
986 986
987 987 if tt=='instance':
988 988 typelist.append( abbrevs.get(str(vv.__class__),
989 989 str(vv.__class__)))
990 990 else:
991 991 typelist.append(tt)
992 992
993 993 # column labels and # of spaces as separator
994 994 varlabel = 'Variable'
995 995 typelabel = 'Type'
996 996 datalabel = 'Data/Info'
997 997 colsep = 3
998 998 # variable format strings
999 999 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1000 1000 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1001 1001 aformat = "%s: %s elems, type `%s`, %s bytes"
1002 1002 # find the size of the columns to format the output nicely
1003 1003 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1004 1004 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1005 1005 # table header
1006 1006 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1007 1007 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1008 1008 # and the table itself
1009 1009 kb = 1024
1010 1010 Mb = 1048576 # kb**2
1011 1011 for vname,var,vtype in zip(varnames,varlist,typelist):
1012 1012 print itpl(vformat),
1013 1013 if vtype in seq_types:
1014 1014 print len(var)
1015 1015 elif vtype in [array_type,ndarray_type]:
1016 1016 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1017 1017 if vtype==ndarray_type:
1018 1018 # numpy
1019 1019 vsize = var.size
1020 1020 vbytes = vsize*var.itemsize
1021 1021 vdtype = var.dtype
1022 1022 else:
1023 1023 # Numeric
1024 1024 vsize = Numeric.size(var)
1025 1025 vbytes = vsize*var.itemsize()
1026 1026 vdtype = var.typecode()
1027 1027
1028 1028 if vbytes < 100000:
1029 1029 print aformat % (vshape,vsize,vdtype,vbytes)
1030 1030 else:
1031 1031 print aformat % (vshape,vsize,vdtype,vbytes),
1032 1032 if vbytes < Mb:
1033 1033 print '(%s kb)' % (vbytes/kb,)
1034 1034 else:
1035 1035 print '(%s Mb)' % (vbytes/Mb,)
1036 1036 else:
1037 1037 try:
1038 1038 vstr = str(var)
1039 1039 except UnicodeEncodeError:
1040 1040 vstr = unicode(var).encode(sys.getdefaultencoding(),
1041 1041 'backslashreplace')
1042 1042 vstr = vstr.replace('\n','\\n')
1043 1043 if len(vstr) < 50:
1044 1044 print vstr
1045 1045 else:
1046 1046 printpl(vfmt_short)
1047 1047
1048 1048 def magic_reset(self, parameter_s=''):
1049 1049 """Resets the namespace by removing all names defined by the user.
1050 1050
1051 1051 Input/Output history are left around in case you need them.
1052 1052
1053 1053 Parameters
1054 1054 ----------
1055 1055 -y : force reset without asking for confirmation.
1056 1056
1057 1057 Examples
1058 1058 --------
1059 1059 In [6]: a = 1
1060 1060
1061 1061 In [7]: a
1062 1062 Out[7]: 1
1063 1063
1064 1064 In [8]: 'a' in _ip.user_ns
1065 1065 Out[8]: True
1066 1066
1067 1067 In [9]: %reset -f
1068 1068
1069 1069 In [10]: 'a' in _ip.user_ns
1070 1070 Out[10]: False
1071 1071 """
1072 1072
1073 1073 if parameter_s == '-f':
1074 1074 ans = True
1075 1075 else:
1076 1076 ans = self.shell.ask_yes_no(
1077 1077 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1078 1078 if not ans:
1079 1079 print 'Nothing done.'
1080 1080 return
1081 1081 user_ns = self.shell.user_ns
1082 1082 for i in self.magic_who_ls():
1083 1083 del(user_ns[i])
1084 1084
1085 1085 # Also flush the private list of module references kept for script
1086 1086 # execution protection
1087 1087 self.shell.clear_main_mod_cache()
1088 1088
1089 1089 def magic_logstart(self,parameter_s=''):
1090 1090 """Start logging anywhere in a session.
1091 1091
1092 1092 %logstart [-o|-r|-t] [log_name [log_mode]]
1093 1093
1094 1094 If no name is given, it defaults to a file named 'ipython_log.py' in your
1095 1095 current directory, in 'rotate' mode (see below).
1096 1096
1097 1097 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1098 1098 history up to that point and then continues logging.
1099 1099
1100 1100 %logstart takes a second optional parameter: logging mode. This can be one
1101 1101 of (note that the modes are given unquoted):\\
1102 1102 append: well, that says it.\\
1103 1103 backup: rename (if exists) to name~ and start name.\\
1104 1104 global: single logfile in your home dir, appended to.\\
1105 1105 over : overwrite existing log.\\
1106 1106 rotate: create rotating logs name.1~, name.2~, etc.
1107 1107
1108 1108 Options:
1109 1109
1110 1110 -o: log also IPython's output. In this mode, all commands which
1111 1111 generate an Out[NN] prompt are recorded to the logfile, right after
1112 1112 their corresponding input line. The output lines are always
1113 1113 prepended with a '#[Out]# ' marker, so that the log remains valid
1114 1114 Python code.
1115 1115
1116 1116 Since this marker is always the same, filtering only the output from
1117 1117 a log is very easy, using for example a simple awk call:
1118 1118
1119 1119 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1120 1120
1121 1121 -r: log 'raw' input. Normally, IPython's logs contain the processed
1122 1122 input, so that user lines are logged in their final form, converted
1123 1123 into valid Python. For example, %Exit is logged as
1124 1124 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1125 1125 exactly as typed, with no transformations applied.
1126 1126
1127 1127 -t: put timestamps before each input line logged (these are put in
1128 1128 comments)."""
1129 1129
1130 1130 opts,par = self.parse_options(parameter_s,'ort')
1131 1131 log_output = 'o' in opts
1132 1132 log_raw_input = 'r' in opts
1133 1133 timestamp = 't' in opts
1134 1134
1135 1135 logger = self.shell.logger
1136 1136
1137 1137 # if no args are given, the defaults set in the logger constructor by
1138 1138 # ipytohn remain valid
1139 1139 if par:
1140 1140 try:
1141 1141 logfname,logmode = par.split()
1142 1142 except:
1143 1143 logfname = par
1144 1144 logmode = 'backup'
1145 1145 else:
1146 1146 logfname = logger.logfname
1147 1147 logmode = logger.logmode
1148 1148 # put logfname into rc struct as if it had been called on the command
1149 1149 # line, so it ends up saved in the log header Save it in case we need
1150 1150 # to restore it...
1151 1151 old_logfile = self.shell.logfile
1152 1152 if logfname:
1153 1153 logfname = os.path.expanduser(logfname)
1154 1154 self.shell.logfile = logfname
1155 1155 # TODO: we need to re-think how logs with args/opts are replayed
1156 1156 # and tracked.
1157 1157 # loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1158 1158 loghead = self.shell.loghead_tpl % ('','')
1159 1159 try:
1160 1160 started = logger.logstart(logfname,loghead,logmode,
1161 1161 log_output,timestamp,log_raw_input)
1162 1162 except:
1163 1163 rc.opts.logfile = old_logfile
1164 1164 warn("Couldn't start log: %s" % sys.exc_info()[1])
1165 1165 else:
1166 1166 # log input history up to this point, optionally interleaving
1167 1167 # output if requested
1168 1168
1169 1169 if timestamp:
1170 1170 # disable timestamping for the previous history, since we've
1171 1171 # lost those already (no time machine here).
1172 1172 logger.timestamp = False
1173 1173
1174 1174 if log_raw_input:
1175 1175 input_hist = self.shell.input_hist_raw
1176 1176 else:
1177 1177 input_hist = self.shell.input_hist
1178 1178
1179 1179 if log_output:
1180 1180 log_write = logger.log_write
1181 1181 output_hist = self.shell.output_hist
1182 1182 for n in range(1,len(input_hist)-1):
1183 1183 log_write(input_hist[n].rstrip())
1184 1184 if n in output_hist:
1185 1185 log_write(repr(output_hist[n]),'output')
1186 1186 else:
1187 1187 logger.log_write(input_hist[1:])
1188 1188 if timestamp:
1189 1189 # re-enable timestamping
1190 1190 logger.timestamp = True
1191 1191
1192 1192 print ('Activating auto-logging. '
1193 1193 'Current session state plus future input saved.')
1194 1194 logger.logstate()
1195 1195
1196 1196 def magic_logstop(self,parameter_s=''):
1197 1197 """Fully stop logging and close log file.
1198 1198
1199 1199 In order to start logging again, a new %logstart call needs to be made,
1200 1200 possibly (though not necessarily) with a new filename, mode and other
1201 1201 options."""
1202 1202 self.logger.logstop()
1203 1203
1204 1204 def magic_logoff(self,parameter_s=''):
1205 1205 """Temporarily stop logging.
1206 1206
1207 1207 You must have previously started logging."""
1208 1208 self.shell.logger.switch_log(0)
1209 1209
1210 1210 def magic_logon(self,parameter_s=''):
1211 1211 """Restart logging.
1212 1212
1213 1213 This function is for restarting logging which you've temporarily
1214 1214 stopped with %logoff. For starting logging for the first time, you
1215 1215 must use the %logstart function, which allows you to specify an
1216 1216 optional log filename."""
1217 1217
1218 1218 self.shell.logger.switch_log(1)
1219 1219
1220 1220 def magic_logstate(self,parameter_s=''):
1221 1221 """Print the status of the logging system."""
1222 1222
1223 1223 self.shell.logger.logstate()
1224 1224
1225 1225 def magic_pdb(self, parameter_s=''):
1226 1226 """Control the automatic calling of the pdb interactive debugger.
1227 1227
1228 1228 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1229 1229 argument it works as a toggle.
1230 1230
1231 1231 When an exception is triggered, IPython can optionally call the
1232 1232 interactive pdb debugger after the traceback printout. %pdb toggles
1233 1233 this feature on and off.
1234 1234
1235 1235 The initial state of this feature is set in your ipythonrc
1236 1236 configuration file (the variable is called 'pdb').
1237 1237
1238 1238 If you want to just activate the debugger AFTER an exception has fired,
1239 1239 without having to type '%pdb on' and rerunning your code, you can use
1240 1240 the %debug magic."""
1241 1241
1242 1242 par = parameter_s.strip().lower()
1243 1243
1244 1244 if par:
1245 1245 try:
1246 1246 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1247 1247 except KeyError:
1248 1248 print ('Incorrect argument. Use on/1, off/0, '
1249 1249 'or nothing for a toggle.')
1250 1250 return
1251 1251 else:
1252 1252 # toggle
1253 1253 new_pdb = not self.shell.call_pdb
1254 1254
1255 1255 # set on the shell
1256 1256 self.shell.call_pdb = new_pdb
1257 1257 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1258 1258
1259 1259 def magic_debug(self, parameter_s=''):
1260 1260 """Activate the interactive debugger in post-mortem mode.
1261 1261
1262 1262 If an exception has just occurred, this lets you inspect its stack
1263 1263 frames interactively. Note that this will always work only on the last
1264 1264 traceback that occurred, so you must call this quickly after an
1265 1265 exception that you wish to inspect has fired, because if another one
1266 1266 occurs, it clobbers the previous one.
1267 1267
1268 1268 If you want IPython to automatically do this on every exception, see
1269 1269 the %pdb magic for more details.
1270 1270 """
1271 1271
1272 1272 self.shell.debugger(force=True)
1273 1273
1274 1274 @testdec.skip_doctest
1275 1275 def magic_prun(self, parameter_s ='',user_mode=1,
1276 1276 opts=None,arg_lst=None,prog_ns=None):
1277 1277
1278 1278 """Run a statement through the python code profiler.
1279 1279
1280 1280 Usage:
1281 1281 %prun [options] statement
1282 1282
1283 1283 The given statement (which doesn't require quote marks) is run via the
1284 1284 python profiler in a manner similar to the profile.run() function.
1285 1285 Namespaces are internally managed to work correctly; profile.run
1286 1286 cannot be used in IPython because it makes certain assumptions about
1287 1287 namespaces which do not hold under IPython.
1288 1288
1289 1289 Options:
1290 1290
1291 1291 -l <limit>: you can place restrictions on what or how much of the
1292 1292 profile gets printed. The limit value can be:
1293 1293
1294 1294 * A string: only information for function names containing this string
1295 1295 is printed.
1296 1296
1297 1297 * An integer: only these many lines are printed.
1298 1298
1299 1299 * A float (between 0 and 1): this fraction of the report is printed
1300 1300 (for example, use a limit of 0.4 to see the topmost 40% only).
1301 1301
1302 1302 You can combine several limits with repeated use of the option. For
1303 1303 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1304 1304 information about class constructors.
1305 1305
1306 1306 -r: return the pstats.Stats object generated by the profiling. This
1307 1307 object has all the information about the profile in it, and you can
1308 1308 later use it for further analysis or in other functions.
1309 1309
1310 1310 -s <key>: sort profile by given key. You can provide more than one key
1311 1311 by using the option several times: '-s key1 -s key2 -s key3...'. The
1312 1312 default sorting key is 'time'.
1313 1313
1314 1314 The following is copied verbatim from the profile documentation
1315 1315 referenced below:
1316 1316
1317 1317 When more than one key is provided, additional keys are used as
1318 1318 secondary criteria when the there is equality in all keys selected
1319 1319 before them.
1320 1320
1321 1321 Abbreviations can be used for any key names, as long as the
1322 1322 abbreviation is unambiguous. The following are the keys currently
1323 1323 defined:
1324 1324
1325 1325 Valid Arg Meaning
1326 1326 "calls" call count
1327 1327 "cumulative" cumulative time
1328 1328 "file" file name
1329 1329 "module" file name
1330 1330 "pcalls" primitive call count
1331 1331 "line" line number
1332 1332 "name" function name
1333 1333 "nfl" name/file/line
1334 1334 "stdname" standard name
1335 1335 "time" internal time
1336 1336
1337 1337 Note that all sorts on statistics are in descending order (placing
1338 1338 most time consuming items first), where as name, file, and line number
1339 1339 searches are in ascending order (i.e., alphabetical). The subtle
1340 1340 distinction between "nfl" and "stdname" is that the standard name is a
1341 1341 sort of the name as printed, which means that the embedded line
1342 1342 numbers get compared in an odd way. For example, lines 3, 20, and 40
1343 1343 would (if the file names were the same) appear in the string order
1344 1344 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1345 1345 line numbers. In fact, sort_stats("nfl") is the same as
1346 1346 sort_stats("name", "file", "line").
1347 1347
1348 1348 -T <filename>: save profile results as shown on screen to a text
1349 1349 file. The profile is still shown on screen.
1350 1350
1351 1351 -D <filename>: save (via dump_stats) profile statistics to given
1352 1352 filename. This data is in a format understod by the pstats module, and
1353 1353 is generated by a call to the dump_stats() method of profile
1354 1354 objects. The profile is still shown on screen.
1355 1355
1356 1356 If you want to run complete programs under the profiler's control, use
1357 1357 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1358 1358 contains profiler specific options as described here.
1359 1359
1360 1360 You can read the complete documentation for the profile module with::
1361 1361
1362 1362 In [1]: import profile; profile.help()
1363 1363 """
1364 1364
1365 1365 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1366 1366 # protect user quote marks
1367 1367 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1368 1368
1369 1369 if user_mode: # regular user call
1370 1370 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1371 1371 list_all=1)
1372 1372 namespace = self.shell.user_ns
1373 1373 else: # called to run a program by %run -p
1374 1374 try:
1375 1375 filename = get_py_filename(arg_lst[0])
1376 1376 except IOError,msg:
1377 1377 error(msg)
1378 1378 return
1379 1379
1380 1380 arg_str = 'execfile(filename,prog_ns)'
1381 1381 namespace = locals()
1382 1382
1383 1383 opts.merge(opts_def)
1384 1384
1385 1385 prof = profile.Profile()
1386 1386 try:
1387 1387 prof = prof.runctx(arg_str,namespace,namespace)
1388 1388 sys_exit = ''
1389 1389 except SystemExit:
1390 1390 sys_exit = """*** SystemExit exception caught in code being profiled."""
1391 1391
1392 1392 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1393 1393
1394 1394 lims = opts.l
1395 1395 if lims:
1396 1396 lims = [] # rebuild lims with ints/floats/strings
1397 1397 for lim in opts.l:
1398 1398 try:
1399 1399 lims.append(int(lim))
1400 1400 except ValueError:
1401 1401 try:
1402 1402 lims.append(float(lim))
1403 1403 except ValueError:
1404 1404 lims.append(lim)
1405 1405
1406 1406 # Trap output.
1407 1407 stdout_trap = StringIO()
1408 1408
1409 1409 if hasattr(stats,'stream'):
1410 1410 # In newer versions of python, the stats object has a 'stream'
1411 1411 # attribute to write into.
1412 1412 stats.stream = stdout_trap
1413 1413 stats.print_stats(*lims)
1414 1414 else:
1415 1415 # For older versions, we manually redirect stdout during printing
1416 1416 sys_stdout = sys.stdout
1417 1417 try:
1418 1418 sys.stdout = stdout_trap
1419 1419 stats.print_stats(*lims)
1420 1420 finally:
1421 1421 sys.stdout = sys_stdout
1422 1422
1423 1423 output = stdout_trap.getvalue()
1424 1424 output = output.rstrip()
1425 1425
1426 1426 page(output,screen_lines=self.shell.usable_screen_length)
1427 1427 print sys_exit,
1428 1428
1429 1429 dump_file = opts.D[0]
1430 1430 text_file = opts.T[0]
1431 1431 if dump_file:
1432 1432 prof.dump_stats(dump_file)
1433 1433 print '\n*** Profile stats marshalled to file',\
1434 1434 `dump_file`+'.',sys_exit
1435 1435 if text_file:
1436 1436 pfile = file(text_file,'w')
1437 1437 pfile.write(output)
1438 1438 pfile.close()
1439 1439 print '\n*** Profile printout saved to text file',\
1440 1440 `text_file`+'.',sys_exit
1441 1441
1442 1442 if opts.has_key('r'):
1443 1443 return stats
1444 1444 else:
1445 1445 return None
1446 1446
1447 1447 @testdec.skip_doctest
1448 1448 def magic_run(self, parameter_s ='',runner=None,
1449 1449 file_finder=get_py_filename):
1450 1450 """Run the named file inside IPython as a program.
1451 1451
1452 1452 Usage:\\
1453 1453 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1454 1454
1455 1455 Parameters after the filename are passed as command-line arguments to
1456 1456 the program (put in sys.argv). Then, control returns to IPython's
1457 1457 prompt.
1458 1458
1459 1459 This is similar to running at a system prompt:\\
1460 1460 $ python file args\\
1461 1461 but with the advantage of giving you IPython's tracebacks, and of
1462 1462 loading all variables into your interactive namespace for further use
1463 1463 (unless -p is used, see below).
1464 1464
1465 1465 The file is executed in a namespace initially consisting only of
1466 1466 __name__=='__main__' and sys.argv constructed as indicated. It thus
1467 1467 sees its environment as if it were being run as a stand-alone program
1468 1468 (except for sharing global objects such as previously imported
1469 1469 modules). But after execution, the IPython interactive namespace gets
1470 1470 updated with all variables defined in the program (except for __name__
1471 1471 and sys.argv). This allows for very convenient loading of code for
1472 1472 interactive work, while giving each program a 'clean sheet' to run in.
1473 1473
1474 1474 Options:
1475 1475
1476 1476 -n: __name__ is NOT set to '__main__', but to the running file's name
1477 1477 without extension (as python does under import). This allows running
1478 1478 scripts and reloading the definitions in them without calling code
1479 1479 protected by an ' if __name__ == "__main__" ' clause.
1480 1480
1481 1481 -i: run the file in IPython's namespace instead of an empty one. This
1482 1482 is useful if you are experimenting with code written in a text editor
1483 1483 which depends on variables defined interactively.
1484 1484
1485 1485 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1486 1486 being run. This is particularly useful if IPython is being used to
1487 1487 run unittests, which always exit with a sys.exit() call. In such
1488 1488 cases you are interested in the output of the test results, not in
1489 1489 seeing a traceback of the unittest module.
1490 1490
1491 1491 -t: print timing information at the end of the run. IPython will give
1492 1492 you an estimated CPU time consumption for your script, which under
1493 1493 Unix uses the resource module to avoid the wraparound problems of
1494 1494 time.clock(). Under Unix, an estimate of time spent on system tasks
1495 1495 is also given (for Windows platforms this is reported as 0.0).
1496 1496
1497 1497 If -t is given, an additional -N<N> option can be given, where <N>
1498 1498 must be an integer indicating how many times you want the script to
1499 1499 run. The final timing report will include total and per run results.
1500 1500
1501 1501 For example (testing the script uniq_stable.py):
1502 1502
1503 1503 In [1]: run -t uniq_stable
1504 1504
1505 1505 IPython CPU timings (estimated):\\
1506 1506 User : 0.19597 s.\\
1507 1507 System: 0.0 s.\\
1508 1508
1509 1509 In [2]: run -t -N5 uniq_stable
1510 1510
1511 1511 IPython CPU timings (estimated):\\
1512 1512 Total runs performed: 5\\
1513 1513 Times : Total Per run\\
1514 1514 User : 0.910862 s, 0.1821724 s.\\
1515 1515 System: 0.0 s, 0.0 s.
1516 1516
1517 1517 -d: run your program under the control of pdb, the Python debugger.
1518 1518 This allows you to execute your program step by step, watch variables,
1519 1519 etc. Internally, what IPython does is similar to calling:
1520 1520
1521 1521 pdb.run('execfile("YOURFILENAME")')
1522 1522
1523 1523 with a breakpoint set on line 1 of your file. You can change the line
1524 1524 number for this automatic breakpoint to be <N> by using the -bN option
1525 1525 (where N must be an integer). For example:
1526 1526
1527 1527 %run -d -b40 myscript
1528 1528
1529 1529 will set the first breakpoint at line 40 in myscript.py. Note that
1530 1530 the first breakpoint must be set on a line which actually does
1531 1531 something (not a comment or docstring) for it to stop execution.
1532 1532
1533 1533 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1534 1534 first enter 'c' (without qoutes) to start execution up to the first
1535 1535 breakpoint.
1536 1536
1537 1537 Entering 'help' gives information about the use of the debugger. You
1538 1538 can easily see pdb's full documentation with "import pdb;pdb.help()"
1539 1539 at a prompt.
1540 1540
1541 1541 -p: run program under the control of the Python profiler module (which
1542 1542 prints a detailed report of execution times, function calls, etc).
1543 1543
1544 1544 You can pass other options after -p which affect the behavior of the
1545 1545 profiler itself. See the docs for %prun for details.
1546 1546
1547 1547 In this mode, the program's variables do NOT propagate back to the
1548 1548 IPython interactive namespace (because they remain in the namespace
1549 1549 where the profiler executes them).
1550 1550
1551 1551 Internally this triggers a call to %prun, see its documentation for
1552 1552 details on the options available specifically for profiling.
1553 1553
1554 1554 There is one special usage for which the text above doesn't apply:
1555 1555 if the filename ends with .ipy, the file is run as ipython script,
1556 1556 just as if the commands were written on IPython prompt.
1557 1557 """
1558 1558
1559 1559 # get arguments and set sys.argv for program to be run.
1560 1560 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1561 1561 mode='list',list_all=1)
1562 1562
1563 1563 try:
1564 1564 filename = file_finder(arg_lst[0])
1565 1565 except IndexError:
1566 1566 warn('you must provide at least a filename.')
1567 1567 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1568 1568 return
1569 1569 except IOError,msg:
1570 1570 error(msg)
1571 1571 return
1572 1572
1573 1573 if filename.lower().endswith('.ipy'):
1574 1574 self.api.runlines(open(filename).read())
1575 1575 return
1576 1576
1577 1577 # Control the response to exit() calls made by the script being run
1578 1578 exit_ignore = opts.has_key('e')
1579 1579
1580 1580 # Make sure that the running script gets a proper sys.argv as if it
1581 1581 # were run from a system shell.
1582 1582 save_argv = sys.argv # save it for later restoring
1583 1583 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1584 1584
1585 1585 if opts.has_key('i'):
1586 1586 # Run in user's interactive namespace
1587 1587 prog_ns = self.shell.user_ns
1588 1588 __name__save = self.shell.user_ns['__name__']
1589 1589 prog_ns['__name__'] = '__main__'
1590 1590 main_mod = self.shell.new_main_mod(prog_ns)
1591 1591 else:
1592 1592 # Run in a fresh, empty namespace
1593 1593 if opts.has_key('n'):
1594 1594 name = os.path.splitext(os.path.basename(filename))[0]
1595 1595 else:
1596 1596 name = '__main__'
1597 1597
1598 1598 main_mod = self.shell.new_main_mod()
1599 1599 prog_ns = main_mod.__dict__
1600 1600 prog_ns['__name__'] = name
1601 1601
1602 1602 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1603 1603 # set the __file__ global in the script's namespace
1604 1604 prog_ns['__file__'] = filename
1605 1605
1606 1606 # pickle fix. See iplib for an explanation. But we need to make sure
1607 1607 # that, if we overwrite __main__, we replace it at the end
1608 1608 main_mod_name = prog_ns['__name__']
1609 1609
1610 1610 if main_mod_name == '__main__':
1611 1611 restore_main = sys.modules['__main__']
1612 1612 else:
1613 1613 restore_main = False
1614 1614
1615 1615 # This needs to be undone at the end to prevent holding references to
1616 1616 # every single object ever created.
1617 1617 sys.modules[main_mod_name] = main_mod
1618 1618
1619 1619 stats = None
1620 1620 try:
1621 1621 self.shell.savehist()
1622 1622
1623 1623 if opts.has_key('p'):
1624 1624 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1625 1625 else:
1626 1626 if opts.has_key('d'):
1627 1627 deb = debugger.Pdb(self.shell.colors)
1628 1628 # reset Breakpoint state, which is moronically kept
1629 1629 # in a class
1630 1630 bdb.Breakpoint.next = 1
1631 1631 bdb.Breakpoint.bplist = {}
1632 1632 bdb.Breakpoint.bpbynumber = [None]
1633 1633 # Set an initial breakpoint to stop execution
1634 1634 maxtries = 10
1635 1635 bp = int(opts.get('b',[1])[0])
1636 1636 checkline = deb.checkline(filename,bp)
1637 1637 if not checkline:
1638 1638 for bp in range(bp+1,bp+maxtries+1):
1639 1639 if deb.checkline(filename,bp):
1640 1640 break
1641 1641 else:
1642 1642 msg = ("\nI failed to find a valid line to set "
1643 1643 "a breakpoint\n"
1644 1644 "after trying up to line: %s.\n"
1645 1645 "Please set a valid breakpoint manually "
1646 1646 "with the -b option." % bp)
1647 1647 error(msg)
1648 1648 return
1649 1649 # if we find a good linenumber, set the breakpoint
1650 1650 deb.do_break('%s:%s' % (filename,bp))
1651 1651 # Start file run
1652 1652 print "NOTE: Enter 'c' at the",
1653 1653 print "%s prompt to start your script." % deb.prompt
1654 1654 try:
1655 1655 deb.run('execfile("%s")' % filename,prog_ns)
1656 1656
1657 1657 except:
1658 1658 etype, value, tb = sys.exc_info()
1659 1659 # Skip three frames in the traceback: the %run one,
1660 1660 # one inside bdb.py, and the command-line typed by the
1661 1661 # user (run by exec in pdb itself).
1662 1662 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1663 1663 else:
1664 1664 if runner is None:
1665 1665 runner = self.shell.safe_execfile
1666 1666 if opts.has_key('t'):
1667 1667 # timed execution
1668 1668 try:
1669 1669 nruns = int(opts['N'][0])
1670 1670 if nruns < 1:
1671 1671 error('Number of runs must be >=1')
1672 1672 return
1673 1673 except (KeyError):
1674 1674 nruns = 1
1675 1675 if nruns == 1:
1676 1676 t0 = clock2()
1677 1677 runner(filename,prog_ns,prog_ns,
1678 1678 exit_ignore=exit_ignore)
1679 1679 t1 = clock2()
1680 1680 t_usr = t1[0]-t0[0]
1681 1681 t_sys = t1[1]-t0[1]
1682 1682 print "\nIPython CPU timings (estimated):"
1683 1683 print " User : %10s s." % t_usr
1684 1684 print " System: %10s s." % t_sys
1685 1685 else:
1686 1686 runs = range(nruns)
1687 1687 t0 = clock2()
1688 1688 for nr in runs:
1689 1689 runner(filename,prog_ns,prog_ns,
1690 1690 exit_ignore=exit_ignore)
1691 1691 t1 = clock2()
1692 1692 t_usr = t1[0]-t0[0]
1693 1693 t_sys = t1[1]-t0[1]
1694 1694 print "\nIPython CPU timings (estimated):"
1695 1695 print "Total runs performed:",nruns
1696 1696 print " Times : %10s %10s" % ('Total','Per run')
1697 1697 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1698 1698 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1699 1699
1700 1700 else:
1701 1701 # regular execution
1702 1702 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1703 1703
1704 1704 if opts.has_key('i'):
1705 1705 self.shell.user_ns['__name__'] = __name__save
1706 1706 else:
1707 1707 # The shell MUST hold a reference to prog_ns so after %run
1708 1708 # exits, the python deletion mechanism doesn't zero it out
1709 1709 # (leaving dangling references).
1710 1710 self.shell.cache_main_mod(prog_ns,filename)
1711 1711 # update IPython interactive namespace
1712 1712
1713 1713 # Some forms of read errors on the file may mean the
1714 1714 # __name__ key was never set; using pop we don't have to
1715 1715 # worry about a possible KeyError.
1716 1716 prog_ns.pop('__name__', None)
1717 1717
1718 1718 self.shell.user_ns.update(prog_ns)
1719 1719 finally:
1720 1720 # It's a bit of a mystery why, but __builtins__ can change from
1721 1721 # being a module to becoming a dict missing some key data after
1722 1722 # %run. As best I can see, this is NOT something IPython is doing
1723 1723 # at all, and similar problems have been reported before:
1724 1724 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1725 1725 # Since this seems to be done by the interpreter itself, the best
1726 1726 # we can do is to at least restore __builtins__ for the user on
1727 1727 # exit.
1728 1728 self.shell.user_ns['__builtins__'] = __builtin__
1729 1729
1730 1730 # Ensure key global structures are restored
1731 1731 sys.argv = save_argv
1732 1732 if restore_main:
1733 1733 sys.modules['__main__'] = restore_main
1734 1734 else:
1735 1735 # Remove from sys.modules the reference to main_mod we'd
1736 1736 # added. Otherwise it will trap references to objects
1737 1737 # contained therein.
1738 1738 del sys.modules[main_mod_name]
1739 1739
1740 1740 self.shell.reloadhist()
1741 1741
1742 1742 return stats
1743 1743
1744 1744 def magic_runlog(self, parameter_s =''):
1745 1745 """Run files as logs.
1746 1746
1747 1747 Usage:\\
1748 1748 %runlog file1 file2 ...
1749 1749
1750 1750 Run the named files (treating them as log files) in sequence inside
1751 1751 the interpreter, and return to the prompt. This is much slower than
1752 1752 %run because each line is executed in a try/except block, but it
1753 1753 allows running files with syntax errors in them.
1754 1754
1755 1755 Normally IPython will guess when a file is one of its own logfiles, so
1756 1756 you can typically use %run even for logs. This shorthand allows you to
1757 1757 force any file to be treated as a log file."""
1758 1758
1759 1759 for f in parameter_s.split():
1760 1760 self.shell.safe_execfile(f,self.shell.user_ns,
1761 1761 self.shell.user_ns,islog=1)
1762 1762
1763 1763 @testdec.skip_doctest
1764 1764 def magic_timeit(self, parameter_s =''):
1765 1765 """Time execution of a Python statement or expression
1766 1766
1767 1767 Usage:\\
1768 1768 %timeit [-n<N> -r<R> [-t|-c]] statement
1769 1769
1770 1770 Time execution of a Python statement or expression using the timeit
1771 1771 module.
1772 1772
1773 1773 Options:
1774 1774 -n<N>: execute the given statement <N> times in a loop. If this value
1775 1775 is not given, a fitting value is chosen.
1776 1776
1777 1777 -r<R>: repeat the loop iteration <R> times and take the best result.
1778 1778 Default: 3
1779 1779
1780 1780 -t: use time.time to measure the time, which is the default on Unix.
1781 1781 This function measures wall time.
1782 1782
1783 1783 -c: use time.clock to measure the time, which is the default on
1784 1784 Windows and measures wall time. On Unix, resource.getrusage is used
1785 1785 instead and returns the CPU user time.
1786 1786
1787 1787 -p<P>: use a precision of <P> digits to display the timing result.
1788 1788 Default: 3
1789 1789
1790 1790
1791 1791 Examples:
1792 1792
1793 1793 In [1]: %timeit pass
1794 1794 10000000 loops, best of 3: 53.3 ns per loop
1795 1795
1796 1796 In [2]: u = None
1797 1797
1798 1798 In [3]: %timeit u is None
1799 1799 10000000 loops, best of 3: 184 ns per loop
1800 1800
1801 1801 In [4]: %timeit -r 4 u == None
1802 1802 1000000 loops, best of 4: 242 ns per loop
1803 1803
1804 1804 In [5]: import time
1805 1805
1806 1806 In [6]: %timeit -n1 time.sleep(2)
1807 1807 1 loops, best of 3: 2 s per loop
1808 1808
1809 1809
1810 1810 The times reported by %timeit will be slightly higher than those
1811 1811 reported by the timeit.py script when variables are accessed. This is
1812 1812 due to the fact that %timeit executes the statement in the namespace
1813 1813 of the shell, compared with timeit.py, which uses a single setup
1814 1814 statement to import function or create variables. Generally, the bias
1815 1815 does not matter as long as results from timeit.py are not mixed with
1816 1816 those from %timeit."""
1817 1817
1818 1818 import timeit
1819 1819 import math
1820 1820
1821 1821 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1822 1822 # certain terminals. Until we figure out a robust way of
1823 1823 # auto-detecting if the terminal can deal with it, use plain 'us' for
1824 1824 # microseconds. I am really NOT happy about disabling the proper
1825 1825 # 'micro' prefix, but crashing is worse... If anyone knows what the
1826 1826 # right solution for this is, I'm all ears...
1827 1827 #
1828 1828 # Note: using
1829 1829 #
1830 1830 # s = u'\xb5'
1831 1831 # s.encode(sys.getdefaultencoding())
1832 1832 #
1833 1833 # is not sufficient, as I've seen terminals where that fails but
1834 1834 # print s
1835 1835 #
1836 1836 # succeeds
1837 1837 #
1838 1838 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1839 1839
1840 1840 #units = [u"s", u"ms",u'\xb5',"ns"]
1841 1841 units = [u"s", u"ms",u'us',"ns"]
1842 1842
1843 1843 scaling = [1, 1e3, 1e6, 1e9]
1844 1844
1845 1845 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1846 1846 posix=False)
1847 1847 if stmt == "":
1848 1848 return
1849 1849 timefunc = timeit.default_timer
1850 1850 number = int(getattr(opts, "n", 0))
1851 1851 repeat = int(getattr(opts, "r", timeit.default_repeat))
1852 1852 precision = int(getattr(opts, "p", 3))
1853 1853 if hasattr(opts, "t"):
1854 1854 timefunc = time.time
1855 1855 if hasattr(opts, "c"):
1856 1856 timefunc = clock
1857 1857
1858 1858 timer = timeit.Timer(timer=timefunc)
1859 1859 # this code has tight coupling to the inner workings of timeit.Timer,
1860 1860 # but is there a better way to achieve that the code stmt has access
1861 1861 # to the shell namespace?
1862 1862
1863 1863 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1864 1864 'setup': "pass"}
1865 1865 # Track compilation time so it can be reported if too long
1866 1866 # Minimum time above which compilation time will be reported
1867 1867 tc_min = 0.1
1868 1868
1869 1869 t0 = clock()
1870 1870 code = compile(src, "<magic-timeit>", "exec")
1871 1871 tc = clock()-t0
1872 1872
1873 1873 ns = {}
1874 1874 exec code in self.shell.user_ns, ns
1875 1875 timer.inner = ns["inner"]
1876 1876
1877 1877 if number == 0:
1878 1878 # determine number so that 0.2 <= total time < 2.0
1879 1879 number = 1
1880 1880 for i in range(1, 10):
1881 1881 if timer.timeit(number) >= 0.2:
1882 1882 break
1883 1883 number *= 10
1884 1884
1885 1885 best = min(timer.repeat(repeat, number)) / number
1886 1886
1887 1887 if best > 0.0:
1888 1888 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1889 1889 else:
1890 1890 order = 3
1891 1891 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1892 1892 precision,
1893 1893 best * scaling[order],
1894 1894 units[order])
1895 1895 if tc > tc_min:
1896 1896 print "Compiler time: %.2f s" % tc
1897 1897
1898 1898 @testdec.skip_doctest
1899 1899 def magic_time(self,parameter_s = ''):
1900 1900 """Time execution of a Python statement or expression.
1901 1901
1902 1902 The CPU and wall clock times are printed, and the value of the
1903 1903 expression (if any) is returned. Note that under Win32, system time
1904 1904 is always reported as 0, since it can not be measured.
1905 1905
1906 1906 This function provides very basic timing functionality. In Python
1907 1907 2.3, the timeit module offers more control and sophistication, so this
1908 1908 could be rewritten to use it (patches welcome).
1909 1909
1910 1910 Some examples:
1911 1911
1912 1912 In [1]: time 2**128
1913 1913 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1914 1914 Wall time: 0.00
1915 1915 Out[1]: 340282366920938463463374607431768211456L
1916 1916
1917 1917 In [2]: n = 1000000
1918 1918
1919 1919 In [3]: time sum(range(n))
1920 1920 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1921 1921 Wall time: 1.37
1922 1922 Out[3]: 499999500000L
1923 1923
1924 1924 In [4]: time print 'hello world'
1925 1925 hello world
1926 1926 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1927 1927 Wall time: 0.00
1928 1928
1929 1929 Note that the time needed by Python to compile the given expression
1930 1930 will be reported if it is more than 0.1s. In this example, the
1931 1931 actual exponentiation is done by Python at compilation time, so while
1932 1932 the expression can take a noticeable amount of time to compute, that
1933 1933 time is purely due to the compilation:
1934 1934
1935 1935 In [5]: time 3**9999;
1936 1936 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1937 1937 Wall time: 0.00 s
1938 1938
1939 1939 In [6]: time 3**999999;
1940 1940 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1941 1941 Wall time: 0.00 s
1942 1942 Compiler : 0.78 s
1943 1943 """
1944 1944
1945 1945 # fail immediately if the given expression can't be compiled
1946 1946
1947 1947 expr = self.shell.prefilter(parameter_s,False)
1948 1948
1949 1949 # Minimum time above which compilation time will be reported
1950 1950 tc_min = 0.1
1951 1951
1952 1952 try:
1953 1953 mode = 'eval'
1954 1954 t0 = clock()
1955 1955 code = compile(expr,'<timed eval>',mode)
1956 1956 tc = clock()-t0
1957 1957 except SyntaxError:
1958 1958 mode = 'exec'
1959 1959 t0 = clock()
1960 1960 code = compile(expr,'<timed exec>',mode)
1961 1961 tc = clock()-t0
1962 1962 # skew measurement as little as possible
1963 1963 glob = self.shell.user_ns
1964 1964 clk = clock2
1965 1965 wtime = time.time
1966 1966 # time execution
1967 1967 wall_st = wtime()
1968 1968 if mode=='eval':
1969 1969 st = clk()
1970 1970 out = eval(code,glob)
1971 1971 end = clk()
1972 1972 else:
1973 1973 st = clk()
1974 1974 exec code in glob
1975 1975 end = clk()
1976 1976 out = None
1977 1977 wall_end = wtime()
1978 1978 # Compute actual times and report
1979 1979 wall_time = wall_end-wall_st
1980 1980 cpu_user = end[0]-st[0]
1981 1981 cpu_sys = end[1]-st[1]
1982 1982 cpu_tot = cpu_user+cpu_sys
1983 1983 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1984 1984 (cpu_user,cpu_sys,cpu_tot)
1985 1985 print "Wall time: %.2f s" % wall_time
1986 1986 if tc > tc_min:
1987 1987 print "Compiler : %.2f s" % tc
1988 1988 return out
1989 1989
1990 1990 @testdec.skip_doctest
1991 1991 def magic_macro(self,parameter_s = ''):
1992 1992 """Define a set of input lines as a macro for future re-execution.
1993 1993
1994 1994 Usage:\\
1995 1995 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1996 1996
1997 1997 Options:
1998 1998
1999 1999 -r: use 'raw' input. By default, the 'processed' history is used,
2000 2000 so that magics are loaded in their transformed version to valid
2001 2001 Python. If this option is given, the raw input as typed as the
2002 2002 command line is used instead.
2003 2003
2004 2004 This will define a global variable called `name` which is a string
2005 2005 made of joining the slices and lines you specify (n1,n2,... numbers
2006 2006 above) from your input history into a single string. This variable
2007 2007 acts like an automatic function which re-executes those lines as if
2008 2008 you had typed them. You just type 'name' at the prompt and the code
2009 2009 executes.
2010 2010
2011 2011 The notation for indicating number ranges is: n1-n2 means 'use line
2012 2012 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2013 2013 using the lines numbered 5,6 and 7.
2014 2014
2015 2015 Note: as a 'hidden' feature, you can also use traditional python slice
2016 2016 notation, where N:M means numbers N through M-1.
2017 2017
2018 2018 For example, if your history contains (%hist prints it):
2019 2019
2020 2020 44: x=1
2021 2021 45: y=3
2022 2022 46: z=x+y
2023 2023 47: print x
2024 2024 48: a=5
2025 2025 49: print 'x',x,'y',y
2026 2026
2027 2027 you can create a macro with lines 44 through 47 (included) and line 49
2028 2028 called my_macro with:
2029 2029
2030 2030 In [55]: %macro my_macro 44-47 49
2031 2031
2032 2032 Now, typing `my_macro` (without quotes) will re-execute all this code
2033 2033 in one pass.
2034 2034
2035 2035 You don't need to give the line-numbers in order, and any given line
2036 2036 number can appear multiple times. You can assemble macros with any
2037 2037 lines from your input history in any order.
2038 2038
2039 2039 The macro is a simple object which holds its value in an attribute,
2040 2040 but IPython's display system checks for macros and executes them as
2041 2041 code instead of printing them when you type their name.
2042 2042
2043 2043 You can view a macro's contents by explicitly printing it with:
2044 2044
2045 2045 'print macro_name'.
2046 2046
2047 2047 For one-off cases which DON'T contain magic function calls in them you
2048 2048 can obtain similar results by explicitly executing slices from your
2049 2049 input history with:
2050 2050
2051 2051 In [60]: exec In[44:48]+In[49]"""
2052 2052
2053 2053 opts,args = self.parse_options(parameter_s,'r',mode='list')
2054 2054 if not args:
2055 2055 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2056 2056 macs.sort()
2057 2057 return macs
2058 2058 if len(args) == 1:
2059 2059 raise UsageError(
2060 2060 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2061 2061 name,ranges = args[0], args[1:]
2062 2062
2063 2063 #print 'rng',ranges # dbg
2064 2064 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2065 2065 macro = Macro(lines)
2066 2066 self.shell.user_ns.update({name:macro})
2067 2067 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2068 2068 print 'Macro contents:'
2069 2069 print macro,
2070 2070
2071 2071 def magic_save(self,parameter_s = ''):
2072 2072 """Save a set of lines to a given filename.
2073 2073
2074 2074 Usage:\\
2075 2075 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2076 2076
2077 2077 Options:
2078 2078
2079 2079 -r: use 'raw' input. By default, the 'processed' history is used,
2080 2080 so that magics are loaded in their transformed version to valid
2081 2081 Python. If this option is given, the raw input as typed as the
2082 2082 command line is used instead.
2083 2083
2084 2084 This function uses the same syntax as %macro for line extraction, but
2085 2085 instead of creating a macro it saves the resulting string to the
2086 2086 filename you specify.
2087 2087
2088 2088 It adds a '.py' extension to the file if you don't do so yourself, and
2089 2089 it asks for confirmation before overwriting existing files."""
2090 2090
2091 2091 opts,args = self.parse_options(parameter_s,'r',mode='list')
2092 2092 fname,ranges = args[0], args[1:]
2093 2093 if not fname.endswith('.py'):
2094 2094 fname += '.py'
2095 2095 if os.path.isfile(fname):
2096 2096 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2097 2097 if ans.lower() not in ['y','yes']:
2098 2098 print 'Operation cancelled.'
2099 2099 return
2100 2100 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2101 2101 f = file(fname,'w')
2102 2102 f.write(cmds)
2103 2103 f.close()
2104 2104 print 'The following commands were written to file `%s`:' % fname
2105 2105 print cmds
2106 2106
2107 2107 def _edit_macro(self,mname,macro):
2108 2108 """open an editor with the macro data in a file"""
2109 2109 filename = self.shell.mktempfile(macro.value)
2110 2110 self.shell.hooks.editor(filename)
2111 2111
2112 2112 # and make a new macro object, to replace the old one
2113 2113 mfile = open(filename)
2114 2114 mvalue = mfile.read()
2115 2115 mfile.close()
2116 2116 self.shell.user_ns[mname] = Macro(mvalue)
2117 2117
2118 2118 def magic_ed(self,parameter_s=''):
2119 2119 """Alias to %edit."""
2120 2120 return self.magic_edit(parameter_s)
2121 2121
2122 2122 @testdec.skip_doctest
2123 2123 def magic_edit(self,parameter_s='',last_call=['','']):
2124 2124 """Bring up an editor and execute the resulting code.
2125 2125
2126 2126 Usage:
2127 2127 %edit [options] [args]
2128 2128
2129 2129 %edit runs IPython's editor hook. The default version of this hook is
2130 2130 set to call the __IPYTHON__.rc.editor command. This is read from your
2131 2131 environment variable $EDITOR. If this isn't found, it will default to
2132 2132 vi under Linux/Unix and to notepad under Windows. See the end of this
2133 2133 docstring for how to change the editor hook.
2134 2134
2135 2135 You can also set the value of this editor via the command line option
2136 2136 '-editor' or in your ipythonrc file. This is useful if you wish to use
2137 2137 specifically for IPython an editor different from your typical default
2138 2138 (and for Windows users who typically don't set environment variables).
2139 2139
2140 2140 This command allows you to conveniently edit multi-line code right in
2141 2141 your IPython session.
2142 2142
2143 2143 If called without arguments, %edit opens up an empty editor with a
2144 2144 temporary file and will execute the contents of this file when you
2145 2145 close it (don't forget to save it!).
2146 2146
2147 2147
2148 2148 Options:
2149 2149
2150 2150 -n <number>: open the editor at a specified line number. By default,
2151 2151 the IPython editor hook uses the unix syntax 'editor +N filename', but
2152 2152 you can configure this by providing your own modified hook if your
2153 2153 favorite editor supports line-number specifications with a different
2154 2154 syntax.
2155 2155
2156 2156 -p: this will call the editor with the same data as the previous time
2157 2157 it was used, regardless of how long ago (in your current session) it
2158 2158 was.
2159 2159
2160 2160 -r: use 'raw' input. This option only applies to input taken from the
2161 2161 user's history. By default, the 'processed' history is used, so that
2162 2162 magics are loaded in their transformed version to valid Python. If
2163 2163 this option is given, the raw input as typed as the command line is
2164 2164 used instead. When you exit the editor, it will be executed by
2165 2165 IPython's own processor.
2166 2166
2167 2167 -x: do not execute the edited code immediately upon exit. This is
2168 2168 mainly useful if you are editing programs which need to be called with
2169 2169 command line arguments, which you can then do using %run.
2170 2170
2171 2171
2172 2172 Arguments:
2173 2173
2174 2174 If arguments are given, the following possibilites exist:
2175 2175
2176 2176 - The arguments are numbers or pairs of colon-separated numbers (like
2177 2177 1 4:8 9). These are interpreted as lines of previous input to be
2178 2178 loaded into the editor. The syntax is the same of the %macro command.
2179 2179
2180 2180 - If the argument doesn't start with a number, it is evaluated as a
2181 2181 variable and its contents loaded into the editor. You can thus edit
2182 2182 any string which contains python code (including the result of
2183 2183 previous edits).
2184 2184
2185 2185 - If the argument is the name of an object (other than a string),
2186 2186 IPython will try to locate the file where it was defined and open the
2187 2187 editor at the point where it is defined. You can use `%edit function`
2188 2188 to load an editor exactly at the point where 'function' is defined,
2189 2189 edit it and have the file be executed automatically.
2190 2190
2191 2191 If the object is a macro (see %macro for details), this opens up your
2192 2192 specified editor with a temporary file containing the macro's data.
2193 2193 Upon exit, the macro is reloaded with the contents of the file.
2194 2194
2195 2195 Note: opening at an exact line is only supported under Unix, and some
2196 2196 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2197 2197 '+NUMBER' parameter necessary for this feature. Good editors like
2198 2198 (X)Emacs, vi, jed, pico and joe all do.
2199 2199
2200 2200 - If the argument is not found as a variable, IPython will look for a
2201 2201 file with that name (adding .py if necessary) and load it into the
2202 2202 editor. It will execute its contents with execfile() when you exit,
2203 2203 loading any code in the file into your interactive namespace.
2204 2204
2205 2205 After executing your code, %edit will return as output the code you
2206 2206 typed in the editor (except when it was an existing file). This way
2207 2207 you can reload the code in further invocations of %edit as a variable,
2208 2208 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2209 2209 the output.
2210 2210
2211 2211 Note that %edit is also available through the alias %ed.
2212 2212
2213 2213 This is an example of creating a simple function inside the editor and
2214 2214 then modifying it. First, start up the editor:
2215 2215
2216 2216 In [1]: ed
2217 2217 Editing... done. Executing edited code...
2218 2218 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2219 2219
2220 2220 We can then call the function foo():
2221 2221
2222 2222 In [2]: foo()
2223 2223 foo() was defined in an editing session
2224 2224
2225 2225 Now we edit foo. IPython automatically loads the editor with the
2226 2226 (temporary) file where foo() was previously defined:
2227 2227
2228 2228 In [3]: ed foo
2229 2229 Editing... done. Executing edited code...
2230 2230
2231 2231 And if we call foo() again we get the modified version:
2232 2232
2233 2233 In [4]: foo()
2234 2234 foo() has now been changed!
2235 2235
2236 2236 Here is an example of how to edit a code snippet successive
2237 2237 times. First we call the editor:
2238 2238
2239 2239 In [5]: ed
2240 2240 Editing... done. Executing edited code...
2241 2241 hello
2242 2242 Out[5]: "print 'hello'n"
2243 2243
2244 2244 Now we call it again with the previous output (stored in _):
2245 2245
2246 2246 In [6]: ed _
2247 2247 Editing... done. Executing edited code...
2248 2248 hello world
2249 2249 Out[6]: "print 'hello world'n"
2250 2250
2251 2251 Now we call it with the output #8 (stored in _8, also as Out[8]):
2252 2252
2253 2253 In [7]: ed _8
2254 2254 Editing... done. Executing edited code...
2255 2255 hello again
2256 2256 Out[7]: "print 'hello again'n"
2257 2257
2258 2258
2259 2259 Changing the default editor hook:
2260 2260
2261 2261 If you wish to write your own editor hook, you can put it in a
2262 2262 configuration file which you load at startup time. The default hook
2263 2263 is defined in the IPython.core.hooks module, and you can use that as a
2264 2264 starting example for further modifications. That file also has
2265 2265 general instructions on how to set a new hook for use once you've
2266 2266 defined it."""
2267 2267
2268 2268 # FIXME: This function has become a convoluted mess. It needs a
2269 2269 # ground-up rewrite with clean, simple logic.
2270 2270
2271 2271 def make_filename(arg):
2272 2272 "Make a filename from the given args"
2273 2273 try:
2274 2274 filename = get_py_filename(arg)
2275 2275 except IOError:
2276 2276 if args.endswith('.py'):
2277 2277 filename = arg
2278 2278 else:
2279 2279 filename = None
2280 2280 return filename
2281 2281
2282 2282 # custom exceptions
2283 2283 class DataIsObject(Exception): pass
2284 2284
2285 2285 opts,args = self.parse_options(parameter_s,'prxn:')
2286 2286 # Set a few locals from the options for convenience:
2287 2287 opts_p = opts.has_key('p')
2288 2288 opts_r = opts.has_key('r')
2289 2289
2290 2290 # Default line number value
2291 2291 lineno = opts.get('n',None)
2292 2292
2293 2293 if opts_p:
2294 2294 args = '_%s' % last_call[0]
2295 2295 if not self.shell.user_ns.has_key(args):
2296 2296 args = last_call[1]
2297 2297
2298 2298 # use last_call to remember the state of the previous call, but don't
2299 2299 # let it be clobbered by successive '-p' calls.
2300 2300 try:
2301 2301 last_call[0] = self.shell.outputcache.prompt_count
2302 2302 if not opts_p:
2303 2303 last_call[1] = parameter_s
2304 2304 except:
2305 2305 pass
2306 2306
2307 2307 # by default this is done with temp files, except when the given
2308 2308 # arg is a filename
2309 2309 use_temp = 1
2310 2310
2311 2311 if re.match(r'\d',args):
2312 2312 # Mode where user specifies ranges of lines, like in %macro.
2313 2313 # This means that you can't edit files whose names begin with
2314 2314 # numbers this way. Tough.
2315 2315 ranges = args.split()
2316 2316 data = ''.join(self.extract_input_slices(ranges,opts_r))
2317 2317 elif args.endswith('.py'):
2318 2318 filename = make_filename(args)
2319 2319 data = ''
2320 2320 use_temp = 0
2321 2321 elif args:
2322 2322 try:
2323 2323 # Load the parameter given as a variable. If not a string,
2324 2324 # process it as an object instead (below)
2325 2325
2326 2326 #print '*** args',args,'type',type(args) # dbg
2327 2327 data = eval(args,self.shell.user_ns)
2328 2328 if not type(data) in StringTypes:
2329 2329 raise DataIsObject
2330 2330
2331 2331 except (NameError,SyntaxError):
2332 2332 # given argument is not a variable, try as a filename
2333 2333 filename = make_filename(args)
2334 2334 if filename is None:
2335 2335 warn("Argument given (%s) can't be found as a variable "
2336 2336 "or as a filename." % args)
2337 2337 return
2338 2338
2339 2339 data = ''
2340 2340 use_temp = 0
2341 2341 except DataIsObject:
2342 2342
2343 2343 # macros have a special edit function
2344 2344 if isinstance(data,Macro):
2345 2345 self._edit_macro(args,data)
2346 2346 return
2347 2347
2348 2348 # For objects, try to edit the file where they are defined
2349 2349 try:
2350 2350 filename = inspect.getabsfile(data)
2351 2351 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2352 2352 # class created by %edit? Try to find source
2353 2353 # by looking for method definitions instead, the
2354 2354 # __module__ in those classes is FakeModule.
2355 2355 attrs = [getattr(data, aname) for aname in dir(data)]
2356 2356 for attr in attrs:
2357 2357 if not inspect.ismethod(attr):
2358 2358 continue
2359 2359 filename = inspect.getabsfile(attr)
2360 2360 if filename and 'fakemodule' not in filename.lower():
2361 2361 # change the attribute to be the edit target instead
2362 2362 data = attr
2363 2363 break
2364 2364
2365 2365 datafile = 1
2366 2366 except TypeError:
2367 2367 filename = make_filename(args)
2368 2368 datafile = 1
2369 2369 warn('Could not find file where `%s` is defined.\n'
2370 2370 'Opening a file named `%s`' % (args,filename))
2371 2371 # Now, make sure we can actually read the source (if it was in
2372 2372 # a temp file it's gone by now).
2373 2373 if datafile:
2374 2374 try:
2375 2375 if lineno is None:
2376 2376 lineno = inspect.getsourcelines(data)[1]
2377 2377 except IOError:
2378 2378 filename = make_filename(args)
2379 2379 if filename is None:
2380 2380 warn('The file `%s` where `%s` was defined cannot '
2381 2381 'be read.' % (filename,data))
2382 2382 return
2383 2383 use_temp = 0
2384 2384 else:
2385 2385 data = ''
2386 2386
2387 2387 if use_temp:
2388 2388 filename = self.shell.mktempfile(data)
2389 2389 print 'IPython will make a temporary file named:',filename
2390 2390
2391 2391 # do actual editing here
2392 2392 print 'Editing...',
2393 2393 sys.stdout.flush()
2394 2394 try:
2395 2395 self.shell.hooks.editor(filename,lineno)
2396 2396 except ipapi.TryNext:
2397 2397 warn('Could not open editor')
2398 2398 return
2399 2399
2400 2400 # XXX TODO: should this be generalized for all string vars?
2401 2401 # For now, this is special-cased to blocks created by cpaste
2402 2402 if args.strip() == 'pasted_block':
2403 2403 self.shell.user_ns['pasted_block'] = file_read(filename)
2404 2404
2405 2405 if opts.has_key('x'): # -x prevents actual execution
2406 2406 print
2407 2407 else:
2408 2408 print 'done. Executing edited code...'
2409 2409 if opts_r:
2410 2410 self.shell.runlines(file_read(filename))
2411 2411 else:
2412 2412 self.shell.safe_execfile(filename,self.shell.user_ns,
2413 2413 self.shell.user_ns)
2414 2414
2415 2415
2416 2416 if use_temp:
2417 2417 try:
2418 2418 return open(filename).read()
2419 2419 except IOError,msg:
2420 2420 if msg.filename == filename:
2421 2421 warn('File not found. Did you forget to save?')
2422 2422 return
2423 2423 else:
2424 2424 self.shell.showtraceback()
2425 2425
2426 2426 def magic_xmode(self,parameter_s = ''):
2427 2427 """Switch modes for the exception handlers.
2428 2428
2429 2429 Valid modes: Plain, Context and Verbose.
2430 2430
2431 2431 If called without arguments, acts as a toggle."""
2432 2432
2433 2433 def xmode_switch_err(name):
2434 2434 warn('Error changing %s exception modes.\n%s' %
2435 2435 (name,sys.exc_info()[1]))
2436 2436
2437 2437 shell = self.shell
2438 2438 new_mode = parameter_s.strip().capitalize()
2439 2439 try:
2440 2440 shell.InteractiveTB.set_mode(mode=new_mode)
2441 2441 print 'Exception reporting mode:',shell.InteractiveTB.mode
2442 2442 except:
2443 2443 xmode_switch_err('user')
2444 2444
2445 2445 # threaded shells use a special handler in sys.excepthook
2446 2446 if shell.isthreaded:
2447 2447 try:
2448 2448 shell.sys_excepthook.set_mode(mode=new_mode)
2449 2449 except:
2450 2450 xmode_switch_err('threaded')
2451 2451
2452 2452 def magic_colors(self,parameter_s = ''):
2453 2453 """Switch color scheme for prompts, info system and exception handlers.
2454 2454
2455 2455 Currently implemented schemes: NoColor, Linux, LightBG.
2456 2456
2457 2457 Color scheme names are not case-sensitive."""
2458 2458
2459 2459 def color_switch_err(name):
2460 2460 warn('Error changing %s color schemes.\n%s' %
2461 2461 (name,sys.exc_info()[1]))
2462 2462
2463 2463
2464 2464 new_scheme = parameter_s.strip()
2465 2465 if not new_scheme:
2466 2466 raise UsageError(
2467 2467 "%colors: you must specify a color scheme. See '%colors?'")
2468 2468 return
2469 2469 # local shortcut
2470 2470 shell = self.shell
2471 2471
2472 2472 import IPython.utils.rlineimpl as readline
2473 2473
2474 2474 if not readline.have_readline and sys.platform == "win32":
2475 2475 msg = """\
2476 2476 Proper color support under MS Windows requires the pyreadline library.
2477 2477 You can find it at:
2478 2478 http://ipython.scipy.org/moin/PyReadline/Intro
2479 2479 Gary's readline needs the ctypes module, from:
2480 2480 http://starship.python.net/crew/theller/ctypes
2481 2481 (Note that ctypes is already part of Python versions 2.5 and newer).
2482 2482
2483 2483 Defaulting color scheme to 'NoColor'"""
2484 2484 new_scheme = 'NoColor'
2485 2485 warn(msg)
2486 2486
2487 2487 # readline option is 0
2488 2488 if not shell.has_readline:
2489 2489 new_scheme = 'NoColor'
2490 2490
2491 2491 # Set prompt colors
2492 2492 try:
2493 2493 shell.outputcache.set_colors(new_scheme)
2494 2494 except:
2495 2495 color_switch_err('prompt')
2496 2496 else:
2497 2497 shell.colors = \
2498 2498 shell.outputcache.color_table.active_scheme_name
2499 2499 # Set exception colors
2500 2500 try:
2501 2501 shell.InteractiveTB.set_colors(scheme = new_scheme)
2502 2502 shell.SyntaxTB.set_colors(scheme = new_scheme)
2503 2503 except:
2504 2504 color_switch_err('exception')
2505 2505
2506 2506 # threaded shells use a verbose traceback in sys.excepthook
2507 2507 if shell.isthreaded:
2508 2508 try:
2509 2509 shell.sys_excepthook.set_colors(scheme=new_scheme)
2510 2510 except:
2511 2511 color_switch_err('system exception handler')
2512 2512
2513 2513 # Set info (for 'object?') colors
2514 2514 if shell.color_info:
2515 2515 try:
2516 2516 shell.inspector.set_active_scheme(new_scheme)
2517 2517 except:
2518 2518 color_switch_err('object inspector')
2519 2519 else:
2520 2520 shell.inspector.set_active_scheme('NoColor')
2521 2521
2522 2522 def magic_color_info(self,parameter_s = ''):
2523 2523 """Toggle color_info.
2524 2524
2525 2525 The color_info configuration parameter controls whether colors are
2526 2526 used for displaying object details (by things like %psource, %pfile or
2527 2527 the '?' system). This function toggles this value with each call.
2528 2528
2529 2529 Note that unless you have a fairly recent pager (less works better
2530 2530 than more) in your system, using colored object information displays
2531 2531 will not work properly. Test it and see."""
2532 2532
2533 2533 self.shell.color_info = not self.shell.color_info
2534 2534 self.magic_colors(self.shell.colors)
2535 2535 print 'Object introspection functions have now coloring:',
2536 2536 print ['OFF','ON'][int(self.shell.color_info)]
2537 2537
2538 2538 def magic_Pprint(self, parameter_s=''):
2539 2539 """Toggle pretty printing on/off."""
2540 2540
2541 2541 self.shell.pprint = 1 - self.shell.pprint
2542 2542 print 'Pretty printing has been turned', \
2543 2543 ['OFF','ON'][self.shell.pprint]
2544 2544
2545 2545 def magic_exit(self, parameter_s=''):
2546 2546 """Exit IPython, confirming if configured to do so.
2547 2547
2548 2548 You can configure whether IPython asks for confirmation upon exit by
2549 2549 setting the confirm_exit flag in the ipythonrc file."""
2550 2550
2551 2551 self.shell.exit()
2552 2552
2553 2553 def magic_quit(self, parameter_s=''):
2554 2554 """Exit IPython, confirming if configured to do so (like %exit)"""
2555 2555
2556 2556 self.shell.exit()
2557 2557
2558 2558 def magic_Exit(self, parameter_s=''):
2559 2559 """Exit IPython without confirmation."""
2560 2560
2561 2561 self.shell.ask_exit()
2562 2562
2563 2563 #......................................................................
2564 2564 # Functions to implement unix shell-type things
2565 2565
2566 2566 @testdec.skip_doctest
2567 2567 def magic_alias(self, parameter_s = ''):
2568 2568 """Define an alias for a system command.
2569 2569
2570 2570 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2571 2571
2572 2572 Then, typing 'alias_name params' will execute the system command 'cmd
2573 2573 params' (from your underlying operating system).
2574 2574
2575 2575 Aliases have lower precedence than magic functions and Python normal
2576 2576 variables, so if 'foo' is both a Python variable and an alias, the
2577 2577 alias can not be executed until 'del foo' removes the Python variable.
2578 2578
2579 2579 You can use the %l specifier in an alias definition to represent the
2580 2580 whole line when the alias is called. For example:
2581 2581
2582 2582 In [2]: alias all echo "Input in brackets: <%l>"
2583 2583 In [3]: all hello world
2584 2584 Input in brackets: <hello world>
2585 2585
2586 2586 You can also define aliases with parameters using %s specifiers (one
2587 2587 per parameter):
2588 2588
2589 2589 In [1]: alias parts echo first %s second %s
2590 2590 In [2]: %parts A B
2591 2591 first A second B
2592 2592 In [3]: %parts A
2593 2593 Incorrect number of arguments: 2 expected.
2594 2594 parts is an alias to: 'echo first %s second %s'
2595 2595
2596 2596 Note that %l and %s are mutually exclusive. You can only use one or
2597 2597 the other in your aliases.
2598 2598
2599 2599 Aliases expand Python variables just like system calls using ! or !!
2600 2600 do: all expressions prefixed with '$' get expanded. For details of
2601 2601 the semantic rules, see PEP-215:
2602 2602 http://www.python.org/peps/pep-0215.html. This is the library used by
2603 2603 IPython for variable expansion. If you want to access a true shell
2604 2604 variable, an extra $ is necessary to prevent its expansion by IPython:
2605 2605
2606 2606 In [6]: alias show echo
2607 2607 In [7]: PATH='A Python string'
2608 2608 In [8]: show $PATH
2609 2609 A Python string
2610 2610 In [9]: show $$PATH
2611 2611 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2612 2612
2613 2613 You can use the alias facility to acess all of $PATH. See the %rehash
2614 2614 and %rehashx functions, which automatically create aliases for the
2615 2615 contents of your $PATH.
2616 2616
2617 2617 If called with no parameters, %alias prints the current alias table."""
2618 2618
2619 2619 par = parameter_s.strip()
2620 2620 if not par:
2621 2621 stored = self.db.get('stored_aliases', {} )
2622 2622 atab = self.shell.alias_table
2623 2623 aliases = atab.keys()
2624 2624 aliases.sort()
2625 2625 res = []
2626 2626 showlast = []
2627 2627 for alias in aliases:
2628 2628 special = False
2629 2629 try:
2630 2630 tgt = atab[alias][1]
2631 2631 except (TypeError, AttributeError):
2632 2632 # unsubscriptable? probably a callable
2633 2633 tgt = atab[alias]
2634 2634 special = True
2635 2635 # 'interesting' aliases
2636 2636 if (alias in stored or
2637 2637 special or
2638 2638 alias.lower() != os.path.splitext(tgt)[0].lower() or
2639 2639 ' ' in tgt):
2640 2640 showlast.append((alias, tgt))
2641 2641 else:
2642 2642 res.append((alias, tgt ))
2643 2643
2644 2644 # show most interesting aliases last
2645 2645 res.extend(showlast)
2646 2646 print "Total number of aliases:",len(aliases)
2647 2647 return res
2648 2648 try:
2649 2649 alias,cmd = par.split(None,1)
2650 2650 except:
2651 2651 print oinspect.getdoc(self.magic_alias)
2652 2652 else:
2653 2653 nargs = cmd.count('%s')
2654 2654 if nargs>0 and cmd.find('%l')>=0:
2655 2655 error('The %s and %l specifiers are mutually exclusive '
2656 2656 'in alias definitions.')
2657 2657 else: # all looks OK
2658 2658 self.shell.alias_table[alias] = (nargs,cmd)
2659 2659 self.shell.alias_table_validate(verbose=0)
2660 2660 # end magic_alias
2661 2661
2662 2662 def magic_unalias(self, parameter_s = ''):
2663 2663 """Remove an alias"""
2664 2664
2665 2665 aname = parameter_s.strip()
2666 2666 if aname in self.shell.alias_table:
2667 2667 del self.shell.alias_table[aname]
2668 2668 stored = self.db.get('stored_aliases', {} )
2669 2669 if aname in stored:
2670 2670 print "Removing %stored alias",aname
2671 2671 del stored[aname]
2672 2672 self.db['stored_aliases'] = stored
2673 2673
2674 2674
2675 2675 def magic_rehashx(self, parameter_s = ''):
2676 2676 """Update the alias table with all executable files in $PATH.
2677 2677
2678 2678 This version explicitly checks that every entry in $PATH is a file
2679 2679 with execute access (os.X_OK), so it is much slower than %rehash.
2680 2680
2681 2681 Under Windows, it checks executability as a match agains a
2682 2682 '|'-separated string of extensions, stored in the IPython config
2683 2683 variable win_exec_ext. This defaults to 'exe|com|bat'.
2684 2684
2685 2685 This function also resets the root module cache of module completer,
2686 2686 used on slow filesystems.
2687 2687 """
2688 2688
2689 2689
2690 2690 ip = self.api
2691 2691
2692 2692 # for the benefit of module completer in ipy_completers.py
2693 2693 del ip.db['rootmodules']
2694 2694
2695 2695 path = [os.path.abspath(os.path.expanduser(p)) for p in
2696 2696 os.environ.get('PATH','').split(os.pathsep)]
2697 2697 path = filter(os.path.isdir,path)
2698 2698
2699 2699 alias_table = self.shell.alias_table
2700 2700 syscmdlist = []
2701 2701 if os.name == 'posix':
2702 2702 isexec = lambda fname:os.path.isfile(fname) and \
2703 2703 os.access(fname,os.X_OK)
2704 2704 else:
2705 2705
2706 2706 try:
2707 2707 winext = os.environ['pathext'].replace(';','|').replace('.','')
2708 2708 except KeyError:
2709 2709 winext = 'exe|com|bat|py'
2710 2710 if 'py' not in winext:
2711 2711 winext += '|py'
2712 2712 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2713 2713 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2714 2714 savedir = os.getcwd()
2715 2715 try:
2716 2716 # write the whole loop for posix/Windows so we don't have an if in
2717 2717 # the innermost part
2718 2718 if os.name == 'posix':
2719 2719 for pdir in path:
2720 2720 os.chdir(pdir)
2721 2721 for ff in os.listdir(pdir):
2722 2722 if isexec(ff) and ff not in self.shell.no_alias:
2723 2723 # each entry in the alias table must be (N,name),
2724 2724 # where N is the number of positional arguments of the
2725 2725 # alias.
2726 2726 # Dots will be removed from alias names, since ipython
2727 2727 # assumes names with dots to be python code
2728 2728 alias_table[ff.replace('.','')] = (0,ff)
2729 2729 syscmdlist.append(ff)
2730 2730 else:
2731 2731 for pdir in path:
2732 2732 os.chdir(pdir)
2733 2733 for ff in os.listdir(pdir):
2734 2734 base, ext = os.path.splitext(ff)
2735 2735 if isexec(ff) and base.lower() not in self.shell.no_alias:
2736 2736 if ext.lower() == '.exe':
2737 2737 ff = base
2738 2738 alias_table[base.lower().replace('.','')] = (0,ff)
2739 2739 syscmdlist.append(ff)
2740 2740 # Make sure the alias table doesn't contain keywords or builtins
2741 2741 self.shell.alias_table_validate()
2742 2742 # Call again init_auto_alias() so we get 'rm -i' and other
2743 2743 # modified aliases since %rehashx will probably clobber them
2744 2744
2745 2745 # no, we don't want them. if %rehashx clobbers them, good,
2746 2746 # we'll probably get better versions
2747 2747 # self.shell.init_auto_alias()
2748 2748 db = ip.db
2749 2749 db['syscmdlist'] = syscmdlist
2750 2750 finally:
2751 2751 os.chdir(savedir)
2752 2752
2753 2753 def magic_pwd(self, parameter_s = ''):
2754 2754 """Return the current working directory path."""
2755 2755 return os.getcwd()
2756 2756
2757 2757 def magic_cd(self, parameter_s=''):
2758 2758 """Change the current working directory.
2759 2759
2760 2760 This command automatically maintains an internal list of directories
2761 2761 you visit during your IPython session, in the variable _dh. The
2762 2762 command %dhist shows this history nicely formatted. You can also
2763 2763 do 'cd -<tab>' to see directory history conveniently.
2764 2764
2765 2765 Usage:
2766 2766
2767 2767 cd 'dir': changes to directory 'dir'.
2768 2768
2769 2769 cd -: changes to the last visited directory.
2770 2770
2771 2771 cd -<n>: changes to the n-th directory in the directory history.
2772 2772
2773 2773 cd --foo: change to directory that matches 'foo' in history
2774 2774
2775 2775 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2776 2776 (note: cd <bookmark_name> is enough if there is no
2777 2777 directory <bookmark_name>, but a bookmark with the name exists.)
2778 2778 'cd -b <tab>' allows you to tab-complete bookmark names.
2779 2779
2780 2780 Options:
2781 2781
2782 2782 -q: quiet. Do not print the working directory after the cd command is
2783 2783 executed. By default IPython's cd command does print this directory,
2784 2784 since the default prompts do not display path information.
2785 2785
2786 2786 Note that !cd doesn't work for this purpose because the shell where
2787 2787 !command runs is immediately discarded after executing 'command'."""
2788 2788
2789 2789 parameter_s = parameter_s.strip()
2790 2790 #bkms = self.shell.persist.get("bookmarks",{})
2791 2791
2792 2792 oldcwd = os.getcwd()
2793 2793 numcd = re.match(r'(-)(\d+)$',parameter_s)
2794 2794 # jump in directory history by number
2795 2795 if numcd:
2796 2796 nn = int(numcd.group(2))
2797 2797 try:
2798 2798 ps = self.shell.user_ns['_dh'][nn]
2799 2799 except IndexError:
2800 2800 print 'The requested directory does not exist in history.'
2801 2801 return
2802 2802 else:
2803 2803 opts = {}
2804 2804 elif parameter_s.startswith('--'):
2805 2805 ps = None
2806 2806 fallback = None
2807 2807 pat = parameter_s[2:]
2808 2808 dh = self.shell.user_ns['_dh']
2809 2809 # first search only by basename (last component)
2810 2810 for ent in reversed(dh):
2811 2811 if pat in os.path.basename(ent) and os.path.isdir(ent):
2812 2812 ps = ent
2813 2813 break
2814 2814
2815 2815 if fallback is None and pat in ent and os.path.isdir(ent):
2816 2816 fallback = ent
2817 2817
2818 2818 # if we have no last part match, pick the first full path match
2819 2819 if ps is None:
2820 2820 ps = fallback
2821 2821
2822 2822 if ps is None:
2823 2823 print "No matching entry in directory history"
2824 2824 return
2825 2825 else:
2826 2826 opts = {}
2827 2827
2828 2828
2829 2829 else:
2830 2830 #turn all non-space-escaping backslashes to slashes,
2831 2831 # for c:\windows\directory\names\
2832 2832 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2833 2833 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2834 2834 # jump to previous
2835 2835 if ps == '-':
2836 2836 try:
2837 2837 ps = self.shell.user_ns['_dh'][-2]
2838 2838 except IndexError:
2839 2839 raise UsageError('%cd -: No previous directory to change to.')
2840 2840 # jump to bookmark if needed
2841 2841 else:
2842 2842 if not os.path.isdir(ps) or opts.has_key('b'):
2843 2843 bkms = self.db.get('bookmarks', {})
2844 2844
2845 2845 if bkms.has_key(ps):
2846 2846 target = bkms[ps]
2847 2847 print '(bookmark:%s) -> %s' % (ps,target)
2848 2848 ps = target
2849 2849 else:
2850 2850 if opts.has_key('b'):
2851 2851 raise UsageError("Bookmark '%s' not found. "
2852 2852 "Use '%%bookmark -l' to see your bookmarks." % ps)
2853 2853
2854 2854 # at this point ps should point to the target dir
2855 2855 if ps:
2856 2856 try:
2857 2857 os.chdir(os.path.expanduser(ps))
2858 2858 if self.shell.term_title:
2859 #print 'set term title:',self.shell.term_title # dbg
2860 platutils.set_term_title('IPy ' + abbrev_cwd())
2859 platutils.set_term_title('IPython: ' + abbrev_cwd())
2861 2860 except OSError:
2862 2861 print sys.exc_info()[1]
2863 2862 else:
2864 2863 cwd = os.getcwd()
2865 2864 dhist = self.shell.user_ns['_dh']
2866 2865 if oldcwd != cwd:
2867 2866 dhist.append(cwd)
2868 2867 self.db['dhist'] = compress_dhist(dhist)[-100:]
2869 2868
2870 2869 else:
2871 2870 os.chdir(self.shell.home_dir)
2872 2871 if self.shell.term_title:
2873 platutils.set_term_title("IPy ~")
2872 platutils.set_term_title('IPython: ' + '~')
2874 2873 cwd = os.getcwd()
2875 2874 dhist = self.shell.user_ns['_dh']
2876 2875
2877 2876 if oldcwd != cwd:
2878 2877 dhist.append(cwd)
2879 2878 self.db['dhist'] = compress_dhist(dhist)[-100:]
2880 2879 if not 'q' in opts and self.shell.user_ns['_dh']:
2881 2880 print self.shell.user_ns['_dh'][-1]
2882 2881
2883 2882
2884 2883 def magic_env(self, parameter_s=''):
2885 2884 """List environment variables."""
2886 2885
2887 2886 return os.environ.data
2888 2887
2889 2888 def magic_pushd(self, parameter_s=''):
2890 2889 """Place the current dir on stack and change directory.
2891 2890
2892 2891 Usage:\\
2893 2892 %pushd ['dirname']
2894 2893 """
2895 2894
2896 2895 dir_s = self.shell.dir_stack
2897 2896 tgt = os.path.expanduser(parameter_s)
2898 2897 cwd = os.getcwd().replace(self.home_dir,'~')
2899 2898 if tgt:
2900 2899 self.magic_cd(parameter_s)
2901 2900 dir_s.insert(0,cwd)
2902 2901 return self.magic_dirs()
2903 2902
2904 2903 def magic_popd(self, parameter_s=''):
2905 2904 """Change to directory popped off the top of the stack.
2906 2905 """
2907 2906 if not self.shell.dir_stack:
2908 2907 raise UsageError("%popd on empty stack")
2909 2908 top = self.shell.dir_stack.pop(0)
2910 2909 self.magic_cd(top)
2911 2910 print "popd ->",top
2912 2911
2913 2912 def magic_dirs(self, parameter_s=''):
2914 2913 """Return the current directory stack."""
2915 2914
2916 2915 return self.shell.dir_stack
2917 2916
2918 2917 def magic_dhist(self, parameter_s=''):
2919 2918 """Print your history of visited directories.
2920 2919
2921 2920 %dhist -> print full history\\
2922 2921 %dhist n -> print last n entries only\\
2923 2922 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2924 2923
2925 2924 This history is automatically maintained by the %cd command, and
2926 2925 always available as the global list variable _dh. You can use %cd -<n>
2927 2926 to go to directory number <n>.
2928 2927
2929 2928 Note that most of time, you should view directory history by entering
2930 2929 cd -<TAB>.
2931 2930
2932 2931 """
2933 2932
2934 2933 dh = self.shell.user_ns['_dh']
2935 2934 if parameter_s:
2936 2935 try:
2937 2936 args = map(int,parameter_s.split())
2938 2937 except:
2939 2938 self.arg_err(Magic.magic_dhist)
2940 2939 return
2941 2940 if len(args) == 1:
2942 2941 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2943 2942 elif len(args) == 2:
2944 2943 ini,fin = args
2945 2944 else:
2946 2945 self.arg_err(Magic.magic_dhist)
2947 2946 return
2948 2947 else:
2949 2948 ini,fin = 0,len(dh)
2950 2949 nlprint(dh,
2951 2950 header = 'Directory history (kept in _dh)',
2952 2951 start=ini,stop=fin)
2953 2952
2954 2953 @testdec.skip_doctest
2955 2954 def magic_sc(self, parameter_s=''):
2956 2955 """Shell capture - execute a shell command and capture its output.
2957 2956
2958 2957 DEPRECATED. Suboptimal, retained for backwards compatibility.
2959 2958
2960 2959 You should use the form 'var = !command' instead. Example:
2961 2960
2962 2961 "%sc -l myfiles = ls ~" should now be written as
2963 2962
2964 2963 "myfiles = !ls ~"
2965 2964
2966 2965 myfiles.s, myfiles.l and myfiles.n still apply as documented
2967 2966 below.
2968 2967
2969 2968 --
2970 2969 %sc [options] varname=command
2971 2970
2972 2971 IPython will run the given command using commands.getoutput(), and
2973 2972 will then update the user's interactive namespace with a variable
2974 2973 called varname, containing the value of the call. Your command can
2975 2974 contain shell wildcards, pipes, etc.
2976 2975
2977 2976 The '=' sign in the syntax is mandatory, and the variable name you
2978 2977 supply must follow Python's standard conventions for valid names.
2979 2978
2980 2979 (A special format without variable name exists for internal use)
2981 2980
2982 2981 Options:
2983 2982
2984 2983 -l: list output. Split the output on newlines into a list before
2985 2984 assigning it to the given variable. By default the output is stored
2986 2985 as a single string.
2987 2986
2988 2987 -v: verbose. Print the contents of the variable.
2989 2988
2990 2989 In most cases you should not need to split as a list, because the
2991 2990 returned value is a special type of string which can automatically
2992 2991 provide its contents either as a list (split on newlines) or as a
2993 2992 space-separated string. These are convenient, respectively, either
2994 2993 for sequential processing or to be passed to a shell command.
2995 2994
2996 2995 For example:
2997 2996
2998 2997 # all-random
2999 2998
3000 2999 # Capture into variable a
3001 3000 In [1]: sc a=ls *py
3002 3001
3003 3002 # a is a string with embedded newlines
3004 3003 In [2]: a
3005 3004 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3006 3005
3007 3006 # which can be seen as a list:
3008 3007 In [3]: a.l
3009 3008 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3010 3009
3011 3010 # or as a whitespace-separated string:
3012 3011 In [4]: a.s
3013 3012 Out[4]: 'setup.py win32_manual_post_install.py'
3014 3013
3015 3014 # a.s is useful to pass as a single command line:
3016 3015 In [5]: !wc -l $a.s
3017 3016 146 setup.py
3018 3017 130 win32_manual_post_install.py
3019 3018 276 total
3020 3019
3021 3020 # while the list form is useful to loop over:
3022 3021 In [6]: for f in a.l:
3023 3022 ...: !wc -l $f
3024 3023 ...:
3025 3024 146 setup.py
3026 3025 130 win32_manual_post_install.py
3027 3026
3028 3027 Similiarly, the lists returned by the -l option are also special, in
3029 3028 the sense that you can equally invoke the .s attribute on them to
3030 3029 automatically get a whitespace-separated string from their contents:
3031 3030
3032 3031 In [7]: sc -l b=ls *py
3033 3032
3034 3033 In [8]: b
3035 3034 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3036 3035
3037 3036 In [9]: b.s
3038 3037 Out[9]: 'setup.py win32_manual_post_install.py'
3039 3038
3040 3039 In summary, both the lists and strings used for ouptut capture have
3041 3040 the following special attributes:
3042 3041
3043 3042 .l (or .list) : value as list.
3044 3043 .n (or .nlstr): value as newline-separated string.
3045 3044 .s (or .spstr): value as space-separated string.
3046 3045 """
3047 3046
3048 3047 opts,args = self.parse_options(parameter_s,'lv')
3049 3048 # Try to get a variable name and command to run
3050 3049 try:
3051 3050 # the variable name must be obtained from the parse_options
3052 3051 # output, which uses shlex.split to strip options out.
3053 3052 var,_ = args.split('=',1)
3054 3053 var = var.strip()
3055 3054 # But the the command has to be extracted from the original input
3056 3055 # parameter_s, not on what parse_options returns, to avoid the
3057 3056 # quote stripping which shlex.split performs on it.
3058 3057 _,cmd = parameter_s.split('=',1)
3059 3058 except ValueError:
3060 3059 var,cmd = '',''
3061 3060 # If all looks ok, proceed
3062 3061 out,err = self.shell.getoutputerror(cmd)
3063 3062 if err:
3064 3063 print >> Term.cerr,err
3065 3064 if opts.has_key('l'):
3066 3065 out = SList(out.split('\n'))
3067 3066 else:
3068 3067 out = LSString(out)
3069 3068 if opts.has_key('v'):
3070 3069 print '%s ==\n%s' % (var,pformat(out))
3071 3070 if var:
3072 3071 self.shell.user_ns.update({var:out})
3073 3072 else:
3074 3073 return out
3075 3074
3076 3075 def magic_sx(self, parameter_s=''):
3077 3076 """Shell execute - run a shell command and capture its output.
3078 3077
3079 3078 %sx command
3080 3079
3081 3080 IPython will run the given command using commands.getoutput(), and
3082 3081 return the result formatted as a list (split on '\\n'). Since the
3083 3082 output is _returned_, it will be stored in ipython's regular output
3084 3083 cache Out[N] and in the '_N' automatic variables.
3085 3084
3086 3085 Notes:
3087 3086
3088 3087 1) If an input line begins with '!!', then %sx is automatically
3089 3088 invoked. That is, while:
3090 3089 !ls
3091 3090 causes ipython to simply issue system('ls'), typing
3092 3091 !!ls
3093 3092 is a shorthand equivalent to:
3094 3093 %sx ls
3095 3094
3096 3095 2) %sx differs from %sc in that %sx automatically splits into a list,
3097 3096 like '%sc -l'. The reason for this is to make it as easy as possible
3098 3097 to process line-oriented shell output via further python commands.
3099 3098 %sc is meant to provide much finer control, but requires more
3100 3099 typing.
3101 3100
3102 3101 3) Just like %sc -l, this is a list with special attributes:
3103 3102
3104 3103 .l (or .list) : value as list.
3105 3104 .n (or .nlstr): value as newline-separated string.
3106 3105 .s (or .spstr): value as whitespace-separated string.
3107 3106
3108 3107 This is very useful when trying to use such lists as arguments to
3109 3108 system commands."""
3110 3109
3111 3110 if parameter_s:
3112 3111 out,err = self.shell.getoutputerror(parameter_s)
3113 3112 if err:
3114 3113 print >> Term.cerr,err
3115 3114 return SList(out.split('\n'))
3116 3115
3117 3116 def magic_bg(self, parameter_s=''):
3118 3117 """Run a job in the background, in a separate thread.
3119 3118
3120 3119 For example,
3121 3120
3122 3121 %bg myfunc(x,y,z=1)
3123 3122
3124 3123 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3125 3124 execution starts, a message will be printed indicating the job
3126 3125 number. If your job number is 5, you can use
3127 3126
3128 3127 myvar = jobs.result(5) or myvar = jobs[5].result
3129 3128
3130 3129 to assign this result to variable 'myvar'.
3131 3130
3132 3131 IPython has a job manager, accessible via the 'jobs' object. You can
3133 3132 type jobs? to get more information about it, and use jobs.<TAB> to see
3134 3133 its attributes. All attributes not starting with an underscore are
3135 3134 meant for public use.
3136 3135
3137 3136 In particular, look at the jobs.new() method, which is used to create
3138 3137 new jobs. This magic %bg function is just a convenience wrapper
3139 3138 around jobs.new(), for expression-based jobs. If you want to create a
3140 3139 new job with an explicit function object and arguments, you must call
3141 3140 jobs.new() directly.
3142 3141
3143 3142 The jobs.new docstring also describes in detail several important
3144 3143 caveats associated with a thread-based model for background job
3145 3144 execution. Type jobs.new? for details.
3146 3145
3147 3146 You can check the status of all jobs with jobs.status().
3148 3147
3149 3148 The jobs variable is set by IPython into the Python builtin namespace.
3150 3149 If you ever declare a variable named 'jobs', you will shadow this
3151 3150 name. You can either delete your global jobs variable to regain
3152 3151 access to the job manager, or make a new name and assign it manually
3153 3152 to the manager (stored in IPython's namespace). For example, to
3154 3153 assign the job manager to the Jobs name, use:
3155 3154
3156 3155 Jobs = __builtins__.jobs"""
3157 3156
3158 3157 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3159 3158
3160 3159 def magic_r(self, parameter_s=''):
3161 3160 """Repeat previous input.
3162 3161
3163 3162 Note: Consider using the more powerfull %rep instead!
3164 3163
3165 3164 If given an argument, repeats the previous command which starts with
3166 3165 the same string, otherwise it just repeats the previous input.
3167 3166
3168 3167 Shell escaped commands (with ! as first character) are not recognized
3169 3168 by this system, only pure python code and magic commands.
3170 3169 """
3171 3170
3172 3171 start = parameter_s.strip()
3173 3172 esc_magic = self.shell.ESC_MAGIC
3174 3173 # Identify magic commands even if automagic is on (which means
3175 3174 # the in-memory version is different from that typed by the user).
3176 3175 if self.shell.automagic:
3177 3176 start_magic = esc_magic+start
3178 3177 else:
3179 3178 start_magic = start
3180 3179 # Look through the input history in reverse
3181 3180 for n in range(len(self.shell.input_hist)-2,0,-1):
3182 3181 input = self.shell.input_hist[n]
3183 3182 # skip plain 'r' lines so we don't recurse to infinity
3184 3183 if input != '_ip.magic("r")\n' and \
3185 3184 (input.startswith(start) or input.startswith(start_magic)):
3186 3185 #print 'match',`input` # dbg
3187 3186 print 'Executing:',input,
3188 3187 self.shell.runlines(input)
3189 3188 return
3190 3189 print 'No previous input matching `%s` found.' % start
3191 3190
3192 3191
3193 3192 def magic_bookmark(self, parameter_s=''):
3194 3193 """Manage IPython's bookmark system.
3195 3194
3196 3195 %bookmark <name> - set bookmark to current dir
3197 3196 %bookmark <name> <dir> - set bookmark to <dir>
3198 3197 %bookmark -l - list all bookmarks
3199 3198 %bookmark -d <name> - remove bookmark
3200 3199 %bookmark -r - remove all bookmarks
3201 3200
3202 3201 You can later on access a bookmarked folder with:
3203 3202 %cd -b <name>
3204 3203 or simply '%cd <name>' if there is no directory called <name> AND
3205 3204 there is such a bookmark defined.
3206 3205
3207 3206 Your bookmarks persist through IPython sessions, but they are
3208 3207 associated with each profile."""
3209 3208
3210 3209 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3211 3210 if len(args) > 2:
3212 3211 raise UsageError("%bookmark: too many arguments")
3213 3212
3214 3213 bkms = self.db.get('bookmarks',{})
3215 3214
3216 3215 if opts.has_key('d'):
3217 3216 try:
3218 3217 todel = args[0]
3219 3218 except IndexError:
3220 3219 raise UsageError(
3221 3220 "%bookmark -d: must provide a bookmark to delete")
3222 3221 else:
3223 3222 try:
3224 3223 del bkms[todel]
3225 3224 except KeyError:
3226 3225 raise UsageError(
3227 3226 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3228 3227
3229 3228 elif opts.has_key('r'):
3230 3229 bkms = {}
3231 3230 elif opts.has_key('l'):
3232 3231 bks = bkms.keys()
3233 3232 bks.sort()
3234 3233 if bks:
3235 3234 size = max(map(len,bks))
3236 3235 else:
3237 3236 size = 0
3238 3237 fmt = '%-'+str(size)+'s -> %s'
3239 3238 print 'Current bookmarks:'
3240 3239 for bk in bks:
3241 3240 print fmt % (bk,bkms[bk])
3242 3241 else:
3243 3242 if not args:
3244 3243 raise UsageError("%bookmark: You must specify the bookmark name")
3245 3244 elif len(args)==1:
3246 3245 bkms[args[0]] = os.getcwd()
3247 3246 elif len(args)==2:
3248 3247 bkms[args[0]] = args[1]
3249 3248 self.db['bookmarks'] = bkms
3250 3249
3251 3250 def magic_pycat(self, parameter_s=''):
3252 3251 """Show a syntax-highlighted file through a pager.
3253 3252
3254 3253 This magic is similar to the cat utility, but it will assume the file
3255 3254 to be Python source and will show it with syntax highlighting. """
3256 3255
3257 3256 try:
3258 3257 filename = get_py_filename(parameter_s)
3259 3258 cont = file_read(filename)
3260 3259 except IOError:
3261 3260 try:
3262 3261 cont = eval(parameter_s,self.user_ns)
3263 3262 except NameError:
3264 3263 cont = None
3265 3264 if cont is None:
3266 3265 print "Error: no such file or variable"
3267 3266 return
3268 3267
3269 3268 page(self.shell.pycolorize(cont),
3270 3269 screen_lines=self.shell.usable_screen_length)
3271 3270
3272 3271 def _rerun_pasted(self):
3273 3272 """ Rerun a previously pasted command.
3274 3273 """
3275 3274 b = self.user_ns.get('pasted_block', None)
3276 3275 if b is None:
3277 3276 raise UsageError('No previous pasted block available')
3278 3277 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3279 3278 exec b in self.user_ns
3280 3279
3281 3280 def _get_pasted_lines(self, sentinel):
3282 3281 """ Yield pasted lines until the user enters the given sentinel value.
3283 3282 """
3284 3283 from IPython.core import iplib
3285 3284 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3286 3285 while True:
3287 3286 l = iplib.raw_input_original(':')
3288 3287 if l == sentinel:
3289 3288 return
3290 3289 else:
3291 3290 yield l
3292 3291
3293 3292 def _strip_pasted_lines_for_code(self, raw_lines):
3294 3293 """ Strip non-code parts of a sequence of lines to return a block of
3295 3294 code.
3296 3295 """
3297 3296 # Regular expressions that declare text we strip from the input:
3298 3297 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3299 3298 r'^\s*(\s?>)+', # Python input prompt
3300 3299 r'^\s*\.{3,}', # Continuation prompts
3301 3300 r'^\++',
3302 3301 ]
3303 3302
3304 3303 strip_from_start = map(re.compile,strip_re)
3305 3304
3306 3305 lines = []
3307 3306 for l in raw_lines:
3308 3307 for pat in strip_from_start:
3309 3308 l = pat.sub('',l)
3310 3309 lines.append(l)
3311 3310
3312 3311 block = "\n".join(lines) + '\n'
3313 3312 #print "block:\n",block
3314 3313 return block
3315 3314
3316 3315 def _execute_block(self, block, par):
3317 3316 """ Execute a block, or store it in a variable, per the user's request.
3318 3317 """
3319 3318 if not par:
3320 3319 b = textwrap.dedent(block)
3321 3320 self.user_ns['pasted_block'] = b
3322 3321 exec b in self.user_ns
3323 3322 else:
3324 3323 self.user_ns[par] = SList(block.splitlines())
3325 3324 print "Block assigned to '%s'" % par
3326 3325
3327 3326 def magic_cpaste(self, parameter_s=''):
3328 3327 """Allows you to paste & execute a pre-formatted code block from clipboard.
3329 3328
3330 3329 You must terminate the block with '--' (two minus-signs) alone on the
3331 3330 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3332 3331 is the new sentinel for this operation)
3333 3332
3334 3333 The block is dedented prior to execution to enable execution of method
3335 3334 definitions. '>' and '+' characters at the beginning of a line are
3336 3335 ignored, to allow pasting directly from e-mails, diff files and
3337 3336 doctests (the '...' continuation prompt is also stripped). The
3338 3337 executed block is also assigned to variable named 'pasted_block' for
3339 3338 later editing with '%edit pasted_block'.
3340 3339
3341 3340 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3342 3341 This assigns the pasted block to variable 'foo' as string, without
3343 3342 dedenting or executing it (preceding >>> and + is still stripped)
3344 3343
3345 3344 '%cpaste -r' re-executes the block previously entered by cpaste.
3346 3345
3347 3346 Do not be alarmed by garbled output on Windows (it's a readline bug).
3348 3347 Just press enter and type -- (and press enter again) and the block
3349 3348 will be what was just pasted.
3350 3349
3351 3350 IPython statements (magics, shell escapes) are not supported (yet).
3352 3351
3353 3352 See also
3354 3353 --------
3355 3354 paste: automatically pull code from clipboard.
3356 3355 """
3357 3356
3358 3357 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3359 3358 par = args.strip()
3360 3359 if opts.has_key('r'):
3361 3360 self._rerun_pasted()
3362 3361 return
3363 3362
3364 3363 sentinel = opts.get('s','--')
3365 3364
3366 3365 block = self._strip_pasted_lines_for_code(
3367 3366 self._get_pasted_lines(sentinel))
3368 3367
3369 3368 self._execute_block(block, par)
3370 3369
3371 3370 def magic_paste(self, parameter_s=''):
3372 3371 """Allows you to paste & execute a pre-formatted code block from clipboard.
3373 3372
3374 3373 The text is pulled directly from the clipboard without user
3375 3374 intervention and printed back on the screen before execution (unless
3376 3375 the -q flag is given to force quiet mode).
3377 3376
3378 3377 The block is dedented prior to execution to enable execution of method
3379 3378 definitions. '>' and '+' characters at the beginning of a line are
3380 3379 ignored, to allow pasting directly from e-mails, diff files and
3381 3380 doctests (the '...' continuation prompt is also stripped). The
3382 3381 executed block is also assigned to variable named 'pasted_block' for
3383 3382 later editing with '%edit pasted_block'.
3384 3383
3385 3384 You can also pass a variable name as an argument, e.g. '%paste foo'.
3386 3385 This assigns the pasted block to variable 'foo' as string, without
3387 3386 dedenting or executing it (preceding >>> and + is still stripped)
3388 3387
3389 3388 Options
3390 3389 -------
3391 3390
3392 3391 -r: re-executes the block previously entered by cpaste.
3393 3392
3394 3393 -q: quiet mode: do not echo the pasted text back to the terminal.
3395 3394
3396 3395 IPython statements (magics, shell escapes) are not supported (yet).
3397 3396
3398 3397 See also
3399 3398 --------
3400 3399 cpaste: manually paste code into terminal until you mark its end.
3401 3400 """
3402 3401 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3403 3402 par = args.strip()
3404 3403 if opts.has_key('r'):
3405 3404 self._rerun_pasted()
3406 3405 return
3407 3406
3408 3407 text = self.shell.hooks.clipboard_get()
3409 3408 block = self._strip_pasted_lines_for_code(text.splitlines())
3410 3409
3411 3410 # By default, echo back to terminal unless quiet mode is requested
3412 3411 if not opts.has_key('q'):
3413 3412 write = self.shell.write
3414 3413 write(block)
3415 3414 if not block.endswith('\n'):
3416 3415 write('\n')
3417 3416 write("## -- End pasted text --\n")
3418 3417
3419 3418 self._execute_block(block, par)
3420 3419
3421 3420 def magic_quickref(self,arg):
3422 3421 """ Show a quick reference sheet """
3423 3422 import IPython.core.usage
3424 3423 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3425 3424
3426 3425 page(qr)
3427 3426
3428 3427 def magic_upgrade(self,arg):
3429 3428 """ Upgrade your IPython installation
3430 3429
3431 3430 This will copy the config files that don't yet exist in your
3432 3431 ipython dir from the system config dir. Use this after upgrading
3433 3432 IPython if you don't wish to delete your .ipython dir.
3434 3433
3435 3434 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3436 3435 new users)
3437 3436
3438 3437 """
3439 3438 ip = self.getapi()
3440 3439 ipinstallation = path(IPython.__file__).dirname()
3441 3440 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'utils' / 'upgradedir.py')
3442 3441 src_config = ipinstallation / 'config' / 'userconfig'
3443 3442 userdir = path(ip.options.IPYTHONDIR)
3444 3443 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3445 3444 print ">",cmd
3446 3445 shell(cmd)
3447 3446 if arg == '-nolegacy':
3448 3447 legacy = userdir.files('ipythonrc*')
3449 3448 print "Nuking legacy files:",legacy
3450 3449
3451 3450 [p.remove() for p in legacy]
3452 3451 suffix = (sys.platform == 'win32' and '.ini' or '')
3453 3452 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3454 3453
3455 3454
3456 3455 def magic_doctest_mode(self,parameter_s=''):
3457 3456 """Toggle doctest mode on and off.
3458 3457
3459 3458 This mode allows you to toggle the prompt behavior between normal
3460 3459 IPython prompts and ones that are as similar to the default IPython
3461 3460 interpreter as possible.
3462 3461
3463 3462 It also supports the pasting of code snippets that have leading '>>>'
3464 3463 and '...' prompts in them. This means that you can paste doctests from
3465 3464 files or docstrings (even if they have leading whitespace), and the
3466 3465 code will execute correctly. You can then use '%history -tn' to see
3467 3466 the translated history without line numbers; this will give you the
3468 3467 input after removal of all the leading prompts and whitespace, which
3469 3468 can be pasted back into an editor.
3470 3469
3471 3470 With these features, you can switch into this mode easily whenever you
3472 3471 need to do testing and changes to doctests, without having to leave
3473 3472 your existing IPython session.
3474 3473 """
3475 3474
3476 3475 # XXX - Fix this to have cleaner activate/deactivate calls.
3477 3476 from IPython.extensions import InterpreterPasteInput as ipaste
3478 3477 from IPython.utils.ipstruct import Struct
3479 3478
3480 3479 # Shorthands
3481 3480 shell = self.shell
3482 3481 oc = shell.outputcache
3483 3482 meta = shell.meta
3484 3483 # dstore is a data store kept in the instance metadata bag to track any
3485 3484 # changes we make, so we can undo them later.
3486 3485 dstore = meta.setdefault('doctest_mode',Struct())
3487 3486 save_dstore = dstore.setdefault
3488 3487
3489 3488 # save a few values we'll need to recover later
3490 3489 mode = save_dstore('mode',False)
3491 3490 save_dstore('rc_pprint',shell.pprint)
3492 3491 save_dstore('xmode',shell.InteractiveTB.mode)
3493 3492 save_dstore('rc_separate_out',shell.separate_out)
3494 3493 save_dstore('rc_separate_out2',shell.separate_out2)
3495 3494 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3496 3495 save_dstore('rc_separate_in',shell.separate_in)
3497 3496
3498 3497 if mode == False:
3499 3498 # turn on
3500 3499 ipaste.activate_prefilter()
3501 3500
3502 3501 oc.prompt1.p_template = '>>> '
3503 3502 oc.prompt2.p_template = '... '
3504 3503 oc.prompt_out.p_template = ''
3505 3504
3506 3505 # Prompt separators like plain python
3507 3506 oc.input_sep = oc.prompt1.sep = ''
3508 3507 oc.output_sep = ''
3509 3508 oc.output_sep2 = ''
3510 3509
3511 3510 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3512 3511 oc.prompt_out.pad_left = False
3513 3512
3514 3513 shell.pprint = False
3515 3514
3516 3515 shell.magic_xmode('Plain')
3517 3516
3518 3517 else:
3519 3518 # turn off
3520 3519 ipaste.deactivate_prefilter()
3521 3520
3522 3521 oc.prompt1.p_template = shell.prompt_in1
3523 3522 oc.prompt2.p_template = shell.prompt_in2
3524 3523 oc.prompt_out.p_template = shell.prompt_out
3525 3524
3526 3525 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3527 3526
3528 3527 oc.output_sep = dstore.rc_separate_out
3529 3528 oc.output_sep2 = dstore.rc_separate_out2
3530 3529
3531 3530 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3532 3531 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3533 3532
3534 3533 rc.pprint = dstore.rc_pprint
3535 3534
3536 3535 shell.magic_xmode(dstore.xmode)
3537 3536
3538 3537 # Store new mode and inform
3539 3538 dstore.mode = bool(1-int(mode))
3540 3539 print 'Doctest mode is:',
3541 3540 print ['OFF','ON'][dstore.mode]
3542 3541
3543 3542 def magic_gui(self, parameter_s=''):
3544 3543 """Enable or disable IPython GUI event loop integration.
3545 3544
3546 3545 %gui [-a] [GUINAME]
3547 3546
3548 3547 This magic replaces IPython's threaded shells that were activated
3549 3548 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3550 3549 can now be enabled, disabled and swtiched at runtime and keyboard
3551 3550 interrupts should work without any problems. The following toolkits
3552 3551 are supports: wxPython, PyQt4, PyGTK, and Tk::
3553 3552
3554 3553 %gui wx # enable wxPython event loop integration
3555 3554 %gui qt4 # enable PyQt4 event loop integration
3556 3555 %gui gtk # enable PyGTK event loop integration
3557 3556 %gui tk # enable Tk event loop integration
3558 3557 %gui # disable all event loop integration
3559 3558
3560 3559 WARNING: after any of these has been called you can simply create
3561 3560 an application object, but DO NOT start the event loop yourself, as
3562 3561 we have already handled that.
3563 3562
3564 3563 If you want us to create an appropriate application object add the
3565 3564 "-a" flag to your command::
3566 3565
3567 3566 %gui -a wx
3568 3567
3569 3568 This is highly recommended for most users.
3570 3569 """
3571 3570 from IPython.lib import inputhook
3572 3571 if "-a" in parameter_s:
3573 3572 app = True
3574 3573 else:
3575 3574 app = False
3576 3575 if not parameter_s:
3577 3576 inputhook.clear_inputhook()
3578 3577 elif 'wx' in parameter_s:
3579 3578 return inputhook.enable_wx(app)
3580 3579 elif 'qt4' in parameter_s:
3581 3580 return inputhook.enable_qt4(app)
3582 3581 elif 'gtk' in parameter_s:
3583 3582 return inputhook.enable_gtk(app)
3584 3583 elif 'tk' in parameter_s:
3585 3584 return inputhook.enable_tk(app)
3586 3585
3587 3586
3588 3587 # end Magic
@@ -1,103 +1,102 b''
1 1 # -*- coding: utf-8 -*-
2 2 """ Proxy module for accessing platform specific utility functions.
3 3
4 4 Importing this module should give you the implementations that are correct
5 5 for your operation system, from platutils_PLATFORMNAME module.
6 6 """
7 7
8 8 #*****************************************************************************
9 9 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
10 10 #
11 11 # Distributed under the terms of the BSD License. The full license is in
12 12 # the file COPYING, distributed as part of this software.
13 13 #*****************************************************************************
14 14
15 15 import os
16 16 import sys
17 17 import warnings
18 18
19 19 # Import the platform-specific implementations
20 20 if os.name == 'posix':
21 21 import platutils_posix as _platutils
22 22 elif sys.platform == 'win32':
23 23 import platutils_win32 as _platutils
24 24 else:
25 25 import platutils_dummy as _platutils
26 26
27 27 # Functionality that's logically common to all platforms goes here, each
28 28 # platform-specific module only provides the bits that are OS-dependent.
29 29
30 30 # XXX - I'm still not happy with a module global for this, but at least now
31 31 # there is a public, cross-platform way of toggling the term title control on
32 32 # and off. We should make this a stateful object later on so that each user
33 33 # can have its own instance if needed.
34 34 def term_clear():
35 35 _platutils.term_clear()
36 36
37 37 def toggle_set_term_title(val):
38 38 """Control whether set_term_title is active or not.
39 39
40 40 set_term_title() allows writing to the console titlebar. In embedded
41 41 widgets this can cause problems, so this call can be used to toggle it on
42 42 or off as needed.
43 43
44 44 The default state of the module is for the function to be disabled.
45 45
46 46 Parameters
47 47 ----------
48 48 val : bool
49 49 If True, set_term_title() actually writes to the terminal (using the
50 50 appropriate platform-specific module). If False, it is a no-op.
51 51 """
52 52 _platutils.ignore_termtitle = not(val)
53 53
54 54
55 55 def set_term_title(title):
56 56 """Set terminal title using the necessary platform-dependent calls."""
57
58 57 if _platutils.ignore_termtitle:
59 58 return
60 59 _platutils.set_term_title(title)
61 60
62 61
63 62 class FindCmdError(Exception):
64 63 pass
65 64
66 65 def find_cmd(cmd):
67 66 """Find full path to executable cmd in a cross platform manner.
68 67
69 68 This function tries to determine the full path to a command line program
70 69 using `which` on Unix/Linux/OS X and `win32api` on Windows. Most of the
71 70 time it will use the version that is first on the users `PATH`. If
72 71 cmd is `python` return `sys.executable`.
73 72
74 73 Parameters
75 74 ----------
76 75 cmd : str
77 76 The command line program to look for.
78 77 """
79 78 if cmd == 'python':
80 79 return sys.executable
81 80 try:
82 81 path = _platutils.find_cmd(cmd)
83 82 except:
84 83 raise FindCmdError('command could not be found: %s' % cmd)
85 84 # which returns empty if not found
86 85 if path == '':
87 86 raise FindCmdError('command could not be found: %s' % cmd)
88 87 return path
89 88
90 89 def get_long_path_name(path):
91 90 """Expand a path into its long form.
92 91
93 92 On Windows this expands any ~ in the paths. On other platforms, it is
94 93 a null operation.
95 94 """
96 95 return _platutils.get_long_path_name(path)
97 96
98 97 #-----------------------------------------------------------------------------
99 98 # Deprecated functions
100 99 #-----------------------------------------------------------------------------
101 100 def freeze_term_title():
102 101 warnings.warn("This function is deprecated, use toggle_set_term_title()")
103 102 _platutils.ignore_termtitle = True
@@ -1,47 +1,48 b''
1 1 # -*- coding: utf-8 -*-
2 2 """ Platform specific utility functions, posix version
3 3
4 4 Importing this module directly is not portable - rather, import platutils
5 5 to use these functions in platform agnostic fashion.
6 6 """
7 7
8 8 #*****************************************************************************
9 9 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
10 10 #
11 11 # Distributed under the terms of the BSD License. The full license is in
12 12 # the file COPYING, distributed as part of this software.
13 13 #*****************************************************************************
14 14
15 15 import sys
16 16 import os
17 17
18 18 ignore_termtitle = True
19 19
20
20 21 def _dummy_op(*a, **b):
21 22 """ A no-op function """
22 23
23 24
24 25 def _set_term_title_xterm(title):
25 26 """ Change virtual terminal title in xterm-workalikes """
26
27 27 sys.stdout.write('\033]0;%s\007' % title)
28 28
29 TERM = os.environ.get('TERM','')
29 30
30 if os.environ.get('TERM','') == 'xterm':
31 if (TERM == 'xterm') or (TERM == 'xterm-color'):
31 32 set_term_title = _set_term_title_xterm
32 33 else:
33 34 set_term_title = _dummy_op
34 35
35 36
36 37 def find_cmd(cmd):
37 38 """Find the full path to a command using which."""
38 39 return os.popen('which %s' % cmd).read().strip()
39 40
40 41
41 42 def get_long_path_name(path):
42 43 """Dummy no-op."""
43 44 return path
44 45
45 46
46 47 def term_clear():
47 48 os.system('clear')
@@ -1,94 +1,95 b''
1 1 # -*- coding: utf-8 -*-
2 2 """ Platform specific utility functions, win32 version
3 3
4 4 Importing this module directly is not portable - rather, import platutils
5 5 to use these functions in platform agnostic fashion.
6 6 """
7 7
8 8 #*****************************************************************************
9 9 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
10 10 #
11 11 # Distributed under the terms of the BSD License. The full license is in
12 12 # the file COPYING, distributed as part of this software.
13 13 #*****************************************************************************
14 14
15 15 import os
16 16
17 17 ignore_termtitle = True
18 18
19 19 try:
20 20 import ctypes
21 21
22 22 SetConsoleTitleW = ctypes.windll.kernel32.SetConsoleTitleW
23 23 SetConsoleTitleW.argtypes = [ctypes.c_wchar_p]
24 24
25 25 def set_term_title(title):
26 26 """Set terminal title using ctypes to access the Win32 APIs."""
27 27 SetConsoleTitleW(title)
28 28
29
29 30 except ImportError:
30 31 def set_term_title(title):
31 32 """Set terminal title using the 'title' command."""
32 33 global ignore_termtitle
33 34
34 35 try:
35 36 # Cannot be on network share when issuing system commands
36 37 curr = os.getcwd()
37 38 os.chdir("C:")
38 39 ret = os.system("title " + title)
39 40 finally:
40 41 os.chdir(curr)
41 42 if ret:
42 43 # non-zero return code signals error, don't try again
43 44 ignore_termtitle = True
44 45
45 46
46 47 def find_cmd(cmd):
47 48 """Find the full path to a .bat or .exe using the win32api module."""
48 49 try:
49 50 from win32api import SearchPath
50 51 except ImportError:
51 52 raise ImportError('you need to have pywin32 installed for this to work')
52 53 else:
53 54 PATH = os.environ['PATH']
54 55 extensions = ['.exe', '.com', '.bat', '.py']
55 56 path = None
56 57 for ext in extensions:
57 58 try:
58 59 path = SearchPath(PATH,cmd + ext)[0]
59 60 except:
60 61 pass
61 62 if path is None:
62 63 raise OSError("command %r not found" % cmd)
63 64 else:
64 65 return path
65 66
66 67
67 68 def get_long_path_name(path):
68 69 """Get a long path name (expand ~) on Windows using ctypes.
69 70
70 71 Examples
71 72 --------
72 73
73 74 >>> get_long_path_name('c:\\docume~1')
74 75 u'c:\\\\Documents and Settings'
75 76
76 77 """
77 78 try:
78 79 import ctypes
79 80 except ImportError:
80 81 raise ImportError('you need to have ctypes installed for this to work')
81 82 _GetLongPathName = ctypes.windll.kernel32.GetLongPathNameW
82 83 _GetLongPathName.argtypes = [ctypes.c_wchar_p, ctypes.c_wchar_p,
83 84 ctypes.c_uint ]
84 85
85 86 buf = ctypes.create_unicode_buffer(260)
86 87 rv = _GetLongPathName(path, buf, 260)
87 88 if rv == 0 or rv > 260:
88 89 return path
89 90 else:
90 91 return buf.value
91 92
92 93
93 94 def term_clear():
94 95 os.system('cls')
@@ -1,899 +1,925 b''
1 1 #!/usr/bin/env python
2 2 # encoding: utf-8
3 3 """
4 4 A lightweight Traits like module.
5 5
6 6 This is designed to provide a lightweight, simple, pure Python version of
7 7 many of the capabilities of enthought.traits. This includes:
8 8
9 9 * Validation
10 10 * Type specification with defaults
11 11 * Static and dynamic notification
12 12 * Basic predefined types
13 13 * An API that is similar to enthought.traits
14 14
15 15 We don't support:
16 16
17 17 * Delegation
18 18 * Automatic GUI generation
19 19 * A full set of trait types. Most importantly, we don't provide container
20 20 traitlets (list, dict, tuple) that can trigger notifications if their
21 21 contents change.
22 22 * API compatibility with enthought.traits
23 23
24 24 There are also some important difference in our design:
25 25
26 26 * enthought.traits does not validate default values. We do.
27 27
28 28 We choose to create this module because we need these capabilities, but
29 29 we need them to be pure Python so they work in all Python implementations,
30 30 including Jython and IronPython.
31 31
32 32 Authors:
33 33
34 34 * Brian Granger
35 35 * Enthought, Inc. Some of the code in this file comes from enthought.traits
36 36 and is licensed under the BSD license. Also, many of the ideas also come
37 37 from enthought.traits even though our implementation is very different.
38 38 """
39 39
40 40 #-----------------------------------------------------------------------------
41 41 # Copyright (C) 2008-2009 The IPython Development Team
42 42 #
43 43 # Distributed under the terms of the BSD License. The full license is in
44 44 # the file COPYING, distributed as part of this software.
45 45 #-----------------------------------------------------------------------------
46 46
47 47 #-----------------------------------------------------------------------------
48 48 # Imports
49 49 #-----------------------------------------------------------------------------
50 50
51 51
52 52 import inspect
53 53 import sys
54 54 import types
55 from types import InstanceType, ClassType, FunctionType
55 from types import (
56 InstanceType, ClassType, FunctionType,
57 ListType, TupleType
58 )
56 59
57 60 ClassTypes = (ClassType, type)
58 61
62 SequenceTypes = (ListType, TupleType)
63
59 64 #-----------------------------------------------------------------------------
60 65 # Basic classes
61 66 #-----------------------------------------------------------------------------
62 67
63 68
64 69 class NoDefaultSpecified ( object ): pass
65 70 NoDefaultSpecified = NoDefaultSpecified()
66 71
67 72
68 73 class Undefined ( object ): pass
69 74 Undefined = Undefined()
70 75
71 76
72 77 class TraitletError(Exception):
73 78 pass
74 79
75 80
76 81 #-----------------------------------------------------------------------------
77 82 # Utilities
78 83 #-----------------------------------------------------------------------------
79 84
80 85
81 86 def class_of ( object ):
82 87 """ Returns a string containing the class name of an object with the
83 88 correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image',
84 89 'a PlotValue').
85 90 """
86 91 if isinstance( object, basestring ):
87 92 return add_article( object )
88 93
89 94 return add_article( object.__class__.__name__ )
90 95
91 96
92 97 def add_article ( name ):
93 98 """ Returns a string containing the correct indefinite article ('a' or 'an')
94 99 prefixed to the specified string.
95 100 """
96 101 if name[:1].lower() in 'aeiou':
97 102 return 'an ' + name
98 103
99 104 return 'a ' + name
100 105
101 106
102 107 def repr_type(obj):
103 108 """ Return a string representation of a value and its type for readable
104 109 error messages.
105 110 """
106 111 the_type = type(obj)
107 112 if the_type is InstanceType:
108 113 # Old-style class.
109 114 the_type = obj.__class__
110 115 msg = '%r %r' % (obj, the_type)
111 116 return msg
112 117
113 118
114 119 def parse_notifier_name(name):
115 120 """Convert the name argument to a list of names.
116 121
117 122 Examples
118 123 --------
119 124
120 125 >>> parse_notifier_name('a')
121 126 ['a']
122 127 >>> parse_notifier_name(['a','b'])
123 128 ['a', 'b']
124 129 >>> parse_notifier_name(None)
125 130 ['anytraitlet']
126 131 """
127 132 if isinstance(name, str):
128 133 return [name]
129 134 elif name is None:
130 135 return ['anytraitlet']
131 136 elif isinstance(name, (list, tuple)):
132 137 for n in name:
133 138 assert isinstance(n, str), "names must be strings"
134 139 return name
135 140
136 141
137 142 class _SimpleTest:
138 143 def __init__ ( self, value ): self.value = value
139 144 def __call__ ( self, test ):
140 145 print test, self.value
141 146 return test == self.value
142 147 def __repr__(self):
143 148 return "<SimpleTest(%r)" % self.value
144 149 def __str__(self):
145 150 return self.__repr__()
146 151
147 152
148 153 #-----------------------------------------------------------------------------
149 154 # Base TraitletType for all traitlets
150 155 #-----------------------------------------------------------------------------
151 156
152 157
153 158 class TraitletType(object):
154 159 """A base class for all traitlet descriptors.
155 160
156 161 Notes
157 162 -----
158 163 Our implementation of traitlets is based on Python's descriptor
159 164 prototol. This class is the base class for all such descriptors. The
160 165 only magic we use is a custom metaclass for the main :class:`HasTraitlets`
161 166 class that does the following:
162 167
163 168 1. Sets the :attr:`name` attribute of every :class:`TraitletType`
164 169 instance in the class dict to the name of the attribute.
165 170 2. Sets the :attr:`this_class` attribute of every :class:`TraitletType`
166 171 instance in the class dict to the *class* that declared the traitlet.
167 172 This is used by the :class:`This` traitlet to allow subclasses to
168 173 accept superclasses for :class:`This` values.
169 174 """
170 175
171 176
172 177 metadata = {}
173 178 default_value = Undefined
174 179 info_text = 'any value'
175 180
176 181 def __init__(self, default_value=NoDefaultSpecified, **metadata):
177 182 """Create a TraitletType.
178 183 """
179 184 if default_value is not NoDefaultSpecified:
180 185 self.default_value = default_value
181 186
182 187 if len(metadata) > 0:
183 188 if len(self.metadata) > 0:
184 189 self._metadata = self.metadata.copy()
185 190 self._metadata.update(metadata)
186 191 else:
187 192 self._metadata = metadata
188 193 else:
189 194 self._metadata = self.metadata
190 195
191 196 self.init()
192 197
193 198 def init(self):
194 199 pass
195 200
196 201 def get_default_value(self):
197 202 """Create a new instance of the default value."""
198 203 dv = self.default_value
199 204 return dv
200 205
201 206 def set_default_value(self, obj):
202 207 dv = self.get_default_value()
203 208 newdv = self._validate(obj, dv)
204 209 obj._traitlet_values[self.name] = newdv
205 210
206 211
207 212 def __get__(self, obj, cls=None):
208 213 """Get the value of the traitlet by self.name for the instance.
209 214
210 215 Default values are instantiated when :meth:`HasTraitlets.__new__`
211 216 is called. Thus by the time this method gets called either the
212 217 default value or a user defined value (they called :meth:`__set__`)
213 218 is in the :class:`HasTraitlets` instance.
214 219 """
215 220 if obj is None:
216 221 return self
217 222 else:
218 223 try:
219 224 value = obj._traitlet_values[self.name]
220 225 except:
221 226 # HasTraitlets should call set_default_value to populate
222 227 # this. So this should never be reached.
223 228 raise TraitletError('Unexpected error in TraitletType: '
224 229 'default value not set properly')
225 230 else:
226 231 return value
227 232
228 233 def __set__(self, obj, value):
229 234 new_value = self._validate(obj, value)
230 235 old_value = self.__get__(obj)
231 236 if old_value != new_value:
232 237 obj._traitlet_values[self.name] = new_value
233 238 obj._notify_traitlet(self.name, old_value, new_value)
234 239
235 240 def _validate(self, obj, value):
236 241 if hasattr(self, 'validate'):
237 242 return self.validate(obj, value)
238 243 elif hasattr(self, 'is_valid_for'):
239 244 valid = self.is_valid_for(value)
240 245 if valid:
241 246 return value
242 247 else:
243 248 raise TraitletError('invalid value for type: %r' % value)
244 249 elif hasattr(self, 'value_for'):
245 250 return self.value_for(value)
246 251 else:
247 252 return value
248 253
249 254 def info(self):
250 255 return self.info_text
251 256
252 257 def error(self, obj, value):
253 258 if obj is not None:
254 259 e = "The '%s' traitlet of %s instance must be %s, but a value of %s was specified." \
255 260 % (self.name, class_of(obj),
256 261 self.info(), repr_type(value))
257 262 else:
258 263 e = "The '%s' traitlet must be %s, but a value of %r was specified." \
259 264 % (self.name, self.info(), repr_type(value))
260 265 raise TraitletError(e)
261 266
262 267 def get_metadata(self, key):
263 268 return getattr(self, '_metadata', {}).get(key, None)
264 269
265 270 def set_metadata(self, key, value):
266 271 getattr(self, '_metadata', {})[key] = value
267 272
268 273
269 274 #-----------------------------------------------------------------------------
270 275 # The HasTraitlets implementation
271 276 #-----------------------------------------------------------------------------
272 277
273 278
274 279 class MetaHasTraitlets(type):
275 280 """A metaclass for HasTraitlets.
276 281
277 282 This metaclass makes sure that any TraitletType class attributes are
278 283 instantiated and sets their name attribute.
279 284 """
280 285
281 286 def __new__(mcls, name, bases, classdict):
282 287 """Create the HasTraitlets class.
283 288
284 289 This instantiates all TraitletTypes in the class dict and sets their
285 290 :attr:`name` attribute.
286 291 """
287 292 # print "========================="
288 293 # print "MetaHasTraitlets.__new__"
289 294 # print "mcls, ", mcls
290 295 # print "name, ", name
291 296 # print "bases, ", bases
292 297 # print "classdict, ", classdict
293 298 for k,v in classdict.iteritems():
294 299 if isinstance(v, TraitletType):
295 300 v.name = k
296 301 elif inspect.isclass(v):
297 302 if issubclass(v, TraitletType):
298 303 vinst = v()
299 304 vinst.name = k
300 305 classdict[k] = vinst
301 306 return super(MetaHasTraitlets, mcls).__new__(mcls, name, bases, classdict)
302 307
303 308 def __init__(cls, name, bases, classdict):
304 309 """Finish initializing the HasTraitlets class.
305 310
306 311 This sets the :attr:`this_class` attribute of each TraitletType in the
307 312 class dict to the newly created class ``cls``.
308 313 """
309 314 # print "========================="
310 315 # print "MetaHasTraitlets.__init__"
311 316 # print "cls, ", cls
312 317 # print "name, ", name
313 318 # print "bases, ", bases
314 319 # print "classdict, ", classdict
315 320 for k, v in classdict.iteritems():
316 321 if isinstance(v, TraitletType):
317 322 v.this_class = cls
318 323 super(MetaHasTraitlets, cls).__init__(name, bases, classdict)
319 324
320 325 class HasTraitlets(object):
321 326
322 327 __metaclass__ = MetaHasTraitlets
323 328
324 329 def __new__(cls, *args, **kw):
325 330 inst = super(HasTraitlets, cls).__new__(cls, *args, **kw)
326 331 inst._traitlet_values = {}
327 332 inst._traitlet_notifiers = {}
328 333 # Here we tell all the TraitletType instances to set their default
329 334 # values on the instance.
330 335 for key in dir(cls):
331 336 value = getattr(cls, key)
332 337 if isinstance(value, TraitletType):
333 338 value.set_default_value(inst)
334 339 return inst
335 340
336 341 # def __init__(self):
337 342 # self._traitlet_values = {}
338 343 # self._traitlet_notifiers = {}
339 344
340 345 def _notify_traitlet(self, name, old_value, new_value):
341 346
342 347 # First dynamic ones
343 348 callables = self._traitlet_notifiers.get(name,[])
344 349 more_callables = self._traitlet_notifiers.get('anytraitlet',[])
345 350 callables.extend(more_callables)
346 351
347 352 # Now static ones
348 353 try:
349 354 cb = getattr(self, '_%s_changed' % name)
350 355 except:
351 356 pass
352 357 else:
353 358 callables.append(cb)
354 359
355 360 # Call them all now
356 361 for c in callables:
357 362 # Traits catches and logs errors here. I allow them to raise
358 363 if callable(c):
359 364 argspec = inspect.getargspec(c)
360 365 nargs = len(argspec[0])
361 366 # Bound methods have an additional 'self' argument
362 367 # I don't know how to treat unbound methods, but they
363 368 # can't really be used for callbacks.
364 369 if isinstance(c, types.MethodType):
365 370 offset = -1
366 371 else:
367 372 offset = 0
368 373 if nargs + offset == 0:
369 374 c()
370 375 elif nargs + offset == 1:
371 376 c(name)
372 377 elif nargs + offset == 2:
373 378 c(name, new_value)
374 379 elif nargs + offset == 3:
375 380 c(name, old_value, new_value)
376 381 else:
377 382 raise TraitletError('a traitlet changed callback '
378 383 'must have 0-3 arguments.')
379 384 else:
380 385 raise TraitletError('a traitlet changed callback '
381 386 'must be callable.')
382 387
383 388
384 389 def _add_notifiers(self, handler, name):
385 390 if not self._traitlet_notifiers.has_key(name):
386 391 nlist = []
387 392 self._traitlet_notifiers[name] = nlist
388 393 else:
389 394 nlist = self._traitlet_notifiers[name]
390 395 if handler not in nlist:
391 396 nlist.append(handler)
392 397
393 398 def _remove_notifiers(self, handler, name):
394 399 if self._traitlet_notifiers.has_key(name):
395 400 nlist = self._traitlet_notifiers[name]
396 401 try:
397 402 index = nlist.index(handler)
398 403 except ValueError:
399 404 pass
400 405 else:
401 406 del nlist[index]
402 407
403 408 def on_traitlet_change(self, handler, name=None, remove=False):
404 409 """Setup a handler to be called when a traitlet changes.
405 410
406 411 This is used to setup dynamic notifications of traitlet changes.
407 412
408 413 Static handlers can be created by creating methods on a HasTraitlets
409 414 subclass with the naming convention '_[traitletname]_changed'. Thus,
410 415 to create static handler for the traitlet 'a', create the method
411 416 _a_changed(self, name, old, new) (fewer arguments can be used, see
412 417 below).
413 418
414 419 Parameters
415 420 ----------
416 421 handler : callable
417 422 A callable that is called when a traitlet changes. Its
418 423 signature can be handler(), handler(name), handler(name, new)
419 424 or handler(name, old, new).
420 425 name : list, str, None
421 426 If None, the handler will apply to all traitlets. If a list
422 427 of str, handler will apply to all names in the list. If a
423 428 str, the handler will apply just to that name.
424 429 remove : bool
425 430 If False (the default), then install the handler. If True
426 431 then unintall it.
427 432 """
428 433 if remove:
429 434 names = parse_notifier_name(name)
430 435 for n in names:
431 436 self._remove_notifiers(handler, n)
432 437 else:
433 438 names = parse_notifier_name(name)
434 439 for n in names:
435 440 self._add_notifiers(handler, n)
436 441
437 442 def traitlet_names(self, **metadata):
438 443 """Get a list of all the names of this classes traitlets."""
439 444 return self.traitlets(**metadata).keys()
440 445
441 446 def traitlets(self, *args, **metadata):
442 447 """Get a list of all the traitlets of this class.
443 448
444 449 The TraitletTypes returned don't know anything about the values
445 450 that the various HasTraitlet's instances are holding.
446 451 """
447 452 traitlets = dict([memb for memb in inspect.getmembers(self.__class__) if \
448 453 isinstance(memb[1], TraitletType)])
449 454 if len(metadata) == 0 and len(args) == 0:
450 455 return traitlets
451 456
452 457 for meta_name in args:
453 458 metadata[meta_name] = lambda _: True
454 459
455 460 for meta_name, meta_eval in metadata.items():
456 461 if type(meta_eval) is not FunctionType:
457 462 metadata[meta_name] = _SimpleTest(meta_eval)
458 463
459 464 result = {}
460 465 for name, traitlet in traitlets.items():
461 466 for meta_name, meta_eval in metadata.items():
462 467 if not meta_eval(traitlet.get_metadata(meta_name)):
463 468 break
464 469 else:
465 470 result[name] = traitlet
466 471
467 472 return result
468 473
469 474 def traitlet_metadata(self, traitletname, key):
470 475 """Get metadata values for traitlet by key."""
471 476 try:
472 477 traitlet = getattr(self.__class__, traitletname)
473 478 except AttributeError:
474 479 raise TraitletError("Class %s does not have a traitlet named %s" %
475 480 (self.__class__.__name__, traitletname))
476 481 else:
477 482 return traitlet.get_metadata(key)
478 483
479 484 #-----------------------------------------------------------------------------
480 485 # Actual TraitletTypes implementations/subclasses
481 486 #-----------------------------------------------------------------------------
482 487
483 488 #-----------------------------------------------------------------------------
484 489 # TraitletTypes subclasses for handling classes and instances of classes
485 490 #-----------------------------------------------------------------------------
486 491
487 492
488 493 class ClassBasedTraitletType(TraitletType):
489 494 """A traitlet with error reporting for Type, Instance and This."""
490 495
491 496 def error(self, obj, value):
492 497 kind = type(value)
493 498 if kind is InstanceType:
494 499 msg = 'class %s' % value.__class__.__name__
495 500 else:
496 501 msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) )
497 502
498 503 super(ClassBasedTraitletType, self).error(obj, msg)
499 504
500 505
501 506 class Type(ClassBasedTraitletType):
502 507 """A traitlet whose value must be a subclass of a specified class."""
503 508
504 509 def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ):
505 510 """Construct a Type traitlet
506 511
507 512 A Type traitlet specifies that its values must be subclasses of
508 513 a particular class.
509 514
510 515 Parameters
511 516 ----------
512 517 default_value : class
513 518 The default value must be a subclass of klass.
514 519 klass : class, str, None
515 520 Values of this traitlet must be a subclass of klass. The klass
516 521 may be specified in a string like: 'foo.bar.MyClass'.
517 522 allow_none : boolean
518 523 Indicates whether None is allowed as an assignable value. Even if
519 524 ``False``, the default value may be ``None``.
520 525 """
521 526 if default_value is None:
522 527 if klass is None:
523 528 klass = object
524 529 elif klass is None:
525 530 klass = default_value
526 531
527 532 if not inspect.isclass(klass):
528 533 raise TraitletError("A Type traitlet must specify a class.")
529 534
530 535 self.klass = klass
531 536 self._allow_none = allow_none
532 537
533 538 super(Type, self).__init__(default_value, **metadata)
534 539
535 540 def validate(self, obj, value):
536 541 """Validates that the value is a valid object instance."""
537 542 try:
538 543 if issubclass(value, self.klass):
539 544 return value
540 545 except:
541 546 if (value is None) and (self._allow_none):
542 547 return value
543 548
544 549 self.error(obj, value)
545 550
546 551 def info(self):
547 552 """ Returns a description of the trait."""
548 553 klass = self.klass.__name__
549 554 result = 'a subclass of ' + klass
550 555 if self._allow_none:
551 556 return result + ' or None'
552 557 return result
553 558
554 559
555 560 class DefaultValueGenerator(object):
556 561 """A class for generating new default value instances."""
557 562
558 563 def __init__(self, klass, *args, **kw):
559 564 self.klass = klass
560 565 self.args = args
561 566 self.kw = kw
562 567
563 568 def generate(self):
564 569 return self.klass(*self.args, **self.kw)
565 570
566 571
567 572 class Instance(ClassBasedTraitletType):
568 573 """A trait whose value must be an instance of a specified class.
569 574
570 575 The value can also be an instance of a subclass of the specified class.
571 576 """
572 577
573 578 def __init__(self, klass=None, args=None, kw=None,
574 579 allow_none=True, **metadata ):
575 580 """Construct an Instance traitlet.
576 581
577 582 This traitlet allows values that are instances of a particular
578 583 class or its sublclasses. Our implementation is quite different
579 584 from that of enthough.traits as we don't allow instances to be used
580 585 for klass and we handle the ``args`` and ``kw`` arguments differently.
581 586
582 587 Parameters
583 588 ----------
584 589 klass : class
585 590 The class that forms the basis for the traitlet. Instances
586 591 and strings are not allowed.
587 592 args : tuple
588 593 Positional arguments for generating the default value.
589 594 kw : dict
590 595 Keyword arguments for generating the default value.
591 596 allow_none : bool
592 597 Indicates whether None is allowed as a value.
593 598
594 599 Default Value
595 600 -------------
596 601 If both ``args`` and ``kw`` are None, then the default value is None.
597 602 If ``args`` is a tuple and ``kw`` is a dict, then the default is
598 603 created as ``klass(*args, **kw)``. If either ``args`` or ``kw`` is
599 604 not (but not both), None is replace by ``()`` or ``{}``.
600 605 """
601 606
602 607 self._allow_none = allow_none
603 608
604 609 if (klass is None) or (not inspect.isclass(klass)):
605 610 raise TraitletError('The klass argument must be a class'
606 611 ' you gave: %r' % klass)
607 612 self.klass = klass
608 613
609 614 # self.klass is a class, so handle default_value
610 615 if args is None and kw is None:
611 616 default_value = None
612 617 else:
613 618 if args is None:
614 619 # kw is not None
615 620 args = ()
616 621 elif kw is None:
617 622 # args is not None
618 623 kw = {}
619 624
620 625 if not isinstance(kw, dict):
621 626 raise TraitletError("The 'kw' argument must be a dict or None.")
622 627 if not isinstance(args, tuple):
623 628 raise TraitletError("The 'args' argument must be a tuple or None.")
624 629
625 630 default_value = DefaultValueGenerator(self.klass, *args, **kw)
626 631
627 632 super(Instance, self).__init__(default_value, **metadata)
628 633
629 634 def validate(self, obj, value):
630 635 if value is None:
631 636 if self._allow_none:
632 637 return value
633 638 self.error(obj, value)
634 639
635 640 if isinstance(value, self.klass):
636 641 return value
637 642 else:
638 643 self.error(obj, value)
639 644
640 645 def info(self):
641 646 klass = self.klass.__name__
642 647 result = class_of(klass)
643 648 if self._allow_none:
644 649 return result + ' or None'
645 650
646 651 return result
647 652
648 653 def get_default_value(self):
649 654 """Instantiate a default value instance.
650 655
651 656 This is called when the containing HasTraitlets classes'
652 657 :meth:`__new__` method is called to ensure that a unique instance
653 658 is created for each HasTraitlets instance.
654 659 """
655 660 dv = self.default_value
656 661 if isinstance(dv, DefaultValueGenerator):
657 662 return dv.generate()
658 663 else:
659 664 return dv
660 665
661 666
662 667 class This(ClassBasedTraitletType):
663 668 """A traitlet for instances of the class containing this trait.
664 669
665 670 Because how how and when class bodies are executed, the ``This``
666 671 traitlet can only have a default value of None. This, and because we
667 672 always validate default values, ``allow_none`` is *always* true.
668 673 """
669 674
670 675 info_text = 'an instance of the same type as the receiver or None'
671 676
672 677 def __init__(self, **metadata):
673 678 super(This, self).__init__(None, **metadata)
674 679
675 680 def validate(self, obj, value):
676 681 # What if value is a superclass of obj.__class__? This is
677 682 # complicated if it was the superclass that defined the This
678 683 # traitlet.
679 684 if isinstance(value, self.this_class) or (value is None):
680 685 return value
681 686 else:
682 687 self.error(obj, value)
683 688
684 689
685 690 #-----------------------------------------------------------------------------
686 691 # Basic TraitletTypes implementations/subclasses
687 692 #-----------------------------------------------------------------------------
688 693
689 694
690 695 class Any(TraitletType):
691 696 default_value = None
692 697 info_text = 'any value'
693 698
694 699
695 700 class Int(TraitletType):
696 701 """A integer traitlet."""
697 702
698 703 evaluate = int
699 704 default_value = 0
700 705 info_text = 'an integer'
701 706
702 707 def validate(self, obj, value):
703 708 if isinstance(value, int):
704 709 return value
705 710 self.error(obj, value)
706 711
707 712 class CInt(Int):
708 713 """A casting version of the int traitlet."""
709 714
710 715 def validate(self, obj, value):
711 716 try:
712 717 return int(value)
713 718 except:
714 719 self.error(obj, value)
715 720
716 721
717 722 class Long(TraitletType):
718 723 """A long integer traitlet."""
719 724
720 725 evaluate = long
721 726 default_value = 0L
722 727 info_text = 'a long'
723 728
724 729 def validate(self, obj, value):
725 730 if isinstance(value, long):
726 731 return value
727 732 if isinstance(value, int):
728 733 return long(value)
729 734 self.error(obj, value)
730 735
731 736
732 737 class CLong(Long):
733 738 """A casting version of the long integer traitlet."""
734 739
735 740 def validate(self, obj, value):
736 741 try:
737 742 return long(value)
738 743 except:
739 744 self.error(obj, value)
740 745
741 746
742 747 class Float(TraitletType):
743 748 """A float traitlet."""
744 749
745 750 evaluate = float
746 751 default_value = 0.0
747 752 info_text = 'a float'
748 753
749 754 def validate(self, obj, value):
750 755 if isinstance(value, float):
751 756 return value
752 757 if isinstance(value, int):
753 758 return float(value)
754 759 self.error(obj, value)
755 760
756 761
757 762 class CFloat(Float):
758 763 """A casting version of the float traitlet."""
759 764
760 765 def validate(self, obj, value):
761 766 try:
762 767 return float(value)
763 768 except:
764 769 self.error(obj, value)
765 770
766 771 class Complex(TraitletType):
767 772 """A traitlet for complex numbers."""
768 773
769 774 evaluate = complex
770 775 default_value = 0.0 + 0.0j
771 776 info_text = 'a complex number'
772 777
773 778 def validate(self, obj, value):
774 779 if isinstance(value, complex):
775 780 return value
776 781 if isinstance(value, (float, int)):
777 782 return complex(value)
778 783 self.error(obj, value)
779 784
780 785
781 786 class CComplex(Complex):
782 787 """A casting version of the complex number traitlet."""
783 788
784 789 def validate (self, obj, value):
785 790 try:
786 791 return complex(value)
787 792 except:
788 793 self.error(obj, value)
789 794
790 795
791 796 class Str(TraitletType):
792 797 """A traitlet for strings."""
793 798
794 799 evaluate = lambda x: x
795 800 default_value = ''
796 801 info_text = 'a string'
797 802
798 803 def validate(self, obj, value):
799 804 if isinstance(value, str):
800 805 return value
801 806 self.error(obj, value)
802 807
803 808
804 809 class CStr(Str):
805 810 """A casting version of the string traitlet."""
806 811
807 812 def validate(self, obj, value):
808 813 try:
809 814 return str(value)
810 815 except:
811 816 try:
812 817 return unicode(value)
813 818 except:
814 819 self.error(obj, value)
815 820
816 821
817 822 class Unicode(TraitletType):
818 823 """A traitlet for unicode strings."""
819 824
820 825 evaluate = unicode
821 826 default_value = u''
822 827 info_text = 'a unicode string'
823 828
824 829 def validate(self, obj, value):
825 830 if isinstance(value, unicode):
826 831 return value
827 832 if isinstance(value, str):
828 833 return unicode(value)
829 834 self.error(obj, value)
830 835
831 836
832 837 class CUnicode(Unicode):
833 838 """A casting version of the unicode traitlet."""
834 839
835 840 def validate(self, obj, value):
836 841 try:
837 842 return unicode(value)
838 843 except:
839 844 self.error(obj, value)
840 845
841 846
842 847 class Bool(TraitletType):
843 848 """A boolean (True, False) traitlet."""
844 849 evaluate = bool
845 850 default_value = False
846 851 info_text = 'a boolean'
847 852
848 853 def validate(self, obj, value):
849 854 if isinstance(value, bool):
850 855 return value
851 856 self.error(obj, value)
852 857
853 858
854 859 class CBool(Bool):
855 860 """A casting version of the boolean traitlet."""
856 861
857 862 def validate(self, obj, value):
858 863 try:
859 864 return bool(value)
860 865 except:
861 866 self.error(obj, value)
862 867
868
863 869 class Enum(TraitletType):
870 """An enum that whose value must be in a given sequence."""
864 871
865 872 def __init__(self, values, default_value=None, allow_none=True, **metadata):
866 873 self.values = values
867 874 self._allow_none = allow_none
868 875 super(Enum, self).__init__(default_value, **metadata)
869 876
870 877 def validate(self, obj, value):
871 878 if value is None:
872 879 if self._allow_none:
873 880 return value
874 881
875 882 if value in self.values:
876 883 return value
877 884 self.error(obj, value)
878 885
879 886 def info(self):
880 887 """ Returns a description of the trait."""
881 888 result = 'any of ' + repr(self.values)
882 889 if self._allow_none:
883 890 return result + ' or None'
884 891 return result
885 892
886 893 class CaselessStrEnum(Enum):
894 """An enum of strings that are caseless in validate."""
887 895
888 896 def validate(self, obj, value):
889 897 if value is None:
890 898 if self._allow_none:
891 899 return value
892 900
893 901 if not isinstance(value, str):
894 902 self.error(obj, value)
895 903
896 904 for v in self.values:
897 905 if v.lower() == value.lower():
898 906 return v
899 907 self.error(obj, value)
908
909
910 class List(Instance):
911 """An instance of a Python list."""
912
913 def __init__(self, default_value=None, allow_none=True, **metadata):
914 """Create a list traitlet type from a list or tuple.
915
916 The default value is created by doing ``list(default_value)``,
917 which creates a copy of the ``default_value``.
918 """
919 if default_value is None:
920 args = ((),)
921 elif isinstance(default_value, SequenceTypes):
922 args = (default_value,)
923
924 super(List,self).__init__(klass=list, args=args,
925 allow_none=allow_none, **metadata)
General Comments 0
You need to be logged in to leave comments. Login now