##// 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 #!/usr/bin/env python
1 #!/usr/bin/env python
2 # encoding: utf-8
2 # encoding: utf-8
3 """
3 """
4 A context manager for managing things injected into :mod:`__builtin__`.
4 A context manager for managing things injected into :mod:`__builtin__`.
5
5
6 Authors:
6 Authors:
7
7
8 * Brian Granger
8 * Brian Granger
9 """
9 """
10
10
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12 # Copyright (C) 2008-2009 The IPython Development Team
12 # Copyright (C) 2008-2009 The IPython Development Team
13 #
13 #
14 # Distributed under the terms of the BSD License. The full license is in
14 # Distributed under the terms of the BSD License. The full license is in
15 # the file COPYING, distributed as part of this software.
15 # the file COPYING, distributed as part of this software.
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17
17
18 #-----------------------------------------------------------------------------
18 #-----------------------------------------------------------------------------
19 # Imports
19 # Imports
20 #-----------------------------------------------------------------------------
20 #-----------------------------------------------------------------------------
21
21
22 import __builtin__
22 import __builtin__
23
23
24 from IPython.core.component import Component
24 from IPython.core.component import Component
25 from IPython.core.quitter import Quitter
25 from IPython.core.quitter import Quitter
26
26
27 from IPython.utils.autoattr import auto_attr
27 from IPython.utils.autoattr import auto_attr
28
28
29 #-----------------------------------------------------------------------------
29 #-----------------------------------------------------------------------------
30 # Classes and functions
30 # Classes and functions
31 #-----------------------------------------------------------------------------
31 #-----------------------------------------------------------------------------
32
32
33
33
34 class BuiltinUndefined(object): pass
34 class BuiltinUndefined(object): pass
35 BuiltinUndefined = BuiltinUndefined()
35 BuiltinUndefined = BuiltinUndefined()
36
36
37
37
38 class BuiltinTrap(Component):
38 class BuiltinTrap(Component):
39
39
40 def __init__(self, parent):
40 def __init__(self, parent):
41 super(BuiltinTrap, self).__init__(parent, None, None)
41 super(BuiltinTrap, self).__init__(parent, None, None)
42 self._orig_builtins = {}
42 self._orig_builtins = {}
43 # We define this to track if a single BuiltinTrap is nested.
43 # We define this to track if a single BuiltinTrap is nested.
44 # Only turn off the trap when the outermost call to __exit__ is made.
44 # Only turn off the trap when the outermost call to __exit__ is made.
45 self._nested_level = 0
45 self._nested_level = 0
46
46
47 @auto_attr
47 @auto_attr
48 def shell(self):
48 def shell(self):
49 return Component.get_instances(
49 return Component.get_instances(
50 root=self.root,
50 root=self.root,
51 klass='IPython.core.iplib.InteractiveShell')[0]
51 klass='IPython.core.iplib.InteractiveShell')[0]
52
52
53 def __enter__(self):
53 def __enter__(self):
54 if self._nested_level == 0:
54 if self._nested_level == 0:
55 self.set()
55 self.set()
56 self._nested_level += 1
56 self._nested_level += 1
57 # I return self, so callers can use add_builtin in a with clause.
57 # I return self, so callers can use add_builtin in a with clause.
58 return self
58 return self
59
59
60 def __exit__(self, type, value, traceback):
60 def __exit__(self, type, value, traceback):
61 if self._nested_level == 1:
61 if self._nested_level == 1:
62 self.unset()
62 self.unset()
63 self._nested_level -= 1
63 self._nested_level -= 1
64 return True
64 # Returning False will cause exceptions to propagate
65 return False
65
66
66 def add_builtin(self, key, value):
67 def add_builtin(self, key, value):
67 """Add a builtin and save the original."""
68 """Add a builtin and save the original."""
68 orig = __builtin__.__dict__.get(key, BuiltinUndefined)
69 orig = __builtin__.__dict__.get(key, BuiltinUndefined)
69 self._orig_builtins[key] = orig
70 self._orig_builtins[key] = orig
70 __builtin__.__dict__[key] = value
71 __builtin__.__dict__[key] = value
71
72
72 def remove_builtin(self, key):
73 def remove_builtin(self, key):
73 """Remove an added builtin and re-set the original."""
74 """Remove an added builtin and re-set the original."""
74 try:
75 try:
75 orig = self._orig_builtins.pop(key)
76 orig = self._orig_builtins.pop(key)
76 except KeyError:
77 except KeyError:
77 pass
78 pass
78 else:
79 else:
79 if orig is BuiltinUndefined:
80 if orig is BuiltinUndefined:
80 del __builtin__.__dict__[key]
81 del __builtin__.__dict__[key]
81 else:
82 else:
82 __builtin__.__dict__[key] = orig
83 __builtin__.__dict__[key] = orig
83
84
84 def set(self):
85 def set(self):
85 """Store ipython references in the __builtin__ namespace."""
86 """Store ipython references in the __builtin__ namespace."""
86 self.add_builtin('exit', Quitter(self.shell, 'exit'))
87 self.add_builtin('exit', Quitter(self.shell, 'exit'))
87 self.add_builtin('quit', Quitter(self.shell, 'quit'))
88 self.add_builtin('quit', Quitter(self.shell, 'quit'))
88
89
89 # Recursive reload function
90 # Recursive reload function
90 try:
91 try:
91 from IPython.lib import deepreload
92 from IPython.lib import deepreload
92 if self.shell.deep_reload:
93 if self.shell.deep_reload:
93 self.add_builtin('reload', deepreload.reload)
94 self.add_builtin('reload', deepreload.reload)
94 else:
95 else:
95 self.add_builtin('dreload', deepreload.reload)
96 self.add_builtin('dreload', deepreload.reload)
96 del deepreload
97 del deepreload
97 except ImportError:
98 except ImportError:
98 pass
99 pass
99
100
100 # Keep in the builtins a flag for when IPython is active. We set it
101 # Keep in the builtins a flag for when IPython is active. We set it
101 # with setdefault so that multiple nested IPythons don't clobber one
102 # with setdefault so that multiple nested IPythons don't clobber one
102 # another. Each will increase its value by one upon being activated,
103 # another. Each will increase its value by one upon being activated,
103 # which also gives us a way to determine the nesting level.
104 # which also gives us a way to determine the nesting level.
104 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
105 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
105
106
106 def unset(self):
107 def unset(self):
107 """Remove any builtins which might have been added by add_builtins, or
108 """Remove any builtins which might have been added by add_builtins, or
108 restore overwritten ones to their previous values."""
109 restore overwritten ones to their previous values."""
109 for key in self._orig_builtins.keys():
110 for key in self._orig_builtins.keys():
110 self.remove_builtin(key)
111 self.remove_builtin(key)
111 self._orig_builtins.clear()
112 self._orig_builtins.clear()
112 self._builtins_added = False
113 self._builtins_added = False
113 try:
114 try:
114 del __builtin__.__dict__['__IPYTHON__active']
115 del __builtin__.__dict__['__IPYTHON__active']
115 except KeyError:
116 except KeyError:
116 pass
117 pass
@@ -1,76 +1,77 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 # encoding: utf-8
2 # encoding: utf-8
3 """
3 """
4 A context manager for handling sys.displayhook.
4 A context manager for handling sys.displayhook.
5
5
6 Authors:
6 Authors:
7
7
8 * Robert Kern
8 * Robert Kern
9 * Brian Granger
9 * Brian Granger
10 """
10 """
11
11
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 # Copyright (C) 2008-2009 The IPython Development Team
13 # Copyright (C) 2008-2009 The IPython Development Team
14 #
14 #
15 # Distributed under the terms of the BSD License. The full license is in
15 # Distributed under the terms of the BSD License. The full license is in
16 # the file COPYING, distributed as part of this software.
16 # the file COPYING, distributed as part of this software.
17 #-----------------------------------------------------------------------------
17 #-----------------------------------------------------------------------------
18
18
19 #-----------------------------------------------------------------------------
19 #-----------------------------------------------------------------------------
20 # Imports
20 # Imports
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22
22
23 import sys
23 import sys
24
24
25 from IPython.core.component import Component
25 from IPython.core.component import Component
26
26
27 from IPython.utils.autoattr import auto_attr
27 from IPython.utils.autoattr import auto_attr
28
28
29 #-----------------------------------------------------------------------------
29 #-----------------------------------------------------------------------------
30 # Classes and functions
30 # Classes and functions
31 #-----------------------------------------------------------------------------
31 #-----------------------------------------------------------------------------
32
32
33
33
34 class DisplayTrap(Component):
34 class DisplayTrap(Component):
35 """Object to manage sys.displayhook.
35 """Object to manage sys.displayhook.
36
36
37 This came from IPython.core.kernel.display_hook, but is simplified
37 This came from IPython.core.kernel.display_hook, but is simplified
38 (no callbacks or formatters) until more of the core is refactored.
38 (no callbacks or formatters) until more of the core is refactored.
39 """
39 """
40
40
41 def __init__(self, parent, hook):
41 def __init__(self, parent, hook):
42 super(DisplayTrap, self).__init__(parent, None, None)
42 super(DisplayTrap, self).__init__(parent, None, None)
43 self.hook = hook
43 self.hook = hook
44 self.old_hook = None
44 self.old_hook = None
45 # We define this to track if a single BuiltinTrap is nested.
45 # We define this to track if a single BuiltinTrap is nested.
46 # Only turn off the trap when the outermost call to __exit__ is made.
46 # Only turn off the trap when the outermost call to __exit__ is made.
47 self._nested_level = 0
47 self._nested_level = 0
48
48
49 @auto_attr
49 @auto_attr
50 def shell(self):
50 def shell(self):
51 return Component.get_instances(
51 return Component.get_instances(
52 root=self.root,
52 root=self.root,
53 klass='IPython.core.iplib.InteractiveShell')[0]
53 klass='IPython.core.iplib.InteractiveShell')[0]
54
54
55 def __enter__(self):
55 def __enter__(self):
56 if self._nested_level == 0:
56 if self._nested_level == 0:
57 self.set()
57 self.set()
58 self._nested_level += 1
58 self._nested_level += 1
59 return self
59 return self
60
60
61 def __exit__(self, type, value, traceback):
61 def __exit__(self, type, value, traceback):
62 if self._nested_level == 1:
62 if self._nested_level == 1:
63 self.unset()
63 self.unset()
64 self._nested_level -= 1
64 self._nested_level -= 1
65 return True
65 # Returning False will cause exceptions to propagate
66 return False
66
67
67 def set(self):
68 def set(self):
68 """Set the hook."""
69 """Set the hook."""
69 if sys.displayhook is not self.hook:
70 if sys.displayhook is not self.hook:
70 self.old_hook = sys.displayhook
71 self.old_hook = sys.displayhook
71 sys.displayhook = self.hook
72 sys.displayhook = self.hook
72
73
73 def unset(self):
74 def unset(self):
74 """Unset the hook."""
75 """Unset the hook."""
75 sys.displayhook = self.old_hook
76 sys.displayhook = self.old_hook
76
77
@@ -1,2438 +1,2470 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 Main IPython Component
3 Main IPython Component
4 """
4 """
5
5
6 #-----------------------------------------------------------------------------
6 #-----------------------------------------------------------------------------
7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
8 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
8 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
9 # Copyright (C) 2008-2009 The IPython Development Team
9 # Copyright (C) 2008-2009 The IPython Development Team
10 #
10 #
11 # Distributed under the terms of the BSD License. The full license is in
11 # Distributed under the terms of the BSD License. The full license is in
12 # the file COPYING, distributed as part of this software.
12 # the file COPYING, distributed as part of this software.
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14
14
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16 # Imports
16 # Imports
17 #-----------------------------------------------------------------------------
17 #-----------------------------------------------------------------------------
18
18
19 from __future__ import with_statement
19 from __future__ import with_statement
20
20
21 import __builtin__
21 import __builtin__
22 import StringIO
22 import StringIO
23 import bdb
23 import bdb
24 import codeop
24 import codeop
25 import exceptions
25 import exceptions
26 import new
26 import new
27 import os
27 import os
28 import re
28 import re
29 import string
29 import string
30 import sys
30 import sys
31 import tempfile
31 import tempfile
32 from contextlib import nested
32 from contextlib import nested
33
33
34 from IPython.core import ultratb
34 from IPython.core import ultratb
35 from IPython.core import debugger, oinspect
35 from IPython.core import debugger, oinspect
36 from IPython.core import shadowns
36 from IPython.core import shadowns
37 from IPython.core import history as ipcorehist
37 from IPython.core import history as ipcorehist
38 from IPython.core import prefilter
38 from IPython.core import prefilter
39 from IPython.core.alias import AliasManager
39 from IPython.core.alias import AliasManager
40 from IPython.core.builtin_trap import BuiltinTrap
40 from IPython.core.builtin_trap import BuiltinTrap
41 from IPython.core.display_trap import DisplayTrap
41 from IPython.core.display_trap import DisplayTrap
42 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
42 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
43 from IPython.core.logger import Logger
43 from IPython.core.logger import Logger
44 from IPython.core.magic import Magic
44 from IPython.core.magic import Magic
45 from IPython.core.prompts import CachedOutput
45 from IPython.core.prompts import CachedOutput
46 from IPython.core.prefilter import PrefilterManager
46 from IPython.core.prefilter import PrefilterManager
47 from IPython.core.component import Component
47 from IPython.core.component import Component
48 from IPython.core.usage import interactive_usage, default_banner
48 from IPython.core.usage import interactive_usage, default_banner
49 from IPython.core.error import TryNext, UsageError
49 from IPython.core.error import TryNext, UsageError
50
50
51 from IPython.utils import pickleshare
51 from IPython.utils import pickleshare
52 from IPython.external.Itpl import ItplNS
52 from IPython.external.Itpl import ItplNS
53 from IPython.lib.backgroundjobs import BackgroundJobManager
53 from IPython.lib.backgroundjobs import BackgroundJobManager
54 from IPython.utils.ipstruct import Struct
54 from IPython.utils.ipstruct import Struct
55 from IPython.utils import PyColorize
55 from IPython.utils import PyColorize
56 from IPython.utils.genutils import *
56 from IPython.utils.genutils import *
57 from IPython.utils.genutils import get_ipython_dir
57 from IPython.utils.genutils import get_ipython_dir
58 from IPython.utils.platutils import toggle_set_term_title, set_term_title
58 from IPython.utils.platutils import toggle_set_term_title, set_term_title
59 from IPython.utils.strdispatch import StrDispatch
59 from IPython.utils.strdispatch import StrDispatch
60 from IPython.utils.syspathcontext import prepended_to_syspath
60 from IPython.utils.syspathcontext import prepended_to_syspath
61
61
62 # from IPython.utils import growl
62 # from IPython.utils import growl
63 # growl.start("IPython")
63 # growl.start("IPython")
64
64
65 from IPython.utils.traitlets import (
65 from IPython.utils.traitlets import (
66 Int, Str, CBool, CaselessStrEnum, Enum, List, Unicode
66 Int, Str, CBool, CaselessStrEnum, Enum, List, Unicode
67 )
67 )
68
68
69 #-----------------------------------------------------------------------------
69 #-----------------------------------------------------------------------------
70 # Globals
70 # Globals
71 #-----------------------------------------------------------------------------
71 #-----------------------------------------------------------------------------
72
72
73
73
74 # store the builtin raw_input globally, and use this always, in case user code
74 # store the builtin raw_input globally, and use this always, in case user code
75 # overwrites it (like wx.py.PyShell does)
75 # overwrites it (like wx.py.PyShell does)
76 raw_input_original = raw_input
76 raw_input_original = raw_input
77
77
78 # compiled regexps for autoindent management
78 # compiled regexps for autoindent management
79 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
79 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
80
80
81
81
82 #-----------------------------------------------------------------------------
82 #-----------------------------------------------------------------------------
83 # Utilities
83 # Utilities
84 #-----------------------------------------------------------------------------
84 #-----------------------------------------------------------------------------
85
85
86
86
87 ini_spaces_re = re.compile(r'^(\s+)')
87 ini_spaces_re = re.compile(r'^(\s+)')
88
88
89
89
90 def num_ini_spaces(strng):
90 def num_ini_spaces(strng):
91 """Return the number of initial spaces in a string"""
91 """Return the number of initial spaces in a string"""
92
92
93 ini_spaces = ini_spaces_re.match(strng)
93 ini_spaces = ini_spaces_re.match(strng)
94 if ini_spaces:
94 if ini_spaces:
95 return ini_spaces.end()
95 return ini_spaces.end()
96 else:
96 else:
97 return 0
97 return 0
98
98
99
99
100 def softspace(file, newvalue):
100 def softspace(file, newvalue):
101 """Copied from code.py, to remove the dependency"""
101 """Copied from code.py, to remove the dependency"""
102
102
103 oldvalue = 0
103 oldvalue = 0
104 try:
104 try:
105 oldvalue = file.softspace
105 oldvalue = file.softspace
106 except AttributeError:
106 except AttributeError:
107 pass
107 pass
108 try:
108 try:
109 file.softspace = newvalue
109 file.softspace = newvalue
110 except (AttributeError, TypeError):
110 except (AttributeError, TypeError):
111 # "attribute-less object" or "read-only attributes"
111 # "attribute-less object" or "read-only attributes"
112 pass
112 pass
113 return oldvalue
113 return oldvalue
114
114
115
115
116 class SpaceInInput(exceptions.Exception): pass
116 class SpaceInInput(exceptions.Exception): pass
117
117
118 class Bunch: pass
118 class Bunch: pass
119
119
120 class InputList(list):
120 class InputList(list):
121 """Class to store user input.
121 """Class to store user input.
122
122
123 It's basically a list, but slices return a string instead of a list, thus
123 It's basically a list, but slices return a string instead of a list, thus
124 allowing things like (assuming 'In' is an instance):
124 allowing things like (assuming 'In' is an instance):
125
125
126 exec In[4:7]
126 exec In[4:7]
127
127
128 or
128 or
129
129
130 exec In[5:9] + In[14] + In[21:25]"""
130 exec In[5:9] + In[14] + In[21:25]"""
131
131
132 def __getslice__(self,i,j):
132 def __getslice__(self,i,j):
133 return ''.join(list.__getslice__(self,i,j))
133 return ''.join(list.__getslice__(self,i,j))
134
134
135
135
136 class SyntaxTB(ultratb.ListTB):
136 class SyntaxTB(ultratb.ListTB):
137 """Extension which holds some state: the last exception value"""
137 """Extension which holds some state: the last exception value"""
138
138
139 def __init__(self,color_scheme = 'NoColor'):
139 def __init__(self,color_scheme = 'NoColor'):
140 ultratb.ListTB.__init__(self,color_scheme)
140 ultratb.ListTB.__init__(self,color_scheme)
141 self.last_syntax_error = None
141 self.last_syntax_error = None
142
142
143 def __call__(self, etype, value, elist):
143 def __call__(self, etype, value, elist):
144 self.last_syntax_error = value
144 self.last_syntax_error = value
145 ultratb.ListTB.__call__(self,etype,value,elist)
145 ultratb.ListTB.__call__(self,etype,value,elist)
146
146
147 def clear_err_state(self):
147 def clear_err_state(self):
148 """Return the current error state and clear it"""
148 """Return the current error state and clear it"""
149 e = self.last_syntax_error
149 e = self.last_syntax_error
150 self.last_syntax_error = None
150 self.last_syntax_error = None
151 return e
151 return e
152
152
153
153
154 def get_default_editor():
154 def get_default_editor():
155 try:
155 try:
156 ed = os.environ['EDITOR']
156 ed = os.environ['EDITOR']
157 except KeyError:
157 except KeyError:
158 if os.name == 'posix':
158 if os.name == 'posix':
159 ed = 'vi' # the only one guaranteed to be there!
159 ed = 'vi' # the only one guaranteed to be there!
160 else:
160 else:
161 ed = 'notepad' # same in Windows!
161 ed = 'notepad' # same in Windows!
162 return ed
162 return ed
163
163
164
164
165 class SeparateStr(Str):
165 class SeparateStr(Str):
166 """A Str subclass to validate separate_in, separate_out, etc.
166 """A Str subclass to validate separate_in, separate_out, etc.
167
167
168 This is a Str based traitlet that converts '0'->'' and '\\n'->'\n'.
168 This is a Str based traitlet that converts '0'->'' and '\\n'->'\n'.
169 """
169 """
170
170
171 def validate(self, obj, value):
171 def validate(self, obj, value):
172 if value == '0': value = ''
172 if value == '0': value = ''
173 value = value.replace('\\n','\n')
173 value = value.replace('\\n','\n')
174 return super(SeparateStr, self).validate(obj, value)
174 return super(SeparateStr, self).validate(obj, value)
175
175
176
176
177 #-----------------------------------------------------------------------------
177 #-----------------------------------------------------------------------------
178 # Main IPython class
178 # Main IPython class
179 #-----------------------------------------------------------------------------
179 #-----------------------------------------------------------------------------
180
180
181
181
182 class InteractiveShell(Component, Magic):
182 class InteractiveShell(Component, Magic):
183 """An enhanced, interactive shell for Python."""
183 """An enhanced, interactive shell for Python."""
184
184
185 autocall = Enum((0,1,2), config=True)
185 autocall = Enum((0,1,2), config=True)
186 autoedit_syntax = CBool(False, config=True)
186 autoedit_syntax = CBool(False, config=True)
187 autoindent = CBool(True, config=True)
187 autoindent = CBool(True, config=True)
188 automagic = CBool(True, config=True)
188 automagic = CBool(True, config=True)
189 banner = Str('')
189 banner = Str('')
190 banner1 = Str(default_banner, config=True)
190 banner1 = Str(default_banner, config=True)
191 banner2 = Str('', config=True)
191 banner2 = Str('', config=True)
192 cache_size = Int(1000, config=True)
192 cache_size = Int(1000, config=True)
193 color_info = CBool(True, config=True)
193 color_info = CBool(True, config=True)
194 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
194 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
195 default_value='LightBG', config=True)
195 default_value='LightBG', config=True)
196 confirm_exit = CBool(True, config=True)
196 confirm_exit = CBool(True, config=True)
197 debug = CBool(False, config=True)
197 debug = CBool(False, config=True)
198 deep_reload = CBool(False, config=True)
198 deep_reload = CBool(False, config=True)
199 # This display_banner only controls whether or not self.show_banner()
199 # This display_banner only controls whether or not self.show_banner()
200 # is called when mainloop/interact are called. The default is False
200 # is called when mainloop/interact are called. The default is False
201 # because for the terminal based application, the banner behavior
201 # because for the terminal based application, the banner behavior
202 # is controlled by Global.display_banner, which IPythonApp looks at
202 # is controlled by Global.display_banner, which IPythonApp looks at
203 # to determine if *it* should call show_banner() by hand or not.
203 # to determine if *it* should call show_banner() by hand or not.
204 display_banner = CBool(False) # This isn't configurable!
204 display_banner = CBool(False) # This isn't configurable!
205 embedded = CBool(False)
205 embedded = CBool(False)
206 embedded_active = CBool(False)
206 embedded_active = CBool(False)
207 editor = Str(get_default_editor(), config=True)
207 editor = Str(get_default_editor(), config=True)
208 filename = Str("<ipython console>")
208 filename = Str("<ipython console>")
209 ipythondir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
209 ipythondir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
210 logstart = CBool(False, config=True)
210 logstart = CBool(False, config=True)
211 logfile = Str('', config=True)
211 logfile = Str('', config=True)
212 logappend = Str('', config=True)
212 logappend = Str('', config=True)
213 object_info_string_level = Enum((0,1,2), default_value=0,
213 object_info_string_level = Enum((0,1,2), default_value=0,
214 config=True)
214 config=True)
215 pager = Str('less', config=True)
215 pager = Str('less', config=True)
216 pdb = CBool(False, config=True)
216 pdb = CBool(False, config=True)
217 pprint = CBool(True, config=True)
217 pprint = CBool(True, config=True)
218 profile = Str('', config=True)
218 profile = Str('', config=True)
219 prompt_in1 = Str('In [\\#]: ', config=True)
219 prompt_in1 = Str('In [\\#]: ', config=True)
220 prompt_in2 = Str(' .\\D.: ', config=True)
220 prompt_in2 = Str(' .\\D.: ', config=True)
221 prompt_out = Str('Out[\\#]: ', config=True)
221 prompt_out = Str('Out[\\#]: ', config=True)
222 prompts_pad_left = CBool(True, config=True)
222 prompts_pad_left = CBool(True, config=True)
223 quiet = CBool(False, config=True)
223 quiet = CBool(False, config=True)
224
224
225 readline_use = CBool(True, config=True)
225 readline_use = CBool(True, config=True)
226 readline_merge_completions = CBool(True, config=True)
226 readline_merge_completions = CBool(True, config=True)
227 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
227 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
228 readline_remove_delims = Str('-/~', config=True)
228 readline_remove_delims = Str('-/~', config=True)
229 readline_parse_and_bind = List([
229 readline_parse_and_bind = List([
230 'tab: complete',
230 'tab: complete',
231 '"\C-l": possible-completions',
231 '"\C-l": possible-completions',
232 'set show-all-if-ambiguous on',
232 'set show-all-if-ambiguous on',
233 '"\C-o": tab-insert',
233 '"\C-o": tab-insert',
234 '"\M-i": " "',
234 '"\M-i": " "',
235 '"\M-o": "\d\d\d\d"',
235 '"\M-o": "\d\d\d\d"',
236 '"\M-I": "\d\d\d\d"',
236 '"\M-I": "\d\d\d\d"',
237 '"\C-r": reverse-search-history',
237 '"\C-r": reverse-search-history',
238 '"\C-s": forward-search-history',
238 '"\C-s": forward-search-history',
239 '"\C-p": history-search-backward',
239 '"\C-p": history-search-backward',
240 '"\C-n": history-search-forward',
240 '"\C-n": history-search-forward',
241 '"\e[A": history-search-backward',
241 '"\e[A": history-search-backward',
242 '"\e[B": history-search-forward',
242 '"\e[B": history-search-forward',
243 '"\C-k": kill-line',
243 '"\C-k": kill-line',
244 '"\C-u": unix-line-discard',
244 '"\C-u": unix-line-discard',
245 ], allow_none=False, config=True)
245 ], allow_none=False, config=True)
246
246
247 screen_length = Int(0, config=True)
247 screen_length = Int(0, config=True)
248
248
249 # Use custom TraitletTypes that convert '0'->'' and '\\n'->'\n'
249 # Use custom TraitletTypes that convert '0'->'' and '\\n'->'\n'
250 separate_in = SeparateStr('\n', config=True)
250 separate_in = SeparateStr('\n', config=True)
251 separate_out = SeparateStr('', config=True)
251 separate_out = SeparateStr('', config=True)
252 separate_out2 = SeparateStr('', config=True)
252 separate_out2 = SeparateStr('', config=True)
253
253
254 system_header = Str('IPython system call: ', config=True)
254 system_header = Str('IPython system call: ', config=True)
255 system_verbose = CBool(False, config=True)
255 system_verbose = CBool(False, config=True)
256 term_title = CBool(False, config=True)
256 term_title = CBool(False, config=True)
257 wildcards_case_sensitive = CBool(True, config=True)
257 wildcards_case_sensitive = CBool(True, config=True)
258 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
258 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
259 default_value='Context', config=True)
259 default_value='Context', config=True)
260
260
261 autoexec = List(allow_none=False)
261 autoexec = List(allow_none=False)
262
262
263 # class attribute to indicate whether the class supports threads or not.
263 # class attribute to indicate whether the class supports threads or not.
264 # Subclasses with thread support should override this as needed.
264 # Subclasses with thread support should override this as needed.
265 isthreaded = False
265 isthreaded = False
266
266
267 def __init__(self, parent=None, config=None, ipythondir=None, usage=None,
267 def __init__(self, parent=None, config=None, ipythondir=None, usage=None,
268 user_ns=None, user_global_ns=None,
268 user_ns=None, user_global_ns=None,
269 banner1=None, banner2=None, display_banner=None,
269 banner1=None, banner2=None, display_banner=None,
270 custom_exceptions=((),None)):
270 custom_exceptions=((),None)):
271
271
272 # This is where traitlets with a config_key argument are updated
272 # This is where traitlets with a config_key argument are updated
273 # from the values on config.
273 # from the values on config.
274 super(InteractiveShell, self).__init__(parent, config=config)
274 super(InteractiveShell, self).__init__(parent, config=config)
275
275
276 # These are relatively independent and stateless
276 # These are relatively independent and stateless
277 self.init_ipythondir(ipythondir)
277 self.init_ipythondir(ipythondir)
278 self.init_instance_attrs()
278 self.init_instance_attrs()
279 self.init_term_title()
279 self.init_term_title()
280 self.init_usage(usage)
280 self.init_usage(usage)
281 self.init_banner(banner1, banner2, display_banner)
281 self.init_banner(banner1, banner2, display_banner)
282
282
283 # Create namespaces (user_ns, user_global_ns, etc.)
283 # Create namespaces (user_ns, user_global_ns, etc.)
284 self.init_create_namespaces(user_ns, user_global_ns)
284 self.init_create_namespaces(user_ns, user_global_ns)
285 # This has to be done after init_create_namespaces because it uses
285 # This has to be done after init_create_namespaces because it uses
286 # something in self.user_ns, but before init_sys_modules, which
286 # something in self.user_ns, but before init_sys_modules, which
287 # is the first thing to modify sys.
287 # is the first thing to modify sys.
288 self.save_sys_module_state()
288 self.save_sys_module_state()
289 self.init_sys_modules()
289 self.init_sys_modules()
290
290
291 self.init_history()
291 self.init_history()
292 self.init_encoding()
292 self.init_encoding()
293 self.init_prefilter()
293 self.init_prefilter()
294
294
295 Magic.__init__(self, self)
295 Magic.__init__(self, self)
296
296
297 self.init_syntax_highlighting()
297 self.init_syntax_highlighting()
298 self.init_hooks()
298 self.init_hooks()
299 self.init_pushd_popd_magic()
299 self.init_pushd_popd_magic()
300 self.init_traceback_handlers(custom_exceptions)
300 self.init_traceback_handlers(custom_exceptions)
301 self.init_user_ns()
301 self.init_user_ns()
302 self.init_logger()
302 self.init_logger()
303 self.init_alias()
303 self.init_alias()
304 self.init_builtins()
304 self.init_builtins()
305
305
306 # pre_config_initialization
306 # pre_config_initialization
307 self.init_shadow_hist()
307 self.init_shadow_hist()
308
308
309 # The next section should contain averything that was in ipmaker.
309 # The next section should contain averything that was in ipmaker.
310 self.init_logstart()
310 self.init_logstart()
311
311
312 # The following was in post_config_initialization
312 # The following was in post_config_initialization
313 self.init_inspector()
313 self.init_inspector()
314 self.init_readline()
314 self.init_readline()
315 self.init_prompts()
315 self.init_prompts()
316 self.init_displayhook()
316 self.init_displayhook()
317 self.init_reload_doctest()
317 self.init_reload_doctest()
318 self.init_magics()
318 self.init_magics()
319 self.init_pdb()
319 self.init_pdb()
320 self.hooks.late_startup_hook()
320 self.hooks.late_startup_hook()
321
321
322 def get_ipython(self):
322 def get_ipython(self):
323 return self
323 return self
324
324
325 #-------------------------------------------------------------------------
325 #-------------------------------------------------------------------------
326 # Traitlet changed handlers
326 # Traitlet changed handlers
327 #-------------------------------------------------------------------------
327 #-------------------------------------------------------------------------
328
328
329 def _banner1_changed(self):
329 def _banner1_changed(self):
330 self.compute_banner()
330 self.compute_banner()
331
331
332 def _banner2_changed(self):
332 def _banner2_changed(self):
333 self.compute_banner()
333 self.compute_banner()
334
334
335 def _ipythondir_changed(self, name, new):
335 def _ipythondir_changed(self, name, new):
336 if not os.path.isdir(new):
336 if not os.path.isdir(new):
337 os.makedirs(new, mode = 0777)
337 os.makedirs(new, mode = 0777)
338 if not os.path.isdir(self.ipython_extension_dir):
338 if not os.path.isdir(self.ipython_extension_dir):
339 os.makedirs(self.ipython_extension_dir, mode = 0777)
339 os.makedirs(self.ipython_extension_dir, mode = 0777)
340
340
341 @property
341 @property
342 def ipython_extension_dir(self):
342 def ipython_extension_dir(self):
343 return os.path.join(self.ipythondir, 'extensions')
343 return os.path.join(self.ipythondir, 'extensions')
344
344
345 @property
345 @property
346 def usable_screen_length(self):
346 def usable_screen_length(self):
347 if self.screen_length == 0:
347 if self.screen_length == 0:
348 return 0
348 return 0
349 else:
349 else:
350 num_lines_bot = self.separate_in.count('\n')+1
350 num_lines_bot = self.separate_in.count('\n')+1
351 return self.screen_length - num_lines_bot
351 return self.screen_length - num_lines_bot
352
352
353 def _term_title_changed(self, name, new_value):
353 def _term_title_changed(self, name, new_value):
354 self.init_term_title()
354 self.init_term_title()
355
355
356 def set_autoindent(self,value=None):
356 def set_autoindent(self,value=None):
357 """Set the autoindent flag, checking for readline support.
357 """Set the autoindent flag, checking for readline support.
358
358
359 If called with no arguments, it acts as a toggle."""
359 If called with no arguments, it acts as a toggle."""
360
360
361 if not self.has_readline:
361 if not self.has_readline:
362 if os.name == 'posix':
362 if os.name == 'posix':
363 warn("The auto-indent feature requires the readline library")
363 warn("The auto-indent feature requires the readline library")
364 self.autoindent = 0
364 self.autoindent = 0
365 return
365 return
366 if value is None:
366 if value is None:
367 self.autoindent = not self.autoindent
367 self.autoindent = not self.autoindent
368 else:
368 else:
369 self.autoindent = value
369 self.autoindent = value
370
370
371 #-------------------------------------------------------------------------
371 #-------------------------------------------------------------------------
372 # init_* methods called by __init__
372 # init_* methods called by __init__
373 #-------------------------------------------------------------------------
373 #-------------------------------------------------------------------------
374
374
375 def init_ipythondir(self, ipythondir):
375 def init_ipythondir(self, ipythondir):
376 if ipythondir is not None:
376 if ipythondir is not None:
377 self.ipythondir = ipythondir
377 self.ipythondir = ipythondir
378 self.config.Global.ipythondir = self.ipythondir
378 self.config.Global.ipythondir = self.ipythondir
379 return
379 return
380
380
381 if hasattr(self.config.Global, 'ipythondir'):
381 if hasattr(self.config.Global, 'ipythondir'):
382 self.ipythondir = self.config.Global.ipythondir
382 self.ipythondir = self.config.Global.ipythondir
383 else:
383 else:
384 self.ipythondir = get_ipython_dir()
384 self.ipythondir = get_ipython_dir()
385
385
386 # All children can just read this
386 # All children can just read this
387 self.config.Global.ipythondir = self.ipythondir
387 self.config.Global.ipythondir = self.ipythondir
388
388
389 def init_instance_attrs(self):
389 def init_instance_attrs(self):
390 self.jobs = BackgroundJobManager()
390 self.jobs = BackgroundJobManager()
391 self.more = False
391 self.more = False
392
392
393 # command compiler
393 # command compiler
394 self.compile = codeop.CommandCompiler()
394 self.compile = codeop.CommandCompiler()
395
395
396 # User input buffer
396 # User input buffer
397 self.buffer = []
397 self.buffer = []
398
398
399 # Make an empty namespace, which extension writers can rely on both
399 # Make an empty namespace, which extension writers can rely on both
400 # existing and NEVER being used by ipython itself. This gives them a
400 # existing and NEVER being used by ipython itself. This gives them a
401 # convenient location for storing additional information and state
401 # convenient location for storing additional information and state
402 # their extensions may require, without fear of collisions with other
402 # their extensions may require, without fear of collisions with other
403 # ipython names that may develop later.
403 # ipython names that may develop later.
404 self.meta = Struct()
404 self.meta = Struct()
405
405
406 # Object variable to store code object waiting execution. This is
406 # Object variable to store code object waiting execution. This is
407 # used mainly by the multithreaded shells, but it can come in handy in
407 # used mainly by the multithreaded shells, but it can come in handy in
408 # other situations. No need to use a Queue here, since it's a single
408 # other situations. No need to use a Queue here, since it's a single
409 # item which gets cleared once run.
409 # item which gets cleared once run.
410 self.code_to_run = None
410 self.code_to_run = None
411
411
412 # Flag to mark unconditional exit
412 # Flag to mark unconditional exit
413 self.exit_now = False
413 self.exit_now = False
414
414
415 # Temporary files used for various purposes. Deleted at exit.
415 # Temporary files used for various purposes. Deleted at exit.
416 self.tempfiles = []
416 self.tempfiles = []
417
417
418 # Keep track of readline usage (later set by init_readline)
418 # Keep track of readline usage (later set by init_readline)
419 self.has_readline = False
419 self.has_readline = False
420
420
421 # keep track of where we started running (mainly for crash post-mortem)
421 # keep track of where we started running (mainly for crash post-mortem)
422 # This is not being used anywhere currently.
422 # This is not being used anywhere currently.
423 self.starting_dir = os.getcwd()
423 self.starting_dir = os.getcwd()
424
424
425 # Indentation management
425 # Indentation management
426 self.indent_current_nsp = 0
426 self.indent_current_nsp = 0
427
427
428 def init_term_title(self):
428 def init_term_title(self):
429 # Enable or disable the terminal title.
429 # Enable or disable the terminal title.
430 if self.term_title:
430 if self.term_title:
431 toggle_set_term_title(True)
431 toggle_set_term_title(True)
432 set_term_title('IPython: ' + abbrev_cwd())
432 set_term_title('IPython: ' + abbrev_cwd())
433 else:
433 else:
434 toggle_set_term_title(False)
434 toggle_set_term_title(False)
435
435
436 def init_usage(self, usage=None):
436 def init_usage(self, usage=None):
437 if usage is None:
437 if usage is None:
438 self.usage = interactive_usage
438 self.usage = interactive_usage
439 else:
439 else:
440 self.usage = usage
440 self.usage = usage
441
441
442 def init_encoding(self):
442 def init_encoding(self):
443 # Get system encoding at startup time. Certain terminals (like Emacs
443 # Get system encoding at startup time. Certain terminals (like Emacs
444 # under Win32 have it set to None, and we need to have a known valid
444 # under Win32 have it set to None, and we need to have a known valid
445 # encoding to use in the raw_input() method
445 # encoding to use in the raw_input() method
446 try:
446 try:
447 self.stdin_encoding = sys.stdin.encoding or 'ascii'
447 self.stdin_encoding = sys.stdin.encoding or 'ascii'
448 except AttributeError:
448 except AttributeError:
449 self.stdin_encoding = 'ascii'
449 self.stdin_encoding = 'ascii'
450
450
451 def init_syntax_highlighting(self):
451 def init_syntax_highlighting(self):
452 # Python source parser/formatter for syntax highlighting
452 # Python source parser/formatter for syntax highlighting
453 pyformat = PyColorize.Parser().format
453 pyformat = PyColorize.Parser().format
454 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
454 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
455
455
456 def init_pushd_popd_magic(self):
456 def init_pushd_popd_magic(self):
457 # for pushd/popd management
457 # for pushd/popd management
458 try:
458 try:
459 self.home_dir = get_home_dir()
459 self.home_dir = get_home_dir()
460 except HomeDirError, msg:
460 except HomeDirError, msg:
461 fatal(msg)
461 fatal(msg)
462
462
463 self.dir_stack = []
463 self.dir_stack = []
464
464
465 def init_logger(self):
465 def init_logger(self):
466 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
466 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
467 # local shortcut, this is used a LOT
467 # local shortcut, this is used a LOT
468 self.log = self.logger.log
468 self.log = self.logger.log
469
469
470 def init_logstart(self):
470 def init_logstart(self):
471 if self.logappend:
471 if self.logappend:
472 self.magic_logstart(self.logappend + ' append')
472 self.magic_logstart(self.logappend + ' append')
473 elif self.logfile:
473 elif self.logfile:
474 self.magic_logstart(self.logfile)
474 self.magic_logstart(self.logfile)
475 elif self.logstart:
475 elif self.logstart:
476 self.magic_logstart()
476 self.magic_logstart()
477
477
478 def init_builtins(self):
478 def init_builtins(self):
479 self.builtin_trap = BuiltinTrap(self)
479 self.builtin_trap = BuiltinTrap(self)
480
480
481 def init_inspector(self):
481 def init_inspector(self):
482 # Object inspector
482 # Object inspector
483 self.inspector = oinspect.Inspector(oinspect.InspectColors,
483 self.inspector = oinspect.Inspector(oinspect.InspectColors,
484 PyColorize.ANSICodeColors,
484 PyColorize.ANSICodeColors,
485 'NoColor',
485 'NoColor',
486 self.object_info_string_level)
486 self.object_info_string_level)
487
487
488 def init_prompts(self):
488 def init_prompts(self):
489 # Initialize cache, set in/out prompts and printing system
489 # Initialize cache, set in/out prompts and printing system
490 self.outputcache = CachedOutput(self,
490 self.outputcache = CachedOutput(self,
491 self.cache_size,
491 self.cache_size,
492 self.pprint,
492 self.pprint,
493 input_sep = self.separate_in,
493 input_sep = self.separate_in,
494 output_sep = self.separate_out,
494 output_sep = self.separate_out,
495 output_sep2 = self.separate_out2,
495 output_sep2 = self.separate_out2,
496 ps1 = self.prompt_in1,
496 ps1 = self.prompt_in1,
497 ps2 = self.prompt_in2,
497 ps2 = self.prompt_in2,
498 ps_out = self.prompt_out,
498 ps_out = self.prompt_out,
499 pad_left = self.prompts_pad_left)
499 pad_left = self.prompts_pad_left)
500
500
501 # user may have over-ridden the default print hook:
501 # user may have over-ridden the default print hook:
502 try:
502 try:
503 self.outputcache.__class__.display = self.hooks.display
503 self.outputcache.__class__.display = self.hooks.display
504 except AttributeError:
504 except AttributeError:
505 pass
505 pass
506
506
507 def init_displayhook(self):
507 def init_displayhook(self):
508 self.display_trap = DisplayTrap(self, self.outputcache)
508 self.display_trap = DisplayTrap(self, self.outputcache)
509
509
510 def init_reload_doctest(self):
510 def init_reload_doctest(self):
511 # Do a proper resetting of doctest, including the necessary displayhook
511 # Do a proper resetting of doctest, including the necessary displayhook
512 # monkeypatching
512 # monkeypatching
513 try:
513 try:
514 doctest_reload()
514 doctest_reload()
515 except ImportError:
515 except ImportError:
516 warn("doctest module does not exist.")
516 warn("doctest module does not exist.")
517
517
518 #-------------------------------------------------------------------------
518 #-------------------------------------------------------------------------
519 # Things related to the banner
519 # Things related to the banner
520 #-------------------------------------------------------------------------
520 #-------------------------------------------------------------------------
521
521
522 def init_banner(self, banner1, banner2, display_banner):
522 def init_banner(self, banner1, banner2, display_banner):
523 if banner1 is not None:
523 if banner1 is not None:
524 self.banner1 = banner1
524 self.banner1 = banner1
525 if banner2 is not None:
525 if banner2 is not None:
526 self.banner2 = banner2
526 self.banner2 = banner2
527 if display_banner is not None:
527 if display_banner is not None:
528 self.display_banner = display_banner
528 self.display_banner = display_banner
529 self.compute_banner()
529 self.compute_banner()
530
530
531 def show_banner(self, banner=None):
531 def show_banner(self, banner=None):
532 if banner is None:
532 if banner is None:
533 banner = self.banner
533 banner = self.banner
534 self.write(banner)
534 self.write(banner)
535
535
536 def compute_banner(self):
536 def compute_banner(self):
537 self.banner = self.banner1 + '\n'
537 self.banner = self.banner1 + '\n'
538 if self.profile:
538 if self.profile:
539 self.banner += '\nIPython profile: %s\n' % self.profile
539 self.banner += '\nIPython profile: %s\n' % self.profile
540 if self.banner2:
540 if self.banner2:
541 self.banner += '\n' + self.banner2 + '\n'
541 self.banner += '\n' + self.banner2 + '\n'
542
542
543 #-------------------------------------------------------------------------
543 #-------------------------------------------------------------------------
544 # Things related to injections into the sys module
544 # Things related to injections into the sys module
545 #-------------------------------------------------------------------------
545 #-------------------------------------------------------------------------
546
546
547 def save_sys_module_state(self):
547 def save_sys_module_state(self):
548 """Save the state of hooks in the sys module.
548 """Save the state of hooks in the sys module.
549
549
550 This has to be called after self.user_ns is created.
550 This has to be called after self.user_ns is created.
551 """
551 """
552 self._orig_sys_module_state = {}
552 self._orig_sys_module_state = {}
553 self._orig_sys_module_state['stdin'] = sys.stdin
553 self._orig_sys_module_state['stdin'] = sys.stdin
554 self._orig_sys_module_state['stdout'] = sys.stdout
554 self._orig_sys_module_state['stdout'] = sys.stdout
555 self._orig_sys_module_state['stderr'] = sys.stderr
555 self._orig_sys_module_state['stderr'] = sys.stderr
556 self._orig_sys_module_state['excepthook'] = sys.excepthook
556 self._orig_sys_module_state['excepthook'] = sys.excepthook
557 try:
557 try:
558 self._orig_sys_modules_main_name = self.user_ns['__name__']
558 self._orig_sys_modules_main_name = self.user_ns['__name__']
559 except KeyError:
559 except KeyError:
560 pass
560 pass
561
561
562 def restore_sys_module_state(self):
562 def restore_sys_module_state(self):
563 """Restore the state of the sys module."""
563 """Restore the state of the sys module."""
564 try:
564 try:
565 for k, v in self._orig_sys_module_state.items():
565 for k, v in self._orig_sys_module_state.items():
566 setattr(sys, k, v)
566 setattr(sys, k, v)
567 except AttributeError:
567 except AttributeError:
568 pass
568 pass
569 try:
569 try:
570 delattr(sys, 'ipcompleter')
570 delattr(sys, 'ipcompleter')
571 except AttributeError:
571 except AttributeError:
572 pass
572 pass
573 # Reset what what done in self.init_sys_modules
573 # Reset what what done in self.init_sys_modules
574 try:
574 try:
575 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
575 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
576 except (AttributeError, KeyError):
576 except (AttributeError, KeyError):
577 pass
577 pass
578
578
579 #-------------------------------------------------------------------------
579 #-------------------------------------------------------------------------
580 # Things related to hooks
580 # Things related to hooks
581 #-------------------------------------------------------------------------
581 #-------------------------------------------------------------------------
582
582
583 def init_hooks(self):
583 def init_hooks(self):
584 # hooks holds pointers used for user-side customizations
584 # hooks holds pointers used for user-side customizations
585 self.hooks = Struct()
585 self.hooks = Struct()
586
586
587 self.strdispatchers = {}
587 self.strdispatchers = {}
588
588
589 # Set all default hooks, defined in the IPython.hooks module.
589 # Set all default hooks, defined in the IPython.hooks module.
590 import IPython.core.hooks
590 import IPython.core.hooks
591 hooks = IPython.core.hooks
591 hooks = IPython.core.hooks
592 for hook_name in hooks.__all__:
592 for hook_name in hooks.__all__:
593 # default hooks have priority 100, i.e. low; user hooks should have
593 # default hooks have priority 100, i.e. low; user hooks should have
594 # 0-100 priority
594 # 0-100 priority
595 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
595 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
596
596
597 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
597 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
598 """set_hook(name,hook) -> sets an internal IPython hook.
598 """set_hook(name,hook) -> sets an internal IPython hook.
599
599
600 IPython exposes some of its internal API as user-modifiable hooks. By
600 IPython exposes some of its internal API as user-modifiable hooks. By
601 adding your function to one of these hooks, you can modify IPython's
601 adding your function to one of these hooks, you can modify IPython's
602 behavior to call at runtime your own routines."""
602 behavior to call at runtime your own routines."""
603
603
604 # At some point in the future, this should validate the hook before it
604 # At some point in the future, this should validate the hook before it
605 # accepts it. Probably at least check that the hook takes the number
605 # accepts it. Probably at least check that the hook takes the number
606 # of args it's supposed to.
606 # of args it's supposed to.
607
607
608 f = new.instancemethod(hook,self,self.__class__)
608 f = new.instancemethod(hook,self,self.__class__)
609
609
610 # check if the hook is for strdispatcher first
610 # check if the hook is for strdispatcher first
611 if str_key is not None:
611 if str_key is not None:
612 sdp = self.strdispatchers.get(name, StrDispatch())
612 sdp = self.strdispatchers.get(name, StrDispatch())
613 sdp.add_s(str_key, f, priority )
613 sdp.add_s(str_key, f, priority )
614 self.strdispatchers[name] = sdp
614 self.strdispatchers[name] = sdp
615 return
615 return
616 if re_key is not None:
616 if re_key is not None:
617 sdp = self.strdispatchers.get(name, StrDispatch())
617 sdp = self.strdispatchers.get(name, StrDispatch())
618 sdp.add_re(re.compile(re_key), f, priority )
618 sdp.add_re(re.compile(re_key), f, priority )
619 self.strdispatchers[name] = sdp
619 self.strdispatchers[name] = sdp
620 return
620 return
621
621
622 dp = getattr(self.hooks, name, None)
622 dp = getattr(self.hooks, name, None)
623 if name not in IPython.core.hooks.__all__:
623 if name not in IPython.core.hooks.__all__:
624 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
624 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
625 if not dp:
625 if not dp:
626 dp = IPython.core.hooks.CommandChainDispatcher()
626 dp = IPython.core.hooks.CommandChainDispatcher()
627
627
628 try:
628 try:
629 dp.add(f,priority)
629 dp.add(f,priority)
630 except AttributeError:
630 except AttributeError:
631 # it was not commandchain, plain old func - replace
631 # it was not commandchain, plain old func - replace
632 dp = f
632 dp = f
633
633
634 setattr(self.hooks,name, dp)
634 setattr(self.hooks,name, dp)
635
635
636 #-------------------------------------------------------------------------
636 #-------------------------------------------------------------------------
637 # Things related to the "main" module
637 # Things related to the "main" module
638 #-------------------------------------------------------------------------
638 #-------------------------------------------------------------------------
639
639
640 def new_main_mod(self,ns=None):
640 def new_main_mod(self,ns=None):
641 """Return a new 'main' module object for user code execution.
641 """Return a new 'main' module object for user code execution.
642 """
642 """
643 main_mod = self._user_main_module
643 main_mod = self._user_main_module
644 init_fakemod_dict(main_mod,ns)
644 init_fakemod_dict(main_mod,ns)
645 return main_mod
645 return main_mod
646
646
647 def cache_main_mod(self,ns,fname):
647 def cache_main_mod(self,ns,fname):
648 """Cache a main module's namespace.
648 """Cache a main module's namespace.
649
649
650 When scripts are executed via %run, we must keep a reference to the
650 When scripts are executed via %run, we must keep a reference to the
651 namespace of their __main__ module (a FakeModule instance) around so
651 namespace of their __main__ module (a FakeModule instance) around so
652 that Python doesn't clear it, rendering objects defined therein
652 that Python doesn't clear it, rendering objects defined therein
653 useless.
653 useless.
654
654
655 This method keeps said reference in a private dict, keyed by the
655 This method keeps said reference in a private dict, keyed by the
656 absolute path of the module object (which corresponds to the script
656 absolute path of the module object (which corresponds to the script
657 path). This way, for multiple executions of the same script we only
657 path). This way, for multiple executions of the same script we only
658 keep one copy of the namespace (the last one), thus preventing memory
658 keep one copy of the namespace (the last one), thus preventing memory
659 leaks from old references while allowing the objects from the last
659 leaks from old references while allowing the objects from the last
660 execution to be accessible.
660 execution to be accessible.
661
661
662 Note: we can not allow the actual FakeModule instances to be deleted,
662 Note: we can not allow the actual FakeModule instances to be deleted,
663 because of how Python tears down modules (it hard-sets all their
663 because of how Python tears down modules (it hard-sets all their
664 references to None without regard for reference counts). This method
664 references to None without regard for reference counts). This method
665 must therefore make a *copy* of the given namespace, to allow the
665 must therefore make a *copy* of the given namespace, to allow the
666 original module's __dict__ to be cleared and reused.
666 original module's __dict__ to be cleared and reused.
667
667
668
668
669 Parameters
669 Parameters
670 ----------
670 ----------
671 ns : a namespace (a dict, typically)
671 ns : a namespace (a dict, typically)
672
672
673 fname : str
673 fname : str
674 Filename associated with the namespace.
674 Filename associated with the namespace.
675
675
676 Examples
676 Examples
677 --------
677 --------
678
678
679 In [10]: import IPython
679 In [10]: import IPython
680
680
681 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
681 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
682
682
683 In [12]: IPython.__file__ in _ip._main_ns_cache
683 In [12]: IPython.__file__ in _ip._main_ns_cache
684 Out[12]: True
684 Out[12]: True
685 """
685 """
686 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
686 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
687
687
688 def clear_main_mod_cache(self):
688 def clear_main_mod_cache(self):
689 """Clear the cache of main modules.
689 """Clear the cache of main modules.
690
690
691 Mainly for use by utilities like %reset.
691 Mainly for use by utilities like %reset.
692
692
693 Examples
693 Examples
694 --------
694 --------
695
695
696 In [15]: import IPython
696 In [15]: import IPython
697
697
698 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
698 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
699
699
700 In [17]: len(_ip._main_ns_cache) > 0
700 In [17]: len(_ip._main_ns_cache) > 0
701 Out[17]: True
701 Out[17]: True
702
702
703 In [18]: _ip.clear_main_mod_cache()
703 In [18]: _ip.clear_main_mod_cache()
704
704
705 In [19]: len(_ip._main_ns_cache) == 0
705 In [19]: len(_ip._main_ns_cache) == 0
706 Out[19]: True
706 Out[19]: True
707 """
707 """
708 self._main_ns_cache.clear()
708 self._main_ns_cache.clear()
709
709
710 #-------------------------------------------------------------------------
710 #-------------------------------------------------------------------------
711 # Things related to debugging
711 # Things related to debugging
712 #-------------------------------------------------------------------------
712 #-------------------------------------------------------------------------
713
713
714 def init_pdb(self):
714 def init_pdb(self):
715 # Set calling of pdb on exceptions
715 # Set calling of pdb on exceptions
716 # self.call_pdb is a property
716 # self.call_pdb is a property
717 self.call_pdb = self.pdb
717 self.call_pdb = self.pdb
718
718
719 def _get_call_pdb(self):
719 def _get_call_pdb(self):
720 return self._call_pdb
720 return self._call_pdb
721
721
722 def _set_call_pdb(self,val):
722 def _set_call_pdb(self,val):
723
723
724 if val not in (0,1,False,True):
724 if val not in (0,1,False,True):
725 raise ValueError,'new call_pdb value must be boolean'
725 raise ValueError,'new call_pdb value must be boolean'
726
726
727 # store value in instance
727 # store value in instance
728 self._call_pdb = val
728 self._call_pdb = val
729
729
730 # notify the actual exception handlers
730 # notify the actual exception handlers
731 self.InteractiveTB.call_pdb = val
731 self.InteractiveTB.call_pdb = val
732 if self.isthreaded:
732 if self.isthreaded:
733 try:
733 try:
734 self.sys_excepthook.call_pdb = val
734 self.sys_excepthook.call_pdb = val
735 except:
735 except:
736 warn('Failed to activate pdb for threaded exception handler')
736 warn('Failed to activate pdb for threaded exception handler')
737
737
738 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
738 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
739 'Control auto-activation of pdb at exceptions')
739 'Control auto-activation of pdb at exceptions')
740
740
741 def debugger(self,force=False):
741 def debugger(self,force=False):
742 """Call the pydb/pdb debugger.
742 """Call the pydb/pdb debugger.
743
743
744 Keywords:
744 Keywords:
745
745
746 - force(False): by default, this routine checks the instance call_pdb
746 - force(False): by default, this routine checks the instance call_pdb
747 flag and does not actually invoke the debugger if the flag is false.
747 flag and does not actually invoke the debugger if the flag is false.
748 The 'force' option forces the debugger to activate even if the flag
748 The 'force' option forces the debugger to activate even if the flag
749 is false.
749 is false.
750 """
750 """
751
751
752 if not (force or self.call_pdb):
752 if not (force or self.call_pdb):
753 return
753 return
754
754
755 if not hasattr(sys,'last_traceback'):
755 if not hasattr(sys,'last_traceback'):
756 error('No traceback has been produced, nothing to debug.')
756 error('No traceback has been produced, nothing to debug.')
757 return
757 return
758
758
759 # use pydb if available
759 # use pydb if available
760 if debugger.has_pydb:
760 if debugger.has_pydb:
761 from pydb import pm
761 from pydb import pm
762 else:
762 else:
763 # fallback to our internal debugger
763 # fallback to our internal debugger
764 pm = lambda : self.InteractiveTB.debugger(force=True)
764 pm = lambda : self.InteractiveTB.debugger(force=True)
765 self.history_saving_wrapper(pm)()
765 self.history_saving_wrapper(pm)()
766
766
767 #-------------------------------------------------------------------------
767 #-------------------------------------------------------------------------
768 # Things related to IPython's various namespaces
768 # Things related to IPython's various namespaces
769 #-------------------------------------------------------------------------
769 #-------------------------------------------------------------------------
770
770
771 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
771 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
772 # Create the namespace where the user will operate. user_ns is
772 # Create the namespace where the user will operate. user_ns is
773 # normally the only one used, and it is passed to the exec calls as
773 # normally the only one used, and it is passed to the exec calls as
774 # the locals argument. But we do carry a user_global_ns namespace
774 # the locals argument. But we do carry a user_global_ns namespace
775 # given as the exec 'globals' argument, This is useful in embedding
775 # given as the exec 'globals' argument, This is useful in embedding
776 # situations where the ipython shell opens in a context where the
776 # situations where the ipython shell opens in a context where the
777 # distinction between locals and globals is meaningful. For
777 # distinction between locals and globals is meaningful. For
778 # non-embedded contexts, it is just the same object as the user_ns dict.
778 # non-embedded contexts, it is just the same object as the user_ns dict.
779
779
780 # FIXME. For some strange reason, __builtins__ is showing up at user
780 # FIXME. For some strange reason, __builtins__ is showing up at user
781 # level as a dict instead of a module. This is a manual fix, but I
781 # level as a dict instead of a module. This is a manual fix, but I
782 # should really track down where the problem is coming from. Alex
782 # should really track down where the problem is coming from. Alex
783 # Schmolck reported this problem first.
783 # Schmolck reported this problem first.
784
784
785 # A useful post by Alex Martelli on this topic:
785 # A useful post by Alex Martelli on this topic:
786 # Re: inconsistent value from __builtins__
786 # Re: inconsistent value from __builtins__
787 # Von: Alex Martelli <aleaxit@yahoo.com>
787 # Von: Alex Martelli <aleaxit@yahoo.com>
788 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
788 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
789 # Gruppen: comp.lang.python
789 # Gruppen: comp.lang.python
790
790
791 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
791 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
792 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
792 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
793 # > <type 'dict'>
793 # > <type 'dict'>
794 # > >>> print type(__builtins__)
794 # > >>> print type(__builtins__)
795 # > <type 'module'>
795 # > <type 'module'>
796 # > Is this difference in return value intentional?
796 # > Is this difference in return value intentional?
797
797
798 # Well, it's documented that '__builtins__' can be either a dictionary
798 # Well, it's documented that '__builtins__' can be either a dictionary
799 # or a module, and it's been that way for a long time. Whether it's
799 # or a module, and it's been that way for a long time. Whether it's
800 # intentional (or sensible), I don't know. In any case, the idea is
800 # intentional (or sensible), I don't know. In any case, the idea is
801 # that if you need to access the built-in namespace directly, you
801 # that if you need to access the built-in namespace directly, you
802 # should start with "import __builtin__" (note, no 's') which will
802 # should start with "import __builtin__" (note, no 's') which will
803 # definitely give you a module. Yeah, it's somewhat confusing:-(.
803 # definitely give you a module. Yeah, it's somewhat confusing:-(.
804
804
805 # These routines return properly built dicts as needed by the rest of
805 # These routines return properly built dicts as needed by the rest of
806 # the code, and can also be used by extension writers to generate
806 # the code, and can also be used by extension writers to generate
807 # properly initialized namespaces.
807 # properly initialized namespaces.
808 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
808 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
809 user_global_ns)
809 user_global_ns)
810
810
811 # Assign namespaces
811 # Assign namespaces
812 # This is the namespace where all normal user variables live
812 # This is the namespace where all normal user variables live
813 self.user_ns = user_ns
813 self.user_ns = user_ns
814 self.user_global_ns = user_global_ns
814 self.user_global_ns = user_global_ns
815
815
816 # An auxiliary namespace that checks what parts of the user_ns were
816 # An auxiliary namespace that checks what parts of the user_ns were
817 # loaded at startup, so we can list later only variables defined in
817 # loaded at startup, so we can list later only variables defined in
818 # actual interactive use. Since it is always a subset of user_ns, it
818 # actual interactive use. Since it is always a subset of user_ns, it
819 # doesn't need to be seaparately tracked in the ns_table
819 # doesn't need to be seaparately tracked in the ns_table
820 self.user_config_ns = {}
820 self.user_config_ns = {}
821
821
822 # A namespace to keep track of internal data structures to prevent
822 # A namespace to keep track of internal data structures to prevent
823 # them from cluttering user-visible stuff. Will be updated later
823 # them from cluttering user-visible stuff. Will be updated later
824 self.internal_ns = {}
824 self.internal_ns = {}
825
825
826 # Now that FakeModule produces a real module, we've run into a nasty
826 # Now that FakeModule produces a real module, we've run into a nasty
827 # problem: after script execution (via %run), the module where the user
827 # problem: after script execution (via %run), the module where the user
828 # code ran is deleted. Now that this object is a true module (needed
828 # code ran is deleted. Now that this object is a true module (needed
829 # so docetst and other tools work correctly), the Python module
829 # so docetst and other tools work correctly), the Python module
830 # teardown mechanism runs over it, and sets to None every variable
830 # teardown mechanism runs over it, and sets to None every variable
831 # present in that module. Top-level references to objects from the
831 # present in that module. Top-level references to objects from the
832 # script survive, because the user_ns is updated with them. However,
832 # script survive, because the user_ns is updated with them. However,
833 # calling functions defined in the script that use other things from
833 # calling functions defined in the script that use other things from
834 # the script will fail, because the function's closure had references
834 # the script will fail, because the function's closure had references
835 # to the original objects, which are now all None. So we must protect
835 # to the original objects, which are now all None. So we must protect
836 # these modules from deletion by keeping a cache.
836 # these modules from deletion by keeping a cache.
837 #
837 #
838 # To avoid keeping stale modules around (we only need the one from the
838 # To avoid keeping stale modules around (we only need the one from the
839 # last run), we use a dict keyed with the full path to the script, so
839 # last run), we use a dict keyed with the full path to the script, so
840 # only the last version of the module is held in the cache. Note,
840 # only the last version of the module is held in the cache. Note,
841 # however, that we must cache the module *namespace contents* (their
841 # however, that we must cache the module *namespace contents* (their
842 # __dict__). Because if we try to cache the actual modules, old ones
842 # __dict__). Because if we try to cache the actual modules, old ones
843 # (uncached) could be destroyed while still holding references (such as
843 # (uncached) could be destroyed while still holding references (such as
844 # those held by GUI objects that tend to be long-lived)>
844 # those held by GUI objects that tend to be long-lived)>
845 #
845 #
846 # The %reset command will flush this cache. See the cache_main_mod()
846 # The %reset command will flush this cache. See the cache_main_mod()
847 # and clear_main_mod_cache() methods for details on use.
847 # and clear_main_mod_cache() methods for details on use.
848
848
849 # This is the cache used for 'main' namespaces
849 # This is the cache used for 'main' namespaces
850 self._main_ns_cache = {}
850 self._main_ns_cache = {}
851 # And this is the single instance of FakeModule whose __dict__ we keep
851 # And this is the single instance of FakeModule whose __dict__ we keep
852 # copying and clearing for reuse on each %run
852 # copying and clearing for reuse on each %run
853 self._user_main_module = FakeModule()
853 self._user_main_module = FakeModule()
854
854
855 # A table holding all the namespaces IPython deals with, so that
855 # A table holding all the namespaces IPython deals with, so that
856 # introspection facilities can search easily.
856 # introspection facilities can search easily.
857 self.ns_table = {'user':user_ns,
857 self.ns_table = {'user':user_ns,
858 'user_global':user_global_ns,
858 'user_global':user_global_ns,
859 'internal':self.internal_ns,
859 'internal':self.internal_ns,
860 'builtin':__builtin__.__dict__
860 'builtin':__builtin__.__dict__
861 }
861 }
862
862
863 # Similarly, track all namespaces where references can be held and that
863 # Similarly, track all namespaces where references can be held and that
864 # we can safely clear (so it can NOT include builtin). This one can be
864 # we can safely clear (so it can NOT include builtin). This one can be
865 # a simple list.
865 # a simple list.
866 self.ns_refs_table = [ user_ns, user_global_ns, self.user_config_ns,
866 self.ns_refs_table = [ user_ns, user_global_ns, self.user_config_ns,
867 self.internal_ns, self._main_ns_cache ]
867 self.internal_ns, self._main_ns_cache ]
868
868
869 def init_sys_modules(self):
869 def init_sys_modules(self):
870 # We need to insert into sys.modules something that looks like a
870 # We need to insert into sys.modules something that looks like a
871 # module but which accesses the IPython namespace, for shelve and
871 # module but which accesses the IPython namespace, for shelve and
872 # pickle to work interactively. Normally they rely on getting
872 # pickle to work interactively. Normally they rely on getting
873 # everything out of __main__, but for embedding purposes each IPython
873 # everything out of __main__, but for embedding purposes each IPython
874 # instance has its own private namespace, so we can't go shoving
874 # instance has its own private namespace, so we can't go shoving
875 # everything into __main__.
875 # everything into __main__.
876
876
877 # note, however, that we should only do this for non-embedded
877 # note, however, that we should only do this for non-embedded
878 # ipythons, which really mimic the __main__.__dict__ with their own
878 # ipythons, which really mimic the __main__.__dict__ with their own
879 # namespace. Embedded instances, on the other hand, should not do
879 # namespace. Embedded instances, on the other hand, should not do
880 # this because they need to manage the user local/global namespaces
880 # this because they need to manage the user local/global namespaces
881 # only, but they live within a 'normal' __main__ (meaning, they
881 # only, but they live within a 'normal' __main__ (meaning, they
882 # shouldn't overtake the execution environment of the script they're
882 # shouldn't overtake the execution environment of the script they're
883 # embedded in).
883 # embedded in).
884
884
885 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
885 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
886
886
887 try:
887 try:
888 main_name = self.user_ns['__name__']
888 main_name = self.user_ns['__name__']
889 except KeyError:
889 except KeyError:
890 raise KeyError('user_ns dictionary MUST have a "__name__" key')
890 raise KeyError('user_ns dictionary MUST have a "__name__" key')
891 else:
891 else:
892 sys.modules[main_name] = FakeModule(self.user_ns)
892 sys.modules[main_name] = FakeModule(self.user_ns)
893
893
894 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
894 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
895 """Return a valid local and global user interactive namespaces.
895 """Return a valid local and global user interactive namespaces.
896
896
897 This builds a dict with the minimal information needed to operate as a
897 This builds a dict with the minimal information needed to operate as a
898 valid IPython user namespace, which you can pass to the various
898 valid IPython user namespace, which you can pass to the various
899 embedding classes in ipython. The default implementation returns the
899 embedding classes in ipython. The default implementation returns the
900 same dict for both the locals and the globals to allow functions to
900 same dict for both the locals and the globals to allow functions to
901 refer to variables in the namespace. Customized implementations can
901 refer to variables in the namespace. Customized implementations can
902 return different dicts. The locals dictionary can actually be anything
902 return different dicts. The locals dictionary can actually be anything
903 following the basic mapping protocol of a dict, but the globals dict
903 following the basic mapping protocol of a dict, but the globals dict
904 must be a true dict, not even a subclass. It is recommended that any
904 must be a true dict, not even a subclass. It is recommended that any
905 custom object for the locals namespace synchronize with the globals
905 custom object for the locals namespace synchronize with the globals
906 dict somehow.
906 dict somehow.
907
907
908 Raises TypeError if the provided globals namespace is not a true dict.
908 Raises TypeError if the provided globals namespace is not a true dict.
909
909
910 :Parameters:
910 :Parameters:
911 user_ns : dict-like, optional
911 user_ns : dict-like, optional
912 The current user namespace. The items in this namespace should
912 The current user namespace. The items in this namespace should
913 be included in the output. If None, an appropriate blank
913 be included in the output. If None, an appropriate blank
914 namespace should be created.
914 namespace should be created.
915 user_global_ns : dict, optional
915 user_global_ns : dict, optional
916 The current user global namespace. The items in this namespace
916 The current user global namespace. The items in this namespace
917 should be included in the output. If None, an appropriate
917 should be included in the output. If None, an appropriate
918 blank namespace should be created.
918 blank namespace should be created.
919
919
920 :Returns:
920 :Returns:
921 A tuple pair of dictionary-like object to be used as the local namespace
921 A tuple pair of dictionary-like object to be used as the local namespace
922 of the interpreter and a dict to be used as the global namespace.
922 of the interpreter and a dict to be used as the global namespace.
923 """
923 """
924
924
925 if user_ns is None:
925 if user_ns is None:
926 # Set __name__ to __main__ to better match the behavior of the
926 # Set __name__ to __main__ to better match the behavior of the
927 # normal interpreter.
927 # normal interpreter.
928 user_ns = {'__name__' :'__main__',
928 user_ns = {'__name__' :'__main__',
929 '__builtins__' : __builtin__,
929 '__builtins__' : __builtin__,
930 }
930 }
931 else:
931 else:
932 user_ns.setdefault('__name__','__main__')
932 user_ns.setdefault('__name__','__main__')
933 user_ns.setdefault('__builtins__',__builtin__)
933 user_ns.setdefault('__builtins__',__builtin__)
934
934
935 if user_global_ns is None:
935 if user_global_ns is None:
936 user_global_ns = user_ns
936 user_global_ns = user_ns
937 if type(user_global_ns) is not dict:
937 if type(user_global_ns) is not dict:
938 raise TypeError("user_global_ns must be a true dict; got %r"
938 raise TypeError("user_global_ns must be a true dict; got %r"
939 % type(user_global_ns))
939 % type(user_global_ns))
940
940
941 return user_ns, user_global_ns
941 return user_ns, user_global_ns
942
942
943 def init_user_ns(self):
943 def init_user_ns(self):
944 """Initialize all user-visible namespaces to their minimum defaults.
944 """Initialize all user-visible namespaces to their minimum defaults.
945
945
946 Certain history lists are also initialized here, as they effectively
946 Certain history lists are also initialized here, as they effectively
947 act as user namespaces.
947 act as user namespaces.
948
948
949 Notes
949 Notes
950 -----
950 -----
951 All data structures here are only filled in, they are NOT reset by this
951 All data structures here are only filled in, they are NOT reset by this
952 method. If they were not empty before, data will simply be added to
952 method. If they were not empty before, data will simply be added to
953 therm.
953 therm.
954 """
954 """
955 # Store myself as the public api!!!
955 # Store myself as the public api!!!
956 self.user_ns['get_ipython'] = self.get_ipython
956 self.user_ns['get_ipython'] = self.get_ipython
957
957
958 # make global variables for user access to the histories
958 # make global variables for user access to the histories
959 self.user_ns['_ih'] = self.input_hist
959 self.user_ns['_ih'] = self.input_hist
960 self.user_ns['_oh'] = self.output_hist
960 self.user_ns['_oh'] = self.output_hist
961 self.user_ns['_dh'] = self.dir_hist
961 self.user_ns['_dh'] = self.dir_hist
962
962
963 # user aliases to input and output histories
963 # user aliases to input and output histories
964 self.user_ns['In'] = self.input_hist
964 self.user_ns['In'] = self.input_hist
965 self.user_ns['Out'] = self.output_hist
965 self.user_ns['Out'] = self.output_hist
966
966
967 self.user_ns['_sh'] = shadowns
967 self.user_ns['_sh'] = shadowns
968
968
969 # Put 'help' in the user namespace
969 # Put 'help' in the user namespace
970 try:
970 try:
971 from site import _Helper
971 from site import _Helper
972 self.user_ns['help'] = _Helper()
972 self.user_ns['help'] = _Helper()
973 except ImportError:
973 except ImportError:
974 warn('help() not available - check site.py')
974 warn('help() not available - check site.py')
975
975
976 def reset(self):
976 def reset(self):
977 """Clear all internal namespaces.
977 """Clear all internal namespaces.
978
978
979 Note that this is much more aggressive than %reset, since it clears
979 Note that this is much more aggressive than %reset, since it clears
980 fully all namespaces, as well as all input/output lists.
980 fully all namespaces, as well as all input/output lists.
981 """
981 """
982 for ns in self.ns_refs_table:
982 for ns in self.ns_refs_table:
983 ns.clear()
983 ns.clear()
984
984
985 self.alias_manager.clear_aliases()
985 self.alias_manager.clear_aliases()
986
986
987 # Clear input and output histories
987 # Clear input and output histories
988 self.input_hist[:] = []
988 self.input_hist[:] = []
989 self.input_hist_raw[:] = []
989 self.input_hist_raw[:] = []
990 self.output_hist.clear()
990 self.output_hist.clear()
991
991
992 # Restore the user namespaces to minimal usability
992 # Restore the user namespaces to minimal usability
993 self.init_user_ns()
993 self.init_user_ns()
994
994
995 # Restore the default and user aliases
995 # Restore the default and user aliases
996 self.alias_manager.init_aliases()
996 self.alias_manager.init_aliases()
997
997
998 def push(self, variables, interactive=True):
998 def push(self, variables, interactive=True):
999 """Inject a group of variables into the IPython user namespace.
999 """Inject a group of variables into the IPython user namespace.
1000
1000
1001 Parameters
1001 Parameters
1002 ----------
1002 ----------
1003 variables : dict, str or list/tuple of str
1003 variables : dict, str or list/tuple of str
1004 The variables to inject into the user's namespace. If a dict,
1004 The variables to inject into the user's namespace. If a dict,
1005 a simple update is done. If a str, the string is assumed to
1005 a simple update is done. If a str, the string is assumed to
1006 have variable names separated by spaces. A list/tuple of str
1006 have variable names separated by spaces. A list/tuple of str
1007 can also be used to give the variable names. If just the variable
1007 can also be used to give the variable names. If just the variable
1008 names are give (list/tuple/str) then the variable values looked
1008 names are give (list/tuple/str) then the variable values looked
1009 up in the callers frame.
1009 up in the callers frame.
1010 interactive : bool
1010 interactive : bool
1011 If True (default), the variables will be listed with the ``who``
1011 If True (default), the variables will be listed with the ``who``
1012 magic.
1012 magic.
1013 """
1013 """
1014 vdict = None
1014 vdict = None
1015
1015
1016 # We need a dict of name/value pairs to do namespace updates.
1016 # We need a dict of name/value pairs to do namespace updates.
1017 if isinstance(variables, dict):
1017 if isinstance(variables, dict):
1018 vdict = variables
1018 vdict = variables
1019 elif isinstance(variables, (basestring, list, tuple)):
1019 elif isinstance(variables, (basestring, list, tuple)):
1020 if isinstance(variables, basestring):
1020 if isinstance(variables, basestring):
1021 vlist = variables.split()
1021 vlist = variables.split()
1022 else:
1022 else:
1023 vlist = variables
1023 vlist = variables
1024 vdict = {}
1024 vdict = {}
1025 cf = sys._getframe(1)
1025 cf = sys._getframe(1)
1026 for name in vlist:
1026 for name in vlist:
1027 try:
1027 try:
1028 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1028 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1029 except:
1029 except:
1030 print ('Could not get variable %s from %s' %
1030 print ('Could not get variable %s from %s' %
1031 (name,cf.f_code.co_name))
1031 (name,cf.f_code.co_name))
1032 else:
1032 else:
1033 raise ValueError('variables must be a dict/str/list/tuple')
1033 raise ValueError('variables must be a dict/str/list/tuple')
1034
1034
1035 # Propagate variables to user namespace
1035 # Propagate variables to user namespace
1036 self.user_ns.update(vdict)
1036 self.user_ns.update(vdict)
1037
1037
1038 # And configure interactive visibility
1038 # And configure interactive visibility
1039 config_ns = self.user_config_ns
1039 config_ns = self.user_config_ns
1040 if interactive:
1040 if interactive:
1041 for name, val in vdict.iteritems():
1041 for name, val in vdict.iteritems():
1042 config_ns.pop(name, None)
1042 config_ns.pop(name, None)
1043 else:
1043 else:
1044 for name,val in vdict.iteritems():
1044 for name,val in vdict.iteritems():
1045 config_ns[name] = val
1045 config_ns[name] = val
1046
1046
1047 #-------------------------------------------------------------------------
1047 #-------------------------------------------------------------------------
1048 # Things related to history management
1048 # Things related to history management
1049 #-------------------------------------------------------------------------
1049 #-------------------------------------------------------------------------
1050
1050
1051 def init_history(self):
1051 def init_history(self):
1052 # List of input with multi-line handling.
1052 # List of input with multi-line handling.
1053 self.input_hist = InputList()
1053 self.input_hist = InputList()
1054 # This one will hold the 'raw' input history, without any
1054 # This one will hold the 'raw' input history, without any
1055 # pre-processing. This will allow users to retrieve the input just as
1055 # pre-processing. This will allow users to retrieve the input just as
1056 # it was exactly typed in by the user, with %hist -r.
1056 # it was exactly typed in by the user, with %hist -r.
1057 self.input_hist_raw = InputList()
1057 self.input_hist_raw = InputList()
1058
1058
1059 # list of visited directories
1059 # list of visited directories
1060 try:
1060 try:
1061 self.dir_hist = [os.getcwd()]
1061 self.dir_hist = [os.getcwd()]
1062 except OSError:
1062 except OSError:
1063 self.dir_hist = []
1063 self.dir_hist = []
1064
1064
1065 # dict of output history
1065 # dict of output history
1066 self.output_hist = {}
1066 self.output_hist = {}
1067
1067
1068 # Now the history file
1068 # Now the history file
1069 if self.profile:
1069 if self.profile:
1070 histfname = 'history-%s' % self.profile
1070 histfname = 'history-%s' % self.profile
1071 else:
1071 else:
1072 histfname = 'history'
1072 histfname = 'history'
1073 self.histfile = os.path.join(self.ipythondir, histfname)
1073 self.histfile = os.path.join(self.ipythondir, histfname)
1074
1074
1075 # Fill the history zero entry, user counter starts at 1
1075 # Fill the history zero entry, user counter starts at 1
1076 self.input_hist.append('\n')
1076 self.input_hist.append('\n')
1077 self.input_hist_raw.append('\n')
1077 self.input_hist_raw.append('\n')
1078
1078
1079 def init_shadow_hist(self):
1079 def init_shadow_hist(self):
1080 try:
1080 try:
1081 self.db = pickleshare.PickleShareDB(self.ipythondir + "/db")
1081 self.db = pickleshare.PickleShareDB(self.ipythondir + "/db")
1082 except exceptions.UnicodeDecodeError:
1082 except exceptions.UnicodeDecodeError:
1083 print "Your ipythondir can't be decoded to unicode!"
1083 print "Your ipythondir can't be decoded to unicode!"
1084 print "Please set HOME environment variable to something that"
1084 print "Please set HOME environment variable to something that"
1085 print r"only has ASCII characters, e.g. c:\home"
1085 print r"only has ASCII characters, e.g. c:\home"
1086 print "Now it is", self.ipythondir
1086 print "Now it is", self.ipythondir
1087 sys.exit()
1087 sys.exit()
1088 self.shadowhist = ipcorehist.ShadowHist(self.db)
1088 self.shadowhist = ipcorehist.ShadowHist(self.db)
1089
1089
1090 def savehist(self):
1090 def savehist(self):
1091 """Save input history to a file (via readline library)."""
1091 """Save input history to a file (via readline library)."""
1092
1092
1093 if not self.has_readline:
1093 if not self.has_readline:
1094 return
1094 return
1095
1095
1096 try:
1096 try:
1097 self.readline.write_history_file(self.histfile)
1097 self.readline.write_history_file(self.histfile)
1098 except:
1098 except:
1099 print 'Unable to save IPython command history to file: ' + \
1099 print 'Unable to save IPython command history to file: ' + \
1100 `self.histfile`
1100 `self.histfile`
1101
1101
1102 def reloadhist(self):
1102 def reloadhist(self):
1103 """Reload the input history from disk file."""
1103 """Reload the input history from disk file."""
1104
1104
1105 if self.has_readline:
1105 if self.has_readline:
1106 try:
1106 try:
1107 self.readline.clear_history()
1107 self.readline.clear_history()
1108 self.readline.read_history_file(self.shell.histfile)
1108 self.readline.read_history_file(self.shell.histfile)
1109 except AttributeError:
1109 except AttributeError:
1110 pass
1110 pass
1111
1111
1112 def history_saving_wrapper(self, func):
1112 def history_saving_wrapper(self, func):
1113 """ Wrap func for readline history saving
1113 """ Wrap func for readline history saving
1114
1114
1115 Convert func into callable that saves & restores
1115 Convert func into callable that saves & restores
1116 history around the call """
1116 history around the call """
1117
1117
1118 if not self.has_readline:
1118 if not self.has_readline:
1119 return func
1119 return func
1120
1120
1121 def wrapper():
1121 def wrapper():
1122 self.savehist()
1122 self.savehist()
1123 try:
1123 try:
1124 func()
1124 func()
1125 finally:
1125 finally:
1126 readline.read_history_file(self.histfile)
1126 readline.read_history_file(self.histfile)
1127 return wrapper
1127 return wrapper
1128
1128
1129 #-------------------------------------------------------------------------
1129 #-------------------------------------------------------------------------
1130 # Things related to exception handling and tracebacks (not debugging)
1130 # Things related to exception handling and tracebacks (not debugging)
1131 #-------------------------------------------------------------------------
1131 #-------------------------------------------------------------------------
1132
1132
1133 def init_traceback_handlers(self, custom_exceptions):
1133 def init_traceback_handlers(self, custom_exceptions):
1134 # Syntax error handler.
1134 # Syntax error handler.
1135 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
1135 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
1136
1136
1137 # The interactive one is initialized with an offset, meaning we always
1137 # The interactive one is initialized with an offset, meaning we always
1138 # want to remove the topmost item in the traceback, which is our own
1138 # want to remove the topmost item in the traceback, which is our own
1139 # internal code. Valid modes: ['Plain','Context','Verbose']
1139 # internal code. Valid modes: ['Plain','Context','Verbose']
1140 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1140 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1141 color_scheme='NoColor',
1141 color_scheme='NoColor',
1142 tb_offset = 1)
1142 tb_offset = 1)
1143
1143
1144 # IPython itself shouldn't crash. This will produce a detailed
1144 # IPython itself shouldn't crash. This will produce a detailed
1145 # post-mortem if it does. But we only install the crash handler for
1145 # post-mortem if it does. But we only install the crash handler for
1146 # non-threaded shells, the threaded ones use a normal verbose reporter
1146 # non-threaded shells, the threaded ones use a normal verbose reporter
1147 # and lose the crash handler. This is because exceptions in the main
1147 # and lose the crash handler. This is because exceptions in the main
1148 # thread (such as in GUI code) propagate directly to sys.excepthook,
1148 # thread (such as in GUI code) propagate directly to sys.excepthook,
1149 # and there's no point in printing crash dumps for every user exception.
1149 # and there's no point in printing crash dumps for every user exception.
1150 if self.isthreaded:
1150 if self.isthreaded:
1151 ipCrashHandler = ultratb.FormattedTB()
1151 ipCrashHandler = ultratb.FormattedTB()
1152 else:
1152 else:
1153 from IPython.core import crashhandler
1153 from IPython.core import crashhandler
1154 ipCrashHandler = crashhandler.IPythonCrashHandler(self)
1154 ipCrashHandler = crashhandler.IPythonCrashHandler(self)
1155 self.set_crash_handler(ipCrashHandler)
1155 self.set_crash_handler(ipCrashHandler)
1156
1156
1157 # and add any custom exception handlers the user may have specified
1157 # and add any custom exception handlers the user may have specified
1158 self.set_custom_exc(*custom_exceptions)
1158 self.set_custom_exc(*custom_exceptions)
1159
1159
1160 def set_crash_handler(self, crashHandler):
1160 def set_crash_handler(self, crashHandler):
1161 """Set the IPython crash handler.
1161 """Set the IPython crash handler.
1162
1162
1163 This must be a callable with a signature suitable for use as
1163 This must be a callable with a signature suitable for use as
1164 sys.excepthook."""
1164 sys.excepthook."""
1165
1165
1166 # Install the given crash handler as the Python exception hook
1166 # Install the given crash handler as the Python exception hook
1167 sys.excepthook = crashHandler
1167 sys.excepthook = crashHandler
1168
1168
1169 # The instance will store a pointer to this, so that runtime code
1169 # The instance will store a pointer to this, so that runtime code
1170 # (such as magics) can access it. This is because during the
1170 # (such as magics) can access it. This is because during the
1171 # read-eval loop, it gets temporarily overwritten (to deal with GUI
1171 # read-eval loop, it gets temporarily overwritten (to deal with GUI
1172 # frameworks).
1172 # frameworks).
1173 self.sys_excepthook = sys.excepthook
1173 self.sys_excepthook = sys.excepthook
1174
1174
1175 def set_custom_exc(self,exc_tuple,handler):
1175 def set_custom_exc(self,exc_tuple,handler):
1176 """set_custom_exc(exc_tuple,handler)
1176 """set_custom_exc(exc_tuple,handler)
1177
1177
1178 Set a custom exception handler, which will be called if any of the
1178 Set a custom exception handler, which will be called if any of the
1179 exceptions in exc_tuple occur in the mainloop (specifically, in the
1179 exceptions in exc_tuple occur in the mainloop (specifically, in the
1180 runcode() method.
1180 runcode() method.
1181
1181
1182 Inputs:
1182 Inputs:
1183
1183
1184 - exc_tuple: a *tuple* of valid exceptions to call the defined
1184 - exc_tuple: a *tuple* of valid exceptions to call the defined
1185 handler for. It is very important that you use a tuple, and NOT A
1185 handler for. It is very important that you use a tuple, and NOT A
1186 LIST here, because of the way Python's except statement works. If
1186 LIST here, because of the way Python's except statement works. If
1187 you only want to trap a single exception, use a singleton tuple:
1187 you only want to trap a single exception, use a singleton tuple:
1188
1188
1189 exc_tuple == (MyCustomException,)
1189 exc_tuple == (MyCustomException,)
1190
1190
1191 - handler: this must be defined as a function with the following
1191 - handler: this must be defined as a function with the following
1192 basic interface: def my_handler(self,etype,value,tb).
1192 basic interface: def my_handler(self,etype,value,tb).
1193
1193
1194 This will be made into an instance method (via new.instancemethod)
1194 This will be made into an instance method (via new.instancemethod)
1195 of IPython itself, and it will be called if any of the exceptions
1195 of IPython itself, and it will be called if any of the exceptions
1196 listed in the exc_tuple are caught. If the handler is None, an
1196 listed in the exc_tuple are caught. If the handler is None, an
1197 internal basic one is used, which just prints basic info.
1197 internal basic one is used, which just prints basic info.
1198
1198
1199 WARNING: by putting in your own exception handler into IPython's main
1199 WARNING: by putting in your own exception handler into IPython's main
1200 execution loop, you run a very good chance of nasty crashes. This
1200 execution loop, you run a very good chance of nasty crashes. This
1201 facility should only be used if you really know what you are doing."""
1201 facility should only be used if you really know what you are doing."""
1202
1202
1203 assert type(exc_tuple)==type(()) , \
1203 assert type(exc_tuple)==type(()) , \
1204 "The custom exceptions must be given AS A TUPLE."
1204 "The custom exceptions must be given AS A TUPLE."
1205
1205
1206 def dummy_handler(self,etype,value,tb):
1206 def dummy_handler(self,etype,value,tb):
1207 print '*** Simple custom exception handler ***'
1207 print '*** Simple custom exception handler ***'
1208 print 'Exception type :',etype
1208 print 'Exception type :',etype
1209 print 'Exception value:',value
1209 print 'Exception value:',value
1210 print 'Traceback :',tb
1210 print 'Traceback :',tb
1211 print 'Source code :','\n'.join(self.buffer)
1211 print 'Source code :','\n'.join(self.buffer)
1212
1212
1213 if handler is None: handler = dummy_handler
1213 if handler is None: handler = dummy_handler
1214
1214
1215 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1215 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1216 self.custom_exceptions = exc_tuple
1216 self.custom_exceptions = exc_tuple
1217
1217
1218 def excepthook(self, etype, value, tb):
1218 def excepthook(self, etype, value, tb):
1219 """One more defense for GUI apps that call sys.excepthook.
1219 """One more defense for GUI apps that call sys.excepthook.
1220
1220
1221 GUI frameworks like wxPython trap exceptions and call
1221 GUI frameworks like wxPython trap exceptions and call
1222 sys.excepthook themselves. I guess this is a feature that
1222 sys.excepthook themselves. I guess this is a feature that
1223 enables them to keep running after exceptions that would
1223 enables them to keep running after exceptions that would
1224 otherwise kill their mainloop. This is a bother for IPython
1224 otherwise kill their mainloop. This is a bother for IPython
1225 which excepts to catch all of the program exceptions with a try:
1225 which excepts to catch all of the program exceptions with a try:
1226 except: statement.
1226 except: statement.
1227
1227
1228 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1228 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1229 any app directly invokes sys.excepthook, it will look to the user like
1229 any app directly invokes sys.excepthook, it will look to the user like
1230 IPython crashed. In order to work around this, we can disable the
1230 IPython crashed. In order to work around this, we can disable the
1231 CrashHandler and replace it with this excepthook instead, which prints a
1231 CrashHandler and replace it with this excepthook instead, which prints a
1232 regular traceback using our InteractiveTB. In this fashion, apps which
1232 regular traceback using our InteractiveTB. In this fashion, apps which
1233 call sys.excepthook will generate a regular-looking exception from
1233 call sys.excepthook will generate a regular-looking exception from
1234 IPython, and the CrashHandler will only be triggered by real IPython
1234 IPython, and the CrashHandler will only be triggered by real IPython
1235 crashes.
1235 crashes.
1236
1236
1237 This hook should be used sparingly, only in places which are not likely
1237 This hook should be used sparingly, only in places which are not likely
1238 to be true IPython errors.
1238 to be true IPython errors.
1239 """
1239 """
1240 self.showtraceback((etype,value,tb),tb_offset=0)
1240 self.showtraceback((etype,value,tb),tb_offset=0)
1241
1241
1242 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1242 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1243 """Display the exception that just occurred.
1243 """Display the exception that just occurred.
1244
1244
1245 If nothing is known about the exception, this is the method which
1245 If nothing is known about the exception, this is the method which
1246 should be used throughout the code for presenting user tracebacks,
1246 should be used throughout the code for presenting user tracebacks,
1247 rather than directly invoking the InteractiveTB object.
1247 rather than directly invoking the InteractiveTB object.
1248
1248
1249 A specific showsyntaxerror() also exists, but this method can take
1249 A specific showsyntaxerror() also exists, but this method can take
1250 care of calling it if needed, so unless you are explicitly catching a
1250 care of calling it if needed, so unless you are explicitly catching a
1251 SyntaxError exception, don't try to analyze the stack manually and
1251 SyntaxError exception, don't try to analyze the stack manually and
1252 simply call this method."""
1252 simply call this method."""
1253
1253
1254
1254
1255 # Though this won't be called by syntax errors in the input line,
1255 # Though this won't be called by syntax errors in the input line,
1256 # there may be SyntaxError cases whith imported code.
1256 # there may be SyntaxError cases whith imported code.
1257
1257
1258 try:
1258 try:
1259 if exc_tuple is None:
1259 if exc_tuple is None:
1260 etype, value, tb = sys.exc_info()
1260 etype, value, tb = sys.exc_info()
1261 else:
1261 else:
1262 etype, value, tb = exc_tuple
1262 etype, value, tb = exc_tuple
1263
1263
1264 if etype is SyntaxError:
1264 if etype is SyntaxError:
1265 self.showsyntaxerror(filename)
1265 self.showsyntaxerror(filename)
1266 elif etype is UsageError:
1266 elif etype is UsageError:
1267 print "UsageError:", value
1267 print "UsageError:", value
1268 else:
1268 else:
1269 # WARNING: these variables are somewhat deprecated and not
1269 # WARNING: these variables are somewhat deprecated and not
1270 # necessarily safe to use in a threaded environment, but tools
1270 # necessarily safe to use in a threaded environment, but tools
1271 # like pdb depend on their existence, so let's set them. If we
1271 # like pdb depend on their existence, so let's set them. If we
1272 # find problems in the field, we'll need to revisit their use.
1272 # find problems in the field, we'll need to revisit their use.
1273 sys.last_type = etype
1273 sys.last_type = etype
1274 sys.last_value = value
1274 sys.last_value = value
1275 sys.last_traceback = tb
1275 sys.last_traceback = tb
1276
1276
1277 if etype in self.custom_exceptions:
1277 if etype in self.custom_exceptions:
1278 self.CustomTB(etype,value,tb)
1278 self.CustomTB(etype,value,tb)
1279 else:
1279 else:
1280 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1280 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1281 if self.InteractiveTB.call_pdb and self.has_readline:
1281 if self.InteractiveTB.call_pdb and self.has_readline:
1282 # pdb mucks up readline, fix it back
1282 # pdb mucks up readline, fix it back
1283 self.set_completer()
1283 self.set_completer()
1284 except KeyboardInterrupt:
1284 except KeyboardInterrupt:
1285 self.write("\nKeyboardInterrupt\n")
1285 self.write("\nKeyboardInterrupt\n")
1286
1286
1287 def showsyntaxerror(self, filename=None):
1287 def showsyntaxerror(self, filename=None):
1288 """Display the syntax error that just occurred.
1288 """Display the syntax error that just occurred.
1289
1289
1290 This doesn't display a stack trace because there isn't one.
1290 This doesn't display a stack trace because there isn't one.
1291
1291
1292 If a filename is given, it is stuffed in the exception instead
1292 If a filename is given, it is stuffed in the exception instead
1293 of what was there before (because Python's parser always uses
1293 of what was there before (because Python's parser always uses
1294 "<string>" when reading from a string).
1294 "<string>" when reading from a string).
1295 """
1295 """
1296 etype, value, last_traceback = sys.exc_info()
1296 etype, value, last_traceback = sys.exc_info()
1297
1297
1298 # See note about these variables in showtraceback() below
1298 # See note about these variables in showtraceback() below
1299 sys.last_type = etype
1299 sys.last_type = etype
1300 sys.last_value = value
1300 sys.last_value = value
1301 sys.last_traceback = last_traceback
1301 sys.last_traceback = last_traceback
1302
1302
1303 if filename and etype is SyntaxError:
1303 if filename and etype is SyntaxError:
1304 # Work hard to stuff the correct filename in the exception
1304 # Work hard to stuff the correct filename in the exception
1305 try:
1305 try:
1306 msg, (dummy_filename, lineno, offset, line) = value
1306 msg, (dummy_filename, lineno, offset, line) = value
1307 except:
1307 except:
1308 # Not the format we expect; leave it alone
1308 # Not the format we expect; leave it alone
1309 pass
1309 pass
1310 else:
1310 else:
1311 # Stuff in the right filename
1311 # Stuff in the right filename
1312 try:
1312 try:
1313 # Assume SyntaxError is a class exception
1313 # Assume SyntaxError is a class exception
1314 value = SyntaxError(msg, (filename, lineno, offset, line))
1314 value = SyntaxError(msg, (filename, lineno, offset, line))
1315 except:
1315 except:
1316 # If that failed, assume SyntaxError is a string
1316 # If that failed, assume SyntaxError is a string
1317 value = msg, (filename, lineno, offset, line)
1317 value = msg, (filename, lineno, offset, line)
1318 self.SyntaxTB(etype,value,[])
1318 self.SyntaxTB(etype,value,[])
1319
1319
1320 def edit_syntax_error(self):
1320 def edit_syntax_error(self):
1321 """The bottom half of the syntax error handler called in the main loop.
1321 """The bottom half of the syntax error handler called in the main loop.
1322
1322
1323 Loop until syntax error is fixed or user cancels.
1323 Loop until syntax error is fixed or user cancels.
1324 """
1324 """
1325
1325
1326 while self.SyntaxTB.last_syntax_error:
1326 while self.SyntaxTB.last_syntax_error:
1327 # copy and clear last_syntax_error
1327 # copy and clear last_syntax_error
1328 err = self.SyntaxTB.clear_err_state()
1328 err = self.SyntaxTB.clear_err_state()
1329 if not self._should_recompile(err):
1329 if not self._should_recompile(err):
1330 return
1330 return
1331 try:
1331 try:
1332 # may set last_syntax_error again if a SyntaxError is raised
1332 # may set last_syntax_error again if a SyntaxError is raised
1333 self.safe_execfile(err.filename,self.user_ns)
1333 self.safe_execfile(err.filename,self.user_ns)
1334 except:
1334 except:
1335 self.showtraceback()
1335 self.showtraceback()
1336 else:
1336 else:
1337 try:
1337 try:
1338 f = file(err.filename)
1338 f = file(err.filename)
1339 try:
1339 try:
1340 # This should be inside a display_trap block and I
1340 # This should be inside a display_trap block and I
1341 # think it is.
1341 # think it is.
1342 sys.displayhook(f.read())
1342 sys.displayhook(f.read())
1343 finally:
1343 finally:
1344 f.close()
1344 f.close()
1345 except:
1345 except:
1346 self.showtraceback()
1346 self.showtraceback()
1347
1347
1348 def _should_recompile(self,e):
1348 def _should_recompile(self,e):
1349 """Utility routine for edit_syntax_error"""
1349 """Utility routine for edit_syntax_error"""
1350
1350
1351 if e.filename in ('<ipython console>','<input>','<string>',
1351 if e.filename in ('<ipython console>','<input>','<string>',
1352 '<console>','<BackgroundJob compilation>',
1352 '<console>','<BackgroundJob compilation>',
1353 None):
1353 None):
1354
1354
1355 return False
1355 return False
1356 try:
1356 try:
1357 if (self.autoedit_syntax and
1357 if (self.autoedit_syntax and
1358 not self.ask_yes_no('Return to editor to correct syntax error? '
1358 not self.ask_yes_no('Return to editor to correct syntax error? '
1359 '[Y/n] ','y')):
1359 '[Y/n] ','y')):
1360 return False
1360 return False
1361 except EOFError:
1361 except EOFError:
1362 return False
1362 return False
1363
1363
1364 def int0(x):
1364 def int0(x):
1365 try:
1365 try:
1366 return int(x)
1366 return int(x)
1367 except TypeError:
1367 except TypeError:
1368 return 0
1368 return 0
1369 # always pass integer line and offset values to editor hook
1369 # always pass integer line and offset values to editor hook
1370 try:
1370 try:
1371 self.hooks.fix_error_editor(e.filename,
1371 self.hooks.fix_error_editor(e.filename,
1372 int0(e.lineno),int0(e.offset),e.msg)
1372 int0(e.lineno),int0(e.offset),e.msg)
1373 except TryNext:
1373 except TryNext:
1374 warn('Could not open editor')
1374 warn('Could not open editor')
1375 return False
1375 return False
1376 return True
1376 return True
1377
1377
1378 #-------------------------------------------------------------------------
1378 #-------------------------------------------------------------------------
1379 # Things related to tab completion
1379 # Things related to tab completion
1380 #-------------------------------------------------------------------------
1380 #-------------------------------------------------------------------------
1381
1381
1382 def complete(self, text):
1382 def complete(self, text):
1383 """Return a sorted list of all possible completions on text.
1383 """Return a sorted list of all possible completions on text.
1384
1384
1385 Inputs:
1385 Inputs:
1386
1386
1387 - text: a string of text to be completed on.
1387 - text: a string of text to be completed on.
1388
1388
1389 This is a wrapper around the completion mechanism, similar to what
1389 This is a wrapper around the completion mechanism, similar to what
1390 readline does at the command line when the TAB key is hit. By
1390 readline does at the command line when the TAB key is hit. By
1391 exposing it as a method, it can be used by other non-readline
1391 exposing it as a method, it can be used by other non-readline
1392 environments (such as GUIs) for text completion.
1392 environments (such as GUIs) for text completion.
1393
1393
1394 Simple usage example:
1394 Simple usage example:
1395
1395
1396 In [7]: x = 'hello'
1396 In [7]: x = 'hello'
1397
1397
1398 In [8]: x
1398 In [8]: x
1399 Out[8]: 'hello'
1399 Out[8]: 'hello'
1400
1400
1401 In [9]: print x
1401 In [9]: print x
1402 hello
1402 hello
1403
1403
1404 In [10]: _ip.complete('x.l')
1404 In [10]: _ip.complete('x.l')
1405 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1405 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1406 """
1406 """
1407
1407
1408 # Inject names into __builtin__ so we can complete on the added names.
1408 # Inject names into __builtin__ so we can complete on the added names.
1409 with self.builtin_trap:
1409 with self.builtin_trap:
1410 complete = self.Completer.complete
1410 complete = self.Completer.complete
1411 state = 0
1411 state = 0
1412 # use a dict so we get unique keys, since ipyhton's multiple
1412 # use a dict so we get unique keys, since ipyhton's multiple
1413 # completers can return duplicates. When we make 2.4 a requirement,
1413 # completers can return duplicates. When we make 2.4 a requirement,
1414 # start using sets instead, which are faster.
1414 # start using sets instead, which are faster.
1415 comps = {}
1415 comps = {}
1416 while True:
1416 while True:
1417 newcomp = complete(text,state,line_buffer=text)
1417 newcomp = complete(text,state,line_buffer=text)
1418 if newcomp is None:
1418 if newcomp is None:
1419 break
1419 break
1420 comps[newcomp] = 1
1420 comps[newcomp] = 1
1421 state += 1
1421 state += 1
1422 outcomps = comps.keys()
1422 outcomps = comps.keys()
1423 outcomps.sort()
1423 outcomps.sort()
1424 #print "T:",text,"OC:",outcomps # dbg
1424 #print "T:",text,"OC:",outcomps # dbg
1425 #print "vars:",self.user_ns.keys()
1425 #print "vars:",self.user_ns.keys()
1426 return outcomps
1426 return outcomps
1427
1427
1428 def set_custom_completer(self,completer,pos=0):
1428 def set_custom_completer(self,completer,pos=0):
1429 """set_custom_completer(completer,pos=0)
1429 """set_custom_completer(completer,pos=0)
1430
1430
1431 Adds a new custom completer function.
1431 Adds a new custom completer function.
1432
1432
1433 The position argument (defaults to 0) is the index in the completers
1433 The position argument (defaults to 0) is the index in the completers
1434 list where you want the completer to be inserted."""
1434 list where you want the completer to be inserted."""
1435
1435
1436 newcomp = new.instancemethod(completer,self.Completer,
1436 newcomp = new.instancemethod(completer,self.Completer,
1437 self.Completer.__class__)
1437 self.Completer.__class__)
1438 self.Completer.matchers.insert(pos,newcomp)
1438 self.Completer.matchers.insert(pos,newcomp)
1439
1439
1440 def set_completer(self):
1440 def set_completer(self):
1441 """reset readline's completer to be our own."""
1441 """reset readline's completer to be our own."""
1442 self.readline.set_completer(self.Completer.complete)
1442 self.readline.set_completer(self.Completer.complete)
1443
1443
1444 #-------------------------------------------------------------------------
1444 #-------------------------------------------------------------------------
1445 # Things related to readline
1445 # Things related to readline
1446 #-------------------------------------------------------------------------
1446 #-------------------------------------------------------------------------
1447
1447
1448 def init_readline(self):
1448 def init_readline(self):
1449 """Command history completion/saving/reloading."""
1449 """Command history completion/saving/reloading."""
1450
1450
1451 self.rl_next_input = None
1451 self.rl_next_input = None
1452 self.rl_do_indent = False
1452 self.rl_do_indent = False
1453
1453
1454 if not self.readline_use:
1454 if not self.readline_use:
1455 return
1455 return
1456
1456
1457 import IPython.utils.rlineimpl as readline
1457 import IPython.utils.rlineimpl as readline
1458
1458
1459 if not readline.have_readline:
1459 if not readline.have_readline:
1460 self.has_readline = 0
1460 self.has_readline = 0
1461 self.readline = None
1461 self.readline = None
1462 # no point in bugging windows users with this every time:
1462 # no point in bugging windows users with this every time:
1463 warn('Readline services not available on this platform.')
1463 warn('Readline services not available on this platform.')
1464 else:
1464 else:
1465 sys.modules['readline'] = readline
1465 sys.modules['readline'] = readline
1466 import atexit
1466 import atexit
1467 from IPython.core.completer import IPCompleter
1467 from IPython.core.completer import IPCompleter
1468 self.Completer = IPCompleter(self,
1468 self.Completer = IPCompleter(self,
1469 self.user_ns,
1469 self.user_ns,
1470 self.user_global_ns,
1470 self.user_global_ns,
1471 self.readline_omit__names,
1471 self.readline_omit__names,
1472 self.alias_manager.alias_table)
1472 self.alias_manager.alias_table)
1473 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1473 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1474 self.strdispatchers['complete_command'] = sdisp
1474 self.strdispatchers['complete_command'] = sdisp
1475 self.Completer.custom_completers = sdisp
1475 self.Completer.custom_completers = sdisp
1476 # Platform-specific configuration
1476 # Platform-specific configuration
1477 if os.name == 'nt':
1477 if os.name == 'nt':
1478 self.readline_startup_hook = readline.set_pre_input_hook
1478 self.readline_startup_hook = readline.set_pre_input_hook
1479 else:
1479 else:
1480 self.readline_startup_hook = readline.set_startup_hook
1480 self.readline_startup_hook = readline.set_startup_hook
1481
1481
1482 # Load user's initrc file (readline config)
1482 # Load user's initrc file (readline config)
1483 # Or if libedit is used, load editrc.
1483 # Or if libedit is used, load editrc.
1484 inputrc_name = os.environ.get('INPUTRC')
1484 inputrc_name = os.environ.get('INPUTRC')
1485 if inputrc_name is None:
1485 if inputrc_name is None:
1486 home_dir = get_home_dir()
1486 home_dir = get_home_dir()
1487 if home_dir is not None:
1487 if home_dir is not None:
1488 inputrc_name = '.inputrc'
1488 inputrc_name = '.inputrc'
1489 if readline.uses_libedit:
1489 if readline.uses_libedit:
1490 inputrc_name = '.editrc'
1490 inputrc_name = '.editrc'
1491 inputrc_name = os.path.join(home_dir, inputrc_name)
1491 inputrc_name = os.path.join(home_dir, inputrc_name)
1492 if os.path.isfile(inputrc_name):
1492 if os.path.isfile(inputrc_name):
1493 try:
1493 try:
1494 readline.read_init_file(inputrc_name)
1494 readline.read_init_file(inputrc_name)
1495 except:
1495 except:
1496 warn('Problems reading readline initialization file <%s>'
1496 warn('Problems reading readline initialization file <%s>'
1497 % inputrc_name)
1497 % inputrc_name)
1498
1498
1499 self.has_readline = 1
1499 self.has_readline = 1
1500 self.readline = readline
1500 self.readline = readline
1501 # save this in sys so embedded copies can restore it properly
1501 # save this in sys so embedded copies can restore it properly
1502 sys.ipcompleter = self.Completer.complete
1502 sys.ipcompleter = self.Completer.complete
1503 self.set_completer()
1503 self.set_completer()
1504
1504
1505 # Configure readline according to user's prefs
1505 # Configure readline according to user's prefs
1506 # This is only done if GNU readline is being used. If libedit
1506 # This is only done if GNU readline is being used. If libedit
1507 # is being used (as on Leopard) the readline config is
1507 # is being used (as on Leopard) the readline config is
1508 # not run as the syntax for libedit is different.
1508 # not run as the syntax for libedit is different.
1509 if not readline.uses_libedit:
1509 if not readline.uses_libedit:
1510 for rlcommand in self.readline_parse_and_bind:
1510 for rlcommand in self.readline_parse_and_bind:
1511 #print "loading rl:",rlcommand # dbg
1511 #print "loading rl:",rlcommand # dbg
1512 readline.parse_and_bind(rlcommand)
1512 readline.parse_and_bind(rlcommand)
1513
1513
1514 # Remove some chars from the delimiters list. If we encounter
1514 # Remove some chars from the delimiters list. If we encounter
1515 # unicode chars, discard them.
1515 # unicode chars, discard them.
1516 delims = readline.get_completer_delims().encode("ascii", "ignore")
1516 delims = readline.get_completer_delims().encode("ascii", "ignore")
1517 delims = delims.translate(string._idmap,
1517 delims = delims.translate(string._idmap,
1518 self.readline_remove_delims)
1518 self.readline_remove_delims)
1519 readline.set_completer_delims(delims)
1519 readline.set_completer_delims(delims)
1520 # otherwise we end up with a monster history after a while:
1520 # otherwise we end up with a monster history after a while:
1521 readline.set_history_length(1000)
1521 readline.set_history_length(1000)
1522 try:
1522 try:
1523 #print '*** Reading readline history' # dbg
1523 #print '*** Reading readline history' # dbg
1524 readline.read_history_file(self.histfile)
1524 readline.read_history_file(self.histfile)
1525 except IOError:
1525 except IOError:
1526 pass # It doesn't exist yet.
1526 pass # It doesn't exist yet.
1527
1527
1528 atexit.register(self.atexit_operations)
1528 atexit.register(self.atexit_operations)
1529 del atexit
1529 del atexit
1530
1530
1531 # Configure auto-indent for all platforms
1531 # Configure auto-indent for all platforms
1532 self.set_autoindent(self.autoindent)
1532 self.set_autoindent(self.autoindent)
1533
1533
1534 def set_next_input(self, s):
1534 def set_next_input(self, s):
1535 """ Sets the 'default' input string for the next command line.
1535 """ Sets the 'default' input string for the next command line.
1536
1536
1537 Requires readline.
1537 Requires readline.
1538
1538
1539 Example:
1539 Example:
1540
1540
1541 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1541 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1542 [D:\ipython]|2> Hello Word_ # cursor is here
1542 [D:\ipython]|2> Hello Word_ # cursor is here
1543 """
1543 """
1544
1544
1545 self.rl_next_input = s
1545 self.rl_next_input = s
1546
1546
1547 def pre_readline(self):
1547 def pre_readline(self):
1548 """readline hook to be used at the start of each line.
1548 """readline hook to be used at the start of each line.
1549
1549
1550 Currently it handles auto-indent only."""
1550 Currently it handles auto-indent only."""
1551
1551
1552 #debugx('self.indent_current_nsp','pre_readline:')
1552 #debugx('self.indent_current_nsp','pre_readline:')
1553
1553
1554 if self.rl_do_indent:
1554 if self.rl_do_indent:
1555 self.readline.insert_text(self._indent_current_str())
1555 self.readline.insert_text(self._indent_current_str())
1556 if self.rl_next_input is not None:
1556 if self.rl_next_input is not None:
1557 self.readline.insert_text(self.rl_next_input)
1557 self.readline.insert_text(self.rl_next_input)
1558 self.rl_next_input = None
1558 self.rl_next_input = None
1559
1559
1560 def _indent_current_str(self):
1560 def _indent_current_str(self):
1561 """return the current level of indentation as a string"""
1561 """return the current level of indentation as a string"""
1562 return self.indent_current_nsp * ' '
1562 return self.indent_current_nsp * ' '
1563
1563
1564 #-------------------------------------------------------------------------
1564 #-------------------------------------------------------------------------
1565 # Things related to magics
1565 # Things related to magics
1566 #-------------------------------------------------------------------------
1566 #-------------------------------------------------------------------------
1567
1567
1568 def init_magics(self):
1568 def init_magics(self):
1569 # Set user colors (don't do it in the constructor above so that it
1569 # Set user colors (don't do it in the constructor above so that it
1570 # doesn't crash if colors option is invalid)
1570 # doesn't crash if colors option is invalid)
1571 self.magic_colors(self.colors)
1571 self.magic_colors(self.colors)
1572
1572
1573 def magic(self,arg_s):
1573 def magic(self,arg_s):
1574 """Call a magic function by name.
1574 """Call a magic function by name.
1575
1575
1576 Input: a string containing the name of the magic function to call and any
1576 Input: a string containing the name of the magic function to call and any
1577 additional arguments to be passed to the magic.
1577 additional arguments to be passed to the magic.
1578
1578
1579 magic('name -opt foo bar') is equivalent to typing at the ipython
1579 magic('name -opt foo bar') is equivalent to typing at the ipython
1580 prompt:
1580 prompt:
1581
1581
1582 In[1]: %name -opt foo bar
1582 In[1]: %name -opt foo bar
1583
1583
1584 To call a magic without arguments, simply use magic('name').
1584 To call a magic without arguments, simply use magic('name').
1585
1585
1586 This provides a proper Python function to call IPython's magics in any
1586 This provides a proper Python function to call IPython's magics in any
1587 valid Python code you can type at the interpreter, including loops and
1587 valid Python code you can type at the interpreter, including loops and
1588 compound statements.
1588 compound statements.
1589 """
1589 """
1590
1590
1591 args = arg_s.split(' ',1)
1591 args = arg_s.split(' ',1)
1592 magic_name = args[0]
1592 magic_name = args[0]
1593 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1593 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1594
1594
1595 try:
1595 try:
1596 magic_args = args[1]
1596 magic_args = args[1]
1597 except IndexError:
1597 except IndexError:
1598 magic_args = ''
1598 magic_args = ''
1599 fn = getattr(self,'magic_'+magic_name,None)
1599 fn = getattr(self,'magic_'+magic_name,None)
1600 if fn is None:
1600 if fn is None:
1601 error("Magic function `%s` not found." % magic_name)
1601 error("Magic function `%s` not found." % magic_name)
1602 else:
1602 else:
1603 magic_args = self.var_expand(magic_args,1)
1603 magic_args = self.var_expand(magic_args,1)
1604 with nested(self.builtin_trap,):
1604 with nested(self.builtin_trap,):
1605 result = fn(magic_args)
1605 result = fn(magic_args)
1606 # Unfortunately, the return statement is what will trigger
1606 return result
1607 # the displayhook, but it is no longer set!
1608 return result
1609
1607
1610 def define_magic(self, magicname, func):
1608 def define_magic(self, magicname, func):
1611 """Expose own function as magic function for ipython
1609 """Expose own function as magic function for ipython
1612
1610
1613 def foo_impl(self,parameter_s=''):
1611 def foo_impl(self,parameter_s=''):
1614 'My very own magic!. (Use docstrings, IPython reads them).'
1612 'My very own magic!. (Use docstrings, IPython reads them).'
1615 print 'Magic function. Passed parameter is between < >:'
1613 print 'Magic function. Passed parameter is between < >:'
1616 print '<%s>' % parameter_s
1614 print '<%s>' % parameter_s
1617 print 'The self object is:',self
1615 print 'The self object is:',self
1618
1616
1619 self.define_magic('foo',foo_impl)
1617 self.define_magic('foo',foo_impl)
1620 """
1618 """
1621
1619
1622 import new
1620 import new
1623 im = new.instancemethod(func,self, self.__class__)
1621 im = new.instancemethod(func,self, self.__class__)
1624 old = getattr(self, "magic_" + magicname, None)
1622 old = getattr(self, "magic_" + magicname, None)
1625 setattr(self, "magic_" + magicname, im)
1623 setattr(self, "magic_" + magicname, im)
1626 return old
1624 return old
1627
1625
1628 #-------------------------------------------------------------------------
1626 #-------------------------------------------------------------------------
1629 # Things related to macros
1627 # Things related to macros
1630 #-------------------------------------------------------------------------
1628 #-------------------------------------------------------------------------
1631
1629
1632 def define_macro(self, name, themacro):
1630 def define_macro(self, name, themacro):
1633 """Define a new macro
1631 """Define a new macro
1634
1632
1635 Parameters
1633 Parameters
1636 ----------
1634 ----------
1637 name : str
1635 name : str
1638 The name of the macro.
1636 The name of the macro.
1639 themacro : str or Macro
1637 themacro : str or Macro
1640 The action to do upon invoking the macro. If a string, a new
1638 The action to do upon invoking the macro. If a string, a new
1641 Macro object is created by passing the string to it.
1639 Macro object is created by passing the string to it.
1642 """
1640 """
1643
1641
1644 from IPython.core import macro
1642 from IPython.core import macro
1645
1643
1646 if isinstance(themacro, basestring):
1644 if isinstance(themacro, basestring):
1647 themacro = macro.Macro(themacro)
1645 themacro = macro.Macro(themacro)
1648 if not isinstance(themacro, macro.Macro):
1646 if not isinstance(themacro, macro.Macro):
1649 raise ValueError('A macro must be a string or a Macro instance.')
1647 raise ValueError('A macro must be a string or a Macro instance.')
1650 self.user_ns[name] = themacro
1648 self.user_ns[name] = themacro
1651
1649
1652 #-------------------------------------------------------------------------
1650 #-------------------------------------------------------------------------
1653 # Things related to the running of system commands
1651 # Things related to the running of system commands
1654 #-------------------------------------------------------------------------
1652 #-------------------------------------------------------------------------
1655
1653
1656 def system(self, cmd):
1654 def system(self, cmd):
1657 """Make a system call, using IPython."""
1655 """Make a system call, using IPython."""
1658 return self.hooks.shell_hook(self.var_expand(cmd, depth=2))
1656 return self.hooks.shell_hook(self.var_expand(cmd, depth=2))
1659
1657
1660 #-------------------------------------------------------------------------
1658 #-------------------------------------------------------------------------
1661 # Things related to aliases
1659 # Things related to aliases
1662 #-------------------------------------------------------------------------
1660 #-------------------------------------------------------------------------
1663
1661
1664 def init_alias(self):
1662 def init_alias(self):
1665 self.alias_manager = AliasManager(self, config=self.config)
1663 self.alias_manager = AliasManager(self, config=self.config)
1666 self.ns_table['alias'] = self.alias_manager.alias_table,
1664 self.ns_table['alias'] = self.alias_manager.alias_table,
1667
1665
1668 #-------------------------------------------------------------------------
1666 #-------------------------------------------------------------------------
1669 # Things related to the running of code
1667 # Things related to the running of code
1670 #-------------------------------------------------------------------------
1668 #-------------------------------------------------------------------------
1671
1669
1672 def ex(self, cmd):
1670 def ex(self, cmd):
1673 """Execute a normal python statement in user namespace."""
1671 """Execute a normal python statement in user namespace."""
1674 with nested(self.builtin_trap,):
1672 with nested(self.builtin_trap,):
1675 exec cmd in self.user_global_ns, self.user_ns
1673 exec cmd in self.user_global_ns, self.user_ns
1676
1674
1677 def ev(self, expr):
1675 def ev(self, expr):
1678 """Evaluate python expression expr in user namespace.
1676 """Evaluate python expression expr in user namespace.
1679
1677
1680 Returns the result of evaluation
1678 Returns the result of evaluation
1681 """
1679 """
1682 with nested(self.builtin_trap,):
1680 with nested(self.builtin_trap,):
1683 return eval(expr, self.user_global_ns, self.user_ns)
1681 return eval(expr, self.user_global_ns, self.user_ns)
1684
1682
1685 def mainloop(self, display_banner=None):
1683 def mainloop(self, display_banner=None):
1686 """Start the mainloop.
1684 """Start the mainloop.
1687
1685
1688 If an optional banner argument is given, it will override the
1686 If an optional banner argument is given, it will override the
1689 internally created default banner.
1687 internally created default banner.
1690 """
1688 """
1691
1689
1692 with nested(self.builtin_trap, self.display_trap):
1690 with nested(self.builtin_trap, self.display_trap):
1693
1691
1694 # if you run stuff with -c <cmd>, raw hist is not updated
1692 # if you run stuff with -c <cmd>, raw hist is not updated
1695 # ensure that it's in sync
1693 # ensure that it's in sync
1696 if len(self.input_hist) != len (self.input_hist_raw):
1694 if len(self.input_hist) != len (self.input_hist_raw):
1697 self.input_hist_raw = InputList(self.input_hist)
1695 self.input_hist_raw = InputList(self.input_hist)
1698
1696
1699 while 1:
1697 while 1:
1700 try:
1698 try:
1701 self.interact(display_banner=display_banner)
1699 self.interact(display_banner=display_banner)
1702 #self.interact_with_readline()
1700 #self.interact_with_readline()
1703 # XXX for testing of a readline-decoupled repl loop, call
1701 # XXX for testing of a readline-decoupled repl loop, call
1704 # interact_with_readline above
1702 # interact_with_readline above
1705 break
1703 break
1706 except KeyboardInterrupt:
1704 except KeyboardInterrupt:
1707 # this should not be necessary, but KeyboardInterrupt
1705 # this should not be necessary, but KeyboardInterrupt
1708 # handling seems rather unpredictable...
1706 # handling seems rather unpredictable...
1709 self.write("\nKeyboardInterrupt in interact()\n")
1707 self.write("\nKeyboardInterrupt in interact()\n")
1710
1708
1711 def interact_prompt(self):
1709 def interact_prompt(self):
1712 """ Print the prompt (in read-eval-print loop)
1710 """ Print the prompt (in read-eval-print loop)
1713
1711
1714 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1712 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1715 used in standard IPython flow.
1713 used in standard IPython flow.
1716 """
1714 """
1717 if self.more:
1715 if self.more:
1718 try:
1716 try:
1719 prompt = self.hooks.generate_prompt(True)
1717 prompt = self.hooks.generate_prompt(True)
1720 except:
1718 except:
1721 self.showtraceback()
1719 self.showtraceback()
1722 if self.autoindent:
1720 if self.autoindent:
1723 self.rl_do_indent = True
1721 self.rl_do_indent = True
1724
1722
1725 else:
1723 else:
1726 try:
1724 try:
1727 prompt = self.hooks.generate_prompt(False)
1725 prompt = self.hooks.generate_prompt(False)
1728 except:
1726 except:
1729 self.showtraceback()
1727 self.showtraceback()
1730 self.write(prompt)
1728 self.write(prompt)
1731
1729
1732 def interact_handle_input(self,line):
1730 def interact_handle_input(self,line):
1733 """ Handle the input line (in read-eval-print loop)
1731 """ Handle the input line (in read-eval-print loop)
1734
1732
1735 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1733 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1736 used in standard IPython flow.
1734 used in standard IPython flow.
1737 """
1735 """
1738 if line.lstrip() == line:
1736 if line.lstrip() == line:
1739 self.shadowhist.add(line.strip())
1737 self.shadowhist.add(line.strip())
1740 lineout = self.prefilter_manager.prefilter_lines(line,self.more)
1738 lineout = self.prefilter_manager.prefilter_lines(line,self.more)
1741
1739
1742 if line.strip():
1740 if line.strip():
1743 if self.more:
1741 if self.more:
1744 self.input_hist_raw[-1] += '%s\n' % line
1742 self.input_hist_raw[-1] += '%s\n' % line
1745 else:
1743 else:
1746 self.input_hist_raw.append('%s\n' % line)
1744 self.input_hist_raw.append('%s\n' % line)
1747
1745
1748
1746
1749 self.more = self.push_line(lineout)
1747 self.more = self.push_line(lineout)
1750 if (self.SyntaxTB.last_syntax_error and
1748 if (self.SyntaxTB.last_syntax_error and
1751 self.autoedit_syntax):
1749 self.autoedit_syntax):
1752 self.edit_syntax_error()
1750 self.edit_syntax_error()
1753
1751
1754 def interact_with_readline(self):
1752 def interact_with_readline(self):
1755 """ Demo of using interact_handle_input, interact_prompt
1753 """ Demo of using interact_handle_input, interact_prompt
1756
1754
1757 This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
1755 This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
1758 it should work like this.
1756 it should work like this.
1759 """
1757 """
1760 self.readline_startup_hook(self.pre_readline)
1758 self.readline_startup_hook(self.pre_readline)
1761 while not self.exit_now:
1759 while not self.exit_now:
1762 self.interact_prompt()
1760 self.interact_prompt()
1763 if self.more:
1761 if self.more:
1764 self.rl_do_indent = True
1762 self.rl_do_indent = True
1765 else:
1763 else:
1766 self.rl_do_indent = False
1764 self.rl_do_indent = False
1767 line = raw_input_original().decode(self.stdin_encoding)
1765 line = raw_input_original().decode(self.stdin_encoding)
1768 self.interact_handle_input(line)
1766 self.interact_handle_input(line)
1769
1767
1770 def interact(self, display_banner=None):
1768 def interact(self, display_banner=None):
1771 """Closely emulate the interactive Python console."""
1769 """Closely emulate the interactive Python console."""
1772
1770
1773 # batch run -> do not interact
1771 # batch run -> do not interact
1774 if self.exit_now:
1772 if self.exit_now:
1775 return
1773 return
1776
1774
1777 if display_banner is None:
1775 if display_banner is None:
1778 display_banner = self.display_banner
1776 display_banner = self.display_banner
1779 if display_banner:
1777 if display_banner:
1780 self.show_banner()
1778 self.show_banner()
1781
1779
1782 more = 0
1780 more = 0
1783
1781
1784 # Mark activity in the builtins
1782 # Mark activity in the builtins
1785 __builtin__.__dict__['__IPYTHON__active'] += 1
1783 __builtin__.__dict__['__IPYTHON__active'] += 1
1786
1784
1787 if self.has_readline:
1785 if self.has_readline:
1788 self.readline_startup_hook(self.pre_readline)
1786 self.readline_startup_hook(self.pre_readline)
1789 # exit_now is set by a call to %Exit or %Quit, through the
1787 # exit_now is set by a call to %Exit or %Quit, through the
1790 # ask_exit callback.
1788 # ask_exit callback.
1791
1789
1792 while not self.exit_now:
1790 while not self.exit_now:
1793 self.hooks.pre_prompt_hook()
1791 self.hooks.pre_prompt_hook()
1794 if more:
1792 if more:
1795 try:
1793 try:
1796 prompt = self.hooks.generate_prompt(True)
1794 prompt = self.hooks.generate_prompt(True)
1797 except:
1795 except:
1798 self.showtraceback()
1796 self.showtraceback()
1799 if self.autoindent:
1797 if self.autoindent:
1800 self.rl_do_indent = True
1798 self.rl_do_indent = True
1801
1799
1802 else:
1800 else:
1803 try:
1801 try:
1804 prompt = self.hooks.generate_prompt(False)
1802 prompt = self.hooks.generate_prompt(False)
1805 except:
1803 except:
1806 self.showtraceback()
1804 self.showtraceback()
1807 try:
1805 try:
1808 line = self.raw_input(prompt, more)
1806 line = self.raw_input(prompt, more)
1809 if self.exit_now:
1807 if self.exit_now:
1810 # quick exit on sys.std[in|out] close
1808 # quick exit on sys.std[in|out] close
1811 break
1809 break
1812 if self.autoindent:
1810 if self.autoindent:
1813 self.rl_do_indent = False
1811 self.rl_do_indent = False
1814
1812
1815 except KeyboardInterrupt:
1813 except KeyboardInterrupt:
1816 #double-guard against keyboardinterrupts during kbdint handling
1814 #double-guard against keyboardinterrupts during kbdint handling
1817 try:
1815 try:
1818 self.write('\nKeyboardInterrupt\n')
1816 self.write('\nKeyboardInterrupt\n')
1819 self.resetbuffer()
1817 self.resetbuffer()
1820 # keep cache in sync with the prompt counter:
1818 # keep cache in sync with the prompt counter:
1821 self.outputcache.prompt_count -= 1
1819 self.outputcache.prompt_count -= 1
1822
1820
1823 if self.autoindent:
1821 if self.autoindent:
1824 self.indent_current_nsp = 0
1822 self.indent_current_nsp = 0
1825 more = 0
1823 more = 0
1826 except KeyboardInterrupt:
1824 except KeyboardInterrupt:
1827 pass
1825 pass
1828 except EOFError:
1826 except EOFError:
1829 if self.autoindent:
1827 if self.autoindent:
1830 self.rl_do_indent = False
1828 self.rl_do_indent = False
1831 self.readline_startup_hook(None)
1829 self.readline_startup_hook(None)
1832 self.write('\n')
1830 self.write('\n')
1833 self.exit()
1831 self.exit()
1834 except bdb.BdbQuit:
1832 except bdb.BdbQuit:
1835 warn('The Python debugger has exited with a BdbQuit exception.\n'
1833 warn('The Python debugger has exited with a BdbQuit exception.\n'
1836 'Because of how pdb handles the stack, it is impossible\n'
1834 'Because of how pdb handles the stack, it is impossible\n'
1837 'for IPython to properly format this particular exception.\n'
1835 'for IPython to properly format this particular exception.\n'
1838 'IPython will resume normal operation.')
1836 'IPython will resume normal operation.')
1839 except:
1837 except:
1840 # exceptions here are VERY RARE, but they can be triggered
1838 # exceptions here are VERY RARE, but they can be triggered
1841 # asynchronously by signal handlers, for example.
1839 # asynchronously by signal handlers, for example.
1842 self.showtraceback()
1840 self.showtraceback()
1843 else:
1841 else:
1844 more = self.push_line(line)
1842 more = self.push_line(line)
1845 if (self.SyntaxTB.last_syntax_error and
1843 if (self.SyntaxTB.last_syntax_error and
1846 self.autoedit_syntax):
1844 self.autoedit_syntax):
1847 self.edit_syntax_error()
1845 self.edit_syntax_error()
1848
1846
1849 # We are off again...
1847 # We are off again...
1850 __builtin__.__dict__['__IPYTHON__active'] -= 1
1848 __builtin__.__dict__['__IPYTHON__active'] -= 1
1851
1849
1852 def safe_execfile(self, fname, *where, **kw):
1850 def safe_execfile(self, fname, *where, **kw):
1853 """A safe version of the builtin execfile().
1851 """A safe version of the builtin execfile().
1854
1852
1855 This version will never throw an exception, but instead print
1853 This version will never throw an exception, but instead print
1856 helpful error messages to the screen. This only works on pure
1854 helpful error messages to the screen. This only works on pure
1857 Python files with the .py extension.
1855 Python files with the .py extension.
1858
1856
1859 Parameters
1857 Parameters
1860 ----------
1858 ----------
1861 fname : string
1859 fname : string
1862 The name of the file to be executed.
1860 The name of the file to be executed.
1863 where : tuple
1861 where : tuple
1864 One or two namespaces, passed to execfile() as (globals,locals).
1862 One or two namespaces, passed to execfile() as (globals,locals).
1865 If only one is given, it is passed as both.
1863 If only one is given, it is passed as both.
1866 exit_ignore : bool (False)
1864 exit_ignore : bool (False)
1867 If True, then don't print errors for non-zero exit statuses.
1865 If True, then don't print errors for non-zero exit statuses.
1868 """
1866 """
1869 kw.setdefault('exit_ignore', False)
1867 kw.setdefault('exit_ignore', False)
1870
1868
1871 fname = os.path.abspath(os.path.expanduser(fname))
1869 fname = os.path.abspath(os.path.expanduser(fname))
1872
1870
1873 # Make sure we have a .py file
1871 # Make sure we have a .py file
1874 if not fname.endswith('.py'):
1872 if not fname.endswith('.py'):
1875 warn('File must end with .py to be run using execfile: <%s>' % fname)
1873 warn('File must end with .py to be run using execfile: <%s>' % fname)
1876
1874
1877 # Make sure we can open the file
1875 # Make sure we can open the file
1878 try:
1876 try:
1879 with open(fname) as thefile:
1877 with open(fname) as thefile:
1880 pass
1878 pass
1881 except:
1879 except:
1882 warn('Could not open file <%s> for safe execution.' % fname)
1880 warn('Could not open file <%s> for safe execution.' % fname)
1883 return
1881 return
1884
1882
1885 # Find things also in current directory. This is needed to mimic the
1883 # Find things also in current directory. This is needed to mimic the
1886 # behavior of running a script from the system command line, where
1884 # behavior of running a script from the system command line, where
1887 # Python inserts the script's directory into sys.path
1885 # Python inserts the script's directory into sys.path
1888 dname = os.path.dirname(fname)
1886 dname = os.path.dirname(fname)
1889
1887
1890 with prepended_to_syspath(dname):
1888 with prepended_to_syspath(dname):
1891 try:
1889 try:
1892 if sys.platform == 'win32' and sys.version_info < (2,5,1):
1890 if sys.platform == 'win32' and sys.version_info < (2,5,1):
1893 # Work around a bug in Python for Windows. The bug was
1891 # Work around a bug in Python for Windows. The bug was
1894 # fixed in in Python 2.5 r54159 and 54158, but that's still
1892 # fixed in in Python 2.5 r54159 and 54158, but that's still
1895 # SVN Python as of March/07. For details, see:
1893 # SVN Python as of March/07. For details, see:
1896 # http://projects.scipy.org/ipython/ipython/ticket/123
1894 # http://projects.scipy.org/ipython/ipython/ticket/123
1897 try:
1895 try:
1898 globs,locs = where[0:2]
1896 globs,locs = where[0:2]
1899 except:
1897 except:
1900 try:
1898 try:
1901 globs = locs = where[0]
1899 globs = locs = where[0]
1902 except:
1900 except:
1903 globs = locs = globals()
1901 globs = locs = globals()
1904 exec file(fname) in globs,locs
1902 exec file(fname) in globs,locs
1905 else:
1903 else:
1906 execfile(fname,*where)
1904 execfile(fname,*where)
1907 except SyntaxError:
1905 except SyntaxError:
1908 self.showsyntaxerror()
1906 self.showsyntaxerror()
1909 warn('Failure executing file: <%s>' % fname)
1907 warn('Failure executing file: <%s>' % fname)
1910 except SystemExit, status:
1908 except SystemExit, status:
1911 # Code that correctly sets the exit status flag to success (0)
1909 # Code that correctly sets the exit status flag to success (0)
1912 # shouldn't be bothered with a traceback. Note that a plain
1910 # shouldn't be bothered with a traceback. Note that a plain
1913 # sys.exit() does NOT set the message to 0 (it's empty) so that
1911 # sys.exit() does NOT set the message to 0 (it's empty) so that
1914 # will still get a traceback. Note that the structure of the
1912 # will still get a traceback. Note that the structure of the
1915 # SystemExit exception changed between Python 2.4 and 2.5, so
1913 # SystemExit exception changed between Python 2.4 and 2.5, so
1916 # the checks must be done in a version-dependent way.
1914 # the checks must be done in a version-dependent way.
1917 show = False
1915 show = False
1918 if status.message!=0 and not kw['exit_ignore']:
1916 if status.message!=0 and not kw['exit_ignore']:
1919 show = True
1917 show = True
1920 if show:
1918 if show:
1921 self.showtraceback()
1919 self.showtraceback()
1922 warn('Failure executing file: <%s>' % fname)
1920 warn('Failure executing file: <%s>' % fname)
1923 except:
1921 except:
1924 self.showtraceback()
1922 self.showtraceback()
1925 warn('Failure executing file: <%s>' % fname)
1923 warn('Failure executing file: <%s>' % fname)
1926
1924
1927 def safe_execfile_ipy(self, fname):
1925 def safe_execfile_ipy(self, fname):
1928 """Like safe_execfile, but for .ipy files with IPython syntax.
1926 """Like safe_execfile, but for .ipy files with IPython syntax.
1929
1927
1930 Parameters
1928 Parameters
1931 ----------
1929 ----------
1932 fname : str
1930 fname : str
1933 The name of the file to execute. The filename must have a
1931 The name of the file to execute. The filename must have a
1934 .ipy extension.
1932 .ipy extension.
1935 """
1933 """
1936 fname = os.path.abspath(os.path.expanduser(fname))
1934 fname = os.path.abspath(os.path.expanduser(fname))
1937
1935
1938 # Make sure we have a .py file
1936 # Make sure we have a .py file
1939 if not fname.endswith('.ipy'):
1937 if not fname.endswith('.ipy'):
1940 warn('File must end with .py to be run using execfile: <%s>' % fname)
1938 warn('File must end with .py to be run using execfile: <%s>' % fname)
1941
1939
1942 # Make sure we can open the file
1940 # Make sure we can open the file
1943 try:
1941 try:
1944 with open(fname) as thefile:
1942 with open(fname) as thefile:
1945 pass
1943 pass
1946 except:
1944 except:
1947 warn('Could not open file <%s> for safe execution.' % fname)
1945 warn('Could not open file <%s> for safe execution.' % fname)
1948 return
1946 return
1949
1947
1950 # Find things also in current directory. This is needed to mimic the
1948 # Find things also in current directory. This is needed to mimic the
1951 # behavior of running a script from the system command line, where
1949 # behavior of running a script from the system command line, where
1952 # Python inserts the script's directory into sys.path
1950 # Python inserts the script's directory into sys.path
1953 dname = os.path.dirname(fname)
1951 dname = os.path.dirname(fname)
1954
1952
1955 with prepended_to_syspath(dname):
1953 with prepended_to_syspath(dname):
1956 try:
1954 try:
1957 with open(fname) as thefile:
1955 with open(fname) as thefile:
1958 script = thefile.read()
1956 script = thefile.read()
1959 # self.runlines currently captures all exceptions
1957 # self.runlines currently captures all exceptions
1960 # raise in user code. It would be nice if there were
1958 # raise in user code. It would be nice if there were
1961 # versions of runlines, execfile that did raise, so
1959 # versions of runlines, execfile that did raise, so
1962 # we could catch the errors.
1960 # we could catch the errors.
1963 self.runlines(script, clean=True)
1961 self.runlines(script, clean=True)
1964 except:
1962 except:
1965 self.showtraceback()
1963 self.showtraceback()
1966 warn('Unknown failure executing file: <%s>' % fname)
1964 warn('Unknown failure executing file: <%s>' % fname)
1967
1965
1968 def _is_secondary_block_start(self, s):
1966 def _is_secondary_block_start(self, s):
1969 if not s.endswith(':'):
1967 if not s.endswith(':'):
1970 return False
1968 return False
1971 if (s.startswith('elif') or
1969 if (s.startswith('elif') or
1972 s.startswith('else') or
1970 s.startswith('else') or
1973 s.startswith('except') or
1971 s.startswith('except') or
1974 s.startswith('finally')):
1972 s.startswith('finally')):
1975 return True
1973 return True
1976
1974
1977 def cleanup_ipy_script(self, script):
1975 def cleanup_ipy_script(self, script):
1978 """Make a script safe for self.runlines()
1976 """Make a script safe for self.runlines()
1979
1977
1980 Currently, IPython is lines based, with blocks being detected by
1978 Currently, IPython is lines based, with blocks being detected by
1981 empty lines. This is a problem for block based scripts that may
1979 empty lines. This is a problem for block based scripts that may
1982 not have empty lines after blocks. This script adds those empty
1980 not have empty lines after blocks. This script adds those empty
1983 lines to make scripts safe for running in the current line based
1981 lines to make scripts safe for running in the current line based
1984 IPython.
1982 IPython.
1985 """
1983 """
1986 res = []
1984 res = []
1987 lines = script.splitlines()
1985 lines = script.splitlines()
1988 level = 0
1986 level = 0
1989
1987
1990 for l in lines:
1988 for l in lines:
1991 lstripped = l.lstrip()
1989 lstripped = l.lstrip()
1992 stripped = l.strip()
1990 stripped = l.strip()
1993 if not stripped:
1991 if not stripped:
1994 continue
1992 continue
1995 newlevel = len(l) - len(lstripped)
1993 newlevel = len(l) - len(lstripped)
1996 if level > 0 and newlevel == 0 and \
1994 if level > 0 and newlevel == 0 and \
1997 not self._is_secondary_block_start(stripped):
1995 not self._is_secondary_block_start(stripped):
1998 # add empty line
1996 # add empty line
1999 res.append('')
1997 res.append('')
2000 res.append(l)
1998 res.append(l)
2001 level = newlevel
1999 level = newlevel
2002
2000
2003 return '\n'.join(res) + '\n'
2001 return '\n'.join(res) + '\n'
2004
2002
2005 def runlines(self, lines, clean=False):
2003 def runlines(self, lines, clean=False):
2006 """Run a string of one or more lines of source.
2004 """Run a string of one or more lines of source.
2007
2005
2008 This method is capable of running a string containing multiple source
2006 This method is capable of running a string containing multiple source
2009 lines, as if they had been entered at the IPython prompt. Since it
2007 lines, as if they had been entered at the IPython prompt. Since it
2010 exposes IPython's processing machinery, the given strings can contain
2008 exposes IPython's processing machinery, the given strings can contain
2011 magic calls (%magic), special shell access (!cmd), etc.
2009 magic calls (%magic), special shell access (!cmd), etc.
2012 """
2010 """
2013
2011
2014 if isinstance(lines, (list, tuple)):
2012 if isinstance(lines, (list, tuple)):
2015 lines = '\n'.join(lines)
2013 lines = '\n'.join(lines)
2016
2014
2017 if clean:
2015 if clean:
2018 lines = self.cleanup_ipy_script(lines)
2016 lines = self.cleanup_ipy_script(lines)
2019
2017
2020 # We must start with a clean buffer, in case this is run from an
2018 # We must start with a clean buffer, in case this is run from an
2021 # interactive IPython session (via a magic, for example).
2019 # interactive IPython session (via a magic, for example).
2022 self.resetbuffer()
2020 self.resetbuffer()
2023 lines = lines.splitlines()
2021 lines = lines.splitlines()
2024 more = 0
2022 more = 0
2025
2023
2026 with nested(self.builtin_trap, self.display_trap):
2024 with nested(self.builtin_trap, self.display_trap):
2027 for line in lines:
2025 for line in lines:
2028 # skip blank lines so we don't mess up the prompt counter, but do
2026 # skip blank lines so we don't mess up the prompt counter, but do
2029 # NOT skip even a blank line if we are in a code block (more is
2027 # NOT skip even a blank line if we are in a code block (more is
2030 # true)
2028 # true)
2031
2029
2032 if line or more:
2030 if line or more:
2033 # push to raw history, so hist line numbers stay in sync
2031 # push to raw history, so hist line numbers stay in sync
2034 self.input_hist_raw.append("# " + line + "\n")
2032 self.input_hist_raw.append("# " + line + "\n")
2035 prefiltered = self.prefilter_manager.prefilter_lines(line,more)
2033 prefiltered = self.prefilter_manager.prefilter_lines(line,more)
2036 more = self.push_line(prefiltered)
2034 more = self.push_line(prefiltered)
2037 # IPython's runsource returns None if there was an error
2035 # IPython's runsource returns None if there was an error
2038 # compiling the code. This allows us to stop processing right
2036 # compiling the code. This allows us to stop processing right
2039 # away, so the user gets the error message at the right place.
2037 # away, so the user gets the error message at the right place.
2040 if more is None:
2038 if more is None:
2041 break
2039 break
2042 else:
2040 else:
2043 self.input_hist_raw.append("\n")
2041 self.input_hist_raw.append("\n")
2044 # final newline in case the input didn't have it, so that the code
2042 # final newline in case the input didn't have it, so that the code
2045 # actually does get executed
2043 # actually does get executed
2046 if more:
2044 if more:
2047 self.push_line('\n')
2045 self.push_line('\n')
2048
2046
2049 def runsource(self, source, filename='<input>', symbol='single'):
2047 def runsource(self, source, filename='<input>', symbol='single'):
2050 """Compile and run some source in the interpreter.
2048 """Compile and run some source in the interpreter.
2051
2049
2052 Arguments are as for compile_command().
2050 Arguments are as for compile_command().
2053
2051
2054 One several things can happen:
2052 One several things can happen:
2055
2053
2056 1) The input is incorrect; compile_command() raised an
2054 1) The input is incorrect; compile_command() raised an
2057 exception (SyntaxError or OverflowError). A syntax traceback
2055 exception (SyntaxError or OverflowError). A syntax traceback
2058 will be printed by calling the showsyntaxerror() method.
2056 will be printed by calling the showsyntaxerror() method.
2059
2057
2060 2) The input is incomplete, and more input is required;
2058 2) The input is incomplete, and more input is required;
2061 compile_command() returned None. Nothing happens.
2059 compile_command() returned None. Nothing happens.
2062
2060
2063 3) The input is complete; compile_command() returned a code
2061 3) The input is complete; compile_command() returned a code
2064 object. The code is executed by calling self.runcode() (which
2062 object. The code is executed by calling self.runcode() (which
2065 also handles run-time exceptions, except for SystemExit).
2063 also handles run-time exceptions, except for SystemExit).
2066
2064
2067 The return value is:
2065 The return value is:
2068
2066
2069 - True in case 2
2067 - True in case 2
2070
2068
2071 - False in the other cases, unless an exception is raised, where
2069 - False in the other cases, unless an exception is raised, where
2072 None is returned instead. This can be used by external callers to
2070 None is returned instead. This can be used by external callers to
2073 know whether to continue feeding input or not.
2071 know whether to continue feeding input or not.
2074
2072
2075 The return value can be used to decide whether to use sys.ps1 or
2073 The return value can be used to decide whether to use sys.ps1 or
2076 sys.ps2 to prompt the next line."""
2074 sys.ps2 to prompt the next line."""
2077
2075
2078 # if the source code has leading blanks, add 'if 1:\n' to it
2076 # if the source code has leading blanks, add 'if 1:\n' to it
2079 # this allows execution of indented pasted code. It is tempting
2077 # this allows execution of indented pasted code. It is tempting
2080 # to add '\n' at the end of source to run commands like ' a=1'
2078 # to add '\n' at the end of source to run commands like ' a=1'
2081 # directly, but this fails for more complicated scenarios
2079 # directly, but this fails for more complicated scenarios
2082 source=source.encode(self.stdin_encoding)
2080 source=source.encode(self.stdin_encoding)
2083 if source[:1] in [' ', '\t']:
2081 if source[:1] in [' ', '\t']:
2084 source = 'if 1:\n%s' % source
2082 source = 'if 1:\n%s' % source
2085
2083
2086 try:
2084 try:
2087 code = self.compile(source,filename,symbol)
2085 code = self.compile(source,filename,symbol)
2088 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2086 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2089 # Case 1
2087 # Case 1
2090 self.showsyntaxerror(filename)
2088 self.showsyntaxerror(filename)
2091 return None
2089 return None
2092
2090
2093 if code is None:
2091 if code is None:
2094 # Case 2
2092 # Case 2
2095 return True
2093 return True
2096
2094
2097 # Case 3
2095 # Case 3
2098 # We store the code object so that threaded shells and
2096 # We store the code object so that threaded shells and
2099 # custom exception handlers can access all this info if needed.
2097 # custom exception handlers can access all this info if needed.
2100 # The source corresponding to this can be obtained from the
2098 # The source corresponding to this can be obtained from the
2101 # buffer attribute as '\n'.join(self.buffer).
2099 # buffer attribute as '\n'.join(self.buffer).
2102 self.code_to_run = code
2100 self.code_to_run = code
2103 # now actually execute the code object
2101 # now actually execute the code object
2104 if self.runcode(code) == 0:
2102 if self.runcode(code) == 0:
2105 return False
2103 return False
2106 else:
2104 else:
2107 return None
2105 return None
2108
2106
2109 def runcode(self,code_obj):
2107 def runcode(self,code_obj):
2110 """Execute a code object.
2108 """Execute a code object.
2111
2109
2112 When an exception occurs, self.showtraceback() is called to display a
2110 When an exception occurs, self.showtraceback() is called to display a
2113 traceback.
2111 traceback.
2114
2112
2115 Return value: a flag indicating whether the code to be run completed
2113 Return value: a flag indicating whether the code to be run completed
2116 successfully:
2114 successfully:
2117
2115
2118 - 0: successful execution.
2116 - 0: successful execution.
2119 - 1: an error occurred.
2117 - 1: an error occurred.
2120 """
2118 """
2121
2119
2122 # Set our own excepthook in case the user code tries to call it
2120 # Set our own excepthook in case the user code tries to call it
2123 # directly, so that the IPython crash handler doesn't get triggered
2121 # directly, so that the IPython crash handler doesn't get triggered
2124 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2122 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2125
2123
2126 # we save the original sys.excepthook in the instance, in case config
2124 # we save the original sys.excepthook in the instance, in case config
2127 # code (such as magics) needs access to it.
2125 # code (such as magics) needs access to it.
2128 self.sys_excepthook = old_excepthook
2126 self.sys_excepthook = old_excepthook
2129 outflag = 1 # happens in more places, so it's easier as default
2127 outflag = 1 # happens in more places, so it's easier as default
2130 try:
2128 try:
2131 try:
2129 try:
2132 self.hooks.pre_runcode_hook()
2130 self.hooks.pre_runcode_hook()
2133 exec code_obj in self.user_global_ns, self.user_ns
2131 exec code_obj in self.user_global_ns, self.user_ns
2134 finally:
2132 finally:
2135 # Reset our crash handler in place
2133 # Reset our crash handler in place
2136 sys.excepthook = old_excepthook
2134 sys.excepthook = old_excepthook
2137 except SystemExit:
2135 except SystemExit:
2138 self.resetbuffer()
2136 self.resetbuffer()
2139 self.showtraceback()
2137 self.showtraceback()
2140 warn("Type %exit or %quit to exit IPython "
2138 warn("Type %exit or %quit to exit IPython "
2141 "(%Exit or %Quit do so unconditionally).",level=1)
2139 "(%Exit or %Quit do so unconditionally).",level=1)
2142 except self.custom_exceptions:
2140 except self.custom_exceptions:
2143 etype,value,tb = sys.exc_info()
2141 etype,value,tb = sys.exc_info()
2144 self.CustomTB(etype,value,tb)
2142 self.CustomTB(etype,value,tb)
2145 except:
2143 except:
2146 self.showtraceback()
2144 self.showtraceback()
2147 else:
2145 else:
2148 outflag = 0
2146 outflag = 0
2149 if softspace(sys.stdout, 0):
2147 if softspace(sys.stdout, 0):
2150 print
2148 print
2151 # Flush out code object which has been run (and source)
2149 # Flush out code object which has been run (and source)
2152 self.code_to_run = None
2150 self.code_to_run = None
2153 return outflag
2151 return outflag
2154
2152
2155 def push_line(self, line):
2153 def push_line(self, line):
2156 """Push a line to the interpreter.
2154 """Push a line to the interpreter.
2157
2155
2158 The line should not have a trailing newline; it may have
2156 The line should not have a trailing newline; it may have
2159 internal newlines. The line is appended to a buffer and the
2157 internal newlines. The line is appended to a buffer and the
2160 interpreter's runsource() method is called with the
2158 interpreter's runsource() method is called with the
2161 concatenated contents of the buffer as source. If this
2159 concatenated contents of the buffer as source. If this
2162 indicates that the command was executed or invalid, the buffer
2160 indicates that the command was executed or invalid, the buffer
2163 is reset; otherwise, the command is incomplete, and the buffer
2161 is reset; otherwise, the command is incomplete, and the buffer
2164 is left as it was after the line was appended. The return
2162 is left as it was after the line was appended. The return
2165 value is 1 if more input is required, 0 if the line was dealt
2163 value is 1 if more input is required, 0 if the line was dealt
2166 with in some way (this is the same as runsource()).
2164 with in some way (this is the same as runsource()).
2167 """
2165 """
2168
2166
2169 # autoindent management should be done here, and not in the
2167 # autoindent management should be done here, and not in the
2170 # interactive loop, since that one is only seen by keyboard input. We
2168 # interactive loop, since that one is only seen by keyboard input. We
2171 # need this done correctly even for code run via runlines (which uses
2169 # need this done correctly even for code run via runlines (which uses
2172 # push).
2170 # push).
2173
2171
2174 #print 'push line: <%s>' % line # dbg
2172 #print 'push line: <%s>' % line # dbg
2175 for subline in line.splitlines():
2173 for subline in line.splitlines():
2176 self._autoindent_update(subline)
2174 self._autoindent_update(subline)
2177 self.buffer.append(line)
2175 self.buffer.append(line)
2178 more = self.runsource('\n'.join(self.buffer), self.filename)
2176 more = self.runsource('\n'.join(self.buffer), self.filename)
2179 if not more:
2177 if not more:
2180 self.resetbuffer()
2178 self.resetbuffer()
2181 return more
2179 return more
2182
2180
2183 def _autoindent_update(self,line):
2181 def _autoindent_update(self,line):
2184 """Keep track of the indent level."""
2182 """Keep track of the indent level."""
2185
2183
2186 #debugx('line')
2184 #debugx('line')
2187 #debugx('self.indent_current_nsp')
2185 #debugx('self.indent_current_nsp')
2188 if self.autoindent:
2186 if self.autoindent:
2189 if line:
2187 if line:
2190 inisp = num_ini_spaces(line)
2188 inisp = num_ini_spaces(line)
2191 if inisp < self.indent_current_nsp:
2189 if inisp < self.indent_current_nsp:
2192 self.indent_current_nsp = inisp
2190 self.indent_current_nsp = inisp
2193
2191
2194 if line[-1] == ':':
2192 if line[-1] == ':':
2195 self.indent_current_nsp += 4
2193 self.indent_current_nsp += 4
2196 elif dedent_re.match(line):
2194 elif dedent_re.match(line):
2197 self.indent_current_nsp -= 4
2195 self.indent_current_nsp -= 4
2198 else:
2196 else:
2199 self.indent_current_nsp = 0
2197 self.indent_current_nsp = 0
2200
2198
2201 def resetbuffer(self):
2199 def resetbuffer(self):
2202 """Reset the input buffer."""
2200 """Reset the input buffer."""
2203 self.buffer[:] = []
2201 self.buffer[:] = []
2204
2202
2205 def raw_input(self,prompt='',continue_prompt=False):
2203 def raw_input(self,prompt='',continue_prompt=False):
2206 """Write a prompt and read a line.
2204 """Write a prompt and read a line.
2207
2205
2208 The returned line does not include the trailing newline.
2206 The returned line does not include the trailing newline.
2209 When the user enters the EOF key sequence, EOFError is raised.
2207 When the user enters the EOF key sequence, EOFError is raised.
2210
2208
2211 Optional inputs:
2209 Optional inputs:
2212
2210
2213 - prompt(''): a string to be printed to prompt the user.
2211 - prompt(''): a string to be printed to prompt the user.
2214
2212
2215 - continue_prompt(False): whether this line is the first one or a
2213 - continue_prompt(False): whether this line is the first one or a
2216 continuation in a sequence of inputs.
2214 continuation in a sequence of inputs.
2217 """
2215 """
2218 # growl.notify("raw_input: ", "prompt = %r\ncontinue_prompt = %s" % (prompt, continue_prompt))
2216 # growl.notify("raw_input: ", "prompt = %r\ncontinue_prompt = %s" % (prompt, continue_prompt))
2219
2217
2220 # Code run by the user may have modified the readline completer state.
2218 # Code run by the user may have modified the readline completer state.
2221 # We must ensure that our completer is back in place.
2219 # We must ensure that our completer is back in place.
2222
2220
2223 if self.has_readline:
2221 if self.has_readline:
2224 self.set_completer()
2222 self.set_completer()
2225
2223
2226 try:
2224 try:
2227 line = raw_input_original(prompt).decode(self.stdin_encoding)
2225 line = raw_input_original(prompt).decode(self.stdin_encoding)
2228 except ValueError:
2226 except ValueError:
2229 warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
2227 warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
2230 " or sys.stdout.close()!\nExiting IPython!")
2228 " or sys.stdout.close()!\nExiting IPython!")
2231 self.ask_exit()
2229 self.ask_exit()
2232 return ""
2230 return ""
2233
2231
2234 # Try to be reasonably smart about not re-indenting pasted input more
2232 # Try to be reasonably smart about not re-indenting pasted input more
2235 # than necessary. We do this by trimming out the auto-indent initial
2233 # than necessary. We do this by trimming out the auto-indent initial
2236 # spaces, if the user's actual input started itself with whitespace.
2234 # spaces, if the user's actual input started itself with whitespace.
2237 #debugx('self.buffer[-1]')
2235 #debugx('self.buffer[-1]')
2238
2236
2239 if self.autoindent:
2237 if self.autoindent:
2240 if num_ini_spaces(line) > self.indent_current_nsp:
2238 if num_ini_spaces(line) > self.indent_current_nsp:
2241 line = line[self.indent_current_nsp:]
2239 line = line[self.indent_current_nsp:]
2242 self.indent_current_nsp = 0
2240 self.indent_current_nsp = 0
2243
2241
2244 # store the unfiltered input before the user has any chance to modify
2242 # store the unfiltered input before the user has any chance to modify
2245 # it.
2243 # it.
2246 if line.strip():
2244 if line.strip():
2247 if continue_prompt:
2245 if continue_prompt:
2248 self.input_hist_raw[-1] += '%s\n' % line
2246 self.input_hist_raw[-1] += '%s\n' % line
2249 if self.has_readline and self.readline_use:
2247 if self.has_readline and self.readline_use:
2250 try:
2248 try:
2251 histlen = self.readline.get_current_history_length()
2249 histlen = self.readline.get_current_history_length()
2252 if histlen > 1:
2250 if histlen > 1:
2253 newhist = self.input_hist_raw[-1].rstrip()
2251 newhist = self.input_hist_raw[-1].rstrip()
2254 self.readline.remove_history_item(histlen-1)
2252 self.readline.remove_history_item(histlen-1)
2255 self.readline.replace_history_item(histlen-2,
2253 self.readline.replace_history_item(histlen-2,
2256 newhist.encode(self.stdin_encoding))
2254 newhist.encode(self.stdin_encoding))
2257 except AttributeError:
2255 except AttributeError:
2258 pass # re{move,place}_history_item are new in 2.4.
2256 pass # re{move,place}_history_item are new in 2.4.
2259 else:
2257 else:
2260 self.input_hist_raw.append('%s\n' % line)
2258 self.input_hist_raw.append('%s\n' % line)
2261 # only entries starting at first column go to shadow history
2259 # only entries starting at first column go to shadow history
2262 if line.lstrip() == line:
2260 if line.lstrip() == line:
2263 self.shadowhist.add(line.strip())
2261 self.shadowhist.add(line.strip())
2264 elif not continue_prompt:
2262 elif not continue_prompt:
2265 self.input_hist_raw.append('\n')
2263 self.input_hist_raw.append('\n')
2266 try:
2264 try:
2267 lineout = self.prefilter_manager.prefilter_lines(line,continue_prompt)
2265 lineout = self.prefilter_manager.prefilter_lines(line,continue_prompt)
2268 except:
2266 except:
2269 # blanket except, in case a user-defined prefilter crashes, so it
2267 # blanket except, in case a user-defined prefilter crashes, so it
2270 # can't take all of ipython with it.
2268 # can't take all of ipython with it.
2271 self.showtraceback()
2269 self.showtraceback()
2272 return ''
2270 return ''
2273 else:
2271 else:
2274 return lineout
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 # IPython extensions
2287 # IPython extensions
2278 #-------------------------------------------------------------------------
2288 #-------------------------------------------------------------------------
2279
2289
2280 def load_extension(self, module_str):
2290 def load_extension(self, module_str):
2281 """Load an IPython extension.
2291 """Load an IPython extension by its module name.
2282
2292
2283 An IPython extension is an importable Python module that has
2293 An IPython extension is an importable Python module that has
2284 a function with the signature::
2294 a function with the signature::
2285
2295
2286 def load_in_ipython(ipython):
2296 def load_ipython_extension(ipython):
2287 # Do things with ipython
2297 # Do things with ipython
2288
2298
2289 This function is called after your extension is imported and the
2299 This function is called after your extension is imported and the
2290 currently active :class:`InteractiveShell` instance is passed as
2300 currently active :class:`InteractiveShell` instance is passed as
2291 the only argument. You can do anything you want with IPython at
2301 the only argument. You can do anything you want with IPython at
2292 that point, including defining new magic and aliases, adding new
2302 that point, including defining new magic and aliases, adding new
2293 components, etc.
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 You can put your extension modules anywhere you want, as long as
2309 You can put your extension modules anywhere you want, as long as
2296 they can be imported by Python's standard import mechanism. However,
2310 they can be imported by Python's standard import mechanism. However,
2297 to make it easy to write extensions, you can also put your extensions
2311 to make it easy to write extensions, you can also put your extensions
2298 in ``os.path.join(self.ipythondir, 'extensions')``. This directory
2312 in ``os.path.join(self.ipythondir, 'extensions')``. This directory
2299 is added to ``sys.path`` automatically.
2313 is added to ``sys.path`` automatically.
2300 """
2314 """
2301 from IPython.utils.syspathcontext import prepended_to_syspath
2315 from IPython.utils.syspathcontext import prepended_to_syspath
2302
2316
2303 if module_str in sys.modules:
2317 if module_str not in sys.modules:
2304 return
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):
2323 def unload_extension(self, module_str):
2307 __import__(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 mod = sys.modules[module_str]
2330 mod = sys.modules[module_str]
2309 self._call_load_in_ipython(mod)
2331 self._call_unload_ipython_extension(mod)
2310
2332
2311 def reload_extension(self, module_str):
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 from IPython.utils.syspathcontext import prepended_to_syspath
2341 from IPython.utils.syspathcontext import prepended_to_syspath
2314
2342
2315 with prepended_to_syspath(self.ipython_extension_dir):
2343 with prepended_to_syspath(self.ipython_extension_dir):
2316 if module_str in sys.modules:
2344 if module_str in sys.modules:
2317 mod = sys.modules[module_str]
2345 mod = sys.modules[module_str]
2318 reload(mod)
2346 reload(mod)
2319 self._call_load_in_ipython(mod)
2347 self._call_load_ipython_extension(mod)
2320 else:
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):
2355 def _call_unload_ipython_extension(self, mod):
2324 if hasattr(mod, 'load_in_ipython'):
2356 if hasattr(mod, 'unload_ipython_extension'):
2325 mod.load_in_ipython(self)
2357 mod.unload_ipython_extension(self)
2326
2358
2327 #-------------------------------------------------------------------------
2359 #-------------------------------------------------------------------------
2328 # Things related to the prefilter
2360 # Things related to the prefilter
2329 #-------------------------------------------------------------------------
2361 #-------------------------------------------------------------------------
2330
2362
2331 def init_prefilter(self):
2363 def init_prefilter(self):
2332 self.prefilter_manager = PrefilterManager(self, config=self.config)
2364 self.prefilter_manager = PrefilterManager(self, config=self.config)
2333
2365
2334 #-------------------------------------------------------------------------
2366 #-------------------------------------------------------------------------
2335 # Utilities
2367 # Utilities
2336 #-------------------------------------------------------------------------
2368 #-------------------------------------------------------------------------
2337
2369
2338 def getoutput(self, cmd):
2370 def getoutput(self, cmd):
2339 return getoutput(self.var_expand(cmd,depth=2),
2371 return getoutput(self.var_expand(cmd,depth=2),
2340 header=self.system_header,
2372 header=self.system_header,
2341 verbose=self.system_verbose)
2373 verbose=self.system_verbose)
2342
2374
2343 def getoutputerror(self, cmd):
2375 def getoutputerror(self, cmd):
2344 return getoutputerror(self.var_expand(cmd,depth=2),
2376 return getoutputerror(self.var_expand(cmd,depth=2),
2345 header=self.system_header,
2377 header=self.system_header,
2346 verbose=self.system_verbose)
2378 verbose=self.system_verbose)
2347
2379
2348 def var_expand(self,cmd,depth=0):
2380 def var_expand(self,cmd,depth=0):
2349 """Expand python variables in a string.
2381 """Expand python variables in a string.
2350
2382
2351 The depth argument indicates how many frames above the caller should
2383 The depth argument indicates how many frames above the caller should
2352 be walked to look for the local namespace where to expand variables.
2384 be walked to look for the local namespace where to expand variables.
2353
2385
2354 The global namespace for expansion is always the user's interactive
2386 The global namespace for expansion is always the user's interactive
2355 namespace.
2387 namespace.
2356 """
2388 """
2357
2389
2358 return str(ItplNS(cmd,
2390 return str(ItplNS(cmd,
2359 self.user_ns, # globals
2391 self.user_ns, # globals
2360 # Skip our own frame in searching for locals:
2392 # Skip our own frame in searching for locals:
2361 sys._getframe(depth+1).f_locals # locals
2393 sys._getframe(depth+1).f_locals # locals
2362 ))
2394 ))
2363
2395
2364 def mktempfile(self,data=None):
2396 def mktempfile(self,data=None):
2365 """Make a new tempfile and return its filename.
2397 """Make a new tempfile and return its filename.
2366
2398
2367 This makes a call to tempfile.mktemp, but it registers the created
2399 This makes a call to tempfile.mktemp, but it registers the created
2368 filename internally so ipython cleans it up at exit time.
2400 filename internally so ipython cleans it up at exit time.
2369
2401
2370 Optional inputs:
2402 Optional inputs:
2371
2403
2372 - data(None): if data is given, it gets written out to the temp file
2404 - data(None): if data is given, it gets written out to the temp file
2373 immediately, and the file is closed again."""
2405 immediately, and the file is closed again."""
2374
2406
2375 filename = tempfile.mktemp('.py','ipython_edit_')
2407 filename = tempfile.mktemp('.py','ipython_edit_')
2376 self.tempfiles.append(filename)
2408 self.tempfiles.append(filename)
2377
2409
2378 if data:
2410 if data:
2379 tmp_file = open(filename,'w')
2411 tmp_file = open(filename,'w')
2380 tmp_file.write(data)
2412 tmp_file.write(data)
2381 tmp_file.close()
2413 tmp_file.close()
2382 return filename
2414 return filename
2383
2415
2384 def write(self,data):
2416 def write(self,data):
2385 """Write a string to the default output"""
2417 """Write a string to the default output"""
2386 Term.cout.write(data)
2418 Term.cout.write(data)
2387
2419
2388 def write_err(self,data):
2420 def write_err(self,data):
2389 """Write a string to the default error output"""
2421 """Write a string to the default error output"""
2390 Term.cerr.write(data)
2422 Term.cerr.write(data)
2391
2423
2392 def ask_yes_no(self,prompt,default=True):
2424 def ask_yes_no(self,prompt,default=True):
2393 if self.quiet:
2425 if self.quiet:
2394 return True
2426 return True
2395 return ask_yes_no(prompt,default)
2427 return ask_yes_no(prompt,default)
2396
2428
2397 #-------------------------------------------------------------------------
2429 #-------------------------------------------------------------------------
2398 # Things related to IPython exiting
2430 # Things related to IPython exiting
2399 #-------------------------------------------------------------------------
2431 #-------------------------------------------------------------------------
2400
2432
2401 def ask_exit(self):
2433 def ask_exit(self):
2402 """ Call for exiting. Can be overiden and used as a callback. """
2434 """ Call for exiting. Can be overiden and used as a callback. """
2403 self.exit_now = True
2435 self.exit_now = True
2404
2436
2405 def exit(self):
2437 def exit(self):
2406 """Handle interactive exit.
2438 """Handle interactive exit.
2407
2439
2408 This method calls the ask_exit callback."""
2440 This method calls the ask_exit callback."""
2409 if self.confirm_exit:
2441 if self.confirm_exit:
2410 if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2442 if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2411 self.ask_exit()
2443 self.ask_exit()
2412 else:
2444 else:
2413 self.ask_exit()
2445 self.ask_exit()
2414
2446
2415 def atexit_operations(self):
2447 def atexit_operations(self):
2416 """This will be executed at the time of exit.
2448 """This will be executed at the time of exit.
2417
2449
2418 Saving of persistent data should be performed here.
2450 Saving of persistent data should be performed here.
2419 """
2451 """
2420 self.savehist()
2452 self.savehist()
2421
2453
2422 # Cleanup all tempfiles left around
2454 # Cleanup all tempfiles left around
2423 for tfile in self.tempfiles:
2455 for tfile in self.tempfiles:
2424 try:
2456 try:
2425 os.unlink(tfile)
2457 os.unlink(tfile)
2426 except OSError:
2458 except OSError:
2427 pass
2459 pass
2428
2460
2429 # Clear all user namespaces to release all references cleanly.
2461 # Clear all user namespaces to release all references cleanly.
2430 self.reset()
2462 self.reset()
2431
2463
2432 # Run user hooks
2464 # Run user hooks
2433 self.hooks.shutdown_hook()
2465 self.hooks.shutdown_hook()
2434
2466
2435 def cleanup(self):
2467 def cleanup(self):
2436 self.restore_sys_module_state()
2468 self.restore_sys_module_state()
2437
2469
2438
2470
@@ -1,3542 +1,3553 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Magic functions for InteractiveShell.
2 """Magic functions for InteractiveShell.
3 """
3 """
4
4
5 #*****************************************************************************
5 #*****************************************************************************
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #*****************************************************************************
11 #*****************************************************************************
12
12
13 #****************************************************************************
13 #****************************************************************************
14 # Modules and globals
14 # Modules and globals
15
15
16 # Python standard modules
16 # Python standard modules
17 import __builtin__
17 import __builtin__
18 import bdb
18 import bdb
19 import inspect
19 import inspect
20 import os
20 import os
21 import pdb
21 import pdb
22 import pydoc
22 import pydoc
23 import sys
23 import sys
24 import re
24 import re
25 import tempfile
25 import tempfile
26 import time
26 import time
27 import cPickle as pickle
27 import cPickle as pickle
28 import textwrap
28 import textwrap
29 from cStringIO import StringIO
29 from cStringIO import StringIO
30 from getopt import getopt,GetoptError
30 from getopt import getopt,GetoptError
31 from pprint import pprint, pformat
31 from pprint import pprint, pformat
32
32
33 # cProfile was added in Python2.5
33 # cProfile was added in Python2.5
34 try:
34 try:
35 import cProfile as profile
35 import cProfile as profile
36 import pstats
36 import pstats
37 except ImportError:
37 except ImportError:
38 # profile isn't bundled by default in Debian for license reasons
38 # profile isn't bundled by default in Debian for license reasons
39 try:
39 try:
40 import profile,pstats
40 import profile,pstats
41 except ImportError:
41 except ImportError:
42 profile = pstats = None
42 profile = pstats = None
43
43
44 # Homebrewed
44 # Homebrewed
45 import IPython
45 import IPython
46 from IPython.utils import wildcard
46 from IPython.utils import wildcard
47 from IPython.core import debugger, oinspect
47 from IPython.core import debugger, oinspect
48 from IPython.core.error import TryNext
48 from IPython.core.error import TryNext
49 from IPython.core.fakemodule import FakeModule
49 from IPython.core.fakemodule import FakeModule
50 from IPython.core.prefilter import ESC_MAGIC
50 from IPython.core.prefilter import ESC_MAGIC
51 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
51 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
52 from IPython.utils.PyColorize import Parser
52 from IPython.utils.PyColorize import Parser
53 from IPython.utils.ipstruct import Struct
53 from IPython.utils.ipstruct import Struct
54 from IPython.core.macro import Macro
54 from IPython.core.macro import Macro
55 from IPython.utils.genutils import *
55 from IPython.utils.genutils import *
56 from IPython.core.page import page
56 from IPython.core.page import page
57 from IPython.utils import platutils
57 from IPython.utils import platutils
58 import IPython.utils.generics
58 import IPython.utils.generics
59 from IPython.core.error import UsageError
59 from IPython.core.error import UsageError
60 from IPython.testing import decorators as testdec
60 from IPython.testing import decorators as testdec
61
61
62 #***************************************************************************
62 #***************************************************************************
63 # Utility functions
63 # Utility functions
64 def on_off(tag):
64 def on_off(tag):
65 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
65 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
66 return ['OFF','ON'][tag]
66 return ['OFF','ON'][tag]
67
67
68 class Bunch: pass
68 class Bunch: pass
69
69
70 def compress_dhist(dh):
70 def compress_dhist(dh):
71 head, tail = dh[:-10], dh[-10:]
71 head, tail = dh[:-10], dh[-10:]
72
72
73 newhead = []
73 newhead = []
74 done = set()
74 done = set()
75 for h in head:
75 for h in head:
76 if h in done:
76 if h in done:
77 continue
77 continue
78 newhead.append(h)
78 newhead.append(h)
79 done.add(h)
79 done.add(h)
80
80
81 return newhead + tail
81 return newhead + tail
82
82
83
83
84 #***************************************************************************
84 #***************************************************************************
85 # Main class implementing Magic functionality
85 # Main class implementing Magic functionality
86 class Magic:
86 class Magic:
87 """Magic functions for InteractiveShell.
87 """Magic functions for InteractiveShell.
88
88
89 Shell functions which can be reached as %function_name. All magic
89 Shell functions which can be reached as %function_name. All magic
90 functions should accept a string, which they can parse for their own
90 functions should accept a string, which they can parse for their own
91 needs. This can make some functions easier to type, eg `%cd ../`
91 needs. This can make some functions easier to type, eg `%cd ../`
92 vs. `%cd("../")`
92 vs. `%cd("../")`
93
93
94 ALL definitions MUST begin with the prefix magic_. The user won't need it
94 ALL definitions MUST begin with the prefix magic_. The user won't need it
95 at the command line, but it is is needed in the definition. """
95 at the command line, but it is is needed in the definition. """
96
96
97 # class globals
97 # class globals
98 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
98 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
99 'Automagic is ON, % prefix NOT needed for magic functions.']
99 'Automagic is ON, % prefix NOT needed for magic functions.']
100
100
101 #......................................................................
101 #......................................................................
102 # some utility functions
102 # some utility functions
103
103
104 def __init__(self,shell):
104 def __init__(self,shell):
105
105
106 self.options_table = {}
106 self.options_table = {}
107 if profile is None:
107 if profile is None:
108 self.magic_prun = self.profile_missing_notice
108 self.magic_prun = self.profile_missing_notice
109 self.shell = shell
109 self.shell = shell
110
110
111 # namespace for holding state we may need
111 # namespace for holding state we may need
112 self._magic_state = Bunch()
112 self._magic_state = Bunch()
113
113
114 def profile_missing_notice(self, *args, **kwargs):
114 def profile_missing_notice(self, *args, **kwargs):
115 error("""\
115 error("""\
116 The profile module could not be found. It has been removed from the standard
116 The profile module could not be found. It has been removed from the standard
117 python packages because of its non-free license. To use profiling, install the
117 python packages because of its non-free license. To use profiling, install the
118 python-profiler package from non-free.""")
118 python-profiler package from non-free.""")
119
119
120 def default_option(self,fn,optstr):
120 def default_option(self,fn,optstr):
121 """Make an entry in the options_table for fn, with value optstr"""
121 """Make an entry in the options_table for fn, with value optstr"""
122
122
123 if fn not in self.lsmagic():
123 if fn not in self.lsmagic():
124 error("%s is not a magic function" % fn)
124 error("%s is not a magic function" % fn)
125 self.options_table[fn] = optstr
125 self.options_table[fn] = optstr
126
126
127 def lsmagic(self):
127 def lsmagic(self):
128 """Return a list of currently available magic functions.
128 """Return a list of currently available magic functions.
129
129
130 Gives a list of the bare names after mangling (['ls','cd', ...], not
130 Gives a list of the bare names after mangling (['ls','cd', ...], not
131 ['magic_ls','magic_cd',...]"""
131 ['magic_ls','magic_cd',...]"""
132
132
133 # FIXME. This needs a cleanup, in the way the magics list is built.
133 # FIXME. This needs a cleanup, in the way the magics list is built.
134
134
135 # magics in class definition
135 # magics in class definition
136 class_magic = lambda fn: fn.startswith('magic_') and \
136 class_magic = lambda fn: fn.startswith('magic_') and \
137 callable(Magic.__dict__[fn])
137 callable(Magic.__dict__[fn])
138 # in instance namespace (run-time user additions)
138 # in instance namespace (run-time user additions)
139 inst_magic = lambda fn: fn.startswith('magic_') and \
139 inst_magic = lambda fn: fn.startswith('magic_') and \
140 callable(self.__dict__[fn])
140 callable(self.__dict__[fn])
141 # and bound magics by user (so they can access self):
141 # and bound magics by user (so they can access self):
142 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
142 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
143 callable(self.__class__.__dict__[fn])
143 callable(self.__class__.__dict__[fn])
144 magics = filter(class_magic,Magic.__dict__.keys()) + \
144 magics = filter(class_magic,Magic.__dict__.keys()) + \
145 filter(inst_magic,self.__dict__.keys()) + \
145 filter(inst_magic,self.__dict__.keys()) + \
146 filter(inst_bound_magic,self.__class__.__dict__.keys())
146 filter(inst_bound_magic,self.__class__.__dict__.keys())
147 out = []
147 out = []
148 for fn in set(magics):
148 for fn in set(magics):
149 out.append(fn.replace('magic_','',1))
149 out.append(fn.replace('magic_','',1))
150 out.sort()
150 out.sort()
151 return out
151 return out
152
152
153 def extract_input_slices(self,slices,raw=False):
153 def extract_input_slices(self,slices,raw=False):
154 """Return as a string a set of input history slices.
154 """Return as a string a set of input history slices.
155
155
156 Inputs:
156 Inputs:
157
157
158 - slices: the set of slices is given as a list of strings (like
158 - slices: the set of slices is given as a list of strings (like
159 ['1','4:8','9'], since this function is for use by magic functions
159 ['1','4:8','9'], since this function is for use by magic functions
160 which get their arguments as strings.
160 which get their arguments as strings.
161
161
162 Optional inputs:
162 Optional inputs:
163
163
164 - raw(False): by default, the processed input is used. If this is
164 - raw(False): by default, the processed input is used. If this is
165 true, the raw input history is used instead.
165 true, the raw input history is used instead.
166
166
167 Note that slices can be called with two notations:
167 Note that slices can be called with two notations:
168
168
169 N:M -> standard python form, means including items N...(M-1).
169 N:M -> standard python form, means including items N...(M-1).
170
170
171 N-M -> include items N..M (closed endpoint)."""
171 N-M -> include items N..M (closed endpoint)."""
172
172
173 if raw:
173 if raw:
174 hist = self.shell.input_hist_raw
174 hist = self.shell.input_hist_raw
175 else:
175 else:
176 hist = self.shell.input_hist
176 hist = self.shell.input_hist
177
177
178 cmds = []
178 cmds = []
179 for chunk in slices:
179 for chunk in slices:
180 if ':' in chunk:
180 if ':' in chunk:
181 ini,fin = map(int,chunk.split(':'))
181 ini,fin = map(int,chunk.split(':'))
182 elif '-' in chunk:
182 elif '-' in chunk:
183 ini,fin = map(int,chunk.split('-'))
183 ini,fin = map(int,chunk.split('-'))
184 fin += 1
184 fin += 1
185 else:
185 else:
186 ini = int(chunk)
186 ini = int(chunk)
187 fin = ini+1
187 fin = ini+1
188 cmds.append(hist[ini:fin])
188 cmds.append(hist[ini:fin])
189 return cmds
189 return cmds
190
190
191 def _ofind(self, oname, namespaces=None):
191 def _ofind(self, oname, namespaces=None):
192 """Find an object in the available namespaces.
192 """Find an object in the available namespaces.
193
193
194 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
194 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
195
195
196 Has special code to detect magic functions.
196 Has special code to detect magic functions.
197 """
197 """
198
198
199 oname = oname.strip()
199 oname = oname.strip()
200
200
201 alias_ns = None
201 alias_ns = None
202 if namespaces is None:
202 if namespaces is None:
203 # Namespaces to search in:
203 # Namespaces to search in:
204 # Put them in a list. The order is important so that we
204 # Put them in a list. The order is important so that we
205 # find things in the same order that Python finds them.
205 # find things in the same order that Python finds them.
206 namespaces = [ ('Interactive', self.shell.user_ns),
206 namespaces = [ ('Interactive', self.shell.user_ns),
207 ('IPython internal', self.shell.internal_ns),
207 ('IPython internal', self.shell.internal_ns),
208 ('Python builtin', __builtin__.__dict__),
208 ('Python builtin', __builtin__.__dict__),
209 ('Alias', self.shell.alias_manager.alias_table),
209 ('Alias', self.shell.alias_manager.alias_table),
210 ]
210 ]
211 alias_ns = self.shell.alias_manager.alias_table
211 alias_ns = self.shell.alias_manager.alias_table
212
212
213 # initialize results to 'null'
213 # initialize results to 'null'
214 found = 0; obj = None; ospace = None; ds = None;
214 found = 0; obj = None; ospace = None; ds = None;
215 ismagic = 0; isalias = 0; parent = None
215 ismagic = 0; isalias = 0; parent = None
216
216
217 # Look for the given name by splitting it in parts. If the head is
217 # Look for the given name by splitting it in parts. If the head is
218 # found, then we look for all the remaining parts as members, and only
218 # found, then we look for all the remaining parts as members, and only
219 # declare success if we can find them all.
219 # declare success if we can find them all.
220 oname_parts = oname.split('.')
220 oname_parts = oname.split('.')
221 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
221 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
222 for nsname,ns in namespaces:
222 for nsname,ns in namespaces:
223 try:
223 try:
224 obj = ns[oname_head]
224 obj = ns[oname_head]
225 except KeyError:
225 except KeyError:
226 continue
226 continue
227 else:
227 else:
228 #print 'oname_rest:', oname_rest # dbg
228 #print 'oname_rest:', oname_rest # dbg
229 for part in oname_rest:
229 for part in oname_rest:
230 try:
230 try:
231 parent = obj
231 parent = obj
232 obj = getattr(obj,part)
232 obj = getattr(obj,part)
233 except:
233 except:
234 # Blanket except b/c some badly implemented objects
234 # Blanket except b/c some badly implemented objects
235 # allow __getattr__ to raise exceptions other than
235 # allow __getattr__ to raise exceptions other than
236 # AttributeError, which then crashes IPython.
236 # AttributeError, which then crashes IPython.
237 break
237 break
238 else:
238 else:
239 # If we finish the for loop (no break), we got all members
239 # If we finish the for loop (no break), we got all members
240 found = 1
240 found = 1
241 ospace = nsname
241 ospace = nsname
242 if ns == alias_ns:
242 if ns == alias_ns:
243 isalias = 1
243 isalias = 1
244 break # namespace loop
244 break # namespace loop
245
245
246 # Try to see if it's magic
246 # Try to see if it's magic
247 if not found:
247 if not found:
248 if oname.startswith(ESC_MAGIC):
248 if oname.startswith(ESC_MAGIC):
249 oname = oname[1:]
249 oname = oname[1:]
250 obj = getattr(self,'magic_'+oname,None)
250 obj = getattr(self,'magic_'+oname,None)
251 if obj is not None:
251 if obj is not None:
252 found = 1
252 found = 1
253 ospace = 'IPython internal'
253 ospace = 'IPython internal'
254 ismagic = 1
254 ismagic = 1
255
255
256 # Last try: special-case some literals like '', [], {}, etc:
256 # Last try: special-case some literals like '', [], {}, etc:
257 if not found and oname_head in ["''",'""','[]','{}','()']:
257 if not found and oname_head in ["''",'""','[]','{}','()']:
258 obj = eval(oname_head)
258 obj = eval(oname_head)
259 found = 1
259 found = 1
260 ospace = 'Interactive'
260 ospace = 'Interactive'
261
261
262 return {'found':found, 'obj':obj, 'namespace':ospace,
262 return {'found':found, 'obj':obj, 'namespace':ospace,
263 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
263 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
264
264
265 def arg_err(self,func):
265 def arg_err(self,func):
266 """Print docstring if incorrect arguments were passed"""
266 """Print docstring if incorrect arguments were passed"""
267 print 'Error in arguments:'
267 print 'Error in arguments:'
268 print OInspect.getdoc(func)
268 print OInspect.getdoc(func)
269
269
270 def format_latex(self,strng):
270 def format_latex(self,strng):
271 """Format a string for latex inclusion."""
271 """Format a string for latex inclusion."""
272
272
273 # Characters that need to be escaped for latex:
273 # Characters that need to be escaped for latex:
274 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
274 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
275 # Magic command names as headers:
275 # Magic command names as headers:
276 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
276 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
277 re.MULTILINE)
277 re.MULTILINE)
278 # Magic commands
278 # Magic commands
279 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
279 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
280 re.MULTILINE)
280 re.MULTILINE)
281 # Paragraph continue
281 # Paragraph continue
282 par_re = re.compile(r'\\$',re.MULTILINE)
282 par_re = re.compile(r'\\$',re.MULTILINE)
283
283
284 # The "\n" symbol
284 # The "\n" symbol
285 newline_re = re.compile(r'\\n')
285 newline_re = re.compile(r'\\n')
286
286
287 # Now build the string for output:
287 # Now build the string for output:
288 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
288 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
289 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
289 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
290 strng)
290 strng)
291 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
291 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
292 strng = par_re.sub(r'\\\\',strng)
292 strng = par_re.sub(r'\\\\',strng)
293 strng = escape_re.sub(r'\\\1',strng)
293 strng = escape_re.sub(r'\\\1',strng)
294 strng = newline_re.sub(r'\\textbackslash{}n',strng)
294 strng = newline_re.sub(r'\\textbackslash{}n',strng)
295 return strng
295 return strng
296
296
297 def format_screen(self,strng):
297 def format_screen(self,strng):
298 """Format a string for screen printing.
298 """Format a string for screen printing.
299
299
300 This removes some latex-type format codes."""
300 This removes some latex-type format codes."""
301 # Paragraph continue
301 # Paragraph continue
302 par_re = re.compile(r'\\$',re.MULTILINE)
302 par_re = re.compile(r'\\$',re.MULTILINE)
303 strng = par_re.sub('',strng)
303 strng = par_re.sub('',strng)
304 return strng
304 return strng
305
305
306 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
306 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
307 """Parse options passed to an argument string.
307 """Parse options passed to an argument string.
308
308
309 The interface is similar to that of getopt(), but it returns back a
309 The interface is similar to that of getopt(), but it returns back a
310 Struct with the options as keys and the stripped argument string still
310 Struct with the options as keys and the stripped argument string still
311 as a string.
311 as a string.
312
312
313 arg_str is quoted as a true sys.argv vector by using shlex.split.
313 arg_str is quoted as a true sys.argv vector by using shlex.split.
314 This allows us to easily expand variables, glob files, quote
314 This allows us to easily expand variables, glob files, quote
315 arguments, etc.
315 arguments, etc.
316
316
317 Options:
317 Options:
318 -mode: default 'string'. If given as 'list', the argument string is
318 -mode: default 'string'. If given as 'list', the argument string is
319 returned as a list (split on whitespace) instead of a string.
319 returned as a list (split on whitespace) instead of a string.
320
320
321 -list_all: put all option values in lists. Normally only options
321 -list_all: put all option values in lists. Normally only options
322 appearing more than once are put in a list.
322 appearing more than once are put in a list.
323
323
324 -posix (True): whether to split the input line in POSIX mode or not,
324 -posix (True): whether to split the input line in POSIX mode or not,
325 as per the conventions outlined in the shlex module from the
325 as per the conventions outlined in the shlex module from the
326 standard library."""
326 standard library."""
327
327
328 # inject default options at the beginning of the input line
328 # inject default options at the beginning of the input line
329 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
329 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
330 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
330 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
331
331
332 mode = kw.get('mode','string')
332 mode = kw.get('mode','string')
333 if mode not in ['string','list']:
333 if mode not in ['string','list']:
334 raise ValueError,'incorrect mode given: %s' % mode
334 raise ValueError,'incorrect mode given: %s' % mode
335 # Get options
335 # Get options
336 list_all = kw.get('list_all',0)
336 list_all = kw.get('list_all',0)
337 posix = kw.get('posix',True)
337 posix = kw.get('posix',True)
338
338
339 # Check if we have more than one argument to warrant extra processing:
339 # Check if we have more than one argument to warrant extra processing:
340 odict = {} # Dictionary with options
340 odict = {} # Dictionary with options
341 args = arg_str.split()
341 args = arg_str.split()
342 if len(args) >= 1:
342 if len(args) >= 1:
343 # If the list of inputs only has 0 or 1 thing in it, there's no
343 # If the list of inputs only has 0 or 1 thing in it, there's no
344 # need to look for options
344 # need to look for options
345 argv = arg_split(arg_str,posix)
345 argv = arg_split(arg_str,posix)
346 # Do regular option processing
346 # Do regular option processing
347 try:
347 try:
348 opts,args = getopt(argv,opt_str,*long_opts)
348 opts,args = getopt(argv,opt_str,*long_opts)
349 except GetoptError,e:
349 except GetoptError,e:
350 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
350 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
351 " ".join(long_opts)))
351 " ".join(long_opts)))
352 for o,a in opts:
352 for o,a in opts:
353 if o.startswith('--'):
353 if o.startswith('--'):
354 o = o[2:]
354 o = o[2:]
355 else:
355 else:
356 o = o[1:]
356 o = o[1:]
357 try:
357 try:
358 odict[o].append(a)
358 odict[o].append(a)
359 except AttributeError:
359 except AttributeError:
360 odict[o] = [odict[o],a]
360 odict[o] = [odict[o],a]
361 except KeyError:
361 except KeyError:
362 if list_all:
362 if list_all:
363 odict[o] = [a]
363 odict[o] = [a]
364 else:
364 else:
365 odict[o] = a
365 odict[o] = a
366
366
367 # Prepare opts,args for return
367 # Prepare opts,args for return
368 opts = Struct(odict)
368 opts = Struct(odict)
369 if mode == 'string':
369 if mode == 'string':
370 args = ' '.join(args)
370 args = ' '.join(args)
371
371
372 return opts,args
372 return opts,args
373
373
374 #......................................................................
374 #......................................................................
375 # And now the actual magic functions
375 # And now the actual magic functions
376
376
377 # Functions for IPython shell work (vars,funcs, config, etc)
377 # Functions for IPython shell work (vars,funcs, config, etc)
378 def magic_lsmagic(self, parameter_s = ''):
378 def magic_lsmagic(self, parameter_s = ''):
379 """List currently available magic functions."""
379 """List currently available magic functions."""
380 mesc = ESC_MAGIC
380 mesc = ESC_MAGIC
381 print 'Available magic functions:\n'+mesc+\
381 print 'Available magic functions:\n'+mesc+\
382 (' '+mesc).join(self.lsmagic())
382 (' '+mesc).join(self.lsmagic())
383 print '\n' + Magic.auto_status[self.shell.automagic]
383 print '\n' + Magic.auto_status[self.shell.automagic]
384 return None
384 return None
385
385
386 def magic_magic(self, parameter_s = ''):
386 def magic_magic(self, parameter_s = ''):
387 """Print information about the magic function system.
387 """Print information about the magic function system.
388
388
389 Supported formats: -latex, -brief, -rest
389 Supported formats: -latex, -brief, -rest
390 """
390 """
391
391
392 mode = ''
392 mode = ''
393 try:
393 try:
394 if parameter_s.split()[0] == '-latex':
394 if parameter_s.split()[0] == '-latex':
395 mode = 'latex'
395 mode = 'latex'
396 if parameter_s.split()[0] == '-brief':
396 if parameter_s.split()[0] == '-brief':
397 mode = 'brief'
397 mode = 'brief'
398 if parameter_s.split()[0] == '-rest':
398 if parameter_s.split()[0] == '-rest':
399 mode = 'rest'
399 mode = 'rest'
400 rest_docs = []
400 rest_docs = []
401 except:
401 except:
402 pass
402 pass
403
403
404 magic_docs = []
404 magic_docs = []
405 for fname in self.lsmagic():
405 for fname in self.lsmagic():
406 mname = 'magic_' + fname
406 mname = 'magic_' + fname
407 for space in (Magic,self,self.__class__):
407 for space in (Magic,self,self.__class__):
408 try:
408 try:
409 fn = space.__dict__[mname]
409 fn = space.__dict__[mname]
410 except KeyError:
410 except KeyError:
411 pass
411 pass
412 else:
412 else:
413 break
413 break
414 if mode == 'brief':
414 if mode == 'brief':
415 # only first line
415 # only first line
416 if fn.__doc__:
416 if fn.__doc__:
417 fndoc = fn.__doc__.split('\n',1)[0]
417 fndoc = fn.__doc__.split('\n',1)[0]
418 else:
418 else:
419 fndoc = 'No documentation'
419 fndoc = 'No documentation'
420 else:
420 else:
421 if fn.__doc__:
421 if fn.__doc__:
422 fndoc = fn.__doc__.rstrip()
422 fndoc = fn.__doc__.rstrip()
423 else:
423 else:
424 fndoc = 'No documentation'
424 fndoc = 'No documentation'
425
425
426
426
427 if mode == 'rest':
427 if mode == 'rest':
428 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
428 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
429 fname,fndoc))
429 fname,fndoc))
430
430
431 else:
431 else:
432 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
432 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
433 fname,fndoc))
433 fname,fndoc))
434
434
435 magic_docs = ''.join(magic_docs)
435 magic_docs = ''.join(magic_docs)
436
436
437 if mode == 'rest':
437 if mode == 'rest':
438 return "".join(rest_docs)
438 return "".join(rest_docs)
439
439
440 if mode == 'latex':
440 if mode == 'latex':
441 print self.format_latex(magic_docs)
441 print self.format_latex(magic_docs)
442 return
442 return
443 else:
443 else:
444 magic_docs = self.format_screen(magic_docs)
444 magic_docs = self.format_screen(magic_docs)
445 if mode == 'brief':
445 if mode == 'brief':
446 return magic_docs
446 return magic_docs
447
447
448 outmsg = """
448 outmsg = """
449 IPython's 'magic' functions
449 IPython's 'magic' functions
450 ===========================
450 ===========================
451
451
452 The magic function system provides a series of functions which allow you to
452 The magic function system provides a series of functions which allow you to
453 control the behavior of IPython itself, plus a lot of system-type
453 control the behavior of IPython itself, plus a lot of system-type
454 features. All these functions are prefixed with a % character, but parameters
454 features. All these functions are prefixed with a % character, but parameters
455 are given without parentheses or quotes.
455 are given without parentheses or quotes.
456
456
457 NOTE: If you have 'automagic' enabled (via the command line option or with the
457 NOTE: If you have 'automagic' enabled (via the command line option or with the
458 %automagic function), you don't need to type in the % explicitly. By default,
458 %automagic function), you don't need to type in the % explicitly. By default,
459 IPython ships with automagic on, so you should only rarely need the % escape.
459 IPython ships with automagic on, so you should only rarely need the % escape.
460
460
461 Example: typing '%cd mydir' (without the quotes) changes you working directory
461 Example: typing '%cd mydir' (without the quotes) changes you working directory
462 to 'mydir', if it exists.
462 to 'mydir', if it exists.
463
463
464 You can define your own magic functions to extend the system. See the supplied
464 You can define your own magic functions to extend the system. See the supplied
465 ipythonrc and example-magic.py files for details (in your ipython
465 ipythonrc and example-magic.py files for details (in your ipython
466 configuration directory, typically $HOME/.ipython/).
466 configuration directory, typically $HOME/.ipython/).
467
467
468 You can also define your own aliased names for magic functions. In your
468 You can also define your own aliased names for magic functions. In your
469 ipythonrc file, placing a line like:
469 ipythonrc file, placing a line like:
470
470
471 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
471 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
472
472
473 will define %pf as a new name for %profile.
473 will define %pf as a new name for %profile.
474
474
475 You can also call magics in code using the magic() function, which IPython
475 You can also call magics in code using the magic() function, which IPython
476 automatically adds to the builtin namespace. Type 'magic?' for details.
476 automatically adds to the builtin namespace. Type 'magic?' for details.
477
477
478 For a list of the available magic functions, use %lsmagic. For a description
478 For a list of the available magic functions, use %lsmagic. For a description
479 of any of them, type %magic_name?, e.g. '%cd?'.
479 of any of them, type %magic_name?, e.g. '%cd?'.
480
480
481 Currently the magic system has the following functions:\n"""
481 Currently the magic system has the following functions:\n"""
482
482
483 mesc = ESC_MAGIC
483 mesc = ESC_MAGIC
484 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
484 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
485 "\n\n%s%s\n\n%s" % (outmsg,
485 "\n\n%s%s\n\n%s" % (outmsg,
486 magic_docs,mesc,mesc,
486 magic_docs,mesc,mesc,
487 (' '+mesc).join(self.lsmagic()),
487 (' '+mesc).join(self.lsmagic()),
488 Magic.auto_status[self.shell.automagic] ) )
488 Magic.auto_status[self.shell.automagic] ) )
489
489
490 page(outmsg,screen_lines=self.shell.usable_screen_length)
490 page(outmsg,screen_lines=self.shell.usable_screen_length)
491
491
492
492
493 def magic_autoindent(self, parameter_s = ''):
493 def magic_autoindent(self, parameter_s = ''):
494 """Toggle autoindent on/off (if available)."""
494 """Toggle autoindent on/off (if available)."""
495
495
496 self.shell.set_autoindent()
496 self.shell.set_autoindent()
497 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
497 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
498
498
499
499
500 def magic_automagic(self, parameter_s = ''):
500 def magic_automagic(self, parameter_s = ''):
501 """Make magic functions callable without having to type the initial %.
501 """Make magic functions callable without having to type the initial %.
502
502
503 Without argumentsl toggles on/off (when off, you must call it as
503 Without argumentsl toggles on/off (when off, you must call it as
504 %automagic, of course). With arguments it sets the value, and you can
504 %automagic, of course). With arguments it sets the value, and you can
505 use any of (case insensitive):
505 use any of (case insensitive):
506
506
507 - on,1,True: to activate
507 - on,1,True: to activate
508
508
509 - off,0,False: to deactivate.
509 - off,0,False: to deactivate.
510
510
511 Note that magic functions have lowest priority, so if there's a
511 Note that magic functions have lowest priority, so if there's a
512 variable whose name collides with that of a magic fn, automagic won't
512 variable whose name collides with that of a magic fn, automagic won't
513 work for that function (you get the variable instead). However, if you
513 work for that function (you get the variable instead). However, if you
514 delete the variable (del var), the previously shadowed magic function
514 delete the variable (del var), the previously shadowed magic function
515 becomes visible to automagic again."""
515 becomes visible to automagic again."""
516
516
517 arg = parameter_s.lower()
517 arg = parameter_s.lower()
518 if parameter_s in ('on','1','true'):
518 if parameter_s in ('on','1','true'):
519 self.shell.automagic = True
519 self.shell.automagic = True
520 elif parameter_s in ('off','0','false'):
520 elif parameter_s in ('off','0','false'):
521 self.shell.automagic = False
521 self.shell.automagic = False
522 else:
522 else:
523 self.shell.automagic = not self.shell.automagic
523 self.shell.automagic = not self.shell.automagic
524 print '\n' + Magic.auto_status[self.shell.automagic]
524 print '\n' + Magic.auto_status[self.shell.automagic]
525
525
526 @testdec.skip_doctest
526 @testdec.skip_doctest
527 def magic_autocall(self, parameter_s = ''):
527 def magic_autocall(self, parameter_s = ''):
528 """Make functions callable without having to type parentheses.
528 """Make functions callable without having to type parentheses.
529
529
530 Usage:
530 Usage:
531
531
532 %autocall [mode]
532 %autocall [mode]
533
533
534 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
534 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
535 value is toggled on and off (remembering the previous state).
535 value is toggled on and off (remembering the previous state).
536
536
537 In more detail, these values mean:
537 In more detail, these values mean:
538
538
539 0 -> fully disabled
539 0 -> fully disabled
540
540
541 1 -> active, but do not apply if there are no arguments on the line.
541 1 -> active, but do not apply if there are no arguments on the line.
542
542
543 In this mode, you get:
543 In this mode, you get:
544
544
545 In [1]: callable
545 In [1]: callable
546 Out[1]: <built-in function callable>
546 Out[1]: <built-in function callable>
547
547
548 In [2]: callable 'hello'
548 In [2]: callable 'hello'
549 ------> callable('hello')
549 ------> callable('hello')
550 Out[2]: False
550 Out[2]: False
551
551
552 2 -> Active always. Even if no arguments are present, the callable
552 2 -> Active always. Even if no arguments are present, the callable
553 object is called:
553 object is called:
554
554
555 In [2]: float
555 In [2]: float
556 ------> float()
556 ------> float()
557 Out[2]: 0.0
557 Out[2]: 0.0
558
558
559 Note that even with autocall off, you can still use '/' at the start of
559 Note that even with autocall off, you can still use '/' at the start of
560 a line to treat the first argument on the command line as a function
560 a line to treat the first argument on the command line as a function
561 and add parentheses to it:
561 and add parentheses to it:
562
562
563 In [8]: /str 43
563 In [8]: /str 43
564 ------> str(43)
564 ------> str(43)
565 Out[8]: '43'
565 Out[8]: '43'
566
566
567 # all-random (note for auto-testing)
567 # all-random (note for auto-testing)
568 """
568 """
569
569
570 if parameter_s:
570 if parameter_s:
571 arg = int(parameter_s)
571 arg = int(parameter_s)
572 else:
572 else:
573 arg = 'toggle'
573 arg = 'toggle'
574
574
575 if not arg in (0,1,2,'toggle'):
575 if not arg in (0,1,2,'toggle'):
576 error('Valid modes: (0->Off, 1->Smart, 2->Full')
576 error('Valid modes: (0->Off, 1->Smart, 2->Full')
577 return
577 return
578
578
579 if arg in (0,1,2):
579 if arg in (0,1,2):
580 self.shell.autocall = arg
580 self.shell.autocall = arg
581 else: # toggle
581 else: # toggle
582 if self.shell.autocall:
582 if self.shell.autocall:
583 self._magic_state.autocall_save = self.shell.autocall
583 self._magic_state.autocall_save = self.shell.autocall
584 self.shell.autocall = 0
584 self.shell.autocall = 0
585 else:
585 else:
586 try:
586 try:
587 self.shell.autocall = self._magic_state.autocall_save
587 self.shell.autocall = self._magic_state.autocall_save
588 except AttributeError:
588 except AttributeError:
589 self.shell.autocall = self._magic_state.autocall_save = 1
589 self.shell.autocall = self._magic_state.autocall_save = 1
590
590
591 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
591 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
592
592
593 def magic_system_verbose(self, parameter_s = ''):
593 def magic_system_verbose(self, parameter_s = ''):
594 """Set verbose printing of system calls.
594 """Set verbose printing of system calls.
595
595
596 If called without an argument, act as a toggle"""
596 If called without an argument, act as a toggle"""
597
597
598 if parameter_s:
598 if parameter_s:
599 val = bool(eval(parameter_s))
599 val = bool(eval(parameter_s))
600 else:
600 else:
601 val = None
601 val = None
602
602
603 if self.shell.system_verbose:
603 if self.shell.system_verbose:
604 self.shell.system_verbose = False
604 self.shell.system_verbose = False
605 else:
605 else:
606 self.shell.system_verbose = True
606 self.shell.system_verbose = True
607 print "System verbose printing is:",\
607 print "System verbose printing is:",\
608 ['OFF','ON'][self.shell.system_verbose]
608 ['OFF','ON'][self.shell.system_verbose]
609
609
610
610
611 def magic_page(self, parameter_s=''):
611 def magic_page(self, parameter_s=''):
612 """Pretty print the object and display it through a pager.
612 """Pretty print the object and display it through a pager.
613
613
614 %page [options] OBJECT
614 %page [options] OBJECT
615
615
616 If no object is given, use _ (last output).
616 If no object is given, use _ (last output).
617
617
618 Options:
618 Options:
619
619
620 -r: page str(object), don't pretty-print it."""
620 -r: page str(object), don't pretty-print it."""
621
621
622 # After a function contributed by Olivier Aubert, slightly modified.
622 # After a function contributed by Olivier Aubert, slightly modified.
623
623
624 # Process options/args
624 # Process options/args
625 opts,args = self.parse_options(parameter_s,'r')
625 opts,args = self.parse_options(parameter_s,'r')
626 raw = 'r' in opts
626 raw = 'r' in opts
627
627
628 oname = args and args or '_'
628 oname = args and args or '_'
629 info = self._ofind(oname)
629 info = self._ofind(oname)
630 if info['found']:
630 if info['found']:
631 txt = (raw and str or pformat)( info['obj'] )
631 txt = (raw and str or pformat)( info['obj'] )
632 page(txt)
632 page(txt)
633 else:
633 else:
634 print 'Object `%s` not found' % oname
634 print 'Object `%s` not found' % oname
635
635
636 def magic_profile(self, parameter_s=''):
636 def magic_profile(self, parameter_s=''):
637 """Print your currently active IPyhton profile."""
637 """Print your currently active IPyhton profile."""
638 if self.shell.profile:
638 if self.shell.profile:
639 printpl('Current IPython profile: $self.shell.profile.')
639 printpl('Current IPython profile: $self.shell.profile.')
640 else:
640 else:
641 print 'No profile active.'
641 print 'No profile active.'
642
642
643 def magic_pinfo(self, parameter_s='', namespaces=None):
643 def magic_pinfo(self, parameter_s='', namespaces=None):
644 """Provide detailed information about an object.
644 """Provide detailed information about an object.
645
645
646 '%pinfo object' is just a synonym for object? or ?object."""
646 '%pinfo object' is just a synonym for object? or ?object."""
647
647
648 #print 'pinfo par: <%s>' % parameter_s # dbg
648 #print 'pinfo par: <%s>' % parameter_s # dbg
649
649
650
650
651 # detail_level: 0 -> obj? , 1 -> obj??
651 # detail_level: 0 -> obj? , 1 -> obj??
652 detail_level = 0
652 detail_level = 0
653 # We need to detect if we got called as 'pinfo pinfo foo', which can
653 # We need to detect if we got called as 'pinfo pinfo foo', which can
654 # happen if the user types 'pinfo foo?' at the cmd line.
654 # happen if the user types 'pinfo foo?' at the cmd line.
655 pinfo,qmark1,oname,qmark2 = \
655 pinfo,qmark1,oname,qmark2 = \
656 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
656 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
657 if pinfo or qmark1 or qmark2:
657 if pinfo or qmark1 or qmark2:
658 detail_level = 1
658 detail_level = 1
659 if "*" in oname:
659 if "*" in oname:
660 self.magic_psearch(oname)
660 self.magic_psearch(oname)
661 else:
661 else:
662 self._inspect('pinfo', oname, detail_level=detail_level,
662 self._inspect('pinfo', oname, detail_level=detail_level,
663 namespaces=namespaces)
663 namespaces=namespaces)
664
664
665 def magic_pdef(self, parameter_s='', namespaces=None):
665 def magic_pdef(self, parameter_s='', namespaces=None):
666 """Print the definition header for any callable object.
666 """Print the definition header for any callable object.
667
667
668 If the object is a class, print the constructor information."""
668 If the object is a class, print the constructor information."""
669 self._inspect('pdef',parameter_s, namespaces)
669 self._inspect('pdef',parameter_s, namespaces)
670
670
671 def magic_pdoc(self, parameter_s='', namespaces=None):
671 def magic_pdoc(self, parameter_s='', namespaces=None):
672 """Print the docstring for an object.
672 """Print the docstring for an object.
673
673
674 If the given object is a class, it will print both the class and the
674 If the given object is a class, it will print both the class and the
675 constructor docstrings."""
675 constructor docstrings."""
676 self._inspect('pdoc',parameter_s, namespaces)
676 self._inspect('pdoc',parameter_s, namespaces)
677
677
678 def magic_psource(self, parameter_s='', namespaces=None):
678 def magic_psource(self, parameter_s='', namespaces=None):
679 """Print (or run through pager) the source code for an object."""
679 """Print (or run through pager) the source code for an object."""
680 self._inspect('psource',parameter_s, namespaces)
680 self._inspect('psource',parameter_s, namespaces)
681
681
682 def magic_pfile(self, parameter_s=''):
682 def magic_pfile(self, parameter_s=''):
683 """Print (or run through pager) the file where an object is defined.
683 """Print (or run through pager) the file where an object is defined.
684
684
685 The file opens at the line where the object definition begins. IPython
685 The file opens at the line where the object definition begins. IPython
686 will honor the environment variable PAGER if set, and otherwise will
686 will honor the environment variable PAGER if set, and otherwise will
687 do its best to print the file in a convenient form.
687 do its best to print the file in a convenient form.
688
688
689 If the given argument is not an object currently defined, IPython will
689 If the given argument is not an object currently defined, IPython will
690 try to interpret it as a filename (automatically adding a .py extension
690 try to interpret it as a filename (automatically adding a .py extension
691 if needed). You can thus use %pfile as a syntax highlighting code
691 if needed). You can thus use %pfile as a syntax highlighting code
692 viewer."""
692 viewer."""
693
693
694 # first interpret argument as an object name
694 # first interpret argument as an object name
695 out = self._inspect('pfile',parameter_s)
695 out = self._inspect('pfile',parameter_s)
696 # if not, try the input as a filename
696 # if not, try the input as a filename
697 if out == 'not found':
697 if out == 'not found':
698 try:
698 try:
699 filename = get_py_filename(parameter_s)
699 filename = get_py_filename(parameter_s)
700 except IOError,msg:
700 except IOError,msg:
701 print msg
701 print msg
702 return
702 return
703 page(self.shell.inspector.format(file(filename).read()))
703 page(self.shell.inspector.format(file(filename).read()))
704
704
705 def _inspect(self,meth,oname,namespaces=None,**kw):
705 def _inspect(self,meth,oname,namespaces=None,**kw):
706 """Generic interface to the inspector system.
706 """Generic interface to the inspector system.
707
707
708 This function is meant to be called by pdef, pdoc & friends."""
708 This function is meant to be called by pdef, pdoc & friends."""
709
709
710 #oname = oname.strip()
710 #oname = oname.strip()
711 #print '1- oname: <%r>' % oname # dbg
711 #print '1- oname: <%r>' % oname # dbg
712 try:
712 try:
713 oname = oname.strip().encode('ascii')
713 oname = oname.strip().encode('ascii')
714 #print '2- oname: <%r>' % oname # dbg
714 #print '2- oname: <%r>' % oname # dbg
715 except UnicodeEncodeError:
715 except UnicodeEncodeError:
716 print 'Python identifiers can only contain ascii characters.'
716 print 'Python identifiers can only contain ascii characters.'
717 return 'not found'
717 return 'not found'
718
718
719 info = Struct(self._ofind(oname, namespaces))
719 info = Struct(self._ofind(oname, namespaces))
720
720
721 if info.found:
721 if info.found:
722 try:
722 try:
723 IPython.utils.generics.inspect_object(info.obj)
723 IPython.utils.generics.inspect_object(info.obj)
724 return
724 return
725 except TryNext:
725 except TryNext:
726 pass
726 pass
727 # Get the docstring of the class property if it exists.
727 # Get the docstring of the class property if it exists.
728 path = oname.split('.')
728 path = oname.split('.')
729 root = '.'.join(path[:-1])
729 root = '.'.join(path[:-1])
730 if info.parent is not None:
730 if info.parent is not None:
731 try:
731 try:
732 target = getattr(info.parent, '__class__')
732 target = getattr(info.parent, '__class__')
733 # The object belongs to a class instance.
733 # The object belongs to a class instance.
734 try:
734 try:
735 target = getattr(target, path[-1])
735 target = getattr(target, path[-1])
736 # The class defines the object.
736 # The class defines the object.
737 if isinstance(target, property):
737 if isinstance(target, property):
738 oname = root + '.__class__.' + path[-1]
738 oname = root + '.__class__.' + path[-1]
739 info = Struct(self._ofind(oname))
739 info = Struct(self._ofind(oname))
740 except AttributeError: pass
740 except AttributeError: pass
741 except AttributeError: pass
741 except AttributeError: pass
742
742
743 pmethod = getattr(self.shell.inspector,meth)
743 pmethod = getattr(self.shell.inspector,meth)
744 formatter = info.ismagic and self.format_screen or None
744 formatter = info.ismagic and self.format_screen or None
745 if meth == 'pdoc':
745 if meth == 'pdoc':
746 pmethod(info.obj,oname,formatter)
746 pmethod(info.obj,oname,formatter)
747 elif meth == 'pinfo':
747 elif meth == 'pinfo':
748 pmethod(info.obj,oname,formatter,info,**kw)
748 pmethod(info.obj,oname,formatter,info,**kw)
749 else:
749 else:
750 pmethod(info.obj,oname)
750 pmethod(info.obj,oname)
751 else:
751 else:
752 print 'Object `%s` not found.' % oname
752 print 'Object `%s` not found.' % oname
753 return 'not found' # so callers can take other action
753 return 'not found' # so callers can take other action
754
754
755 def magic_psearch(self, parameter_s=''):
755 def magic_psearch(self, parameter_s=''):
756 """Search for object in namespaces by wildcard.
756 """Search for object in namespaces by wildcard.
757
757
758 %psearch [options] PATTERN [OBJECT TYPE]
758 %psearch [options] PATTERN [OBJECT TYPE]
759
759
760 Note: ? can be used as a synonym for %psearch, at the beginning or at
760 Note: ? can be used as a synonym for %psearch, at the beginning or at
761 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
761 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
762 rest of the command line must be unchanged (options come first), so
762 rest of the command line must be unchanged (options come first), so
763 for example the following forms are equivalent
763 for example the following forms are equivalent
764
764
765 %psearch -i a* function
765 %psearch -i a* function
766 -i a* function?
766 -i a* function?
767 ?-i a* function
767 ?-i a* function
768
768
769 Arguments:
769 Arguments:
770
770
771 PATTERN
771 PATTERN
772
772
773 where PATTERN is a string containing * as a wildcard similar to its
773 where PATTERN is a string containing * as a wildcard similar to its
774 use in a shell. The pattern is matched in all namespaces on the
774 use in a shell. The pattern is matched in all namespaces on the
775 search path. By default objects starting with a single _ are not
775 search path. By default objects starting with a single _ are not
776 matched, many IPython generated objects have a single
776 matched, many IPython generated objects have a single
777 underscore. The default is case insensitive matching. Matching is
777 underscore. The default is case insensitive matching. Matching is
778 also done on the attributes of objects and not only on the objects
778 also done on the attributes of objects and not only on the objects
779 in a module.
779 in a module.
780
780
781 [OBJECT TYPE]
781 [OBJECT TYPE]
782
782
783 Is the name of a python type from the types module. The name is
783 Is the name of a python type from the types module. The name is
784 given in lowercase without the ending type, ex. StringType is
784 given in lowercase without the ending type, ex. StringType is
785 written string. By adding a type here only objects matching the
785 written string. By adding a type here only objects matching the
786 given type are matched. Using all here makes the pattern match all
786 given type are matched. Using all here makes the pattern match all
787 types (this is the default).
787 types (this is the default).
788
788
789 Options:
789 Options:
790
790
791 -a: makes the pattern match even objects whose names start with a
791 -a: makes the pattern match even objects whose names start with a
792 single underscore. These names are normally ommitted from the
792 single underscore. These names are normally ommitted from the
793 search.
793 search.
794
794
795 -i/-c: make the pattern case insensitive/sensitive. If neither of
795 -i/-c: make the pattern case insensitive/sensitive. If neither of
796 these options is given, the default is read from your ipythonrc
796 these options is given, the default is read from your ipythonrc
797 file. The option name which sets this value is
797 file. The option name which sets this value is
798 'wildcards_case_sensitive'. If this option is not specified in your
798 'wildcards_case_sensitive'. If this option is not specified in your
799 ipythonrc file, IPython's internal default is to do a case sensitive
799 ipythonrc file, IPython's internal default is to do a case sensitive
800 search.
800 search.
801
801
802 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
802 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
803 specifiy can be searched in any of the following namespaces:
803 specifiy can be searched in any of the following namespaces:
804 'builtin', 'user', 'user_global','internal', 'alias', where
804 'builtin', 'user', 'user_global','internal', 'alias', where
805 'builtin' and 'user' are the search defaults. Note that you should
805 'builtin' and 'user' are the search defaults. Note that you should
806 not use quotes when specifying namespaces.
806 not use quotes when specifying namespaces.
807
807
808 'Builtin' contains the python module builtin, 'user' contains all
808 'Builtin' contains the python module builtin, 'user' contains all
809 user data, 'alias' only contain the shell aliases and no python
809 user data, 'alias' only contain the shell aliases and no python
810 objects, 'internal' contains objects used by IPython. The
810 objects, 'internal' contains objects used by IPython. The
811 'user_global' namespace is only used by embedded IPython instances,
811 'user_global' namespace is only used by embedded IPython instances,
812 and it contains module-level globals. You can add namespaces to the
812 and it contains module-level globals. You can add namespaces to the
813 search with -s or exclude them with -e (these options can be given
813 search with -s or exclude them with -e (these options can be given
814 more than once).
814 more than once).
815
815
816 Examples:
816 Examples:
817
817
818 %psearch a* -> objects beginning with an a
818 %psearch a* -> objects beginning with an a
819 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
819 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
820 %psearch a* function -> all functions beginning with an a
820 %psearch a* function -> all functions beginning with an a
821 %psearch re.e* -> objects beginning with an e in module re
821 %psearch re.e* -> objects beginning with an e in module re
822 %psearch r*.e* -> objects that start with e in modules starting in r
822 %psearch r*.e* -> objects that start with e in modules starting in r
823 %psearch r*.* string -> all strings in modules beginning with r
823 %psearch r*.* string -> all strings in modules beginning with r
824
824
825 Case sensitve search:
825 Case sensitve search:
826
826
827 %psearch -c a* list all object beginning with lower case a
827 %psearch -c a* list all object beginning with lower case a
828
828
829 Show objects beginning with a single _:
829 Show objects beginning with a single _:
830
830
831 %psearch -a _* list objects beginning with a single underscore"""
831 %psearch -a _* list objects beginning with a single underscore"""
832 try:
832 try:
833 parameter_s = parameter_s.encode('ascii')
833 parameter_s = parameter_s.encode('ascii')
834 except UnicodeEncodeError:
834 except UnicodeEncodeError:
835 print 'Python identifiers can only contain ascii characters.'
835 print 'Python identifiers can only contain ascii characters.'
836 return
836 return
837
837
838 # default namespaces to be searched
838 # default namespaces to be searched
839 def_search = ['user','builtin']
839 def_search = ['user','builtin']
840
840
841 # Process options/args
841 # Process options/args
842 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
842 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
843 opt = opts.get
843 opt = opts.get
844 shell = self.shell
844 shell = self.shell
845 psearch = shell.inspector.psearch
845 psearch = shell.inspector.psearch
846
846
847 # select case options
847 # select case options
848 if opts.has_key('i'):
848 if opts.has_key('i'):
849 ignore_case = True
849 ignore_case = True
850 elif opts.has_key('c'):
850 elif opts.has_key('c'):
851 ignore_case = False
851 ignore_case = False
852 else:
852 else:
853 ignore_case = not shell.wildcards_case_sensitive
853 ignore_case = not shell.wildcards_case_sensitive
854
854
855 # Build list of namespaces to search from user options
855 # Build list of namespaces to search from user options
856 def_search.extend(opt('s',[]))
856 def_search.extend(opt('s',[]))
857 ns_exclude = ns_exclude=opt('e',[])
857 ns_exclude = ns_exclude=opt('e',[])
858 ns_search = [nm for nm in def_search if nm not in ns_exclude]
858 ns_search = [nm for nm in def_search if nm not in ns_exclude]
859
859
860 # Call the actual search
860 # Call the actual search
861 try:
861 try:
862 psearch(args,shell.ns_table,ns_search,
862 psearch(args,shell.ns_table,ns_search,
863 show_all=opt('a'),ignore_case=ignore_case)
863 show_all=opt('a'),ignore_case=ignore_case)
864 except:
864 except:
865 shell.showtraceback()
865 shell.showtraceback()
866
866
867 def magic_who_ls(self, parameter_s=''):
867 def magic_who_ls(self, parameter_s=''):
868 """Return a sorted list of all interactive variables.
868 """Return a sorted list of all interactive variables.
869
869
870 If arguments are given, only variables of types matching these
870 If arguments are given, only variables of types matching these
871 arguments are returned."""
871 arguments are returned."""
872
872
873 user_ns = self.shell.user_ns
873 user_ns = self.shell.user_ns
874 internal_ns = self.shell.internal_ns
874 internal_ns = self.shell.internal_ns
875 user_config_ns = self.shell.user_config_ns
875 user_config_ns = self.shell.user_config_ns
876 out = []
876 out = []
877 typelist = parameter_s.split()
877 typelist = parameter_s.split()
878
878
879 for i in user_ns:
879 for i in user_ns:
880 if not (i.startswith('_') or i.startswith('_i')) \
880 if not (i.startswith('_') or i.startswith('_i')) \
881 and not (i in internal_ns or i in user_config_ns):
881 and not (i in internal_ns or i in user_config_ns):
882 if typelist:
882 if typelist:
883 if type(user_ns[i]).__name__ in typelist:
883 if type(user_ns[i]).__name__ in typelist:
884 out.append(i)
884 out.append(i)
885 else:
885 else:
886 out.append(i)
886 out.append(i)
887 out.sort()
887 out.sort()
888 return out
888 return out
889
889
890 def magic_who(self, parameter_s=''):
890 def magic_who(self, parameter_s=''):
891 """Print all interactive variables, with some minimal formatting.
891 """Print all interactive variables, with some minimal formatting.
892
892
893 If any arguments are given, only variables whose type matches one of
893 If any arguments are given, only variables whose type matches one of
894 these are printed. For example:
894 these are printed. For example:
895
895
896 %who function str
896 %who function str
897
897
898 will only list functions and strings, excluding all other types of
898 will only list functions and strings, excluding all other types of
899 variables. To find the proper type names, simply use type(var) at a
899 variables. To find the proper type names, simply use type(var) at a
900 command line to see how python prints type names. For example:
900 command line to see how python prints type names. For example:
901
901
902 In [1]: type('hello')\\
902 In [1]: type('hello')\\
903 Out[1]: <type 'str'>
903 Out[1]: <type 'str'>
904
904
905 indicates that the type name for strings is 'str'.
905 indicates that the type name for strings is 'str'.
906
906
907 %who always excludes executed names loaded through your configuration
907 %who always excludes executed names loaded through your configuration
908 file and things which are internal to IPython.
908 file and things which are internal to IPython.
909
909
910 This is deliberate, as typically you may load many modules and the
910 This is deliberate, as typically you may load many modules and the
911 purpose of %who is to show you only what you've manually defined."""
911 purpose of %who is to show you only what you've manually defined."""
912
912
913 varlist = self.magic_who_ls(parameter_s)
913 varlist = self.magic_who_ls(parameter_s)
914 if not varlist:
914 if not varlist:
915 if parameter_s:
915 if parameter_s:
916 print 'No variables match your requested type.'
916 print 'No variables match your requested type.'
917 else:
917 else:
918 print 'Interactive namespace is empty.'
918 print 'Interactive namespace is empty.'
919 return
919 return
920
920
921 # if we have variables, move on...
921 # if we have variables, move on...
922 count = 0
922 count = 0
923 for i in varlist:
923 for i in varlist:
924 print i+'\t',
924 print i+'\t',
925 count += 1
925 count += 1
926 if count > 8:
926 if count > 8:
927 count = 0
927 count = 0
928 print
928 print
929 print
929 print
930
930
931 def magic_whos(self, parameter_s=''):
931 def magic_whos(self, parameter_s=''):
932 """Like %who, but gives some extra information about each variable.
932 """Like %who, but gives some extra information about each variable.
933
933
934 The same type filtering of %who can be applied here.
934 The same type filtering of %who can be applied here.
935
935
936 For all variables, the type is printed. Additionally it prints:
936 For all variables, the type is printed. Additionally it prints:
937
937
938 - For {},[],(): their length.
938 - For {},[],(): their length.
939
939
940 - For numpy and Numeric arrays, a summary with shape, number of
940 - For numpy and Numeric arrays, a summary with shape, number of
941 elements, typecode and size in memory.
941 elements, typecode and size in memory.
942
942
943 - Everything else: a string representation, snipping their middle if
943 - Everything else: a string representation, snipping their middle if
944 too long."""
944 too long."""
945
945
946 varnames = self.magic_who_ls(parameter_s)
946 varnames = self.magic_who_ls(parameter_s)
947 if not varnames:
947 if not varnames:
948 if parameter_s:
948 if parameter_s:
949 print 'No variables match your requested type.'
949 print 'No variables match your requested type.'
950 else:
950 else:
951 print 'Interactive namespace is empty.'
951 print 'Interactive namespace is empty.'
952 return
952 return
953
953
954 # if we have variables, move on...
954 # if we have variables, move on...
955
955
956 # for these types, show len() instead of data:
956 # for these types, show len() instead of data:
957 seq_types = [types.DictType,types.ListType,types.TupleType]
957 seq_types = [types.DictType,types.ListType,types.TupleType]
958
958
959 # for numpy/Numeric arrays, display summary info
959 # for numpy/Numeric arrays, display summary info
960 try:
960 try:
961 import numpy
961 import numpy
962 except ImportError:
962 except ImportError:
963 ndarray_type = None
963 ndarray_type = None
964 else:
964 else:
965 ndarray_type = numpy.ndarray.__name__
965 ndarray_type = numpy.ndarray.__name__
966 try:
966 try:
967 import Numeric
967 import Numeric
968 except ImportError:
968 except ImportError:
969 array_type = None
969 array_type = None
970 else:
970 else:
971 array_type = Numeric.ArrayType.__name__
971 array_type = Numeric.ArrayType.__name__
972
972
973 # Find all variable names and types so we can figure out column sizes
973 # Find all variable names and types so we can figure out column sizes
974 def get_vars(i):
974 def get_vars(i):
975 return self.shell.user_ns[i]
975 return self.shell.user_ns[i]
976
976
977 # some types are well known and can be shorter
977 # some types are well known and can be shorter
978 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
978 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
979 def type_name(v):
979 def type_name(v):
980 tn = type(v).__name__
980 tn = type(v).__name__
981 return abbrevs.get(tn,tn)
981 return abbrevs.get(tn,tn)
982
982
983 varlist = map(get_vars,varnames)
983 varlist = map(get_vars,varnames)
984
984
985 typelist = []
985 typelist = []
986 for vv in varlist:
986 for vv in varlist:
987 tt = type_name(vv)
987 tt = type_name(vv)
988
988
989 if tt=='instance':
989 if tt=='instance':
990 typelist.append( abbrevs.get(str(vv.__class__),
990 typelist.append( abbrevs.get(str(vv.__class__),
991 str(vv.__class__)))
991 str(vv.__class__)))
992 else:
992 else:
993 typelist.append(tt)
993 typelist.append(tt)
994
994
995 # column labels and # of spaces as separator
995 # column labels and # of spaces as separator
996 varlabel = 'Variable'
996 varlabel = 'Variable'
997 typelabel = 'Type'
997 typelabel = 'Type'
998 datalabel = 'Data/Info'
998 datalabel = 'Data/Info'
999 colsep = 3
999 colsep = 3
1000 # variable format strings
1000 # variable format strings
1001 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1001 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1002 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1002 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1003 aformat = "%s: %s elems, type `%s`, %s bytes"
1003 aformat = "%s: %s elems, type `%s`, %s bytes"
1004 # find the size of the columns to format the output nicely
1004 # find the size of the columns to format the output nicely
1005 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1005 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1006 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1006 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1007 # table header
1007 # table header
1008 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1008 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1009 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1009 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1010 # and the table itself
1010 # and the table itself
1011 kb = 1024
1011 kb = 1024
1012 Mb = 1048576 # kb**2
1012 Mb = 1048576 # kb**2
1013 for vname,var,vtype in zip(varnames,varlist,typelist):
1013 for vname,var,vtype in zip(varnames,varlist,typelist):
1014 print itpl(vformat),
1014 print itpl(vformat),
1015 if vtype in seq_types:
1015 if vtype in seq_types:
1016 print len(var)
1016 print len(var)
1017 elif vtype in [array_type,ndarray_type]:
1017 elif vtype in [array_type,ndarray_type]:
1018 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1018 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1019 if vtype==ndarray_type:
1019 if vtype==ndarray_type:
1020 # numpy
1020 # numpy
1021 vsize = var.size
1021 vsize = var.size
1022 vbytes = vsize*var.itemsize
1022 vbytes = vsize*var.itemsize
1023 vdtype = var.dtype
1023 vdtype = var.dtype
1024 else:
1024 else:
1025 # Numeric
1025 # Numeric
1026 vsize = Numeric.size(var)
1026 vsize = Numeric.size(var)
1027 vbytes = vsize*var.itemsize()
1027 vbytes = vsize*var.itemsize()
1028 vdtype = var.typecode()
1028 vdtype = var.typecode()
1029
1029
1030 if vbytes < 100000:
1030 if vbytes < 100000:
1031 print aformat % (vshape,vsize,vdtype,vbytes)
1031 print aformat % (vshape,vsize,vdtype,vbytes)
1032 else:
1032 else:
1033 print aformat % (vshape,vsize,vdtype,vbytes),
1033 print aformat % (vshape,vsize,vdtype,vbytes),
1034 if vbytes < Mb:
1034 if vbytes < Mb:
1035 print '(%s kb)' % (vbytes/kb,)
1035 print '(%s kb)' % (vbytes/kb,)
1036 else:
1036 else:
1037 print '(%s Mb)' % (vbytes/Mb,)
1037 print '(%s Mb)' % (vbytes/Mb,)
1038 else:
1038 else:
1039 try:
1039 try:
1040 vstr = str(var)
1040 vstr = str(var)
1041 except UnicodeEncodeError:
1041 except UnicodeEncodeError:
1042 vstr = unicode(var).encode(sys.getdefaultencoding(),
1042 vstr = unicode(var).encode(sys.getdefaultencoding(),
1043 'backslashreplace')
1043 'backslashreplace')
1044 vstr = vstr.replace('\n','\\n')
1044 vstr = vstr.replace('\n','\\n')
1045 if len(vstr) < 50:
1045 if len(vstr) < 50:
1046 print vstr
1046 print vstr
1047 else:
1047 else:
1048 printpl(vfmt_short)
1048 printpl(vfmt_short)
1049
1049
1050 def magic_reset(self, parameter_s=''):
1050 def magic_reset(self, parameter_s=''):
1051 """Resets the namespace by removing all names defined by the user.
1051 """Resets the namespace by removing all names defined by the user.
1052
1052
1053 Input/Output history are left around in case you need them.
1053 Input/Output history are left around in case you need them.
1054
1054
1055 Parameters
1055 Parameters
1056 ----------
1056 ----------
1057 -y : force reset without asking for confirmation.
1057 -y : force reset without asking for confirmation.
1058
1058
1059 Examples
1059 Examples
1060 --------
1060 --------
1061 In [6]: a = 1
1061 In [6]: a = 1
1062
1062
1063 In [7]: a
1063 In [7]: a
1064 Out[7]: 1
1064 Out[7]: 1
1065
1065
1066 In [8]: 'a' in _ip.user_ns
1066 In [8]: 'a' in _ip.user_ns
1067 Out[8]: True
1067 Out[8]: True
1068
1068
1069 In [9]: %reset -f
1069 In [9]: %reset -f
1070
1070
1071 In [10]: 'a' in _ip.user_ns
1071 In [10]: 'a' in _ip.user_ns
1072 Out[10]: False
1072 Out[10]: False
1073 """
1073 """
1074
1074
1075 if parameter_s == '-f':
1075 if parameter_s == '-f':
1076 ans = True
1076 ans = True
1077 else:
1077 else:
1078 ans = self.shell.ask_yes_no(
1078 ans = self.shell.ask_yes_no(
1079 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1079 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1080 if not ans:
1080 if not ans:
1081 print 'Nothing done.'
1081 print 'Nothing done.'
1082 return
1082 return
1083 user_ns = self.shell.user_ns
1083 user_ns = self.shell.user_ns
1084 for i in self.magic_who_ls():
1084 for i in self.magic_who_ls():
1085 del(user_ns[i])
1085 del(user_ns[i])
1086
1086
1087 # Also flush the private list of module references kept for script
1087 # Also flush the private list of module references kept for script
1088 # execution protection
1088 # execution protection
1089 self.shell.clear_main_mod_cache()
1089 self.shell.clear_main_mod_cache()
1090
1090
1091 def magic_logstart(self,parameter_s=''):
1091 def magic_logstart(self,parameter_s=''):
1092 """Start logging anywhere in a session.
1092 """Start logging anywhere in a session.
1093
1093
1094 %logstart [-o|-r|-t] [log_name [log_mode]]
1094 %logstart [-o|-r|-t] [log_name [log_mode]]
1095
1095
1096 If no name is given, it defaults to a file named 'ipython_log.py' in your
1096 If no name is given, it defaults to a file named 'ipython_log.py' in your
1097 current directory, in 'rotate' mode (see below).
1097 current directory, in 'rotate' mode (see below).
1098
1098
1099 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1099 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1100 history up to that point and then continues logging.
1100 history up to that point and then continues logging.
1101
1101
1102 %logstart takes a second optional parameter: logging mode. This can be one
1102 %logstart takes a second optional parameter: logging mode. This can be one
1103 of (note that the modes are given unquoted):\\
1103 of (note that the modes are given unquoted):\\
1104 append: well, that says it.\\
1104 append: well, that says it.\\
1105 backup: rename (if exists) to name~ and start name.\\
1105 backup: rename (if exists) to name~ and start name.\\
1106 global: single logfile in your home dir, appended to.\\
1106 global: single logfile in your home dir, appended to.\\
1107 over : overwrite existing log.\\
1107 over : overwrite existing log.\\
1108 rotate: create rotating logs name.1~, name.2~, etc.
1108 rotate: create rotating logs name.1~, name.2~, etc.
1109
1109
1110 Options:
1110 Options:
1111
1111
1112 -o: log also IPython's output. In this mode, all commands which
1112 -o: log also IPython's output. In this mode, all commands which
1113 generate an Out[NN] prompt are recorded to the logfile, right after
1113 generate an Out[NN] prompt are recorded to the logfile, right after
1114 their corresponding input line. The output lines are always
1114 their corresponding input line. The output lines are always
1115 prepended with a '#[Out]# ' marker, so that the log remains valid
1115 prepended with a '#[Out]# ' marker, so that the log remains valid
1116 Python code.
1116 Python code.
1117
1117
1118 Since this marker is always the same, filtering only the output from
1118 Since this marker is always the same, filtering only the output from
1119 a log is very easy, using for example a simple awk call:
1119 a log is very easy, using for example a simple awk call:
1120
1120
1121 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1121 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1122
1122
1123 -r: log 'raw' input. Normally, IPython's logs contain the processed
1123 -r: log 'raw' input. Normally, IPython's logs contain the processed
1124 input, so that user lines are logged in their final form, converted
1124 input, so that user lines are logged in their final form, converted
1125 into valid Python. For example, %Exit is logged as
1125 into valid Python. For example, %Exit is logged as
1126 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1126 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1127 exactly as typed, with no transformations applied.
1127 exactly as typed, with no transformations applied.
1128
1128
1129 -t: put timestamps before each input line logged (these are put in
1129 -t: put timestamps before each input line logged (these are put in
1130 comments)."""
1130 comments)."""
1131
1131
1132 opts,par = self.parse_options(parameter_s,'ort')
1132 opts,par = self.parse_options(parameter_s,'ort')
1133 log_output = 'o' in opts
1133 log_output = 'o' in opts
1134 log_raw_input = 'r' in opts
1134 log_raw_input = 'r' in opts
1135 timestamp = 't' in opts
1135 timestamp = 't' in opts
1136
1136
1137 logger = self.shell.logger
1137 logger = self.shell.logger
1138
1138
1139 # if no args are given, the defaults set in the logger constructor by
1139 # if no args are given, the defaults set in the logger constructor by
1140 # ipytohn remain valid
1140 # ipytohn remain valid
1141 if par:
1141 if par:
1142 try:
1142 try:
1143 logfname,logmode = par.split()
1143 logfname,logmode = par.split()
1144 except:
1144 except:
1145 logfname = par
1145 logfname = par
1146 logmode = 'backup'
1146 logmode = 'backup'
1147 else:
1147 else:
1148 logfname = logger.logfname
1148 logfname = logger.logfname
1149 logmode = logger.logmode
1149 logmode = logger.logmode
1150 # put logfname into rc struct as if it had been called on the command
1150 # put logfname into rc struct as if it had been called on the command
1151 # line, so it ends up saved in the log header Save it in case we need
1151 # line, so it ends up saved in the log header Save it in case we need
1152 # to restore it...
1152 # to restore it...
1153 old_logfile = self.shell.logfile
1153 old_logfile = self.shell.logfile
1154 if logfname:
1154 if logfname:
1155 logfname = os.path.expanduser(logfname)
1155 logfname = os.path.expanduser(logfname)
1156 self.shell.logfile = logfname
1156 self.shell.logfile = logfname
1157
1157
1158 loghead = '# IPython log file\n\n'
1158 loghead = '# IPython log file\n\n'
1159 try:
1159 try:
1160 started = logger.logstart(logfname,loghead,logmode,
1160 started = logger.logstart(logfname,loghead,logmode,
1161 log_output,timestamp,log_raw_input)
1161 log_output,timestamp,log_raw_input)
1162 except:
1162 except:
1163 rc.opts.logfile = old_logfile
1163 rc.opts.logfile = old_logfile
1164 warn("Couldn't start log: %s" % sys.exc_info()[1])
1164 warn("Couldn't start log: %s" % sys.exc_info()[1])
1165 else:
1165 else:
1166 # log input history up to this point, optionally interleaving
1166 # log input history up to this point, optionally interleaving
1167 # output if requested
1167 # output if requested
1168
1168
1169 if timestamp:
1169 if timestamp:
1170 # disable timestamping for the previous history, since we've
1170 # disable timestamping for the previous history, since we've
1171 # lost those already (no time machine here).
1171 # lost those already (no time machine here).
1172 logger.timestamp = False
1172 logger.timestamp = False
1173
1173
1174 if log_raw_input:
1174 if log_raw_input:
1175 input_hist = self.shell.input_hist_raw
1175 input_hist = self.shell.input_hist_raw
1176 else:
1176 else:
1177 input_hist = self.shell.input_hist
1177 input_hist = self.shell.input_hist
1178
1178
1179 if log_output:
1179 if log_output:
1180 log_write = logger.log_write
1180 log_write = logger.log_write
1181 output_hist = self.shell.output_hist
1181 output_hist = self.shell.output_hist
1182 for n in range(1,len(input_hist)-1):
1182 for n in range(1,len(input_hist)-1):
1183 log_write(input_hist[n].rstrip())
1183 log_write(input_hist[n].rstrip())
1184 if n in output_hist:
1184 if n in output_hist:
1185 log_write(repr(output_hist[n]),'output')
1185 log_write(repr(output_hist[n]),'output')
1186 else:
1186 else:
1187 logger.log_write(input_hist[1:])
1187 logger.log_write(input_hist[1:])
1188 if timestamp:
1188 if timestamp:
1189 # re-enable timestamping
1189 # re-enable timestamping
1190 logger.timestamp = True
1190 logger.timestamp = True
1191
1191
1192 print ('Activating auto-logging. '
1192 print ('Activating auto-logging. '
1193 'Current session state plus future input saved.')
1193 'Current session state plus future input saved.')
1194 logger.logstate()
1194 logger.logstate()
1195
1195
1196 def magic_logstop(self,parameter_s=''):
1196 def magic_logstop(self,parameter_s=''):
1197 """Fully stop logging and close log file.
1197 """Fully stop logging and close log file.
1198
1198
1199 In order to start logging again, a new %logstart call needs to be made,
1199 In order to start logging again, a new %logstart call needs to be made,
1200 possibly (though not necessarily) with a new filename, mode and other
1200 possibly (though not necessarily) with a new filename, mode and other
1201 options."""
1201 options."""
1202 self.logger.logstop()
1202 self.logger.logstop()
1203
1203
1204 def magic_logoff(self,parameter_s=''):
1204 def magic_logoff(self,parameter_s=''):
1205 """Temporarily stop logging.
1205 """Temporarily stop logging.
1206
1206
1207 You must have previously started logging."""
1207 You must have previously started logging."""
1208 self.shell.logger.switch_log(0)
1208 self.shell.logger.switch_log(0)
1209
1209
1210 def magic_logon(self,parameter_s=''):
1210 def magic_logon(self,parameter_s=''):
1211 """Restart logging.
1211 """Restart logging.
1212
1212
1213 This function is for restarting logging which you've temporarily
1213 This function is for restarting logging which you've temporarily
1214 stopped with %logoff. For starting logging for the first time, you
1214 stopped with %logoff. For starting logging for the first time, you
1215 must use the %logstart function, which allows you to specify an
1215 must use the %logstart function, which allows you to specify an
1216 optional log filename."""
1216 optional log filename."""
1217
1217
1218 self.shell.logger.switch_log(1)
1218 self.shell.logger.switch_log(1)
1219
1219
1220 def magic_logstate(self,parameter_s=''):
1220 def magic_logstate(self,parameter_s=''):
1221 """Print the status of the logging system."""
1221 """Print the status of the logging system."""
1222
1222
1223 self.shell.logger.logstate()
1223 self.shell.logger.logstate()
1224
1224
1225 def magic_pdb(self, parameter_s=''):
1225 def magic_pdb(self, parameter_s=''):
1226 """Control the automatic calling of the pdb interactive debugger.
1226 """Control the automatic calling of the pdb interactive debugger.
1227
1227
1228 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1228 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1229 argument it works as a toggle.
1229 argument it works as a toggle.
1230
1230
1231 When an exception is triggered, IPython can optionally call the
1231 When an exception is triggered, IPython can optionally call the
1232 interactive pdb debugger after the traceback printout. %pdb toggles
1232 interactive pdb debugger after the traceback printout. %pdb toggles
1233 this feature on and off.
1233 this feature on and off.
1234
1234
1235 The initial state of this feature is set in your ipythonrc
1235 The initial state of this feature is set in your ipythonrc
1236 configuration file (the variable is called 'pdb').
1236 configuration file (the variable is called 'pdb').
1237
1237
1238 If you want to just activate the debugger AFTER an exception has fired,
1238 If you want to just activate the debugger AFTER an exception has fired,
1239 without having to type '%pdb on' and rerunning your code, you can use
1239 without having to type '%pdb on' and rerunning your code, you can use
1240 the %debug magic."""
1240 the %debug magic."""
1241
1241
1242 par = parameter_s.strip().lower()
1242 par = parameter_s.strip().lower()
1243
1243
1244 if par:
1244 if par:
1245 try:
1245 try:
1246 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1246 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1247 except KeyError:
1247 except KeyError:
1248 print ('Incorrect argument. Use on/1, off/0, '
1248 print ('Incorrect argument. Use on/1, off/0, '
1249 'or nothing for a toggle.')
1249 'or nothing for a toggle.')
1250 return
1250 return
1251 else:
1251 else:
1252 # toggle
1252 # toggle
1253 new_pdb = not self.shell.call_pdb
1253 new_pdb = not self.shell.call_pdb
1254
1254
1255 # set on the shell
1255 # set on the shell
1256 self.shell.call_pdb = new_pdb
1256 self.shell.call_pdb = new_pdb
1257 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1257 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1258
1258
1259 def magic_debug(self, parameter_s=''):
1259 def magic_debug(self, parameter_s=''):
1260 """Activate the interactive debugger in post-mortem mode.
1260 """Activate the interactive debugger in post-mortem mode.
1261
1261
1262 If an exception has just occurred, this lets you inspect its stack
1262 If an exception has just occurred, this lets you inspect its stack
1263 frames interactively. Note that this will always work only on the last
1263 frames interactively. Note that this will always work only on the last
1264 traceback that occurred, so you must call this quickly after an
1264 traceback that occurred, so you must call this quickly after an
1265 exception that you wish to inspect has fired, because if another one
1265 exception that you wish to inspect has fired, because if another one
1266 occurs, it clobbers the previous one.
1266 occurs, it clobbers the previous one.
1267
1267
1268 If you want IPython to automatically do this on every exception, see
1268 If you want IPython to automatically do this on every exception, see
1269 the %pdb magic for more details.
1269 the %pdb magic for more details.
1270 """
1270 """
1271
1271
1272 self.shell.debugger(force=True)
1272 self.shell.debugger(force=True)
1273
1273
1274 @testdec.skip_doctest
1274 @testdec.skip_doctest
1275 def magic_prun(self, parameter_s ='',user_mode=1,
1275 def magic_prun(self, parameter_s ='',user_mode=1,
1276 opts=None,arg_lst=None,prog_ns=None):
1276 opts=None,arg_lst=None,prog_ns=None):
1277
1277
1278 """Run a statement through the python code profiler.
1278 """Run a statement through the python code profiler.
1279
1279
1280 Usage:
1280 Usage:
1281 %prun [options] statement
1281 %prun [options] statement
1282
1282
1283 The given statement (which doesn't require quote marks) is run via the
1283 The given statement (which doesn't require quote marks) is run via the
1284 python profiler in a manner similar to the profile.run() function.
1284 python profiler in a manner similar to the profile.run() function.
1285 Namespaces are internally managed to work correctly; profile.run
1285 Namespaces are internally managed to work correctly; profile.run
1286 cannot be used in IPython because it makes certain assumptions about
1286 cannot be used in IPython because it makes certain assumptions about
1287 namespaces which do not hold under IPython.
1287 namespaces which do not hold under IPython.
1288
1288
1289 Options:
1289 Options:
1290
1290
1291 -l <limit>: you can place restrictions on what or how much of the
1291 -l <limit>: you can place restrictions on what or how much of the
1292 profile gets printed. The limit value can be:
1292 profile gets printed. The limit value can be:
1293
1293
1294 * A string: only information for function names containing this string
1294 * A string: only information for function names containing this string
1295 is printed.
1295 is printed.
1296
1296
1297 * An integer: only these many lines are printed.
1297 * An integer: only these many lines are printed.
1298
1298
1299 * A float (between 0 and 1): this fraction of the report is printed
1299 * A float (between 0 and 1): this fraction of the report is printed
1300 (for example, use a limit of 0.4 to see the topmost 40% only).
1300 (for example, use a limit of 0.4 to see the topmost 40% only).
1301
1301
1302 You can combine several limits with repeated use of the option. For
1302 You can combine several limits with repeated use of the option. For
1303 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1303 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1304 information about class constructors.
1304 information about class constructors.
1305
1305
1306 -r: return the pstats.Stats object generated by the profiling. This
1306 -r: return the pstats.Stats object generated by the profiling. This
1307 object has all the information about the profile in it, and you can
1307 object has all the information about the profile in it, and you can
1308 later use it for further analysis or in other functions.
1308 later use it for further analysis or in other functions.
1309
1309
1310 -s <key>: sort profile by given key. You can provide more than one key
1310 -s <key>: sort profile by given key. You can provide more than one key
1311 by using the option several times: '-s key1 -s key2 -s key3...'. The
1311 by using the option several times: '-s key1 -s key2 -s key3...'. The
1312 default sorting key is 'time'.
1312 default sorting key is 'time'.
1313
1313
1314 The following is copied verbatim from the profile documentation
1314 The following is copied verbatim from the profile documentation
1315 referenced below:
1315 referenced below:
1316
1316
1317 When more than one key is provided, additional keys are used as
1317 When more than one key is provided, additional keys are used as
1318 secondary criteria when the there is equality in all keys selected
1318 secondary criteria when the there is equality in all keys selected
1319 before them.
1319 before them.
1320
1320
1321 Abbreviations can be used for any key names, as long as the
1321 Abbreviations can be used for any key names, as long as the
1322 abbreviation is unambiguous. The following are the keys currently
1322 abbreviation is unambiguous. The following are the keys currently
1323 defined:
1323 defined:
1324
1324
1325 Valid Arg Meaning
1325 Valid Arg Meaning
1326 "calls" call count
1326 "calls" call count
1327 "cumulative" cumulative time
1327 "cumulative" cumulative time
1328 "file" file name
1328 "file" file name
1329 "module" file name
1329 "module" file name
1330 "pcalls" primitive call count
1330 "pcalls" primitive call count
1331 "line" line number
1331 "line" line number
1332 "name" function name
1332 "name" function name
1333 "nfl" name/file/line
1333 "nfl" name/file/line
1334 "stdname" standard name
1334 "stdname" standard name
1335 "time" internal time
1335 "time" internal time
1336
1336
1337 Note that all sorts on statistics are in descending order (placing
1337 Note that all sorts on statistics are in descending order (placing
1338 most time consuming items first), where as name, file, and line number
1338 most time consuming items first), where as name, file, and line number
1339 searches are in ascending order (i.e., alphabetical). The subtle
1339 searches are in ascending order (i.e., alphabetical). The subtle
1340 distinction between "nfl" and "stdname" is that the standard name is a
1340 distinction between "nfl" and "stdname" is that the standard name is a
1341 sort of the name as printed, which means that the embedded line
1341 sort of the name as printed, which means that the embedded line
1342 numbers get compared in an odd way. For example, lines 3, 20, and 40
1342 numbers get compared in an odd way. For example, lines 3, 20, and 40
1343 would (if the file names were the same) appear in the string order
1343 would (if the file names were the same) appear in the string order
1344 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1344 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1345 line numbers. In fact, sort_stats("nfl") is the same as
1345 line numbers. In fact, sort_stats("nfl") is the same as
1346 sort_stats("name", "file", "line").
1346 sort_stats("name", "file", "line").
1347
1347
1348 -T <filename>: save profile results as shown on screen to a text
1348 -T <filename>: save profile results as shown on screen to a text
1349 file. The profile is still shown on screen.
1349 file. The profile is still shown on screen.
1350
1350
1351 -D <filename>: save (via dump_stats) profile statistics to given
1351 -D <filename>: save (via dump_stats) profile statistics to given
1352 filename. This data is in a format understod by the pstats module, and
1352 filename. This data is in a format understod by the pstats module, and
1353 is generated by a call to the dump_stats() method of profile
1353 is generated by a call to the dump_stats() method of profile
1354 objects. The profile is still shown on screen.
1354 objects. The profile is still shown on screen.
1355
1355
1356 If you want to run complete programs under the profiler's control, use
1356 If you want to run complete programs under the profiler's control, use
1357 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1357 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1358 contains profiler specific options as described here.
1358 contains profiler specific options as described here.
1359
1359
1360 You can read the complete documentation for the profile module with::
1360 You can read the complete documentation for the profile module with::
1361
1361
1362 In [1]: import profile; profile.help()
1362 In [1]: import profile; profile.help()
1363 """
1363 """
1364
1364
1365 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1365 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1366 # protect user quote marks
1366 # protect user quote marks
1367 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1367 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1368
1368
1369 if user_mode: # regular user call
1369 if user_mode: # regular user call
1370 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1370 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1371 list_all=1)
1371 list_all=1)
1372 namespace = self.shell.user_ns
1372 namespace = self.shell.user_ns
1373 else: # called to run a program by %run -p
1373 else: # called to run a program by %run -p
1374 try:
1374 try:
1375 filename = get_py_filename(arg_lst[0])
1375 filename = get_py_filename(arg_lst[0])
1376 except IOError,msg:
1376 except IOError,msg:
1377 error(msg)
1377 error(msg)
1378 return
1378 return
1379
1379
1380 arg_str = 'execfile(filename,prog_ns)'
1380 arg_str = 'execfile(filename,prog_ns)'
1381 namespace = locals()
1381 namespace = locals()
1382
1382
1383 opts.merge(opts_def)
1383 opts.merge(opts_def)
1384
1384
1385 prof = profile.Profile()
1385 prof = profile.Profile()
1386 try:
1386 try:
1387 prof = prof.runctx(arg_str,namespace,namespace)
1387 prof = prof.runctx(arg_str,namespace,namespace)
1388 sys_exit = ''
1388 sys_exit = ''
1389 except SystemExit:
1389 except SystemExit:
1390 sys_exit = """*** SystemExit exception caught in code being profiled."""
1390 sys_exit = """*** SystemExit exception caught in code being profiled."""
1391
1391
1392 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1392 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1393
1393
1394 lims = opts.l
1394 lims = opts.l
1395 if lims:
1395 if lims:
1396 lims = [] # rebuild lims with ints/floats/strings
1396 lims = [] # rebuild lims with ints/floats/strings
1397 for lim in opts.l:
1397 for lim in opts.l:
1398 try:
1398 try:
1399 lims.append(int(lim))
1399 lims.append(int(lim))
1400 except ValueError:
1400 except ValueError:
1401 try:
1401 try:
1402 lims.append(float(lim))
1402 lims.append(float(lim))
1403 except ValueError:
1403 except ValueError:
1404 lims.append(lim)
1404 lims.append(lim)
1405
1405
1406 # Trap output.
1406 # Trap output.
1407 stdout_trap = StringIO()
1407 stdout_trap = StringIO()
1408
1408
1409 if hasattr(stats,'stream'):
1409 if hasattr(stats,'stream'):
1410 # In newer versions of python, the stats object has a 'stream'
1410 # In newer versions of python, the stats object has a 'stream'
1411 # attribute to write into.
1411 # attribute to write into.
1412 stats.stream = stdout_trap
1412 stats.stream = stdout_trap
1413 stats.print_stats(*lims)
1413 stats.print_stats(*lims)
1414 else:
1414 else:
1415 # For older versions, we manually redirect stdout during printing
1415 # For older versions, we manually redirect stdout during printing
1416 sys_stdout = sys.stdout
1416 sys_stdout = sys.stdout
1417 try:
1417 try:
1418 sys.stdout = stdout_trap
1418 sys.stdout = stdout_trap
1419 stats.print_stats(*lims)
1419 stats.print_stats(*lims)
1420 finally:
1420 finally:
1421 sys.stdout = sys_stdout
1421 sys.stdout = sys_stdout
1422
1422
1423 output = stdout_trap.getvalue()
1423 output = stdout_trap.getvalue()
1424 output = output.rstrip()
1424 output = output.rstrip()
1425
1425
1426 page(output,screen_lines=self.shell.usable_screen_length)
1426 page(output,screen_lines=self.shell.usable_screen_length)
1427 print sys_exit,
1427 print sys_exit,
1428
1428
1429 dump_file = opts.D[0]
1429 dump_file = opts.D[0]
1430 text_file = opts.T[0]
1430 text_file = opts.T[0]
1431 if dump_file:
1431 if dump_file:
1432 prof.dump_stats(dump_file)
1432 prof.dump_stats(dump_file)
1433 print '\n*** Profile stats marshalled to file',\
1433 print '\n*** Profile stats marshalled to file',\
1434 `dump_file`+'.',sys_exit
1434 `dump_file`+'.',sys_exit
1435 if text_file:
1435 if text_file:
1436 pfile = file(text_file,'w')
1436 pfile = file(text_file,'w')
1437 pfile.write(output)
1437 pfile.write(output)
1438 pfile.close()
1438 pfile.close()
1439 print '\n*** Profile printout saved to text file',\
1439 print '\n*** Profile printout saved to text file',\
1440 `text_file`+'.',sys_exit
1440 `text_file`+'.',sys_exit
1441
1441
1442 if opts.has_key('r'):
1442 if opts.has_key('r'):
1443 return stats
1443 return stats
1444 else:
1444 else:
1445 return None
1445 return None
1446
1446
1447 @testdec.skip_doctest
1447 @testdec.skip_doctest
1448 def magic_run(self, parameter_s ='',runner=None,
1448 def magic_run(self, parameter_s ='',runner=None,
1449 file_finder=get_py_filename):
1449 file_finder=get_py_filename):
1450 """Run the named file inside IPython as a program.
1450 """Run the named file inside IPython as a program.
1451
1451
1452 Usage:\\
1452 Usage:\\
1453 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1453 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1454
1454
1455 Parameters after the filename are passed as command-line arguments to
1455 Parameters after the filename are passed as command-line arguments to
1456 the program (put in sys.argv). Then, control returns to IPython's
1456 the program (put in sys.argv). Then, control returns to IPython's
1457 prompt.
1457 prompt.
1458
1458
1459 This is similar to running at a system prompt:\\
1459 This is similar to running at a system prompt:\\
1460 $ python file args\\
1460 $ python file args\\
1461 but with the advantage of giving you IPython's tracebacks, and of
1461 but with the advantage of giving you IPython's tracebacks, and of
1462 loading all variables into your interactive namespace for further use
1462 loading all variables into your interactive namespace for further use
1463 (unless -p is used, see below).
1463 (unless -p is used, see below).
1464
1464
1465 The file is executed in a namespace initially consisting only of
1465 The file is executed in a namespace initially consisting only of
1466 __name__=='__main__' and sys.argv constructed as indicated. It thus
1466 __name__=='__main__' and sys.argv constructed as indicated. It thus
1467 sees its environment as if it were being run as a stand-alone program
1467 sees its environment as if it were being run as a stand-alone program
1468 (except for sharing global objects such as previously imported
1468 (except for sharing global objects such as previously imported
1469 modules). But after execution, the IPython interactive namespace gets
1469 modules). But after execution, the IPython interactive namespace gets
1470 updated with all variables defined in the program (except for __name__
1470 updated with all variables defined in the program (except for __name__
1471 and sys.argv). This allows for very convenient loading of code for
1471 and sys.argv). This allows for very convenient loading of code for
1472 interactive work, while giving each program a 'clean sheet' to run in.
1472 interactive work, while giving each program a 'clean sheet' to run in.
1473
1473
1474 Options:
1474 Options:
1475
1475
1476 -n: __name__ is NOT set to '__main__', but to the running file's name
1476 -n: __name__ is NOT set to '__main__', but to the running file's name
1477 without extension (as python does under import). This allows running
1477 without extension (as python does under import). This allows running
1478 scripts and reloading the definitions in them without calling code
1478 scripts and reloading the definitions in them without calling code
1479 protected by an ' if __name__ == "__main__" ' clause.
1479 protected by an ' if __name__ == "__main__" ' clause.
1480
1480
1481 -i: run the file in IPython's namespace instead of an empty one. This
1481 -i: run the file in IPython's namespace instead of an empty one. This
1482 is useful if you are experimenting with code written in a text editor
1482 is useful if you are experimenting with code written in a text editor
1483 which depends on variables defined interactively.
1483 which depends on variables defined interactively.
1484
1484
1485 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1485 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1486 being run. This is particularly useful if IPython is being used to
1486 being run. This is particularly useful if IPython is being used to
1487 run unittests, which always exit with a sys.exit() call. In such
1487 run unittests, which always exit with a sys.exit() call. In such
1488 cases you are interested in the output of the test results, not in
1488 cases you are interested in the output of the test results, not in
1489 seeing a traceback of the unittest module.
1489 seeing a traceback of the unittest module.
1490
1490
1491 -t: print timing information at the end of the run. IPython will give
1491 -t: print timing information at the end of the run. IPython will give
1492 you an estimated CPU time consumption for your script, which under
1492 you an estimated CPU time consumption for your script, which under
1493 Unix uses the resource module to avoid the wraparound problems of
1493 Unix uses the resource module to avoid the wraparound problems of
1494 time.clock(). Under Unix, an estimate of time spent on system tasks
1494 time.clock(). Under Unix, an estimate of time spent on system tasks
1495 is also given (for Windows platforms this is reported as 0.0).
1495 is also given (for Windows platforms this is reported as 0.0).
1496
1496
1497 If -t is given, an additional -N<N> option can be given, where <N>
1497 If -t is given, an additional -N<N> option can be given, where <N>
1498 must be an integer indicating how many times you want the script to
1498 must be an integer indicating how many times you want the script to
1499 run. The final timing report will include total and per run results.
1499 run. The final timing report will include total and per run results.
1500
1500
1501 For example (testing the script uniq_stable.py):
1501 For example (testing the script uniq_stable.py):
1502
1502
1503 In [1]: run -t uniq_stable
1503 In [1]: run -t uniq_stable
1504
1504
1505 IPython CPU timings (estimated):\\
1505 IPython CPU timings (estimated):\\
1506 User : 0.19597 s.\\
1506 User : 0.19597 s.\\
1507 System: 0.0 s.\\
1507 System: 0.0 s.\\
1508
1508
1509 In [2]: run -t -N5 uniq_stable
1509 In [2]: run -t -N5 uniq_stable
1510
1510
1511 IPython CPU timings (estimated):\\
1511 IPython CPU timings (estimated):\\
1512 Total runs performed: 5\\
1512 Total runs performed: 5\\
1513 Times : Total Per run\\
1513 Times : Total Per run\\
1514 User : 0.910862 s, 0.1821724 s.\\
1514 User : 0.910862 s, 0.1821724 s.\\
1515 System: 0.0 s, 0.0 s.
1515 System: 0.0 s, 0.0 s.
1516
1516
1517 -d: run your program under the control of pdb, the Python debugger.
1517 -d: run your program under the control of pdb, the Python debugger.
1518 This allows you to execute your program step by step, watch variables,
1518 This allows you to execute your program step by step, watch variables,
1519 etc. Internally, what IPython does is similar to calling:
1519 etc. Internally, what IPython does is similar to calling:
1520
1520
1521 pdb.run('execfile("YOURFILENAME")')
1521 pdb.run('execfile("YOURFILENAME")')
1522
1522
1523 with a breakpoint set on line 1 of your file. You can change the line
1523 with a breakpoint set on line 1 of your file. You can change the line
1524 number for this automatic breakpoint to be <N> by using the -bN option
1524 number for this automatic breakpoint to be <N> by using the -bN option
1525 (where N must be an integer). For example:
1525 (where N must be an integer). For example:
1526
1526
1527 %run -d -b40 myscript
1527 %run -d -b40 myscript
1528
1528
1529 will set the first breakpoint at line 40 in myscript.py. Note that
1529 will set the first breakpoint at line 40 in myscript.py. Note that
1530 the first breakpoint must be set on a line which actually does
1530 the first breakpoint must be set on a line which actually does
1531 something (not a comment or docstring) for it to stop execution.
1531 something (not a comment or docstring) for it to stop execution.
1532
1532
1533 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1533 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1534 first enter 'c' (without qoutes) to start execution up to the first
1534 first enter 'c' (without qoutes) to start execution up to the first
1535 breakpoint.
1535 breakpoint.
1536
1536
1537 Entering 'help' gives information about the use of the debugger. You
1537 Entering 'help' gives information about the use of the debugger. You
1538 can easily see pdb's full documentation with "import pdb;pdb.help()"
1538 can easily see pdb's full documentation with "import pdb;pdb.help()"
1539 at a prompt.
1539 at a prompt.
1540
1540
1541 -p: run program under the control of the Python profiler module (which
1541 -p: run program under the control of the Python profiler module (which
1542 prints a detailed report of execution times, function calls, etc).
1542 prints a detailed report of execution times, function calls, etc).
1543
1543
1544 You can pass other options after -p which affect the behavior of the
1544 You can pass other options after -p which affect the behavior of the
1545 profiler itself. See the docs for %prun for details.
1545 profiler itself. See the docs for %prun for details.
1546
1546
1547 In this mode, the program's variables do NOT propagate back to the
1547 In this mode, the program's variables do NOT propagate back to the
1548 IPython interactive namespace (because they remain in the namespace
1548 IPython interactive namespace (because they remain in the namespace
1549 where the profiler executes them).
1549 where the profiler executes them).
1550
1550
1551 Internally this triggers a call to %prun, see its documentation for
1551 Internally this triggers a call to %prun, see its documentation for
1552 details on the options available specifically for profiling.
1552 details on the options available specifically for profiling.
1553
1553
1554 There is one special usage for which the text above doesn't apply:
1554 There is one special usage for which the text above doesn't apply:
1555 if the filename ends with .ipy, the file is run as ipython script,
1555 if the filename ends with .ipy, the file is run as ipython script,
1556 just as if the commands were written on IPython prompt.
1556 just as if the commands were written on IPython prompt.
1557 """
1557 """
1558
1558
1559 # get arguments and set sys.argv for program to be run.
1559 # get arguments and set sys.argv for program to be run.
1560 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1560 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1561 mode='list',list_all=1)
1561 mode='list',list_all=1)
1562
1562
1563 try:
1563 try:
1564 filename = file_finder(arg_lst[0])
1564 filename = file_finder(arg_lst[0])
1565 except IndexError:
1565 except IndexError:
1566 warn('you must provide at least a filename.')
1566 warn('you must provide at least a filename.')
1567 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1567 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1568 return
1568 return
1569 except IOError,msg:
1569 except IOError,msg:
1570 error(msg)
1570 error(msg)
1571 return
1571 return
1572
1572
1573 if filename.lower().endswith('.ipy'):
1573 if filename.lower().endswith('.ipy'):
1574 self.safe_execfile_ipy(filename)
1574 self.safe_execfile_ipy(filename)
1575 return
1575 return
1576
1576
1577 # Control the response to exit() calls made by the script being run
1577 # Control the response to exit() calls made by the script being run
1578 exit_ignore = opts.has_key('e')
1578 exit_ignore = opts.has_key('e')
1579
1579
1580 # Make sure that the running script gets a proper sys.argv as if it
1580 # Make sure that the running script gets a proper sys.argv as if it
1581 # were run from a system shell.
1581 # were run from a system shell.
1582 save_argv = sys.argv # save it for later restoring
1582 save_argv = sys.argv # save it for later restoring
1583 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1583 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1584
1584
1585 if opts.has_key('i'):
1585 if opts.has_key('i'):
1586 # Run in user's interactive namespace
1586 # Run in user's interactive namespace
1587 prog_ns = self.shell.user_ns
1587 prog_ns = self.shell.user_ns
1588 __name__save = self.shell.user_ns['__name__']
1588 __name__save = self.shell.user_ns['__name__']
1589 prog_ns['__name__'] = '__main__'
1589 prog_ns['__name__'] = '__main__'
1590 main_mod = self.shell.new_main_mod(prog_ns)
1590 main_mod = self.shell.new_main_mod(prog_ns)
1591 else:
1591 else:
1592 # Run in a fresh, empty namespace
1592 # Run in a fresh, empty namespace
1593 if opts.has_key('n'):
1593 if opts.has_key('n'):
1594 name = os.path.splitext(os.path.basename(filename))[0]
1594 name = os.path.splitext(os.path.basename(filename))[0]
1595 else:
1595 else:
1596 name = '__main__'
1596 name = '__main__'
1597
1597
1598 main_mod = self.shell.new_main_mod()
1598 main_mod = self.shell.new_main_mod()
1599 prog_ns = main_mod.__dict__
1599 prog_ns = main_mod.__dict__
1600 prog_ns['__name__'] = name
1600 prog_ns['__name__'] = name
1601
1601
1602 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1602 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1603 # set the __file__ global in the script's namespace
1603 # set the __file__ global in the script's namespace
1604 prog_ns['__file__'] = filename
1604 prog_ns['__file__'] = filename
1605
1605
1606 # pickle fix. See iplib for an explanation. But we need to make sure
1606 # pickle fix. See iplib for an explanation. But we need to make sure
1607 # that, if we overwrite __main__, we replace it at the end
1607 # that, if we overwrite __main__, we replace it at the end
1608 main_mod_name = prog_ns['__name__']
1608 main_mod_name = prog_ns['__name__']
1609
1609
1610 if main_mod_name == '__main__':
1610 if main_mod_name == '__main__':
1611 restore_main = sys.modules['__main__']
1611 restore_main = sys.modules['__main__']
1612 else:
1612 else:
1613 restore_main = False
1613 restore_main = False
1614
1614
1615 # This needs to be undone at the end to prevent holding references to
1615 # This needs to be undone at the end to prevent holding references to
1616 # every single object ever created.
1616 # every single object ever created.
1617 sys.modules[main_mod_name] = main_mod
1617 sys.modules[main_mod_name] = main_mod
1618
1618
1619 stats = None
1619 stats = None
1620 try:
1620 try:
1621 self.shell.savehist()
1621 self.shell.savehist()
1622
1622
1623 if opts.has_key('p'):
1623 if opts.has_key('p'):
1624 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1624 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1625 else:
1625 else:
1626 if opts.has_key('d'):
1626 if opts.has_key('d'):
1627 deb = debugger.Pdb(self.shell.colors)
1627 deb = debugger.Pdb(self.shell.colors)
1628 # reset Breakpoint state, which is moronically kept
1628 # reset Breakpoint state, which is moronically kept
1629 # in a class
1629 # in a class
1630 bdb.Breakpoint.next = 1
1630 bdb.Breakpoint.next = 1
1631 bdb.Breakpoint.bplist = {}
1631 bdb.Breakpoint.bplist = {}
1632 bdb.Breakpoint.bpbynumber = [None]
1632 bdb.Breakpoint.bpbynumber = [None]
1633 # Set an initial breakpoint to stop execution
1633 # Set an initial breakpoint to stop execution
1634 maxtries = 10
1634 maxtries = 10
1635 bp = int(opts.get('b',[1])[0])
1635 bp = int(opts.get('b',[1])[0])
1636 checkline = deb.checkline(filename,bp)
1636 checkline = deb.checkline(filename,bp)
1637 if not checkline:
1637 if not checkline:
1638 for bp in range(bp+1,bp+maxtries+1):
1638 for bp in range(bp+1,bp+maxtries+1):
1639 if deb.checkline(filename,bp):
1639 if deb.checkline(filename,bp):
1640 break
1640 break
1641 else:
1641 else:
1642 msg = ("\nI failed to find a valid line to set "
1642 msg = ("\nI failed to find a valid line to set "
1643 "a breakpoint\n"
1643 "a breakpoint\n"
1644 "after trying up to line: %s.\n"
1644 "after trying up to line: %s.\n"
1645 "Please set a valid breakpoint manually "
1645 "Please set a valid breakpoint manually "
1646 "with the -b option." % bp)
1646 "with the -b option." % bp)
1647 error(msg)
1647 error(msg)
1648 return
1648 return
1649 # if we find a good linenumber, set the breakpoint
1649 # if we find a good linenumber, set the breakpoint
1650 deb.do_break('%s:%s' % (filename,bp))
1650 deb.do_break('%s:%s' % (filename,bp))
1651 # Start file run
1651 # Start file run
1652 print "NOTE: Enter 'c' at the",
1652 print "NOTE: Enter 'c' at the",
1653 print "%s prompt to start your script." % deb.prompt
1653 print "%s prompt to start your script." % deb.prompt
1654 try:
1654 try:
1655 deb.run('execfile("%s")' % filename,prog_ns)
1655 deb.run('execfile("%s")' % filename,prog_ns)
1656
1656
1657 except:
1657 except:
1658 etype, value, tb = sys.exc_info()
1658 etype, value, tb = sys.exc_info()
1659 # Skip three frames in the traceback: the %run one,
1659 # Skip three frames in the traceback: the %run one,
1660 # one inside bdb.py, and the command-line typed by the
1660 # one inside bdb.py, and the command-line typed by the
1661 # user (run by exec in pdb itself).
1661 # user (run by exec in pdb itself).
1662 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1662 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1663 else:
1663 else:
1664 if runner is None:
1664 if runner is None:
1665 runner = self.shell.safe_execfile
1665 runner = self.shell.safe_execfile
1666 if opts.has_key('t'):
1666 if opts.has_key('t'):
1667 # timed execution
1667 # timed execution
1668 try:
1668 try:
1669 nruns = int(opts['N'][0])
1669 nruns = int(opts['N'][0])
1670 if nruns < 1:
1670 if nruns < 1:
1671 error('Number of runs must be >=1')
1671 error('Number of runs must be >=1')
1672 return
1672 return
1673 except (KeyError):
1673 except (KeyError):
1674 nruns = 1
1674 nruns = 1
1675 if nruns == 1:
1675 if nruns == 1:
1676 t0 = clock2()
1676 t0 = clock2()
1677 runner(filename,prog_ns,prog_ns,
1677 runner(filename,prog_ns,prog_ns,
1678 exit_ignore=exit_ignore)
1678 exit_ignore=exit_ignore)
1679 t1 = clock2()
1679 t1 = clock2()
1680 t_usr = t1[0]-t0[0]
1680 t_usr = t1[0]-t0[0]
1681 t_sys = t1[1]-t0[1]
1681 t_sys = t1[1]-t0[1]
1682 print "\nIPython CPU timings (estimated):"
1682 print "\nIPython CPU timings (estimated):"
1683 print " User : %10s s." % t_usr
1683 print " User : %10s s." % t_usr
1684 print " System: %10s s." % t_sys
1684 print " System: %10s s." % t_sys
1685 else:
1685 else:
1686 runs = range(nruns)
1686 runs = range(nruns)
1687 t0 = clock2()
1687 t0 = clock2()
1688 for nr in runs:
1688 for nr in runs:
1689 runner(filename,prog_ns,prog_ns,
1689 runner(filename,prog_ns,prog_ns,
1690 exit_ignore=exit_ignore)
1690 exit_ignore=exit_ignore)
1691 t1 = clock2()
1691 t1 = clock2()
1692 t_usr = t1[0]-t0[0]
1692 t_usr = t1[0]-t0[0]
1693 t_sys = t1[1]-t0[1]
1693 t_sys = t1[1]-t0[1]
1694 print "\nIPython CPU timings (estimated):"
1694 print "\nIPython CPU timings (estimated):"
1695 print "Total runs performed:",nruns
1695 print "Total runs performed:",nruns
1696 print " Times : %10s %10s" % ('Total','Per run')
1696 print " Times : %10s %10s" % ('Total','Per run')
1697 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1697 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1698 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1698 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1699
1699
1700 else:
1700 else:
1701 # regular execution
1701 # regular execution
1702 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1702 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1703
1703
1704 if opts.has_key('i'):
1704 if opts.has_key('i'):
1705 self.shell.user_ns['__name__'] = __name__save
1705 self.shell.user_ns['__name__'] = __name__save
1706 else:
1706 else:
1707 # The shell MUST hold a reference to prog_ns so after %run
1707 # The shell MUST hold a reference to prog_ns so after %run
1708 # exits, the python deletion mechanism doesn't zero it out
1708 # exits, the python deletion mechanism doesn't zero it out
1709 # (leaving dangling references).
1709 # (leaving dangling references).
1710 self.shell.cache_main_mod(prog_ns,filename)
1710 self.shell.cache_main_mod(prog_ns,filename)
1711 # update IPython interactive namespace
1711 # update IPython interactive namespace
1712
1712
1713 # Some forms of read errors on the file may mean the
1713 # Some forms of read errors on the file may mean the
1714 # __name__ key was never set; using pop we don't have to
1714 # __name__ key was never set; using pop we don't have to
1715 # worry about a possible KeyError.
1715 # worry about a possible KeyError.
1716 prog_ns.pop('__name__', None)
1716 prog_ns.pop('__name__', None)
1717
1717
1718 self.shell.user_ns.update(prog_ns)
1718 self.shell.user_ns.update(prog_ns)
1719 finally:
1719 finally:
1720 # It's a bit of a mystery why, but __builtins__ can change from
1720 # It's a bit of a mystery why, but __builtins__ can change from
1721 # being a module to becoming a dict missing some key data after
1721 # being a module to becoming a dict missing some key data after
1722 # %run. As best I can see, this is NOT something IPython is doing
1722 # %run. As best I can see, this is NOT something IPython is doing
1723 # at all, and similar problems have been reported before:
1723 # at all, and similar problems have been reported before:
1724 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1724 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1725 # Since this seems to be done by the interpreter itself, the best
1725 # Since this seems to be done by the interpreter itself, the best
1726 # we can do is to at least restore __builtins__ for the user on
1726 # we can do is to at least restore __builtins__ for the user on
1727 # exit.
1727 # exit.
1728 self.shell.user_ns['__builtins__'] = __builtin__
1728 self.shell.user_ns['__builtins__'] = __builtin__
1729
1729
1730 # Ensure key global structures are restored
1730 # Ensure key global structures are restored
1731 sys.argv = save_argv
1731 sys.argv = save_argv
1732 if restore_main:
1732 if restore_main:
1733 sys.modules['__main__'] = restore_main
1733 sys.modules['__main__'] = restore_main
1734 else:
1734 else:
1735 # Remove from sys.modules the reference to main_mod we'd
1735 # Remove from sys.modules the reference to main_mod we'd
1736 # added. Otherwise it will trap references to objects
1736 # added. Otherwise it will trap references to objects
1737 # contained therein.
1737 # contained therein.
1738 del sys.modules[main_mod_name]
1738 del sys.modules[main_mod_name]
1739
1739
1740 self.shell.reloadhist()
1740 self.shell.reloadhist()
1741
1741
1742 return stats
1742 return stats
1743
1743
1744 @testdec.skip_doctest
1744 @testdec.skip_doctest
1745 def magic_timeit(self, parameter_s =''):
1745 def magic_timeit(self, parameter_s =''):
1746 """Time execution of a Python statement or expression
1746 """Time execution of a Python statement or expression
1747
1747
1748 Usage:\\
1748 Usage:\\
1749 %timeit [-n<N> -r<R> [-t|-c]] statement
1749 %timeit [-n<N> -r<R> [-t|-c]] statement
1750
1750
1751 Time execution of a Python statement or expression using the timeit
1751 Time execution of a Python statement or expression using the timeit
1752 module.
1752 module.
1753
1753
1754 Options:
1754 Options:
1755 -n<N>: execute the given statement <N> times in a loop. If this value
1755 -n<N>: execute the given statement <N> times in a loop. If this value
1756 is not given, a fitting value is chosen.
1756 is not given, a fitting value is chosen.
1757
1757
1758 -r<R>: repeat the loop iteration <R> times and take the best result.
1758 -r<R>: repeat the loop iteration <R> times and take the best result.
1759 Default: 3
1759 Default: 3
1760
1760
1761 -t: use time.time to measure the time, which is the default on Unix.
1761 -t: use time.time to measure the time, which is the default on Unix.
1762 This function measures wall time.
1762 This function measures wall time.
1763
1763
1764 -c: use time.clock to measure the time, which is the default on
1764 -c: use time.clock to measure the time, which is the default on
1765 Windows and measures wall time. On Unix, resource.getrusage is used
1765 Windows and measures wall time. On Unix, resource.getrusage is used
1766 instead and returns the CPU user time.
1766 instead and returns the CPU user time.
1767
1767
1768 -p<P>: use a precision of <P> digits to display the timing result.
1768 -p<P>: use a precision of <P> digits to display the timing result.
1769 Default: 3
1769 Default: 3
1770
1770
1771
1771
1772 Examples:
1772 Examples:
1773
1773
1774 In [1]: %timeit pass
1774 In [1]: %timeit pass
1775 10000000 loops, best of 3: 53.3 ns per loop
1775 10000000 loops, best of 3: 53.3 ns per loop
1776
1776
1777 In [2]: u = None
1777 In [2]: u = None
1778
1778
1779 In [3]: %timeit u is None
1779 In [3]: %timeit u is None
1780 10000000 loops, best of 3: 184 ns per loop
1780 10000000 loops, best of 3: 184 ns per loop
1781
1781
1782 In [4]: %timeit -r 4 u == None
1782 In [4]: %timeit -r 4 u == None
1783 1000000 loops, best of 4: 242 ns per loop
1783 1000000 loops, best of 4: 242 ns per loop
1784
1784
1785 In [5]: import time
1785 In [5]: import time
1786
1786
1787 In [6]: %timeit -n1 time.sleep(2)
1787 In [6]: %timeit -n1 time.sleep(2)
1788 1 loops, best of 3: 2 s per loop
1788 1 loops, best of 3: 2 s per loop
1789
1789
1790
1790
1791 The times reported by %timeit will be slightly higher than those
1791 The times reported by %timeit will be slightly higher than those
1792 reported by the timeit.py script when variables are accessed. This is
1792 reported by the timeit.py script when variables are accessed. This is
1793 due to the fact that %timeit executes the statement in the namespace
1793 due to the fact that %timeit executes the statement in the namespace
1794 of the shell, compared with timeit.py, which uses a single setup
1794 of the shell, compared with timeit.py, which uses a single setup
1795 statement to import function or create variables. Generally, the bias
1795 statement to import function or create variables. Generally, the bias
1796 does not matter as long as results from timeit.py are not mixed with
1796 does not matter as long as results from timeit.py are not mixed with
1797 those from %timeit."""
1797 those from %timeit."""
1798
1798
1799 import timeit
1799 import timeit
1800 import math
1800 import math
1801
1801
1802 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1802 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1803 # certain terminals. Until we figure out a robust way of
1803 # certain terminals. Until we figure out a robust way of
1804 # auto-detecting if the terminal can deal with it, use plain 'us' for
1804 # auto-detecting if the terminal can deal with it, use plain 'us' for
1805 # microseconds. I am really NOT happy about disabling the proper
1805 # microseconds. I am really NOT happy about disabling the proper
1806 # 'micro' prefix, but crashing is worse... If anyone knows what the
1806 # 'micro' prefix, but crashing is worse... If anyone knows what the
1807 # right solution for this is, I'm all ears...
1807 # right solution for this is, I'm all ears...
1808 #
1808 #
1809 # Note: using
1809 # Note: using
1810 #
1810 #
1811 # s = u'\xb5'
1811 # s = u'\xb5'
1812 # s.encode(sys.getdefaultencoding())
1812 # s.encode(sys.getdefaultencoding())
1813 #
1813 #
1814 # is not sufficient, as I've seen terminals where that fails but
1814 # is not sufficient, as I've seen terminals where that fails but
1815 # print s
1815 # print s
1816 #
1816 #
1817 # succeeds
1817 # succeeds
1818 #
1818 #
1819 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1819 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1820
1820
1821 #units = [u"s", u"ms",u'\xb5',"ns"]
1821 #units = [u"s", u"ms",u'\xb5',"ns"]
1822 units = [u"s", u"ms",u'us',"ns"]
1822 units = [u"s", u"ms",u'us',"ns"]
1823
1823
1824 scaling = [1, 1e3, 1e6, 1e9]
1824 scaling = [1, 1e3, 1e6, 1e9]
1825
1825
1826 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1826 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1827 posix=False)
1827 posix=False)
1828 if stmt == "":
1828 if stmt == "":
1829 return
1829 return
1830 timefunc = timeit.default_timer
1830 timefunc = timeit.default_timer
1831 number = int(getattr(opts, "n", 0))
1831 number = int(getattr(opts, "n", 0))
1832 repeat = int(getattr(opts, "r", timeit.default_repeat))
1832 repeat = int(getattr(opts, "r", timeit.default_repeat))
1833 precision = int(getattr(opts, "p", 3))
1833 precision = int(getattr(opts, "p", 3))
1834 if hasattr(opts, "t"):
1834 if hasattr(opts, "t"):
1835 timefunc = time.time
1835 timefunc = time.time
1836 if hasattr(opts, "c"):
1836 if hasattr(opts, "c"):
1837 timefunc = clock
1837 timefunc = clock
1838
1838
1839 timer = timeit.Timer(timer=timefunc)
1839 timer = timeit.Timer(timer=timefunc)
1840 # this code has tight coupling to the inner workings of timeit.Timer,
1840 # this code has tight coupling to the inner workings of timeit.Timer,
1841 # but is there a better way to achieve that the code stmt has access
1841 # but is there a better way to achieve that the code stmt has access
1842 # to the shell namespace?
1842 # to the shell namespace?
1843
1843
1844 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1844 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1845 'setup': "pass"}
1845 'setup': "pass"}
1846 # Track compilation time so it can be reported if too long
1846 # Track compilation time so it can be reported if too long
1847 # Minimum time above which compilation time will be reported
1847 # Minimum time above which compilation time will be reported
1848 tc_min = 0.1
1848 tc_min = 0.1
1849
1849
1850 t0 = clock()
1850 t0 = clock()
1851 code = compile(src, "<magic-timeit>", "exec")
1851 code = compile(src, "<magic-timeit>", "exec")
1852 tc = clock()-t0
1852 tc = clock()-t0
1853
1853
1854 ns = {}
1854 ns = {}
1855 exec code in self.shell.user_ns, ns
1855 exec code in self.shell.user_ns, ns
1856 timer.inner = ns["inner"]
1856 timer.inner = ns["inner"]
1857
1857
1858 if number == 0:
1858 if number == 0:
1859 # determine number so that 0.2 <= total time < 2.0
1859 # determine number so that 0.2 <= total time < 2.0
1860 number = 1
1860 number = 1
1861 for i in range(1, 10):
1861 for i in range(1, 10):
1862 if timer.timeit(number) >= 0.2:
1862 if timer.timeit(number) >= 0.2:
1863 break
1863 break
1864 number *= 10
1864 number *= 10
1865
1865
1866 best = min(timer.repeat(repeat, number)) / number
1866 best = min(timer.repeat(repeat, number)) / number
1867
1867
1868 if best > 0.0:
1868 if best > 0.0:
1869 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1869 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1870 else:
1870 else:
1871 order = 3
1871 order = 3
1872 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1872 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1873 precision,
1873 precision,
1874 best * scaling[order],
1874 best * scaling[order],
1875 units[order])
1875 units[order])
1876 if tc > tc_min:
1876 if tc > tc_min:
1877 print "Compiler time: %.2f s" % tc
1877 print "Compiler time: %.2f s" % tc
1878
1878
1879 @testdec.skip_doctest
1879 @testdec.skip_doctest
1880 def magic_time(self,parameter_s = ''):
1880 def magic_time(self,parameter_s = ''):
1881 """Time execution of a Python statement or expression.
1881 """Time execution of a Python statement or expression.
1882
1882
1883 The CPU and wall clock times are printed, and the value of the
1883 The CPU and wall clock times are printed, and the value of the
1884 expression (if any) is returned. Note that under Win32, system time
1884 expression (if any) is returned. Note that under Win32, system time
1885 is always reported as 0, since it can not be measured.
1885 is always reported as 0, since it can not be measured.
1886
1886
1887 This function provides very basic timing functionality. In Python
1887 This function provides very basic timing functionality. In Python
1888 2.3, the timeit module offers more control and sophistication, so this
1888 2.3, the timeit module offers more control and sophistication, so this
1889 could be rewritten to use it (patches welcome).
1889 could be rewritten to use it (patches welcome).
1890
1890
1891 Some examples:
1891 Some examples:
1892
1892
1893 In [1]: time 2**128
1893 In [1]: time 2**128
1894 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1894 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1895 Wall time: 0.00
1895 Wall time: 0.00
1896 Out[1]: 340282366920938463463374607431768211456L
1896 Out[1]: 340282366920938463463374607431768211456L
1897
1897
1898 In [2]: n = 1000000
1898 In [2]: n = 1000000
1899
1899
1900 In [3]: time sum(range(n))
1900 In [3]: time sum(range(n))
1901 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1901 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1902 Wall time: 1.37
1902 Wall time: 1.37
1903 Out[3]: 499999500000L
1903 Out[3]: 499999500000L
1904
1904
1905 In [4]: time print 'hello world'
1905 In [4]: time print 'hello world'
1906 hello world
1906 hello world
1907 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1907 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1908 Wall time: 0.00
1908 Wall time: 0.00
1909
1909
1910 Note that the time needed by Python to compile the given expression
1910 Note that the time needed by Python to compile the given expression
1911 will be reported if it is more than 0.1s. In this example, the
1911 will be reported if it is more than 0.1s. In this example, the
1912 actual exponentiation is done by Python at compilation time, so while
1912 actual exponentiation is done by Python at compilation time, so while
1913 the expression can take a noticeable amount of time to compute, that
1913 the expression can take a noticeable amount of time to compute, that
1914 time is purely due to the compilation:
1914 time is purely due to the compilation:
1915
1915
1916 In [5]: time 3**9999;
1916 In [5]: time 3**9999;
1917 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1917 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1918 Wall time: 0.00 s
1918 Wall time: 0.00 s
1919
1919
1920 In [6]: time 3**999999;
1920 In [6]: time 3**999999;
1921 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1921 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1922 Wall time: 0.00 s
1922 Wall time: 0.00 s
1923 Compiler : 0.78 s
1923 Compiler : 0.78 s
1924 """
1924 """
1925
1925
1926 # fail immediately if the given expression can't be compiled
1926 # fail immediately if the given expression can't be compiled
1927
1927
1928 expr = self.shell.prefilter(parameter_s,False)
1928 expr = self.shell.prefilter(parameter_s,False)
1929
1929
1930 # Minimum time above which compilation time will be reported
1930 # Minimum time above which compilation time will be reported
1931 tc_min = 0.1
1931 tc_min = 0.1
1932
1932
1933 try:
1933 try:
1934 mode = 'eval'
1934 mode = 'eval'
1935 t0 = clock()
1935 t0 = clock()
1936 code = compile(expr,'<timed eval>',mode)
1936 code = compile(expr,'<timed eval>',mode)
1937 tc = clock()-t0
1937 tc = clock()-t0
1938 except SyntaxError:
1938 except SyntaxError:
1939 mode = 'exec'
1939 mode = 'exec'
1940 t0 = clock()
1940 t0 = clock()
1941 code = compile(expr,'<timed exec>',mode)
1941 code = compile(expr,'<timed exec>',mode)
1942 tc = clock()-t0
1942 tc = clock()-t0
1943 # skew measurement as little as possible
1943 # skew measurement as little as possible
1944 glob = self.shell.user_ns
1944 glob = self.shell.user_ns
1945 clk = clock2
1945 clk = clock2
1946 wtime = time.time
1946 wtime = time.time
1947 # time execution
1947 # time execution
1948 wall_st = wtime()
1948 wall_st = wtime()
1949 if mode=='eval':
1949 if mode=='eval':
1950 st = clk()
1950 st = clk()
1951 out = eval(code,glob)
1951 out = eval(code,glob)
1952 end = clk()
1952 end = clk()
1953 else:
1953 else:
1954 st = clk()
1954 st = clk()
1955 exec code in glob
1955 exec code in glob
1956 end = clk()
1956 end = clk()
1957 out = None
1957 out = None
1958 wall_end = wtime()
1958 wall_end = wtime()
1959 # Compute actual times and report
1959 # Compute actual times and report
1960 wall_time = wall_end-wall_st
1960 wall_time = wall_end-wall_st
1961 cpu_user = end[0]-st[0]
1961 cpu_user = end[0]-st[0]
1962 cpu_sys = end[1]-st[1]
1962 cpu_sys = end[1]-st[1]
1963 cpu_tot = cpu_user+cpu_sys
1963 cpu_tot = cpu_user+cpu_sys
1964 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1964 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1965 (cpu_user,cpu_sys,cpu_tot)
1965 (cpu_user,cpu_sys,cpu_tot)
1966 print "Wall time: %.2f s" % wall_time
1966 print "Wall time: %.2f s" % wall_time
1967 if tc > tc_min:
1967 if tc > tc_min:
1968 print "Compiler : %.2f s" % tc
1968 print "Compiler : %.2f s" % tc
1969 return out
1969 return out
1970
1970
1971 @testdec.skip_doctest
1971 @testdec.skip_doctest
1972 def magic_macro(self,parameter_s = ''):
1972 def magic_macro(self,parameter_s = ''):
1973 """Define a set of input lines as a macro for future re-execution.
1973 """Define a set of input lines as a macro for future re-execution.
1974
1974
1975 Usage:\\
1975 Usage:\\
1976 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1976 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1977
1977
1978 Options:
1978 Options:
1979
1979
1980 -r: use 'raw' input. By default, the 'processed' history is used,
1980 -r: use 'raw' input. By default, the 'processed' history is used,
1981 so that magics are loaded in their transformed version to valid
1981 so that magics are loaded in their transformed version to valid
1982 Python. If this option is given, the raw input as typed as the
1982 Python. If this option is given, the raw input as typed as the
1983 command line is used instead.
1983 command line is used instead.
1984
1984
1985 This will define a global variable called `name` which is a string
1985 This will define a global variable called `name` which is a string
1986 made of joining the slices and lines you specify (n1,n2,... numbers
1986 made of joining the slices and lines you specify (n1,n2,... numbers
1987 above) from your input history into a single string. This variable
1987 above) from your input history into a single string. This variable
1988 acts like an automatic function which re-executes those lines as if
1988 acts like an automatic function which re-executes those lines as if
1989 you had typed them. You just type 'name' at the prompt and the code
1989 you had typed them. You just type 'name' at the prompt and the code
1990 executes.
1990 executes.
1991
1991
1992 The notation for indicating number ranges is: n1-n2 means 'use line
1992 The notation for indicating number ranges is: n1-n2 means 'use line
1993 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1993 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1994 using the lines numbered 5,6 and 7.
1994 using the lines numbered 5,6 and 7.
1995
1995
1996 Note: as a 'hidden' feature, you can also use traditional python slice
1996 Note: as a 'hidden' feature, you can also use traditional python slice
1997 notation, where N:M means numbers N through M-1.
1997 notation, where N:M means numbers N through M-1.
1998
1998
1999 For example, if your history contains (%hist prints it):
1999 For example, if your history contains (%hist prints it):
2000
2000
2001 44: x=1
2001 44: x=1
2002 45: y=3
2002 45: y=3
2003 46: z=x+y
2003 46: z=x+y
2004 47: print x
2004 47: print x
2005 48: a=5
2005 48: a=5
2006 49: print 'x',x,'y',y
2006 49: print 'x',x,'y',y
2007
2007
2008 you can create a macro with lines 44 through 47 (included) and line 49
2008 you can create a macro with lines 44 through 47 (included) and line 49
2009 called my_macro with:
2009 called my_macro with:
2010
2010
2011 In [55]: %macro my_macro 44-47 49
2011 In [55]: %macro my_macro 44-47 49
2012
2012
2013 Now, typing `my_macro` (without quotes) will re-execute all this code
2013 Now, typing `my_macro` (without quotes) will re-execute all this code
2014 in one pass.
2014 in one pass.
2015
2015
2016 You don't need to give the line-numbers in order, and any given line
2016 You don't need to give the line-numbers in order, and any given line
2017 number can appear multiple times. You can assemble macros with any
2017 number can appear multiple times. You can assemble macros with any
2018 lines from your input history in any order.
2018 lines from your input history in any order.
2019
2019
2020 The macro is a simple object which holds its value in an attribute,
2020 The macro is a simple object which holds its value in an attribute,
2021 but IPython's display system checks for macros and executes them as
2021 but IPython's display system checks for macros and executes them as
2022 code instead of printing them when you type their name.
2022 code instead of printing them when you type their name.
2023
2023
2024 You can view a macro's contents by explicitly printing it with:
2024 You can view a macro's contents by explicitly printing it with:
2025
2025
2026 'print macro_name'.
2026 'print macro_name'.
2027
2027
2028 For one-off cases which DON'T contain magic function calls in them you
2028 For one-off cases which DON'T contain magic function calls in them you
2029 can obtain similar results by explicitly executing slices from your
2029 can obtain similar results by explicitly executing slices from your
2030 input history with:
2030 input history with:
2031
2031
2032 In [60]: exec In[44:48]+In[49]"""
2032 In [60]: exec In[44:48]+In[49]"""
2033
2033
2034 opts,args = self.parse_options(parameter_s,'r',mode='list')
2034 opts,args = self.parse_options(parameter_s,'r',mode='list')
2035 if not args:
2035 if not args:
2036 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2036 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2037 macs.sort()
2037 macs.sort()
2038 return macs
2038 return macs
2039 if len(args) == 1:
2039 if len(args) == 1:
2040 raise UsageError(
2040 raise UsageError(
2041 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2041 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2042 name,ranges = args[0], args[1:]
2042 name,ranges = args[0], args[1:]
2043
2043
2044 #print 'rng',ranges # dbg
2044 #print 'rng',ranges # dbg
2045 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2045 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2046 macro = Macro(lines)
2046 macro = Macro(lines)
2047 self.shell.define_macro(name, macro)
2047 self.shell.define_macro(name, macro)
2048 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2048 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2049 print 'Macro contents:'
2049 print 'Macro contents:'
2050 print macro,
2050 print macro,
2051
2051
2052 def magic_save(self,parameter_s = ''):
2052 def magic_save(self,parameter_s = ''):
2053 """Save a set of lines to a given filename.
2053 """Save a set of lines to a given filename.
2054
2054
2055 Usage:\\
2055 Usage:\\
2056 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2056 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2057
2057
2058 Options:
2058 Options:
2059
2059
2060 -r: use 'raw' input. By default, the 'processed' history is used,
2060 -r: use 'raw' input. By default, the 'processed' history is used,
2061 so that magics are loaded in their transformed version to valid
2061 so that magics are loaded in their transformed version to valid
2062 Python. If this option is given, the raw input as typed as the
2062 Python. If this option is given, the raw input as typed as the
2063 command line is used instead.
2063 command line is used instead.
2064
2064
2065 This function uses the same syntax as %macro for line extraction, but
2065 This function uses the same syntax as %macro for line extraction, but
2066 instead of creating a macro it saves the resulting string to the
2066 instead of creating a macro it saves the resulting string to the
2067 filename you specify.
2067 filename you specify.
2068
2068
2069 It adds a '.py' extension to the file if you don't do so yourself, and
2069 It adds a '.py' extension to the file if you don't do so yourself, and
2070 it asks for confirmation before overwriting existing files."""
2070 it asks for confirmation before overwriting existing files."""
2071
2071
2072 opts,args = self.parse_options(parameter_s,'r',mode='list')
2072 opts,args = self.parse_options(parameter_s,'r',mode='list')
2073 fname,ranges = args[0], args[1:]
2073 fname,ranges = args[0], args[1:]
2074 if not fname.endswith('.py'):
2074 if not fname.endswith('.py'):
2075 fname += '.py'
2075 fname += '.py'
2076 if os.path.isfile(fname):
2076 if os.path.isfile(fname):
2077 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2077 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2078 if ans.lower() not in ['y','yes']:
2078 if ans.lower() not in ['y','yes']:
2079 print 'Operation cancelled.'
2079 print 'Operation cancelled.'
2080 return
2080 return
2081 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2081 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2082 f = file(fname,'w')
2082 f = file(fname,'w')
2083 f.write(cmds)
2083 f.write(cmds)
2084 f.close()
2084 f.close()
2085 print 'The following commands were written to file `%s`:' % fname
2085 print 'The following commands were written to file `%s`:' % fname
2086 print cmds
2086 print cmds
2087
2087
2088 def _edit_macro(self,mname,macro):
2088 def _edit_macro(self,mname,macro):
2089 """open an editor with the macro data in a file"""
2089 """open an editor with the macro data in a file"""
2090 filename = self.shell.mktempfile(macro.value)
2090 filename = self.shell.mktempfile(macro.value)
2091 self.shell.hooks.editor(filename)
2091 self.shell.hooks.editor(filename)
2092
2092
2093 # and make a new macro object, to replace the old one
2093 # and make a new macro object, to replace the old one
2094 mfile = open(filename)
2094 mfile = open(filename)
2095 mvalue = mfile.read()
2095 mvalue = mfile.read()
2096 mfile.close()
2096 mfile.close()
2097 self.shell.user_ns[mname] = Macro(mvalue)
2097 self.shell.user_ns[mname] = Macro(mvalue)
2098
2098
2099 def magic_ed(self,parameter_s=''):
2099 def magic_ed(self,parameter_s=''):
2100 """Alias to %edit."""
2100 """Alias to %edit."""
2101 return self.magic_edit(parameter_s)
2101 return self.magic_edit(parameter_s)
2102
2102
2103 @testdec.skip_doctest
2103 @testdec.skip_doctest
2104 def magic_edit(self,parameter_s='',last_call=['','']):
2104 def magic_edit(self,parameter_s='',last_call=['','']):
2105 """Bring up an editor and execute the resulting code.
2105 """Bring up an editor and execute the resulting code.
2106
2106
2107 Usage:
2107 Usage:
2108 %edit [options] [args]
2108 %edit [options] [args]
2109
2109
2110 %edit runs IPython's editor hook. The default version of this hook is
2110 %edit runs IPython's editor hook. The default version of this hook is
2111 set to call the __IPYTHON__.rc.editor command. This is read from your
2111 set to call the __IPYTHON__.rc.editor command. This is read from your
2112 environment variable $EDITOR. If this isn't found, it will default to
2112 environment variable $EDITOR. If this isn't found, it will default to
2113 vi under Linux/Unix and to notepad under Windows. See the end of this
2113 vi under Linux/Unix and to notepad under Windows. See the end of this
2114 docstring for how to change the editor hook.
2114 docstring for how to change the editor hook.
2115
2115
2116 You can also set the value of this editor via the command line option
2116 You can also set the value of this editor via the command line option
2117 '-editor' or in your ipythonrc file. This is useful if you wish to use
2117 '-editor' or in your ipythonrc file. This is useful if you wish to use
2118 specifically for IPython an editor different from your typical default
2118 specifically for IPython an editor different from your typical default
2119 (and for Windows users who typically don't set environment variables).
2119 (and for Windows users who typically don't set environment variables).
2120
2120
2121 This command allows you to conveniently edit multi-line code right in
2121 This command allows you to conveniently edit multi-line code right in
2122 your IPython session.
2122 your IPython session.
2123
2123
2124 If called without arguments, %edit opens up an empty editor with a
2124 If called without arguments, %edit opens up an empty editor with a
2125 temporary file and will execute the contents of this file when you
2125 temporary file and will execute the contents of this file when you
2126 close it (don't forget to save it!).
2126 close it (don't forget to save it!).
2127
2127
2128
2128
2129 Options:
2129 Options:
2130
2130
2131 -n <number>: open the editor at a specified line number. By default,
2131 -n <number>: open the editor at a specified line number. By default,
2132 the IPython editor hook uses the unix syntax 'editor +N filename', but
2132 the IPython editor hook uses the unix syntax 'editor +N filename', but
2133 you can configure this by providing your own modified hook if your
2133 you can configure this by providing your own modified hook if your
2134 favorite editor supports line-number specifications with a different
2134 favorite editor supports line-number specifications with a different
2135 syntax.
2135 syntax.
2136
2136
2137 -p: this will call the editor with the same data as the previous time
2137 -p: this will call the editor with the same data as the previous time
2138 it was used, regardless of how long ago (in your current session) it
2138 it was used, regardless of how long ago (in your current session) it
2139 was.
2139 was.
2140
2140
2141 -r: use 'raw' input. This option only applies to input taken from the
2141 -r: use 'raw' input. This option only applies to input taken from the
2142 user's history. By default, the 'processed' history is used, so that
2142 user's history. By default, the 'processed' history is used, so that
2143 magics are loaded in their transformed version to valid Python. If
2143 magics are loaded in their transformed version to valid Python. If
2144 this option is given, the raw input as typed as the command line is
2144 this option is given, the raw input as typed as the command line is
2145 used instead. When you exit the editor, it will be executed by
2145 used instead. When you exit the editor, it will be executed by
2146 IPython's own processor.
2146 IPython's own processor.
2147
2147
2148 -x: do not execute the edited code immediately upon exit. This is
2148 -x: do not execute the edited code immediately upon exit. This is
2149 mainly useful if you are editing programs which need to be called with
2149 mainly useful if you are editing programs which need to be called with
2150 command line arguments, which you can then do using %run.
2150 command line arguments, which you can then do using %run.
2151
2151
2152
2152
2153 Arguments:
2153 Arguments:
2154
2154
2155 If arguments are given, the following possibilites exist:
2155 If arguments are given, the following possibilites exist:
2156
2156
2157 - The arguments are numbers or pairs of colon-separated numbers (like
2157 - The arguments are numbers or pairs of colon-separated numbers (like
2158 1 4:8 9). These are interpreted as lines of previous input to be
2158 1 4:8 9). These are interpreted as lines of previous input to be
2159 loaded into the editor. The syntax is the same of the %macro command.
2159 loaded into the editor. The syntax is the same of the %macro command.
2160
2160
2161 - If the argument doesn't start with a number, it is evaluated as a
2161 - If the argument doesn't start with a number, it is evaluated as a
2162 variable and its contents loaded into the editor. You can thus edit
2162 variable and its contents loaded into the editor. You can thus edit
2163 any string which contains python code (including the result of
2163 any string which contains python code (including the result of
2164 previous edits).
2164 previous edits).
2165
2165
2166 - If the argument is the name of an object (other than a string),
2166 - If the argument is the name of an object (other than a string),
2167 IPython will try to locate the file where it was defined and open the
2167 IPython will try to locate the file where it was defined and open the
2168 editor at the point where it is defined. You can use `%edit function`
2168 editor at the point where it is defined. You can use `%edit function`
2169 to load an editor exactly at the point where 'function' is defined,
2169 to load an editor exactly at the point where 'function' is defined,
2170 edit it and have the file be executed automatically.
2170 edit it and have the file be executed automatically.
2171
2171
2172 If the object is a macro (see %macro for details), this opens up your
2172 If the object is a macro (see %macro for details), this opens up your
2173 specified editor with a temporary file containing the macro's data.
2173 specified editor with a temporary file containing the macro's data.
2174 Upon exit, the macro is reloaded with the contents of the file.
2174 Upon exit, the macro is reloaded with the contents of the file.
2175
2175
2176 Note: opening at an exact line is only supported under Unix, and some
2176 Note: opening at an exact line is only supported under Unix, and some
2177 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2177 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2178 '+NUMBER' parameter necessary for this feature. Good editors like
2178 '+NUMBER' parameter necessary for this feature. Good editors like
2179 (X)Emacs, vi, jed, pico and joe all do.
2179 (X)Emacs, vi, jed, pico and joe all do.
2180
2180
2181 - If the argument is not found as a variable, IPython will look for a
2181 - If the argument is not found as a variable, IPython will look for a
2182 file with that name (adding .py if necessary) and load it into the
2182 file with that name (adding .py if necessary) and load it into the
2183 editor. It will execute its contents with execfile() when you exit,
2183 editor. It will execute its contents with execfile() when you exit,
2184 loading any code in the file into your interactive namespace.
2184 loading any code in the file into your interactive namespace.
2185
2185
2186 After executing your code, %edit will return as output the code you
2186 After executing your code, %edit will return as output the code you
2187 typed in the editor (except when it was an existing file). This way
2187 typed in the editor (except when it was an existing file). This way
2188 you can reload the code in further invocations of %edit as a variable,
2188 you can reload the code in further invocations of %edit as a variable,
2189 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2189 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2190 the output.
2190 the output.
2191
2191
2192 Note that %edit is also available through the alias %ed.
2192 Note that %edit is also available through the alias %ed.
2193
2193
2194 This is an example of creating a simple function inside the editor and
2194 This is an example of creating a simple function inside the editor and
2195 then modifying it. First, start up the editor:
2195 then modifying it. First, start up the editor:
2196
2196
2197 In [1]: ed
2197 In [1]: ed
2198 Editing... done. Executing edited code...
2198 Editing... done. Executing edited code...
2199 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2199 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2200
2200
2201 We can then call the function foo():
2201 We can then call the function foo():
2202
2202
2203 In [2]: foo()
2203 In [2]: foo()
2204 foo() was defined in an editing session
2204 foo() was defined in an editing session
2205
2205
2206 Now we edit foo. IPython automatically loads the editor with the
2206 Now we edit foo. IPython automatically loads the editor with the
2207 (temporary) file where foo() was previously defined:
2207 (temporary) file where foo() was previously defined:
2208
2208
2209 In [3]: ed foo
2209 In [3]: ed foo
2210 Editing... done. Executing edited code...
2210 Editing... done. Executing edited code...
2211
2211
2212 And if we call foo() again we get the modified version:
2212 And if we call foo() again we get the modified version:
2213
2213
2214 In [4]: foo()
2214 In [4]: foo()
2215 foo() has now been changed!
2215 foo() has now been changed!
2216
2216
2217 Here is an example of how to edit a code snippet successive
2217 Here is an example of how to edit a code snippet successive
2218 times. First we call the editor:
2218 times. First we call the editor:
2219
2219
2220 In [5]: ed
2220 In [5]: ed
2221 Editing... done. Executing edited code...
2221 Editing... done. Executing edited code...
2222 hello
2222 hello
2223 Out[5]: "print 'hello'n"
2223 Out[5]: "print 'hello'n"
2224
2224
2225 Now we call it again with the previous output (stored in _):
2225 Now we call it again with the previous output (stored in _):
2226
2226
2227 In [6]: ed _
2227 In [6]: ed _
2228 Editing... done. Executing edited code...
2228 Editing... done. Executing edited code...
2229 hello world
2229 hello world
2230 Out[6]: "print 'hello world'n"
2230 Out[6]: "print 'hello world'n"
2231
2231
2232 Now we call it with the output #8 (stored in _8, also as Out[8]):
2232 Now we call it with the output #8 (stored in _8, also as Out[8]):
2233
2233
2234 In [7]: ed _8
2234 In [7]: ed _8
2235 Editing... done. Executing edited code...
2235 Editing... done. Executing edited code...
2236 hello again
2236 hello again
2237 Out[7]: "print 'hello again'n"
2237 Out[7]: "print 'hello again'n"
2238
2238
2239
2239
2240 Changing the default editor hook:
2240 Changing the default editor hook:
2241
2241
2242 If you wish to write your own editor hook, you can put it in a
2242 If you wish to write your own editor hook, you can put it in a
2243 configuration file which you load at startup time. The default hook
2243 configuration file which you load at startup time. The default hook
2244 is defined in the IPython.core.hooks module, and you can use that as a
2244 is defined in the IPython.core.hooks module, and you can use that as a
2245 starting example for further modifications. That file also has
2245 starting example for further modifications. That file also has
2246 general instructions on how to set a new hook for use once you've
2246 general instructions on how to set a new hook for use once you've
2247 defined it."""
2247 defined it."""
2248
2248
2249 # FIXME: This function has become a convoluted mess. It needs a
2249 # FIXME: This function has become a convoluted mess. It needs a
2250 # ground-up rewrite with clean, simple logic.
2250 # ground-up rewrite with clean, simple logic.
2251
2251
2252 def make_filename(arg):
2252 def make_filename(arg):
2253 "Make a filename from the given args"
2253 "Make a filename from the given args"
2254 try:
2254 try:
2255 filename = get_py_filename(arg)
2255 filename = get_py_filename(arg)
2256 except IOError:
2256 except IOError:
2257 if args.endswith('.py'):
2257 if args.endswith('.py'):
2258 filename = arg
2258 filename = arg
2259 else:
2259 else:
2260 filename = None
2260 filename = None
2261 return filename
2261 return filename
2262
2262
2263 # custom exceptions
2263 # custom exceptions
2264 class DataIsObject(Exception): pass
2264 class DataIsObject(Exception): pass
2265
2265
2266 opts,args = self.parse_options(parameter_s,'prxn:')
2266 opts,args = self.parse_options(parameter_s,'prxn:')
2267 # Set a few locals from the options for convenience:
2267 # Set a few locals from the options for convenience:
2268 opts_p = opts.has_key('p')
2268 opts_p = opts.has_key('p')
2269 opts_r = opts.has_key('r')
2269 opts_r = opts.has_key('r')
2270
2270
2271 # Default line number value
2271 # Default line number value
2272 lineno = opts.get('n',None)
2272 lineno = opts.get('n',None)
2273
2273
2274 if opts_p:
2274 if opts_p:
2275 args = '_%s' % last_call[0]
2275 args = '_%s' % last_call[0]
2276 if not self.shell.user_ns.has_key(args):
2276 if not self.shell.user_ns.has_key(args):
2277 args = last_call[1]
2277 args = last_call[1]
2278
2278
2279 # use last_call to remember the state of the previous call, but don't
2279 # use last_call to remember the state of the previous call, but don't
2280 # let it be clobbered by successive '-p' calls.
2280 # let it be clobbered by successive '-p' calls.
2281 try:
2281 try:
2282 last_call[0] = self.shell.outputcache.prompt_count
2282 last_call[0] = self.shell.outputcache.prompt_count
2283 if not opts_p:
2283 if not opts_p:
2284 last_call[1] = parameter_s
2284 last_call[1] = parameter_s
2285 except:
2285 except:
2286 pass
2286 pass
2287
2287
2288 # by default this is done with temp files, except when the given
2288 # by default this is done with temp files, except when the given
2289 # arg is a filename
2289 # arg is a filename
2290 use_temp = 1
2290 use_temp = 1
2291
2291
2292 if re.match(r'\d',args):
2292 if re.match(r'\d',args):
2293 # Mode where user specifies ranges of lines, like in %macro.
2293 # Mode where user specifies ranges of lines, like in %macro.
2294 # This means that you can't edit files whose names begin with
2294 # This means that you can't edit files whose names begin with
2295 # numbers this way. Tough.
2295 # numbers this way. Tough.
2296 ranges = args.split()
2296 ranges = args.split()
2297 data = ''.join(self.extract_input_slices(ranges,opts_r))
2297 data = ''.join(self.extract_input_slices(ranges,opts_r))
2298 elif args.endswith('.py'):
2298 elif args.endswith('.py'):
2299 filename = make_filename(args)
2299 filename = make_filename(args)
2300 data = ''
2300 data = ''
2301 use_temp = 0
2301 use_temp = 0
2302 elif args:
2302 elif args:
2303 try:
2303 try:
2304 # Load the parameter given as a variable. If not a string,
2304 # Load the parameter given as a variable. If not a string,
2305 # process it as an object instead (below)
2305 # process it as an object instead (below)
2306
2306
2307 #print '*** args',args,'type',type(args) # dbg
2307 #print '*** args',args,'type',type(args) # dbg
2308 data = eval(args,self.shell.user_ns)
2308 data = eval(args,self.shell.user_ns)
2309 if not type(data) in StringTypes:
2309 if not type(data) in StringTypes:
2310 raise DataIsObject
2310 raise DataIsObject
2311
2311
2312 except (NameError,SyntaxError):
2312 except (NameError,SyntaxError):
2313 # given argument is not a variable, try as a filename
2313 # given argument is not a variable, try as a filename
2314 filename = make_filename(args)
2314 filename = make_filename(args)
2315 if filename is None:
2315 if filename is None:
2316 warn("Argument given (%s) can't be found as a variable "
2316 warn("Argument given (%s) can't be found as a variable "
2317 "or as a filename." % args)
2317 "or as a filename." % args)
2318 return
2318 return
2319
2319
2320 data = ''
2320 data = ''
2321 use_temp = 0
2321 use_temp = 0
2322 except DataIsObject:
2322 except DataIsObject:
2323
2323
2324 # macros have a special edit function
2324 # macros have a special edit function
2325 if isinstance(data,Macro):
2325 if isinstance(data,Macro):
2326 self._edit_macro(args,data)
2326 self._edit_macro(args,data)
2327 return
2327 return
2328
2328
2329 # For objects, try to edit the file where they are defined
2329 # For objects, try to edit the file where they are defined
2330 try:
2330 try:
2331 filename = inspect.getabsfile(data)
2331 filename = inspect.getabsfile(data)
2332 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2332 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2333 # class created by %edit? Try to find source
2333 # class created by %edit? Try to find source
2334 # by looking for method definitions instead, the
2334 # by looking for method definitions instead, the
2335 # __module__ in those classes is FakeModule.
2335 # __module__ in those classes is FakeModule.
2336 attrs = [getattr(data, aname) for aname in dir(data)]
2336 attrs = [getattr(data, aname) for aname in dir(data)]
2337 for attr in attrs:
2337 for attr in attrs:
2338 if not inspect.ismethod(attr):
2338 if not inspect.ismethod(attr):
2339 continue
2339 continue
2340 filename = inspect.getabsfile(attr)
2340 filename = inspect.getabsfile(attr)
2341 if filename and 'fakemodule' not in filename.lower():
2341 if filename and 'fakemodule' not in filename.lower():
2342 # change the attribute to be the edit target instead
2342 # change the attribute to be the edit target instead
2343 data = attr
2343 data = attr
2344 break
2344 break
2345
2345
2346 datafile = 1
2346 datafile = 1
2347 except TypeError:
2347 except TypeError:
2348 filename = make_filename(args)
2348 filename = make_filename(args)
2349 datafile = 1
2349 datafile = 1
2350 warn('Could not find file where `%s` is defined.\n'
2350 warn('Could not find file where `%s` is defined.\n'
2351 'Opening a file named `%s`' % (args,filename))
2351 'Opening a file named `%s`' % (args,filename))
2352 # Now, make sure we can actually read the source (if it was in
2352 # Now, make sure we can actually read the source (if it was in
2353 # a temp file it's gone by now).
2353 # a temp file it's gone by now).
2354 if datafile:
2354 if datafile:
2355 try:
2355 try:
2356 if lineno is None:
2356 if lineno is None:
2357 lineno = inspect.getsourcelines(data)[1]
2357 lineno = inspect.getsourcelines(data)[1]
2358 except IOError:
2358 except IOError:
2359 filename = make_filename(args)
2359 filename = make_filename(args)
2360 if filename is None:
2360 if filename is None:
2361 warn('The file `%s` where `%s` was defined cannot '
2361 warn('The file `%s` where `%s` was defined cannot '
2362 'be read.' % (filename,data))
2362 'be read.' % (filename,data))
2363 return
2363 return
2364 use_temp = 0
2364 use_temp = 0
2365 else:
2365 else:
2366 data = ''
2366 data = ''
2367
2367
2368 if use_temp:
2368 if use_temp:
2369 filename = self.shell.mktempfile(data)
2369 filename = self.shell.mktempfile(data)
2370 print 'IPython will make a temporary file named:',filename
2370 print 'IPython will make a temporary file named:',filename
2371
2371
2372 # do actual editing here
2372 # do actual editing here
2373 print 'Editing...',
2373 print 'Editing...',
2374 sys.stdout.flush()
2374 sys.stdout.flush()
2375 try:
2375 try:
2376 self.shell.hooks.editor(filename,lineno)
2376 self.shell.hooks.editor(filename,lineno)
2377 except TryNext:
2377 except TryNext:
2378 warn('Could not open editor')
2378 warn('Could not open editor')
2379 return
2379 return
2380
2380
2381 # XXX TODO: should this be generalized for all string vars?
2381 # XXX TODO: should this be generalized for all string vars?
2382 # For now, this is special-cased to blocks created by cpaste
2382 # For now, this is special-cased to blocks created by cpaste
2383 if args.strip() == 'pasted_block':
2383 if args.strip() == 'pasted_block':
2384 self.shell.user_ns['pasted_block'] = file_read(filename)
2384 self.shell.user_ns['pasted_block'] = file_read(filename)
2385
2385
2386 if opts.has_key('x'): # -x prevents actual execution
2386 if opts.has_key('x'): # -x prevents actual execution
2387 print
2387 print
2388 else:
2388 else:
2389 print 'done. Executing edited code...'
2389 print 'done. Executing edited code...'
2390 if opts_r:
2390 if opts_r:
2391 self.shell.runlines(file_read(filename))
2391 self.shell.runlines(file_read(filename))
2392 else:
2392 else:
2393 self.shell.safe_execfile(filename,self.shell.user_ns,
2393 self.shell.safe_execfile(filename,self.shell.user_ns,
2394 self.shell.user_ns)
2394 self.shell.user_ns)
2395
2395
2396
2396
2397 if use_temp:
2397 if use_temp:
2398 try:
2398 try:
2399 return open(filename).read()
2399 return open(filename).read()
2400 except IOError,msg:
2400 except IOError,msg:
2401 if msg.filename == filename:
2401 if msg.filename == filename:
2402 warn('File not found. Did you forget to save?')
2402 warn('File not found. Did you forget to save?')
2403 return
2403 return
2404 else:
2404 else:
2405 self.shell.showtraceback()
2405 self.shell.showtraceback()
2406
2406
2407 def magic_xmode(self,parameter_s = ''):
2407 def magic_xmode(self,parameter_s = ''):
2408 """Switch modes for the exception handlers.
2408 """Switch modes for the exception handlers.
2409
2409
2410 Valid modes: Plain, Context and Verbose.
2410 Valid modes: Plain, Context and Verbose.
2411
2411
2412 If called without arguments, acts as a toggle."""
2412 If called without arguments, acts as a toggle."""
2413
2413
2414 def xmode_switch_err(name):
2414 def xmode_switch_err(name):
2415 warn('Error changing %s exception modes.\n%s' %
2415 warn('Error changing %s exception modes.\n%s' %
2416 (name,sys.exc_info()[1]))
2416 (name,sys.exc_info()[1]))
2417
2417
2418 shell = self.shell
2418 shell = self.shell
2419 new_mode = parameter_s.strip().capitalize()
2419 new_mode = parameter_s.strip().capitalize()
2420 try:
2420 try:
2421 shell.InteractiveTB.set_mode(mode=new_mode)
2421 shell.InteractiveTB.set_mode(mode=new_mode)
2422 print 'Exception reporting mode:',shell.InteractiveTB.mode
2422 print 'Exception reporting mode:',shell.InteractiveTB.mode
2423 except:
2423 except:
2424 xmode_switch_err('user')
2424 xmode_switch_err('user')
2425
2425
2426 # threaded shells use a special handler in sys.excepthook
2426 # threaded shells use a special handler in sys.excepthook
2427 if shell.isthreaded:
2427 if shell.isthreaded:
2428 try:
2428 try:
2429 shell.sys_excepthook.set_mode(mode=new_mode)
2429 shell.sys_excepthook.set_mode(mode=new_mode)
2430 except:
2430 except:
2431 xmode_switch_err('threaded')
2431 xmode_switch_err('threaded')
2432
2432
2433 def magic_colors(self,parameter_s = ''):
2433 def magic_colors(self,parameter_s = ''):
2434 """Switch color scheme for prompts, info system and exception handlers.
2434 """Switch color scheme for prompts, info system and exception handlers.
2435
2435
2436 Currently implemented schemes: NoColor, Linux, LightBG.
2436 Currently implemented schemes: NoColor, Linux, LightBG.
2437
2437
2438 Color scheme names are not case-sensitive."""
2438 Color scheme names are not case-sensitive."""
2439
2439
2440 def color_switch_err(name):
2440 def color_switch_err(name):
2441 warn('Error changing %s color schemes.\n%s' %
2441 warn('Error changing %s color schemes.\n%s' %
2442 (name,sys.exc_info()[1]))
2442 (name,sys.exc_info()[1]))
2443
2443
2444
2444
2445 new_scheme = parameter_s.strip()
2445 new_scheme = parameter_s.strip()
2446 if not new_scheme:
2446 if not new_scheme:
2447 raise UsageError(
2447 raise UsageError(
2448 "%colors: you must specify a color scheme. See '%colors?'")
2448 "%colors: you must specify a color scheme. See '%colors?'")
2449 return
2449 return
2450 # local shortcut
2450 # local shortcut
2451 shell = self.shell
2451 shell = self.shell
2452
2452
2453 import IPython.utils.rlineimpl as readline
2453 import IPython.utils.rlineimpl as readline
2454
2454
2455 if not readline.have_readline and sys.platform == "win32":
2455 if not readline.have_readline and sys.platform == "win32":
2456 msg = """\
2456 msg = """\
2457 Proper color support under MS Windows requires the pyreadline library.
2457 Proper color support under MS Windows requires the pyreadline library.
2458 You can find it at:
2458 You can find it at:
2459 http://ipython.scipy.org/moin/PyReadline/Intro
2459 http://ipython.scipy.org/moin/PyReadline/Intro
2460 Gary's readline needs the ctypes module, from:
2460 Gary's readline needs the ctypes module, from:
2461 http://starship.python.net/crew/theller/ctypes
2461 http://starship.python.net/crew/theller/ctypes
2462 (Note that ctypes is already part of Python versions 2.5 and newer).
2462 (Note that ctypes is already part of Python versions 2.5 and newer).
2463
2463
2464 Defaulting color scheme to 'NoColor'"""
2464 Defaulting color scheme to 'NoColor'"""
2465 new_scheme = 'NoColor'
2465 new_scheme = 'NoColor'
2466 warn(msg)
2466 warn(msg)
2467
2467
2468 # readline option is 0
2468 # readline option is 0
2469 if not shell.has_readline:
2469 if not shell.has_readline:
2470 new_scheme = 'NoColor'
2470 new_scheme = 'NoColor'
2471
2471
2472 # Set prompt colors
2472 # Set prompt colors
2473 try:
2473 try:
2474 shell.outputcache.set_colors(new_scheme)
2474 shell.outputcache.set_colors(new_scheme)
2475 except:
2475 except:
2476 color_switch_err('prompt')
2476 color_switch_err('prompt')
2477 else:
2477 else:
2478 shell.colors = \
2478 shell.colors = \
2479 shell.outputcache.color_table.active_scheme_name
2479 shell.outputcache.color_table.active_scheme_name
2480 # Set exception colors
2480 # Set exception colors
2481 try:
2481 try:
2482 shell.InteractiveTB.set_colors(scheme = new_scheme)
2482 shell.InteractiveTB.set_colors(scheme = new_scheme)
2483 shell.SyntaxTB.set_colors(scheme = new_scheme)
2483 shell.SyntaxTB.set_colors(scheme = new_scheme)
2484 except:
2484 except:
2485 color_switch_err('exception')
2485 color_switch_err('exception')
2486
2486
2487 # threaded shells use a verbose traceback in sys.excepthook
2487 # threaded shells use a verbose traceback in sys.excepthook
2488 if shell.isthreaded:
2488 if shell.isthreaded:
2489 try:
2489 try:
2490 shell.sys_excepthook.set_colors(scheme=new_scheme)
2490 shell.sys_excepthook.set_colors(scheme=new_scheme)
2491 except:
2491 except:
2492 color_switch_err('system exception handler')
2492 color_switch_err('system exception handler')
2493
2493
2494 # Set info (for 'object?') colors
2494 # Set info (for 'object?') colors
2495 if shell.color_info:
2495 if shell.color_info:
2496 try:
2496 try:
2497 shell.inspector.set_active_scheme(new_scheme)
2497 shell.inspector.set_active_scheme(new_scheme)
2498 except:
2498 except:
2499 color_switch_err('object inspector')
2499 color_switch_err('object inspector')
2500 else:
2500 else:
2501 shell.inspector.set_active_scheme('NoColor')
2501 shell.inspector.set_active_scheme('NoColor')
2502
2502
2503 def magic_color_info(self,parameter_s = ''):
2503 def magic_color_info(self,parameter_s = ''):
2504 """Toggle color_info.
2504 """Toggle color_info.
2505
2505
2506 The color_info configuration parameter controls whether colors are
2506 The color_info configuration parameter controls whether colors are
2507 used for displaying object details (by things like %psource, %pfile or
2507 used for displaying object details (by things like %psource, %pfile or
2508 the '?' system). This function toggles this value with each call.
2508 the '?' system). This function toggles this value with each call.
2509
2509
2510 Note that unless you have a fairly recent pager (less works better
2510 Note that unless you have a fairly recent pager (less works better
2511 than more) in your system, using colored object information displays
2511 than more) in your system, using colored object information displays
2512 will not work properly. Test it and see."""
2512 will not work properly. Test it and see."""
2513
2513
2514 self.shell.color_info = not self.shell.color_info
2514 self.shell.color_info = not self.shell.color_info
2515 self.magic_colors(self.shell.colors)
2515 self.magic_colors(self.shell.colors)
2516 print 'Object introspection functions have now coloring:',
2516 print 'Object introspection functions have now coloring:',
2517 print ['OFF','ON'][int(self.shell.color_info)]
2517 print ['OFF','ON'][int(self.shell.color_info)]
2518
2518
2519 def magic_Pprint(self, parameter_s=''):
2519 def magic_Pprint(self, parameter_s=''):
2520 """Toggle pretty printing on/off."""
2520 """Toggle pretty printing on/off."""
2521
2521
2522 self.shell.pprint = 1 - self.shell.pprint
2522 self.shell.pprint = 1 - self.shell.pprint
2523 print 'Pretty printing has been turned', \
2523 print 'Pretty printing has been turned', \
2524 ['OFF','ON'][self.shell.pprint]
2524 ['OFF','ON'][self.shell.pprint]
2525
2525
2526 def magic_exit(self, parameter_s=''):
2526 def magic_exit(self, parameter_s=''):
2527 """Exit IPython, confirming if configured to do so.
2527 """Exit IPython, confirming if configured to do so.
2528
2528
2529 You can configure whether IPython asks for confirmation upon exit by
2529 You can configure whether IPython asks for confirmation upon exit by
2530 setting the confirm_exit flag in the ipythonrc file."""
2530 setting the confirm_exit flag in the ipythonrc file."""
2531
2531
2532 self.shell.exit()
2532 self.shell.exit()
2533
2533
2534 def magic_quit(self, parameter_s=''):
2534 def magic_quit(self, parameter_s=''):
2535 """Exit IPython, confirming if configured to do so (like %exit)"""
2535 """Exit IPython, confirming if configured to do so (like %exit)"""
2536
2536
2537 self.shell.exit()
2537 self.shell.exit()
2538
2538
2539 def magic_Exit(self, parameter_s=''):
2539 def magic_Exit(self, parameter_s=''):
2540 """Exit IPython without confirmation."""
2540 """Exit IPython without confirmation."""
2541
2541
2542 self.shell.ask_exit()
2542 self.shell.ask_exit()
2543
2543
2544 #......................................................................
2544 #......................................................................
2545 # Functions to implement unix shell-type things
2545 # Functions to implement unix shell-type things
2546
2546
2547 @testdec.skip_doctest
2547 @testdec.skip_doctest
2548 def magic_alias(self, parameter_s = ''):
2548 def magic_alias(self, parameter_s = ''):
2549 """Define an alias for a system command.
2549 """Define an alias for a system command.
2550
2550
2551 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2551 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2552
2552
2553 Then, typing 'alias_name params' will execute the system command 'cmd
2553 Then, typing 'alias_name params' will execute the system command 'cmd
2554 params' (from your underlying operating system).
2554 params' (from your underlying operating system).
2555
2555
2556 Aliases have lower precedence than magic functions and Python normal
2556 Aliases have lower precedence than magic functions and Python normal
2557 variables, so if 'foo' is both a Python variable and an alias, the
2557 variables, so if 'foo' is both a Python variable and an alias, the
2558 alias can not be executed until 'del foo' removes the Python variable.
2558 alias can not be executed until 'del foo' removes the Python variable.
2559
2559
2560 You can use the %l specifier in an alias definition to represent the
2560 You can use the %l specifier in an alias definition to represent the
2561 whole line when the alias is called. For example:
2561 whole line when the alias is called. For example:
2562
2562
2563 In [2]: alias all echo "Input in brackets: <%l>"
2563 In [2]: alias all echo "Input in brackets: <%l>"
2564 In [3]: all hello world
2564 In [3]: all hello world
2565 Input in brackets: <hello world>
2565 Input in brackets: <hello world>
2566
2566
2567 You can also define aliases with parameters using %s specifiers (one
2567 You can also define aliases with parameters using %s specifiers (one
2568 per parameter):
2568 per parameter):
2569
2569
2570 In [1]: alias parts echo first %s second %s
2570 In [1]: alias parts echo first %s second %s
2571 In [2]: %parts A B
2571 In [2]: %parts A B
2572 first A second B
2572 first A second B
2573 In [3]: %parts A
2573 In [3]: %parts A
2574 Incorrect number of arguments: 2 expected.
2574 Incorrect number of arguments: 2 expected.
2575 parts is an alias to: 'echo first %s second %s'
2575 parts is an alias to: 'echo first %s second %s'
2576
2576
2577 Note that %l and %s are mutually exclusive. You can only use one or
2577 Note that %l and %s are mutually exclusive. You can only use one or
2578 the other in your aliases.
2578 the other in your aliases.
2579
2579
2580 Aliases expand Python variables just like system calls using ! or !!
2580 Aliases expand Python variables just like system calls using ! or !!
2581 do: all expressions prefixed with '$' get expanded. For details of
2581 do: all expressions prefixed with '$' get expanded. For details of
2582 the semantic rules, see PEP-215:
2582 the semantic rules, see PEP-215:
2583 http://www.python.org/peps/pep-0215.html. This is the library used by
2583 http://www.python.org/peps/pep-0215.html. This is the library used by
2584 IPython for variable expansion. If you want to access a true shell
2584 IPython for variable expansion. If you want to access a true shell
2585 variable, an extra $ is necessary to prevent its expansion by IPython:
2585 variable, an extra $ is necessary to prevent its expansion by IPython:
2586
2586
2587 In [6]: alias show echo
2587 In [6]: alias show echo
2588 In [7]: PATH='A Python string'
2588 In [7]: PATH='A Python string'
2589 In [8]: show $PATH
2589 In [8]: show $PATH
2590 A Python string
2590 A Python string
2591 In [9]: show $$PATH
2591 In [9]: show $$PATH
2592 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2592 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2593
2593
2594 You can use the alias facility to acess all of $PATH. See the %rehash
2594 You can use the alias facility to acess all of $PATH. See the %rehash
2595 and %rehashx functions, which automatically create aliases for the
2595 and %rehashx functions, which automatically create aliases for the
2596 contents of your $PATH.
2596 contents of your $PATH.
2597
2597
2598 If called with no parameters, %alias prints the current alias table."""
2598 If called with no parameters, %alias prints the current alias table."""
2599
2599
2600 par = parameter_s.strip()
2600 par = parameter_s.strip()
2601 if not par:
2601 if not par:
2602 stored = self.db.get('stored_aliases', {} )
2602 stored = self.db.get('stored_aliases', {} )
2603 aliases = sorted(self.shell.alias_manager.aliases)
2603 aliases = sorted(self.shell.alias_manager.aliases)
2604 # for k, v in stored:
2604 # for k, v in stored:
2605 # atab.append(k, v[0])
2605 # atab.append(k, v[0])
2606
2606
2607 print "Total number of aliases:", len(aliases)
2607 print "Total number of aliases:", len(aliases)
2608 return aliases
2608 return aliases
2609
2609
2610 # Now try to define a new one
2610 # Now try to define a new one
2611 try:
2611 try:
2612 alias,cmd = par.split(None, 1)
2612 alias,cmd = par.split(None, 1)
2613 except:
2613 except:
2614 print oinspect.getdoc(self.magic_alias)
2614 print oinspect.getdoc(self.magic_alias)
2615 else:
2615 else:
2616 self.shell.alias_manager.soft_define_alias(alias, cmd)
2616 self.shell.alias_manager.soft_define_alias(alias, cmd)
2617 # end magic_alias
2617 # end magic_alias
2618
2618
2619 def magic_unalias(self, parameter_s = ''):
2619 def magic_unalias(self, parameter_s = ''):
2620 """Remove an alias"""
2620 """Remove an alias"""
2621
2621
2622 aname = parameter_s.strip()
2622 aname = parameter_s.strip()
2623 self.shell.alias_manager.undefine_alias(aname)
2623 self.shell.alias_manager.undefine_alias(aname)
2624 stored = self.db.get('stored_aliases', {} )
2624 stored = self.db.get('stored_aliases', {} )
2625 if aname in stored:
2625 if aname in stored:
2626 print "Removing %stored alias",aname
2626 print "Removing %stored alias",aname
2627 del stored[aname]
2627 del stored[aname]
2628 self.db['stored_aliases'] = stored
2628 self.db['stored_aliases'] = stored
2629
2629
2630
2630
2631 def magic_rehashx(self, parameter_s = ''):
2631 def magic_rehashx(self, parameter_s = ''):
2632 """Update the alias table with all executable files in $PATH.
2632 """Update the alias table with all executable files in $PATH.
2633
2633
2634 This version explicitly checks that every entry in $PATH is a file
2634 This version explicitly checks that every entry in $PATH is a file
2635 with execute access (os.X_OK), so it is much slower than %rehash.
2635 with execute access (os.X_OK), so it is much slower than %rehash.
2636
2636
2637 Under Windows, it checks executability as a match agains a
2637 Under Windows, it checks executability as a match agains a
2638 '|'-separated string of extensions, stored in the IPython config
2638 '|'-separated string of extensions, stored in the IPython config
2639 variable win_exec_ext. This defaults to 'exe|com|bat'.
2639 variable win_exec_ext. This defaults to 'exe|com|bat'.
2640
2640
2641 This function also resets the root module cache of module completer,
2641 This function also resets the root module cache of module completer,
2642 used on slow filesystems.
2642 used on slow filesystems.
2643 """
2643 """
2644 from IPython.core.alias import InvalidAliasError
2644 from IPython.core.alias import InvalidAliasError
2645
2645
2646 # for the benefit of module completer in ipy_completers.py
2646 # for the benefit of module completer in ipy_completers.py
2647 del self.db['rootmodules']
2647 del self.db['rootmodules']
2648
2648
2649 path = [os.path.abspath(os.path.expanduser(p)) for p in
2649 path = [os.path.abspath(os.path.expanduser(p)) for p in
2650 os.environ.get('PATH','').split(os.pathsep)]
2650 os.environ.get('PATH','').split(os.pathsep)]
2651 path = filter(os.path.isdir,path)
2651 path = filter(os.path.isdir,path)
2652
2652
2653 syscmdlist = []
2653 syscmdlist = []
2654 # Now define isexec in a cross platform manner.
2654 # Now define isexec in a cross platform manner.
2655 if os.name == 'posix':
2655 if os.name == 'posix':
2656 isexec = lambda fname:os.path.isfile(fname) and \
2656 isexec = lambda fname:os.path.isfile(fname) and \
2657 os.access(fname,os.X_OK)
2657 os.access(fname,os.X_OK)
2658 else:
2658 else:
2659 try:
2659 try:
2660 winext = os.environ['pathext'].replace(';','|').replace('.','')
2660 winext = os.environ['pathext'].replace(';','|').replace('.','')
2661 except KeyError:
2661 except KeyError:
2662 winext = 'exe|com|bat|py'
2662 winext = 'exe|com|bat|py'
2663 if 'py' not in winext:
2663 if 'py' not in winext:
2664 winext += '|py'
2664 winext += '|py'
2665 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2665 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2666 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2666 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2667 savedir = os.getcwd()
2667 savedir = os.getcwd()
2668
2668
2669 # Now walk the paths looking for executables to alias.
2669 # Now walk the paths looking for executables to alias.
2670 try:
2670 try:
2671 # write the whole loop for posix/Windows so we don't have an if in
2671 # write the whole loop for posix/Windows so we don't have an if in
2672 # the innermost part
2672 # the innermost part
2673 if os.name == 'posix':
2673 if os.name == 'posix':
2674 for pdir in path:
2674 for pdir in path:
2675 os.chdir(pdir)
2675 os.chdir(pdir)
2676 for ff in os.listdir(pdir):
2676 for ff in os.listdir(pdir):
2677 if isexec(ff):
2677 if isexec(ff):
2678 try:
2678 try:
2679 # Removes dots from the name since ipython
2679 # Removes dots from the name since ipython
2680 # will assume names with dots to be python.
2680 # will assume names with dots to be python.
2681 self.shell.alias_manager.define_alias(
2681 self.shell.alias_manager.define_alias(
2682 ff.replace('.',''), ff)
2682 ff.replace('.',''), ff)
2683 except InvalidAliasError:
2683 except InvalidAliasError:
2684 pass
2684 pass
2685 else:
2685 else:
2686 syscmdlist.append(ff)
2686 syscmdlist.append(ff)
2687 else:
2687 else:
2688 for pdir in path:
2688 for pdir in path:
2689 os.chdir(pdir)
2689 os.chdir(pdir)
2690 for ff in os.listdir(pdir):
2690 for ff in os.listdir(pdir):
2691 base, ext = os.path.splitext(ff)
2691 base, ext = os.path.splitext(ff)
2692 if isexec(ff) and base.lower() not in self.shell.no_alias:
2692 if isexec(ff) and base.lower() not in self.shell.no_alias:
2693 if ext.lower() == '.exe':
2693 if ext.lower() == '.exe':
2694 ff = base
2694 ff = base
2695 try:
2695 try:
2696 # Removes dots from the name since ipython
2696 # Removes dots from the name since ipython
2697 # will assume names with dots to be python.
2697 # will assume names with dots to be python.
2698 self.shell.alias_manager.define_alias(
2698 self.shell.alias_manager.define_alias(
2699 base.lower().replace('.',''), ff)
2699 base.lower().replace('.',''), ff)
2700 except InvalidAliasError:
2700 except InvalidAliasError:
2701 pass
2701 pass
2702 syscmdlist.append(ff)
2702 syscmdlist.append(ff)
2703 db = self.db
2703 db = self.db
2704 db['syscmdlist'] = syscmdlist
2704 db['syscmdlist'] = syscmdlist
2705 finally:
2705 finally:
2706 os.chdir(savedir)
2706 os.chdir(savedir)
2707
2707
2708 def magic_pwd(self, parameter_s = ''):
2708 def magic_pwd(self, parameter_s = ''):
2709 """Return the current working directory path."""
2709 """Return the current working directory path."""
2710 return os.getcwd()
2710 return os.getcwd()
2711
2711
2712 def magic_cd(self, parameter_s=''):
2712 def magic_cd(self, parameter_s=''):
2713 """Change the current working directory.
2713 """Change the current working directory.
2714
2714
2715 This command automatically maintains an internal list of directories
2715 This command automatically maintains an internal list of directories
2716 you visit during your IPython session, in the variable _dh. The
2716 you visit during your IPython session, in the variable _dh. The
2717 command %dhist shows this history nicely formatted. You can also
2717 command %dhist shows this history nicely formatted. You can also
2718 do 'cd -<tab>' to see directory history conveniently.
2718 do 'cd -<tab>' to see directory history conveniently.
2719
2719
2720 Usage:
2720 Usage:
2721
2721
2722 cd 'dir': changes to directory 'dir'.
2722 cd 'dir': changes to directory 'dir'.
2723
2723
2724 cd -: changes to the last visited directory.
2724 cd -: changes to the last visited directory.
2725
2725
2726 cd -<n>: changes to the n-th directory in the directory history.
2726 cd -<n>: changes to the n-th directory in the directory history.
2727
2727
2728 cd --foo: change to directory that matches 'foo' in history
2728 cd --foo: change to directory that matches 'foo' in history
2729
2729
2730 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2730 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2731 (note: cd <bookmark_name> is enough if there is no
2731 (note: cd <bookmark_name> is enough if there is no
2732 directory <bookmark_name>, but a bookmark with the name exists.)
2732 directory <bookmark_name>, but a bookmark with the name exists.)
2733 'cd -b <tab>' allows you to tab-complete bookmark names.
2733 'cd -b <tab>' allows you to tab-complete bookmark names.
2734
2734
2735 Options:
2735 Options:
2736
2736
2737 -q: quiet. Do not print the working directory after the cd command is
2737 -q: quiet. Do not print the working directory after the cd command is
2738 executed. By default IPython's cd command does print this directory,
2738 executed. By default IPython's cd command does print this directory,
2739 since the default prompts do not display path information.
2739 since the default prompts do not display path information.
2740
2740
2741 Note that !cd doesn't work for this purpose because the shell where
2741 Note that !cd doesn't work for this purpose because the shell where
2742 !command runs is immediately discarded after executing 'command'."""
2742 !command runs is immediately discarded after executing 'command'."""
2743
2743
2744 parameter_s = parameter_s.strip()
2744 parameter_s = parameter_s.strip()
2745 #bkms = self.shell.persist.get("bookmarks",{})
2745 #bkms = self.shell.persist.get("bookmarks",{})
2746
2746
2747 oldcwd = os.getcwd()
2747 oldcwd = os.getcwd()
2748 numcd = re.match(r'(-)(\d+)$',parameter_s)
2748 numcd = re.match(r'(-)(\d+)$',parameter_s)
2749 # jump in directory history by number
2749 # jump in directory history by number
2750 if numcd:
2750 if numcd:
2751 nn = int(numcd.group(2))
2751 nn = int(numcd.group(2))
2752 try:
2752 try:
2753 ps = self.shell.user_ns['_dh'][nn]
2753 ps = self.shell.user_ns['_dh'][nn]
2754 except IndexError:
2754 except IndexError:
2755 print 'The requested directory does not exist in history.'
2755 print 'The requested directory does not exist in history.'
2756 return
2756 return
2757 else:
2757 else:
2758 opts = {}
2758 opts = {}
2759 elif parameter_s.startswith('--'):
2759 elif parameter_s.startswith('--'):
2760 ps = None
2760 ps = None
2761 fallback = None
2761 fallback = None
2762 pat = parameter_s[2:]
2762 pat = parameter_s[2:]
2763 dh = self.shell.user_ns['_dh']
2763 dh = self.shell.user_ns['_dh']
2764 # first search only by basename (last component)
2764 # first search only by basename (last component)
2765 for ent in reversed(dh):
2765 for ent in reversed(dh):
2766 if pat in os.path.basename(ent) and os.path.isdir(ent):
2766 if pat in os.path.basename(ent) and os.path.isdir(ent):
2767 ps = ent
2767 ps = ent
2768 break
2768 break
2769
2769
2770 if fallback is None and pat in ent and os.path.isdir(ent):
2770 if fallback is None and pat in ent and os.path.isdir(ent):
2771 fallback = ent
2771 fallback = ent
2772
2772
2773 # if we have no last part match, pick the first full path match
2773 # if we have no last part match, pick the first full path match
2774 if ps is None:
2774 if ps is None:
2775 ps = fallback
2775 ps = fallback
2776
2776
2777 if ps is None:
2777 if ps is None:
2778 print "No matching entry in directory history"
2778 print "No matching entry in directory history"
2779 return
2779 return
2780 else:
2780 else:
2781 opts = {}
2781 opts = {}
2782
2782
2783
2783
2784 else:
2784 else:
2785 #turn all non-space-escaping backslashes to slashes,
2785 #turn all non-space-escaping backslashes to slashes,
2786 # for c:\windows\directory\names\
2786 # for c:\windows\directory\names\
2787 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2787 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2788 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2788 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2789 # jump to previous
2789 # jump to previous
2790 if ps == '-':
2790 if ps == '-':
2791 try:
2791 try:
2792 ps = self.shell.user_ns['_dh'][-2]
2792 ps = self.shell.user_ns['_dh'][-2]
2793 except IndexError:
2793 except IndexError:
2794 raise UsageError('%cd -: No previous directory to change to.')
2794 raise UsageError('%cd -: No previous directory to change to.')
2795 # jump to bookmark if needed
2795 # jump to bookmark if needed
2796 else:
2796 else:
2797 if not os.path.isdir(ps) or opts.has_key('b'):
2797 if not os.path.isdir(ps) or opts.has_key('b'):
2798 bkms = self.db.get('bookmarks', {})
2798 bkms = self.db.get('bookmarks', {})
2799
2799
2800 if bkms.has_key(ps):
2800 if bkms.has_key(ps):
2801 target = bkms[ps]
2801 target = bkms[ps]
2802 print '(bookmark:%s) -> %s' % (ps,target)
2802 print '(bookmark:%s) -> %s' % (ps,target)
2803 ps = target
2803 ps = target
2804 else:
2804 else:
2805 if opts.has_key('b'):
2805 if opts.has_key('b'):
2806 raise UsageError("Bookmark '%s' not found. "
2806 raise UsageError("Bookmark '%s' not found. "
2807 "Use '%%bookmark -l' to see your bookmarks." % ps)
2807 "Use '%%bookmark -l' to see your bookmarks." % ps)
2808
2808
2809 # at this point ps should point to the target dir
2809 # at this point ps should point to the target dir
2810 if ps:
2810 if ps:
2811 try:
2811 try:
2812 os.chdir(os.path.expanduser(ps))
2812 os.chdir(os.path.expanduser(ps))
2813 if self.shell.term_title:
2813 if self.shell.term_title:
2814 platutils.set_term_title('IPython: ' + abbrev_cwd())
2814 platutils.set_term_title('IPython: ' + abbrev_cwd())
2815 except OSError:
2815 except OSError:
2816 print sys.exc_info()[1]
2816 print sys.exc_info()[1]
2817 else:
2817 else:
2818 cwd = os.getcwd()
2818 cwd = os.getcwd()
2819 dhist = self.shell.user_ns['_dh']
2819 dhist = self.shell.user_ns['_dh']
2820 if oldcwd != cwd:
2820 if oldcwd != cwd:
2821 dhist.append(cwd)
2821 dhist.append(cwd)
2822 self.db['dhist'] = compress_dhist(dhist)[-100:]
2822 self.db['dhist'] = compress_dhist(dhist)[-100:]
2823
2823
2824 else:
2824 else:
2825 os.chdir(self.shell.home_dir)
2825 os.chdir(self.shell.home_dir)
2826 if self.shell.term_title:
2826 if self.shell.term_title:
2827 platutils.set_term_title('IPython: ' + '~')
2827 platutils.set_term_title('IPython: ' + '~')
2828 cwd = os.getcwd()
2828 cwd = os.getcwd()
2829 dhist = self.shell.user_ns['_dh']
2829 dhist = self.shell.user_ns['_dh']
2830
2830
2831 if oldcwd != cwd:
2831 if oldcwd != cwd:
2832 dhist.append(cwd)
2832 dhist.append(cwd)
2833 self.db['dhist'] = compress_dhist(dhist)[-100:]
2833 self.db['dhist'] = compress_dhist(dhist)[-100:]
2834 if not 'q' in opts and self.shell.user_ns['_dh']:
2834 if not 'q' in opts and self.shell.user_ns['_dh']:
2835 print self.shell.user_ns['_dh'][-1]
2835 print self.shell.user_ns['_dh'][-1]
2836
2836
2837
2837
2838 def magic_env(self, parameter_s=''):
2838 def magic_env(self, parameter_s=''):
2839 """List environment variables."""
2839 """List environment variables."""
2840
2840
2841 return os.environ.data
2841 return os.environ.data
2842
2842
2843 def magic_pushd(self, parameter_s=''):
2843 def magic_pushd(self, parameter_s=''):
2844 """Place the current dir on stack and change directory.
2844 """Place the current dir on stack and change directory.
2845
2845
2846 Usage:\\
2846 Usage:\\
2847 %pushd ['dirname']
2847 %pushd ['dirname']
2848 """
2848 """
2849
2849
2850 dir_s = self.shell.dir_stack
2850 dir_s = self.shell.dir_stack
2851 tgt = os.path.expanduser(parameter_s)
2851 tgt = os.path.expanduser(parameter_s)
2852 cwd = os.getcwd().replace(self.home_dir,'~')
2852 cwd = os.getcwd().replace(self.home_dir,'~')
2853 if tgt:
2853 if tgt:
2854 self.magic_cd(parameter_s)
2854 self.magic_cd(parameter_s)
2855 dir_s.insert(0,cwd)
2855 dir_s.insert(0,cwd)
2856 return self.magic_dirs()
2856 return self.magic_dirs()
2857
2857
2858 def magic_popd(self, parameter_s=''):
2858 def magic_popd(self, parameter_s=''):
2859 """Change to directory popped off the top of the stack.
2859 """Change to directory popped off the top of the stack.
2860 """
2860 """
2861 if not self.shell.dir_stack:
2861 if not self.shell.dir_stack:
2862 raise UsageError("%popd on empty stack")
2862 raise UsageError("%popd on empty stack")
2863 top = self.shell.dir_stack.pop(0)
2863 top = self.shell.dir_stack.pop(0)
2864 self.magic_cd(top)
2864 self.magic_cd(top)
2865 print "popd ->",top
2865 print "popd ->",top
2866
2866
2867 def magic_dirs(self, parameter_s=''):
2867 def magic_dirs(self, parameter_s=''):
2868 """Return the current directory stack."""
2868 """Return the current directory stack."""
2869
2869
2870 return self.shell.dir_stack
2870 return self.shell.dir_stack
2871
2871
2872 def magic_dhist(self, parameter_s=''):
2872 def magic_dhist(self, parameter_s=''):
2873 """Print your history of visited directories.
2873 """Print your history of visited directories.
2874
2874
2875 %dhist -> print full history\\
2875 %dhist -> print full history\\
2876 %dhist n -> print last n entries only\\
2876 %dhist n -> print last n entries only\\
2877 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2877 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2878
2878
2879 This history is automatically maintained by the %cd command, and
2879 This history is automatically maintained by the %cd command, and
2880 always available as the global list variable _dh. You can use %cd -<n>
2880 always available as the global list variable _dh. You can use %cd -<n>
2881 to go to directory number <n>.
2881 to go to directory number <n>.
2882
2882
2883 Note that most of time, you should view directory history by entering
2883 Note that most of time, you should view directory history by entering
2884 cd -<TAB>.
2884 cd -<TAB>.
2885
2885
2886 """
2886 """
2887
2887
2888 dh = self.shell.user_ns['_dh']
2888 dh = self.shell.user_ns['_dh']
2889 if parameter_s:
2889 if parameter_s:
2890 try:
2890 try:
2891 args = map(int,parameter_s.split())
2891 args = map(int,parameter_s.split())
2892 except:
2892 except:
2893 self.arg_err(Magic.magic_dhist)
2893 self.arg_err(Magic.magic_dhist)
2894 return
2894 return
2895 if len(args) == 1:
2895 if len(args) == 1:
2896 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2896 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2897 elif len(args) == 2:
2897 elif len(args) == 2:
2898 ini,fin = args
2898 ini,fin = args
2899 else:
2899 else:
2900 self.arg_err(Magic.magic_dhist)
2900 self.arg_err(Magic.magic_dhist)
2901 return
2901 return
2902 else:
2902 else:
2903 ini,fin = 0,len(dh)
2903 ini,fin = 0,len(dh)
2904 nlprint(dh,
2904 nlprint(dh,
2905 header = 'Directory history (kept in _dh)',
2905 header = 'Directory history (kept in _dh)',
2906 start=ini,stop=fin)
2906 start=ini,stop=fin)
2907
2907
2908 @testdec.skip_doctest
2908 @testdec.skip_doctest
2909 def magic_sc(self, parameter_s=''):
2909 def magic_sc(self, parameter_s=''):
2910 """Shell capture - execute a shell command and capture its output.
2910 """Shell capture - execute a shell command and capture its output.
2911
2911
2912 DEPRECATED. Suboptimal, retained for backwards compatibility.
2912 DEPRECATED. Suboptimal, retained for backwards compatibility.
2913
2913
2914 You should use the form 'var = !command' instead. Example:
2914 You should use the form 'var = !command' instead. Example:
2915
2915
2916 "%sc -l myfiles = ls ~" should now be written as
2916 "%sc -l myfiles = ls ~" should now be written as
2917
2917
2918 "myfiles = !ls ~"
2918 "myfiles = !ls ~"
2919
2919
2920 myfiles.s, myfiles.l and myfiles.n still apply as documented
2920 myfiles.s, myfiles.l and myfiles.n still apply as documented
2921 below.
2921 below.
2922
2922
2923 --
2923 --
2924 %sc [options] varname=command
2924 %sc [options] varname=command
2925
2925
2926 IPython will run the given command using commands.getoutput(), and
2926 IPython will run the given command using commands.getoutput(), and
2927 will then update the user's interactive namespace with a variable
2927 will then update the user's interactive namespace with a variable
2928 called varname, containing the value of the call. Your command can
2928 called varname, containing the value of the call. Your command can
2929 contain shell wildcards, pipes, etc.
2929 contain shell wildcards, pipes, etc.
2930
2930
2931 The '=' sign in the syntax is mandatory, and the variable name you
2931 The '=' sign in the syntax is mandatory, and the variable name you
2932 supply must follow Python's standard conventions for valid names.
2932 supply must follow Python's standard conventions for valid names.
2933
2933
2934 (A special format without variable name exists for internal use)
2934 (A special format without variable name exists for internal use)
2935
2935
2936 Options:
2936 Options:
2937
2937
2938 -l: list output. Split the output on newlines into a list before
2938 -l: list output. Split the output on newlines into a list before
2939 assigning it to the given variable. By default the output is stored
2939 assigning it to the given variable. By default the output is stored
2940 as a single string.
2940 as a single string.
2941
2941
2942 -v: verbose. Print the contents of the variable.
2942 -v: verbose. Print the contents of the variable.
2943
2943
2944 In most cases you should not need to split as a list, because the
2944 In most cases you should not need to split as a list, because the
2945 returned value is a special type of string which can automatically
2945 returned value is a special type of string which can automatically
2946 provide its contents either as a list (split on newlines) or as a
2946 provide its contents either as a list (split on newlines) or as a
2947 space-separated string. These are convenient, respectively, either
2947 space-separated string. These are convenient, respectively, either
2948 for sequential processing or to be passed to a shell command.
2948 for sequential processing or to be passed to a shell command.
2949
2949
2950 For example:
2950 For example:
2951
2951
2952 # all-random
2952 # all-random
2953
2953
2954 # Capture into variable a
2954 # Capture into variable a
2955 In [1]: sc a=ls *py
2955 In [1]: sc a=ls *py
2956
2956
2957 # a is a string with embedded newlines
2957 # a is a string with embedded newlines
2958 In [2]: a
2958 In [2]: a
2959 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2959 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2960
2960
2961 # which can be seen as a list:
2961 # which can be seen as a list:
2962 In [3]: a.l
2962 In [3]: a.l
2963 Out[3]: ['setup.py', 'win32_manual_post_install.py']
2963 Out[3]: ['setup.py', 'win32_manual_post_install.py']
2964
2964
2965 # or as a whitespace-separated string:
2965 # or as a whitespace-separated string:
2966 In [4]: a.s
2966 In [4]: a.s
2967 Out[4]: 'setup.py win32_manual_post_install.py'
2967 Out[4]: 'setup.py win32_manual_post_install.py'
2968
2968
2969 # a.s is useful to pass as a single command line:
2969 # a.s is useful to pass as a single command line:
2970 In [5]: !wc -l $a.s
2970 In [5]: !wc -l $a.s
2971 146 setup.py
2971 146 setup.py
2972 130 win32_manual_post_install.py
2972 130 win32_manual_post_install.py
2973 276 total
2973 276 total
2974
2974
2975 # while the list form is useful to loop over:
2975 # while the list form is useful to loop over:
2976 In [6]: for f in a.l:
2976 In [6]: for f in a.l:
2977 ...: !wc -l $f
2977 ...: !wc -l $f
2978 ...:
2978 ...:
2979 146 setup.py
2979 146 setup.py
2980 130 win32_manual_post_install.py
2980 130 win32_manual_post_install.py
2981
2981
2982 Similiarly, the lists returned by the -l option are also special, in
2982 Similiarly, the lists returned by the -l option are also special, in
2983 the sense that you can equally invoke the .s attribute on them to
2983 the sense that you can equally invoke the .s attribute on them to
2984 automatically get a whitespace-separated string from their contents:
2984 automatically get a whitespace-separated string from their contents:
2985
2985
2986 In [7]: sc -l b=ls *py
2986 In [7]: sc -l b=ls *py
2987
2987
2988 In [8]: b
2988 In [8]: b
2989 Out[8]: ['setup.py', 'win32_manual_post_install.py']
2989 Out[8]: ['setup.py', 'win32_manual_post_install.py']
2990
2990
2991 In [9]: b.s
2991 In [9]: b.s
2992 Out[9]: 'setup.py win32_manual_post_install.py'
2992 Out[9]: 'setup.py win32_manual_post_install.py'
2993
2993
2994 In summary, both the lists and strings used for ouptut capture have
2994 In summary, both the lists and strings used for ouptut capture have
2995 the following special attributes:
2995 the following special attributes:
2996
2996
2997 .l (or .list) : value as list.
2997 .l (or .list) : value as list.
2998 .n (or .nlstr): value as newline-separated string.
2998 .n (or .nlstr): value as newline-separated string.
2999 .s (or .spstr): value as space-separated string.
2999 .s (or .spstr): value as space-separated string.
3000 """
3000 """
3001
3001
3002 opts,args = self.parse_options(parameter_s,'lv')
3002 opts,args = self.parse_options(parameter_s,'lv')
3003 # Try to get a variable name and command to run
3003 # Try to get a variable name and command to run
3004 try:
3004 try:
3005 # the variable name must be obtained from the parse_options
3005 # the variable name must be obtained from the parse_options
3006 # output, which uses shlex.split to strip options out.
3006 # output, which uses shlex.split to strip options out.
3007 var,_ = args.split('=',1)
3007 var,_ = args.split('=',1)
3008 var = var.strip()
3008 var = var.strip()
3009 # But the the command has to be extracted from the original input
3009 # But the the command has to be extracted from the original input
3010 # parameter_s, not on what parse_options returns, to avoid the
3010 # parameter_s, not on what parse_options returns, to avoid the
3011 # quote stripping which shlex.split performs on it.
3011 # quote stripping which shlex.split performs on it.
3012 _,cmd = parameter_s.split('=',1)
3012 _,cmd = parameter_s.split('=',1)
3013 except ValueError:
3013 except ValueError:
3014 var,cmd = '',''
3014 var,cmd = '',''
3015 # If all looks ok, proceed
3015 # If all looks ok, proceed
3016 out,err = self.shell.getoutputerror(cmd)
3016 out,err = self.shell.getoutputerror(cmd)
3017 if err:
3017 if err:
3018 print >> Term.cerr,err
3018 print >> Term.cerr,err
3019 if opts.has_key('l'):
3019 if opts.has_key('l'):
3020 out = SList(out.split('\n'))
3020 out = SList(out.split('\n'))
3021 else:
3021 else:
3022 out = LSString(out)
3022 out = LSString(out)
3023 if opts.has_key('v'):
3023 if opts.has_key('v'):
3024 print '%s ==\n%s' % (var,pformat(out))
3024 print '%s ==\n%s' % (var,pformat(out))
3025 if var:
3025 if var:
3026 self.shell.user_ns.update({var:out})
3026 self.shell.user_ns.update({var:out})
3027 else:
3027 else:
3028 return out
3028 return out
3029
3029
3030 def magic_sx(self, parameter_s=''):
3030 def magic_sx(self, parameter_s=''):
3031 """Shell execute - run a shell command and capture its output.
3031 """Shell execute - run a shell command and capture its output.
3032
3032
3033 %sx command
3033 %sx command
3034
3034
3035 IPython will run the given command using commands.getoutput(), and
3035 IPython will run the given command using commands.getoutput(), and
3036 return the result formatted as a list (split on '\\n'). Since the
3036 return the result formatted as a list (split on '\\n'). Since the
3037 output is _returned_, it will be stored in ipython's regular output
3037 output is _returned_, it will be stored in ipython's regular output
3038 cache Out[N] and in the '_N' automatic variables.
3038 cache Out[N] and in the '_N' automatic variables.
3039
3039
3040 Notes:
3040 Notes:
3041
3041
3042 1) If an input line begins with '!!', then %sx is automatically
3042 1) If an input line begins with '!!', then %sx is automatically
3043 invoked. That is, while:
3043 invoked. That is, while:
3044 !ls
3044 !ls
3045 causes ipython to simply issue system('ls'), typing
3045 causes ipython to simply issue system('ls'), typing
3046 !!ls
3046 !!ls
3047 is a shorthand equivalent to:
3047 is a shorthand equivalent to:
3048 %sx ls
3048 %sx ls
3049
3049
3050 2) %sx differs from %sc in that %sx automatically splits into a list,
3050 2) %sx differs from %sc in that %sx automatically splits into a list,
3051 like '%sc -l'. The reason for this is to make it as easy as possible
3051 like '%sc -l'. The reason for this is to make it as easy as possible
3052 to process line-oriented shell output via further python commands.
3052 to process line-oriented shell output via further python commands.
3053 %sc is meant to provide much finer control, but requires more
3053 %sc is meant to provide much finer control, but requires more
3054 typing.
3054 typing.
3055
3055
3056 3) Just like %sc -l, this is a list with special attributes:
3056 3) Just like %sc -l, this is a list with special attributes:
3057
3057
3058 .l (or .list) : value as list.
3058 .l (or .list) : value as list.
3059 .n (or .nlstr): value as newline-separated string.
3059 .n (or .nlstr): value as newline-separated string.
3060 .s (or .spstr): value as whitespace-separated string.
3060 .s (or .spstr): value as whitespace-separated string.
3061
3061
3062 This is very useful when trying to use such lists as arguments to
3062 This is very useful when trying to use such lists as arguments to
3063 system commands."""
3063 system commands."""
3064
3064
3065 if parameter_s:
3065 if parameter_s:
3066 out,err = self.shell.getoutputerror(parameter_s)
3066 out,err = self.shell.getoutputerror(parameter_s)
3067 if err:
3067 if err:
3068 print >> Term.cerr,err
3068 print >> Term.cerr,err
3069 return SList(out.split('\n'))
3069 return SList(out.split('\n'))
3070
3070
3071 def magic_bg(self, parameter_s=''):
3071 def magic_bg(self, parameter_s=''):
3072 """Run a job in the background, in a separate thread.
3072 """Run a job in the background, in a separate thread.
3073
3073
3074 For example,
3074 For example,
3075
3075
3076 %bg myfunc(x,y,z=1)
3076 %bg myfunc(x,y,z=1)
3077
3077
3078 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3078 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3079 execution starts, a message will be printed indicating the job
3079 execution starts, a message will be printed indicating the job
3080 number. If your job number is 5, you can use
3080 number. If your job number is 5, you can use
3081
3081
3082 myvar = jobs.result(5) or myvar = jobs[5].result
3082 myvar = jobs.result(5) or myvar = jobs[5].result
3083
3083
3084 to assign this result to variable 'myvar'.
3084 to assign this result to variable 'myvar'.
3085
3085
3086 IPython has a job manager, accessible via the 'jobs' object. You can
3086 IPython has a job manager, accessible via the 'jobs' object. You can
3087 type jobs? to get more information about it, and use jobs.<TAB> to see
3087 type jobs? to get more information about it, and use jobs.<TAB> to see
3088 its attributes. All attributes not starting with an underscore are
3088 its attributes. All attributes not starting with an underscore are
3089 meant for public use.
3089 meant for public use.
3090
3090
3091 In particular, look at the jobs.new() method, which is used to create
3091 In particular, look at the jobs.new() method, which is used to create
3092 new jobs. This magic %bg function is just a convenience wrapper
3092 new jobs. This magic %bg function is just a convenience wrapper
3093 around jobs.new(), for expression-based jobs. If you want to create a
3093 around jobs.new(), for expression-based jobs. If you want to create a
3094 new job with an explicit function object and arguments, you must call
3094 new job with an explicit function object and arguments, you must call
3095 jobs.new() directly.
3095 jobs.new() directly.
3096
3096
3097 The jobs.new docstring also describes in detail several important
3097 The jobs.new docstring also describes in detail several important
3098 caveats associated with a thread-based model for background job
3098 caveats associated with a thread-based model for background job
3099 execution. Type jobs.new? for details.
3099 execution. Type jobs.new? for details.
3100
3100
3101 You can check the status of all jobs with jobs.status().
3101 You can check the status of all jobs with jobs.status().
3102
3102
3103 The jobs variable is set by IPython into the Python builtin namespace.
3103 The jobs variable is set by IPython into the Python builtin namespace.
3104 If you ever declare a variable named 'jobs', you will shadow this
3104 If you ever declare a variable named 'jobs', you will shadow this
3105 name. You can either delete your global jobs variable to regain
3105 name. You can either delete your global jobs variable to regain
3106 access to the job manager, or make a new name and assign it manually
3106 access to the job manager, or make a new name and assign it manually
3107 to the manager (stored in IPython's namespace). For example, to
3107 to the manager (stored in IPython's namespace). For example, to
3108 assign the job manager to the Jobs name, use:
3108 assign the job manager to the Jobs name, use:
3109
3109
3110 Jobs = __builtins__.jobs"""
3110 Jobs = __builtins__.jobs"""
3111
3111
3112 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3112 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3113
3113
3114 def magic_r(self, parameter_s=''):
3114 def magic_r(self, parameter_s=''):
3115 """Repeat previous input.
3115 """Repeat previous input.
3116
3116
3117 Note: Consider using the more powerfull %rep instead!
3117 Note: Consider using the more powerfull %rep instead!
3118
3118
3119 If given an argument, repeats the previous command which starts with
3119 If given an argument, repeats the previous command which starts with
3120 the same string, otherwise it just repeats the previous input.
3120 the same string, otherwise it just repeats the previous input.
3121
3121
3122 Shell escaped commands (with ! as first character) are not recognized
3122 Shell escaped commands (with ! as first character) are not recognized
3123 by this system, only pure python code and magic commands.
3123 by this system, only pure python code and magic commands.
3124 """
3124 """
3125
3125
3126 start = parameter_s.strip()
3126 start = parameter_s.strip()
3127 esc_magic = ESC_MAGIC
3127 esc_magic = ESC_MAGIC
3128 # Identify magic commands even if automagic is on (which means
3128 # Identify magic commands even if automagic is on (which means
3129 # the in-memory version is different from that typed by the user).
3129 # the in-memory version is different from that typed by the user).
3130 if self.shell.automagic:
3130 if self.shell.automagic:
3131 start_magic = esc_magic+start
3131 start_magic = esc_magic+start
3132 else:
3132 else:
3133 start_magic = start
3133 start_magic = start
3134 # Look through the input history in reverse
3134 # Look through the input history in reverse
3135 for n in range(len(self.shell.input_hist)-2,0,-1):
3135 for n in range(len(self.shell.input_hist)-2,0,-1):
3136 input = self.shell.input_hist[n]
3136 input = self.shell.input_hist[n]
3137 # skip plain 'r' lines so we don't recurse to infinity
3137 # skip plain 'r' lines so we don't recurse to infinity
3138 if input != '_ip.magic("r")\n' and \
3138 if input != '_ip.magic("r")\n' and \
3139 (input.startswith(start) or input.startswith(start_magic)):
3139 (input.startswith(start) or input.startswith(start_magic)):
3140 #print 'match',`input` # dbg
3140 #print 'match',`input` # dbg
3141 print 'Executing:',input,
3141 print 'Executing:',input,
3142 self.shell.runlines(input)
3142 self.shell.runlines(input)
3143 return
3143 return
3144 print 'No previous input matching `%s` found.' % start
3144 print 'No previous input matching `%s` found.' % start
3145
3145
3146
3146
3147 def magic_bookmark(self, parameter_s=''):
3147 def magic_bookmark(self, parameter_s=''):
3148 """Manage IPython's bookmark system.
3148 """Manage IPython's bookmark system.
3149
3149
3150 %bookmark <name> - set bookmark to current dir
3150 %bookmark <name> - set bookmark to current dir
3151 %bookmark <name> <dir> - set bookmark to <dir>
3151 %bookmark <name> <dir> - set bookmark to <dir>
3152 %bookmark -l - list all bookmarks
3152 %bookmark -l - list all bookmarks
3153 %bookmark -d <name> - remove bookmark
3153 %bookmark -d <name> - remove bookmark
3154 %bookmark -r - remove all bookmarks
3154 %bookmark -r - remove all bookmarks
3155
3155
3156 You can later on access a bookmarked folder with:
3156 You can later on access a bookmarked folder with:
3157 %cd -b <name>
3157 %cd -b <name>
3158 or simply '%cd <name>' if there is no directory called <name> AND
3158 or simply '%cd <name>' if there is no directory called <name> AND
3159 there is such a bookmark defined.
3159 there is such a bookmark defined.
3160
3160
3161 Your bookmarks persist through IPython sessions, but they are
3161 Your bookmarks persist through IPython sessions, but they are
3162 associated with each profile."""
3162 associated with each profile."""
3163
3163
3164 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3164 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3165 if len(args) > 2:
3165 if len(args) > 2:
3166 raise UsageError("%bookmark: too many arguments")
3166 raise UsageError("%bookmark: too many arguments")
3167
3167
3168 bkms = self.db.get('bookmarks',{})
3168 bkms = self.db.get('bookmarks',{})
3169
3169
3170 if opts.has_key('d'):
3170 if opts.has_key('d'):
3171 try:
3171 try:
3172 todel = args[0]
3172 todel = args[0]
3173 except IndexError:
3173 except IndexError:
3174 raise UsageError(
3174 raise UsageError(
3175 "%bookmark -d: must provide a bookmark to delete")
3175 "%bookmark -d: must provide a bookmark to delete")
3176 else:
3176 else:
3177 try:
3177 try:
3178 del bkms[todel]
3178 del bkms[todel]
3179 except KeyError:
3179 except KeyError:
3180 raise UsageError(
3180 raise UsageError(
3181 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3181 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3182
3182
3183 elif opts.has_key('r'):
3183 elif opts.has_key('r'):
3184 bkms = {}
3184 bkms = {}
3185 elif opts.has_key('l'):
3185 elif opts.has_key('l'):
3186 bks = bkms.keys()
3186 bks = bkms.keys()
3187 bks.sort()
3187 bks.sort()
3188 if bks:
3188 if bks:
3189 size = max(map(len,bks))
3189 size = max(map(len,bks))
3190 else:
3190 else:
3191 size = 0
3191 size = 0
3192 fmt = '%-'+str(size)+'s -> %s'
3192 fmt = '%-'+str(size)+'s -> %s'
3193 print 'Current bookmarks:'
3193 print 'Current bookmarks:'
3194 for bk in bks:
3194 for bk in bks:
3195 print fmt % (bk,bkms[bk])
3195 print fmt % (bk,bkms[bk])
3196 else:
3196 else:
3197 if not args:
3197 if not args:
3198 raise UsageError("%bookmark: You must specify the bookmark name")
3198 raise UsageError("%bookmark: You must specify the bookmark name")
3199 elif len(args)==1:
3199 elif len(args)==1:
3200 bkms[args[0]] = os.getcwd()
3200 bkms[args[0]] = os.getcwd()
3201 elif len(args)==2:
3201 elif len(args)==2:
3202 bkms[args[0]] = args[1]
3202 bkms[args[0]] = args[1]
3203 self.db['bookmarks'] = bkms
3203 self.db['bookmarks'] = bkms
3204
3204
3205 def magic_pycat(self, parameter_s=''):
3205 def magic_pycat(self, parameter_s=''):
3206 """Show a syntax-highlighted file through a pager.
3206 """Show a syntax-highlighted file through a pager.
3207
3207
3208 This magic is similar to the cat utility, but it will assume the file
3208 This magic is similar to the cat utility, but it will assume the file
3209 to be Python source and will show it with syntax highlighting. """
3209 to be Python source and will show it with syntax highlighting. """
3210
3210
3211 try:
3211 try:
3212 filename = get_py_filename(parameter_s)
3212 filename = get_py_filename(parameter_s)
3213 cont = file_read(filename)
3213 cont = file_read(filename)
3214 except IOError:
3214 except IOError:
3215 try:
3215 try:
3216 cont = eval(parameter_s,self.user_ns)
3216 cont = eval(parameter_s,self.user_ns)
3217 except NameError:
3217 except NameError:
3218 cont = None
3218 cont = None
3219 if cont is None:
3219 if cont is None:
3220 print "Error: no such file or variable"
3220 print "Error: no such file or variable"
3221 return
3221 return
3222
3222
3223 page(self.shell.pycolorize(cont),
3223 page(self.shell.pycolorize(cont),
3224 screen_lines=self.shell.usable_screen_length)
3224 screen_lines=self.shell.usable_screen_length)
3225
3225
3226 def _rerun_pasted(self):
3226 def _rerun_pasted(self):
3227 """ Rerun a previously pasted command.
3227 """ Rerun a previously pasted command.
3228 """
3228 """
3229 b = self.user_ns.get('pasted_block', None)
3229 b = self.user_ns.get('pasted_block', None)
3230 if b is None:
3230 if b is None:
3231 raise UsageError('No previous pasted block available')
3231 raise UsageError('No previous pasted block available')
3232 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3232 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3233 exec b in self.user_ns
3233 exec b in self.user_ns
3234
3234
3235 def _get_pasted_lines(self, sentinel):
3235 def _get_pasted_lines(self, sentinel):
3236 """ Yield pasted lines until the user enters the given sentinel value.
3236 """ Yield pasted lines until the user enters the given sentinel value.
3237 """
3237 """
3238 from IPython.core import iplib
3238 from IPython.core import iplib
3239 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3239 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3240 while True:
3240 while True:
3241 l = iplib.raw_input_original(':')
3241 l = iplib.raw_input_original(':')
3242 if l == sentinel:
3242 if l == sentinel:
3243 return
3243 return
3244 else:
3244 else:
3245 yield l
3245 yield l
3246
3246
3247 def _strip_pasted_lines_for_code(self, raw_lines):
3247 def _strip_pasted_lines_for_code(self, raw_lines):
3248 """ Strip non-code parts of a sequence of lines to return a block of
3248 """ Strip non-code parts of a sequence of lines to return a block of
3249 code.
3249 code.
3250 """
3250 """
3251 # Regular expressions that declare text we strip from the input:
3251 # Regular expressions that declare text we strip from the input:
3252 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3252 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3253 r'^\s*(\s?>)+', # Python input prompt
3253 r'^\s*(\s?>)+', # Python input prompt
3254 r'^\s*\.{3,}', # Continuation prompts
3254 r'^\s*\.{3,}', # Continuation prompts
3255 r'^\++',
3255 r'^\++',
3256 ]
3256 ]
3257
3257
3258 strip_from_start = map(re.compile,strip_re)
3258 strip_from_start = map(re.compile,strip_re)
3259
3259
3260 lines = []
3260 lines = []
3261 for l in raw_lines:
3261 for l in raw_lines:
3262 for pat in strip_from_start:
3262 for pat in strip_from_start:
3263 l = pat.sub('',l)
3263 l = pat.sub('',l)
3264 lines.append(l)
3264 lines.append(l)
3265
3265
3266 block = "\n".join(lines) + '\n'
3266 block = "\n".join(lines) + '\n'
3267 #print "block:\n",block
3267 #print "block:\n",block
3268 return block
3268 return block
3269
3269
3270 def _execute_block(self, block, par):
3270 def _execute_block(self, block, par):
3271 """ Execute a block, or store it in a variable, per the user's request.
3271 """ Execute a block, or store it in a variable, per the user's request.
3272 """
3272 """
3273 if not par:
3273 if not par:
3274 b = textwrap.dedent(block)
3274 b = textwrap.dedent(block)
3275 self.user_ns['pasted_block'] = b
3275 self.user_ns['pasted_block'] = b
3276 exec b in self.user_ns
3276 exec b in self.user_ns
3277 else:
3277 else:
3278 self.user_ns[par] = SList(block.splitlines())
3278 self.user_ns[par] = SList(block.splitlines())
3279 print "Block assigned to '%s'" % par
3279 print "Block assigned to '%s'" % par
3280
3280
3281 def magic_cpaste(self, parameter_s=''):
3281 def magic_cpaste(self, parameter_s=''):
3282 """Allows you to paste & execute a pre-formatted code block from clipboard.
3282 """Allows you to paste & execute a pre-formatted code block from clipboard.
3283
3283
3284 You must terminate the block with '--' (two minus-signs) alone on the
3284 You must terminate the block with '--' (two minus-signs) alone on the
3285 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3285 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3286 is the new sentinel for this operation)
3286 is the new sentinel for this operation)
3287
3287
3288 The block is dedented prior to execution to enable execution of method
3288 The block is dedented prior to execution to enable execution of method
3289 definitions. '>' and '+' characters at the beginning of a line are
3289 definitions. '>' and '+' characters at the beginning of a line are
3290 ignored, to allow pasting directly from e-mails, diff files and
3290 ignored, to allow pasting directly from e-mails, diff files and
3291 doctests (the '...' continuation prompt is also stripped). The
3291 doctests (the '...' continuation prompt is also stripped). The
3292 executed block is also assigned to variable named 'pasted_block' for
3292 executed block is also assigned to variable named 'pasted_block' for
3293 later editing with '%edit pasted_block'.
3293 later editing with '%edit pasted_block'.
3294
3294
3295 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3295 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3296 This assigns the pasted block to variable 'foo' as string, without
3296 This assigns the pasted block to variable 'foo' as string, without
3297 dedenting or executing it (preceding >>> and + is still stripped)
3297 dedenting or executing it (preceding >>> and + is still stripped)
3298
3298
3299 '%cpaste -r' re-executes the block previously entered by cpaste.
3299 '%cpaste -r' re-executes the block previously entered by cpaste.
3300
3300
3301 Do not be alarmed by garbled output on Windows (it's a readline bug).
3301 Do not be alarmed by garbled output on Windows (it's a readline bug).
3302 Just press enter and type -- (and press enter again) and the block
3302 Just press enter and type -- (and press enter again) and the block
3303 will be what was just pasted.
3303 will be what was just pasted.
3304
3304
3305 IPython statements (magics, shell escapes) are not supported (yet).
3305 IPython statements (magics, shell escapes) are not supported (yet).
3306
3306
3307 See also
3307 See also
3308 --------
3308 --------
3309 paste: automatically pull code from clipboard.
3309 paste: automatically pull code from clipboard.
3310 """
3310 """
3311
3311
3312 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3312 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3313 par = args.strip()
3313 par = args.strip()
3314 if opts.has_key('r'):
3314 if opts.has_key('r'):
3315 self._rerun_pasted()
3315 self._rerun_pasted()
3316 return
3316 return
3317
3317
3318 sentinel = opts.get('s','--')
3318 sentinel = opts.get('s','--')
3319
3319
3320 block = self._strip_pasted_lines_for_code(
3320 block = self._strip_pasted_lines_for_code(
3321 self._get_pasted_lines(sentinel))
3321 self._get_pasted_lines(sentinel))
3322
3322
3323 self._execute_block(block, par)
3323 self._execute_block(block, par)
3324
3324
3325 def magic_paste(self, parameter_s=''):
3325 def magic_paste(self, parameter_s=''):
3326 """Allows you to paste & execute a pre-formatted code block from clipboard.
3326 """Allows you to paste & execute a pre-formatted code block from clipboard.
3327
3327
3328 The text is pulled directly from the clipboard without user
3328 The text is pulled directly from the clipboard without user
3329 intervention and printed back on the screen before execution (unless
3329 intervention and printed back on the screen before execution (unless
3330 the -q flag is given to force quiet mode).
3330 the -q flag is given to force quiet mode).
3331
3331
3332 The block is dedented prior to execution to enable execution of method
3332 The block is dedented prior to execution to enable execution of method
3333 definitions. '>' and '+' characters at the beginning of a line are
3333 definitions. '>' and '+' characters at the beginning of a line are
3334 ignored, to allow pasting directly from e-mails, diff files and
3334 ignored, to allow pasting directly from e-mails, diff files and
3335 doctests (the '...' continuation prompt is also stripped). The
3335 doctests (the '...' continuation prompt is also stripped). The
3336 executed block is also assigned to variable named 'pasted_block' for
3336 executed block is also assigned to variable named 'pasted_block' for
3337 later editing with '%edit pasted_block'.
3337 later editing with '%edit pasted_block'.
3338
3338
3339 You can also pass a variable name as an argument, e.g. '%paste foo'.
3339 You can also pass a variable name as an argument, e.g. '%paste foo'.
3340 This assigns the pasted block to variable 'foo' as string, without
3340 This assigns the pasted block to variable 'foo' as string, without
3341 dedenting or executing it (preceding >>> and + is still stripped)
3341 dedenting or executing it (preceding >>> and + is still stripped)
3342
3342
3343 Options
3343 Options
3344 -------
3344 -------
3345
3345
3346 -r: re-executes the block previously entered by cpaste.
3346 -r: re-executes the block previously entered by cpaste.
3347
3347
3348 -q: quiet mode: do not echo the pasted text back to the terminal.
3348 -q: quiet mode: do not echo the pasted text back to the terminal.
3349
3349
3350 IPython statements (magics, shell escapes) are not supported (yet).
3350 IPython statements (magics, shell escapes) are not supported (yet).
3351
3351
3352 See also
3352 See also
3353 --------
3353 --------
3354 cpaste: manually paste code into terminal until you mark its end.
3354 cpaste: manually paste code into terminal until you mark its end.
3355 """
3355 """
3356 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3356 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3357 par = args.strip()
3357 par = args.strip()
3358 if opts.has_key('r'):
3358 if opts.has_key('r'):
3359 self._rerun_pasted()
3359 self._rerun_pasted()
3360 return
3360 return
3361
3361
3362 text = self.shell.hooks.clipboard_get()
3362 text = self.shell.hooks.clipboard_get()
3363 block = self._strip_pasted_lines_for_code(text.splitlines())
3363 block = self._strip_pasted_lines_for_code(text.splitlines())
3364
3364
3365 # By default, echo back to terminal unless quiet mode is requested
3365 # By default, echo back to terminal unless quiet mode is requested
3366 if not opts.has_key('q'):
3366 if not opts.has_key('q'):
3367 write = self.shell.write
3367 write = self.shell.write
3368 write(block)
3368 write(block)
3369 if not block.endswith('\n'):
3369 if not block.endswith('\n'):
3370 write('\n')
3370 write('\n')
3371 write("## -- End pasted text --\n")
3371 write("## -- End pasted text --\n")
3372
3372
3373 self._execute_block(block, par)
3373 self._execute_block(block, par)
3374
3374
3375 def magic_quickref(self,arg):
3375 def magic_quickref(self,arg):
3376 """ Show a quick reference sheet """
3376 """ Show a quick reference sheet """
3377 import IPython.core.usage
3377 import IPython.core.usage
3378 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3378 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3379
3379
3380 page(qr)
3380 page(qr)
3381
3381
3382 def magic_upgrade(self,arg):
3382 def magic_upgrade(self,arg):
3383 """ Upgrade your IPython installation
3383 """ Upgrade your IPython installation
3384
3384
3385 This will copy the config files that don't yet exist in your
3385 This will copy the config files that don't yet exist in your
3386 ipython dir from the system config dir. Use this after upgrading
3386 ipython dir from the system config dir. Use this after upgrading
3387 IPython if you don't wish to delete your .ipython dir.
3387 IPython if you don't wish to delete your .ipython dir.
3388
3388
3389 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3389 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3390 new users)
3390 new users)
3391
3391
3392 """
3392 """
3393 ip = self.getapi()
3393 ip = self.getapi()
3394 ipinstallation = path(IPython.__file__).dirname()
3394 ipinstallation = path(IPython.__file__).dirname()
3395 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'utils' / 'upgradedir.py')
3395 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'utils' / 'upgradedir.py')
3396 src_config = ipinstallation / 'config' / 'userconfig'
3396 src_config = ipinstallation / 'config' / 'userconfig'
3397 userdir = path(ip.config.IPYTHONDIR)
3397 userdir = path(ip.config.IPYTHONDIR)
3398 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3398 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3399 print ">",cmd
3399 print ">",cmd
3400 shell(cmd)
3400 shell(cmd)
3401 if arg == '-nolegacy':
3401 if arg == '-nolegacy':
3402 legacy = userdir.files('ipythonrc*')
3402 legacy = userdir.files('ipythonrc*')
3403 print "Nuking legacy files:",legacy
3403 print "Nuking legacy files:",legacy
3404
3404
3405 [p.remove() for p in legacy]
3405 [p.remove() for p in legacy]
3406 suffix = (sys.platform == 'win32' and '.ini' or '')
3406 suffix = (sys.platform == 'win32' and '.ini' or '')
3407 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3407 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3408
3408
3409
3409
3410 def magic_doctest_mode(self,parameter_s=''):
3410 def magic_doctest_mode(self,parameter_s=''):
3411 """Toggle doctest mode on and off.
3411 """Toggle doctest mode on and off.
3412
3412
3413 This mode allows you to toggle the prompt behavior between normal
3413 This mode allows you to toggle the prompt behavior between normal
3414 IPython prompts and ones that are as similar to the default IPython
3414 IPython prompts and ones that are as similar to the default IPython
3415 interpreter as possible.
3415 interpreter as possible.
3416
3416
3417 It also supports the pasting of code snippets that have leading '>>>'
3417 It also supports the pasting of code snippets that have leading '>>>'
3418 and '...' prompts in them. This means that you can paste doctests from
3418 and '...' prompts in them. This means that you can paste doctests from
3419 files or docstrings (even if they have leading whitespace), and the
3419 files or docstrings (even if they have leading whitespace), and the
3420 code will execute correctly. You can then use '%history -tn' to see
3420 code will execute correctly. You can then use '%history -tn' to see
3421 the translated history without line numbers; this will give you the
3421 the translated history without line numbers; this will give you the
3422 input after removal of all the leading prompts and whitespace, which
3422 input after removal of all the leading prompts and whitespace, which
3423 can be pasted back into an editor.
3423 can be pasted back into an editor.
3424
3424
3425 With these features, you can switch into this mode easily whenever you
3425 With these features, you can switch into this mode easily whenever you
3426 need to do testing and changes to doctests, without having to leave
3426 need to do testing and changes to doctests, without having to leave
3427 your existing IPython session.
3427 your existing IPython session.
3428 """
3428 """
3429
3429
3430 # XXX - Fix this to have cleaner activate/deactivate calls.
3430 # XXX - Fix this to have cleaner activate/deactivate calls.
3431 from IPython.extensions import InterpreterPasteInput as ipaste
3431 from IPython.extensions import InterpreterPasteInput as ipaste
3432 from IPython.utils.ipstruct import Struct
3432 from IPython.utils.ipstruct import Struct
3433
3433
3434 # Shorthands
3434 # Shorthands
3435 shell = self.shell
3435 shell = self.shell
3436 oc = shell.outputcache
3436 oc = shell.outputcache
3437 meta = shell.meta
3437 meta = shell.meta
3438 # dstore is a data store kept in the instance metadata bag to track any
3438 # dstore is a data store kept in the instance metadata bag to track any
3439 # changes we make, so we can undo them later.
3439 # changes we make, so we can undo them later.
3440 dstore = meta.setdefault('doctest_mode',Struct())
3440 dstore = meta.setdefault('doctest_mode',Struct())
3441 save_dstore = dstore.setdefault
3441 save_dstore = dstore.setdefault
3442
3442
3443 # save a few values we'll need to recover later
3443 # save a few values we'll need to recover later
3444 mode = save_dstore('mode',False)
3444 mode = save_dstore('mode',False)
3445 save_dstore('rc_pprint',shell.pprint)
3445 save_dstore('rc_pprint',shell.pprint)
3446 save_dstore('xmode',shell.InteractiveTB.mode)
3446 save_dstore('xmode',shell.InteractiveTB.mode)
3447 save_dstore('rc_separate_out',shell.separate_out)
3447 save_dstore('rc_separate_out',shell.separate_out)
3448 save_dstore('rc_separate_out2',shell.separate_out2)
3448 save_dstore('rc_separate_out2',shell.separate_out2)
3449 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3449 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3450 save_dstore('rc_separate_in',shell.separate_in)
3450 save_dstore('rc_separate_in',shell.separate_in)
3451
3451
3452 if mode == False:
3452 if mode == False:
3453 # turn on
3453 # turn on
3454 ipaste.activate_prefilter()
3454 ipaste.activate_prefilter()
3455
3455
3456 oc.prompt1.p_template = '>>> '
3456 oc.prompt1.p_template = '>>> '
3457 oc.prompt2.p_template = '... '
3457 oc.prompt2.p_template = '... '
3458 oc.prompt_out.p_template = ''
3458 oc.prompt_out.p_template = ''
3459
3459
3460 # Prompt separators like plain python
3460 # Prompt separators like plain python
3461 oc.input_sep = oc.prompt1.sep = ''
3461 oc.input_sep = oc.prompt1.sep = ''
3462 oc.output_sep = ''
3462 oc.output_sep = ''
3463 oc.output_sep2 = ''
3463 oc.output_sep2 = ''
3464
3464
3465 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3465 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3466 oc.prompt_out.pad_left = False
3466 oc.prompt_out.pad_left = False
3467
3467
3468 shell.pprint = False
3468 shell.pprint = False
3469
3469
3470 shell.magic_xmode('Plain')
3470 shell.magic_xmode('Plain')
3471
3471
3472 else:
3472 else:
3473 # turn off
3473 # turn off
3474 ipaste.deactivate_prefilter()
3474 ipaste.deactivate_prefilter()
3475
3475
3476 oc.prompt1.p_template = shell.prompt_in1
3476 oc.prompt1.p_template = shell.prompt_in1
3477 oc.prompt2.p_template = shell.prompt_in2
3477 oc.prompt2.p_template = shell.prompt_in2
3478 oc.prompt_out.p_template = shell.prompt_out
3478 oc.prompt_out.p_template = shell.prompt_out
3479
3479
3480 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3480 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3481
3481
3482 oc.output_sep = dstore.rc_separate_out
3482 oc.output_sep = dstore.rc_separate_out
3483 oc.output_sep2 = dstore.rc_separate_out2
3483 oc.output_sep2 = dstore.rc_separate_out2
3484
3484
3485 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3485 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3486 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3486 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3487
3487
3488 rc.pprint = dstore.rc_pprint
3488 rc.pprint = dstore.rc_pprint
3489
3489
3490 shell.magic_xmode(dstore.xmode)
3490 shell.magic_xmode(dstore.xmode)
3491
3491
3492 # Store new mode and inform
3492 # Store new mode and inform
3493 dstore.mode = bool(1-int(mode))
3493 dstore.mode = bool(1-int(mode))
3494 print 'Doctest mode is:',
3494 print 'Doctest mode is:',
3495 print ['OFF','ON'][dstore.mode]
3495 print ['OFF','ON'][dstore.mode]
3496
3496
3497 def magic_gui(self, parameter_s=''):
3497 def magic_gui(self, parameter_s=''):
3498 """Enable or disable IPython GUI event loop integration.
3498 """Enable or disable IPython GUI event loop integration.
3499
3499
3500 %gui [-a] [GUINAME]
3500 %gui [-a] [GUINAME]
3501
3501
3502 This magic replaces IPython's threaded shells that were activated
3502 This magic replaces IPython's threaded shells that were activated
3503 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3503 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3504 can now be enabled, disabled and swtiched at runtime and keyboard
3504 can now be enabled, disabled and swtiched at runtime and keyboard
3505 interrupts should work without any problems. The following toolkits
3505 interrupts should work without any problems. The following toolkits
3506 are supports: wxPython, PyQt4, PyGTK, and Tk::
3506 are supports: wxPython, PyQt4, PyGTK, and Tk::
3507
3507
3508 %gui wx # enable wxPython event loop integration
3508 %gui wx # enable wxPython event loop integration
3509 %gui qt4|qt # enable PyQt4 event loop integration
3509 %gui qt4|qt # enable PyQt4 event loop integration
3510 %gui gtk # enable PyGTK event loop integration
3510 %gui gtk # enable PyGTK event loop integration
3511 %gui tk # enable Tk event loop integration
3511 %gui tk # enable Tk event loop integration
3512 %gui # disable all event loop integration
3512 %gui # disable all event loop integration
3513
3513
3514 WARNING: after any of these has been called you can simply create
3514 WARNING: after any of these has been called you can simply create
3515 an application object, but DO NOT start the event loop yourself, as
3515 an application object, but DO NOT start the event loop yourself, as
3516 we have already handled that.
3516 we have already handled that.
3517
3517
3518 If you want us to create an appropriate application object add the
3518 If you want us to create an appropriate application object add the
3519 "-a" flag to your command::
3519 "-a" flag to your command::
3520
3520
3521 %gui -a wx
3521 %gui -a wx
3522
3522
3523 This is highly recommended for most users.
3523 This is highly recommended for most users.
3524 """
3524 """
3525 from IPython.lib import inputhook
3525 from IPython.lib import inputhook
3526 if "-a" in parameter_s:
3526 if "-a" in parameter_s:
3527 app = True
3527 app = True
3528 else:
3528 else:
3529 app = False
3529 app = False
3530 if not parameter_s:
3530 if not parameter_s:
3531 inputhook.clear_inputhook()
3531 inputhook.clear_inputhook()
3532 elif 'wx' in parameter_s:
3532 elif 'wx' in parameter_s:
3533 return inputhook.enable_wx(app)
3533 return inputhook.enable_wx(app)
3534 elif ('qt4' in parameter_s) or ('qt' in parameter_s):
3534 elif ('qt4' in parameter_s) or ('qt' in parameter_s):
3535 return inputhook.enable_qt4(app)
3535 return inputhook.enable_qt4(app)
3536 elif 'gtk' in parameter_s:
3536 elif 'gtk' in parameter_s:
3537 return inputhook.enable_gtk(app)
3537 return inputhook.enable_gtk(app)
3538 elif 'tk' in parameter_s:
3538 elif 'tk' in parameter_s:
3539 return inputhook.enable_tk(app)
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 # end Magic
3553 # end Magic
@@ -1,134 +1,136 b''
1 .. _configuring_ipython:
1 .. _configuring_ipython:
2
2
3 ===========================================================
3 ===========================================================
4 Configuring the :command:`ipython` command line application
4 Configuring the :command:`ipython` command line application
5 ===========================================================
5 ===========================================================
6
6
7 This section contains information about how to configure the
7 This section contains information about how to configure the
8 :command:`ipython` command line application. See the :ref:`configuration
8 :command:`ipython` command line application. See the :ref:`configuration
9 overview <config_overview>` for a more general description of the
9 overview <config_overview>` for a more general description of the
10 configuration system and configuration file format.
10 configuration system and configuration file format.
11
11
12 The default configuration file for the :command:`ipython` command line application
12 The default configuration file for the :command:`ipython` command line application
13 is :file:`ipython_config.py`. By setting the attributes in this file, you
13 is :file:`ipython_config.py`. By setting the attributes in this file, you
14 can configure the application. A sample is provided in
14 can configure the application. A sample is provided in
15 :mod:`IPython.config.default.ipython_config`. Simply copy this file to your
15 :mod:`IPython.config.default.ipython_config`. Simply copy this file to your
16 IPython directory to start using it.
16 IPython directory to start using it.
17
17
18 Most configuration attributes that this file accepts are associated with
18 Most configuration attributes that this file accepts are associated with
19 classes that are subclasses of :class:`~IPython.core.component.Component`.
19 classes that are subclasses of :class:`~IPython.core.component.Component`.
20
20
21 A few configuration attributes are not associated with a particular
21 A few configuration attributes are not associated with a particular
22 :class:`~IPython.core.component.Component` subclass. These are application
22 :class:`~IPython.core.component.Component` subclass. These are application
23 wide configuration attributes and are stored in the ``Global``
23 wide configuration attributes and are stored in the ``Global``
24 sub-configuration section. We begin with a description of these
24 sub-configuration section. We begin with a description of these
25 attributes.
25 attributes.
26
26
27 Global configuration
27 Global configuration
28 ====================
28 ====================
29
29
30 Assuming that your configuration file has the following at the top::
30 Assuming that your configuration file has the following at the top::
31
31
32 c = get_config()
32 c = get_config()
33
33
34 the following attributes can be set in the ``Global`` section.
34 the following attributes can be set in the ``Global`` section.
35
35
36 :attr:`c.Global.display_banner`
36 :attr:`c.Global.display_banner`
37 A boolean that determined if the banner is printer when :command:`ipython`
37 A boolean that determined if the banner is printer when :command:`ipython`
38 is started.
38 is started.
39
39
40 :attr:`c.Global.classic`
40 :attr:`c.Global.classic`
41 A boolean that determines if IPython starts in "classic" mode. In this
41 A boolean that determines if IPython starts in "classic" mode. In this
42 mode, the prompts and everything mimic that of the normal :command:`python`
42 mode, the prompts and everything mimic that of the normal :command:`python`
43 shell
43 shell
44
44
45 :attr:`c.Global.nosep`
45 :attr:`c.Global.nosep`
46 A boolean that determines if there should be no blank lines between
46 A boolean that determines if there should be no blank lines between
47 prompts.
47 prompts.
48
48
49 :attr:`c.Global.log_level`
49 :attr:`c.Global.log_level`
50 An integer that sets the detail of the logging level during the startup
50 An integer that sets the detail of the logging level during the startup
51 of :command:`ipython`. The default is 30 and the possible values are
51 of :command:`ipython`. The default is 30 and the possible values are
52 (0, 10, 20, 30, 40, 50). Higher is quieter and lower is more verbose.
52 (0, 10, 20, 30, 40, 50). Higher is quieter and lower is more verbose.
53
53
54 :attr:`c.Global.extensions`
54 :attr:`c.Global.extensions`
55 A list of strings, each of which is an importable IPython extension. An
55 A list of strings, each of which is an importable IPython extension. An
56 IPython extension is a regular Python module or package that has a
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
57 :func:`load_ipython_extension(ip)` method. This method gets called when
58 extension is loaded with the currently running
58 the extension is loaded with the currently running
59 :class:`~IPython.core.iplib.InteractiveShell` as its only argument. You
59 :class:`~IPython.core.iplib.InteractiveShell` as its only argument. You
60 can put your extensions anywhere they can be imported but we add the
60 can put your extensions anywhere they can be imported but we add the
61 :file:`extensions` subdirectory of the ipython directory to ``sys.path``
61 :file:`extensions` subdirectory of the ipython directory to ``sys.path``
62 during extension loading, so you can put them there as well. Extensions
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
63 are not executed in the user's interactive namespace and they must be pure
64 be pure Python code. Extensions are the recommended way of customizing
64 Python code. Extensions are the recommended way of customizing
65 :command:`ipython`.
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 :attr:`c.Global.exec_lines`
69 :attr:`c.Global.exec_lines`
68 A list of strings, each of which is Python code that is run in the user's
70 A list of strings, each of which is Python code that is run in the user's
69 namespace after IPython start. These lines can contain full IPython syntax
71 namespace after IPython start. These lines can contain full IPython syntax
70 with magics, etc.
72 with magics, etc.
71
73
72 :attr:`c.Global.exec_files`
74 :attr:`c.Global.exec_files`
73 A list of strings, each of which is the full pathname of a ``.py`` or
75 A list of strings, each of which is the full pathname of a ``.py`` or
74 ``.ipy`` file that will be executed as IPython starts. These files are run
76 ``.ipy`` file that will be executed as IPython starts. These files are run
75 in IPython in the user's namespace. Files with a ``.py`` extension need to
77 in IPython in the user's namespace. Files with a ``.py`` extension need to
76 be pure Python. Files with a ``.ipy`` extension can have custom IPython
78 be pure Python. Files with a ``.ipy`` extension can have custom IPython
77 syntax (magics, etc.). These files need to be in the cwd, the ipythondir
79 syntax (magics, etc.). These files need to be in the cwd, the ipythondir
78 or be absolute paths.
80 or be absolute paths.
79
81
80 Classes that can be configured
82 Classes that can be configured
81 ==============================
83 ==============================
82
84
83 The following classes can also be configured in the configuration file for
85 The following classes can also be configured in the configuration file for
84 :command:`ipython`:
86 :command:`ipython`:
85
87
86 * :class:`~IPython.core.iplib.InteractiveShell`
88 * :class:`~IPython.core.iplib.InteractiveShell`
87
89
88 * :class:`~IPython.core.prefilter.PrefilterManager`
90 * :class:`~IPython.core.prefilter.PrefilterManager`
89
91
90 * :class:`~IPython.core.alias.AliasManager`
92 * :class:`~IPython.core.alias.AliasManager`
91
93
92 To see which attributes of these classes are configurable, please see the
94 To see which attributes of these classes are configurable, please see the
93 source code for these classes, the class docstrings or the sample
95 source code for these classes, the class docstrings or the sample
94 configuration file :mod:`IPython.config.default.ipython_config`.
96 configuration file :mod:`IPython.config.default.ipython_config`.
95
97
96 Example
98 Example
97 =======
99 =======
98
100
99 For those who want to get a quick start, here is a sample
101 For those who want to get a quick start, here is a sample
100 :file:`ipython_config.py` that sets some of the common configuration
102 :file:`ipython_config.py` that sets some of the common configuration
101 attributes::
103 attributes::
102
104
103 # sample ipython_config.py
105 # sample ipython_config.py
104 c = get_config()
106 c = get_config()
105
107
106 c.Global.display_banner = True
108 c.Global.display_banner = True
107 c.Global.log_level = 20
109 c.Global.log_level = 20
108 c.Global.extensions = [
110 c.Global.extensions = [
109 'myextension'
111 'myextension'
110 ]
112 ]
111 c.Global.exec_lines = [
113 c.Global.exec_lines = [
112 'import numpy',
114 'import numpy',
113 'import scipy'
115 'import scipy'
114 ]
116 ]
115 c.Global.exec_files = [
117 c.Global.exec_files = [
116 'mycode.py',
118 'mycode.py',
117 'fancy.ipy'
119 'fancy.ipy'
118 ]
120 ]
119 c.InteractiveShell.autoindent = True
121 c.InteractiveShell.autoindent = True
120 c.InteractiveShell.colors = 'LightBG'
122 c.InteractiveShell.colors = 'LightBG'
121 c.InteractiveShell.confirm_exit = False
123 c.InteractiveShell.confirm_exit = False
122 c.InteractiveShell.deep_reload = True
124 c.InteractiveShell.deep_reload = True
123 c.InteractiveShell.editor = 'nano'
125 c.InteractiveShell.editor = 'nano'
124 c.InteractiveShell.prompt_in1 = 'In [\#]: '
126 c.InteractiveShell.prompt_in1 = 'In [\#]: '
125 c.InteractiveShell.prompt_in2 = ' .\D.: '
127 c.InteractiveShell.prompt_in2 = ' .\D.: '
126 c.InteractiveShell.prompt_out = 'Out[\#]: '
128 c.InteractiveShell.prompt_out = 'Out[\#]: '
127 c.InteractiveShell.prompts_pad_left = True
129 c.InteractiveShell.prompts_pad_left = True
128 c.InteractiveShell.xmode = 'Context'
130 c.InteractiveShell.xmode = 'Context'
129
131
130 c.PrefilterManager.multi_line_specials = True
132 c.PrefilterManager.multi_line_specials = True
131
133
132 c.AliasManager.user_aliases = [
134 c.AliasManager.user_aliases = [
133 ('la', 'ls -al')
135 ('la', 'ls -al')
134 ] No newline at end of file
136 ]
1 NO CONTENT: file was removed
NO CONTENT: file was removed
General Comments 0
You need to be logged in to leave comments. Login now