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