##// END OF EJS Templates
wildcard.py => utils/wildcard.py and updated imports.
Brian Granger -
Show More
@@ -1,3457 +1,3457 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 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.fakemodule import FakeModule
48 from IPython.core.fakemodule import FakeModule
49 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
49 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
50 from IPython.utils.PyColorize import Parser
50 from IPython.utils.PyColorize import Parser
51 from IPython.utils.ipstruct import Struct
51 from IPython.utils.ipstruct import Struct
52 from IPython.core.macro import Macro
52 from IPython.core.macro import Macro
53 from IPython.utils.genutils import *
53 from IPython.utils.genutils import *
54 from IPython.utils import platutils
54 from IPython.utils import platutils
55 import IPython.utils.generics
55 import IPython.utils.generics
56 from IPython.core import ipapi
56 from IPython.core import ipapi
57 from IPython.core.ipapi import UsageError
57 from IPython.core.ipapi import UsageError
58 from IPython.testing import decorators as testdec
58 from IPython.testing import decorators as testdec
59
59
60 #***************************************************************************
60 #***************************************************************************
61 # Utility functions
61 # Utility functions
62 def on_off(tag):
62 def on_off(tag):
63 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
63 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
64 return ['OFF','ON'][tag]
64 return ['OFF','ON'][tag]
65
65
66 class Bunch: pass
66 class Bunch: pass
67
67
68 def compress_dhist(dh):
68 def compress_dhist(dh):
69 head, tail = dh[:-10], dh[-10:]
69 head, tail = dh[:-10], dh[-10:]
70
70
71 newhead = []
71 newhead = []
72 done = set()
72 done = set()
73 for h in head:
73 for h in head:
74 if h in done:
74 if h in done:
75 continue
75 continue
76 newhead.append(h)
76 newhead.append(h)
77 done.add(h)
77 done.add(h)
78
78
79 return newhead + tail
79 return newhead + tail
80
80
81
81
82 #***************************************************************************
82 #***************************************************************************
83 # Main class implementing Magic functionality
83 # Main class implementing Magic functionality
84 class Magic:
84 class Magic:
85 """Magic functions for InteractiveShell.
85 """Magic functions for InteractiveShell.
86
86
87 Shell functions which can be reached as %function_name. All magic
87 Shell functions which can be reached as %function_name. All magic
88 functions should accept a string, which they can parse for their own
88 functions should accept a string, which they can parse for their own
89 needs. This can make some functions easier to type, eg `%cd ../`
89 needs. This can make some functions easier to type, eg `%cd ../`
90 vs. `%cd("../")`
90 vs. `%cd("../")`
91
91
92 ALL definitions MUST begin with the prefix magic_. The user won't need it
92 ALL definitions MUST begin with the prefix magic_. The user won't need it
93 at the command line, but it is is needed in the definition. """
93 at the command line, but it is is needed in the definition. """
94
94
95 # class globals
95 # class globals
96 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
96 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
97 'Automagic is ON, % prefix NOT needed for magic functions.']
97 'Automagic is ON, % prefix NOT needed for magic functions.']
98
98
99 #......................................................................
99 #......................................................................
100 # some utility functions
100 # some utility functions
101
101
102 def __init__(self,shell):
102 def __init__(self,shell):
103
103
104 self.options_table = {}
104 self.options_table = {}
105 if profile is None:
105 if profile is None:
106 self.magic_prun = self.profile_missing_notice
106 self.magic_prun = self.profile_missing_notice
107 self.shell = shell
107 self.shell = shell
108
108
109 # namespace for holding state we may need
109 # namespace for holding state we may need
110 self._magic_state = Bunch()
110 self._magic_state = Bunch()
111
111
112 def profile_missing_notice(self, *args, **kwargs):
112 def profile_missing_notice(self, *args, **kwargs):
113 error("""\
113 error("""\
114 The profile module could not be found. It has been removed from the standard
114 The profile module could not be found. It has been removed from the standard
115 python packages because of its non-free license. To use profiling, install the
115 python packages because of its non-free license. To use profiling, install the
116 python-profiler package from non-free.""")
116 python-profiler package from non-free.""")
117
117
118 def default_option(self,fn,optstr):
118 def default_option(self,fn,optstr):
119 """Make an entry in the options_table for fn, with value optstr"""
119 """Make an entry in the options_table for fn, with value optstr"""
120
120
121 if fn not in self.lsmagic():
121 if fn not in self.lsmagic():
122 error("%s is not a magic function" % fn)
122 error("%s is not a magic function" % fn)
123 self.options_table[fn] = optstr
123 self.options_table[fn] = optstr
124
124
125 def lsmagic(self):
125 def lsmagic(self):
126 """Return a list of currently available magic functions.
126 """Return a list of currently available magic functions.
127
127
128 Gives a list of the bare names after mangling (['ls','cd', ...], not
128 Gives a list of the bare names after mangling (['ls','cd', ...], not
129 ['magic_ls','magic_cd',...]"""
129 ['magic_ls','magic_cd',...]"""
130
130
131 # FIXME. This needs a cleanup, in the way the magics list is built.
131 # FIXME. This needs a cleanup, in the way the magics list is built.
132
132
133 # magics in class definition
133 # magics in class definition
134 class_magic = lambda fn: fn.startswith('magic_') and \
134 class_magic = lambda fn: fn.startswith('magic_') and \
135 callable(Magic.__dict__[fn])
135 callable(Magic.__dict__[fn])
136 # in instance namespace (run-time user additions)
136 # in instance namespace (run-time user additions)
137 inst_magic = lambda fn: fn.startswith('magic_') and \
137 inst_magic = lambda fn: fn.startswith('magic_') and \
138 callable(self.__dict__[fn])
138 callable(self.__dict__[fn])
139 # and bound magics by user (so they can access self):
139 # and bound magics by user (so they can access self):
140 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
140 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
141 callable(self.__class__.__dict__[fn])
141 callable(self.__class__.__dict__[fn])
142 magics = filter(class_magic,Magic.__dict__.keys()) + \
142 magics = filter(class_magic,Magic.__dict__.keys()) + \
143 filter(inst_magic,self.__dict__.keys()) + \
143 filter(inst_magic,self.__dict__.keys()) + \
144 filter(inst_bound_magic,self.__class__.__dict__.keys())
144 filter(inst_bound_magic,self.__class__.__dict__.keys())
145 out = []
145 out = []
146 for fn in set(magics):
146 for fn in set(magics):
147 out.append(fn.replace('magic_','',1))
147 out.append(fn.replace('magic_','',1))
148 out.sort()
148 out.sort()
149 return out
149 return out
150
150
151 def extract_input_slices(self,slices,raw=False):
151 def extract_input_slices(self,slices,raw=False):
152 """Return as a string a set of input history slices.
152 """Return as a string a set of input history slices.
153
153
154 Inputs:
154 Inputs:
155
155
156 - slices: the set of slices is given as a list of strings (like
156 - slices: the set of slices is given as a list of strings (like
157 ['1','4:8','9'], since this function is for use by magic functions
157 ['1','4:8','9'], since this function is for use by magic functions
158 which get their arguments as strings.
158 which get their arguments as strings.
159
159
160 Optional inputs:
160 Optional inputs:
161
161
162 - raw(False): by default, the processed input is used. If this is
162 - raw(False): by default, the processed input is used. If this is
163 true, the raw input history is used instead.
163 true, the raw input history is used instead.
164
164
165 Note that slices can be called with two notations:
165 Note that slices can be called with two notations:
166
166
167 N:M -> standard python form, means including items N...(M-1).
167 N:M -> standard python form, means including items N...(M-1).
168
168
169 N-M -> include items N..M (closed endpoint)."""
169 N-M -> include items N..M (closed endpoint)."""
170
170
171 if raw:
171 if raw:
172 hist = self.shell.input_hist_raw
172 hist = self.shell.input_hist_raw
173 else:
173 else:
174 hist = self.shell.input_hist
174 hist = self.shell.input_hist
175
175
176 cmds = []
176 cmds = []
177 for chunk in slices:
177 for chunk in slices:
178 if ':' in chunk:
178 if ':' in chunk:
179 ini,fin = map(int,chunk.split(':'))
179 ini,fin = map(int,chunk.split(':'))
180 elif '-' in chunk:
180 elif '-' in chunk:
181 ini,fin = map(int,chunk.split('-'))
181 ini,fin = map(int,chunk.split('-'))
182 fin += 1
182 fin += 1
183 else:
183 else:
184 ini = int(chunk)
184 ini = int(chunk)
185 fin = ini+1
185 fin = ini+1
186 cmds.append(hist[ini:fin])
186 cmds.append(hist[ini:fin])
187 return cmds
187 return cmds
188
188
189 def _ofind(self, oname, namespaces=None):
189 def _ofind(self, oname, namespaces=None):
190 """Find an object in the available namespaces.
190 """Find an object in the available namespaces.
191
191
192 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
192 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
193
193
194 Has special code to detect magic functions.
194 Has special code to detect magic functions.
195 """
195 """
196
196
197 oname = oname.strip()
197 oname = oname.strip()
198
198
199 alias_ns = None
199 alias_ns = None
200 if namespaces is None:
200 if namespaces is None:
201 # Namespaces to search in:
201 # Namespaces to search in:
202 # Put them in a list. The order is important so that we
202 # Put them in a list. The order is important so that we
203 # find things in the same order that Python finds them.
203 # find things in the same order that Python finds them.
204 namespaces = [ ('Interactive', self.shell.user_ns),
204 namespaces = [ ('Interactive', self.shell.user_ns),
205 ('IPython internal', self.shell.internal_ns),
205 ('IPython internal', self.shell.internal_ns),
206 ('Python builtin', __builtin__.__dict__),
206 ('Python builtin', __builtin__.__dict__),
207 ('Alias', self.shell.alias_table),
207 ('Alias', self.shell.alias_table),
208 ]
208 ]
209 alias_ns = self.shell.alias_table
209 alias_ns = self.shell.alias_table
210
210
211 # initialize results to 'null'
211 # initialize results to 'null'
212 found = 0; obj = None; ospace = None; ds = None;
212 found = 0; obj = None; ospace = None; ds = None;
213 ismagic = 0; isalias = 0; parent = None
213 ismagic = 0; isalias = 0; parent = None
214
214
215 # Look for the given name by splitting it in parts. If the head is
215 # Look for the given name by splitting it in parts. If the head is
216 # found, then we look for all the remaining parts as members, and only
216 # found, then we look for all the remaining parts as members, and only
217 # declare success if we can find them all.
217 # declare success if we can find them all.
218 oname_parts = oname.split('.')
218 oname_parts = oname.split('.')
219 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
219 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
220 for nsname,ns in namespaces:
220 for nsname,ns in namespaces:
221 try:
221 try:
222 obj = ns[oname_head]
222 obj = ns[oname_head]
223 except KeyError:
223 except KeyError:
224 continue
224 continue
225 else:
225 else:
226 #print 'oname_rest:', oname_rest # dbg
226 #print 'oname_rest:', oname_rest # dbg
227 for part in oname_rest:
227 for part in oname_rest:
228 try:
228 try:
229 parent = obj
229 parent = obj
230 obj = getattr(obj,part)
230 obj = getattr(obj,part)
231 except:
231 except:
232 # Blanket except b/c some badly implemented objects
232 # Blanket except b/c some badly implemented objects
233 # allow __getattr__ to raise exceptions other than
233 # allow __getattr__ to raise exceptions other than
234 # AttributeError, which then crashes IPython.
234 # AttributeError, which then crashes IPython.
235 break
235 break
236 else:
236 else:
237 # If we finish the for loop (no break), we got all members
237 # If we finish the for loop (no break), we got all members
238 found = 1
238 found = 1
239 ospace = nsname
239 ospace = nsname
240 if ns == alias_ns:
240 if ns == alias_ns:
241 isalias = 1
241 isalias = 1
242 break # namespace loop
242 break # namespace loop
243
243
244 # Try to see if it's magic
244 # Try to see if it's magic
245 if not found:
245 if not found:
246 if oname.startswith(self.shell.ESC_MAGIC):
246 if oname.startswith(self.shell.ESC_MAGIC):
247 oname = oname[1:]
247 oname = oname[1:]
248 obj = getattr(self,'magic_'+oname,None)
248 obj = getattr(self,'magic_'+oname,None)
249 if obj is not None:
249 if obj is not None:
250 found = 1
250 found = 1
251 ospace = 'IPython internal'
251 ospace = 'IPython internal'
252 ismagic = 1
252 ismagic = 1
253
253
254 # Last try: special-case some literals like '', [], {}, etc:
254 # Last try: special-case some literals like '', [], {}, etc:
255 if not found and oname_head in ["''",'""','[]','{}','()']:
255 if not found and oname_head in ["''",'""','[]','{}','()']:
256 obj = eval(oname_head)
256 obj = eval(oname_head)
257 found = 1
257 found = 1
258 ospace = 'Interactive'
258 ospace = 'Interactive'
259
259
260 return {'found':found, 'obj':obj, 'namespace':ospace,
260 return {'found':found, 'obj':obj, 'namespace':ospace,
261 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
261 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
262
262
263 def arg_err(self,func):
263 def arg_err(self,func):
264 """Print docstring if incorrect arguments were passed"""
264 """Print docstring if incorrect arguments were passed"""
265 print 'Error in arguments:'
265 print 'Error in arguments:'
266 print OInspect.getdoc(func)
266 print OInspect.getdoc(func)
267
267
268 def format_latex(self,strng):
268 def format_latex(self,strng):
269 """Format a string for latex inclusion."""
269 """Format a string for latex inclusion."""
270
270
271 # Characters that need to be escaped for latex:
271 # Characters that need to be escaped for latex:
272 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
272 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
273 # Magic command names as headers:
273 # Magic command names as headers:
274 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
274 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
275 re.MULTILINE)
275 re.MULTILINE)
276 # Magic commands
276 # Magic commands
277 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
277 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
278 re.MULTILINE)
278 re.MULTILINE)
279 # Paragraph continue
279 # Paragraph continue
280 par_re = re.compile(r'\\$',re.MULTILINE)
280 par_re = re.compile(r'\\$',re.MULTILINE)
281
281
282 # The "\n" symbol
282 # The "\n" symbol
283 newline_re = re.compile(r'\\n')
283 newline_re = re.compile(r'\\n')
284
284
285 # Now build the string for output:
285 # Now build the string for output:
286 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
286 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
287 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
287 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
288 strng)
288 strng)
289 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
289 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
290 strng = par_re.sub(r'\\\\',strng)
290 strng = par_re.sub(r'\\\\',strng)
291 strng = escape_re.sub(r'\\\1',strng)
291 strng = escape_re.sub(r'\\\1',strng)
292 strng = newline_re.sub(r'\\textbackslash{}n',strng)
292 strng = newline_re.sub(r'\\textbackslash{}n',strng)
293 return strng
293 return strng
294
294
295 def format_screen(self,strng):
295 def format_screen(self,strng):
296 """Format a string for screen printing.
296 """Format a string for screen printing.
297
297
298 This removes some latex-type format codes."""
298 This removes some latex-type format codes."""
299 # Paragraph continue
299 # Paragraph continue
300 par_re = re.compile(r'\\$',re.MULTILINE)
300 par_re = re.compile(r'\\$',re.MULTILINE)
301 strng = par_re.sub('',strng)
301 strng = par_re.sub('',strng)
302 return strng
302 return strng
303
303
304 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
304 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
305 """Parse options passed to an argument string.
305 """Parse options passed to an argument string.
306
306
307 The interface is similar to that of getopt(), but it returns back a
307 The interface is similar to that of getopt(), but it returns back a
308 Struct with the options as keys and the stripped argument string still
308 Struct with the options as keys and the stripped argument string still
309 as a string.
309 as a string.
310
310
311 arg_str is quoted as a true sys.argv vector by using shlex.split.
311 arg_str is quoted as a true sys.argv vector by using shlex.split.
312 This allows us to easily expand variables, glob files, quote
312 This allows us to easily expand variables, glob files, quote
313 arguments, etc.
313 arguments, etc.
314
314
315 Options:
315 Options:
316 -mode: default 'string'. If given as 'list', the argument string is
316 -mode: default 'string'. If given as 'list', the argument string is
317 returned as a list (split on whitespace) instead of a string.
317 returned as a list (split on whitespace) instead of a string.
318
318
319 -list_all: put all option values in lists. Normally only options
319 -list_all: put all option values in lists. Normally only options
320 appearing more than once are put in a list.
320 appearing more than once are put in a list.
321
321
322 -posix (True): whether to split the input line in POSIX mode or not,
322 -posix (True): whether to split the input line in POSIX mode or not,
323 as per the conventions outlined in the shlex module from the
323 as per the conventions outlined in the shlex module from the
324 standard library."""
324 standard library."""
325
325
326 # inject default options at the beginning of the input line
326 # inject default options at the beginning of the input line
327 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
327 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
328 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
328 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
329
329
330 mode = kw.get('mode','string')
330 mode = kw.get('mode','string')
331 if mode not in ['string','list']:
331 if mode not in ['string','list']:
332 raise ValueError,'incorrect mode given: %s' % mode
332 raise ValueError,'incorrect mode given: %s' % mode
333 # Get options
333 # Get options
334 list_all = kw.get('list_all',0)
334 list_all = kw.get('list_all',0)
335 posix = kw.get('posix',True)
335 posix = kw.get('posix',True)
336
336
337 # Check if we have more than one argument to warrant extra processing:
337 # Check if we have more than one argument to warrant extra processing:
338 odict = {} # Dictionary with options
338 odict = {} # Dictionary with options
339 args = arg_str.split()
339 args = arg_str.split()
340 if len(args) >= 1:
340 if len(args) >= 1:
341 # If the list of inputs only has 0 or 1 thing in it, there's no
341 # If the list of inputs only has 0 or 1 thing in it, there's no
342 # need to look for options
342 # need to look for options
343 argv = arg_split(arg_str,posix)
343 argv = arg_split(arg_str,posix)
344 # Do regular option processing
344 # Do regular option processing
345 try:
345 try:
346 opts,args = getopt(argv,opt_str,*long_opts)
346 opts,args = getopt(argv,opt_str,*long_opts)
347 except GetoptError,e:
347 except GetoptError,e:
348 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
348 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
349 " ".join(long_opts)))
349 " ".join(long_opts)))
350 for o,a in opts:
350 for o,a in opts:
351 if o.startswith('--'):
351 if o.startswith('--'):
352 o = o[2:]
352 o = o[2:]
353 else:
353 else:
354 o = o[1:]
354 o = o[1:]
355 try:
355 try:
356 odict[o].append(a)
356 odict[o].append(a)
357 except AttributeError:
357 except AttributeError:
358 odict[o] = [odict[o],a]
358 odict[o] = [odict[o],a]
359 except KeyError:
359 except KeyError:
360 if list_all:
360 if list_all:
361 odict[o] = [a]
361 odict[o] = [a]
362 else:
362 else:
363 odict[o] = a
363 odict[o] = a
364
364
365 # Prepare opts,args for return
365 # Prepare opts,args for return
366 opts = Struct(odict)
366 opts = Struct(odict)
367 if mode == 'string':
367 if mode == 'string':
368 args = ' '.join(args)
368 args = ' '.join(args)
369
369
370 return opts,args
370 return opts,args
371
371
372 #......................................................................
372 #......................................................................
373 # And now the actual magic functions
373 # And now the actual magic functions
374
374
375 # Functions for IPython shell work (vars,funcs, config, etc)
375 # Functions for IPython shell work (vars,funcs, config, etc)
376 def magic_lsmagic(self, parameter_s = ''):
376 def magic_lsmagic(self, parameter_s = ''):
377 """List currently available magic functions."""
377 """List currently available magic functions."""
378 mesc = self.shell.ESC_MAGIC
378 mesc = self.shell.ESC_MAGIC
379 print 'Available magic functions:\n'+mesc+\
379 print 'Available magic functions:\n'+mesc+\
380 (' '+mesc).join(self.lsmagic())
380 (' '+mesc).join(self.lsmagic())
381 print '\n' + Magic.auto_status[self.shell.rc.automagic]
381 print '\n' + Magic.auto_status[self.shell.rc.automagic]
382 return None
382 return None
383
383
384 def magic_magic(self, parameter_s = ''):
384 def magic_magic(self, parameter_s = ''):
385 """Print information about the magic function system.
385 """Print information about the magic function system.
386
386
387 Supported formats: -latex, -brief, -rest
387 Supported formats: -latex, -brief, -rest
388 """
388 """
389
389
390 mode = ''
390 mode = ''
391 try:
391 try:
392 if parameter_s.split()[0] == '-latex':
392 if parameter_s.split()[0] == '-latex':
393 mode = 'latex'
393 mode = 'latex'
394 if parameter_s.split()[0] == '-brief':
394 if parameter_s.split()[0] == '-brief':
395 mode = 'brief'
395 mode = 'brief'
396 if parameter_s.split()[0] == '-rest':
396 if parameter_s.split()[0] == '-rest':
397 mode = 'rest'
397 mode = 'rest'
398 rest_docs = []
398 rest_docs = []
399 except:
399 except:
400 pass
400 pass
401
401
402 magic_docs = []
402 magic_docs = []
403 for fname in self.lsmagic():
403 for fname in self.lsmagic():
404 mname = 'magic_' + fname
404 mname = 'magic_' + fname
405 for space in (Magic,self,self.__class__):
405 for space in (Magic,self,self.__class__):
406 try:
406 try:
407 fn = space.__dict__[mname]
407 fn = space.__dict__[mname]
408 except KeyError:
408 except KeyError:
409 pass
409 pass
410 else:
410 else:
411 break
411 break
412 if mode == 'brief':
412 if mode == 'brief':
413 # only first line
413 # only first line
414 if fn.__doc__:
414 if fn.__doc__:
415 fndoc = fn.__doc__.split('\n',1)[0]
415 fndoc = fn.__doc__.split('\n',1)[0]
416 else:
416 else:
417 fndoc = 'No documentation'
417 fndoc = 'No documentation'
418 else:
418 else:
419 if fn.__doc__:
419 if fn.__doc__:
420 fndoc = fn.__doc__.rstrip()
420 fndoc = fn.__doc__.rstrip()
421 else:
421 else:
422 fndoc = 'No documentation'
422 fndoc = 'No documentation'
423
423
424
424
425 if mode == 'rest':
425 if mode == 'rest':
426 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
426 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
427 fname,fndoc))
427 fname,fndoc))
428
428
429 else:
429 else:
430 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
430 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
431 fname,fndoc))
431 fname,fndoc))
432
432
433 magic_docs = ''.join(magic_docs)
433 magic_docs = ''.join(magic_docs)
434
434
435 if mode == 'rest':
435 if mode == 'rest':
436 return "".join(rest_docs)
436 return "".join(rest_docs)
437
437
438 if mode == 'latex':
438 if mode == 'latex':
439 print self.format_latex(magic_docs)
439 print self.format_latex(magic_docs)
440 return
440 return
441 else:
441 else:
442 magic_docs = self.format_screen(magic_docs)
442 magic_docs = self.format_screen(magic_docs)
443 if mode == 'brief':
443 if mode == 'brief':
444 return magic_docs
444 return magic_docs
445
445
446 outmsg = """
446 outmsg = """
447 IPython's 'magic' functions
447 IPython's 'magic' functions
448 ===========================
448 ===========================
449
449
450 The magic function system provides a series of functions which allow you to
450 The magic function system provides a series of functions which allow you to
451 control the behavior of IPython itself, plus a lot of system-type
451 control the behavior of IPython itself, plus a lot of system-type
452 features. All these functions are prefixed with a % character, but parameters
452 features. All these functions are prefixed with a % character, but parameters
453 are given without parentheses or quotes.
453 are given without parentheses or quotes.
454
454
455 NOTE: If you have 'automagic' enabled (via the command line option or with the
455 NOTE: If you have 'automagic' enabled (via the command line option or with the
456 %automagic function), you don't need to type in the % explicitly. By default,
456 %automagic function), you don't need to type in the % explicitly. By default,
457 IPython ships with automagic on, so you should only rarely need the % escape.
457 IPython ships with automagic on, so you should only rarely need the % escape.
458
458
459 Example: typing '%cd mydir' (without the quotes) changes you working directory
459 Example: typing '%cd mydir' (without the quotes) changes you working directory
460 to 'mydir', if it exists.
460 to 'mydir', if it exists.
461
461
462 You can define your own magic functions to extend the system. See the supplied
462 You can define your own magic functions to extend the system. See the supplied
463 ipythonrc and example-magic.py files for details (in your ipython
463 ipythonrc and example-magic.py files for details (in your ipython
464 configuration directory, typically $HOME/.ipython/).
464 configuration directory, typically $HOME/.ipython/).
465
465
466 You can also define your own aliased names for magic functions. In your
466 You can also define your own aliased names for magic functions. In your
467 ipythonrc file, placing a line like:
467 ipythonrc file, placing a line like:
468
468
469 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
469 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
470
470
471 will define %pf as a new name for %profile.
471 will define %pf as a new name for %profile.
472
472
473 You can also call magics in code using the ipmagic() function, which IPython
473 You can also call magics in code using the ipmagic() function, which IPython
474 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
474 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
475
475
476 For a list of the available magic functions, use %lsmagic. For a description
476 For a list of the available magic functions, use %lsmagic. For a description
477 of any of them, type %magic_name?, e.g. '%cd?'.
477 of any of them, type %magic_name?, e.g. '%cd?'.
478
478
479 Currently the magic system has the following functions:\n"""
479 Currently the magic system has the following functions:\n"""
480
480
481 mesc = self.shell.ESC_MAGIC
481 mesc = self.shell.ESC_MAGIC
482 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
482 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
483 "\n\n%s%s\n\n%s" % (outmsg,
483 "\n\n%s%s\n\n%s" % (outmsg,
484 magic_docs,mesc,mesc,
484 magic_docs,mesc,mesc,
485 (' '+mesc).join(self.lsmagic()),
485 (' '+mesc).join(self.lsmagic()),
486 Magic.auto_status[self.shell.rc.automagic] ) )
486 Magic.auto_status[self.shell.rc.automagic] ) )
487
487
488 page(outmsg,screen_lines=self.shell.rc.screen_length)
488 page(outmsg,screen_lines=self.shell.rc.screen_length)
489
489
490
490
491 def magic_autoindent(self, parameter_s = ''):
491 def magic_autoindent(self, parameter_s = ''):
492 """Toggle autoindent on/off (if available)."""
492 """Toggle autoindent on/off (if available)."""
493
493
494 self.shell.set_autoindent()
494 self.shell.set_autoindent()
495 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
495 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
496
496
497
497
498 def magic_automagic(self, parameter_s = ''):
498 def magic_automagic(self, parameter_s = ''):
499 """Make magic functions callable without having to type the initial %.
499 """Make magic functions callable without having to type the initial %.
500
500
501 Without argumentsl toggles on/off (when off, you must call it as
501 Without argumentsl toggles on/off (when off, you must call it as
502 %automagic, of course). With arguments it sets the value, and you can
502 %automagic, of course). With arguments it sets the value, and you can
503 use any of (case insensitive):
503 use any of (case insensitive):
504
504
505 - on,1,True: to activate
505 - on,1,True: to activate
506
506
507 - off,0,False: to deactivate.
507 - off,0,False: to deactivate.
508
508
509 Note that magic functions have lowest priority, so if there's a
509 Note that magic functions have lowest priority, so if there's a
510 variable whose name collides with that of a magic fn, automagic won't
510 variable whose name collides with that of a magic fn, automagic won't
511 work for that function (you get the variable instead). However, if you
511 work for that function (you get the variable instead). However, if you
512 delete the variable (del var), the previously shadowed magic function
512 delete the variable (del var), the previously shadowed magic function
513 becomes visible to automagic again."""
513 becomes visible to automagic again."""
514
514
515 rc = self.shell.rc
515 rc = self.shell.rc
516 arg = parameter_s.lower()
516 arg = parameter_s.lower()
517 if parameter_s in ('on','1','true'):
517 if parameter_s in ('on','1','true'):
518 rc.automagic = True
518 rc.automagic = True
519 elif parameter_s in ('off','0','false'):
519 elif parameter_s in ('off','0','false'):
520 rc.automagic = False
520 rc.automagic = False
521 else:
521 else:
522 rc.automagic = not rc.automagic
522 rc.automagic = not rc.automagic
523 print '\n' + Magic.auto_status[rc.automagic]
523 print '\n' + Magic.auto_status[rc.automagic]
524
524
525 @testdec.skip_doctest
525 @testdec.skip_doctest
526 def magic_autocall(self, parameter_s = ''):
526 def magic_autocall(self, parameter_s = ''):
527 """Make functions callable without having to type parentheses.
527 """Make functions callable without having to type parentheses.
528
528
529 Usage:
529 Usage:
530
530
531 %autocall [mode]
531 %autocall [mode]
532
532
533 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
533 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
534 value is toggled on and off (remembering the previous state).
534 value is toggled on and off (remembering the previous state).
535
535
536 In more detail, these values mean:
536 In more detail, these values mean:
537
537
538 0 -> fully disabled
538 0 -> fully disabled
539
539
540 1 -> active, but do not apply if there are no arguments on the line.
540 1 -> active, but do not apply if there are no arguments on the line.
541
541
542 In this mode, you get:
542 In this mode, you get:
543
543
544 In [1]: callable
544 In [1]: callable
545 Out[1]: <built-in function callable>
545 Out[1]: <built-in function callable>
546
546
547 In [2]: callable 'hello'
547 In [2]: callable 'hello'
548 ------> callable('hello')
548 ------> callable('hello')
549 Out[2]: False
549 Out[2]: False
550
550
551 2 -> Active always. Even if no arguments are present, the callable
551 2 -> Active always. Even if no arguments are present, the callable
552 object is called:
552 object is called:
553
553
554 In [2]: float
554 In [2]: float
555 ------> float()
555 ------> float()
556 Out[2]: 0.0
556 Out[2]: 0.0
557
557
558 Note that even with autocall off, you can still use '/' at the start of
558 Note that even with autocall off, you can still use '/' at the start of
559 a line to treat the first argument on the command line as a function
559 a line to treat the first argument on the command line as a function
560 and add parentheses to it:
560 and add parentheses to it:
561
561
562 In [8]: /str 43
562 In [8]: /str 43
563 ------> str(43)
563 ------> str(43)
564 Out[8]: '43'
564 Out[8]: '43'
565
565
566 # all-random (note for auto-testing)
566 # all-random (note for auto-testing)
567 """
567 """
568
568
569 rc = self.shell.rc
569 rc = self.shell.rc
570
570
571 if parameter_s:
571 if parameter_s:
572 arg = int(parameter_s)
572 arg = int(parameter_s)
573 else:
573 else:
574 arg = 'toggle'
574 arg = 'toggle'
575
575
576 if not arg in (0,1,2,'toggle'):
576 if not arg in (0,1,2,'toggle'):
577 error('Valid modes: (0->Off, 1->Smart, 2->Full')
577 error('Valid modes: (0->Off, 1->Smart, 2->Full')
578 return
578 return
579
579
580 if arg in (0,1,2):
580 if arg in (0,1,2):
581 rc.autocall = arg
581 rc.autocall = arg
582 else: # toggle
582 else: # toggle
583 if rc.autocall:
583 if rc.autocall:
584 self._magic_state.autocall_save = rc.autocall
584 self._magic_state.autocall_save = rc.autocall
585 rc.autocall = 0
585 rc.autocall = 0
586 else:
586 else:
587 try:
587 try:
588 rc.autocall = self._magic_state.autocall_save
588 rc.autocall = self._magic_state.autocall_save
589 except AttributeError:
589 except AttributeError:
590 rc.autocall = self._magic_state.autocall_save = 1
590 rc.autocall = self._magic_state.autocall_save = 1
591
591
592 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
592 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
593
593
594 def magic_system_verbose(self, parameter_s = ''):
594 def magic_system_verbose(self, parameter_s = ''):
595 """Set verbose printing of system calls.
595 """Set verbose printing of system calls.
596
596
597 If called without an argument, act as a toggle"""
597 If called without an argument, act as a toggle"""
598
598
599 if parameter_s:
599 if parameter_s:
600 val = bool(eval(parameter_s))
600 val = bool(eval(parameter_s))
601 else:
601 else:
602 val = None
602 val = None
603
603
604 self.shell.rc_set_toggle('system_verbose',val)
604 self.shell.rc_set_toggle('system_verbose',val)
605 print "System verbose printing is:",\
605 print "System verbose printing is:",\
606 ['OFF','ON'][self.shell.rc.system_verbose]
606 ['OFF','ON'][self.shell.rc.system_verbose]
607
607
608
608
609 def magic_page(self, parameter_s=''):
609 def magic_page(self, parameter_s=''):
610 """Pretty print the object and display it through a pager.
610 """Pretty print the object and display it through a pager.
611
611
612 %page [options] OBJECT
612 %page [options] OBJECT
613
613
614 If no object is given, use _ (last output).
614 If no object is given, use _ (last output).
615
615
616 Options:
616 Options:
617
617
618 -r: page str(object), don't pretty-print it."""
618 -r: page str(object), don't pretty-print it."""
619
619
620 # After a function contributed by Olivier Aubert, slightly modified.
620 # After a function contributed by Olivier Aubert, slightly modified.
621
621
622 # Process options/args
622 # Process options/args
623 opts,args = self.parse_options(parameter_s,'r')
623 opts,args = self.parse_options(parameter_s,'r')
624 raw = 'r' in opts
624 raw = 'r' in opts
625
625
626 oname = args and args or '_'
626 oname = args and args or '_'
627 info = self._ofind(oname)
627 info = self._ofind(oname)
628 if info['found']:
628 if info['found']:
629 txt = (raw and str or pformat)( info['obj'] )
629 txt = (raw and str or pformat)( info['obj'] )
630 page(txt)
630 page(txt)
631 else:
631 else:
632 print 'Object `%s` not found' % oname
632 print 'Object `%s` not found' % oname
633
633
634 def magic_profile(self, parameter_s=''):
634 def magic_profile(self, parameter_s=''):
635 """Print your currently active IPyhton profile."""
635 """Print your currently active IPyhton profile."""
636 if self.shell.rc.profile:
636 if self.shell.rc.profile:
637 printpl('Current IPython profile: $self.shell.rc.profile.')
637 printpl('Current IPython profile: $self.shell.rc.profile.')
638 else:
638 else:
639 print 'No profile active.'
639 print 'No profile active.'
640
640
641 def magic_pinfo(self, parameter_s='', namespaces=None):
641 def magic_pinfo(self, parameter_s='', namespaces=None):
642 """Provide detailed information about an object.
642 """Provide detailed information about an object.
643
643
644 '%pinfo object' is just a synonym for object? or ?object."""
644 '%pinfo object' is just a synonym for object? or ?object."""
645
645
646 #print 'pinfo par: <%s>' % parameter_s # dbg
646 #print 'pinfo par: <%s>' % parameter_s # dbg
647
647
648
648
649 # detail_level: 0 -> obj? , 1 -> obj??
649 # detail_level: 0 -> obj? , 1 -> obj??
650 detail_level = 0
650 detail_level = 0
651 # We need to detect if we got called as 'pinfo pinfo foo', which can
651 # We need to detect if we got called as 'pinfo pinfo foo', which can
652 # happen if the user types 'pinfo foo?' at the cmd line.
652 # happen if the user types 'pinfo foo?' at the cmd line.
653 pinfo,qmark1,oname,qmark2 = \
653 pinfo,qmark1,oname,qmark2 = \
654 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
654 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
655 if pinfo or qmark1 or qmark2:
655 if pinfo or qmark1 or qmark2:
656 detail_level = 1
656 detail_level = 1
657 if "*" in oname:
657 if "*" in oname:
658 self.magic_psearch(oname)
658 self.magic_psearch(oname)
659 else:
659 else:
660 self._inspect('pinfo', oname, detail_level=detail_level,
660 self._inspect('pinfo', oname, detail_level=detail_level,
661 namespaces=namespaces)
661 namespaces=namespaces)
662
662
663 def magic_pdef(self, parameter_s='', namespaces=None):
663 def magic_pdef(self, parameter_s='', namespaces=None):
664 """Print the definition header for any callable object.
664 """Print the definition header for any callable object.
665
665
666 If the object is a class, print the constructor information."""
666 If the object is a class, print the constructor information."""
667 self._inspect('pdef',parameter_s, namespaces)
667 self._inspect('pdef',parameter_s, namespaces)
668
668
669 def magic_pdoc(self, parameter_s='', namespaces=None):
669 def magic_pdoc(self, parameter_s='', namespaces=None):
670 """Print the docstring for an object.
670 """Print the docstring for an object.
671
671
672 If the given object is a class, it will print both the class and the
672 If the given object is a class, it will print both the class and the
673 constructor docstrings."""
673 constructor docstrings."""
674 self._inspect('pdoc',parameter_s, namespaces)
674 self._inspect('pdoc',parameter_s, namespaces)
675
675
676 def magic_psource(self, parameter_s='', namespaces=None):
676 def magic_psource(self, parameter_s='', namespaces=None):
677 """Print (or run through pager) the source code for an object."""
677 """Print (or run through pager) the source code for an object."""
678 self._inspect('psource',parameter_s, namespaces)
678 self._inspect('psource',parameter_s, namespaces)
679
679
680 def magic_pfile(self, parameter_s=''):
680 def magic_pfile(self, parameter_s=''):
681 """Print (or run through pager) the file where an object is defined.
681 """Print (or run through pager) the file where an object is defined.
682
682
683 The file opens at the line where the object definition begins. IPython
683 The file opens at the line where the object definition begins. IPython
684 will honor the environment variable PAGER if set, and otherwise will
684 will honor the environment variable PAGER if set, and otherwise will
685 do its best to print the file in a convenient form.
685 do its best to print the file in a convenient form.
686
686
687 If the given argument is not an object currently defined, IPython will
687 If the given argument is not an object currently defined, IPython will
688 try to interpret it as a filename (automatically adding a .py extension
688 try to interpret it as a filename (automatically adding a .py extension
689 if needed). You can thus use %pfile as a syntax highlighting code
689 if needed). You can thus use %pfile as a syntax highlighting code
690 viewer."""
690 viewer."""
691
691
692 # first interpret argument as an object name
692 # first interpret argument as an object name
693 out = self._inspect('pfile',parameter_s)
693 out = self._inspect('pfile',parameter_s)
694 # if not, try the input as a filename
694 # if not, try the input as a filename
695 if out == 'not found':
695 if out == 'not found':
696 try:
696 try:
697 filename = get_py_filename(parameter_s)
697 filename = get_py_filename(parameter_s)
698 except IOError,msg:
698 except IOError,msg:
699 print msg
699 print msg
700 return
700 return
701 page(self.shell.inspector.format(file(filename).read()))
701 page(self.shell.inspector.format(file(filename).read()))
702
702
703 def _inspect(self,meth,oname,namespaces=None,**kw):
703 def _inspect(self,meth,oname,namespaces=None,**kw):
704 """Generic interface to the inspector system.
704 """Generic interface to the inspector system.
705
705
706 This function is meant to be called by pdef, pdoc & friends."""
706 This function is meant to be called by pdef, pdoc & friends."""
707
707
708 #oname = oname.strip()
708 #oname = oname.strip()
709 #print '1- oname: <%r>' % oname # dbg
709 #print '1- oname: <%r>' % oname # dbg
710 try:
710 try:
711 oname = oname.strip().encode('ascii')
711 oname = oname.strip().encode('ascii')
712 #print '2- oname: <%r>' % oname # dbg
712 #print '2- oname: <%r>' % oname # dbg
713 except UnicodeEncodeError:
713 except UnicodeEncodeError:
714 print 'Python identifiers can only contain ascii characters.'
714 print 'Python identifiers can only contain ascii characters.'
715 return 'not found'
715 return 'not found'
716
716
717 info = Struct(self._ofind(oname, namespaces))
717 info = Struct(self._ofind(oname, namespaces))
718
718
719 if info.found:
719 if info.found:
720 try:
720 try:
721 IPython.utils.generics.inspect_object(info.obj)
721 IPython.utils.generics.inspect_object(info.obj)
722 return
722 return
723 except ipapi.TryNext:
723 except ipapi.TryNext:
724 pass
724 pass
725 # Get the docstring of the class property if it exists.
725 # Get the docstring of the class property if it exists.
726 path = oname.split('.')
726 path = oname.split('.')
727 root = '.'.join(path[:-1])
727 root = '.'.join(path[:-1])
728 if info.parent is not None:
728 if info.parent is not None:
729 try:
729 try:
730 target = getattr(info.parent, '__class__')
730 target = getattr(info.parent, '__class__')
731 # The object belongs to a class instance.
731 # The object belongs to a class instance.
732 try:
732 try:
733 target = getattr(target, path[-1])
733 target = getattr(target, path[-1])
734 # The class defines the object.
734 # The class defines the object.
735 if isinstance(target, property):
735 if isinstance(target, property):
736 oname = root + '.__class__.' + path[-1]
736 oname = root + '.__class__.' + path[-1]
737 info = Struct(self._ofind(oname))
737 info = Struct(self._ofind(oname))
738 except AttributeError: pass
738 except AttributeError: pass
739 except AttributeError: pass
739 except AttributeError: pass
740
740
741 pmethod = getattr(self.shell.inspector,meth)
741 pmethod = getattr(self.shell.inspector,meth)
742 formatter = info.ismagic and self.format_screen or None
742 formatter = info.ismagic and self.format_screen or None
743 if meth == 'pdoc':
743 if meth == 'pdoc':
744 pmethod(info.obj,oname,formatter)
744 pmethod(info.obj,oname,formatter)
745 elif meth == 'pinfo':
745 elif meth == 'pinfo':
746 pmethod(info.obj,oname,formatter,info,**kw)
746 pmethod(info.obj,oname,formatter,info,**kw)
747 else:
747 else:
748 pmethod(info.obj,oname)
748 pmethod(info.obj,oname)
749 else:
749 else:
750 print 'Object `%s` not found.' % oname
750 print 'Object `%s` not found.' % oname
751 return 'not found' # so callers can take other action
751 return 'not found' # so callers can take other action
752
752
753 def magic_psearch(self, parameter_s=''):
753 def magic_psearch(self, parameter_s=''):
754 """Search for object in namespaces by wildcard.
754 """Search for object in namespaces by wildcard.
755
755
756 %psearch [options] PATTERN [OBJECT TYPE]
756 %psearch [options] PATTERN [OBJECT TYPE]
757
757
758 Note: ? can be used as a synonym for %psearch, at the beginning or at
758 Note: ? can be used as a synonym for %psearch, at the beginning or at
759 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
759 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
760 rest of the command line must be unchanged (options come first), so
760 rest of the command line must be unchanged (options come first), so
761 for example the following forms are equivalent
761 for example the following forms are equivalent
762
762
763 %psearch -i a* function
763 %psearch -i a* function
764 -i a* function?
764 -i a* function?
765 ?-i a* function
765 ?-i a* function
766
766
767 Arguments:
767 Arguments:
768
768
769 PATTERN
769 PATTERN
770
770
771 where PATTERN is a string containing * as a wildcard similar to its
771 where PATTERN is a string containing * as a wildcard similar to its
772 use in a shell. The pattern is matched in all namespaces on the
772 use in a shell. The pattern is matched in all namespaces on the
773 search path. By default objects starting with a single _ are not
773 search path. By default objects starting with a single _ are not
774 matched, many IPython generated objects have a single
774 matched, many IPython generated objects have a single
775 underscore. The default is case insensitive matching. Matching is
775 underscore. The default is case insensitive matching. Matching is
776 also done on the attributes of objects and not only on the objects
776 also done on the attributes of objects and not only on the objects
777 in a module.
777 in a module.
778
778
779 [OBJECT TYPE]
779 [OBJECT TYPE]
780
780
781 Is the name of a python type from the types module. The name is
781 Is the name of a python type from the types module. The name is
782 given in lowercase without the ending type, ex. StringType is
782 given in lowercase without the ending type, ex. StringType is
783 written string. By adding a type here only objects matching the
783 written string. By adding a type here only objects matching the
784 given type are matched. Using all here makes the pattern match all
784 given type are matched. Using all here makes the pattern match all
785 types (this is the default).
785 types (this is the default).
786
786
787 Options:
787 Options:
788
788
789 -a: makes the pattern match even objects whose names start with a
789 -a: makes the pattern match even objects whose names start with a
790 single underscore. These names are normally ommitted from the
790 single underscore. These names are normally ommitted from the
791 search.
791 search.
792
792
793 -i/-c: make the pattern case insensitive/sensitive. If neither of
793 -i/-c: make the pattern case insensitive/sensitive. If neither of
794 these options is given, the default is read from your ipythonrc
794 these options is given, the default is read from your ipythonrc
795 file. The option name which sets this value is
795 file. The option name which sets this value is
796 'wildcards_case_sensitive'. If this option is not specified in your
796 'wildcards_case_sensitive'. If this option is not specified in your
797 ipythonrc file, IPython's internal default is to do a case sensitive
797 ipythonrc file, IPython's internal default is to do a case sensitive
798 search.
798 search.
799
799
800 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
800 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
801 specifiy can be searched in any of the following namespaces:
801 specifiy can be searched in any of the following namespaces:
802 'builtin', 'user', 'user_global','internal', 'alias', where
802 'builtin', 'user', 'user_global','internal', 'alias', where
803 'builtin' and 'user' are the search defaults. Note that you should
803 'builtin' and 'user' are the search defaults. Note that you should
804 not use quotes when specifying namespaces.
804 not use quotes when specifying namespaces.
805
805
806 'Builtin' contains the python module builtin, 'user' contains all
806 'Builtin' contains the python module builtin, 'user' contains all
807 user data, 'alias' only contain the shell aliases and no python
807 user data, 'alias' only contain the shell aliases and no python
808 objects, 'internal' contains objects used by IPython. The
808 objects, 'internal' contains objects used by IPython. The
809 'user_global' namespace is only used by embedded IPython instances,
809 'user_global' namespace is only used by embedded IPython instances,
810 and it contains module-level globals. You can add namespaces to the
810 and it contains module-level globals. You can add namespaces to the
811 search with -s or exclude them with -e (these options can be given
811 search with -s or exclude them with -e (these options can be given
812 more than once).
812 more than once).
813
813
814 Examples:
814 Examples:
815
815
816 %psearch a* -> objects beginning with an a
816 %psearch a* -> objects beginning with an a
817 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
817 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
818 %psearch a* function -> all functions beginning with an a
818 %psearch a* function -> all functions beginning with an a
819 %psearch re.e* -> objects beginning with an e in module re
819 %psearch re.e* -> objects beginning with an e in module re
820 %psearch r*.e* -> objects that start with e in modules starting in r
820 %psearch r*.e* -> objects that start with e in modules starting in r
821 %psearch r*.* string -> all strings in modules beginning with r
821 %psearch r*.* string -> all strings in modules beginning with r
822
822
823 Case sensitve search:
823 Case sensitve search:
824
824
825 %psearch -c a* list all object beginning with lower case a
825 %psearch -c a* list all object beginning with lower case a
826
826
827 Show objects beginning with a single _:
827 Show objects beginning with a single _:
828
828
829 %psearch -a _* list objects beginning with a single underscore"""
829 %psearch -a _* list objects beginning with a single underscore"""
830 try:
830 try:
831 parameter_s = parameter_s.encode('ascii')
831 parameter_s = parameter_s.encode('ascii')
832 except UnicodeEncodeError:
832 except UnicodeEncodeError:
833 print 'Python identifiers can only contain ascii characters.'
833 print 'Python identifiers can only contain ascii characters.'
834 return
834 return
835
835
836 # default namespaces to be searched
836 # default namespaces to be searched
837 def_search = ['user','builtin']
837 def_search = ['user','builtin']
838
838
839 # Process options/args
839 # Process options/args
840 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
840 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
841 opt = opts.get
841 opt = opts.get
842 shell = self.shell
842 shell = self.shell
843 psearch = shell.inspector.psearch
843 psearch = shell.inspector.psearch
844
844
845 # select case options
845 # select case options
846 if opts.has_key('i'):
846 if opts.has_key('i'):
847 ignore_case = True
847 ignore_case = True
848 elif opts.has_key('c'):
848 elif opts.has_key('c'):
849 ignore_case = False
849 ignore_case = False
850 else:
850 else:
851 ignore_case = not shell.rc.wildcards_case_sensitive
851 ignore_case = not shell.rc.wildcards_case_sensitive
852
852
853 # Build list of namespaces to search from user options
853 # Build list of namespaces to search from user options
854 def_search.extend(opt('s',[]))
854 def_search.extend(opt('s',[]))
855 ns_exclude = ns_exclude=opt('e',[])
855 ns_exclude = ns_exclude=opt('e',[])
856 ns_search = [nm for nm in def_search if nm not in ns_exclude]
856 ns_search = [nm for nm in def_search if nm not in ns_exclude]
857
857
858 # Call the actual search
858 # Call the actual search
859 try:
859 try:
860 psearch(args,shell.ns_table,ns_search,
860 psearch(args,shell.ns_table,ns_search,
861 show_all=opt('a'),ignore_case=ignore_case)
861 show_all=opt('a'),ignore_case=ignore_case)
862 except:
862 except:
863 shell.showtraceback()
863 shell.showtraceback()
864
864
865 def magic_who_ls(self, parameter_s=''):
865 def magic_who_ls(self, parameter_s=''):
866 """Return a sorted list of all interactive variables.
866 """Return a sorted list of all interactive variables.
867
867
868 If arguments are given, only variables of types matching these
868 If arguments are given, only variables of types matching these
869 arguments are returned."""
869 arguments are returned."""
870
870
871 user_ns = self.shell.user_ns
871 user_ns = self.shell.user_ns
872 internal_ns = self.shell.internal_ns
872 internal_ns = self.shell.internal_ns
873 user_config_ns = self.shell.user_config_ns
873 user_config_ns = self.shell.user_config_ns
874 out = []
874 out = []
875 typelist = parameter_s.split()
875 typelist = parameter_s.split()
876
876
877 for i in user_ns:
877 for i in user_ns:
878 if not (i.startswith('_') or i.startswith('_i')) \
878 if not (i.startswith('_') or i.startswith('_i')) \
879 and not (i in internal_ns or i in user_config_ns):
879 and not (i in internal_ns or i in user_config_ns):
880 if typelist:
880 if typelist:
881 if type(user_ns[i]).__name__ in typelist:
881 if type(user_ns[i]).__name__ in typelist:
882 out.append(i)
882 out.append(i)
883 else:
883 else:
884 out.append(i)
884 out.append(i)
885 out.sort()
885 out.sort()
886 return out
886 return out
887
887
888 def magic_who(self, parameter_s=''):
888 def magic_who(self, parameter_s=''):
889 """Print all interactive variables, with some minimal formatting.
889 """Print all interactive variables, with some minimal formatting.
890
890
891 If any arguments are given, only variables whose type matches one of
891 If any arguments are given, only variables whose type matches one of
892 these are printed. For example:
892 these are printed. For example:
893
893
894 %who function str
894 %who function str
895
895
896 will only list functions and strings, excluding all other types of
896 will only list functions and strings, excluding all other types of
897 variables. To find the proper type names, simply use type(var) at a
897 variables. To find the proper type names, simply use type(var) at a
898 command line to see how python prints type names. For example:
898 command line to see how python prints type names. For example:
899
899
900 In [1]: type('hello')\\
900 In [1]: type('hello')\\
901 Out[1]: <type 'str'>
901 Out[1]: <type 'str'>
902
902
903 indicates that the type name for strings is 'str'.
903 indicates that the type name for strings is 'str'.
904
904
905 %who always excludes executed names loaded through your configuration
905 %who always excludes executed names loaded through your configuration
906 file and things which are internal to IPython.
906 file and things which are internal to IPython.
907
907
908 This is deliberate, as typically you may load many modules and the
908 This is deliberate, as typically you may load many modules and the
909 purpose of %who is to show you only what you've manually defined."""
909 purpose of %who is to show you only what you've manually defined."""
910
910
911 varlist = self.magic_who_ls(parameter_s)
911 varlist = self.magic_who_ls(parameter_s)
912 if not varlist:
912 if not varlist:
913 if parameter_s:
913 if parameter_s:
914 print 'No variables match your requested type.'
914 print 'No variables match your requested type.'
915 else:
915 else:
916 print 'Interactive namespace is empty.'
916 print 'Interactive namespace is empty.'
917 return
917 return
918
918
919 # if we have variables, move on...
919 # if we have variables, move on...
920 count = 0
920 count = 0
921 for i in varlist:
921 for i in varlist:
922 print i+'\t',
922 print i+'\t',
923 count += 1
923 count += 1
924 if count > 8:
924 if count > 8:
925 count = 0
925 count = 0
926 print
926 print
927 print
927 print
928
928
929 def magic_whos(self, parameter_s=''):
929 def magic_whos(self, parameter_s=''):
930 """Like %who, but gives some extra information about each variable.
930 """Like %who, but gives some extra information about each variable.
931
931
932 The same type filtering of %who can be applied here.
932 The same type filtering of %who can be applied here.
933
933
934 For all variables, the type is printed. Additionally it prints:
934 For all variables, the type is printed. Additionally it prints:
935
935
936 - For {},[],(): their length.
936 - For {},[],(): their length.
937
937
938 - For numpy and Numeric arrays, a summary with shape, number of
938 - For numpy and Numeric arrays, a summary with shape, number of
939 elements, typecode and size in memory.
939 elements, typecode and size in memory.
940
940
941 - Everything else: a string representation, snipping their middle if
941 - Everything else: a string representation, snipping their middle if
942 too long."""
942 too long."""
943
943
944 varnames = self.magic_who_ls(parameter_s)
944 varnames = self.magic_who_ls(parameter_s)
945 if not varnames:
945 if not varnames:
946 if parameter_s:
946 if parameter_s:
947 print 'No variables match your requested type.'
947 print 'No variables match your requested type.'
948 else:
948 else:
949 print 'Interactive namespace is empty.'
949 print 'Interactive namespace is empty.'
950 return
950 return
951
951
952 # if we have variables, move on...
952 # if we have variables, move on...
953
953
954 # for these types, show len() instead of data:
954 # for these types, show len() instead of data:
955 seq_types = [types.DictType,types.ListType,types.TupleType]
955 seq_types = [types.DictType,types.ListType,types.TupleType]
956
956
957 # for numpy/Numeric arrays, display summary info
957 # for numpy/Numeric arrays, display summary info
958 try:
958 try:
959 import numpy
959 import numpy
960 except ImportError:
960 except ImportError:
961 ndarray_type = None
961 ndarray_type = None
962 else:
962 else:
963 ndarray_type = numpy.ndarray.__name__
963 ndarray_type = numpy.ndarray.__name__
964 try:
964 try:
965 import Numeric
965 import Numeric
966 except ImportError:
966 except ImportError:
967 array_type = None
967 array_type = None
968 else:
968 else:
969 array_type = Numeric.ArrayType.__name__
969 array_type = Numeric.ArrayType.__name__
970
970
971 # Find all variable names and types so we can figure out column sizes
971 # Find all variable names and types so we can figure out column sizes
972 def get_vars(i):
972 def get_vars(i):
973 return self.shell.user_ns[i]
973 return self.shell.user_ns[i]
974
974
975 # some types are well known and can be shorter
975 # some types are well known and can be shorter
976 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
976 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
977 def type_name(v):
977 def type_name(v):
978 tn = type(v).__name__
978 tn = type(v).__name__
979 return abbrevs.get(tn,tn)
979 return abbrevs.get(tn,tn)
980
980
981 varlist = map(get_vars,varnames)
981 varlist = map(get_vars,varnames)
982
982
983 typelist = []
983 typelist = []
984 for vv in varlist:
984 for vv in varlist:
985 tt = type_name(vv)
985 tt = type_name(vv)
986
986
987 if tt=='instance':
987 if tt=='instance':
988 typelist.append( abbrevs.get(str(vv.__class__),
988 typelist.append( abbrevs.get(str(vv.__class__),
989 str(vv.__class__)))
989 str(vv.__class__)))
990 else:
990 else:
991 typelist.append(tt)
991 typelist.append(tt)
992
992
993 # column labels and # of spaces as separator
993 # column labels and # of spaces as separator
994 varlabel = 'Variable'
994 varlabel = 'Variable'
995 typelabel = 'Type'
995 typelabel = 'Type'
996 datalabel = 'Data/Info'
996 datalabel = 'Data/Info'
997 colsep = 3
997 colsep = 3
998 # variable format strings
998 # variable format strings
999 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
999 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1000 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1000 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1001 aformat = "%s: %s elems, type `%s`, %s bytes"
1001 aformat = "%s: %s elems, type `%s`, %s bytes"
1002 # find the size of the columns to format the output nicely
1002 # find the size of the columns to format the output nicely
1003 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1003 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1004 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1004 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1005 # table header
1005 # table header
1006 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1006 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1007 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1007 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1008 # and the table itself
1008 # and the table itself
1009 kb = 1024
1009 kb = 1024
1010 Mb = 1048576 # kb**2
1010 Mb = 1048576 # kb**2
1011 for vname,var,vtype in zip(varnames,varlist,typelist):
1011 for vname,var,vtype in zip(varnames,varlist,typelist):
1012 print itpl(vformat),
1012 print itpl(vformat),
1013 if vtype in seq_types:
1013 if vtype in seq_types:
1014 print len(var)
1014 print len(var)
1015 elif vtype in [array_type,ndarray_type]:
1015 elif vtype in [array_type,ndarray_type]:
1016 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1016 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1017 if vtype==ndarray_type:
1017 if vtype==ndarray_type:
1018 # numpy
1018 # numpy
1019 vsize = var.size
1019 vsize = var.size
1020 vbytes = vsize*var.itemsize
1020 vbytes = vsize*var.itemsize
1021 vdtype = var.dtype
1021 vdtype = var.dtype
1022 else:
1022 else:
1023 # Numeric
1023 # Numeric
1024 vsize = Numeric.size(var)
1024 vsize = Numeric.size(var)
1025 vbytes = vsize*var.itemsize()
1025 vbytes = vsize*var.itemsize()
1026 vdtype = var.typecode()
1026 vdtype = var.typecode()
1027
1027
1028 if vbytes < 100000:
1028 if vbytes < 100000:
1029 print aformat % (vshape,vsize,vdtype,vbytes)
1029 print aformat % (vshape,vsize,vdtype,vbytes)
1030 else:
1030 else:
1031 print aformat % (vshape,vsize,vdtype,vbytes),
1031 print aformat % (vshape,vsize,vdtype,vbytes),
1032 if vbytes < Mb:
1032 if vbytes < Mb:
1033 print '(%s kb)' % (vbytes/kb,)
1033 print '(%s kb)' % (vbytes/kb,)
1034 else:
1034 else:
1035 print '(%s Mb)' % (vbytes/Mb,)
1035 print '(%s Mb)' % (vbytes/Mb,)
1036 else:
1036 else:
1037 try:
1037 try:
1038 vstr = str(var)
1038 vstr = str(var)
1039 except UnicodeEncodeError:
1039 except UnicodeEncodeError:
1040 vstr = unicode(var).encode(sys.getdefaultencoding(),
1040 vstr = unicode(var).encode(sys.getdefaultencoding(),
1041 'backslashreplace')
1041 'backslashreplace')
1042 vstr = vstr.replace('\n','\\n')
1042 vstr = vstr.replace('\n','\\n')
1043 if len(vstr) < 50:
1043 if len(vstr) < 50:
1044 print vstr
1044 print vstr
1045 else:
1045 else:
1046 printpl(vfmt_short)
1046 printpl(vfmt_short)
1047
1047
1048 def magic_reset(self, parameter_s=''):
1048 def magic_reset(self, parameter_s=''):
1049 """Resets the namespace by removing all names defined by the user.
1049 """Resets the namespace by removing all names defined by the user.
1050
1050
1051 Input/Output history are left around in case you need them.
1051 Input/Output history are left around in case you need them.
1052
1052
1053 Parameters
1053 Parameters
1054 ----------
1054 ----------
1055 -y : force reset without asking for confirmation.
1055 -y : force reset without asking for confirmation.
1056
1056
1057 Examples
1057 Examples
1058 --------
1058 --------
1059 In [6]: a = 1
1059 In [6]: a = 1
1060
1060
1061 In [7]: a
1061 In [7]: a
1062 Out[7]: 1
1062 Out[7]: 1
1063
1063
1064 In [8]: 'a' in _ip.user_ns
1064 In [8]: 'a' in _ip.user_ns
1065 Out[8]: True
1065 Out[8]: True
1066
1066
1067 In [9]: %reset -f
1067 In [9]: %reset -f
1068
1068
1069 In [10]: 'a' in _ip.user_ns
1069 In [10]: 'a' in _ip.user_ns
1070 Out[10]: False
1070 Out[10]: False
1071 """
1071 """
1072
1072
1073 if parameter_s == '-f':
1073 if parameter_s == '-f':
1074 ans = True
1074 ans = True
1075 else:
1075 else:
1076 ans = self.shell.ask_yes_no(
1076 ans = self.shell.ask_yes_no(
1077 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1077 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1078 if not ans:
1078 if not ans:
1079 print 'Nothing done.'
1079 print 'Nothing done.'
1080 return
1080 return
1081 user_ns = self.shell.user_ns
1081 user_ns = self.shell.user_ns
1082 for i in self.magic_who_ls():
1082 for i in self.magic_who_ls():
1083 del(user_ns[i])
1083 del(user_ns[i])
1084
1084
1085 # Also flush the private list of module references kept for script
1085 # Also flush the private list of module references kept for script
1086 # execution protection
1086 # execution protection
1087 self.shell.clear_main_mod_cache()
1087 self.shell.clear_main_mod_cache()
1088
1088
1089 def magic_logstart(self,parameter_s=''):
1089 def magic_logstart(self,parameter_s=''):
1090 """Start logging anywhere in a session.
1090 """Start logging anywhere in a session.
1091
1091
1092 %logstart [-o|-r|-t] [log_name [log_mode]]
1092 %logstart [-o|-r|-t] [log_name [log_mode]]
1093
1093
1094 If no name is given, it defaults to a file named 'ipython_log.py' in your
1094 If no name is given, it defaults to a file named 'ipython_log.py' in your
1095 current directory, in 'rotate' mode (see below).
1095 current directory, in 'rotate' mode (see below).
1096
1096
1097 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1097 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1098 history up to that point and then continues logging.
1098 history up to that point and then continues logging.
1099
1099
1100 %logstart takes a second optional parameter: logging mode. This can be one
1100 %logstart takes a second optional parameter: logging mode. This can be one
1101 of (note that the modes are given unquoted):\\
1101 of (note that the modes are given unquoted):\\
1102 append: well, that says it.\\
1102 append: well, that says it.\\
1103 backup: rename (if exists) to name~ and start name.\\
1103 backup: rename (if exists) to name~ and start name.\\
1104 global: single logfile in your home dir, appended to.\\
1104 global: single logfile in your home dir, appended to.\\
1105 over : overwrite existing log.\\
1105 over : overwrite existing log.\\
1106 rotate: create rotating logs name.1~, name.2~, etc.
1106 rotate: create rotating logs name.1~, name.2~, etc.
1107
1107
1108 Options:
1108 Options:
1109
1109
1110 -o: log also IPython's output. In this mode, all commands which
1110 -o: log also IPython's output. In this mode, all commands which
1111 generate an Out[NN] prompt are recorded to the logfile, right after
1111 generate an Out[NN] prompt are recorded to the logfile, right after
1112 their corresponding input line. The output lines are always
1112 their corresponding input line. The output lines are always
1113 prepended with a '#[Out]# ' marker, so that the log remains valid
1113 prepended with a '#[Out]# ' marker, so that the log remains valid
1114 Python code.
1114 Python code.
1115
1115
1116 Since this marker is always the same, filtering only the output from
1116 Since this marker is always the same, filtering only the output from
1117 a log is very easy, using for example a simple awk call:
1117 a log is very easy, using for example a simple awk call:
1118
1118
1119 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1119 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1120
1120
1121 -r: log 'raw' input. Normally, IPython's logs contain the processed
1121 -r: log 'raw' input. Normally, IPython's logs contain the processed
1122 input, so that user lines are logged in their final form, converted
1122 input, so that user lines are logged in their final form, converted
1123 into valid Python. For example, %Exit is logged as
1123 into valid Python. For example, %Exit is logged as
1124 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1124 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1125 exactly as typed, with no transformations applied.
1125 exactly as typed, with no transformations applied.
1126
1126
1127 -t: put timestamps before each input line logged (these are put in
1127 -t: put timestamps before each input line logged (these are put in
1128 comments)."""
1128 comments)."""
1129
1129
1130 opts,par = self.parse_options(parameter_s,'ort')
1130 opts,par = self.parse_options(parameter_s,'ort')
1131 log_output = 'o' in opts
1131 log_output = 'o' in opts
1132 log_raw_input = 'r' in opts
1132 log_raw_input = 'r' in opts
1133 timestamp = 't' in opts
1133 timestamp = 't' in opts
1134
1134
1135 rc = self.shell.rc
1135 rc = self.shell.rc
1136 logger = self.shell.logger
1136 logger = self.shell.logger
1137
1137
1138 # if no args are given, the defaults set in the logger constructor by
1138 # if no args are given, the defaults set in the logger constructor by
1139 # ipytohn remain valid
1139 # ipytohn remain valid
1140 if par:
1140 if par:
1141 try:
1141 try:
1142 logfname,logmode = par.split()
1142 logfname,logmode = par.split()
1143 except:
1143 except:
1144 logfname = par
1144 logfname = par
1145 logmode = 'backup'
1145 logmode = 'backup'
1146 else:
1146 else:
1147 logfname = logger.logfname
1147 logfname = logger.logfname
1148 logmode = logger.logmode
1148 logmode = logger.logmode
1149 # put logfname into rc struct as if it had been called on the command
1149 # put logfname into rc struct as if it had been called on the command
1150 # line, so it ends up saved in the log header Save it in case we need
1150 # line, so it ends up saved in the log header Save it in case we need
1151 # to restore it...
1151 # to restore it...
1152 old_logfile = rc.opts.get('logfile','')
1152 old_logfile = rc.opts.get('logfile','')
1153 if logfname:
1153 if logfname:
1154 logfname = os.path.expanduser(logfname)
1154 logfname = os.path.expanduser(logfname)
1155 rc.opts.logfile = logfname
1155 rc.opts.logfile = logfname
1156 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1156 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1157 try:
1157 try:
1158 started = logger.logstart(logfname,loghead,logmode,
1158 started = logger.logstart(logfname,loghead,logmode,
1159 log_output,timestamp,log_raw_input)
1159 log_output,timestamp,log_raw_input)
1160 except:
1160 except:
1161 rc.opts.logfile = old_logfile
1161 rc.opts.logfile = old_logfile
1162 warn("Couldn't start log: %s" % sys.exc_info()[1])
1162 warn("Couldn't start log: %s" % sys.exc_info()[1])
1163 else:
1163 else:
1164 # log input history up to this point, optionally interleaving
1164 # log input history up to this point, optionally interleaving
1165 # output if requested
1165 # output if requested
1166
1166
1167 if timestamp:
1167 if timestamp:
1168 # disable timestamping for the previous history, since we've
1168 # disable timestamping for the previous history, since we've
1169 # lost those already (no time machine here).
1169 # lost those already (no time machine here).
1170 logger.timestamp = False
1170 logger.timestamp = False
1171
1171
1172 if log_raw_input:
1172 if log_raw_input:
1173 input_hist = self.shell.input_hist_raw
1173 input_hist = self.shell.input_hist_raw
1174 else:
1174 else:
1175 input_hist = self.shell.input_hist
1175 input_hist = self.shell.input_hist
1176
1176
1177 if log_output:
1177 if log_output:
1178 log_write = logger.log_write
1178 log_write = logger.log_write
1179 output_hist = self.shell.output_hist
1179 output_hist = self.shell.output_hist
1180 for n in range(1,len(input_hist)-1):
1180 for n in range(1,len(input_hist)-1):
1181 log_write(input_hist[n].rstrip())
1181 log_write(input_hist[n].rstrip())
1182 if n in output_hist:
1182 if n in output_hist:
1183 log_write(repr(output_hist[n]),'output')
1183 log_write(repr(output_hist[n]),'output')
1184 else:
1184 else:
1185 logger.log_write(input_hist[1:])
1185 logger.log_write(input_hist[1:])
1186 if timestamp:
1186 if timestamp:
1187 # re-enable timestamping
1187 # re-enable timestamping
1188 logger.timestamp = True
1188 logger.timestamp = True
1189
1189
1190 print ('Activating auto-logging. '
1190 print ('Activating auto-logging. '
1191 'Current session state plus future input saved.')
1191 'Current session state plus future input saved.')
1192 logger.logstate()
1192 logger.logstate()
1193
1193
1194 def magic_logstop(self,parameter_s=''):
1194 def magic_logstop(self,parameter_s=''):
1195 """Fully stop logging and close log file.
1195 """Fully stop logging and close log file.
1196
1196
1197 In order to start logging again, a new %logstart call needs to be made,
1197 In order to start logging again, a new %logstart call needs to be made,
1198 possibly (though not necessarily) with a new filename, mode and other
1198 possibly (though not necessarily) with a new filename, mode and other
1199 options."""
1199 options."""
1200 self.logger.logstop()
1200 self.logger.logstop()
1201
1201
1202 def magic_logoff(self,parameter_s=''):
1202 def magic_logoff(self,parameter_s=''):
1203 """Temporarily stop logging.
1203 """Temporarily stop logging.
1204
1204
1205 You must have previously started logging."""
1205 You must have previously started logging."""
1206 self.shell.logger.switch_log(0)
1206 self.shell.logger.switch_log(0)
1207
1207
1208 def magic_logon(self,parameter_s=''):
1208 def magic_logon(self,parameter_s=''):
1209 """Restart logging.
1209 """Restart logging.
1210
1210
1211 This function is for restarting logging which you've temporarily
1211 This function is for restarting logging which you've temporarily
1212 stopped with %logoff. For starting logging for the first time, you
1212 stopped with %logoff. For starting logging for the first time, you
1213 must use the %logstart function, which allows you to specify an
1213 must use the %logstart function, which allows you to specify an
1214 optional log filename."""
1214 optional log filename."""
1215
1215
1216 self.shell.logger.switch_log(1)
1216 self.shell.logger.switch_log(1)
1217
1217
1218 def magic_logstate(self,parameter_s=''):
1218 def magic_logstate(self,parameter_s=''):
1219 """Print the status of the logging system."""
1219 """Print the status of the logging system."""
1220
1220
1221 self.shell.logger.logstate()
1221 self.shell.logger.logstate()
1222
1222
1223 def magic_pdb(self, parameter_s=''):
1223 def magic_pdb(self, parameter_s=''):
1224 """Control the automatic calling of the pdb interactive debugger.
1224 """Control the automatic calling of the pdb interactive debugger.
1225
1225
1226 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1226 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1227 argument it works as a toggle.
1227 argument it works as a toggle.
1228
1228
1229 When an exception is triggered, IPython can optionally call the
1229 When an exception is triggered, IPython can optionally call the
1230 interactive pdb debugger after the traceback printout. %pdb toggles
1230 interactive pdb debugger after the traceback printout. %pdb toggles
1231 this feature on and off.
1231 this feature on and off.
1232
1232
1233 The initial state of this feature is set in your ipythonrc
1233 The initial state of this feature is set in your ipythonrc
1234 configuration file (the variable is called 'pdb').
1234 configuration file (the variable is called 'pdb').
1235
1235
1236 If you want to just activate the debugger AFTER an exception has fired,
1236 If you want to just activate the debugger AFTER an exception has fired,
1237 without having to type '%pdb on' and rerunning your code, you can use
1237 without having to type '%pdb on' and rerunning your code, you can use
1238 the %debug magic."""
1238 the %debug magic."""
1239
1239
1240 par = parameter_s.strip().lower()
1240 par = parameter_s.strip().lower()
1241
1241
1242 if par:
1242 if par:
1243 try:
1243 try:
1244 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1244 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1245 except KeyError:
1245 except KeyError:
1246 print ('Incorrect argument. Use on/1, off/0, '
1246 print ('Incorrect argument. Use on/1, off/0, '
1247 'or nothing for a toggle.')
1247 'or nothing for a toggle.')
1248 return
1248 return
1249 else:
1249 else:
1250 # toggle
1250 # toggle
1251 new_pdb = not self.shell.call_pdb
1251 new_pdb = not self.shell.call_pdb
1252
1252
1253 # set on the shell
1253 # set on the shell
1254 self.shell.call_pdb = new_pdb
1254 self.shell.call_pdb = new_pdb
1255 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1255 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1256
1256
1257 def magic_debug(self, parameter_s=''):
1257 def magic_debug(self, parameter_s=''):
1258 """Activate the interactive debugger in post-mortem mode.
1258 """Activate the interactive debugger in post-mortem mode.
1259
1259
1260 If an exception has just occurred, this lets you inspect its stack
1260 If an exception has just occurred, this lets you inspect its stack
1261 frames interactively. Note that this will always work only on the last
1261 frames interactively. Note that this will always work only on the last
1262 traceback that occurred, so you must call this quickly after an
1262 traceback that occurred, so you must call this quickly after an
1263 exception that you wish to inspect has fired, because if another one
1263 exception that you wish to inspect has fired, because if another one
1264 occurs, it clobbers the previous one.
1264 occurs, it clobbers the previous one.
1265
1265
1266 If you want IPython to automatically do this on every exception, see
1266 If you want IPython to automatically do this on every exception, see
1267 the %pdb magic for more details.
1267 the %pdb magic for more details.
1268 """
1268 """
1269
1269
1270 self.shell.debugger(force=True)
1270 self.shell.debugger(force=True)
1271
1271
1272 @testdec.skip_doctest
1272 @testdec.skip_doctest
1273 def magic_prun(self, parameter_s ='',user_mode=1,
1273 def magic_prun(self, parameter_s ='',user_mode=1,
1274 opts=None,arg_lst=None,prog_ns=None):
1274 opts=None,arg_lst=None,prog_ns=None):
1275
1275
1276 """Run a statement through the python code profiler.
1276 """Run a statement through the python code profiler.
1277
1277
1278 Usage:
1278 Usage:
1279 %prun [options] statement
1279 %prun [options] statement
1280
1280
1281 The given statement (which doesn't require quote marks) is run via the
1281 The given statement (which doesn't require quote marks) is run via the
1282 python profiler in a manner similar to the profile.run() function.
1282 python profiler in a manner similar to the profile.run() function.
1283 Namespaces are internally managed to work correctly; profile.run
1283 Namespaces are internally managed to work correctly; profile.run
1284 cannot be used in IPython because it makes certain assumptions about
1284 cannot be used in IPython because it makes certain assumptions about
1285 namespaces which do not hold under IPython.
1285 namespaces which do not hold under IPython.
1286
1286
1287 Options:
1287 Options:
1288
1288
1289 -l <limit>: you can place restrictions on what or how much of the
1289 -l <limit>: you can place restrictions on what or how much of the
1290 profile gets printed. The limit value can be:
1290 profile gets printed. The limit value can be:
1291
1291
1292 * A string: only information for function names containing this string
1292 * A string: only information for function names containing this string
1293 is printed.
1293 is printed.
1294
1294
1295 * An integer: only these many lines are printed.
1295 * An integer: only these many lines are printed.
1296
1296
1297 * A float (between 0 and 1): this fraction of the report is printed
1297 * A float (between 0 and 1): this fraction of the report is printed
1298 (for example, use a limit of 0.4 to see the topmost 40% only).
1298 (for example, use a limit of 0.4 to see the topmost 40% only).
1299
1299
1300 You can combine several limits with repeated use of the option. For
1300 You can combine several limits with repeated use of the option. For
1301 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1301 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1302 information about class constructors.
1302 information about class constructors.
1303
1303
1304 -r: return the pstats.Stats object generated by the profiling. This
1304 -r: return the pstats.Stats object generated by the profiling. This
1305 object has all the information about the profile in it, and you can
1305 object has all the information about the profile in it, and you can
1306 later use it for further analysis or in other functions.
1306 later use it for further analysis or in other functions.
1307
1307
1308 -s <key>: sort profile by given key. You can provide more than one key
1308 -s <key>: sort profile by given key. You can provide more than one key
1309 by using the option several times: '-s key1 -s key2 -s key3...'. The
1309 by using the option several times: '-s key1 -s key2 -s key3...'. The
1310 default sorting key is 'time'.
1310 default sorting key is 'time'.
1311
1311
1312 The following is copied verbatim from the profile documentation
1312 The following is copied verbatim from the profile documentation
1313 referenced below:
1313 referenced below:
1314
1314
1315 When more than one key is provided, additional keys are used as
1315 When more than one key is provided, additional keys are used as
1316 secondary criteria when the there is equality in all keys selected
1316 secondary criteria when the there is equality in all keys selected
1317 before them.
1317 before them.
1318
1318
1319 Abbreviations can be used for any key names, as long as the
1319 Abbreviations can be used for any key names, as long as the
1320 abbreviation is unambiguous. The following are the keys currently
1320 abbreviation is unambiguous. The following are the keys currently
1321 defined:
1321 defined:
1322
1322
1323 Valid Arg Meaning
1323 Valid Arg Meaning
1324 "calls" call count
1324 "calls" call count
1325 "cumulative" cumulative time
1325 "cumulative" cumulative time
1326 "file" file name
1326 "file" file name
1327 "module" file name
1327 "module" file name
1328 "pcalls" primitive call count
1328 "pcalls" primitive call count
1329 "line" line number
1329 "line" line number
1330 "name" function name
1330 "name" function name
1331 "nfl" name/file/line
1331 "nfl" name/file/line
1332 "stdname" standard name
1332 "stdname" standard name
1333 "time" internal time
1333 "time" internal time
1334
1334
1335 Note that all sorts on statistics are in descending order (placing
1335 Note that all sorts on statistics are in descending order (placing
1336 most time consuming items first), where as name, file, and line number
1336 most time consuming items first), where as name, file, and line number
1337 searches are in ascending order (i.e., alphabetical). The subtle
1337 searches are in ascending order (i.e., alphabetical). The subtle
1338 distinction between "nfl" and "stdname" is that the standard name is a
1338 distinction between "nfl" and "stdname" is that the standard name is a
1339 sort of the name as printed, which means that the embedded line
1339 sort of the name as printed, which means that the embedded line
1340 numbers get compared in an odd way. For example, lines 3, 20, and 40
1340 numbers get compared in an odd way. For example, lines 3, 20, and 40
1341 would (if the file names were the same) appear in the string order
1341 would (if the file names were the same) appear in the string order
1342 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1342 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1343 line numbers. In fact, sort_stats("nfl") is the same as
1343 line numbers. In fact, sort_stats("nfl") is the same as
1344 sort_stats("name", "file", "line").
1344 sort_stats("name", "file", "line").
1345
1345
1346 -T <filename>: save profile results as shown on screen to a text
1346 -T <filename>: save profile results as shown on screen to a text
1347 file. The profile is still shown on screen.
1347 file. The profile is still shown on screen.
1348
1348
1349 -D <filename>: save (via dump_stats) profile statistics to given
1349 -D <filename>: save (via dump_stats) profile statistics to given
1350 filename. This data is in a format understod by the pstats module, and
1350 filename. This data is in a format understod by the pstats module, and
1351 is generated by a call to the dump_stats() method of profile
1351 is generated by a call to the dump_stats() method of profile
1352 objects. The profile is still shown on screen.
1352 objects. The profile is still shown on screen.
1353
1353
1354 If you want to run complete programs under the profiler's control, use
1354 If you want to run complete programs under the profiler's control, use
1355 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1355 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1356 contains profiler specific options as described here.
1356 contains profiler specific options as described here.
1357
1357
1358 You can read the complete documentation for the profile module with::
1358 You can read the complete documentation for the profile module with::
1359
1359
1360 In [1]: import profile; profile.help()
1360 In [1]: import profile; profile.help()
1361 """
1361 """
1362
1362
1363 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1363 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1364 # protect user quote marks
1364 # protect user quote marks
1365 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1365 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1366
1366
1367 if user_mode: # regular user call
1367 if user_mode: # regular user call
1368 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1368 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1369 list_all=1)
1369 list_all=1)
1370 namespace = self.shell.user_ns
1370 namespace = self.shell.user_ns
1371 else: # called to run a program by %run -p
1371 else: # called to run a program by %run -p
1372 try:
1372 try:
1373 filename = get_py_filename(arg_lst[0])
1373 filename = get_py_filename(arg_lst[0])
1374 except IOError,msg:
1374 except IOError,msg:
1375 error(msg)
1375 error(msg)
1376 return
1376 return
1377
1377
1378 arg_str = 'execfile(filename,prog_ns)'
1378 arg_str = 'execfile(filename,prog_ns)'
1379 namespace = locals()
1379 namespace = locals()
1380
1380
1381 opts.merge(opts_def)
1381 opts.merge(opts_def)
1382
1382
1383 prof = profile.Profile()
1383 prof = profile.Profile()
1384 try:
1384 try:
1385 prof = prof.runctx(arg_str,namespace,namespace)
1385 prof = prof.runctx(arg_str,namespace,namespace)
1386 sys_exit = ''
1386 sys_exit = ''
1387 except SystemExit:
1387 except SystemExit:
1388 sys_exit = """*** SystemExit exception caught in code being profiled."""
1388 sys_exit = """*** SystemExit exception caught in code being profiled."""
1389
1389
1390 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1390 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1391
1391
1392 lims = opts.l
1392 lims = opts.l
1393 if lims:
1393 if lims:
1394 lims = [] # rebuild lims with ints/floats/strings
1394 lims = [] # rebuild lims with ints/floats/strings
1395 for lim in opts.l:
1395 for lim in opts.l:
1396 try:
1396 try:
1397 lims.append(int(lim))
1397 lims.append(int(lim))
1398 except ValueError:
1398 except ValueError:
1399 try:
1399 try:
1400 lims.append(float(lim))
1400 lims.append(float(lim))
1401 except ValueError:
1401 except ValueError:
1402 lims.append(lim)
1402 lims.append(lim)
1403
1403
1404 # Trap output.
1404 # Trap output.
1405 stdout_trap = StringIO()
1405 stdout_trap = StringIO()
1406
1406
1407 if hasattr(stats,'stream'):
1407 if hasattr(stats,'stream'):
1408 # In newer versions of python, the stats object has a 'stream'
1408 # In newer versions of python, the stats object has a 'stream'
1409 # attribute to write into.
1409 # attribute to write into.
1410 stats.stream = stdout_trap
1410 stats.stream = stdout_trap
1411 stats.print_stats(*lims)
1411 stats.print_stats(*lims)
1412 else:
1412 else:
1413 # For older versions, we manually redirect stdout during printing
1413 # For older versions, we manually redirect stdout during printing
1414 sys_stdout = sys.stdout
1414 sys_stdout = sys.stdout
1415 try:
1415 try:
1416 sys.stdout = stdout_trap
1416 sys.stdout = stdout_trap
1417 stats.print_stats(*lims)
1417 stats.print_stats(*lims)
1418 finally:
1418 finally:
1419 sys.stdout = sys_stdout
1419 sys.stdout = sys_stdout
1420
1420
1421 output = stdout_trap.getvalue()
1421 output = stdout_trap.getvalue()
1422 output = output.rstrip()
1422 output = output.rstrip()
1423
1423
1424 page(output,screen_lines=self.shell.rc.screen_length)
1424 page(output,screen_lines=self.shell.rc.screen_length)
1425 print sys_exit,
1425 print sys_exit,
1426
1426
1427 dump_file = opts.D[0]
1427 dump_file = opts.D[0]
1428 text_file = opts.T[0]
1428 text_file = opts.T[0]
1429 if dump_file:
1429 if dump_file:
1430 prof.dump_stats(dump_file)
1430 prof.dump_stats(dump_file)
1431 print '\n*** Profile stats marshalled to file',\
1431 print '\n*** Profile stats marshalled to file',\
1432 `dump_file`+'.',sys_exit
1432 `dump_file`+'.',sys_exit
1433 if text_file:
1433 if text_file:
1434 pfile = file(text_file,'w')
1434 pfile = file(text_file,'w')
1435 pfile.write(output)
1435 pfile.write(output)
1436 pfile.close()
1436 pfile.close()
1437 print '\n*** Profile printout saved to text file',\
1437 print '\n*** Profile printout saved to text file',\
1438 `text_file`+'.',sys_exit
1438 `text_file`+'.',sys_exit
1439
1439
1440 if opts.has_key('r'):
1440 if opts.has_key('r'):
1441 return stats
1441 return stats
1442 else:
1442 else:
1443 return None
1443 return None
1444
1444
1445 @testdec.skip_doctest
1445 @testdec.skip_doctest
1446 def magic_run(self, parameter_s ='',runner=None,
1446 def magic_run(self, parameter_s ='',runner=None,
1447 file_finder=get_py_filename):
1447 file_finder=get_py_filename):
1448 """Run the named file inside IPython as a program.
1448 """Run the named file inside IPython as a program.
1449
1449
1450 Usage:\\
1450 Usage:\\
1451 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1451 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1452
1452
1453 Parameters after the filename are passed as command-line arguments to
1453 Parameters after the filename are passed as command-line arguments to
1454 the program (put in sys.argv). Then, control returns to IPython's
1454 the program (put in sys.argv). Then, control returns to IPython's
1455 prompt.
1455 prompt.
1456
1456
1457 This is similar to running at a system prompt:\\
1457 This is similar to running at a system prompt:\\
1458 $ python file args\\
1458 $ python file args\\
1459 but with the advantage of giving you IPython's tracebacks, and of
1459 but with the advantage of giving you IPython's tracebacks, and of
1460 loading all variables into your interactive namespace for further use
1460 loading all variables into your interactive namespace for further use
1461 (unless -p is used, see below).
1461 (unless -p is used, see below).
1462
1462
1463 The file is executed in a namespace initially consisting only of
1463 The file is executed in a namespace initially consisting only of
1464 __name__=='__main__' and sys.argv constructed as indicated. It thus
1464 __name__=='__main__' and sys.argv constructed as indicated. It thus
1465 sees its environment as if it were being run as a stand-alone program
1465 sees its environment as if it were being run as a stand-alone program
1466 (except for sharing global objects such as previously imported
1466 (except for sharing global objects such as previously imported
1467 modules). But after execution, the IPython interactive namespace gets
1467 modules). But after execution, the IPython interactive namespace gets
1468 updated with all variables defined in the program (except for __name__
1468 updated with all variables defined in the program (except for __name__
1469 and sys.argv). This allows for very convenient loading of code for
1469 and sys.argv). This allows for very convenient loading of code for
1470 interactive work, while giving each program a 'clean sheet' to run in.
1470 interactive work, while giving each program a 'clean sheet' to run in.
1471
1471
1472 Options:
1472 Options:
1473
1473
1474 -n: __name__ is NOT set to '__main__', but to the running file's name
1474 -n: __name__ is NOT set to '__main__', but to the running file's name
1475 without extension (as python does under import). This allows running
1475 without extension (as python does under import). This allows running
1476 scripts and reloading the definitions in them without calling code
1476 scripts and reloading the definitions in them without calling code
1477 protected by an ' if __name__ == "__main__" ' clause.
1477 protected by an ' if __name__ == "__main__" ' clause.
1478
1478
1479 -i: run the file in IPython's namespace instead of an empty one. This
1479 -i: run the file in IPython's namespace instead of an empty one. This
1480 is useful if you are experimenting with code written in a text editor
1480 is useful if you are experimenting with code written in a text editor
1481 which depends on variables defined interactively.
1481 which depends on variables defined interactively.
1482
1482
1483 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1483 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1484 being run. This is particularly useful if IPython is being used to
1484 being run. This is particularly useful if IPython is being used to
1485 run unittests, which always exit with a sys.exit() call. In such
1485 run unittests, which always exit with a sys.exit() call. In such
1486 cases you are interested in the output of the test results, not in
1486 cases you are interested in the output of the test results, not in
1487 seeing a traceback of the unittest module.
1487 seeing a traceback of the unittest module.
1488
1488
1489 -t: print timing information at the end of the run. IPython will give
1489 -t: print timing information at the end of the run. IPython will give
1490 you an estimated CPU time consumption for your script, which under
1490 you an estimated CPU time consumption for your script, which under
1491 Unix uses the resource module to avoid the wraparound problems of
1491 Unix uses the resource module to avoid the wraparound problems of
1492 time.clock(). Under Unix, an estimate of time spent on system tasks
1492 time.clock(). Under Unix, an estimate of time spent on system tasks
1493 is also given (for Windows platforms this is reported as 0.0).
1493 is also given (for Windows platforms this is reported as 0.0).
1494
1494
1495 If -t is given, an additional -N<N> option can be given, where <N>
1495 If -t is given, an additional -N<N> option can be given, where <N>
1496 must be an integer indicating how many times you want the script to
1496 must be an integer indicating how many times you want the script to
1497 run. The final timing report will include total and per run results.
1497 run. The final timing report will include total and per run results.
1498
1498
1499 For example (testing the script uniq_stable.py):
1499 For example (testing the script uniq_stable.py):
1500
1500
1501 In [1]: run -t uniq_stable
1501 In [1]: run -t uniq_stable
1502
1502
1503 IPython CPU timings (estimated):\\
1503 IPython CPU timings (estimated):\\
1504 User : 0.19597 s.\\
1504 User : 0.19597 s.\\
1505 System: 0.0 s.\\
1505 System: 0.0 s.\\
1506
1506
1507 In [2]: run -t -N5 uniq_stable
1507 In [2]: run -t -N5 uniq_stable
1508
1508
1509 IPython CPU timings (estimated):\\
1509 IPython CPU timings (estimated):\\
1510 Total runs performed: 5\\
1510 Total runs performed: 5\\
1511 Times : Total Per run\\
1511 Times : Total Per run\\
1512 User : 0.910862 s, 0.1821724 s.\\
1512 User : 0.910862 s, 0.1821724 s.\\
1513 System: 0.0 s, 0.0 s.
1513 System: 0.0 s, 0.0 s.
1514
1514
1515 -d: run your program under the control of pdb, the Python debugger.
1515 -d: run your program under the control of pdb, the Python debugger.
1516 This allows you to execute your program step by step, watch variables,
1516 This allows you to execute your program step by step, watch variables,
1517 etc. Internally, what IPython does is similar to calling:
1517 etc. Internally, what IPython does is similar to calling:
1518
1518
1519 pdb.run('execfile("YOURFILENAME")')
1519 pdb.run('execfile("YOURFILENAME")')
1520
1520
1521 with a breakpoint set on line 1 of your file. You can change the line
1521 with a breakpoint set on line 1 of your file. You can change the line
1522 number for this automatic breakpoint to be <N> by using the -bN option
1522 number for this automatic breakpoint to be <N> by using the -bN option
1523 (where N must be an integer). For example:
1523 (where N must be an integer). For example:
1524
1524
1525 %run -d -b40 myscript
1525 %run -d -b40 myscript
1526
1526
1527 will set the first breakpoint at line 40 in myscript.py. Note that
1527 will set the first breakpoint at line 40 in myscript.py. Note that
1528 the first breakpoint must be set on a line which actually does
1528 the first breakpoint must be set on a line which actually does
1529 something (not a comment or docstring) for it to stop execution.
1529 something (not a comment or docstring) for it to stop execution.
1530
1530
1531 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1531 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1532 first enter 'c' (without qoutes) to start execution up to the first
1532 first enter 'c' (without qoutes) to start execution up to the first
1533 breakpoint.
1533 breakpoint.
1534
1534
1535 Entering 'help' gives information about the use of the debugger. You
1535 Entering 'help' gives information about the use of the debugger. You
1536 can easily see pdb's full documentation with "import pdb;pdb.help()"
1536 can easily see pdb's full documentation with "import pdb;pdb.help()"
1537 at a prompt.
1537 at a prompt.
1538
1538
1539 -p: run program under the control of the Python profiler module (which
1539 -p: run program under the control of the Python profiler module (which
1540 prints a detailed report of execution times, function calls, etc).
1540 prints a detailed report of execution times, function calls, etc).
1541
1541
1542 You can pass other options after -p which affect the behavior of the
1542 You can pass other options after -p which affect the behavior of the
1543 profiler itself. See the docs for %prun for details.
1543 profiler itself. See the docs for %prun for details.
1544
1544
1545 In this mode, the program's variables do NOT propagate back to the
1545 In this mode, the program's variables do NOT propagate back to the
1546 IPython interactive namespace (because they remain in the namespace
1546 IPython interactive namespace (because they remain in the namespace
1547 where the profiler executes them).
1547 where the profiler executes them).
1548
1548
1549 Internally this triggers a call to %prun, see its documentation for
1549 Internally this triggers a call to %prun, see its documentation for
1550 details on the options available specifically for profiling.
1550 details on the options available specifically for profiling.
1551
1551
1552 There is one special usage for which the text above doesn't apply:
1552 There is one special usage for which the text above doesn't apply:
1553 if the filename ends with .ipy, the file is run as ipython script,
1553 if the filename ends with .ipy, the file is run as ipython script,
1554 just as if the commands were written on IPython prompt.
1554 just as if the commands were written on IPython prompt.
1555 """
1555 """
1556
1556
1557 # get arguments and set sys.argv for program to be run.
1557 # get arguments and set sys.argv for program to be run.
1558 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1558 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1559 mode='list',list_all=1)
1559 mode='list',list_all=1)
1560
1560
1561 try:
1561 try:
1562 filename = file_finder(arg_lst[0])
1562 filename = file_finder(arg_lst[0])
1563 except IndexError:
1563 except IndexError:
1564 warn('you must provide at least a filename.')
1564 warn('you must provide at least a filename.')
1565 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1565 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1566 return
1566 return
1567 except IOError,msg:
1567 except IOError,msg:
1568 error(msg)
1568 error(msg)
1569 return
1569 return
1570
1570
1571 if filename.lower().endswith('.ipy'):
1571 if filename.lower().endswith('.ipy'):
1572 self.api.runlines(open(filename).read())
1572 self.api.runlines(open(filename).read())
1573 return
1573 return
1574
1574
1575 # Control the response to exit() calls made by the script being run
1575 # Control the response to exit() calls made by the script being run
1576 exit_ignore = opts.has_key('e')
1576 exit_ignore = opts.has_key('e')
1577
1577
1578 # Make sure that the running script gets a proper sys.argv as if it
1578 # Make sure that the running script gets a proper sys.argv as if it
1579 # were run from a system shell.
1579 # were run from a system shell.
1580 save_argv = sys.argv # save it for later restoring
1580 save_argv = sys.argv # save it for later restoring
1581 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1581 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1582
1582
1583 if opts.has_key('i'):
1583 if opts.has_key('i'):
1584 # Run in user's interactive namespace
1584 # Run in user's interactive namespace
1585 prog_ns = self.shell.user_ns
1585 prog_ns = self.shell.user_ns
1586 __name__save = self.shell.user_ns['__name__']
1586 __name__save = self.shell.user_ns['__name__']
1587 prog_ns['__name__'] = '__main__'
1587 prog_ns['__name__'] = '__main__'
1588 main_mod = self.shell.new_main_mod(prog_ns)
1588 main_mod = self.shell.new_main_mod(prog_ns)
1589 else:
1589 else:
1590 # Run in a fresh, empty namespace
1590 # Run in a fresh, empty namespace
1591 if opts.has_key('n'):
1591 if opts.has_key('n'):
1592 name = os.path.splitext(os.path.basename(filename))[0]
1592 name = os.path.splitext(os.path.basename(filename))[0]
1593 else:
1593 else:
1594 name = '__main__'
1594 name = '__main__'
1595
1595
1596 main_mod = self.shell.new_main_mod()
1596 main_mod = self.shell.new_main_mod()
1597 prog_ns = main_mod.__dict__
1597 prog_ns = main_mod.__dict__
1598 prog_ns['__name__'] = name
1598 prog_ns['__name__'] = name
1599
1599
1600 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1600 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1601 # set the __file__ global in the script's namespace
1601 # set the __file__ global in the script's namespace
1602 prog_ns['__file__'] = filename
1602 prog_ns['__file__'] = filename
1603
1603
1604 # pickle fix. See iplib for an explanation. But we need to make sure
1604 # pickle fix. See iplib for an explanation. But we need to make sure
1605 # that, if we overwrite __main__, we replace it at the end
1605 # that, if we overwrite __main__, we replace it at the end
1606 main_mod_name = prog_ns['__name__']
1606 main_mod_name = prog_ns['__name__']
1607
1607
1608 if main_mod_name == '__main__':
1608 if main_mod_name == '__main__':
1609 restore_main = sys.modules['__main__']
1609 restore_main = sys.modules['__main__']
1610 else:
1610 else:
1611 restore_main = False
1611 restore_main = False
1612
1612
1613 # This needs to be undone at the end to prevent holding references to
1613 # This needs to be undone at the end to prevent holding references to
1614 # every single object ever created.
1614 # every single object ever created.
1615 sys.modules[main_mod_name] = main_mod
1615 sys.modules[main_mod_name] = main_mod
1616
1616
1617 stats = None
1617 stats = None
1618 try:
1618 try:
1619 self.shell.savehist()
1619 self.shell.savehist()
1620
1620
1621 if opts.has_key('p'):
1621 if opts.has_key('p'):
1622 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1622 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1623 else:
1623 else:
1624 if opts.has_key('d'):
1624 if opts.has_key('d'):
1625 deb = debugger.Pdb(self.shell.rc.colors)
1625 deb = debugger.Pdb(self.shell.rc.colors)
1626 # reset Breakpoint state, which is moronically kept
1626 # reset Breakpoint state, which is moronically kept
1627 # in a class
1627 # in a class
1628 bdb.Breakpoint.next = 1
1628 bdb.Breakpoint.next = 1
1629 bdb.Breakpoint.bplist = {}
1629 bdb.Breakpoint.bplist = {}
1630 bdb.Breakpoint.bpbynumber = [None]
1630 bdb.Breakpoint.bpbynumber = [None]
1631 # Set an initial breakpoint to stop execution
1631 # Set an initial breakpoint to stop execution
1632 maxtries = 10
1632 maxtries = 10
1633 bp = int(opts.get('b',[1])[0])
1633 bp = int(opts.get('b',[1])[0])
1634 checkline = deb.checkline(filename,bp)
1634 checkline = deb.checkline(filename,bp)
1635 if not checkline:
1635 if not checkline:
1636 for bp in range(bp+1,bp+maxtries+1):
1636 for bp in range(bp+1,bp+maxtries+1):
1637 if deb.checkline(filename,bp):
1637 if deb.checkline(filename,bp):
1638 break
1638 break
1639 else:
1639 else:
1640 msg = ("\nI failed to find a valid line to set "
1640 msg = ("\nI failed to find a valid line to set "
1641 "a breakpoint\n"
1641 "a breakpoint\n"
1642 "after trying up to line: %s.\n"
1642 "after trying up to line: %s.\n"
1643 "Please set a valid breakpoint manually "
1643 "Please set a valid breakpoint manually "
1644 "with the -b option." % bp)
1644 "with the -b option." % bp)
1645 error(msg)
1645 error(msg)
1646 return
1646 return
1647 # if we find a good linenumber, set the breakpoint
1647 # if we find a good linenumber, set the breakpoint
1648 deb.do_break('%s:%s' % (filename,bp))
1648 deb.do_break('%s:%s' % (filename,bp))
1649 # Start file run
1649 # Start file run
1650 print "NOTE: Enter 'c' at the",
1650 print "NOTE: Enter 'c' at the",
1651 print "%s prompt to start your script." % deb.prompt
1651 print "%s prompt to start your script." % deb.prompt
1652 try:
1652 try:
1653 deb.run('execfile("%s")' % filename,prog_ns)
1653 deb.run('execfile("%s")' % filename,prog_ns)
1654
1654
1655 except:
1655 except:
1656 etype, value, tb = sys.exc_info()
1656 etype, value, tb = sys.exc_info()
1657 # Skip three frames in the traceback: the %run one,
1657 # Skip three frames in the traceback: the %run one,
1658 # one inside bdb.py, and the command-line typed by the
1658 # one inside bdb.py, and the command-line typed by the
1659 # user (run by exec in pdb itself).
1659 # user (run by exec in pdb itself).
1660 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1660 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1661 else:
1661 else:
1662 if runner is None:
1662 if runner is None:
1663 runner = self.shell.safe_execfile
1663 runner = self.shell.safe_execfile
1664 if opts.has_key('t'):
1664 if opts.has_key('t'):
1665 # timed execution
1665 # timed execution
1666 try:
1666 try:
1667 nruns = int(opts['N'][0])
1667 nruns = int(opts['N'][0])
1668 if nruns < 1:
1668 if nruns < 1:
1669 error('Number of runs must be >=1')
1669 error('Number of runs must be >=1')
1670 return
1670 return
1671 except (KeyError):
1671 except (KeyError):
1672 nruns = 1
1672 nruns = 1
1673 if nruns == 1:
1673 if nruns == 1:
1674 t0 = clock2()
1674 t0 = clock2()
1675 runner(filename,prog_ns,prog_ns,
1675 runner(filename,prog_ns,prog_ns,
1676 exit_ignore=exit_ignore)
1676 exit_ignore=exit_ignore)
1677 t1 = clock2()
1677 t1 = clock2()
1678 t_usr = t1[0]-t0[0]
1678 t_usr = t1[0]-t0[0]
1679 t_sys = t1[1]-t0[1]
1679 t_sys = t1[1]-t0[1]
1680 print "\nIPython CPU timings (estimated):"
1680 print "\nIPython CPU timings (estimated):"
1681 print " User : %10s s." % t_usr
1681 print " User : %10s s." % t_usr
1682 print " System: %10s s." % t_sys
1682 print " System: %10s s." % t_sys
1683 else:
1683 else:
1684 runs = range(nruns)
1684 runs = range(nruns)
1685 t0 = clock2()
1685 t0 = clock2()
1686 for nr in runs:
1686 for nr in runs:
1687 runner(filename,prog_ns,prog_ns,
1687 runner(filename,prog_ns,prog_ns,
1688 exit_ignore=exit_ignore)
1688 exit_ignore=exit_ignore)
1689 t1 = clock2()
1689 t1 = clock2()
1690 t_usr = t1[0]-t0[0]
1690 t_usr = t1[0]-t0[0]
1691 t_sys = t1[1]-t0[1]
1691 t_sys = t1[1]-t0[1]
1692 print "\nIPython CPU timings (estimated):"
1692 print "\nIPython CPU timings (estimated):"
1693 print "Total runs performed:",nruns
1693 print "Total runs performed:",nruns
1694 print " Times : %10s %10s" % ('Total','Per run')
1694 print " Times : %10s %10s" % ('Total','Per run')
1695 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1695 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1696 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1696 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1697
1697
1698 else:
1698 else:
1699 # regular execution
1699 # regular execution
1700 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1700 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1701
1701
1702 if opts.has_key('i'):
1702 if opts.has_key('i'):
1703 self.shell.user_ns['__name__'] = __name__save
1703 self.shell.user_ns['__name__'] = __name__save
1704 else:
1704 else:
1705 # The shell MUST hold a reference to prog_ns so after %run
1705 # The shell MUST hold a reference to prog_ns so after %run
1706 # exits, the python deletion mechanism doesn't zero it out
1706 # exits, the python deletion mechanism doesn't zero it out
1707 # (leaving dangling references).
1707 # (leaving dangling references).
1708 self.shell.cache_main_mod(prog_ns,filename)
1708 self.shell.cache_main_mod(prog_ns,filename)
1709 # update IPython interactive namespace
1709 # update IPython interactive namespace
1710 del prog_ns['__name__']
1710 del prog_ns['__name__']
1711 self.shell.user_ns.update(prog_ns)
1711 self.shell.user_ns.update(prog_ns)
1712 finally:
1712 finally:
1713 # It's a bit of a mystery why, but __builtins__ can change from
1713 # It's a bit of a mystery why, but __builtins__ can change from
1714 # being a module to becoming a dict missing some key data after
1714 # being a module to becoming a dict missing some key data after
1715 # %run. As best I can see, this is NOT something IPython is doing
1715 # %run. As best I can see, this is NOT something IPython is doing
1716 # at all, and similar problems have been reported before:
1716 # at all, and similar problems have been reported before:
1717 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1717 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1718 # Since this seems to be done by the interpreter itself, the best
1718 # Since this seems to be done by the interpreter itself, the best
1719 # we can do is to at least restore __builtins__ for the user on
1719 # we can do is to at least restore __builtins__ for the user on
1720 # exit.
1720 # exit.
1721 self.shell.user_ns['__builtins__'] = __builtin__
1721 self.shell.user_ns['__builtins__'] = __builtin__
1722
1722
1723 # Ensure key global structures are restored
1723 # Ensure key global structures are restored
1724 sys.argv = save_argv
1724 sys.argv = save_argv
1725 if restore_main:
1725 if restore_main:
1726 sys.modules['__main__'] = restore_main
1726 sys.modules['__main__'] = restore_main
1727 else:
1727 else:
1728 # Remove from sys.modules the reference to main_mod we'd
1728 # Remove from sys.modules the reference to main_mod we'd
1729 # added. Otherwise it will trap references to objects
1729 # added. Otherwise it will trap references to objects
1730 # contained therein.
1730 # contained therein.
1731 del sys.modules[main_mod_name]
1731 del sys.modules[main_mod_name]
1732
1732
1733 self.shell.reloadhist()
1733 self.shell.reloadhist()
1734
1734
1735 return stats
1735 return stats
1736
1736
1737 def magic_runlog(self, parameter_s =''):
1737 def magic_runlog(self, parameter_s =''):
1738 """Run files as logs.
1738 """Run files as logs.
1739
1739
1740 Usage:\\
1740 Usage:\\
1741 %runlog file1 file2 ...
1741 %runlog file1 file2 ...
1742
1742
1743 Run the named files (treating them as log files) in sequence inside
1743 Run the named files (treating them as log files) in sequence inside
1744 the interpreter, and return to the prompt. This is much slower than
1744 the interpreter, and return to the prompt. This is much slower than
1745 %run because each line is executed in a try/except block, but it
1745 %run because each line is executed in a try/except block, but it
1746 allows running files with syntax errors in them.
1746 allows running files with syntax errors in them.
1747
1747
1748 Normally IPython will guess when a file is one of its own logfiles, so
1748 Normally IPython will guess when a file is one of its own logfiles, so
1749 you can typically use %run even for logs. This shorthand allows you to
1749 you can typically use %run even for logs. This shorthand allows you to
1750 force any file to be treated as a log file."""
1750 force any file to be treated as a log file."""
1751
1751
1752 for f in parameter_s.split():
1752 for f in parameter_s.split():
1753 self.shell.safe_execfile(f,self.shell.user_ns,
1753 self.shell.safe_execfile(f,self.shell.user_ns,
1754 self.shell.user_ns,islog=1)
1754 self.shell.user_ns,islog=1)
1755
1755
1756 @testdec.skip_doctest
1756 @testdec.skip_doctest
1757 def magic_timeit(self, parameter_s =''):
1757 def magic_timeit(self, parameter_s =''):
1758 """Time execution of a Python statement or expression
1758 """Time execution of a Python statement or expression
1759
1759
1760 Usage:\\
1760 Usage:\\
1761 %timeit [-n<N> -r<R> [-t|-c]] statement
1761 %timeit [-n<N> -r<R> [-t|-c]] statement
1762
1762
1763 Time execution of a Python statement or expression using the timeit
1763 Time execution of a Python statement or expression using the timeit
1764 module.
1764 module.
1765
1765
1766 Options:
1766 Options:
1767 -n<N>: execute the given statement <N> times in a loop. If this value
1767 -n<N>: execute the given statement <N> times in a loop. If this value
1768 is not given, a fitting value is chosen.
1768 is not given, a fitting value is chosen.
1769
1769
1770 -r<R>: repeat the loop iteration <R> times and take the best result.
1770 -r<R>: repeat the loop iteration <R> times and take the best result.
1771 Default: 3
1771 Default: 3
1772
1772
1773 -t: use time.time to measure the time, which is the default on Unix.
1773 -t: use time.time to measure the time, which is the default on Unix.
1774 This function measures wall time.
1774 This function measures wall time.
1775
1775
1776 -c: use time.clock to measure the time, which is the default on
1776 -c: use time.clock to measure the time, which is the default on
1777 Windows and measures wall time. On Unix, resource.getrusage is used
1777 Windows and measures wall time. On Unix, resource.getrusage is used
1778 instead and returns the CPU user time.
1778 instead and returns the CPU user time.
1779
1779
1780 -p<P>: use a precision of <P> digits to display the timing result.
1780 -p<P>: use a precision of <P> digits to display the timing result.
1781 Default: 3
1781 Default: 3
1782
1782
1783
1783
1784 Examples:
1784 Examples:
1785
1785
1786 In [1]: %timeit pass
1786 In [1]: %timeit pass
1787 10000000 loops, best of 3: 53.3 ns per loop
1787 10000000 loops, best of 3: 53.3 ns per loop
1788
1788
1789 In [2]: u = None
1789 In [2]: u = None
1790
1790
1791 In [3]: %timeit u is None
1791 In [3]: %timeit u is None
1792 10000000 loops, best of 3: 184 ns per loop
1792 10000000 loops, best of 3: 184 ns per loop
1793
1793
1794 In [4]: %timeit -r 4 u == None
1794 In [4]: %timeit -r 4 u == None
1795 1000000 loops, best of 4: 242 ns per loop
1795 1000000 loops, best of 4: 242 ns per loop
1796
1796
1797 In [5]: import time
1797 In [5]: import time
1798
1798
1799 In [6]: %timeit -n1 time.sleep(2)
1799 In [6]: %timeit -n1 time.sleep(2)
1800 1 loops, best of 3: 2 s per loop
1800 1 loops, best of 3: 2 s per loop
1801
1801
1802
1802
1803 The times reported by %timeit will be slightly higher than those
1803 The times reported by %timeit will be slightly higher than those
1804 reported by the timeit.py script when variables are accessed. This is
1804 reported by the timeit.py script when variables are accessed. This is
1805 due to the fact that %timeit executes the statement in the namespace
1805 due to the fact that %timeit executes the statement in the namespace
1806 of the shell, compared with timeit.py, which uses a single setup
1806 of the shell, compared with timeit.py, which uses a single setup
1807 statement to import function or create variables. Generally, the bias
1807 statement to import function or create variables. Generally, the bias
1808 does not matter as long as results from timeit.py are not mixed with
1808 does not matter as long as results from timeit.py are not mixed with
1809 those from %timeit."""
1809 those from %timeit."""
1810
1810
1811 import timeit
1811 import timeit
1812 import math
1812 import math
1813
1813
1814 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1814 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1815 # certain terminals. Until we figure out a robust way of
1815 # certain terminals. Until we figure out a robust way of
1816 # auto-detecting if the terminal can deal with it, use plain 'us' for
1816 # auto-detecting if the terminal can deal with it, use plain 'us' for
1817 # microseconds. I am really NOT happy about disabling the proper
1817 # microseconds. I am really NOT happy about disabling the proper
1818 # 'micro' prefix, but crashing is worse... If anyone knows what the
1818 # 'micro' prefix, but crashing is worse... If anyone knows what the
1819 # right solution for this is, I'm all ears...
1819 # right solution for this is, I'm all ears...
1820 #
1820 #
1821 # Note: using
1821 # Note: using
1822 #
1822 #
1823 # s = u'\xb5'
1823 # s = u'\xb5'
1824 # s.encode(sys.getdefaultencoding())
1824 # s.encode(sys.getdefaultencoding())
1825 #
1825 #
1826 # is not sufficient, as I've seen terminals where that fails but
1826 # is not sufficient, as I've seen terminals where that fails but
1827 # print s
1827 # print s
1828 #
1828 #
1829 # succeeds
1829 # succeeds
1830 #
1830 #
1831 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1831 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1832
1832
1833 #units = [u"s", u"ms",u'\xb5',"ns"]
1833 #units = [u"s", u"ms",u'\xb5',"ns"]
1834 units = [u"s", u"ms",u'us',"ns"]
1834 units = [u"s", u"ms",u'us',"ns"]
1835
1835
1836 scaling = [1, 1e3, 1e6, 1e9]
1836 scaling = [1, 1e3, 1e6, 1e9]
1837
1837
1838 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1838 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1839 posix=False)
1839 posix=False)
1840 if stmt == "":
1840 if stmt == "":
1841 return
1841 return
1842 timefunc = timeit.default_timer
1842 timefunc = timeit.default_timer
1843 number = int(getattr(opts, "n", 0))
1843 number = int(getattr(opts, "n", 0))
1844 repeat = int(getattr(opts, "r", timeit.default_repeat))
1844 repeat = int(getattr(opts, "r", timeit.default_repeat))
1845 precision = int(getattr(opts, "p", 3))
1845 precision = int(getattr(opts, "p", 3))
1846 if hasattr(opts, "t"):
1846 if hasattr(opts, "t"):
1847 timefunc = time.time
1847 timefunc = time.time
1848 if hasattr(opts, "c"):
1848 if hasattr(opts, "c"):
1849 timefunc = clock
1849 timefunc = clock
1850
1850
1851 timer = timeit.Timer(timer=timefunc)
1851 timer = timeit.Timer(timer=timefunc)
1852 # this code has tight coupling to the inner workings of timeit.Timer,
1852 # this code has tight coupling to the inner workings of timeit.Timer,
1853 # but is there a better way to achieve that the code stmt has access
1853 # but is there a better way to achieve that the code stmt has access
1854 # to the shell namespace?
1854 # to the shell namespace?
1855
1855
1856 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1856 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1857 'setup': "pass"}
1857 'setup': "pass"}
1858 # Track compilation time so it can be reported if too long
1858 # Track compilation time so it can be reported if too long
1859 # Minimum time above which compilation time will be reported
1859 # Minimum time above which compilation time will be reported
1860 tc_min = 0.1
1860 tc_min = 0.1
1861
1861
1862 t0 = clock()
1862 t0 = clock()
1863 code = compile(src, "<magic-timeit>", "exec")
1863 code = compile(src, "<magic-timeit>", "exec")
1864 tc = clock()-t0
1864 tc = clock()-t0
1865
1865
1866 ns = {}
1866 ns = {}
1867 exec code in self.shell.user_ns, ns
1867 exec code in self.shell.user_ns, ns
1868 timer.inner = ns["inner"]
1868 timer.inner = ns["inner"]
1869
1869
1870 if number == 0:
1870 if number == 0:
1871 # determine number so that 0.2 <= total time < 2.0
1871 # determine number so that 0.2 <= total time < 2.0
1872 number = 1
1872 number = 1
1873 for i in range(1, 10):
1873 for i in range(1, 10):
1874 if timer.timeit(number) >= 0.2:
1874 if timer.timeit(number) >= 0.2:
1875 break
1875 break
1876 number *= 10
1876 number *= 10
1877
1877
1878 best = min(timer.repeat(repeat, number)) / number
1878 best = min(timer.repeat(repeat, number)) / number
1879
1879
1880 if best > 0.0:
1880 if best > 0.0:
1881 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1881 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1882 else:
1882 else:
1883 order = 3
1883 order = 3
1884 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1884 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1885 precision,
1885 precision,
1886 best * scaling[order],
1886 best * scaling[order],
1887 units[order])
1887 units[order])
1888 if tc > tc_min:
1888 if tc > tc_min:
1889 print "Compiler time: %.2f s" % tc
1889 print "Compiler time: %.2f s" % tc
1890
1890
1891 @testdec.skip_doctest
1891 @testdec.skip_doctest
1892 def magic_time(self,parameter_s = ''):
1892 def magic_time(self,parameter_s = ''):
1893 """Time execution of a Python statement or expression.
1893 """Time execution of a Python statement or expression.
1894
1894
1895 The CPU and wall clock times are printed, and the value of the
1895 The CPU and wall clock times are printed, and the value of the
1896 expression (if any) is returned. Note that under Win32, system time
1896 expression (if any) is returned. Note that under Win32, system time
1897 is always reported as 0, since it can not be measured.
1897 is always reported as 0, since it can not be measured.
1898
1898
1899 This function provides very basic timing functionality. In Python
1899 This function provides very basic timing functionality. In Python
1900 2.3, the timeit module offers more control and sophistication, so this
1900 2.3, the timeit module offers more control and sophistication, so this
1901 could be rewritten to use it (patches welcome).
1901 could be rewritten to use it (patches welcome).
1902
1902
1903 Some examples:
1903 Some examples:
1904
1904
1905 In [1]: time 2**128
1905 In [1]: time 2**128
1906 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1906 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1907 Wall time: 0.00
1907 Wall time: 0.00
1908 Out[1]: 340282366920938463463374607431768211456L
1908 Out[1]: 340282366920938463463374607431768211456L
1909
1909
1910 In [2]: n = 1000000
1910 In [2]: n = 1000000
1911
1911
1912 In [3]: time sum(range(n))
1912 In [3]: time sum(range(n))
1913 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1913 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1914 Wall time: 1.37
1914 Wall time: 1.37
1915 Out[3]: 499999500000L
1915 Out[3]: 499999500000L
1916
1916
1917 In [4]: time print 'hello world'
1917 In [4]: time print 'hello world'
1918 hello world
1918 hello world
1919 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1919 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1920 Wall time: 0.00
1920 Wall time: 0.00
1921
1921
1922 Note that the time needed by Python to compile the given expression
1922 Note that the time needed by Python to compile the given expression
1923 will be reported if it is more than 0.1s. In this example, the
1923 will be reported if it is more than 0.1s. In this example, the
1924 actual exponentiation is done by Python at compilation time, so while
1924 actual exponentiation is done by Python at compilation time, so while
1925 the expression can take a noticeable amount of time to compute, that
1925 the expression can take a noticeable amount of time to compute, that
1926 time is purely due to the compilation:
1926 time is purely due to the compilation:
1927
1927
1928 In [5]: time 3**9999;
1928 In [5]: time 3**9999;
1929 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1929 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1930 Wall time: 0.00 s
1930 Wall time: 0.00 s
1931
1931
1932 In [6]: time 3**999999;
1932 In [6]: time 3**999999;
1933 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1933 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1934 Wall time: 0.00 s
1934 Wall time: 0.00 s
1935 Compiler : 0.78 s
1935 Compiler : 0.78 s
1936 """
1936 """
1937
1937
1938 # fail immediately if the given expression can't be compiled
1938 # fail immediately if the given expression can't be compiled
1939
1939
1940 expr = self.shell.prefilter(parameter_s,False)
1940 expr = self.shell.prefilter(parameter_s,False)
1941
1941
1942 # Minimum time above which compilation time will be reported
1942 # Minimum time above which compilation time will be reported
1943 tc_min = 0.1
1943 tc_min = 0.1
1944
1944
1945 try:
1945 try:
1946 mode = 'eval'
1946 mode = 'eval'
1947 t0 = clock()
1947 t0 = clock()
1948 code = compile(expr,'<timed eval>',mode)
1948 code = compile(expr,'<timed eval>',mode)
1949 tc = clock()-t0
1949 tc = clock()-t0
1950 except SyntaxError:
1950 except SyntaxError:
1951 mode = 'exec'
1951 mode = 'exec'
1952 t0 = clock()
1952 t0 = clock()
1953 code = compile(expr,'<timed exec>',mode)
1953 code = compile(expr,'<timed exec>',mode)
1954 tc = clock()-t0
1954 tc = clock()-t0
1955 # skew measurement as little as possible
1955 # skew measurement as little as possible
1956 glob = self.shell.user_ns
1956 glob = self.shell.user_ns
1957 clk = clock2
1957 clk = clock2
1958 wtime = time.time
1958 wtime = time.time
1959 # time execution
1959 # time execution
1960 wall_st = wtime()
1960 wall_st = wtime()
1961 if mode=='eval':
1961 if mode=='eval':
1962 st = clk()
1962 st = clk()
1963 out = eval(code,glob)
1963 out = eval(code,glob)
1964 end = clk()
1964 end = clk()
1965 else:
1965 else:
1966 st = clk()
1966 st = clk()
1967 exec code in glob
1967 exec code in glob
1968 end = clk()
1968 end = clk()
1969 out = None
1969 out = None
1970 wall_end = wtime()
1970 wall_end = wtime()
1971 # Compute actual times and report
1971 # Compute actual times and report
1972 wall_time = wall_end-wall_st
1972 wall_time = wall_end-wall_st
1973 cpu_user = end[0]-st[0]
1973 cpu_user = end[0]-st[0]
1974 cpu_sys = end[1]-st[1]
1974 cpu_sys = end[1]-st[1]
1975 cpu_tot = cpu_user+cpu_sys
1975 cpu_tot = cpu_user+cpu_sys
1976 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1976 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1977 (cpu_user,cpu_sys,cpu_tot)
1977 (cpu_user,cpu_sys,cpu_tot)
1978 print "Wall time: %.2f s" % wall_time
1978 print "Wall time: %.2f s" % wall_time
1979 if tc > tc_min:
1979 if tc > tc_min:
1980 print "Compiler : %.2f s" % tc
1980 print "Compiler : %.2f s" % tc
1981 return out
1981 return out
1982
1982
1983 @testdec.skip_doctest
1983 @testdec.skip_doctest
1984 def magic_macro(self,parameter_s = ''):
1984 def magic_macro(self,parameter_s = ''):
1985 """Define a set of input lines as a macro for future re-execution.
1985 """Define a set of input lines as a macro for future re-execution.
1986
1986
1987 Usage:\\
1987 Usage:\\
1988 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1988 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1989
1989
1990 Options:
1990 Options:
1991
1991
1992 -r: use 'raw' input. By default, the 'processed' history is used,
1992 -r: use 'raw' input. By default, the 'processed' history is used,
1993 so that magics are loaded in their transformed version to valid
1993 so that magics are loaded in their transformed version to valid
1994 Python. If this option is given, the raw input as typed as the
1994 Python. If this option is given, the raw input as typed as the
1995 command line is used instead.
1995 command line is used instead.
1996
1996
1997 This will define a global variable called `name` which is a string
1997 This will define a global variable called `name` which is a string
1998 made of joining the slices and lines you specify (n1,n2,... numbers
1998 made of joining the slices and lines you specify (n1,n2,... numbers
1999 above) from your input history into a single string. This variable
1999 above) from your input history into a single string. This variable
2000 acts like an automatic function which re-executes those lines as if
2000 acts like an automatic function which re-executes those lines as if
2001 you had typed them. You just type 'name' at the prompt and the code
2001 you had typed them. You just type 'name' at the prompt and the code
2002 executes.
2002 executes.
2003
2003
2004 The notation for indicating number ranges is: n1-n2 means 'use line
2004 The notation for indicating number ranges is: n1-n2 means 'use line
2005 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2005 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2006 using the lines numbered 5,6 and 7.
2006 using the lines numbered 5,6 and 7.
2007
2007
2008 Note: as a 'hidden' feature, you can also use traditional python slice
2008 Note: as a 'hidden' feature, you can also use traditional python slice
2009 notation, where N:M means numbers N through M-1.
2009 notation, where N:M means numbers N through M-1.
2010
2010
2011 For example, if your history contains (%hist prints it):
2011 For example, if your history contains (%hist prints it):
2012
2012
2013 44: x=1
2013 44: x=1
2014 45: y=3
2014 45: y=3
2015 46: z=x+y
2015 46: z=x+y
2016 47: print x
2016 47: print x
2017 48: a=5
2017 48: a=5
2018 49: print 'x',x,'y',y
2018 49: print 'x',x,'y',y
2019
2019
2020 you can create a macro with lines 44 through 47 (included) and line 49
2020 you can create a macro with lines 44 through 47 (included) and line 49
2021 called my_macro with:
2021 called my_macro with:
2022
2022
2023 In [55]: %macro my_macro 44-47 49
2023 In [55]: %macro my_macro 44-47 49
2024
2024
2025 Now, typing `my_macro` (without quotes) will re-execute all this code
2025 Now, typing `my_macro` (without quotes) will re-execute all this code
2026 in one pass.
2026 in one pass.
2027
2027
2028 You don't need to give the line-numbers in order, and any given line
2028 You don't need to give the line-numbers in order, and any given line
2029 number can appear multiple times. You can assemble macros with any
2029 number can appear multiple times. You can assemble macros with any
2030 lines from your input history in any order.
2030 lines from your input history in any order.
2031
2031
2032 The macro is a simple object which holds its value in an attribute,
2032 The macro is a simple object which holds its value in an attribute,
2033 but IPython's display system checks for macros and executes them as
2033 but IPython's display system checks for macros and executes them as
2034 code instead of printing them when you type their name.
2034 code instead of printing them when you type their name.
2035
2035
2036 You can view a macro's contents by explicitly printing it with:
2036 You can view a macro's contents by explicitly printing it with:
2037
2037
2038 'print macro_name'.
2038 'print macro_name'.
2039
2039
2040 For one-off cases which DON'T contain magic function calls in them you
2040 For one-off cases which DON'T contain magic function calls in them you
2041 can obtain similar results by explicitly executing slices from your
2041 can obtain similar results by explicitly executing slices from your
2042 input history with:
2042 input history with:
2043
2043
2044 In [60]: exec In[44:48]+In[49]"""
2044 In [60]: exec In[44:48]+In[49]"""
2045
2045
2046 opts,args = self.parse_options(parameter_s,'r',mode='list')
2046 opts,args = self.parse_options(parameter_s,'r',mode='list')
2047 if not args:
2047 if not args:
2048 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2048 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2049 macs.sort()
2049 macs.sort()
2050 return macs
2050 return macs
2051 if len(args) == 1:
2051 if len(args) == 1:
2052 raise UsageError(
2052 raise UsageError(
2053 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2053 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2054 name,ranges = args[0], args[1:]
2054 name,ranges = args[0], args[1:]
2055
2055
2056 #print 'rng',ranges # dbg
2056 #print 'rng',ranges # dbg
2057 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2057 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2058 macro = Macro(lines)
2058 macro = Macro(lines)
2059 self.shell.user_ns.update({name:macro})
2059 self.shell.user_ns.update({name:macro})
2060 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2060 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2061 print 'Macro contents:'
2061 print 'Macro contents:'
2062 print macro,
2062 print macro,
2063
2063
2064 def magic_save(self,parameter_s = ''):
2064 def magic_save(self,parameter_s = ''):
2065 """Save a set of lines to a given filename.
2065 """Save a set of lines to a given filename.
2066
2066
2067 Usage:\\
2067 Usage:\\
2068 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2068 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2069
2069
2070 Options:
2070 Options:
2071
2071
2072 -r: use 'raw' input. By default, the 'processed' history is used,
2072 -r: use 'raw' input. By default, the 'processed' history is used,
2073 so that magics are loaded in their transformed version to valid
2073 so that magics are loaded in their transformed version to valid
2074 Python. If this option is given, the raw input as typed as the
2074 Python. If this option is given, the raw input as typed as the
2075 command line is used instead.
2075 command line is used instead.
2076
2076
2077 This function uses the same syntax as %macro for line extraction, but
2077 This function uses the same syntax as %macro for line extraction, but
2078 instead of creating a macro it saves the resulting string to the
2078 instead of creating a macro it saves the resulting string to the
2079 filename you specify.
2079 filename you specify.
2080
2080
2081 It adds a '.py' extension to the file if you don't do so yourself, and
2081 It adds a '.py' extension to the file if you don't do so yourself, and
2082 it asks for confirmation before overwriting existing files."""
2082 it asks for confirmation before overwriting existing files."""
2083
2083
2084 opts,args = self.parse_options(parameter_s,'r',mode='list')
2084 opts,args = self.parse_options(parameter_s,'r',mode='list')
2085 fname,ranges = args[0], args[1:]
2085 fname,ranges = args[0], args[1:]
2086 if not fname.endswith('.py'):
2086 if not fname.endswith('.py'):
2087 fname += '.py'
2087 fname += '.py'
2088 if os.path.isfile(fname):
2088 if os.path.isfile(fname):
2089 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2089 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2090 if ans.lower() not in ['y','yes']:
2090 if ans.lower() not in ['y','yes']:
2091 print 'Operation cancelled.'
2091 print 'Operation cancelled.'
2092 return
2092 return
2093 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2093 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2094 f = file(fname,'w')
2094 f = file(fname,'w')
2095 f.write(cmds)
2095 f.write(cmds)
2096 f.close()
2096 f.close()
2097 print 'The following commands were written to file `%s`:' % fname
2097 print 'The following commands were written to file `%s`:' % fname
2098 print cmds
2098 print cmds
2099
2099
2100 def _edit_macro(self,mname,macro):
2100 def _edit_macro(self,mname,macro):
2101 """open an editor with the macro data in a file"""
2101 """open an editor with the macro data in a file"""
2102 filename = self.shell.mktempfile(macro.value)
2102 filename = self.shell.mktempfile(macro.value)
2103 self.shell.hooks.editor(filename)
2103 self.shell.hooks.editor(filename)
2104
2104
2105 # and make a new macro object, to replace the old one
2105 # and make a new macro object, to replace the old one
2106 mfile = open(filename)
2106 mfile = open(filename)
2107 mvalue = mfile.read()
2107 mvalue = mfile.read()
2108 mfile.close()
2108 mfile.close()
2109 self.shell.user_ns[mname] = Macro(mvalue)
2109 self.shell.user_ns[mname] = Macro(mvalue)
2110
2110
2111 def magic_ed(self,parameter_s=''):
2111 def magic_ed(self,parameter_s=''):
2112 """Alias to %edit."""
2112 """Alias to %edit."""
2113 return self.magic_edit(parameter_s)
2113 return self.magic_edit(parameter_s)
2114
2114
2115 @testdec.skip_doctest
2115 @testdec.skip_doctest
2116 def magic_edit(self,parameter_s='',last_call=['','']):
2116 def magic_edit(self,parameter_s='',last_call=['','']):
2117 """Bring up an editor and execute the resulting code.
2117 """Bring up an editor and execute the resulting code.
2118
2118
2119 Usage:
2119 Usage:
2120 %edit [options] [args]
2120 %edit [options] [args]
2121
2121
2122 %edit runs IPython's editor hook. The default version of this hook is
2122 %edit runs IPython's editor hook. The default version of this hook is
2123 set to call the __IPYTHON__.rc.editor command. This is read from your
2123 set to call the __IPYTHON__.rc.editor command. This is read from your
2124 environment variable $EDITOR. If this isn't found, it will default to
2124 environment variable $EDITOR. If this isn't found, it will default to
2125 vi under Linux/Unix and to notepad under Windows. See the end of this
2125 vi under Linux/Unix and to notepad under Windows. See the end of this
2126 docstring for how to change the editor hook.
2126 docstring for how to change the editor hook.
2127
2127
2128 You can also set the value of this editor via the command line option
2128 You can also set the value of this editor via the command line option
2129 '-editor' or in your ipythonrc file. This is useful if you wish to use
2129 '-editor' or in your ipythonrc file. This is useful if you wish to use
2130 specifically for IPython an editor different from your typical default
2130 specifically for IPython an editor different from your typical default
2131 (and for Windows users who typically don't set environment variables).
2131 (and for Windows users who typically don't set environment variables).
2132
2132
2133 This command allows you to conveniently edit multi-line code right in
2133 This command allows you to conveniently edit multi-line code right in
2134 your IPython session.
2134 your IPython session.
2135
2135
2136 If called without arguments, %edit opens up an empty editor with a
2136 If called without arguments, %edit opens up an empty editor with a
2137 temporary file and will execute the contents of this file when you
2137 temporary file and will execute the contents of this file when you
2138 close it (don't forget to save it!).
2138 close it (don't forget to save it!).
2139
2139
2140
2140
2141 Options:
2141 Options:
2142
2142
2143 -n <number>: open the editor at a specified line number. By default,
2143 -n <number>: open the editor at a specified line number. By default,
2144 the IPython editor hook uses the unix syntax 'editor +N filename', but
2144 the IPython editor hook uses the unix syntax 'editor +N filename', but
2145 you can configure this by providing your own modified hook if your
2145 you can configure this by providing your own modified hook if your
2146 favorite editor supports line-number specifications with a different
2146 favorite editor supports line-number specifications with a different
2147 syntax.
2147 syntax.
2148
2148
2149 -p: this will call the editor with the same data as the previous time
2149 -p: this will call the editor with the same data as the previous time
2150 it was used, regardless of how long ago (in your current session) it
2150 it was used, regardless of how long ago (in your current session) it
2151 was.
2151 was.
2152
2152
2153 -r: use 'raw' input. This option only applies to input taken from the
2153 -r: use 'raw' input. This option only applies to input taken from the
2154 user's history. By default, the 'processed' history is used, so that
2154 user's history. By default, the 'processed' history is used, so that
2155 magics are loaded in their transformed version to valid Python. If
2155 magics are loaded in their transformed version to valid Python. If
2156 this option is given, the raw input as typed as the command line is
2156 this option is given, the raw input as typed as the command line is
2157 used instead. When you exit the editor, it will be executed by
2157 used instead. When you exit the editor, it will be executed by
2158 IPython's own processor.
2158 IPython's own processor.
2159
2159
2160 -x: do not execute the edited code immediately upon exit. This is
2160 -x: do not execute the edited code immediately upon exit. This is
2161 mainly useful if you are editing programs which need to be called with
2161 mainly useful if you are editing programs which need to be called with
2162 command line arguments, which you can then do using %run.
2162 command line arguments, which you can then do using %run.
2163
2163
2164
2164
2165 Arguments:
2165 Arguments:
2166
2166
2167 If arguments are given, the following possibilites exist:
2167 If arguments are given, the following possibilites exist:
2168
2168
2169 - The arguments are numbers or pairs of colon-separated numbers (like
2169 - The arguments are numbers or pairs of colon-separated numbers (like
2170 1 4:8 9). These are interpreted as lines of previous input to be
2170 1 4:8 9). These are interpreted as lines of previous input to be
2171 loaded into the editor. The syntax is the same of the %macro command.
2171 loaded into the editor. The syntax is the same of the %macro command.
2172
2172
2173 - If the argument doesn't start with a number, it is evaluated as a
2173 - If the argument doesn't start with a number, it is evaluated as a
2174 variable and its contents loaded into the editor. You can thus edit
2174 variable and its contents loaded into the editor. You can thus edit
2175 any string which contains python code (including the result of
2175 any string which contains python code (including the result of
2176 previous edits).
2176 previous edits).
2177
2177
2178 - If the argument is the name of an object (other than a string),
2178 - If the argument is the name of an object (other than a string),
2179 IPython will try to locate the file where it was defined and open the
2179 IPython will try to locate the file where it was defined and open the
2180 editor at the point where it is defined. You can use `%edit function`
2180 editor at the point where it is defined. You can use `%edit function`
2181 to load an editor exactly at the point where 'function' is defined,
2181 to load an editor exactly at the point where 'function' is defined,
2182 edit it and have the file be executed automatically.
2182 edit it and have the file be executed automatically.
2183
2183
2184 If the object is a macro (see %macro for details), this opens up your
2184 If the object is a macro (see %macro for details), this opens up your
2185 specified editor with a temporary file containing the macro's data.
2185 specified editor with a temporary file containing the macro's data.
2186 Upon exit, the macro is reloaded with the contents of the file.
2186 Upon exit, the macro is reloaded with the contents of the file.
2187
2187
2188 Note: opening at an exact line is only supported under Unix, and some
2188 Note: opening at an exact line is only supported under Unix, and some
2189 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2189 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2190 '+NUMBER' parameter necessary for this feature. Good editors like
2190 '+NUMBER' parameter necessary for this feature. Good editors like
2191 (X)Emacs, vi, jed, pico and joe all do.
2191 (X)Emacs, vi, jed, pico and joe all do.
2192
2192
2193 - If the argument is not found as a variable, IPython will look for a
2193 - If the argument is not found as a variable, IPython will look for a
2194 file with that name (adding .py if necessary) and load it into the
2194 file with that name (adding .py if necessary) and load it into the
2195 editor. It will execute its contents with execfile() when you exit,
2195 editor. It will execute its contents with execfile() when you exit,
2196 loading any code in the file into your interactive namespace.
2196 loading any code in the file into your interactive namespace.
2197
2197
2198 After executing your code, %edit will return as output the code you
2198 After executing your code, %edit will return as output the code you
2199 typed in the editor (except when it was an existing file). This way
2199 typed in the editor (except when it was an existing file). This way
2200 you can reload the code in further invocations of %edit as a variable,
2200 you can reload the code in further invocations of %edit as a variable,
2201 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2201 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2202 the output.
2202 the output.
2203
2203
2204 Note that %edit is also available through the alias %ed.
2204 Note that %edit is also available through the alias %ed.
2205
2205
2206 This is an example of creating a simple function inside the editor and
2206 This is an example of creating a simple function inside the editor and
2207 then modifying it. First, start up the editor:
2207 then modifying it. First, start up the editor:
2208
2208
2209 In [1]: ed
2209 In [1]: ed
2210 Editing... done. Executing edited code...
2210 Editing... done. Executing edited code...
2211 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2211 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2212
2212
2213 We can then call the function foo():
2213 We can then call the function foo():
2214
2214
2215 In [2]: foo()
2215 In [2]: foo()
2216 foo() was defined in an editing session
2216 foo() was defined in an editing session
2217
2217
2218 Now we edit foo. IPython automatically loads the editor with the
2218 Now we edit foo. IPython automatically loads the editor with the
2219 (temporary) file where foo() was previously defined:
2219 (temporary) file where foo() was previously defined:
2220
2220
2221 In [3]: ed foo
2221 In [3]: ed foo
2222 Editing... done. Executing edited code...
2222 Editing... done. Executing edited code...
2223
2223
2224 And if we call foo() again we get the modified version:
2224 And if we call foo() again we get the modified version:
2225
2225
2226 In [4]: foo()
2226 In [4]: foo()
2227 foo() has now been changed!
2227 foo() has now been changed!
2228
2228
2229 Here is an example of how to edit a code snippet successive
2229 Here is an example of how to edit a code snippet successive
2230 times. First we call the editor:
2230 times. First we call the editor:
2231
2231
2232 In [5]: ed
2232 In [5]: ed
2233 Editing... done. Executing edited code...
2233 Editing... done. Executing edited code...
2234 hello
2234 hello
2235 Out[5]: "print 'hello'n"
2235 Out[5]: "print 'hello'n"
2236
2236
2237 Now we call it again with the previous output (stored in _):
2237 Now we call it again with the previous output (stored in _):
2238
2238
2239 In [6]: ed _
2239 In [6]: ed _
2240 Editing... done. Executing edited code...
2240 Editing... done. Executing edited code...
2241 hello world
2241 hello world
2242 Out[6]: "print 'hello world'n"
2242 Out[6]: "print 'hello world'n"
2243
2243
2244 Now we call it with the output #8 (stored in _8, also as Out[8]):
2244 Now we call it with the output #8 (stored in _8, also as Out[8]):
2245
2245
2246 In [7]: ed _8
2246 In [7]: ed _8
2247 Editing... done. Executing edited code...
2247 Editing... done. Executing edited code...
2248 hello again
2248 hello again
2249 Out[7]: "print 'hello again'n"
2249 Out[7]: "print 'hello again'n"
2250
2250
2251
2251
2252 Changing the default editor hook:
2252 Changing the default editor hook:
2253
2253
2254 If you wish to write your own editor hook, you can put it in a
2254 If you wish to write your own editor hook, you can put it in a
2255 configuration file which you load at startup time. The default hook
2255 configuration file which you load at startup time. The default hook
2256 is defined in the IPython.core.hooks module, and you can use that as a
2256 is defined in the IPython.core.hooks module, and you can use that as a
2257 starting example for further modifications. That file also has
2257 starting example for further modifications. That file also has
2258 general instructions on how to set a new hook for use once you've
2258 general instructions on how to set a new hook for use once you've
2259 defined it."""
2259 defined it."""
2260
2260
2261 # FIXME: This function has become a convoluted mess. It needs a
2261 # FIXME: This function has become a convoluted mess. It needs a
2262 # ground-up rewrite with clean, simple logic.
2262 # ground-up rewrite with clean, simple logic.
2263
2263
2264 def make_filename(arg):
2264 def make_filename(arg):
2265 "Make a filename from the given args"
2265 "Make a filename from the given args"
2266 try:
2266 try:
2267 filename = get_py_filename(arg)
2267 filename = get_py_filename(arg)
2268 except IOError:
2268 except IOError:
2269 if args.endswith('.py'):
2269 if args.endswith('.py'):
2270 filename = arg
2270 filename = arg
2271 else:
2271 else:
2272 filename = None
2272 filename = None
2273 return filename
2273 return filename
2274
2274
2275 # custom exceptions
2275 # custom exceptions
2276 class DataIsObject(Exception): pass
2276 class DataIsObject(Exception): pass
2277
2277
2278 opts,args = self.parse_options(parameter_s,'prxn:')
2278 opts,args = self.parse_options(parameter_s,'prxn:')
2279 # Set a few locals from the options for convenience:
2279 # Set a few locals from the options for convenience:
2280 opts_p = opts.has_key('p')
2280 opts_p = opts.has_key('p')
2281 opts_r = opts.has_key('r')
2281 opts_r = opts.has_key('r')
2282
2282
2283 # Default line number value
2283 # Default line number value
2284 lineno = opts.get('n',None)
2284 lineno = opts.get('n',None)
2285
2285
2286 if opts_p:
2286 if opts_p:
2287 args = '_%s' % last_call[0]
2287 args = '_%s' % last_call[0]
2288 if not self.shell.user_ns.has_key(args):
2288 if not self.shell.user_ns.has_key(args):
2289 args = last_call[1]
2289 args = last_call[1]
2290
2290
2291 # use last_call to remember the state of the previous call, but don't
2291 # use last_call to remember the state of the previous call, but don't
2292 # let it be clobbered by successive '-p' calls.
2292 # let it be clobbered by successive '-p' calls.
2293 try:
2293 try:
2294 last_call[0] = self.shell.outputcache.prompt_count
2294 last_call[0] = self.shell.outputcache.prompt_count
2295 if not opts_p:
2295 if not opts_p:
2296 last_call[1] = parameter_s
2296 last_call[1] = parameter_s
2297 except:
2297 except:
2298 pass
2298 pass
2299
2299
2300 # by default this is done with temp files, except when the given
2300 # by default this is done with temp files, except when the given
2301 # arg is a filename
2301 # arg is a filename
2302 use_temp = 1
2302 use_temp = 1
2303
2303
2304 if re.match(r'\d',args):
2304 if re.match(r'\d',args):
2305 # Mode where user specifies ranges of lines, like in %macro.
2305 # Mode where user specifies ranges of lines, like in %macro.
2306 # This means that you can't edit files whose names begin with
2306 # This means that you can't edit files whose names begin with
2307 # numbers this way. Tough.
2307 # numbers this way. Tough.
2308 ranges = args.split()
2308 ranges = args.split()
2309 data = ''.join(self.extract_input_slices(ranges,opts_r))
2309 data = ''.join(self.extract_input_slices(ranges,opts_r))
2310 elif args.endswith('.py'):
2310 elif args.endswith('.py'):
2311 filename = make_filename(args)
2311 filename = make_filename(args)
2312 data = ''
2312 data = ''
2313 use_temp = 0
2313 use_temp = 0
2314 elif args:
2314 elif args:
2315 try:
2315 try:
2316 # Load the parameter given as a variable. If not a string,
2316 # Load the parameter given as a variable. If not a string,
2317 # process it as an object instead (below)
2317 # process it as an object instead (below)
2318
2318
2319 #print '*** args',args,'type',type(args) # dbg
2319 #print '*** args',args,'type',type(args) # dbg
2320 data = eval(args,self.shell.user_ns)
2320 data = eval(args,self.shell.user_ns)
2321 if not type(data) in StringTypes:
2321 if not type(data) in StringTypes:
2322 raise DataIsObject
2322 raise DataIsObject
2323
2323
2324 except (NameError,SyntaxError):
2324 except (NameError,SyntaxError):
2325 # given argument is not a variable, try as a filename
2325 # given argument is not a variable, try as a filename
2326 filename = make_filename(args)
2326 filename = make_filename(args)
2327 if filename is None:
2327 if filename is None:
2328 warn("Argument given (%s) can't be found as a variable "
2328 warn("Argument given (%s) can't be found as a variable "
2329 "or as a filename." % args)
2329 "or as a filename." % args)
2330 return
2330 return
2331
2331
2332 data = ''
2332 data = ''
2333 use_temp = 0
2333 use_temp = 0
2334 except DataIsObject:
2334 except DataIsObject:
2335
2335
2336 # macros have a special edit function
2336 # macros have a special edit function
2337 if isinstance(data,Macro):
2337 if isinstance(data,Macro):
2338 self._edit_macro(args,data)
2338 self._edit_macro(args,data)
2339 return
2339 return
2340
2340
2341 # For objects, try to edit the file where they are defined
2341 # For objects, try to edit the file where they are defined
2342 try:
2342 try:
2343 filename = inspect.getabsfile(data)
2343 filename = inspect.getabsfile(data)
2344 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2344 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2345 # class created by %edit? Try to find source
2345 # class created by %edit? Try to find source
2346 # by looking for method definitions instead, the
2346 # by looking for method definitions instead, the
2347 # __module__ in those classes is FakeModule.
2347 # __module__ in those classes is FakeModule.
2348 attrs = [getattr(data, aname) for aname in dir(data)]
2348 attrs = [getattr(data, aname) for aname in dir(data)]
2349 for attr in attrs:
2349 for attr in attrs:
2350 if not inspect.ismethod(attr):
2350 if not inspect.ismethod(attr):
2351 continue
2351 continue
2352 filename = inspect.getabsfile(attr)
2352 filename = inspect.getabsfile(attr)
2353 if filename and 'fakemodule' not in filename.lower():
2353 if filename and 'fakemodule' not in filename.lower():
2354 # change the attribute to be the edit target instead
2354 # change the attribute to be the edit target instead
2355 data = attr
2355 data = attr
2356 break
2356 break
2357
2357
2358 datafile = 1
2358 datafile = 1
2359 except TypeError:
2359 except TypeError:
2360 filename = make_filename(args)
2360 filename = make_filename(args)
2361 datafile = 1
2361 datafile = 1
2362 warn('Could not find file where `%s` is defined.\n'
2362 warn('Could not find file where `%s` is defined.\n'
2363 'Opening a file named `%s`' % (args,filename))
2363 'Opening a file named `%s`' % (args,filename))
2364 # Now, make sure we can actually read the source (if it was in
2364 # Now, make sure we can actually read the source (if it was in
2365 # a temp file it's gone by now).
2365 # a temp file it's gone by now).
2366 if datafile:
2366 if datafile:
2367 try:
2367 try:
2368 if lineno is None:
2368 if lineno is None:
2369 lineno = inspect.getsourcelines(data)[1]
2369 lineno = inspect.getsourcelines(data)[1]
2370 except IOError:
2370 except IOError:
2371 filename = make_filename(args)
2371 filename = make_filename(args)
2372 if filename is None:
2372 if filename is None:
2373 warn('The file `%s` where `%s` was defined cannot '
2373 warn('The file `%s` where `%s` was defined cannot '
2374 'be read.' % (filename,data))
2374 'be read.' % (filename,data))
2375 return
2375 return
2376 use_temp = 0
2376 use_temp = 0
2377 else:
2377 else:
2378 data = ''
2378 data = ''
2379
2379
2380 if use_temp:
2380 if use_temp:
2381 filename = self.shell.mktempfile(data)
2381 filename = self.shell.mktempfile(data)
2382 print 'IPython will make a temporary file named:',filename
2382 print 'IPython will make a temporary file named:',filename
2383
2383
2384 # do actual editing here
2384 # do actual editing here
2385 print 'Editing...',
2385 print 'Editing...',
2386 sys.stdout.flush()
2386 sys.stdout.flush()
2387 try:
2387 try:
2388 self.shell.hooks.editor(filename,lineno)
2388 self.shell.hooks.editor(filename,lineno)
2389 except ipapi.TryNext:
2389 except ipapi.TryNext:
2390 warn('Could not open editor')
2390 warn('Could not open editor')
2391 return
2391 return
2392
2392
2393 # XXX TODO: should this be generalized for all string vars?
2393 # XXX TODO: should this be generalized for all string vars?
2394 # For now, this is special-cased to blocks created by cpaste
2394 # For now, this is special-cased to blocks created by cpaste
2395 if args.strip() == 'pasted_block':
2395 if args.strip() == 'pasted_block':
2396 self.shell.user_ns['pasted_block'] = file_read(filename)
2396 self.shell.user_ns['pasted_block'] = file_read(filename)
2397
2397
2398 if opts.has_key('x'): # -x prevents actual execution
2398 if opts.has_key('x'): # -x prevents actual execution
2399 print
2399 print
2400 else:
2400 else:
2401 print 'done. Executing edited code...'
2401 print 'done. Executing edited code...'
2402 if opts_r:
2402 if opts_r:
2403 self.shell.runlines(file_read(filename))
2403 self.shell.runlines(file_read(filename))
2404 else:
2404 else:
2405 self.shell.safe_execfile(filename,self.shell.user_ns,
2405 self.shell.safe_execfile(filename,self.shell.user_ns,
2406 self.shell.user_ns)
2406 self.shell.user_ns)
2407
2407
2408
2408
2409 if use_temp:
2409 if use_temp:
2410 try:
2410 try:
2411 return open(filename).read()
2411 return open(filename).read()
2412 except IOError,msg:
2412 except IOError,msg:
2413 if msg.filename == filename:
2413 if msg.filename == filename:
2414 warn('File not found. Did you forget to save?')
2414 warn('File not found. Did you forget to save?')
2415 return
2415 return
2416 else:
2416 else:
2417 self.shell.showtraceback()
2417 self.shell.showtraceback()
2418
2418
2419 def magic_xmode(self,parameter_s = ''):
2419 def magic_xmode(self,parameter_s = ''):
2420 """Switch modes for the exception handlers.
2420 """Switch modes for the exception handlers.
2421
2421
2422 Valid modes: Plain, Context and Verbose.
2422 Valid modes: Plain, Context and Verbose.
2423
2423
2424 If called without arguments, acts as a toggle."""
2424 If called without arguments, acts as a toggle."""
2425
2425
2426 def xmode_switch_err(name):
2426 def xmode_switch_err(name):
2427 warn('Error changing %s exception modes.\n%s' %
2427 warn('Error changing %s exception modes.\n%s' %
2428 (name,sys.exc_info()[1]))
2428 (name,sys.exc_info()[1]))
2429
2429
2430 shell = self.shell
2430 shell = self.shell
2431 new_mode = parameter_s.strip().capitalize()
2431 new_mode = parameter_s.strip().capitalize()
2432 try:
2432 try:
2433 shell.InteractiveTB.set_mode(mode=new_mode)
2433 shell.InteractiveTB.set_mode(mode=new_mode)
2434 print 'Exception reporting mode:',shell.InteractiveTB.mode
2434 print 'Exception reporting mode:',shell.InteractiveTB.mode
2435 except:
2435 except:
2436 xmode_switch_err('user')
2436 xmode_switch_err('user')
2437
2437
2438 # threaded shells use a special handler in sys.excepthook
2438 # threaded shells use a special handler in sys.excepthook
2439 if shell.isthreaded:
2439 if shell.isthreaded:
2440 try:
2440 try:
2441 shell.sys_excepthook.set_mode(mode=new_mode)
2441 shell.sys_excepthook.set_mode(mode=new_mode)
2442 except:
2442 except:
2443 xmode_switch_err('threaded')
2443 xmode_switch_err('threaded')
2444
2444
2445 def magic_colors(self,parameter_s = ''):
2445 def magic_colors(self,parameter_s = ''):
2446 """Switch color scheme for prompts, info system and exception handlers.
2446 """Switch color scheme for prompts, info system and exception handlers.
2447
2447
2448 Currently implemented schemes: NoColor, Linux, LightBG.
2448 Currently implemented schemes: NoColor, Linux, LightBG.
2449
2449
2450 Color scheme names are not case-sensitive."""
2450 Color scheme names are not case-sensitive."""
2451
2451
2452 def color_switch_err(name):
2452 def color_switch_err(name):
2453 warn('Error changing %s color schemes.\n%s' %
2453 warn('Error changing %s color schemes.\n%s' %
2454 (name,sys.exc_info()[1]))
2454 (name,sys.exc_info()[1]))
2455
2455
2456
2456
2457 new_scheme = parameter_s.strip()
2457 new_scheme = parameter_s.strip()
2458 if not new_scheme:
2458 if not new_scheme:
2459 raise UsageError(
2459 raise UsageError(
2460 "%colors: you must specify a color scheme. See '%colors?'")
2460 "%colors: you must specify a color scheme. See '%colors?'")
2461 return
2461 return
2462 # local shortcut
2462 # local shortcut
2463 shell = self.shell
2463 shell = self.shell
2464
2464
2465 import IPython.utils.rlineimpl as readline
2465 import IPython.utils.rlineimpl as readline
2466
2466
2467 if not readline.have_readline and sys.platform == "win32":
2467 if not readline.have_readline and sys.platform == "win32":
2468 msg = """\
2468 msg = """\
2469 Proper color support under MS Windows requires the pyreadline library.
2469 Proper color support under MS Windows requires the pyreadline library.
2470 You can find it at:
2470 You can find it at:
2471 http://ipython.scipy.org/moin/PyReadline/Intro
2471 http://ipython.scipy.org/moin/PyReadline/Intro
2472 Gary's readline needs the ctypes module, from:
2472 Gary's readline needs the ctypes module, from:
2473 http://starship.python.net/crew/theller/ctypes
2473 http://starship.python.net/crew/theller/ctypes
2474 (Note that ctypes is already part of Python versions 2.5 and newer).
2474 (Note that ctypes is already part of Python versions 2.5 and newer).
2475
2475
2476 Defaulting color scheme to 'NoColor'"""
2476 Defaulting color scheme to 'NoColor'"""
2477 new_scheme = 'NoColor'
2477 new_scheme = 'NoColor'
2478 warn(msg)
2478 warn(msg)
2479
2479
2480 # readline option is 0
2480 # readline option is 0
2481 if not shell.has_readline:
2481 if not shell.has_readline:
2482 new_scheme = 'NoColor'
2482 new_scheme = 'NoColor'
2483
2483
2484 # Set prompt colors
2484 # Set prompt colors
2485 try:
2485 try:
2486 shell.outputcache.set_colors(new_scheme)
2486 shell.outputcache.set_colors(new_scheme)
2487 except:
2487 except:
2488 color_switch_err('prompt')
2488 color_switch_err('prompt')
2489 else:
2489 else:
2490 shell.rc.colors = \
2490 shell.rc.colors = \
2491 shell.outputcache.color_table.active_scheme_name
2491 shell.outputcache.color_table.active_scheme_name
2492 # Set exception colors
2492 # Set exception colors
2493 try:
2493 try:
2494 shell.InteractiveTB.set_colors(scheme = new_scheme)
2494 shell.InteractiveTB.set_colors(scheme = new_scheme)
2495 shell.SyntaxTB.set_colors(scheme = new_scheme)
2495 shell.SyntaxTB.set_colors(scheme = new_scheme)
2496 except:
2496 except:
2497 color_switch_err('exception')
2497 color_switch_err('exception')
2498
2498
2499 # threaded shells use a verbose traceback in sys.excepthook
2499 # threaded shells use a verbose traceback in sys.excepthook
2500 if shell.isthreaded:
2500 if shell.isthreaded:
2501 try:
2501 try:
2502 shell.sys_excepthook.set_colors(scheme=new_scheme)
2502 shell.sys_excepthook.set_colors(scheme=new_scheme)
2503 except:
2503 except:
2504 color_switch_err('system exception handler')
2504 color_switch_err('system exception handler')
2505
2505
2506 # Set info (for 'object?') colors
2506 # Set info (for 'object?') colors
2507 if shell.rc.color_info:
2507 if shell.rc.color_info:
2508 try:
2508 try:
2509 shell.inspector.set_active_scheme(new_scheme)
2509 shell.inspector.set_active_scheme(new_scheme)
2510 except:
2510 except:
2511 color_switch_err('object inspector')
2511 color_switch_err('object inspector')
2512 else:
2512 else:
2513 shell.inspector.set_active_scheme('NoColor')
2513 shell.inspector.set_active_scheme('NoColor')
2514
2514
2515 def magic_color_info(self,parameter_s = ''):
2515 def magic_color_info(self,parameter_s = ''):
2516 """Toggle color_info.
2516 """Toggle color_info.
2517
2517
2518 The color_info configuration parameter controls whether colors are
2518 The color_info configuration parameter controls whether colors are
2519 used for displaying object details (by things like %psource, %pfile or
2519 used for displaying object details (by things like %psource, %pfile or
2520 the '?' system). This function toggles this value with each call.
2520 the '?' system). This function toggles this value with each call.
2521
2521
2522 Note that unless you have a fairly recent pager (less works better
2522 Note that unless you have a fairly recent pager (less works better
2523 than more) in your system, using colored object information displays
2523 than more) in your system, using colored object information displays
2524 will not work properly. Test it and see."""
2524 will not work properly. Test it and see."""
2525
2525
2526 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2526 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2527 self.magic_colors(self.shell.rc.colors)
2527 self.magic_colors(self.shell.rc.colors)
2528 print 'Object introspection functions have now coloring:',
2528 print 'Object introspection functions have now coloring:',
2529 print ['OFF','ON'][self.shell.rc.color_info]
2529 print ['OFF','ON'][self.shell.rc.color_info]
2530
2530
2531 def magic_Pprint(self, parameter_s=''):
2531 def magic_Pprint(self, parameter_s=''):
2532 """Toggle pretty printing on/off."""
2532 """Toggle pretty printing on/off."""
2533
2533
2534 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2534 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2535 print 'Pretty printing has been turned', \
2535 print 'Pretty printing has been turned', \
2536 ['OFF','ON'][self.shell.rc.pprint]
2536 ['OFF','ON'][self.shell.rc.pprint]
2537
2537
2538 def magic_exit(self, parameter_s=''):
2538 def magic_exit(self, parameter_s=''):
2539 """Exit IPython, confirming if configured to do so.
2539 """Exit IPython, confirming if configured to do so.
2540
2540
2541 You can configure whether IPython asks for confirmation upon exit by
2541 You can configure whether IPython asks for confirmation upon exit by
2542 setting the confirm_exit flag in the ipythonrc file."""
2542 setting the confirm_exit flag in the ipythonrc file."""
2543
2543
2544 self.shell.exit()
2544 self.shell.exit()
2545
2545
2546 def magic_quit(self, parameter_s=''):
2546 def magic_quit(self, parameter_s=''):
2547 """Exit IPython, confirming if configured to do so (like %exit)"""
2547 """Exit IPython, confirming if configured to do so (like %exit)"""
2548
2548
2549 self.shell.exit()
2549 self.shell.exit()
2550
2550
2551 def magic_Exit(self, parameter_s=''):
2551 def magic_Exit(self, parameter_s=''):
2552 """Exit IPython without confirmation."""
2552 """Exit IPython without confirmation."""
2553
2553
2554 self.shell.ask_exit()
2554 self.shell.ask_exit()
2555
2555
2556 #......................................................................
2556 #......................................................................
2557 # Functions to implement unix shell-type things
2557 # Functions to implement unix shell-type things
2558
2558
2559 @testdec.skip_doctest
2559 @testdec.skip_doctest
2560 def magic_alias(self, parameter_s = ''):
2560 def magic_alias(self, parameter_s = ''):
2561 """Define an alias for a system command.
2561 """Define an alias for a system command.
2562
2562
2563 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2563 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2564
2564
2565 Then, typing 'alias_name params' will execute the system command 'cmd
2565 Then, typing 'alias_name params' will execute the system command 'cmd
2566 params' (from your underlying operating system).
2566 params' (from your underlying operating system).
2567
2567
2568 Aliases have lower precedence than magic functions and Python normal
2568 Aliases have lower precedence than magic functions and Python normal
2569 variables, so if 'foo' is both a Python variable and an alias, the
2569 variables, so if 'foo' is both a Python variable and an alias, the
2570 alias can not be executed until 'del foo' removes the Python variable.
2570 alias can not be executed until 'del foo' removes the Python variable.
2571
2571
2572 You can use the %l specifier in an alias definition to represent the
2572 You can use the %l specifier in an alias definition to represent the
2573 whole line when the alias is called. For example:
2573 whole line when the alias is called. For example:
2574
2574
2575 In [2]: alias all echo "Input in brackets: <%l>"
2575 In [2]: alias all echo "Input in brackets: <%l>"
2576 In [3]: all hello world
2576 In [3]: all hello world
2577 Input in brackets: <hello world>
2577 Input in brackets: <hello world>
2578
2578
2579 You can also define aliases with parameters using %s specifiers (one
2579 You can also define aliases with parameters using %s specifiers (one
2580 per parameter):
2580 per parameter):
2581
2581
2582 In [1]: alias parts echo first %s second %s
2582 In [1]: alias parts echo first %s second %s
2583 In [2]: %parts A B
2583 In [2]: %parts A B
2584 first A second B
2584 first A second B
2585 In [3]: %parts A
2585 In [3]: %parts A
2586 Incorrect number of arguments: 2 expected.
2586 Incorrect number of arguments: 2 expected.
2587 parts is an alias to: 'echo first %s second %s'
2587 parts is an alias to: 'echo first %s second %s'
2588
2588
2589 Note that %l and %s are mutually exclusive. You can only use one or
2589 Note that %l and %s are mutually exclusive. You can only use one or
2590 the other in your aliases.
2590 the other in your aliases.
2591
2591
2592 Aliases expand Python variables just like system calls using ! or !!
2592 Aliases expand Python variables just like system calls using ! or !!
2593 do: all expressions prefixed with '$' get expanded. For details of
2593 do: all expressions prefixed with '$' get expanded. For details of
2594 the semantic rules, see PEP-215:
2594 the semantic rules, see PEP-215:
2595 http://www.python.org/peps/pep-0215.html. This is the library used by
2595 http://www.python.org/peps/pep-0215.html. This is the library used by
2596 IPython for variable expansion. If you want to access a true shell
2596 IPython for variable expansion. If you want to access a true shell
2597 variable, an extra $ is necessary to prevent its expansion by IPython:
2597 variable, an extra $ is necessary to prevent its expansion by IPython:
2598
2598
2599 In [6]: alias show echo
2599 In [6]: alias show echo
2600 In [7]: PATH='A Python string'
2600 In [7]: PATH='A Python string'
2601 In [8]: show $PATH
2601 In [8]: show $PATH
2602 A Python string
2602 A Python string
2603 In [9]: show $$PATH
2603 In [9]: show $$PATH
2604 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2604 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2605
2605
2606 You can use the alias facility to acess all of $PATH. See the %rehash
2606 You can use the alias facility to acess all of $PATH. See the %rehash
2607 and %rehashx functions, which automatically create aliases for the
2607 and %rehashx functions, which automatically create aliases for the
2608 contents of your $PATH.
2608 contents of your $PATH.
2609
2609
2610 If called with no parameters, %alias prints the current alias table."""
2610 If called with no parameters, %alias prints the current alias table."""
2611
2611
2612 par = parameter_s.strip()
2612 par = parameter_s.strip()
2613 if not par:
2613 if not par:
2614 stored = self.db.get('stored_aliases', {} )
2614 stored = self.db.get('stored_aliases', {} )
2615 atab = self.shell.alias_table
2615 atab = self.shell.alias_table
2616 aliases = atab.keys()
2616 aliases = atab.keys()
2617 aliases.sort()
2617 aliases.sort()
2618 res = []
2618 res = []
2619 showlast = []
2619 showlast = []
2620 for alias in aliases:
2620 for alias in aliases:
2621 special = False
2621 special = False
2622 try:
2622 try:
2623 tgt = atab[alias][1]
2623 tgt = atab[alias][1]
2624 except (TypeError, AttributeError):
2624 except (TypeError, AttributeError):
2625 # unsubscriptable? probably a callable
2625 # unsubscriptable? probably a callable
2626 tgt = atab[alias]
2626 tgt = atab[alias]
2627 special = True
2627 special = True
2628 # 'interesting' aliases
2628 # 'interesting' aliases
2629 if (alias in stored or
2629 if (alias in stored or
2630 special or
2630 special or
2631 alias.lower() != os.path.splitext(tgt)[0].lower() or
2631 alias.lower() != os.path.splitext(tgt)[0].lower() or
2632 ' ' in tgt):
2632 ' ' in tgt):
2633 showlast.append((alias, tgt))
2633 showlast.append((alias, tgt))
2634 else:
2634 else:
2635 res.append((alias, tgt ))
2635 res.append((alias, tgt ))
2636
2636
2637 # show most interesting aliases last
2637 # show most interesting aliases last
2638 res.extend(showlast)
2638 res.extend(showlast)
2639 print "Total number of aliases:",len(aliases)
2639 print "Total number of aliases:",len(aliases)
2640 return res
2640 return res
2641 try:
2641 try:
2642 alias,cmd = par.split(None,1)
2642 alias,cmd = par.split(None,1)
2643 except:
2643 except:
2644 print oinspect.getdoc(self.magic_alias)
2644 print oinspect.getdoc(self.magic_alias)
2645 else:
2645 else:
2646 nargs = cmd.count('%s')
2646 nargs = cmd.count('%s')
2647 if nargs>0 and cmd.find('%l')>=0:
2647 if nargs>0 and cmd.find('%l')>=0:
2648 error('The %s and %l specifiers are mutually exclusive '
2648 error('The %s and %l specifiers are mutually exclusive '
2649 'in alias definitions.')
2649 'in alias definitions.')
2650 else: # all looks OK
2650 else: # all looks OK
2651 self.shell.alias_table[alias] = (nargs,cmd)
2651 self.shell.alias_table[alias] = (nargs,cmd)
2652 self.shell.alias_table_validate(verbose=0)
2652 self.shell.alias_table_validate(verbose=0)
2653 # end magic_alias
2653 # end magic_alias
2654
2654
2655 def magic_unalias(self, parameter_s = ''):
2655 def magic_unalias(self, parameter_s = ''):
2656 """Remove an alias"""
2656 """Remove an alias"""
2657
2657
2658 aname = parameter_s.strip()
2658 aname = parameter_s.strip()
2659 if aname in self.shell.alias_table:
2659 if aname in self.shell.alias_table:
2660 del self.shell.alias_table[aname]
2660 del self.shell.alias_table[aname]
2661 stored = self.db.get('stored_aliases', {} )
2661 stored = self.db.get('stored_aliases', {} )
2662 if aname in stored:
2662 if aname in stored:
2663 print "Removing %stored alias",aname
2663 print "Removing %stored alias",aname
2664 del stored[aname]
2664 del stored[aname]
2665 self.db['stored_aliases'] = stored
2665 self.db['stored_aliases'] = stored
2666
2666
2667
2667
2668 def magic_rehashx(self, parameter_s = ''):
2668 def magic_rehashx(self, parameter_s = ''):
2669 """Update the alias table with all executable files in $PATH.
2669 """Update the alias table with all executable files in $PATH.
2670
2670
2671 This version explicitly checks that every entry in $PATH is a file
2671 This version explicitly checks that every entry in $PATH is a file
2672 with execute access (os.X_OK), so it is much slower than %rehash.
2672 with execute access (os.X_OK), so it is much slower than %rehash.
2673
2673
2674 Under Windows, it checks executability as a match agains a
2674 Under Windows, it checks executability as a match agains a
2675 '|'-separated string of extensions, stored in the IPython config
2675 '|'-separated string of extensions, stored in the IPython config
2676 variable win_exec_ext. This defaults to 'exe|com|bat'.
2676 variable win_exec_ext. This defaults to 'exe|com|bat'.
2677
2677
2678 This function also resets the root module cache of module completer,
2678 This function also resets the root module cache of module completer,
2679 used on slow filesystems.
2679 used on slow filesystems.
2680 """
2680 """
2681
2681
2682
2682
2683 ip = self.api
2683 ip = self.api
2684
2684
2685 # for the benefit of module completer in ipy_completers.py
2685 # for the benefit of module completer in ipy_completers.py
2686 del ip.db['rootmodules']
2686 del ip.db['rootmodules']
2687
2687
2688 path = [os.path.abspath(os.path.expanduser(p)) for p in
2688 path = [os.path.abspath(os.path.expanduser(p)) for p in
2689 os.environ.get('PATH','').split(os.pathsep)]
2689 os.environ.get('PATH','').split(os.pathsep)]
2690 path = filter(os.path.isdir,path)
2690 path = filter(os.path.isdir,path)
2691
2691
2692 alias_table = self.shell.alias_table
2692 alias_table = self.shell.alias_table
2693 syscmdlist = []
2693 syscmdlist = []
2694 if os.name == 'posix':
2694 if os.name == 'posix':
2695 isexec = lambda fname:os.path.isfile(fname) and \
2695 isexec = lambda fname:os.path.isfile(fname) and \
2696 os.access(fname,os.X_OK)
2696 os.access(fname,os.X_OK)
2697 else:
2697 else:
2698
2698
2699 try:
2699 try:
2700 winext = os.environ['pathext'].replace(';','|').replace('.','')
2700 winext = os.environ['pathext'].replace(';','|').replace('.','')
2701 except KeyError:
2701 except KeyError:
2702 winext = 'exe|com|bat|py'
2702 winext = 'exe|com|bat|py'
2703 if 'py' not in winext:
2703 if 'py' not in winext:
2704 winext += '|py'
2704 winext += '|py'
2705 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2705 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2706 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2706 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2707 savedir = os.getcwd()
2707 savedir = os.getcwd()
2708 try:
2708 try:
2709 # write the whole loop for posix/Windows so we don't have an if in
2709 # write the whole loop for posix/Windows so we don't have an if in
2710 # the innermost part
2710 # the innermost part
2711 if os.name == 'posix':
2711 if os.name == 'posix':
2712 for pdir in path:
2712 for pdir in path:
2713 os.chdir(pdir)
2713 os.chdir(pdir)
2714 for ff in os.listdir(pdir):
2714 for ff in os.listdir(pdir):
2715 if isexec(ff) and ff not in self.shell.no_alias:
2715 if isexec(ff) and ff not in self.shell.no_alias:
2716 # each entry in the alias table must be (N,name),
2716 # each entry in the alias table must be (N,name),
2717 # where N is the number of positional arguments of the
2717 # where N is the number of positional arguments of the
2718 # alias.
2718 # alias.
2719 # Dots will be removed from alias names, since ipython
2719 # Dots will be removed from alias names, since ipython
2720 # assumes names with dots to be python code
2720 # assumes names with dots to be python code
2721 alias_table[ff.replace('.','')] = (0,ff)
2721 alias_table[ff.replace('.','')] = (0,ff)
2722 syscmdlist.append(ff)
2722 syscmdlist.append(ff)
2723 else:
2723 else:
2724 for pdir in path:
2724 for pdir in path:
2725 os.chdir(pdir)
2725 os.chdir(pdir)
2726 for ff in os.listdir(pdir):
2726 for ff in os.listdir(pdir):
2727 base, ext = os.path.splitext(ff)
2727 base, ext = os.path.splitext(ff)
2728 if isexec(ff) and base.lower() not in self.shell.no_alias:
2728 if isexec(ff) and base.lower() not in self.shell.no_alias:
2729 if ext.lower() == '.exe':
2729 if ext.lower() == '.exe':
2730 ff = base
2730 ff = base
2731 alias_table[base.lower().replace('.','')] = (0,ff)
2731 alias_table[base.lower().replace('.','')] = (0,ff)
2732 syscmdlist.append(ff)
2732 syscmdlist.append(ff)
2733 # Make sure the alias table doesn't contain keywords or builtins
2733 # Make sure the alias table doesn't contain keywords or builtins
2734 self.shell.alias_table_validate()
2734 self.shell.alias_table_validate()
2735 # Call again init_auto_alias() so we get 'rm -i' and other
2735 # Call again init_auto_alias() so we get 'rm -i' and other
2736 # modified aliases since %rehashx will probably clobber them
2736 # modified aliases since %rehashx will probably clobber them
2737
2737
2738 # no, we don't want them. if %rehashx clobbers them, good,
2738 # no, we don't want them. if %rehashx clobbers them, good,
2739 # we'll probably get better versions
2739 # we'll probably get better versions
2740 # self.shell.init_auto_alias()
2740 # self.shell.init_auto_alias()
2741 db = ip.db
2741 db = ip.db
2742 db['syscmdlist'] = syscmdlist
2742 db['syscmdlist'] = syscmdlist
2743 finally:
2743 finally:
2744 os.chdir(savedir)
2744 os.chdir(savedir)
2745
2745
2746 def magic_pwd(self, parameter_s = ''):
2746 def magic_pwd(self, parameter_s = ''):
2747 """Return the current working directory path."""
2747 """Return the current working directory path."""
2748 return os.getcwd()
2748 return os.getcwd()
2749
2749
2750 def magic_cd(self, parameter_s=''):
2750 def magic_cd(self, parameter_s=''):
2751 """Change the current working directory.
2751 """Change the current working directory.
2752
2752
2753 This command automatically maintains an internal list of directories
2753 This command automatically maintains an internal list of directories
2754 you visit during your IPython session, in the variable _dh. The
2754 you visit during your IPython session, in the variable _dh. The
2755 command %dhist shows this history nicely formatted. You can also
2755 command %dhist shows this history nicely formatted. You can also
2756 do 'cd -<tab>' to see directory history conveniently.
2756 do 'cd -<tab>' to see directory history conveniently.
2757
2757
2758 Usage:
2758 Usage:
2759
2759
2760 cd 'dir': changes to directory 'dir'.
2760 cd 'dir': changes to directory 'dir'.
2761
2761
2762 cd -: changes to the last visited directory.
2762 cd -: changes to the last visited directory.
2763
2763
2764 cd -<n>: changes to the n-th directory in the directory history.
2764 cd -<n>: changes to the n-th directory in the directory history.
2765
2765
2766 cd --foo: change to directory that matches 'foo' in history
2766 cd --foo: change to directory that matches 'foo' in history
2767
2767
2768 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2768 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2769 (note: cd <bookmark_name> is enough if there is no
2769 (note: cd <bookmark_name> is enough if there is no
2770 directory <bookmark_name>, but a bookmark with the name exists.)
2770 directory <bookmark_name>, but a bookmark with the name exists.)
2771 'cd -b <tab>' allows you to tab-complete bookmark names.
2771 'cd -b <tab>' allows you to tab-complete bookmark names.
2772
2772
2773 Options:
2773 Options:
2774
2774
2775 -q: quiet. Do not print the working directory after the cd command is
2775 -q: quiet. Do not print the working directory after the cd command is
2776 executed. By default IPython's cd command does print this directory,
2776 executed. By default IPython's cd command does print this directory,
2777 since the default prompts do not display path information.
2777 since the default prompts do not display path information.
2778
2778
2779 Note that !cd doesn't work for this purpose because the shell where
2779 Note that !cd doesn't work for this purpose because the shell where
2780 !command runs is immediately discarded after executing 'command'."""
2780 !command runs is immediately discarded after executing 'command'."""
2781
2781
2782 parameter_s = parameter_s.strip()
2782 parameter_s = parameter_s.strip()
2783 #bkms = self.shell.persist.get("bookmarks",{})
2783 #bkms = self.shell.persist.get("bookmarks",{})
2784
2784
2785 oldcwd = os.getcwd()
2785 oldcwd = os.getcwd()
2786 numcd = re.match(r'(-)(\d+)$',parameter_s)
2786 numcd = re.match(r'(-)(\d+)$',parameter_s)
2787 # jump in directory history by number
2787 # jump in directory history by number
2788 if numcd:
2788 if numcd:
2789 nn = int(numcd.group(2))
2789 nn = int(numcd.group(2))
2790 try:
2790 try:
2791 ps = self.shell.user_ns['_dh'][nn]
2791 ps = self.shell.user_ns['_dh'][nn]
2792 except IndexError:
2792 except IndexError:
2793 print 'The requested directory does not exist in history.'
2793 print 'The requested directory does not exist in history.'
2794 return
2794 return
2795 else:
2795 else:
2796 opts = {}
2796 opts = {}
2797 elif parameter_s.startswith('--'):
2797 elif parameter_s.startswith('--'):
2798 ps = None
2798 ps = None
2799 fallback = None
2799 fallback = None
2800 pat = parameter_s[2:]
2800 pat = parameter_s[2:]
2801 dh = self.shell.user_ns['_dh']
2801 dh = self.shell.user_ns['_dh']
2802 # first search only by basename (last component)
2802 # first search only by basename (last component)
2803 for ent in reversed(dh):
2803 for ent in reversed(dh):
2804 if pat in os.path.basename(ent) and os.path.isdir(ent):
2804 if pat in os.path.basename(ent) and os.path.isdir(ent):
2805 ps = ent
2805 ps = ent
2806 break
2806 break
2807
2807
2808 if fallback is None and pat in ent and os.path.isdir(ent):
2808 if fallback is None and pat in ent and os.path.isdir(ent):
2809 fallback = ent
2809 fallback = ent
2810
2810
2811 # if we have no last part match, pick the first full path match
2811 # if we have no last part match, pick the first full path match
2812 if ps is None:
2812 if ps is None:
2813 ps = fallback
2813 ps = fallback
2814
2814
2815 if ps is None:
2815 if ps is None:
2816 print "No matching entry in directory history"
2816 print "No matching entry in directory history"
2817 return
2817 return
2818 else:
2818 else:
2819 opts = {}
2819 opts = {}
2820
2820
2821
2821
2822 else:
2822 else:
2823 #turn all non-space-escaping backslashes to slashes,
2823 #turn all non-space-escaping backslashes to slashes,
2824 # for c:\windows\directory\names\
2824 # for c:\windows\directory\names\
2825 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2825 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2826 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2826 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2827 # jump to previous
2827 # jump to previous
2828 if ps == '-':
2828 if ps == '-':
2829 try:
2829 try:
2830 ps = self.shell.user_ns['_dh'][-2]
2830 ps = self.shell.user_ns['_dh'][-2]
2831 except IndexError:
2831 except IndexError:
2832 raise UsageError('%cd -: No previous directory to change to.')
2832 raise UsageError('%cd -: No previous directory to change to.')
2833 # jump to bookmark if needed
2833 # jump to bookmark if needed
2834 else:
2834 else:
2835 if not os.path.isdir(ps) or opts.has_key('b'):
2835 if not os.path.isdir(ps) or opts.has_key('b'):
2836 bkms = self.db.get('bookmarks', {})
2836 bkms = self.db.get('bookmarks', {})
2837
2837
2838 if bkms.has_key(ps):
2838 if bkms.has_key(ps):
2839 target = bkms[ps]
2839 target = bkms[ps]
2840 print '(bookmark:%s) -> %s' % (ps,target)
2840 print '(bookmark:%s) -> %s' % (ps,target)
2841 ps = target
2841 ps = target
2842 else:
2842 else:
2843 if opts.has_key('b'):
2843 if opts.has_key('b'):
2844 raise UsageError("Bookmark '%s' not found. "
2844 raise UsageError("Bookmark '%s' not found. "
2845 "Use '%%bookmark -l' to see your bookmarks." % ps)
2845 "Use '%%bookmark -l' to see your bookmarks." % ps)
2846
2846
2847 # at this point ps should point to the target dir
2847 # at this point ps should point to the target dir
2848 if ps:
2848 if ps:
2849 try:
2849 try:
2850 os.chdir(os.path.expanduser(ps))
2850 os.chdir(os.path.expanduser(ps))
2851 if self.shell.rc.term_title:
2851 if self.shell.rc.term_title:
2852 #print 'set term title:',self.shell.rc.term_title # dbg
2852 #print 'set term title:',self.shell.rc.term_title # dbg
2853 platutils.set_term_title('IPy ' + abbrev_cwd())
2853 platutils.set_term_title('IPy ' + abbrev_cwd())
2854 except OSError:
2854 except OSError:
2855 print sys.exc_info()[1]
2855 print sys.exc_info()[1]
2856 else:
2856 else:
2857 cwd = os.getcwd()
2857 cwd = os.getcwd()
2858 dhist = self.shell.user_ns['_dh']
2858 dhist = self.shell.user_ns['_dh']
2859 if oldcwd != cwd:
2859 if oldcwd != cwd:
2860 dhist.append(cwd)
2860 dhist.append(cwd)
2861 self.db['dhist'] = compress_dhist(dhist)[-100:]
2861 self.db['dhist'] = compress_dhist(dhist)[-100:]
2862
2862
2863 else:
2863 else:
2864 os.chdir(self.shell.home_dir)
2864 os.chdir(self.shell.home_dir)
2865 if self.shell.rc.term_title:
2865 if self.shell.rc.term_title:
2866 platutils.set_term_title("IPy ~")
2866 platutils.set_term_title("IPy ~")
2867 cwd = os.getcwd()
2867 cwd = os.getcwd()
2868 dhist = self.shell.user_ns['_dh']
2868 dhist = self.shell.user_ns['_dh']
2869
2869
2870 if oldcwd != cwd:
2870 if oldcwd != cwd:
2871 dhist.append(cwd)
2871 dhist.append(cwd)
2872 self.db['dhist'] = compress_dhist(dhist)[-100:]
2872 self.db['dhist'] = compress_dhist(dhist)[-100:]
2873 if not 'q' in opts and self.shell.user_ns['_dh']:
2873 if not 'q' in opts and self.shell.user_ns['_dh']:
2874 print self.shell.user_ns['_dh'][-1]
2874 print self.shell.user_ns['_dh'][-1]
2875
2875
2876
2876
2877 def magic_env(self, parameter_s=''):
2877 def magic_env(self, parameter_s=''):
2878 """List environment variables."""
2878 """List environment variables."""
2879
2879
2880 return os.environ.data
2880 return os.environ.data
2881
2881
2882 def magic_pushd(self, parameter_s=''):
2882 def magic_pushd(self, parameter_s=''):
2883 """Place the current dir on stack and change directory.
2883 """Place the current dir on stack and change directory.
2884
2884
2885 Usage:\\
2885 Usage:\\
2886 %pushd ['dirname']
2886 %pushd ['dirname']
2887 """
2887 """
2888
2888
2889 dir_s = self.shell.dir_stack
2889 dir_s = self.shell.dir_stack
2890 tgt = os.path.expanduser(parameter_s)
2890 tgt = os.path.expanduser(parameter_s)
2891 cwd = os.getcwd().replace(self.home_dir,'~')
2891 cwd = os.getcwd().replace(self.home_dir,'~')
2892 if tgt:
2892 if tgt:
2893 self.magic_cd(parameter_s)
2893 self.magic_cd(parameter_s)
2894 dir_s.insert(0,cwd)
2894 dir_s.insert(0,cwd)
2895 return self.magic_dirs()
2895 return self.magic_dirs()
2896
2896
2897 def magic_popd(self, parameter_s=''):
2897 def magic_popd(self, parameter_s=''):
2898 """Change to directory popped off the top of the stack.
2898 """Change to directory popped off the top of the stack.
2899 """
2899 """
2900 if not self.shell.dir_stack:
2900 if not self.shell.dir_stack:
2901 raise UsageError("%popd on empty stack")
2901 raise UsageError("%popd on empty stack")
2902 top = self.shell.dir_stack.pop(0)
2902 top = self.shell.dir_stack.pop(0)
2903 self.magic_cd(top)
2903 self.magic_cd(top)
2904 print "popd ->",top
2904 print "popd ->",top
2905
2905
2906 def magic_dirs(self, parameter_s=''):
2906 def magic_dirs(self, parameter_s=''):
2907 """Return the current directory stack."""
2907 """Return the current directory stack."""
2908
2908
2909 return self.shell.dir_stack
2909 return self.shell.dir_stack
2910
2910
2911 def magic_dhist(self, parameter_s=''):
2911 def magic_dhist(self, parameter_s=''):
2912 """Print your history of visited directories.
2912 """Print your history of visited directories.
2913
2913
2914 %dhist -> print full history\\
2914 %dhist -> print full history\\
2915 %dhist n -> print last n entries only\\
2915 %dhist n -> print last n entries only\\
2916 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2916 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2917
2917
2918 This history is automatically maintained by the %cd command, and
2918 This history is automatically maintained by the %cd command, and
2919 always available as the global list variable _dh. You can use %cd -<n>
2919 always available as the global list variable _dh. You can use %cd -<n>
2920 to go to directory number <n>.
2920 to go to directory number <n>.
2921
2921
2922 Note that most of time, you should view directory history by entering
2922 Note that most of time, you should view directory history by entering
2923 cd -<TAB>.
2923 cd -<TAB>.
2924
2924
2925 """
2925 """
2926
2926
2927 dh = self.shell.user_ns['_dh']
2927 dh = self.shell.user_ns['_dh']
2928 if parameter_s:
2928 if parameter_s:
2929 try:
2929 try:
2930 args = map(int,parameter_s.split())
2930 args = map(int,parameter_s.split())
2931 except:
2931 except:
2932 self.arg_err(Magic.magic_dhist)
2932 self.arg_err(Magic.magic_dhist)
2933 return
2933 return
2934 if len(args) == 1:
2934 if len(args) == 1:
2935 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2935 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2936 elif len(args) == 2:
2936 elif len(args) == 2:
2937 ini,fin = args
2937 ini,fin = args
2938 else:
2938 else:
2939 self.arg_err(Magic.magic_dhist)
2939 self.arg_err(Magic.magic_dhist)
2940 return
2940 return
2941 else:
2941 else:
2942 ini,fin = 0,len(dh)
2942 ini,fin = 0,len(dh)
2943 nlprint(dh,
2943 nlprint(dh,
2944 header = 'Directory history (kept in _dh)',
2944 header = 'Directory history (kept in _dh)',
2945 start=ini,stop=fin)
2945 start=ini,stop=fin)
2946
2946
2947 @testdec.skip_doctest
2947 @testdec.skip_doctest
2948 def magic_sc(self, parameter_s=''):
2948 def magic_sc(self, parameter_s=''):
2949 """Shell capture - execute a shell command and capture its output.
2949 """Shell capture - execute a shell command and capture its output.
2950
2950
2951 DEPRECATED. Suboptimal, retained for backwards compatibility.
2951 DEPRECATED. Suboptimal, retained for backwards compatibility.
2952
2952
2953 You should use the form 'var = !command' instead. Example:
2953 You should use the form 'var = !command' instead. Example:
2954
2954
2955 "%sc -l myfiles = ls ~" should now be written as
2955 "%sc -l myfiles = ls ~" should now be written as
2956
2956
2957 "myfiles = !ls ~"
2957 "myfiles = !ls ~"
2958
2958
2959 myfiles.s, myfiles.l and myfiles.n still apply as documented
2959 myfiles.s, myfiles.l and myfiles.n still apply as documented
2960 below.
2960 below.
2961
2961
2962 --
2962 --
2963 %sc [options] varname=command
2963 %sc [options] varname=command
2964
2964
2965 IPython will run the given command using commands.getoutput(), and
2965 IPython will run the given command using commands.getoutput(), and
2966 will then update the user's interactive namespace with a variable
2966 will then update the user's interactive namespace with a variable
2967 called varname, containing the value of the call. Your command can
2967 called varname, containing the value of the call. Your command can
2968 contain shell wildcards, pipes, etc.
2968 contain shell wildcards, pipes, etc.
2969
2969
2970 The '=' sign in the syntax is mandatory, and the variable name you
2970 The '=' sign in the syntax is mandatory, and the variable name you
2971 supply must follow Python's standard conventions for valid names.
2971 supply must follow Python's standard conventions for valid names.
2972
2972
2973 (A special format without variable name exists for internal use)
2973 (A special format without variable name exists for internal use)
2974
2974
2975 Options:
2975 Options:
2976
2976
2977 -l: list output. Split the output on newlines into a list before
2977 -l: list output. Split the output on newlines into a list before
2978 assigning it to the given variable. By default the output is stored
2978 assigning it to the given variable. By default the output is stored
2979 as a single string.
2979 as a single string.
2980
2980
2981 -v: verbose. Print the contents of the variable.
2981 -v: verbose. Print the contents of the variable.
2982
2982
2983 In most cases you should not need to split as a list, because the
2983 In most cases you should not need to split as a list, because the
2984 returned value is a special type of string which can automatically
2984 returned value is a special type of string which can automatically
2985 provide its contents either as a list (split on newlines) or as a
2985 provide its contents either as a list (split on newlines) or as a
2986 space-separated string. These are convenient, respectively, either
2986 space-separated string. These are convenient, respectively, either
2987 for sequential processing or to be passed to a shell command.
2987 for sequential processing or to be passed to a shell command.
2988
2988
2989 For example:
2989 For example:
2990
2990
2991 # all-random
2991 # all-random
2992
2992
2993 # Capture into variable a
2993 # Capture into variable a
2994 In [1]: sc a=ls *py
2994 In [1]: sc a=ls *py
2995
2995
2996 # a is a string with embedded newlines
2996 # a is a string with embedded newlines
2997 In [2]: a
2997 In [2]: a
2998 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2998 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2999
2999
3000 # which can be seen as a list:
3000 # which can be seen as a list:
3001 In [3]: a.l
3001 In [3]: a.l
3002 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3002 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3003
3003
3004 # or as a whitespace-separated string:
3004 # or as a whitespace-separated string:
3005 In [4]: a.s
3005 In [4]: a.s
3006 Out[4]: 'setup.py win32_manual_post_install.py'
3006 Out[4]: 'setup.py win32_manual_post_install.py'
3007
3007
3008 # a.s is useful to pass as a single command line:
3008 # a.s is useful to pass as a single command line:
3009 In [5]: !wc -l $a.s
3009 In [5]: !wc -l $a.s
3010 146 setup.py
3010 146 setup.py
3011 130 win32_manual_post_install.py
3011 130 win32_manual_post_install.py
3012 276 total
3012 276 total
3013
3013
3014 # while the list form is useful to loop over:
3014 # while the list form is useful to loop over:
3015 In [6]: for f in a.l:
3015 In [6]: for f in a.l:
3016 ...: !wc -l $f
3016 ...: !wc -l $f
3017 ...:
3017 ...:
3018 146 setup.py
3018 146 setup.py
3019 130 win32_manual_post_install.py
3019 130 win32_manual_post_install.py
3020
3020
3021 Similiarly, the lists returned by the -l option are also special, in
3021 Similiarly, the lists returned by the -l option are also special, in
3022 the sense that you can equally invoke the .s attribute on them to
3022 the sense that you can equally invoke the .s attribute on them to
3023 automatically get a whitespace-separated string from their contents:
3023 automatically get a whitespace-separated string from their contents:
3024
3024
3025 In [7]: sc -l b=ls *py
3025 In [7]: sc -l b=ls *py
3026
3026
3027 In [8]: b
3027 In [8]: b
3028 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3028 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3029
3029
3030 In [9]: b.s
3030 In [9]: b.s
3031 Out[9]: 'setup.py win32_manual_post_install.py'
3031 Out[9]: 'setup.py win32_manual_post_install.py'
3032
3032
3033 In summary, both the lists and strings used for ouptut capture have
3033 In summary, both the lists and strings used for ouptut capture have
3034 the following special attributes:
3034 the following special attributes:
3035
3035
3036 .l (or .list) : value as list.
3036 .l (or .list) : value as list.
3037 .n (or .nlstr): value as newline-separated string.
3037 .n (or .nlstr): value as newline-separated string.
3038 .s (or .spstr): value as space-separated string.
3038 .s (or .spstr): value as space-separated string.
3039 """
3039 """
3040
3040
3041 opts,args = self.parse_options(parameter_s,'lv')
3041 opts,args = self.parse_options(parameter_s,'lv')
3042 # Try to get a variable name and command to run
3042 # Try to get a variable name and command to run
3043 try:
3043 try:
3044 # the variable name must be obtained from the parse_options
3044 # the variable name must be obtained from the parse_options
3045 # output, which uses shlex.split to strip options out.
3045 # output, which uses shlex.split to strip options out.
3046 var,_ = args.split('=',1)
3046 var,_ = args.split('=',1)
3047 var = var.strip()
3047 var = var.strip()
3048 # But the the command has to be extracted from the original input
3048 # But the the command has to be extracted from the original input
3049 # parameter_s, not on what parse_options returns, to avoid the
3049 # parameter_s, not on what parse_options returns, to avoid the
3050 # quote stripping which shlex.split performs on it.
3050 # quote stripping which shlex.split performs on it.
3051 _,cmd = parameter_s.split('=',1)
3051 _,cmd = parameter_s.split('=',1)
3052 except ValueError:
3052 except ValueError:
3053 var,cmd = '',''
3053 var,cmd = '',''
3054 # If all looks ok, proceed
3054 # If all looks ok, proceed
3055 out,err = self.shell.getoutputerror(cmd)
3055 out,err = self.shell.getoutputerror(cmd)
3056 if err:
3056 if err:
3057 print >> Term.cerr,err
3057 print >> Term.cerr,err
3058 if opts.has_key('l'):
3058 if opts.has_key('l'):
3059 out = SList(out.split('\n'))
3059 out = SList(out.split('\n'))
3060 else:
3060 else:
3061 out = LSString(out)
3061 out = LSString(out)
3062 if opts.has_key('v'):
3062 if opts.has_key('v'):
3063 print '%s ==\n%s' % (var,pformat(out))
3063 print '%s ==\n%s' % (var,pformat(out))
3064 if var:
3064 if var:
3065 self.shell.user_ns.update({var:out})
3065 self.shell.user_ns.update({var:out})
3066 else:
3066 else:
3067 return out
3067 return out
3068
3068
3069 def magic_sx(self, parameter_s=''):
3069 def magic_sx(self, parameter_s=''):
3070 """Shell execute - run a shell command and capture its output.
3070 """Shell execute - run a shell command and capture its output.
3071
3071
3072 %sx command
3072 %sx command
3073
3073
3074 IPython will run the given command using commands.getoutput(), and
3074 IPython will run the given command using commands.getoutput(), and
3075 return the result formatted as a list (split on '\\n'). Since the
3075 return the result formatted as a list (split on '\\n'). Since the
3076 output is _returned_, it will be stored in ipython's regular output
3076 output is _returned_, it will be stored in ipython's regular output
3077 cache Out[N] and in the '_N' automatic variables.
3077 cache Out[N] and in the '_N' automatic variables.
3078
3078
3079 Notes:
3079 Notes:
3080
3080
3081 1) If an input line begins with '!!', then %sx is automatically
3081 1) If an input line begins with '!!', then %sx is automatically
3082 invoked. That is, while:
3082 invoked. That is, while:
3083 !ls
3083 !ls
3084 causes ipython to simply issue system('ls'), typing
3084 causes ipython to simply issue system('ls'), typing
3085 !!ls
3085 !!ls
3086 is a shorthand equivalent to:
3086 is a shorthand equivalent to:
3087 %sx ls
3087 %sx ls
3088
3088
3089 2) %sx differs from %sc in that %sx automatically splits into a list,
3089 2) %sx differs from %sc in that %sx automatically splits into a list,
3090 like '%sc -l'. The reason for this is to make it as easy as possible
3090 like '%sc -l'. The reason for this is to make it as easy as possible
3091 to process line-oriented shell output via further python commands.
3091 to process line-oriented shell output via further python commands.
3092 %sc is meant to provide much finer control, but requires more
3092 %sc is meant to provide much finer control, but requires more
3093 typing.
3093 typing.
3094
3094
3095 3) Just like %sc -l, this is a list with special attributes:
3095 3) Just like %sc -l, this is a list with special attributes:
3096
3096
3097 .l (or .list) : value as list.
3097 .l (or .list) : value as list.
3098 .n (or .nlstr): value as newline-separated string.
3098 .n (or .nlstr): value as newline-separated string.
3099 .s (or .spstr): value as whitespace-separated string.
3099 .s (or .spstr): value as whitespace-separated string.
3100
3100
3101 This is very useful when trying to use such lists as arguments to
3101 This is very useful when trying to use such lists as arguments to
3102 system commands."""
3102 system commands."""
3103
3103
3104 if parameter_s:
3104 if parameter_s:
3105 out,err = self.shell.getoutputerror(parameter_s)
3105 out,err = self.shell.getoutputerror(parameter_s)
3106 if err:
3106 if err:
3107 print >> Term.cerr,err
3107 print >> Term.cerr,err
3108 return SList(out.split('\n'))
3108 return SList(out.split('\n'))
3109
3109
3110 def magic_bg(self, parameter_s=''):
3110 def magic_bg(self, parameter_s=''):
3111 """Run a job in the background, in a separate thread.
3111 """Run a job in the background, in a separate thread.
3112
3112
3113 For example,
3113 For example,
3114
3114
3115 %bg myfunc(x,y,z=1)
3115 %bg myfunc(x,y,z=1)
3116
3116
3117 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3117 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3118 execution starts, a message will be printed indicating the job
3118 execution starts, a message will be printed indicating the job
3119 number. If your job number is 5, you can use
3119 number. If your job number is 5, you can use
3120
3120
3121 myvar = jobs.result(5) or myvar = jobs[5].result
3121 myvar = jobs.result(5) or myvar = jobs[5].result
3122
3122
3123 to assign this result to variable 'myvar'.
3123 to assign this result to variable 'myvar'.
3124
3124
3125 IPython has a job manager, accessible via the 'jobs' object. You can
3125 IPython has a job manager, accessible via the 'jobs' object. You can
3126 type jobs? to get more information about it, and use jobs.<TAB> to see
3126 type jobs? to get more information about it, and use jobs.<TAB> to see
3127 its attributes. All attributes not starting with an underscore are
3127 its attributes. All attributes not starting with an underscore are
3128 meant for public use.
3128 meant for public use.
3129
3129
3130 In particular, look at the jobs.new() method, which is used to create
3130 In particular, look at the jobs.new() method, which is used to create
3131 new jobs. This magic %bg function is just a convenience wrapper
3131 new jobs. This magic %bg function is just a convenience wrapper
3132 around jobs.new(), for expression-based jobs. If you want to create a
3132 around jobs.new(), for expression-based jobs. If you want to create a
3133 new job with an explicit function object and arguments, you must call
3133 new job with an explicit function object and arguments, you must call
3134 jobs.new() directly.
3134 jobs.new() directly.
3135
3135
3136 The jobs.new docstring also describes in detail several important
3136 The jobs.new docstring also describes in detail several important
3137 caveats associated with a thread-based model for background job
3137 caveats associated with a thread-based model for background job
3138 execution. Type jobs.new? for details.
3138 execution. Type jobs.new? for details.
3139
3139
3140 You can check the status of all jobs with jobs.status().
3140 You can check the status of all jobs with jobs.status().
3141
3141
3142 The jobs variable is set by IPython into the Python builtin namespace.
3142 The jobs variable is set by IPython into the Python builtin namespace.
3143 If you ever declare a variable named 'jobs', you will shadow this
3143 If you ever declare a variable named 'jobs', you will shadow this
3144 name. You can either delete your global jobs variable to regain
3144 name. You can either delete your global jobs variable to regain
3145 access to the job manager, or make a new name and assign it manually
3145 access to the job manager, or make a new name and assign it manually
3146 to the manager (stored in IPython's namespace). For example, to
3146 to the manager (stored in IPython's namespace). For example, to
3147 assign the job manager to the Jobs name, use:
3147 assign the job manager to the Jobs name, use:
3148
3148
3149 Jobs = __builtins__.jobs"""
3149 Jobs = __builtins__.jobs"""
3150
3150
3151 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3151 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3152
3152
3153 def magic_r(self, parameter_s=''):
3153 def magic_r(self, parameter_s=''):
3154 """Repeat previous input.
3154 """Repeat previous input.
3155
3155
3156 Note: Consider using the more powerfull %rep instead!
3156 Note: Consider using the more powerfull %rep instead!
3157
3157
3158 If given an argument, repeats the previous command which starts with
3158 If given an argument, repeats the previous command which starts with
3159 the same string, otherwise it just repeats the previous input.
3159 the same string, otherwise it just repeats the previous input.
3160
3160
3161 Shell escaped commands (with ! as first character) are not recognized
3161 Shell escaped commands (with ! as first character) are not recognized
3162 by this system, only pure python code and magic commands.
3162 by this system, only pure python code and magic commands.
3163 """
3163 """
3164
3164
3165 start = parameter_s.strip()
3165 start = parameter_s.strip()
3166 esc_magic = self.shell.ESC_MAGIC
3166 esc_magic = self.shell.ESC_MAGIC
3167 # Identify magic commands even if automagic is on (which means
3167 # Identify magic commands even if automagic is on (which means
3168 # the in-memory version is different from that typed by the user).
3168 # the in-memory version is different from that typed by the user).
3169 if self.shell.rc.automagic:
3169 if self.shell.rc.automagic:
3170 start_magic = esc_magic+start
3170 start_magic = esc_magic+start
3171 else:
3171 else:
3172 start_magic = start
3172 start_magic = start
3173 # Look through the input history in reverse
3173 # Look through the input history in reverse
3174 for n in range(len(self.shell.input_hist)-2,0,-1):
3174 for n in range(len(self.shell.input_hist)-2,0,-1):
3175 input = self.shell.input_hist[n]
3175 input = self.shell.input_hist[n]
3176 # skip plain 'r' lines so we don't recurse to infinity
3176 # skip plain 'r' lines so we don't recurse to infinity
3177 if input != '_ip.magic("r")\n' and \
3177 if input != '_ip.magic("r")\n' and \
3178 (input.startswith(start) or input.startswith(start_magic)):
3178 (input.startswith(start) or input.startswith(start_magic)):
3179 #print 'match',`input` # dbg
3179 #print 'match',`input` # dbg
3180 print 'Executing:',input,
3180 print 'Executing:',input,
3181 self.shell.runlines(input)
3181 self.shell.runlines(input)
3182 return
3182 return
3183 print 'No previous input matching `%s` found.' % start
3183 print 'No previous input matching `%s` found.' % start
3184
3184
3185
3185
3186 def magic_bookmark(self, parameter_s=''):
3186 def magic_bookmark(self, parameter_s=''):
3187 """Manage IPython's bookmark system.
3187 """Manage IPython's bookmark system.
3188
3188
3189 %bookmark <name> - set bookmark to current dir
3189 %bookmark <name> - set bookmark to current dir
3190 %bookmark <name> <dir> - set bookmark to <dir>
3190 %bookmark <name> <dir> - set bookmark to <dir>
3191 %bookmark -l - list all bookmarks
3191 %bookmark -l - list all bookmarks
3192 %bookmark -d <name> - remove bookmark
3192 %bookmark -d <name> - remove bookmark
3193 %bookmark -r - remove all bookmarks
3193 %bookmark -r - remove all bookmarks
3194
3194
3195 You can later on access a bookmarked folder with:
3195 You can later on access a bookmarked folder with:
3196 %cd -b <name>
3196 %cd -b <name>
3197 or simply '%cd <name>' if there is no directory called <name> AND
3197 or simply '%cd <name>' if there is no directory called <name> AND
3198 there is such a bookmark defined.
3198 there is such a bookmark defined.
3199
3199
3200 Your bookmarks persist through IPython sessions, but they are
3200 Your bookmarks persist through IPython sessions, but they are
3201 associated with each profile."""
3201 associated with each profile."""
3202
3202
3203 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3203 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3204 if len(args) > 2:
3204 if len(args) > 2:
3205 raise UsageError("%bookmark: too many arguments")
3205 raise UsageError("%bookmark: too many arguments")
3206
3206
3207 bkms = self.db.get('bookmarks',{})
3207 bkms = self.db.get('bookmarks',{})
3208
3208
3209 if opts.has_key('d'):
3209 if opts.has_key('d'):
3210 try:
3210 try:
3211 todel = args[0]
3211 todel = args[0]
3212 except IndexError:
3212 except IndexError:
3213 raise UsageError(
3213 raise UsageError(
3214 "%bookmark -d: must provide a bookmark to delete")
3214 "%bookmark -d: must provide a bookmark to delete")
3215 else:
3215 else:
3216 try:
3216 try:
3217 del bkms[todel]
3217 del bkms[todel]
3218 except KeyError:
3218 except KeyError:
3219 raise UsageError(
3219 raise UsageError(
3220 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3220 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3221
3221
3222 elif opts.has_key('r'):
3222 elif opts.has_key('r'):
3223 bkms = {}
3223 bkms = {}
3224 elif opts.has_key('l'):
3224 elif opts.has_key('l'):
3225 bks = bkms.keys()
3225 bks = bkms.keys()
3226 bks.sort()
3226 bks.sort()
3227 if bks:
3227 if bks:
3228 size = max(map(len,bks))
3228 size = max(map(len,bks))
3229 else:
3229 else:
3230 size = 0
3230 size = 0
3231 fmt = '%-'+str(size)+'s -> %s'
3231 fmt = '%-'+str(size)+'s -> %s'
3232 print 'Current bookmarks:'
3232 print 'Current bookmarks:'
3233 for bk in bks:
3233 for bk in bks:
3234 print fmt % (bk,bkms[bk])
3234 print fmt % (bk,bkms[bk])
3235 else:
3235 else:
3236 if not args:
3236 if not args:
3237 raise UsageError("%bookmark: You must specify the bookmark name")
3237 raise UsageError("%bookmark: You must specify the bookmark name")
3238 elif len(args)==1:
3238 elif len(args)==1:
3239 bkms[args[0]] = os.getcwd()
3239 bkms[args[0]] = os.getcwd()
3240 elif len(args)==2:
3240 elif len(args)==2:
3241 bkms[args[0]] = args[1]
3241 bkms[args[0]] = args[1]
3242 self.db['bookmarks'] = bkms
3242 self.db['bookmarks'] = bkms
3243
3243
3244 def magic_pycat(self, parameter_s=''):
3244 def magic_pycat(self, parameter_s=''):
3245 """Show a syntax-highlighted file through a pager.
3245 """Show a syntax-highlighted file through a pager.
3246
3246
3247 This magic is similar to the cat utility, but it will assume the file
3247 This magic is similar to the cat utility, but it will assume the file
3248 to be Python source and will show it with syntax highlighting. """
3248 to be Python source and will show it with syntax highlighting. """
3249
3249
3250 try:
3250 try:
3251 filename = get_py_filename(parameter_s)
3251 filename = get_py_filename(parameter_s)
3252 cont = file_read(filename)
3252 cont = file_read(filename)
3253 except IOError:
3253 except IOError:
3254 try:
3254 try:
3255 cont = eval(parameter_s,self.user_ns)
3255 cont = eval(parameter_s,self.user_ns)
3256 except NameError:
3256 except NameError:
3257 cont = None
3257 cont = None
3258 if cont is None:
3258 if cont is None:
3259 print "Error: no such file or variable"
3259 print "Error: no such file or variable"
3260 return
3260 return
3261
3261
3262 page(self.shell.pycolorize(cont),
3262 page(self.shell.pycolorize(cont),
3263 screen_lines=self.shell.rc.screen_length)
3263 screen_lines=self.shell.rc.screen_length)
3264
3264
3265 def magic_cpaste(self, parameter_s=''):
3265 def magic_cpaste(self, parameter_s=''):
3266 """Allows you to paste & execute a pre-formatted code block from clipboard.
3266 """Allows you to paste & execute a pre-formatted code block from clipboard.
3267
3267
3268 You must terminate the block with '--' (two minus-signs) alone on the
3268 You must terminate the block with '--' (two minus-signs) alone on the
3269 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3269 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3270 is the new sentinel for this operation)
3270 is the new sentinel for this operation)
3271
3271
3272 The block is dedented prior to execution to enable execution of method
3272 The block is dedented prior to execution to enable execution of method
3273 definitions. '>' and '+' characters at the beginning of a line are
3273 definitions. '>' and '+' characters at the beginning of a line are
3274 ignored, to allow pasting directly from e-mails, diff files and
3274 ignored, to allow pasting directly from e-mails, diff files and
3275 doctests (the '...' continuation prompt is also stripped). The
3275 doctests (the '...' continuation prompt is also stripped). The
3276 executed block is also assigned to variable named 'pasted_block' for
3276 executed block is also assigned to variable named 'pasted_block' for
3277 later editing with '%edit pasted_block'.
3277 later editing with '%edit pasted_block'.
3278
3278
3279 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3279 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3280 This assigns the pasted block to variable 'foo' as string, without
3280 This assigns the pasted block to variable 'foo' as string, without
3281 dedenting or executing it (preceding >>> and + is still stripped)
3281 dedenting or executing it (preceding >>> and + is still stripped)
3282
3282
3283 '%cpaste -r' re-executes the block previously entered by cpaste.
3283 '%cpaste -r' re-executes the block previously entered by cpaste.
3284
3284
3285 Do not be alarmed by garbled output on Windows (it's a readline bug).
3285 Do not be alarmed by garbled output on Windows (it's a readline bug).
3286 Just press enter and type -- (and press enter again) and the block
3286 Just press enter and type -- (and press enter again) and the block
3287 will be what was just pasted.
3287 will be what was just pasted.
3288
3288
3289 IPython statements (magics, shell escapes) are not supported (yet).
3289 IPython statements (magics, shell escapes) are not supported (yet).
3290 """
3290 """
3291 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3291 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3292 par = args.strip()
3292 par = args.strip()
3293 if opts.has_key('r'):
3293 if opts.has_key('r'):
3294 b = self.user_ns.get('pasted_block', None)
3294 b = self.user_ns.get('pasted_block', None)
3295 if b is None:
3295 if b is None:
3296 raise UsageError('No previous pasted block available')
3296 raise UsageError('No previous pasted block available')
3297 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3297 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3298 exec b in self.user_ns
3298 exec b in self.user_ns
3299 return
3299 return
3300
3300
3301 sentinel = opts.get('s','--')
3301 sentinel = opts.get('s','--')
3302
3302
3303 # Regular expressions that declare text we strip from the input:
3303 # Regular expressions that declare text we strip from the input:
3304 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3304 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3305 r'^\s*(\s?>)+', # Python input prompt
3305 r'^\s*(\s?>)+', # Python input prompt
3306 r'^\s*\.{3,}', # Continuation prompts
3306 r'^\s*\.{3,}', # Continuation prompts
3307 r'^\++',
3307 r'^\++',
3308 ]
3308 ]
3309
3309
3310 strip_from_start = map(re.compile,strip_re)
3310 strip_from_start = map(re.compile,strip_re)
3311
3311
3312 from IPython.core import iplib
3312 from IPython.core import iplib
3313 lines = []
3313 lines = []
3314 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3314 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3315 while 1:
3315 while 1:
3316 l = iplib.raw_input_original(':')
3316 l = iplib.raw_input_original(':')
3317 if l ==sentinel:
3317 if l ==sentinel:
3318 break
3318 break
3319
3319
3320 for pat in strip_from_start:
3320 for pat in strip_from_start:
3321 l = pat.sub('',l)
3321 l = pat.sub('',l)
3322 lines.append(l)
3322 lines.append(l)
3323
3323
3324 block = "\n".join(lines) + '\n'
3324 block = "\n".join(lines) + '\n'
3325 #print "block:\n",block
3325 #print "block:\n",block
3326 if not par:
3326 if not par:
3327 b = textwrap.dedent(block)
3327 b = textwrap.dedent(block)
3328 self.user_ns['pasted_block'] = b
3328 self.user_ns['pasted_block'] = b
3329 exec b in self.user_ns
3329 exec b in self.user_ns
3330 else:
3330 else:
3331 self.user_ns[par] = SList(block.splitlines())
3331 self.user_ns[par] = SList(block.splitlines())
3332 print "Block assigned to '%s'" % par
3332 print "Block assigned to '%s'" % par
3333
3333
3334 def magic_quickref(self,arg):
3334 def magic_quickref(self,arg):
3335 """ Show a quick reference sheet """
3335 """ Show a quick reference sheet """
3336 import IPython.core.usage
3336 import IPython.core.usage
3337 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3337 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3338
3338
3339 page(qr)
3339 page(qr)
3340
3340
3341 def magic_upgrade(self,arg):
3341 def magic_upgrade(self,arg):
3342 """ Upgrade your IPython installation
3342 """ Upgrade your IPython installation
3343
3343
3344 This will copy the config files that don't yet exist in your
3344 This will copy the config files that don't yet exist in your
3345 ipython dir from the system config dir. Use this after upgrading
3345 ipython dir from the system config dir. Use this after upgrading
3346 IPython if you don't wish to delete your .ipython dir.
3346 IPython if you don't wish to delete your .ipython dir.
3347
3347
3348 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3348 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3349 new users)
3349 new users)
3350
3350
3351 """
3351 """
3352 ip = self.getapi()
3352 ip = self.getapi()
3353 ipinstallation = path(IPython.__file__).dirname()
3353 ipinstallation = path(IPython.__file__).dirname()
3354 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'utils' / 'upgradedir.py')
3354 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'utils' / 'upgradedir.py')
3355 src_config = ipinstallation / 'UserConfig'
3355 src_config = ipinstallation / 'UserConfig'
3356 userdir = path(ip.options.ipythondir)
3356 userdir = path(ip.options.ipythondir)
3357 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3357 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3358 print ">",cmd
3358 print ">",cmd
3359 shell(cmd)
3359 shell(cmd)
3360 if arg == '-nolegacy':
3360 if arg == '-nolegacy':
3361 legacy = userdir.files('ipythonrc*')
3361 legacy = userdir.files('ipythonrc*')
3362 print "Nuking legacy files:",legacy
3362 print "Nuking legacy files:",legacy
3363
3363
3364 [p.remove() for p in legacy]
3364 [p.remove() for p in legacy]
3365 suffix = (sys.platform == 'win32' and '.ini' or '')
3365 suffix = (sys.platform == 'win32' and '.ini' or '')
3366 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3366 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3367
3367
3368
3368
3369 def magic_doctest_mode(self,parameter_s=''):
3369 def magic_doctest_mode(self,parameter_s=''):
3370 """Toggle doctest mode on and off.
3370 """Toggle doctest mode on and off.
3371
3371
3372 This mode allows you to toggle the prompt behavior between normal
3372 This mode allows you to toggle the prompt behavior between normal
3373 IPython prompts and ones that are as similar to the default IPython
3373 IPython prompts and ones that are as similar to the default IPython
3374 interpreter as possible.
3374 interpreter as possible.
3375
3375
3376 It also supports the pasting of code snippets that have leading '>>>'
3376 It also supports the pasting of code snippets that have leading '>>>'
3377 and '...' prompts in them. This means that you can paste doctests from
3377 and '...' prompts in them. This means that you can paste doctests from
3378 files or docstrings (even if they have leading whitespace), and the
3378 files or docstrings (even if they have leading whitespace), and the
3379 code will execute correctly. You can then use '%history -tn' to see
3379 code will execute correctly. You can then use '%history -tn' to see
3380 the translated history without line numbers; this will give you the
3380 the translated history without line numbers; this will give you the
3381 input after removal of all the leading prompts and whitespace, which
3381 input after removal of all the leading prompts and whitespace, which
3382 can be pasted back into an editor.
3382 can be pasted back into an editor.
3383
3383
3384 With these features, you can switch into this mode easily whenever you
3384 With these features, you can switch into this mode easily whenever you
3385 need to do testing and changes to doctests, without having to leave
3385 need to do testing and changes to doctests, without having to leave
3386 your existing IPython session.
3386 your existing IPython session.
3387 """
3387 """
3388
3388
3389 # XXX - Fix this to have cleaner activate/deactivate calls.
3389 # XXX - Fix this to have cleaner activate/deactivate calls.
3390 from IPython.Extensions import InterpreterPasteInput as ipaste
3390 from IPython.Extensions import InterpreterPasteInput as ipaste
3391 from IPython.utils.ipstruct import Struct
3391 from IPython.utils.ipstruct import Struct
3392
3392
3393 # Shorthands
3393 # Shorthands
3394 shell = self.shell
3394 shell = self.shell
3395 oc = shell.outputcache
3395 oc = shell.outputcache
3396 rc = shell.rc
3396 rc = shell.rc
3397 meta = shell.meta
3397 meta = shell.meta
3398 # dstore is a data store kept in the instance metadata bag to track any
3398 # dstore is a data store kept in the instance metadata bag to track any
3399 # changes we make, so we can undo them later.
3399 # changes we make, so we can undo them later.
3400 dstore = meta.setdefault('doctest_mode',Struct())
3400 dstore = meta.setdefault('doctest_mode',Struct())
3401 save_dstore = dstore.setdefault
3401 save_dstore = dstore.setdefault
3402
3402
3403 # save a few values we'll need to recover later
3403 # save a few values we'll need to recover later
3404 mode = save_dstore('mode',False)
3404 mode = save_dstore('mode',False)
3405 save_dstore('rc_pprint',rc.pprint)
3405 save_dstore('rc_pprint',rc.pprint)
3406 save_dstore('xmode',shell.InteractiveTB.mode)
3406 save_dstore('xmode',shell.InteractiveTB.mode)
3407 save_dstore('rc_separate_out',rc.separate_out)
3407 save_dstore('rc_separate_out',rc.separate_out)
3408 save_dstore('rc_separate_out2',rc.separate_out2)
3408 save_dstore('rc_separate_out2',rc.separate_out2)
3409 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3409 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3410 save_dstore('rc_separate_in',rc.separate_in)
3410 save_dstore('rc_separate_in',rc.separate_in)
3411
3411
3412 if mode == False:
3412 if mode == False:
3413 # turn on
3413 # turn on
3414 ipaste.activate_prefilter()
3414 ipaste.activate_prefilter()
3415
3415
3416 oc.prompt1.p_template = '>>> '
3416 oc.prompt1.p_template = '>>> '
3417 oc.prompt2.p_template = '... '
3417 oc.prompt2.p_template = '... '
3418 oc.prompt_out.p_template = ''
3418 oc.prompt_out.p_template = ''
3419
3419
3420 # Prompt separators like plain python
3420 # Prompt separators like plain python
3421 oc.input_sep = oc.prompt1.sep = ''
3421 oc.input_sep = oc.prompt1.sep = ''
3422 oc.output_sep = ''
3422 oc.output_sep = ''
3423 oc.output_sep2 = ''
3423 oc.output_sep2 = ''
3424
3424
3425 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3425 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3426 oc.prompt_out.pad_left = False
3426 oc.prompt_out.pad_left = False
3427
3427
3428 rc.pprint = False
3428 rc.pprint = False
3429
3429
3430 shell.magic_xmode('Plain')
3430 shell.magic_xmode('Plain')
3431
3431
3432 else:
3432 else:
3433 # turn off
3433 # turn off
3434 ipaste.deactivate_prefilter()
3434 ipaste.deactivate_prefilter()
3435
3435
3436 oc.prompt1.p_template = rc.prompt_in1
3436 oc.prompt1.p_template = rc.prompt_in1
3437 oc.prompt2.p_template = rc.prompt_in2
3437 oc.prompt2.p_template = rc.prompt_in2
3438 oc.prompt_out.p_template = rc.prompt_out
3438 oc.prompt_out.p_template = rc.prompt_out
3439
3439
3440 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3440 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3441
3441
3442 oc.output_sep = dstore.rc_separate_out
3442 oc.output_sep = dstore.rc_separate_out
3443 oc.output_sep2 = dstore.rc_separate_out2
3443 oc.output_sep2 = dstore.rc_separate_out2
3444
3444
3445 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3445 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3446 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3446 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3447
3447
3448 rc.pprint = dstore.rc_pprint
3448 rc.pprint = dstore.rc_pprint
3449
3449
3450 shell.magic_xmode(dstore.xmode)
3450 shell.magic_xmode(dstore.xmode)
3451
3451
3452 # Store new mode and inform
3452 # Store new mode and inform
3453 dstore.mode = bool(1-int(mode))
3453 dstore.mode = bool(1-int(mode))
3454 print 'Doctest mode is:',
3454 print 'Doctest mode is:',
3455 print ['OFF','ON'][dstore.mode]
3455 print ['OFF','ON'][dstore.mode]
3456
3456
3457 # end Magic
3457 # end Magic
@@ -1,607 +1,607 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Tools for inspecting Python objects.
2 """Tools for inspecting Python objects.
3
3
4 Uses syntax highlighting for presenting the various information elements.
4 Uses syntax highlighting for presenting the various information elements.
5
5
6 Similar in spirit to the inspect module, but all calls take a name argument to
6 Similar in spirit to the inspect module, but all calls take a name argument to
7 reference the name under which an object is being read.
7 reference the name under which an object is being read.
8 """
8 """
9
9
10 #*****************************************************************************
10 #*****************************************************************************
11 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
11 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
12 #
12 #
13 # Distributed under the terms of the BSD License. The full license is in
13 # Distributed under the terms of the BSD License. The full license is in
14 # the file COPYING, distributed as part of this software.
14 # the file COPYING, distributed as part of this software.
15 #*****************************************************************************
15 #*****************************************************************************
16
16
17 __all__ = ['Inspector','InspectColors']
17 __all__ = ['Inspector','InspectColors']
18
18
19 # stdlib modules
19 # stdlib modules
20 import __builtin__
20 import __builtin__
21 import StringIO
21 import StringIO
22 import inspect
22 import inspect
23 import linecache
23 import linecache
24 import os
24 import os
25 import string
25 import string
26 import sys
26 import sys
27 import types
27 import types
28
28
29 # IPython's own
29 # IPython's own
30 from IPython.utils import PyColorize
30 from IPython.utils import PyColorize
31 from IPython.utils.genutils import page,indent,Term
31 from IPython.utils.genutils import page,indent,Term
32 from IPython.external.Itpl import itpl
32 from IPython.external.Itpl import itpl
33 from IPython.wildcard import list_namespace
33 from IPython.utils.wildcard import list_namespace
34 from IPython.utils.coloransi import *
34 from IPython.utils.coloransi import *
35
35
36 #****************************************************************************
36 #****************************************************************************
37 # HACK!!! This is a crude fix for bugs in python 2.3's inspect module. We
37 # HACK!!! This is a crude fix for bugs in python 2.3's inspect module. We
38 # simply monkeypatch inspect with code copied from python 2.4.
38 # simply monkeypatch inspect with code copied from python 2.4.
39 if sys.version_info[:2] == (2,3):
39 if sys.version_info[:2] == (2,3):
40 from inspect import ismodule, getabsfile, modulesbyfile
40 from inspect import ismodule, getabsfile, modulesbyfile
41 def getmodule(object):
41 def getmodule(object):
42 """Return the module an object was defined in, or None if not found."""
42 """Return the module an object was defined in, or None if not found."""
43 if ismodule(object):
43 if ismodule(object):
44 return object
44 return object
45 if hasattr(object, '__module__'):
45 if hasattr(object, '__module__'):
46 return sys.modules.get(object.__module__)
46 return sys.modules.get(object.__module__)
47 try:
47 try:
48 file = getabsfile(object)
48 file = getabsfile(object)
49 except TypeError:
49 except TypeError:
50 return None
50 return None
51 if file in modulesbyfile:
51 if file in modulesbyfile:
52 return sys.modules.get(modulesbyfile[file])
52 return sys.modules.get(modulesbyfile[file])
53 for module in sys.modules.values():
53 for module in sys.modules.values():
54 if hasattr(module, '__file__'):
54 if hasattr(module, '__file__'):
55 modulesbyfile[
55 modulesbyfile[
56 os.path.realpath(
56 os.path.realpath(
57 getabsfile(module))] = module.__name__
57 getabsfile(module))] = module.__name__
58 if file in modulesbyfile:
58 if file in modulesbyfile:
59 return sys.modules.get(modulesbyfile[file])
59 return sys.modules.get(modulesbyfile[file])
60 main = sys.modules['__main__']
60 main = sys.modules['__main__']
61 if not hasattr(object, '__name__'):
61 if not hasattr(object, '__name__'):
62 return None
62 return None
63 if hasattr(main, object.__name__):
63 if hasattr(main, object.__name__):
64 mainobject = getattr(main, object.__name__)
64 mainobject = getattr(main, object.__name__)
65 if mainobject is object:
65 if mainobject is object:
66 return main
66 return main
67 builtin = sys.modules['__builtin__']
67 builtin = sys.modules['__builtin__']
68 if hasattr(builtin, object.__name__):
68 if hasattr(builtin, object.__name__):
69 builtinobject = getattr(builtin, object.__name__)
69 builtinobject = getattr(builtin, object.__name__)
70 if builtinobject is object:
70 if builtinobject is object:
71 return builtin
71 return builtin
72
72
73 inspect.getmodule = getmodule
73 inspect.getmodule = getmodule
74
74
75 #****************************************************************************
75 #****************************************************************************
76 # Builtin color schemes
76 # Builtin color schemes
77
77
78 Colors = TermColors # just a shorthand
78 Colors = TermColors # just a shorthand
79
79
80 # Build a few color schemes
80 # Build a few color schemes
81 NoColor = ColorScheme(
81 NoColor = ColorScheme(
82 'NoColor',{
82 'NoColor',{
83 'header' : Colors.NoColor,
83 'header' : Colors.NoColor,
84 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
84 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
85 } )
85 } )
86
86
87 LinuxColors = ColorScheme(
87 LinuxColors = ColorScheme(
88 'Linux',{
88 'Linux',{
89 'header' : Colors.LightRed,
89 'header' : Colors.LightRed,
90 'normal' : Colors.Normal # color off (usu. Colors.Normal)
90 'normal' : Colors.Normal # color off (usu. Colors.Normal)
91 } )
91 } )
92
92
93 LightBGColors = ColorScheme(
93 LightBGColors = ColorScheme(
94 'LightBG',{
94 'LightBG',{
95 'header' : Colors.Red,
95 'header' : Colors.Red,
96 'normal' : Colors.Normal # color off (usu. Colors.Normal)
96 'normal' : Colors.Normal # color off (usu. Colors.Normal)
97 } )
97 } )
98
98
99 # Build table of color schemes (needed by the parser)
99 # Build table of color schemes (needed by the parser)
100 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
100 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
101 'Linux')
101 'Linux')
102
102
103 #****************************************************************************
103 #****************************************************************************
104 # Auxiliary functions
104 # Auxiliary functions
105 def getdoc(obj):
105 def getdoc(obj):
106 """Stable wrapper around inspect.getdoc.
106 """Stable wrapper around inspect.getdoc.
107
107
108 This can't crash because of attribute problems.
108 This can't crash because of attribute problems.
109
109
110 It also attempts to call a getdoc() method on the given object. This
110 It also attempts to call a getdoc() method on the given object. This
111 allows objects which provide their docstrings via non-standard mechanisms
111 allows objects which provide their docstrings via non-standard mechanisms
112 (like Pyro proxies) to still be inspected by ipython's ? system."""
112 (like Pyro proxies) to still be inspected by ipython's ? system."""
113
113
114 ds = None # default return value
114 ds = None # default return value
115 try:
115 try:
116 ds = inspect.getdoc(obj)
116 ds = inspect.getdoc(obj)
117 except:
117 except:
118 # Harden against an inspect failure, which can occur with
118 # Harden against an inspect failure, which can occur with
119 # SWIG-wrapped extensions.
119 # SWIG-wrapped extensions.
120 pass
120 pass
121 # Allow objects to offer customized documentation via a getdoc method:
121 # Allow objects to offer customized documentation via a getdoc method:
122 try:
122 try:
123 ds2 = obj.getdoc()
123 ds2 = obj.getdoc()
124 except:
124 except:
125 pass
125 pass
126 else:
126 else:
127 # if we get extra info, we add it to the normal docstring.
127 # if we get extra info, we add it to the normal docstring.
128 if ds is None:
128 if ds is None:
129 ds = ds2
129 ds = ds2
130 else:
130 else:
131 ds = '%s\n%s' % (ds,ds2)
131 ds = '%s\n%s' % (ds,ds2)
132 return ds
132 return ds
133
133
134
134
135 def getsource(obj,is_binary=False):
135 def getsource(obj,is_binary=False):
136 """Wrapper around inspect.getsource.
136 """Wrapper around inspect.getsource.
137
137
138 This can be modified by other projects to provide customized source
138 This can be modified by other projects to provide customized source
139 extraction.
139 extraction.
140
140
141 Inputs:
141 Inputs:
142
142
143 - obj: an object whose source code we will attempt to extract.
143 - obj: an object whose source code we will attempt to extract.
144
144
145 Optional inputs:
145 Optional inputs:
146
146
147 - is_binary: whether the object is known to come from a binary source.
147 - is_binary: whether the object is known to come from a binary source.
148 This implementation will skip returning any output for binary objects, but
148 This implementation will skip returning any output for binary objects, but
149 custom extractors may know how to meaningfully process them."""
149 custom extractors may know how to meaningfully process them."""
150
150
151 if is_binary:
151 if is_binary:
152 return None
152 return None
153 else:
153 else:
154 try:
154 try:
155 src = inspect.getsource(obj)
155 src = inspect.getsource(obj)
156 except TypeError:
156 except TypeError:
157 if hasattr(obj,'__class__'):
157 if hasattr(obj,'__class__'):
158 src = inspect.getsource(obj.__class__)
158 src = inspect.getsource(obj.__class__)
159 return src
159 return src
160
160
161 def getargspec(obj):
161 def getargspec(obj):
162 """Get the names and default values of a function's arguments.
162 """Get the names and default values of a function's arguments.
163
163
164 A tuple of four things is returned: (args, varargs, varkw, defaults).
164 A tuple of four things is returned: (args, varargs, varkw, defaults).
165 'args' is a list of the argument names (it may contain nested lists).
165 'args' is a list of the argument names (it may contain nested lists).
166 'varargs' and 'varkw' are the names of the * and ** arguments or None.
166 'varargs' and 'varkw' are the names of the * and ** arguments or None.
167 'defaults' is an n-tuple of the default values of the last n arguments.
167 'defaults' is an n-tuple of the default values of the last n arguments.
168
168
169 Modified version of inspect.getargspec from the Python Standard
169 Modified version of inspect.getargspec from the Python Standard
170 Library."""
170 Library."""
171
171
172 if inspect.isfunction(obj):
172 if inspect.isfunction(obj):
173 func_obj = obj
173 func_obj = obj
174 elif inspect.ismethod(obj):
174 elif inspect.ismethod(obj):
175 func_obj = obj.im_func
175 func_obj = obj.im_func
176 else:
176 else:
177 raise TypeError, 'arg is not a Python function'
177 raise TypeError, 'arg is not a Python function'
178 args, varargs, varkw = inspect.getargs(func_obj.func_code)
178 args, varargs, varkw = inspect.getargs(func_obj.func_code)
179 return args, varargs, varkw, func_obj.func_defaults
179 return args, varargs, varkw, func_obj.func_defaults
180
180
181 #****************************************************************************
181 #****************************************************************************
182 # Class definitions
182 # Class definitions
183
183
184 class myStringIO(StringIO.StringIO):
184 class myStringIO(StringIO.StringIO):
185 """Adds a writeln method to normal StringIO."""
185 """Adds a writeln method to normal StringIO."""
186 def writeln(self,*arg,**kw):
186 def writeln(self,*arg,**kw):
187 """Does a write() and then a write('\n')"""
187 """Does a write() and then a write('\n')"""
188 self.write(*arg,**kw)
188 self.write(*arg,**kw)
189 self.write('\n')
189 self.write('\n')
190
190
191
191
192 class Inspector:
192 class Inspector:
193 def __init__(self,color_table,code_color_table,scheme,
193 def __init__(self,color_table,code_color_table,scheme,
194 str_detail_level=0):
194 str_detail_level=0):
195 self.color_table = color_table
195 self.color_table = color_table
196 self.parser = PyColorize.Parser(code_color_table,out='str')
196 self.parser = PyColorize.Parser(code_color_table,out='str')
197 self.format = self.parser.format
197 self.format = self.parser.format
198 self.str_detail_level = str_detail_level
198 self.str_detail_level = str_detail_level
199 self.set_active_scheme(scheme)
199 self.set_active_scheme(scheme)
200
200
201 def __getdef(self,obj,oname=''):
201 def __getdef(self,obj,oname=''):
202 """Return the definition header for any callable object.
202 """Return the definition header for any callable object.
203
203
204 If any exception is generated, None is returned instead and the
204 If any exception is generated, None is returned instead and the
205 exception is suppressed."""
205 exception is suppressed."""
206
206
207 try:
207 try:
208 return oname + inspect.formatargspec(*getargspec(obj))
208 return oname + inspect.formatargspec(*getargspec(obj))
209 except:
209 except:
210 return None
210 return None
211
211
212 def __head(self,h):
212 def __head(self,h):
213 """Return a header string with proper colors."""
213 """Return a header string with proper colors."""
214 return '%s%s%s' % (self.color_table.active_colors.header,h,
214 return '%s%s%s' % (self.color_table.active_colors.header,h,
215 self.color_table.active_colors.normal)
215 self.color_table.active_colors.normal)
216
216
217 def set_active_scheme(self,scheme):
217 def set_active_scheme(self,scheme):
218 self.color_table.set_active_scheme(scheme)
218 self.color_table.set_active_scheme(scheme)
219 self.parser.color_table.set_active_scheme(scheme)
219 self.parser.color_table.set_active_scheme(scheme)
220
220
221 def noinfo(self,msg,oname):
221 def noinfo(self,msg,oname):
222 """Generic message when no information is found."""
222 """Generic message when no information is found."""
223 print 'No %s found' % msg,
223 print 'No %s found' % msg,
224 if oname:
224 if oname:
225 print 'for %s' % oname
225 print 'for %s' % oname
226 else:
226 else:
227 print
227 print
228
228
229 def pdef(self,obj,oname=''):
229 def pdef(self,obj,oname=''):
230 """Print the definition header for any callable object.
230 """Print the definition header for any callable object.
231
231
232 If the object is a class, print the constructor information."""
232 If the object is a class, print the constructor information."""
233
233
234 if not callable(obj):
234 if not callable(obj):
235 print 'Object is not callable.'
235 print 'Object is not callable.'
236 return
236 return
237
237
238 header = ''
238 header = ''
239
239
240 if inspect.isclass(obj):
240 if inspect.isclass(obj):
241 header = self.__head('Class constructor information:\n')
241 header = self.__head('Class constructor information:\n')
242 obj = obj.__init__
242 obj = obj.__init__
243 elif type(obj) is types.InstanceType:
243 elif type(obj) is types.InstanceType:
244 obj = obj.__call__
244 obj = obj.__call__
245
245
246 output = self.__getdef(obj,oname)
246 output = self.__getdef(obj,oname)
247 if output is None:
247 if output is None:
248 self.noinfo('definition header',oname)
248 self.noinfo('definition header',oname)
249 else:
249 else:
250 print >>Term.cout, header,self.format(output),
250 print >>Term.cout, header,self.format(output),
251
251
252 def pdoc(self,obj,oname='',formatter = None):
252 def pdoc(self,obj,oname='',formatter = None):
253 """Print the docstring for any object.
253 """Print the docstring for any object.
254
254
255 Optional:
255 Optional:
256 -formatter: a function to run the docstring through for specially
256 -formatter: a function to run the docstring through for specially
257 formatted docstrings."""
257 formatted docstrings."""
258
258
259 head = self.__head # so that itpl can find it even if private
259 head = self.__head # so that itpl can find it even if private
260 ds = getdoc(obj)
260 ds = getdoc(obj)
261 if formatter:
261 if formatter:
262 ds = formatter(ds)
262 ds = formatter(ds)
263 if inspect.isclass(obj):
263 if inspect.isclass(obj):
264 init_ds = getdoc(obj.__init__)
264 init_ds = getdoc(obj.__init__)
265 output = itpl('$head("Class Docstring:")\n'
265 output = itpl('$head("Class Docstring:")\n'
266 '$indent(ds)\n'
266 '$indent(ds)\n'
267 '$head("Constructor Docstring"):\n'
267 '$head("Constructor Docstring"):\n'
268 '$indent(init_ds)')
268 '$indent(init_ds)')
269 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
269 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
270 and hasattr(obj,'__call__'):
270 and hasattr(obj,'__call__'):
271 call_ds = getdoc(obj.__call__)
271 call_ds = getdoc(obj.__call__)
272 if call_ds:
272 if call_ds:
273 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
273 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
274 '$head("Calling Docstring:")\n$indent(call_ds)')
274 '$head("Calling Docstring:")\n$indent(call_ds)')
275 else:
275 else:
276 output = ds
276 output = ds
277 else:
277 else:
278 output = ds
278 output = ds
279 if output is None:
279 if output is None:
280 self.noinfo('documentation',oname)
280 self.noinfo('documentation',oname)
281 return
281 return
282 page(output)
282 page(output)
283
283
284 def psource(self,obj,oname=''):
284 def psource(self,obj,oname=''):
285 """Print the source code for an object."""
285 """Print the source code for an object."""
286
286
287 # Flush the source cache because inspect can return out-of-date source
287 # Flush the source cache because inspect can return out-of-date source
288 linecache.checkcache()
288 linecache.checkcache()
289 try:
289 try:
290 src = getsource(obj)
290 src = getsource(obj)
291 except:
291 except:
292 self.noinfo('source',oname)
292 self.noinfo('source',oname)
293 else:
293 else:
294 page(self.format(src))
294 page(self.format(src))
295
295
296 def pfile(self,obj,oname=''):
296 def pfile(self,obj,oname=''):
297 """Show the whole file where an object was defined."""
297 """Show the whole file where an object was defined."""
298
298
299 try:
299 try:
300 try:
300 try:
301 lineno = inspect.getsourcelines(obj)[1]
301 lineno = inspect.getsourcelines(obj)[1]
302 except TypeError:
302 except TypeError:
303 # For instances, try the class object like getsource() does
303 # For instances, try the class object like getsource() does
304 if hasattr(obj,'__class__'):
304 if hasattr(obj,'__class__'):
305 lineno = inspect.getsourcelines(obj.__class__)[1]
305 lineno = inspect.getsourcelines(obj.__class__)[1]
306 # Adjust the inspected object so getabsfile() below works
306 # Adjust the inspected object so getabsfile() below works
307 obj = obj.__class__
307 obj = obj.__class__
308 except:
308 except:
309 self.noinfo('file',oname)
309 self.noinfo('file',oname)
310 return
310 return
311
311
312 # We only reach this point if object was successfully queried
312 # We only reach this point if object was successfully queried
313
313
314 # run contents of file through pager starting at line
314 # run contents of file through pager starting at line
315 # where the object is defined
315 # where the object is defined
316 ofile = inspect.getabsfile(obj)
316 ofile = inspect.getabsfile(obj)
317
317
318 if (ofile.endswith('.so') or ofile.endswith('.dll')):
318 if (ofile.endswith('.so') or ofile.endswith('.dll')):
319 print 'File %r is binary, not printing.' % ofile
319 print 'File %r is binary, not printing.' % ofile
320 elif not os.path.isfile(ofile):
320 elif not os.path.isfile(ofile):
321 print 'File %r does not exist, not printing.' % ofile
321 print 'File %r does not exist, not printing.' % ofile
322 else:
322 else:
323 # Print only text files, not extension binaries. Note that
323 # Print only text files, not extension binaries. Note that
324 # getsourcelines returns lineno with 1-offset and page() uses
324 # getsourcelines returns lineno with 1-offset and page() uses
325 # 0-offset, so we must adjust.
325 # 0-offset, so we must adjust.
326 page(self.format(open(ofile).read()),lineno-1)
326 page(self.format(open(ofile).read()),lineno-1)
327
327
328 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
328 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
329 """Show detailed information about an object.
329 """Show detailed information about an object.
330
330
331 Optional arguments:
331 Optional arguments:
332
332
333 - oname: name of the variable pointing to the object.
333 - oname: name of the variable pointing to the object.
334
334
335 - formatter: special formatter for docstrings (see pdoc)
335 - formatter: special formatter for docstrings (see pdoc)
336
336
337 - info: a structure with some information fields which may have been
337 - info: a structure with some information fields which may have been
338 precomputed already.
338 precomputed already.
339
339
340 - detail_level: if set to 1, more information is given.
340 - detail_level: if set to 1, more information is given.
341 """
341 """
342
342
343 obj_type = type(obj)
343 obj_type = type(obj)
344
344
345 header = self.__head
345 header = self.__head
346 if info is None:
346 if info is None:
347 ismagic = 0
347 ismagic = 0
348 isalias = 0
348 isalias = 0
349 ospace = ''
349 ospace = ''
350 else:
350 else:
351 ismagic = info.ismagic
351 ismagic = info.ismagic
352 isalias = info.isalias
352 isalias = info.isalias
353 ospace = info.namespace
353 ospace = info.namespace
354 # Get docstring, special-casing aliases:
354 # Get docstring, special-casing aliases:
355 if isalias:
355 if isalias:
356 if not callable(obj):
356 if not callable(obj):
357 try:
357 try:
358 ds = "Alias to the system command:\n %s" % obj[1]
358 ds = "Alias to the system command:\n %s" % obj[1]
359 except:
359 except:
360 ds = "Alias: " + str(obj)
360 ds = "Alias: " + str(obj)
361 else:
361 else:
362 ds = "Alias to " + str(obj)
362 ds = "Alias to " + str(obj)
363 if obj.__doc__:
363 if obj.__doc__:
364 ds += "\nDocstring:\n" + obj.__doc__
364 ds += "\nDocstring:\n" + obj.__doc__
365 else:
365 else:
366 ds = getdoc(obj)
366 ds = getdoc(obj)
367 if ds is None:
367 if ds is None:
368 ds = '<no docstring>'
368 ds = '<no docstring>'
369 if formatter is not None:
369 if formatter is not None:
370 ds = formatter(ds)
370 ds = formatter(ds)
371
371
372 # store output in a list which gets joined with \n at the end.
372 # store output in a list which gets joined with \n at the end.
373 out = myStringIO()
373 out = myStringIO()
374
374
375 string_max = 200 # max size of strings to show (snipped if longer)
375 string_max = 200 # max size of strings to show (snipped if longer)
376 shalf = int((string_max -5)/2)
376 shalf = int((string_max -5)/2)
377
377
378 if ismagic:
378 if ismagic:
379 obj_type_name = 'Magic function'
379 obj_type_name = 'Magic function'
380 elif isalias:
380 elif isalias:
381 obj_type_name = 'System alias'
381 obj_type_name = 'System alias'
382 else:
382 else:
383 obj_type_name = obj_type.__name__
383 obj_type_name = obj_type.__name__
384 out.writeln(header('Type:\t\t')+obj_type_name)
384 out.writeln(header('Type:\t\t')+obj_type_name)
385
385
386 try:
386 try:
387 bclass = obj.__class__
387 bclass = obj.__class__
388 out.writeln(header('Base Class:\t')+str(bclass))
388 out.writeln(header('Base Class:\t')+str(bclass))
389 except: pass
389 except: pass
390
390
391 # String form, but snip if too long in ? form (full in ??)
391 # String form, but snip if too long in ? form (full in ??)
392 if detail_level >= self.str_detail_level:
392 if detail_level >= self.str_detail_level:
393 try:
393 try:
394 ostr = str(obj)
394 ostr = str(obj)
395 str_head = 'String Form:'
395 str_head = 'String Form:'
396 if not detail_level and len(ostr)>string_max:
396 if not detail_level and len(ostr)>string_max:
397 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
397 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
398 ostr = ("\n" + " " * len(str_head.expandtabs())).\
398 ostr = ("\n" + " " * len(str_head.expandtabs())).\
399 join(map(string.strip,ostr.split("\n")))
399 join(map(string.strip,ostr.split("\n")))
400 if ostr.find('\n') > -1:
400 if ostr.find('\n') > -1:
401 # Print multi-line strings starting at the next line.
401 # Print multi-line strings starting at the next line.
402 str_sep = '\n'
402 str_sep = '\n'
403 else:
403 else:
404 str_sep = '\t'
404 str_sep = '\t'
405 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
405 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
406 except:
406 except:
407 pass
407 pass
408
408
409 if ospace:
409 if ospace:
410 out.writeln(header('Namespace:\t')+ospace)
410 out.writeln(header('Namespace:\t')+ospace)
411
411
412 # Length (for strings and lists)
412 # Length (for strings and lists)
413 try:
413 try:
414 length = str(len(obj))
414 length = str(len(obj))
415 out.writeln(header('Length:\t\t')+length)
415 out.writeln(header('Length:\t\t')+length)
416 except: pass
416 except: pass
417
417
418 # Filename where object was defined
418 # Filename where object was defined
419 binary_file = False
419 binary_file = False
420 try:
420 try:
421 try:
421 try:
422 fname = inspect.getabsfile(obj)
422 fname = inspect.getabsfile(obj)
423 except TypeError:
423 except TypeError:
424 # For an instance, the file that matters is where its class was
424 # For an instance, the file that matters is where its class was
425 # declared.
425 # declared.
426 if hasattr(obj,'__class__'):
426 if hasattr(obj,'__class__'):
427 fname = inspect.getabsfile(obj.__class__)
427 fname = inspect.getabsfile(obj.__class__)
428 if fname.endswith('<string>'):
428 if fname.endswith('<string>'):
429 fname = 'Dynamically generated function. No source code available.'
429 fname = 'Dynamically generated function. No source code available.'
430 if (fname.endswith('.so') or fname.endswith('.dll')):
430 if (fname.endswith('.so') or fname.endswith('.dll')):
431 binary_file = True
431 binary_file = True
432 out.writeln(header('File:\t\t')+fname)
432 out.writeln(header('File:\t\t')+fname)
433 except:
433 except:
434 # if anything goes wrong, we don't want to show source, so it's as
434 # if anything goes wrong, we don't want to show source, so it's as
435 # if the file was binary
435 # if the file was binary
436 binary_file = True
436 binary_file = True
437
437
438 # reconstruct the function definition and print it:
438 # reconstruct the function definition and print it:
439 defln = self.__getdef(obj,oname)
439 defln = self.__getdef(obj,oname)
440 if defln:
440 if defln:
441 out.write(header('Definition:\t')+self.format(defln))
441 out.write(header('Definition:\t')+self.format(defln))
442
442
443 # Docstrings only in detail 0 mode, since source contains them (we
443 # Docstrings only in detail 0 mode, since source contains them (we
444 # avoid repetitions). If source fails, we add them back, see below.
444 # avoid repetitions). If source fails, we add them back, see below.
445 if ds and detail_level == 0:
445 if ds and detail_level == 0:
446 out.writeln(header('Docstring:\n') + indent(ds))
446 out.writeln(header('Docstring:\n') + indent(ds))
447
447
448 # Original source code for any callable
448 # Original source code for any callable
449 if detail_level:
449 if detail_level:
450 # Flush the source cache because inspect can return out-of-date
450 # Flush the source cache because inspect can return out-of-date
451 # source
451 # source
452 linecache.checkcache()
452 linecache.checkcache()
453 source_success = False
453 source_success = False
454 try:
454 try:
455 try:
455 try:
456 src = getsource(obj,binary_file)
456 src = getsource(obj,binary_file)
457 except TypeError:
457 except TypeError:
458 if hasattr(obj,'__class__'):
458 if hasattr(obj,'__class__'):
459 src = getsource(obj.__class__,binary_file)
459 src = getsource(obj.__class__,binary_file)
460 if src is not None:
460 if src is not None:
461 source = self.format(src)
461 source = self.format(src)
462 out.write(header('Source:\n')+source.rstrip())
462 out.write(header('Source:\n')+source.rstrip())
463 source_success = True
463 source_success = True
464 except Exception, msg:
464 except Exception, msg:
465 pass
465 pass
466
466
467 if ds and not source_success:
467 if ds and not source_success:
468 out.writeln(header('Docstring [source file open failed]:\n')
468 out.writeln(header('Docstring [source file open failed]:\n')
469 + indent(ds))
469 + indent(ds))
470
470
471 # Constructor docstring for classes
471 # Constructor docstring for classes
472 if inspect.isclass(obj):
472 if inspect.isclass(obj):
473 # reconstruct the function definition and print it:
473 # reconstruct the function definition and print it:
474 try:
474 try:
475 obj_init = obj.__init__
475 obj_init = obj.__init__
476 except AttributeError:
476 except AttributeError:
477 init_def = init_ds = None
477 init_def = init_ds = None
478 else:
478 else:
479 init_def = self.__getdef(obj_init,oname)
479 init_def = self.__getdef(obj_init,oname)
480 init_ds = getdoc(obj_init)
480 init_ds = getdoc(obj_init)
481 # Skip Python's auto-generated docstrings
481 # Skip Python's auto-generated docstrings
482 if init_ds and \
482 if init_ds and \
483 init_ds.startswith('x.__init__(...) initializes'):
483 init_ds.startswith('x.__init__(...) initializes'):
484 init_ds = None
484 init_ds = None
485
485
486 if init_def or init_ds:
486 if init_def or init_ds:
487 out.writeln(header('\nConstructor information:'))
487 out.writeln(header('\nConstructor information:'))
488 if init_def:
488 if init_def:
489 out.write(header('Definition:\t')+ self.format(init_def))
489 out.write(header('Definition:\t')+ self.format(init_def))
490 if init_ds:
490 if init_ds:
491 out.writeln(header('Docstring:\n') + indent(init_ds))
491 out.writeln(header('Docstring:\n') + indent(init_ds))
492 # and class docstring for instances:
492 # and class docstring for instances:
493 elif obj_type is types.InstanceType or \
493 elif obj_type is types.InstanceType or \
494 isinstance(obj,object):
494 isinstance(obj,object):
495
495
496 # First, check whether the instance docstring is identical to the
496 # First, check whether the instance docstring is identical to the
497 # class one, and print it separately if they don't coincide. In
497 # class one, and print it separately if they don't coincide. In
498 # most cases they will, but it's nice to print all the info for
498 # most cases they will, but it's nice to print all the info for
499 # objects which use instance-customized docstrings.
499 # objects which use instance-customized docstrings.
500 if ds:
500 if ds:
501 try:
501 try:
502 cls = getattr(obj,'__class__')
502 cls = getattr(obj,'__class__')
503 except:
503 except:
504 class_ds = None
504 class_ds = None
505 else:
505 else:
506 class_ds = getdoc(cls)
506 class_ds = getdoc(cls)
507 # Skip Python's auto-generated docstrings
507 # Skip Python's auto-generated docstrings
508 if class_ds and \
508 if class_ds and \
509 (class_ds.startswith('function(code, globals[,') or \
509 (class_ds.startswith('function(code, globals[,') or \
510 class_ds.startswith('instancemethod(function, instance,') or \
510 class_ds.startswith('instancemethod(function, instance,') or \
511 class_ds.startswith('module(name[,') ):
511 class_ds.startswith('module(name[,') ):
512 class_ds = None
512 class_ds = None
513 if class_ds and ds != class_ds:
513 if class_ds and ds != class_ds:
514 out.writeln(header('Class Docstring:\n') +
514 out.writeln(header('Class Docstring:\n') +
515 indent(class_ds))
515 indent(class_ds))
516
516
517 # Next, try to show constructor docstrings
517 # Next, try to show constructor docstrings
518 try:
518 try:
519 init_ds = getdoc(obj.__init__)
519 init_ds = getdoc(obj.__init__)
520 # Skip Python's auto-generated docstrings
520 # Skip Python's auto-generated docstrings
521 if init_ds and \
521 if init_ds and \
522 init_ds.startswith('x.__init__(...) initializes'):
522 init_ds.startswith('x.__init__(...) initializes'):
523 init_ds = None
523 init_ds = None
524 except AttributeError:
524 except AttributeError:
525 init_ds = None
525 init_ds = None
526 if init_ds:
526 if init_ds:
527 out.writeln(header('Constructor Docstring:\n') +
527 out.writeln(header('Constructor Docstring:\n') +
528 indent(init_ds))
528 indent(init_ds))
529
529
530 # Call form docstring for callable instances
530 # Call form docstring for callable instances
531 if hasattr(obj,'__call__'):
531 if hasattr(obj,'__call__'):
532 #out.writeln(header('Callable:\t')+'Yes')
532 #out.writeln(header('Callable:\t')+'Yes')
533 call_def = self.__getdef(obj.__call__,oname)
533 call_def = self.__getdef(obj.__call__,oname)
534 #if call_def is None:
534 #if call_def is None:
535 # out.writeln(header('Call def:\t')+
535 # out.writeln(header('Call def:\t')+
536 # 'Calling definition not available.')
536 # 'Calling definition not available.')
537 if call_def is not None:
537 if call_def is not None:
538 out.writeln(header('Call def:\t')+self.format(call_def))
538 out.writeln(header('Call def:\t')+self.format(call_def))
539 call_ds = getdoc(obj.__call__)
539 call_ds = getdoc(obj.__call__)
540 # Skip Python's auto-generated docstrings
540 # Skip Python's auto-generated docstrings
541 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
541 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
542 call_ds = None
542 call_ds = None
543 if call_ds:
543 if call_ds:
544 out.writeln(header('Call docstring:\n') + indent(call_ds))
544 out.writeln(header('Call docstring:\n') + indent(call_ds))
545
545
546 # Finally send to printer/pager
546 # Finally send to printer/pager
547 output = out.getvalue()
547 output = out.getvalue()
548 if output:
548 if output:
549 page(output)
549 page(output)
550 # end pinfo
550 # end pinfo
551
551
552 def psearch(self,pattern,ns_table,ns_search=[],
552 def psearch(self,pattern,ns_table,ns_search=[],
553 ignore_case=False,show_all=False):
553 ignore_case=False,show_all=False):
554 """Search namespaces with wildcards for objects.
554 """Search namespaces with wildcards for objects.
555
555
556 Arguments:
556 Arguments:
557
557
558 - pattern: string containing shell-like wildcards to use in namespace
558 - pattern: string containing shell-like wildcards to use in namespace
559 searches and optionally a type specification to narrow the search to
559 searches and optionally a type specification to narrow the search to
560 objects of that type.
560 objects of that type.
561
561
562 - ns_table: dict of name->namespaces for search.
562 - ns_table: dict of name->namespaces for search.
563
563
564 Optional arguments:
564 Optional arguments:
565
565
566 - ns_search: list of namespace names to include in search.
566 - ns_search: list of namespace names to include in search.
567
567
568 - ignore_case(False): make the search case-insensitive.
568 - ignore_case(False): make the search case-insensitive.
569
569
570 - show_all(False): show all names, including those starting with
570 - show_all(False): show all names, including those starting with
571 underscores.
571 underscores.
572 """
572 """
573 #print 'ps pattern:<%r>' % pattern # dbg
573 #print 'ps pattern:<%r>' % pattern # dbg
574
574
575 # defaults
575 # defaults
576 type_pattern = 'all'
576 type_pattern = 'all'
577 filter = ''
577 filter = ''
578
578
579 cmds = pattern.split()
579 cmds = pattern.split()
580 len_cmds = len(cmds)
580 len_cmds = len(cmds)
581 if len_cmds == 1:
581 if len_cmds == 1:
582 # Only filter pattern given
582 # Only filter pattern given
583 filter = cmds[0]
583 filter = cmds[0]
584 elif len_cmds == 2:
584 elif len_cmds == 2:
585 # Both filter and type specified
585 # Both filter and type specified
586 filter,type_pattern = cmds
586 filter,type_pattern = cmds
587 else:
587 else:
588 raise ValueError('invalid argument string for psearch: <%s>' %
588 raise ValueError('invalid argument string for psearch: <%s>' %
589 pattern)
589 pattern)
590
590
591 # filter search namespaces
591 # filter search namespaces
592 for name in ns_search:
592 for name in ns_search:
593 if name not in ns_table:
593 if name not in ns_table:
594 raise ValueError('invalid namespace <%s>. Valid names: %s' %
594 raise ValueError('invalid namespace <%s>. Valid names: %s' %
595 (name,ns_table.keys()))
595 (name,ns_table.keys()))
596
596
597 #print 'type_pattern:',type_pattern # dbg
597 #print 'type_pattern:',type_pattern # dbg
598 search_result = []
598 search_result = []
599 for ns_name in ns_search:
599 for ns_name in ns_search:
600 ns = ns_table[ns_name]
600 ns = ns_table[ns_name]
601 tmp_res = list(list_namespace(ns,type_pattern,filter,
601 tmp_res = list(list_namespace(ns,type_pattern,filter,
602 ignore_case=ignore_case,
602 ignore_case=ignore_case,
603 show_all=show_all))
603 show_all=show_all))
604 search_result.extend(tmp_res)
604 search_result.extend(tmp_res)
605 search_result.sort()
605 search_result.sort()
606
606
607 page('\n'.join(search_result))
607 page('\n'.join(search_result))
@@ -1,32 +1,35 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 # encoding: utf-8
2 # encoding: utf-8
3
3
4 def test_import_coloransi():
4 def test_import_coloransi():
5 from IPython.utils import coloransi
5 from IPython.utils import coloransi
6
6
7 def test_import_DPyGetOpt():
7 def test_import_DPyGetOpt():
8 from IPython.utils import DPyGetOpt
8 from IPython.utils import DPyGetOpt
9
9
10 def test_import_generics():
10 def test_import_generics():
11 from IPython.utils import generics
11 from IPython.utils import generics
12
12
13 def test_import_genutils():
13 def test_import_genutils():
14 from IPython.utils import genutils
14 from IPython.utils import genutils
15
15
16 def test_import_ipstruct():
16 def test_import_ipstruct():
17 from IPython.utils import ipstruct
17 from IPython.utils import ipstruct
18
18
19 def test_import_platutils():
19 def test_import_platutils():
20 from IPython.utils import platutils
20 from IPython.utils import platutils
21
21
22 def test_import_PyColorize():
22 def test_import_PyColorize():
23 from IPython.utils import PyColorize
23 from IPython.utils import PyColorize
24
24
25 def test_import_rlineimpl():
25 def test_import_rlineimpl():
26 from IPython.utils import rlineimpl
26 from IPython.utils import rlineimpl
27
27
28 def test_import_strdispatch():
28 def test_import_strdispatch():
29 from IPython.utils import strdispatch
29 from IPython.utils import strdispatch
30
30
31 def test_import_upgradedir():
31 def test_import_upgradedir():
32 from IPython.utils import upgradedir
32 from IPython.utils import upgradedir
33
34 def test_import_wildcard():
35 from IPython.utils import wildcard
1 NO CONTENT: file renamed from IPython/wildcard.py to IPython/utils/wildcard.py
NO CONTENT: file renamed from IPython/wildcard.py to IPython/utils/wildcard.py
@@ -1,270 +1,270 b''
1 =============================
1 =============================
2 IPython module reorganization
2 IPython module reorganization
3 =============================
3 =============================
4
4
5 Currently, IPython has many top-level modules that serve many different purposes.
5 Currently, IPython has many top-level modules that serve many different purposes.
6 The lack of organization make it very difficult for developers to work on IPython
6 The lack of organization make it very difficult for developers to work on IPython
7 and understand its design. This document contains notes about how we will reorganize
7 and understand its design. This document contains notes about how we will reorganize
8 the modules into sub-packages.
8 the modules into sub-packages.
9
9
10 .. warning::
10 .. warning::
11
11
12 This effort will possibly break third party packages that use IPython as
12 This effort will possibly break third party packages that use IPython as
13 a library or hack on the IPython internals.
13 a library or hack on the IPython internals.
14
14
15 .. warning::
15 .. warning::
16
16
17 This effort will result in the removal from IPython of certain modules
17 This effort will result in the removal from IPython of certain modules
18 that are not used anymore, don't currently work, are unmaintained, etc.
18 that are not used anymore, don't currently work, are unmaintained, etc.
19
19
20
20
21 Current subpackges
21 Current subpackges
22 ==================
22 ==================
23
23
24 IPython currently has the following sub-packages:
24 IPython currently has the following sub-packages:
25
25
26 * :mod:`IPython.config`
26 * :mod:`IPython.config`
27
27
28 * :mod:`IPython.Extensions`
28 * :mod:`IPython.Extensions`
29
29
30 * :mod:`IPython.external`
30 * :mod:`IPython.external`
31
31
32 * :mod:`IPython.frontend`
32 * :mod:`IPython.frontend`
33
33
34 * :mod:`IPython.gui`
34 * :mod:`IPython.gui`
35
35
36 * :mod:`IPython.kernel`
36 * :mod:`IPython.kernel`
37
37
38 * :mod:`IPython.testing`
38 * :mod:`IPython.testing`
39
39
40 * :mod:`IPython.tests`
40 * :mod:`IPython.tests`
41
41
42 * :mod:`IPython.tools`
42 * :mod:`IPython.tools`
43
43
44 * :mod:`IPython.UserConfig`
44 * :mod:`IPython.UserConfig`
45
45
46 New Subpackages to be created
46 New Subpackages to be created
47 =============================
47 =============================
48
48
49 We propose to create the following new sub-packages:
49 We propose to create the following new sub-packages:
50
50
51 * :mod:`IPython.core`. This sub-package will contain the core of the IPython
51 * :mod:`IPython.core`. This sub-package will contain the core of the IPython
52 interpreter, but none of its extended capabilities.
52 interpreter, but none of its extended capabilities.
53
53
54 * :mod:`IPython.lib`. IPython has many extended capabilities that are not part
54 * :mod:`IPython.lib`. IPython has many extended capabilities that are not part
55 of the IPython core. These things will go here. Any better names than
55 of the IPython core. These things will go here. Any better names than
56 :mod:`IPython.lib`?
56 :mod:`IPython.lib`?
57
57
58 * :mod:`IPython.utils`. This sub-package will contain anything that might
58 * :mod:`IPython.utils`. This sub-package will contain anything that might
59 eventually be found in the Python standard library, like things in
59 eventually be found in the Python standard library, like things in
60 :mod:`genutils`. Each sub-module in this sub-package should contain
60 :mod:`genutils`. Each sub-module in this sub-package should contain
61 functions and classes that serve a single purpose.
61 functions and classes that serve a single purpose.
62
62
63 * :mod:`IPython.deathrow`. This is for code that is untested and/or rotting
63 * :mod:`IPython.deathrow`. This is for code that is untested and/or rotting
64 and needs to be removed from IPython. Eventually all this code will either
64 and needs to be removed from IPython. Eventually all this code will either
65 i) be revived by someone willing to maintain it with tests and docs and
65 i) be revived by someone willing to maintain it with tests and docs and
66 re-included into IPython or 2) be removed from IPython proper, but put into
66 re-included into IPython or 2) be removed from IPython proper, but put into
67 a separate top-level (not IPython) package that we keep around. No new code
67 a separate top-level (not IPython) package that we keep around. No new code
68 will be allowed here.
68 will be allowed here.
69
69
70 * :mod:`IPython.quarantine`. This is for code that doesn't meet IPython's
70 * :mod:`IPython.quarantine`. This is for code that doesn't meet IPython's
71 standards, but that we plan on keeping. To be moved out of this sub-package
71 standards, but that we plan on keeping. To be moved out of this sub-package
72 a module needs to have a maintainer, tests and documentation.
72 a module needs to have a maintainer, tests and documentation.
73
73
74 Prodecure
74 Prodecure
75 =========
75 =========
76
76
77 1. Move the file to its new location with its new name.
77 1. Move the file to its new location with its new name.
78 2. Rename all import statements to reflect the change.
78 2. Rename all import statements to reflect the change.
79 3. Run PyFlakes on each changes module.
79 3. Run PyFlakes on each changes module.
80 3. Add tests/test_imports.py to test it.
80 3. Add tests/test_imports.py to test it.
81
81
82 Need to modify iptests to properly skip modules that are no longer top
82 Need to modify iptests to properly skip modules that are no longer top
83 level modules.
83 level modules.
84
84
85 Need to update the top level IPython/__init__.py file.
85 Need to update the top level IPython/__init__.py file.
86
86
87 Where things will be moved
87 Where things will be moved
88 ==========================
88 ==========================
89
89
90 * :file:`background_jobs.py`. Move to :file:`IPython/lib/backgroundjobs.py`.
90 * :file:`background_jobs.py`. Move to :file:`IPython/lib/backgroundjobs.py`.
91
91
92 * :file:`ColorANSI.py`. Move to :file:`IPython/utils/coloransi.py`.
92 * :file:`ColorANSI.py`. Move to :file:`IPython/utils/coloransi.py`.
93
93
94 * :file:`completer.py`. Move to :file:`IPython/core/completer.py`.
94 * :file:`completer.py`. Move to :file:`IPython/core/completer.py`.
95
95
96 * :file:`ConfigLoader.py`. Move to :file:`IPython/config/configloader.py`.
96 * :file:`ConfigLoader.py`. Move to :file:`IPython/config/configloader.py`.
97
97
98 * :file:`CrashHandler.py`. Move to :file:`IPython/core/crashhandler`.
98 * :file:`CrashHandler.py`. Move to :file:`IPython/core/crashhandler`.
99
99
100 * :file:`Debugger.py`. Move to :file:`IPython/core/debugger.py`.
100 * :file:`Debugger.py`. Move to :file:`IPython/core/debugger.py`.
101
101
102 * :file:`deep_reload.py`. Move to :file:`IPython/lib/deepreload.py`.
102 * :file:`deep_reload.py`. Move to :file:`IPython/lib/deepreload.py`.
103
103
104 * :file:`demo.py`. Move to :file:`IPython/lib/demo.py`.
104 * :file:`demo.py`. Move to :file:`IPython/lib/demo.py`.
105
105
106 * :file:`DPyGetOpt.py`. Move to :mod:`IPython.utils` and replace with newer options parser.
106 * :file:`DPyGetOpt.py`. Move to :mod:`IPython.utils` and replace with newer options parser.
107
107
108 * :file:`dtutils.py`. Move to :file:`IPython.deathrow`.
108 * :file:`dtutils.py`. Move to :file:`IPython.deathrow`.
109
109
110 * :file:`excolors.py`. Move to :file:`IPython.core` or :file:`IPython.config`.
110 * :file:`excolors.py`. Move to :file:`IPython.core` or :file:`IPython.config`.
111 Maybe move to :mod:`IPython.lib` or :mod:`IPython.python`?
111 Maybe move to :mod:`IPython.lib` or :mod:`IPython.python`?
112
112
113 * :file:`FakeModule.py`. Move to :file:`IPython/core/fakemodule.py`.
113 * :file:`FakeModule.py`. Move to :file:`IPython/core/fakemodule.py`.
114
114
115 * :file:`generics.py`. Move to :file:`IPython.python`.
115 * :file:`generics.py`. Move to :file:`IPython.python`.
116
116
117 * :file:`genutils.py`. Move to :file:`IPython.utils`.
117 * :file:`genutils.py`. Move to :file:`IPython.utils`.
118
118
119 * :file:`Gnuplot2.py`. Move to :file:`IPython.sandbox`.
119 * :file:`Gnuplot2.py`. Move to :file:`IPython.sandbox`.
120
120
121 * :file:`GnuplotInteractive.py`. Move to :file:`IPython.sandbox`.
121 * :file:`GnuplotInteractive.py`. Move to :file:`IPython.sandbox`.
122
122
123 * :file:`GnuplotRuntime.py`. Move to :file:`IPython.sandbox`.
123 * :file:`GnuplotRuntime.py`. Move to :file:`IPython.sandbox`.
124
124
125 * :file:`numutils.py`. Move to :file:`IPython.sandbox`.
125 * :file:`numutils.py`. Move to :file:`IPython.sandbox`.
126
126
127 * :file:`twshell.py`. Move to :file:`IPython.sandbox`.
127 * :file:`twshell.py`. Move to :file:`IPython.sandbox`.
128
128
129 * :file:`Extensions`. This needs to be gone through separately. Minimally,
129 * :file:`Extensions`. This needs to be gone through separately. Minimally,
130 the package should be renamed to :file:`extensions`.
130 the package should be renamed to :file:`extensions`.
131
131
132 * :file:`history.py`. Move to :file:`IPython.core`.
132 * :file:`history.py`. Move to :file:`IPython.core`.
133
133
134 * :file:`hooks.py`. Move to :file:`IPython.core`.
134 * :file:`hooks.py`. Move to :file:`IPython.core`.
135
135
136 * :file:`ipapi.py`. Move to :file:`IPython.core`.
136 * :file:`ipapi.py`. Move to :file:`IPython.core`.
137
137
138 * :file:`iplib.py`. Move to :file:`IPython.core`.
138 * :file:`iplib.py`. Move to :file:`IPython.core`.
139
139
140 * :file:`ipmaker.py`: Move to :file:`IPython.core`.
140 * :file:`ipmaker.py`: Move to :file:`IPython.core`.
141
141
142 * :file:`ipstruct.py`. Move to :file:`IPython.python`.
142 * :file:`ipstruct.py`. Move to :file:`IPython.python`.
143
143
144 * :file:`irunner.py`. Move to :file:`IPython.scripts`. ???
144 * :file:`irunner.py`. Move to :file:`IPython.scripts`. ???
145
145
146 * :file:`Itpl.py`. Move to :file:`deathrow/Itpl.py`. Copy already in
146 * :file:`Itpl.py`. Move to :file:`deathrow/Itpl.py`. Copy already in
147 :file:`IPython.external`.
147 :file:`IPython.external`.
148
148
149 * :file:`Logger.py`. Move to :file:`IPython/core/logger.py`.
149 * :file:`Logger.py`. Move to :file:`IPython/core/logger.py`.
150
150
151 * :file:`macro.py`. Move to :file:`IPython.core`.
151 * :file:`macro.py`. Move to :file:`IPython.core`.
152
152
153 * :file:`Magic.py`. Move to :file:`IPython/core/magic.py`.
153 * :file:`Magic.py`. Move to :file:`IPython/core/magic.py`.
154
154
155 * :file:`OInspect.py`. Move to :file:`IPython/core/oinspect.py`.
155 * :file:`OInspect.py`. Move to :file:`IPython/core/oinspect.py`.
156
156
157 * :file:`OutputTrap.py`. Move to :file:`IPython/core/outputtrap.py`.
157 * :file:`OutputTrap.py`. Move to :file:`IPython/core/outputtrap.py`.
158
158
159 * :file:`platutils.py`. Move to :file:`IPython.python`.
159 * :file:`platutils.py`. Move to :file:`IPython.python`.
160
160
161 * :file:`platutils_dummy.py`. Move to :file:`IPython.python`.
161 * :file:`platutils_dummy.py`. Move to :file:`IPython.python`.
162
162
163 * :file:`platutils_posix.py`. Move to :file:`IPython.python`.
163 * :file:`platutils_posix.py`. Move to :file:`IPython.python`.
164
164
165 * :file:`platutils_win32.py`. Move to :file:`IPython.python`.
165 * :file:`platutils_win32.py`. Move to :file:`IPython.python`.
166
166
167 * :file:`prefilter.py`: Move to :file:`IPython.core`.
167 * :file:`prefilter.py`: Move to :file:`IPython.core`.
168
168
169 * :file:`Prompts.py`. Move to :file:`IPython/core/prompts.py` or
169 * :file:`Prompts.py`. Move to :file:`IPython/core/prompts.py` or
170 :file:`IPython/frontend/prompts.py`.
170 :file:`IPython/frontend/prompts.py`.
171
171
172 * :file:`PyColorize.py`. Replace with pygments? If not, move to
172 * :file:`PyColorize.py`. Replace with pygments? If not, move to
173 :file:`IPython/core/pycolorize.py`. Maybe move to :mod:`IPython.lib` or
173 :file:`IPython/core/pycolorize.py`. Maybe move to :mod:`IPython.lib` or
174 :mod:`IPython.python`?
174 :mod:`IPython.python`?
175
175
176 * :file:`Release.py`. Move to ??? or remove?
176 * :file:`Release.py`. Move to ??? or remove?
177
177
178 * :file:`rlineimpl.py`. Move to :file:`IPython.core`.
178 * :file:`rlineimpl.py`. Move to :file:`IPython.core`.
179
179
180 * :file:`shadowns.py`. Move to :file:`IPython.core`.
180 * :file:`shadowns.py`. Move to :file:`IPython.core`.
181
181
182 * :file:`Shell.py`. Move to :file:`IPython.core.shell.py` or
182 * :file:`Shell.py`. Move to :file:`IPython.core.shell.py` or
183 :file:`IPython/frontend/shell.py`.
183 :file:`IPython/frontend/shell.py`.
184
184
185 * :file:`shellglobals.py`. Move to :file:`IPython.core`.
185 * :file:`shellglobals.py`. Move to :file:`IPython.core`.
186
186
187 * :file:`strdispatch.py`. Move to :file:`IPython.python`.
187 * :file:`strdispatch.py`. Move to :file:`IPython.python`.
188
188
189 * :file:`testing`. Good where it is.
189 * :file:`testing`. Good where it is.
190
190
191 * :file:`tests`. Good where it is.
191 * :file:`tests`. Good where it is.
192
192
193 * :file:`tools`. Things in here need to be looked at and moved elsewhere like
193 * :file:`tools`. Things in here need to be looked at and moved elsewhere like
194 :file:`IPython.python`.
194 :file:`IPython.python`.
195
195
196 * :file:`UserConfig`. Move to a subdirectory of :file:`IPython.config`.
196 * :file:`UserConfig`. Move to a subdirectory of :file:`IPython.config`.
197
197
198
198
199
199
200
200
201 * :file:`config`. Good where it is!
201 * :file:`config`. Good where it is!
202
202
203 * :file:`external`. Good where it is!
203 * :file:`external`. Good where it is!
204
204
205 * :file:`frontend`. Good where it is!
205 * :file:`frontend`. Good where it is!
206
206
207
207
208
208
209 * :file:`gui`. Eventually this should be moved to a subdir of
209 * :file:`gui`. Eventually this should be moved to a subdir of
210 :file:`IPython.frontend`.
210 :file:`IPython.frontend`.
211
211
212
212
213
213
214
214
215
215
216
216
217
217
218
218
219
219
220
220
221
221
222 * :file:`kernel`. Good where it is.
222 * :file:`kernel`. Good where it is.
223
223
224
224
225
225
226
226
227
227
228
228
229
229
230
230
231
231
232
232
233
233
234
234
235
235
236
236
237
237
238 * :file:`twshell.py`. Move to :file:`IPython.sandbox`.
238 * :file:`twshell.py`. Move to :file:`IPython.sandbox`.
239
239
240 * :file:`ultraTB.py`. Move to :file:`IPython/core/ultratb.py`.
240 * :file:`ultraTB.py`. Move to :file:`IPython/core/ultratb.py`.
241
241
242 * :file:`upgrade_dir.py`. Move to :file:`IPython/python/upgradedir.py`.
242 * :file:`upgrade_dir.py`. Move to :file:`IPython/utils/upgradedir.py`.
243
243
244 * :file:`usage.py`. Move to :file:`IPython.core`.
244 * :file:`usage.py`. Move to :file:`IPython.core`.
245
245
246 * :file:`wildcard.py`. Move to :file:`IPython.python` or :file:`IPython.core`.
246 * :file:`wildcard.py`. Move to :file:`IPython.utils`.
247
247
248 * :file:`winconsole.py`. Move to :file:`IPython.lib`.
248 * :file:`winconsole.py`. Move to :file:`IPython.lib`.
249
249
250 Other things
250 Other things
251 ============
251 ============
252
252
253 When these files are moved around, a number of other things will happen at the same time:
253 When these files are moved around, a number of other things will happen at the same time:
254
254
255 1. Test files will be created for each module in IPython. Minimally, all
255 1. Test files will be created for each module in IPython. Minimally, all
256 modules will be imported as a part of the test. This will serve as a
256 modules will be imported as a part of the test. This will serve as a
257 test of the module reorganization. These tests will be put into new
257 test of the module reorganization. These tests will be put into new
258 :file:`tests` subdirectories that each package will have.
258 :file:`tests` subdirectories that each package will have.
259
259
260 2. PyFlakes and other code checkers will be run to look for problems.
260 2. PyFlakes and other code checkers will be run to look for problems.
261
261
262 3. Modules will be renamed to comply with PEP 8 naming conventions: all
262 3. Modules will be renamed to comply with PEP 8 naming conventions: all
263 lowercase and no special characters like ``-`` or ``_``.
263 lowercase and no special characters like ``-`` or ``_``.
264
264
265 4. Existing tests will be moved to the appropriate :file:`tests`
265 4. Existing tests will be moved to the appropriate :file:`tests`
266 subdirectories.
266 subdirectories.
267
267
268
268
269
269
270
270
General Comments 0
You need to be logged in to leave comments. Login now