##// END OF EJS Templates
New system for interactively running scripts. After a submission by Ken...
fperez -
Show More

The requested changes are too big and content was truncated. Show full diff

@@ -0,0 +1,276 b''
1 #!/usr/bin/env python
2 """Module for interactively running scripts.
3
4 This module implements classes for interactively running scripts written for
5 any system with a prompt which can be matched by a regexp suitable for
6 pexpect. It can be used to run as if they had been typed up interactively, an
7 arbitrary series of commands for the target system.
8
9 The module includes classes ready for IPython (with the default prompts),
10 plain Python and SAGE, but making a new one is trivial. To see how to use it,
11 simply run the module as a script:
12
13 ./irunner.py --help
14
15
16 This is an extension of Ken Schutte <kschutte-AT-csail.mit.edu>'s script
17 contributed on the ipython-user list:
18
19 http://scipy.net/pipermail/ipython-user/2006-May/001705.html
20
21
22 NOTES:
23
24 - This module requires pexpect, available in most linux distros, or which can
25 be downloaded from
26
27 http://pexpect.sourceforge.net
28
29 - Because pexpect only works under Unix or Windows-Cygwin, this has the same
30 limitations. This means that it will NOT work under native windows Python.
31 """
32
33 # Stdlib imports
34 import optparse
35 import sys
36
37 # Third-party modules.
38 import pexpect
39
40 # Global usage strings, to avoid indentation issues when typing it below.
41 USAGE = """
42 Interactive script runner, type: %s
43
44 runner [opts] script_name
45 """
46
47 # The generic runner class
48 class InteractiveRunner(object):
49 """Class to run a sequence of commands through an interactive program."""
50
51 def __init__(self,program,prompts,args=None):
52 """Construct a runner.
53
54 Inputs:
55
56 - program: command to execute the given program.
57
58 - prompts: a list of patterns to match as valid prompts, in the
59 format used by pexpect. This basically means that it can be either
60 a string (to be compiled as a regular expression) or a list of such
61 (it must be a true list, as pexpect does type checks).
62
63 If more than one prompt is given, the first is treated as the main
64 program prompt and the others as 'continuation' prompts, like
65 python's. This means that blank lines in the input source are
66 ommitted when the first prompt is matched, but are NOT ommitted when
67 the continuation one matches, since this is how python signals the
68 end of multiline input interactively.
69
70 Optional inputs:
71
72 - args(None): optional list of strings to pass as arguments to the
73 child program.
74 """
75
76 self.program = program
77 self.prompts = prompts
78 if args is None: args = []
79 self.args = args
80
81 def run_file(self,fname,interact=False):
82 """Run the given file interactively.
83
84 Inputs:
85
86 -fname: name of the file to execute.
87
88 See the run_source docstring for the meaning of the optional
89 arguments."""
90
91 fobj = open(fname,'r')
92 try:
93 self.run_source(fobj,interact)
94 finally:
95 fobj.close()
96
97 def run_source(self,source,interact=False):
98 """Run the given source code interactively.
99
100 Inputs:
101
102 - source: a string of code to be executed, or an open file object we
103 can iterate over.
104
105 Optional inputs:
106
107 - interact(False): if true, start to interact with the running
108 program at the end of the script. Otherwise, just exit.
109 """
110
111 # if the source is a string, chop it up in lines so we can iterate
112 # over it just as if it were an open file.
113 if not isinstance(source,file):
114 source = source.splitlines(True)
115
116 # grab the true write method of stdout, in case anything later
117 # reassigns sys.stdout, so that we really are writing to the true
118 # stdout and not to something else.
119 write = sys.stdout.write
120
121 c = pexpect.spawn(self.program,self.args,timeout=None)
122
123 prompts = c.compile_pattern_list(self.prompts[0])
124 prompts = c.compile_pattern_list(self.prompts)
125
126 prompt_idx = c.expect_list(prompts)
127 # Flag whether the script ends normally or not, to know whether we can
128 # do anything further with the underlying process.
129 end_normal = True
130 for cmd in source:
131 # skip blank lines for all matches to the 'main' prompt, while the
132 # secondary prompts do not
133 if prompt_idx==0 and cmd.isspace():
134 continue
135
136 write(c.after)
137 c.send(cmd)
138 try:
139 prompt_idx = c.expect_list(prompts)
140 except pexpect.EOF:
141 # this will happen if the child dies unexpectedly
142 write(c.before)
143 end_normal = False
144 break
145 write(c.before)
146
147 if isinstance(source,file):
148 source.close()
149
150 if end_normal:
151 if interact:
152 c.send('\n')
153 print '<< Starting interactive mode >>',
154 try:
155 c.interact()
156 except OSError:
157 # This is what fires when the child stops. Simply print a
158 # newline so the system prompt is alingned. The extra
159 # space is there to make sure it gets printed, otherwise
160 # OS buffering sometimes just suppresses it.
161 write(' \n')
162 sys.stdout.flush()
163 else:
164 c.close()
165 else:
166 if interact:
167 e="Further interaction is not possible: child process is dead."
168 print >> sys.stderr, e
169
170 def main(self,argv=None):
171 """Run as a command-line script."""
172
173 parser = optparse.OptionParser(usage=USAGE % self.__class__.__name__)
174 newopt = parser.add_option
175 newopt('-i','--interact',action='store_true',default=False,
176 help='Interact with the program after the script is run.')
177
178 opts,args = parser.parse_args(argv)
179
180 if len(args) != 1:
181 print >> sys.stderr,"You must supply exactly one file to run."
182 sys.exit(1)
183
184 self.run_file(args[0],opts.interact)
185
186
187 # Specific runners for particular programs
188 class IPythonRunner(InteractiveRunner):
189 """Interactive IPython runner.
190
191 This initalizes IPython in 'nocolor' mode for simplicity. This lets us
192 avoid having to write a regexp that matches ANSI sequences, though pexpect
193 does support them. If anyone contributes patches for ANSI color support,
194 they will be welcome.
195
196 It also sets the prompts manually, since the prompt regexps for
197 pexpect need to be matched to the actual prompts, so user-customized
198 prompts would break this.
199 """
200
201 def __init__(self,program = 'ipython',args=None):
202 """New runner, optionally passing the ipython command to use."""
203
204 args0 = ['-colors','NoColor',
205 '-pi1','In [\\#]: ',
206 '-pi2',' .\\D.: ']
207 if args is None: args = args0
208 else: args = args0 + args
209 prompts = [r'In \[\d+\]: ',r' \.*: ']
210 InteractiveRunner.__init__(self,program,prompts,args)
211
212
213 class PythonRunner(InteractiveRunner):
214 """Interactive Python runner."""
215
216 def __init__(self,program='python',args=None):
217 """New runner, optionally passing the python command to use."""
218
219 prompts = [r'>>> ',r'\.\.\. ']
220 InteractiveRunner.__init__(self,program,prompts,args)
221
222
223 class SAGERunner(InteractiveRunner):
224 """Interactive SAGE runner.
225
226 XXX - This class is currently untested, meant for feedback from the SAGE
227 team. """
228
229 def __init__(self,program='sage',args=None):
230 """New runner, optionally passing the sage command to use."""
231 print 'XXX - This class is currently untested!!!'
232 print 'It is a placeholder, meant for feedback from the SAGE team.'
233
234 prompts = ['sage: ',r'\s*\.\.\. ']
235 InteractiveRunner.__init__(self,program,prompts,args)
236
237 # Global usage string, to avoid indentation issues if typed in a function def.
238 MAIN_USAGE = """
239 %prog [options] file_to_run
240
241 This is an interface to the various interactive runners available in this
242 module. If you want to pass specific options to one of the runners, you need
243 to first terminate the main options with a '--', and then provide the runner's
244 options. For example:
245
246 irunner.py --python -- --help
247
248 will pass --help to the python runner. Similarly,
249
250 irunner.py --ipython -- --log test.log script.ipy
251
252 will run the script.ipy file under the IPython runner, logging all output into
253 the test.log file.
254 """
255
256 def main():
257 """Run as a command-line script."""
258
259 parser = optparse.OptionParser(usage=MAIN_USAGE)
260 newopt = parser.add_option
261 parser.set_defaults(mode='ipython')
262 newopt('--ipython',action='store_const',dest='mode',const='ipython',
263 help='IPython interactive runner (default).')
264 newopt('--python',action='store_const',dest='mode',const='python',
265 help='Python interactive runner.')
266 newopt('--sage',action='store_const',dest='mode',const='sage',
267 help='SAGE interactive runner - UNTESTED.')
268
269 opts,args = parser.parse_args()
270 runners = dict(ipython=IPythonRunner,
271 python=PythonRunner,
272 sage=SAGERunner)
273 runners[opts.mode]().main(args)
274
275 if __name__ == '__main__':
276 main()
1 NO CONTENT: new file 100755
The requested commit or file is too big and content was truncated. Show full diff
@@ -1,2300 +1,2299 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 IPython -- An enhanced Interactive Python
4 4
5 5 Requires Python 2.3 or newer.
6 6
7 7 This file contains all the classes and helper functions specific to IPython.
8 8
9 $Id: iplib.py 1329 2006-05-26 07:52:45Z fperez $
9 $Id: iplib.py 1332 2006-05-30 01:41:28Z fperez $
10 10 """
11 11
12 12 #*****************************************************************************
13 13 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
14 14 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
15 15 #
16 16 # Distributed under the terms of the BSD License. The full license is in
17 17 # the file COPYING, distributed as part of this software.
18 18 #
19 19 # Note: this code originally subclassed code.InteractiveConsole from the
20 20 # Python standard library. Over time, all of that class has been copied
21 21 # verbatim here for modifications which could not be accomplished by
22 22 # subclassing. At this point, there are no dependencies at all on the code
23 23 # module anymore (it is not even imported). The Python License (sec. 2)
24 24 # allows for this, but it's always nice to acknowledge credit where credit is
25 25 # due.
26 26 #*****************************************************************************
27 27
28 28 #****************************************************************************
29 29 # Modules and globals
30 30
31 31 from IPython import Release
32 32 __author__ = '%s <%s>\n%s <%s>' % \
33 33 ( Release.authors['Janko'] + Release.authors['Fernando'] )
34 34 __license__ = Release.license
35 35 __version__ = Release.version
36 36
37 37 # Python standard modules
38 38 import __main__
39 39 import __builtin__
40 40 import StringIO
41 41 import bdb
42 42 import cPickle as pickle
43 43 import codeop
44 44 import exceptions
45 45 import glob
46 46 import inspect
47 47 import keyword
48 48 import new
49 49 import os
50 50 import pdb
51 51 import pydoc
52 52 import re
53 53 import shutil
54 54 import string
55 55 import sys
56 56 import tempfile
57 57 import traceback
58 58 import types
59 59 import pickleshare
60 60
61 61 from pprint import pprint, pformat
62 62
63 63 # IPython's own modules
64 64 import IPython
65 65 from IPython import OInspect,PyColorize,ultraTB
66 66 from IPython.ColorANSI import ColorScheme,ColorSchemeTable # too long names
67 67 from IPython.FakeModule import FakeModule
68 68 from IPython.Itpl import Itpl,itpl,printpl,ItplNS,itplns
69 69 from IPython.Logger import Logger
70 70 from IPython.Magic import Magic
71 71 from IPython.Prompts import CachedOutput
72 72 from IPython.ipstruct import Struct
73 73 from IPython.background_jobs import BackgroundJobManager
74 74 from IPython.usage import cmd_line_usage,interactive_usage
75 75 from IPython.genutils import *
76 76 import IPython.ipapi
77 77
78 78 # Globals
79 79
80 80 # store the builtin raw_input globally, and use this always, in case user code
81 81 # overwrites it (like wx.py.PyShell does)
82 82 raw_input_original = raw_input
83 83
84 84 # compiled regexps for autoindent management
85 85 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
86 86
87 87
88 88 #****************************************************************************
89 89 # Some utility function definitions
90 90
91 91 ini_spaces_re = re.compile(r'^(\s+)')
92 92
93 93 def num_ini_spaces(strng):
94 94 """Return the number of initial spaces in a string"""
95 95
96 96 ini_spaces = ini_spaces_re.match(strng)
97 97 if ini_spaces:
98 98 return ini_spaces.end()
99 99 else:
100 100 return 0
101 101
102 102 def softspace(file, newvalue):
103 103 """Copied from code.py, to remove the dependency"""
104 104
105 105 oldvalue = 0
106 106 try:
107 107 oldvalue = file.softspace
108 108 except AttributeError:
109 109 pass
110 110 try:
111 111 file.softspace = newvalue
112 112 except (AttributeError, TypeError):
113 113 # "attribute-less object" or "read-only attributes"
114 114 pass
115 115 return oldvalue
116 116
117 117
118 118 #****************************************************************************
119 119 # Local use exceptions
120 120 class SpaceInInput(exceptions.Exception): pass
121 121
122 122
123 123 #****************************************************************************
124 124 # Local use classes
125 125 class Bunch: pass
126 126
127 127 class Undefined: pass
128 128
129 129 class InputList(list):
130 130 """Class to store user input.
131 131
132 132 It's basically a list, but slices return a string instead of a list, thus
133 133 allowing things like (assuming 'In' is an instance):
134 134
135 135 exec In[4:7]
136 136
137 137 or
138 138
139 139 exec In[5:9] + In[14] + In[21:25]"""
140 140
141 141 def __getslice__(self,i,j):
142 142 return ''.join(list.__getslice__(self,i,j))
143 143
144 144 class SyntaxTB(ultraTB.ListTB):
145 145 """Extension which holds some state: the last exception value"""
146 146
147 147 def __init__(self,color_scheme = 'NoColor'):
148 148 ultraTB.ListTB.__init__(self,color_scheme)
149 149 self.last_syntax_error = None
150 150
151 151 def __call__(self, etype, value, elist):
152 152 self.last_syntax_error = value
153 153 ultraTB.ListTB.__call__(self,etype,value,elist)
154 154
155 155 def clear_err_state(self):
156 156 """Return the current error state and clear it"""
157 157 e = self.last_syntax_error
158 158 self.last_syntax_error = None
159 159 return e
160 160
161 161 #****************************************************************************
162 162 # Main IPython class
163 163
164 164 # FIXME: the Magic class is a mixin for now, and will unfortunately remain so
165 165 # until a full rewrite is made. I've cleaned all cross-class uses of
166 166 # attributes and methods, but too much user code out there relies on the
167 167 # equlity %foo == __IP.magic_foo, so I can't actually remove the mixin usage.
168 168 #
169 169 # But at least now, all the pieces have been separated and we could, in
170 170 # principle, stop using the mixin. This will ease the transition to the
171 171 # chainsaw branch.
172 172
173 173 # For reference, the following is the list of 'self.foo' uses in the Magic
174 174 # class as of 2005-12-28. These are names we CAN'T use in the main ipython
175 175 # class, to prevent clashes.
176 176
177 177 # ['self.__class__', 'self.__dict__', 'self._inspect', 'self._ofind',
178 178 # 'self.arg_err', 'self.extract_input', 'self.format_', 'self.lsmagic',
179 179 # 'self.magic_', 'self.options_table', 'self.parse', 'self.shell',
180 180 # 'self.value']
181 181
182 182 class InteractiveShell(object,Magic):
183 183 """An enhanced console for Python."""
184 184
185 185 # class attribute to indicate whether the class supports threads or not.
186 186 # Subclasses with thread support should override this as needed.
187 187 isthreaded = False
188 188
189 189 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
190 190 user_ns = None,user_global_ns=None,banner2='',
191 191 custom_exceptions=((),None),embedded=False):
192 192
193
194 193 # log system
195 194 self.logger = Logger(self,logfname='ipython_log.py',logmode='rotate')
196 195
197 196 # some minimal strict typechecks. For some core data structures, I
198 197 # want actual basic python types, not just anything that looks like
199 198 # one. This is especially true for namespaces.
200 199 for ns in (user_ns,user_global_ns):
201 200 if ns is not None and type(ns) != types.DictType:
202 201 raise TypeError,'namespace must be a dictionary'
203 202
204 203 # Job manager (for jobs run as background threads)
205 204 self.jobs = BackgroundJobManager()
206 205
207 206 # Store the actual shell's name
208 207 self.name = name
209 208
210 209 # We need to know whether the instance is meant for embedding, since
211 210 # global/local namespaces need to be handled differently in that case
212 211 self.embedded = embedded
213 212
214 213 # command compiler
215 214 self.compile = codeop.CommandCompiler()
216 215
217 216 # User input buffer
218 217 self.buffer = []
219 218
220 219 # Default name given in compilation of code
221 220 self.filename = '<ipython console>'
222 221
223 222 # Make an empty namespace, which extension writers can rely on both
224 223 # existing and NEVER being used by ipython itself. This gives them a
225 224 # convenient location for storing additional information and state
226 225 # their extensions may require, without fear of collisions with other
227 226 # ipython names that may develop later.
228 227 self.meta = Struct()
229 228
230 229 # Create the namespace where the user will operate. user_ns is
231 230 # normally the only one used, and it is passed to the exec calls as
232 231 # the locals argument. But we do carry a user_global_ns namespace
233 232 # given as the exec 'globals' argument, This is useful in embedding
234 233 # situations where the ipython shell opens in a context where the
235 234 # distinction between locals and globals is meaningful.
236 235
237 236 # FIXME. For some strange reason, __builtins__ is showing up at user
238 237 # level as a dict instead of a module. This is a manual fix, but I
239 238 # should really track down where the problem is coming from. Alex
240 239 # Schmolck reported this problem first.
241 240
242 241 # A useful post by Alex Martelli on this topic:
243 242 # Re: inconsistent value from __builtins__
244 243 # Von: Alex Martelli <aleaxit@yahoo.com>
245 244 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
246 245 # Gruppen: comp.lang.python
247 246
248 247 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
249 248 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
250 249 # > <type 'dict'>
251 250 # > >>> print type(__builtins__)
252 251 # > <type 'module'>
253 252 # > Is this difference in return value intentional?
254 253
255 254 # Well, it's documented that '__builtins__' can be either a dictionary
256 255 # or a module, and it's been that way for a long time. Whether it's
257 256 # intentional (or sensible), I don't know. In any case, the idea is
258 257 # that if you need to access the built-in namespace directly, you
259 258 # should start with "import __builtin__" (note, no 's') which will
260 259 # definitely give you a module. Yeah, it's somewhat confusing:-(.
261 260
262 261 # These routines return properly built dicts as needed by the rest of
263 262 # the code, and can also be used by extension writers to generate
264 263 # properly initialized namespaces.
265 264 user_ns = IPython.ipapi.make_user_ns(user_ns)
266 265 user_global_ns = IPython.ipapi.make_user_global_ns(user_global_ns)
267 266
268 267 # Assign namespaces
269 268 # This is the namespace where all normal user variables live
270 269 self.user_ns = user_ns
271 270 # Embedded instances require a separate namespace for globals.
272 271 # Normally this one is unused by non-embedded instances.
273 272 self.user_global_ns = user_global_ns
274 273 # A namespace to keep track of internal data structures to prevent
275 274 # them from cluttering user-visible stuff. Will be updated later
276 275 self.internal_ns = {}
277 276
278 277 # Namespace of system aliases. Each entry in the alias
279 278 # table must be a 2-tuple of the form (N,name), where N is the number
280 279 # of positional arguments of the alias.
281 280 self.alias_table = {}
282 281
283 282 # A table holding all the namespaces IPython deals with, so that
284 283 # introspection facilities can search easily.
285 284 self.ns_table = {'user':user_ns,
286 285 'user_global':user_global_ns,
287 286 'alias':self.alias_table,
288 287 'internal':self.internal_ns,
289 288 'builtin':__builtin__.__dict__
290 289 }
291 290
292 291 # The user namespace MUST have a pointer to the shell itself.
293 292 self.user_ns[name] = self
294 293
295 294 # We need to insert into sys.modules something that looks like a
296 295 # module but which accesses the IPython namespace, for shelve and
297 296 # pickle to work interactively. Normally they rely on getting
298 297 # everything out of __main__, but for embedding purposes each IPython
299 298 # instance has its own private namespace, so we can't go shoving
300 299 # everything into __main__.
301 300
302 301 # note, however, that we should only do this for non-embedded
303 302 # ipythons, which really mimic the __main__.__dict__ with their own
304 303 # namespace. Embedded instances, on the other hand, should not do
305 304 # this because they need to manage the user local/global namespaces
306 305 # only, but they live within a 'normal' __main__ (meaning, they
307 306 # shouldn't overtake the execution environment of the script they're
308 307 # embedded in).
309 308
310 309 if not embedded:
311 310 try:
312 311 main_name = self.user_ns['__name__']
313 312 except KeyError:
314 313 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
315 314 else:
316 315 #print "pickle hack in place" # dbg
317 316 #print 'main_name:',main_name # dbg
318 317 sys.modules[main_name] = FakeModule(self.user_ns)
319 318
320 319 # List of input with multi-line handling.
321 320 # Fill its zero entry, user counter starts at 1
322 321 self.input_hist = InputList(['\n'])
323 322 # This one will hold the 'raw' input history, without any
324 323 # pre-processing. This will allow users to retrieve the input just as
325 324 # it was exactly typed in by the user, with %hist -r.
326 325 self.input_hist_raw = InputList(['\n'])
327 326
328 327 # list of visited directories
329 328 try:
330 329 self.dir_hist = [os.getcwd()]
331 330 except IOError, e:
332 331 self.dir_hist = []
333 332
334 333 # dict of output history
335 334 self.output_hist = {}
336 335
337 336 # dict of things NOT to alias (keywords, builtins and some magics)
338 337 no_alias = {}
339 338 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
340 339 for key in keyword.kwlist + no_alias_magics:
341 340 no_alias[key] = 1
342 341 no_alias.update(__builtin__.__dict__)
343 342 self.no_alias = no_alias
344 343
345 344 # make global variables for user access to these
346 345 self.user_ns['_ih'] = self.input_hist
347 346 self.user_ns['_oh'] = self.output_hist
348 347 self.user_ns['_dh'] = self.dir_hist
349 348
350 349 # user aliases to input and output histories
351 350 self.user_ns['In'] = self.input_hist
352 351 self.user_ns['Out'] = self.output_hist
353 352
354 353 # Object variable to store code object waiting execution. This is
355 354 # used mainly by the multithreaded shells, but it can come in handy in
356 355 # other situations. No need to use a Queue here, since it's a single
357 356 # item which gets cleared once run.
358 357 self.code_to_run = None
359 358
360 359 # escapes for automatic behavior on the command line
361 360 self.ESC_SHELL = '!'
362 361 self.ESC_HELP = '?'
363 362 self.ESC_MAGIC = '%'
364 363 self.ESC_QUOTE = ','
365 364 self.ESC_QUOTE2 = ';'
366 365 self.ESC_PAREN = '/'
367 366
368 367 # And their associated handlers
369 368 self.esc_handlers = {self.ESC_PAREN : self.handle_auto,
370 369 self.ESC_QUOTE : self.handle_auto,
371 370 self.ESC_QUOTE2 : self.handle_auto,
372 371 self.ESC_MAGIC : self.handle_magic,
373 372 self.ESC_HELP : self.handle_help,
374 373 self.ESC_SHELL : self.handle_shell_escape,
375 374 }
376 375
377 376 # class initializations
378 377 Magic.__init__(self,self)
379 378
380 379 # Python source parser/formatter for syntax highlighting
381 380 pyformat = PyColorize.Parser().format
382 381 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
383 382
384 383 # hooks holds pointers used for user-side customizations
385 384 self.hooks = Struct()
386 385
387 386 # Set all default hooks, defined in the IPython.hooks module.
388 387 hooks = IPython.hooks
389 388 for hook_name in hooks.__all__:
390 389 # default hooks have priority 100, i.e. low; user hooks should have 0-100 priority
391 390 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
392 391 #print "bound hook",hook_name
393 392
394 393 # Flag to mark unconditional exit
395 394 self.exit_now = False
396 395
397 396 self.usage_min = """\
398 397 An enhanced console for Python.
399 398 Some of its features are:
400 399 - Readline support if the readline library is present.
401 400 - Tab completion in the local namespace.
402 401 - Logging of input, see command-line options.
403 402 - System shell escape via ! , eg !ls.
404 403 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
405 404 - Keeps track of locally defined variables via %who, %whos.
406 405 - Show object information with a ? eg ?x or x? (use ?? for more info).
407 406 """
408 407 if usage: self.usage = usage
409 408 else: self.usage = self.usage_min
410 409
411 410 # Storage
412 411 self.rc = rc # This will hold all configuration information
413 412 self.pager = 'less'
414 413 # temporary files used for various purposes. Deleted at exit.
415 414 self.tempfiles = []
416 415
417 416 # Keep track of readline usage (later set by init_readline)
418 417 self.has_readline = False
419 418
420 419 # template for logfile headers. It gets resolved at runtime by the
421 420 # logstart method.
422 421 self.loghead_tpl = \
423 422 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
424 423 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
425 424 #log# opts = %s
426 425 #log# args = %s
427 426 #log# It is safe to make manual edits below here.
428 427 #log#-----------------------------------------------------------------------
429 428 """
430 429 # for pushd/popd management
431 430 try:
432 431 self.home_dir = get_home_dir()
433 432 except HomeDirError,msg:
434 433 fatal(msg)
435 434
436 435 self.dir_stack = [os.getcwd().replace(self.home_dir,'~')]
437 436
438 437 # Functions to call the underlying shell.
439 438
440 439 # utility to expand user variables via Itpl
441 440 self.var_expand = lambda cmd: str(ItplNS(cmd.replace('#','\#'),
442 441 self.user_ns))
443 442 # The first is similar to os.system, but it doesn't return a value,
444 443 # and it allows interpolation of variables in the user's namespace.
445 444 self.system = lambda cmd: shell(self.var_expand(cmd),
446 445 header='IPython system call: ',
447 446 verbose=self.rc.system_verbose)
448 447 # These are for getoutput and getoutputerror:
449 448 self.getoutput = lambda cmd: \
450 449 getoutput(self.var_expand(cmd),
451 450 header='IPython system call: ',
452 451 verbose=self.rc.system_verbose)
453 452 self.getoutputerror = lambda cmd: \
454 453 getoutputerror(str(ItplNS(cmd.replace('#','\#'),
455 454 self.user_ns)),
456 455 header='IPython system call: ',
457 456 verbose=self.rc.system_verbose)
458 457
459 458 # RegExp for splitting line contents into pre-char//first
460 459 # word-method//rest. For clarity, each group in on one line.
461 460
462 461 # WARNING: update the regexp if the above escapes are changed, as they
463 462 # are hardwired in.
464 463
465 464 # Don't get carried away with trying to make the autocalling catch too
466 465 # much: it's better to be conservative rather than to trigger hidden
467 466 # evals() somewhere and end up causing side effects.
468 467
469 468 self.line_split = re.compile(r'^([\s*,;/])'
470 469 r'([\?\w\.]+\w*\s*)'
471 470 r'(\(?.*$)')
472 471
473 472 # Original re, keep around for a while in case changes break something
474 473 #self.line_split = re.compile(r'(^[\s*!\?%,/]?)'
475 474 # r'(\s*[\?\w\.]+\w*\s*)'
476 475 # r'(\(?.*$)')
477 476
478 477 # RegExp to identify potential function names
479 478 self.re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
480 479
481 480 # RegExp to exclude strings with this start from autocalling. In
482 481 # particular, all binary operators should be excluded, so that if foo
483 482 # is callable, foo OP bar doesn't become foo(OP bar), which is
484 483 # invalid. The characters '!=()' don't need to be checked for, as the
485 484 # _prefilter routine explicitely does so, to catch direct calls and
486 485 # rebindings of existing names.
487 486
488 487 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
489 488 # it affects the rest of the group in square brackets.
490 489 self.re_exclude_auto = re.compile(r'^[<>,&^\|\*/\+-]'
491 490 '|^is |^not |^in |^and |^or ')
492 491
493 492 # try to catch also methods for stuff in lists/tuples/dicts: off
494 493 # (experimental). For this to work, the line_split regexp would need
495 494 # to be modified so it wouldn't break things at '['. That line is
496 495 # nasty enough that I shouldn't change it until I can test it _well_.
497 496 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
498 497
499 498 # keep track of where we started running (mainly for crash post-mortem)
500 499 self.starting_dir = os.getcwd()
501 500
502 501 # Various switches which can be set
503 502 self.CACHELENGTH = 5000 # this is cheap, it's just text
504 503 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
505 504 self.banner2 = banner2
506 505
507 506 # TraceBack handlers:
508 507
509 508 # Syntax error handler.
510 509 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
511 510
512 511 # The interactive one is initialized with an offset, meaning we always
513 512 # want to remove the topmost item in the traceback, which is our own
514 513 # internal code. Valid modes: ['Plain','Context','Verbose']
515 514 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
516 515 color_scheme='NoColor',
517 516 tb_offset = 1)
518 517
519 518 # IPython itself shouldn't crash. This will produce a detailed
520 519 # post-mortem if it does. But we only install the crash handler for
521 520 # non-threaded shells, the threaded ones use a normal verbose reporter
522 521 # and lose the crash handler. This is because exceptions in the main
523 522 # thread (such as in GUI code) propagate directly to sys.excepthook,
524 523 # and there's no point in printing crash dumps for every user exception.
525 524 if self.isthreaded:
526 525 sys.excepthook = ultraTB.FormattedTB()
527 526 else:
528 527 from IPython import CrashHandler
529 528 sys.excepthook = CrashHandler.CrashHandler(self)
530 529
531 530 # The instance will store a pointer to this, so that runtime code
532 531 # (such as magics) can access it. This is because during the
533 532 # read-eval loop, it gets temporarily overwritten (to deal with GUI
534 533 # frameworks).
535 534 self.sys_excepthook = sys.excepthook
536 535
537 536 # and add any custom exception handlers the user may have specified
538 537 self.set_custom_exc(*custom_exceptions)
539 538
540 539 # indentation management
541 540 self.autoindent = False
542 541 self.indent_current_nsp = 0
543 542
544 543 # Make some aliases automatically
545 544 # Prepare list of shell aliases to auto-define
546 545 if os.name == 'posix':
547 546 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
548 547 'mv mv -i','rm rm -i','cp cp -i',
549 548 'cat cat','less less','clear clear',
550 549 # a better ls
551 550 'ls ls -F',
552 551 # long ls
553 552 'll ls -lF',
554 553 # color ls
555 554 'lc ls -F -o --color',
556 555 # ls normal files only
557 556 'lf ls -F -o --color %l | grep ^-',
558 557 # ls symbolic links
559 558 'lk ls -F -o --color %l | grep ^l',
560 559 # directories or links to directories,
561 560 'ldir ls -F -o --color %l | grep /$',
562 561 # things which are executable
563 562 'lx ls -F -o --color %l | grep ^-..x',
564 563 )
565 564 elif os.name in ['nt','dos']:
566 565 auto_alias = ('dir dir /on', 'ls dir /on',
567 566 'ddir dir /ad /on', 'ldir dir /ad /on',
568 567 'mkdir mkdir','rmdir rmdir','echo echo',
569 568 'ren ren','cls cls','copy copy')
570 569 else:
571 570 auto_alias = ()
572 571 self.auto_alias = map(lambda s:s.split(None,1),auto_alias)
573 572 # Call the actual (public) initializer
574 573 self.init_auto_alias()
575 574
576 575 # Produce a public API instance
577 576 self.api = IPython.ipapi.IPApi(self)
578 577
579 578 # track which builtins we add, so we can clean up later
580 579 self.builtins_added = {}
581 580 # This method will add the necessary builtins for operation, but
582 581 # tracking what it did via the builtins_added dict.
583 582 self.add_builtins()
584 583
585 584 # end __init__
586 585
587 586 def pre_config_initialization(self):
588 587 """Pre-configuration init method
589 588
590 589 This is called before the configuration files are processed to
591 590 prepare the services the config files might need.
592 591
593 592 self.rc already has reasonable default values at this point.
594 593 """
595 594 rc = self.rc
596 595
597 596 self.db = pickleshare.PickleShareDB(rc.ipythondir + "/db")
598 597
599 598 def post_config_initialization(self):
600 599 """Post configuration init method
601 600
602 601 This is called after the configuration files have been processed to
603 602 'finalize' the initialization."""
604 603
605 604 rc = self.rc
606 605
607 606 # Object inspector
608 607 self.inspector = OInspect.Inspector(OInspect.InspectColors,
609 608 PyColorize.ANSICodeColors,
610 609 'NoColor',
611 610 rc.object_info_string_level)
612 611
613 612 # Load readline proper
614 613 if rc.readline:
615 614 self.init_readline()
616 615
617 616 # local shortcut, this is used a LOT
618 617 self.log = self.logger.log
619 618
620 619 # Initialize cache, set in/out prompts and printing system
621 620 self.outputcache = CachedOutput(self,
622 621 rc.cache_size,
623 622 rc.pprint,
624 623 input_sep = rc.separate_in,
625 624 output_sep = rc.separate_out,
626 625 output_sep2 = rc.separate_out2,
627 626 ps1 = rc.prompt_in1,
628 627 ps2 = rc.prompt_in2,
629 628 ps_out = rc.prompt_out,
630 629 pad_left = rc.prompts_pad_left)
631 630
632 631 # user may have over-ridden the default print hook:
633 632 try:
634 633 self.outputcache.__class__.display = self.hooks.display
635 634 except AttributeError:
636 635 pass
637 636
638 637 # I don't like assigning globally to sys, because it means when embedding
639 638 # instances, each embedded instance overrides the previous choice. But
640 639 # sys.displayhook seems to be called internally by exec, so I don't see a
641 640 # way around it.
642 641 sys.displayhook = self.outputcache
643 642
644 643 # Set user colors (don't do it in the constructor above so that it
645 644 # doesn't crash if colors option is invalid)
646 645 self.magic_colors(rc.colors)
647 646
648 647 # Set calling of pdb on exceptions
649 648 self.call_pdb = rc.pdb
650 649
651 650 # Load user aliases
652 651 for alias in rc.alias:
653 652 self.magic_alias(alias)
654 653 self.hooks.late_startup_hook()
655 654
656 655 for batchfile in [path(arg) for arg in self.rc.args
657 656 if arg.lower().endswith('.ipy')]:
658 657 if not batchfile.isfile():
659 658 print "No such batch file:", batchfile
660 659 continue
661 660 self.api.runlines(batchfile.text())
662 661
663 662 def add_builtins(self):
664 663 """Store ipython references into the builtin namespace.
665 664
666 665 Some parts of ipython operate via builtins injected here, which hold a
667 666 reference to IPython itself."""
668 667
669 668 # TODO: deprecate all except _ip; 'jobs' should be installed
670 669 # by an extension and the rest are under _ip, ipalias is redundant
671 670 builtins_new = dict(__IPYTHON__ = self,
672 671 ip_set_hook = self.set_hook,
673 672 jobs = self.jobs,
674 673 ipmagic = self.ipmagic,
675 674 ipalias = self.ipalias,
676 675 ipsystem = self.ipsystem,
677 676 _ip = self.api
678 677 )
679 678 for biname,bival in builtins_new.items():
680 679 try:
681 680 # store the orignal value so we can restore it
682 681 self.builtins_added[biname] = __builtin__.__dict__[biname]
683 682 except KeyError:
684 683 # or mark that it wasn't defined, and we'll just delete it at
685 684 # cleanup
686 685 self.builtins_added[biname] = Undefined
687 686 __builtin__.__dict__[biname] = bival
688 687
689 688 # Keep in the builtins a flag for when IPython is active. We set it
690 689 # with setdefault so that multiple nested IPythons don't clobber one
691 690 # another. Each will increase its value by one upon being activated,
692 691 # which also gives us a way to determine the nesting level.
693 692 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
694 693
695 694 def clean_builtins(self):
696 695 """Remove any builtins which might have been added by add_builtins, or
697 696 restore overwritten ones to their previous values."""
698 697 for biname,bival in self.builtins_added.items():
699 698 if bival is Undefined:
700 699 del __builtin__.__dict__[biname]
701 700 else:
702 701 __builtin__.__dict__[biname] = bival
703 702 self.builtins_added.clear()
704 703
705 704 def set_hook(self,name,hook, priority = 50):
706 705 """set_hook(name,hook) -> sets an internal IPython hook.
707 706
708 707 IPython exposes some of its internal API as user-modifiable hooks. By
709 708 adding your function to one of these hooks, you can modify IPython's
710 709 behavior to call at runtime your own routines."""
711 710
712 711 # At some point in the future, this should validate the hook before it
713 712 # accepts it. Probably at least check that the hook takes the number
714 713 # of args it's supposed to.
715 714 dp = getattr(self.hooks, name, None)
716 715 if name not in IPython.hooks.__all__:
717 716 print "Warning! Hook '%s' is not one of %s" % (name, IPython.hooks.__all__ )
718 717 if not dp:
719 718 dp = IPython.hooks.CommandChainDispatcher()
720 719
721 720 f = new.instancemethod(hook,self,self.__class__)
722 721 try:
723 722 dp.add(f,priority)
724 723 except AttributeError:
725 724 # it was not commandchain, plain old func - replace
726 725 dp = f
727 726
728 727 setattr(self.hooks,name, dp)
729 728
730 729
731 730 #setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
732 731
733 732 def set_custom_exc(self,exc_tuple,handler):
734 733 """set_custom_exc(exc_tuple,handler)
735 734
736 735 Set a custom exception handler, which will be called if any of the
737 736 exceptions in exc_tuple occur in the mainloop (specifically, in the
738 737 runcode() method.
739 738
740 739 Inputs:
741 740
742 741 - exc_tuple: a *tuple* of valid exceptions to call the defined
743 742 handler for. It is very important that you use a tuple, and NOT A
744 743 LIST here, because of the way Python's except statement works. If
745 744 you only want to trap a single exception, use a singleton tuple:
746 745
747 746 exc_tuple == (MyCustomException,)
748 747
749 748 - handler: this must be defined as a function with the following
750 749 basic interface: def my_handler(self,etype,value,tb).
751 750
752 751 This will be made into an instance method (via new.instancemethod)
753 752 of IPython itself, and it will be called if any of the exceptions
754 753 listed in the exc_tuple are caught. If the handler is None, an
755 754 internal basic one is used, which just prints basic info.
756 755
757 756 WARNING: by putting in your own exception handler into IPython's main
758 757 execution loop, you run a very good chance of nasty crashes. This
759 758 facility should only be used if you really know what you are doing."""
760 759
761 760 assert type(exc_tuple)==type(()) , \
762 761 "The custom exceptions must be given AS A TUPLE."
763 762
764 763 def dummy_handler(self,etype,value,tb):
765 764 print '*** Simple custom exception handler ***'
766 765 print 'Exception type :',etype
767 766 print 'Exception value:',value
768 767 print 'Traceback :',tb
769 768 print 'Source code :','\n'.join(self.buffer)
770 769
771 770 if handler is None: handler = dummy_handler
772 771
773 772 self.CustomTB = new.instancemethod(handler,self,self.__class__)
774 773 self.custom_exceptions = exc_tuple
775 774
776 775 def set_custom_completer(self,completer,pos=0):
777 776 """set_custom_completer(completer,pos=0)
778 777
779 778 Adds a new custom completer function.
780 779
781 780 The position argument (defaults to 0) is the index in the completers
782 781 list where you want the completer to be inserted."""
783 782
784 783 newcomp = new.instancemethod(completer,self.Completer,
785 784 self.Completer.__class__)
786 785 self.Completer.matchers.insert(pos,newcomp)
787 786
788 787 def _get_call_pdb(self):
789 788 return self._call_pdb
790 789
791 790 def _set_call_pdb(self,val):
792 791
793 792 if val not in (0,1,False,True):
794 793 raise ValueError,'new call_pdb value must be boolean'
795 794
796 795 # store value in instance
797 796 self._call_pdb = val
798 797
799 798 # notify the actual exception handlers
800 799 self.InteractiveTB.call_pdb = val
801 800 if self.isthreaded:
802 801 try:
803 802 self.sys_excepthook.call_pdb = val
804 803 except:
805 804 warn('Failed to activate pdb for threaded exception handler')
806 805
807 806 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
808 807 'Control auto-activation of pdb at exceptions')
809 808
810 809
811 810 # These special functions get installed in the builtin namespace, to
812 811 # provide programmatic (pure python) access to magics, aliases and system
813 812 # calls. This is important for logging, user scripting, and more.
814 813
815 814 # We are basically exposing, via normal python functions, the three
816 815 # mechanisms in which ipython offers special call modes (magics for
817 816 # internal control, aliases for direct system access via pre-selected
818 817 # names, and !cmd for calling arbitrary system commands).
819 818
820 819 def ipmagic(self,arg_s):
821 820 """Call a magic function by name.
822 821
823 822 Input: a string containing the name of the magic function to call and any
824 823 additional arguments to be passed to the magic.
825 824
826 825 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
827 826 prompt:
828 827
829 828 In[1]: %name -opt foo bar
830 829
831 830 To call a magic without arguments, simply use ipmagic('name').
832 831
833 832 This provides a proper Python function to call IPython's magics in any
834 833 valid Python code you can type at the interpreter, including loops and
835 834 compound statements. It is added by IPython to the Python builtin
836 835 namespace upon initialization."""
837 836
838 837 args = arg_s.split(' ',1)
839 838 magic_name = args[0]
840 839 magic_name = magic_name.lstrip(self.ESC_MAGIC)
841 840
842 841 try:
843 842 magic_args = args[1]
844 843 except IndexError:
845 844 magic_args = ''
846 845 fn = getattr(self,'magic_'+magic_name,None)
847 846 if fn is None:
848 847 error("Magic function `%s` not found." % magic_name)
849 848 else:
850 849 magic_args = self.var_expand(magic_args)
851 850 return fn(magic_args)
852 851
853 852 def ipalias(self,arg_s):
854 853 """Call an alias by name.
855 854
856 855 Input: a string containing the name of the alias to call and any
857 856 additional arguments to be passed to the magic.
858 857
859 858 ipalias('name -opt foo bar') is equivalent to typing at the ipython
860 859 prompt:
861 860
862 861 In[1]: name -opt foo bar
863 862
864 863 To call an alias without arguments, simply use ipalias('name').
865 864
866 865 This provides a proper Python function to call IPython's aliases in any
867 866 valid Python code you can type at the interpreter, including loops and
868 867 compound statements. It is added by IPython to the Python builtin
869 868 namespace upon initialization."""
870 869
871 870 args = arg_s.split(' ',1)
872 871 alias_name = args[0]
873 872 try:
874 873 alias_args = args[1]
875 874 except IndexError:
876 875 alias_args = ''
877 876 if alias_name in self.alias_table:
878 877 self.call_alias(alias_name,alias_args)
879 878 else:
880 879 error("Alias `%s` not found." % alias_name)
881 880
882 881 def ipsystem(self,arg_s):
883 882 """Make a system call, using IPython."""
884 883
885 884 self.system(arg_s)
886 885
887 886 def complete(self,text):
888 887 """Return a sorted list of all possible completions on text.
889 888
890 889 Inputs:
891 890
892 891 - text: a string of text to be completed on.
893 892
894 893 This is a wrapper around the completion mechanism, similar to what
895 894 readline does at the command line when the TAB key is hit. By
896 895 exposing it as a method, it can be used by other non-readline
897 896 environments (such as GUIs) for text completion.
898 897
899 898 Simple usage example:
900 899
901 900 In [1]: x = 'hello'
902 901
903 902 In [2]: __IP.complete('x.l')
904 903 Out[2]: ['x.ljust', 'x.lower', 'x.lstrip']"""
905 904
906 905 complete = self.Completer.complete
907 906 state = 0
908 907 # use a dict so we get unique keys, since ipyhton's multiple
909 908 # completers can return duplicates.
910 909 comps = {}
911 910 while True:
912 911 newcomp = complete(text,state)
913 912 if newcomp is None:
914 913 break
915 914 comps[newcomp] = 1
916 915 state += 1
917 916 outcomps = comps.keys()
918 917 outcomps.sort()
919 918 return outcomps
920 919
921 920 def set_completer_frame(self, frame=None):
922 921 if frame:
923 922 self.Completer.namespace = frame.f_locals
924 923 self.Completer.global_namespace = frame.f_globals
925 924 else:
926 925 self.Completer.namespace = self.user_ns
927 926 self.Completer.global_namespace = self.user_global_ns
928 927
929 928 def init_auto_alias(self):
930 929 """Define some aliases automatically.
931 930
932 931 These are ALL parameter-less aliases"""
933 932
934 933 for alias,cmd in self.auto_alias:
935 934 self.alias_table[alias] = (0,cmd)
936 935
937 936 def alias_table_validate(self,verbose=0):
938 937 """Update information about the alias table.
939 938
940 939 In particular, make sure no Python keywords/builtins are in it."""
941 940
942 941 no_alias = self.no_alias
943 942 for k in self.alias_table.keys():
944 943 if k in no_alias:
945 944 del self.alias_table[k]
946 945 if verbose:
947 946 print ("Deleting alias <%s>, it's a Python "
948 947 "keyword or builtin." % k)
949 948
950 949 def set_autoindent(self,value=None):
951 950 """Set the autoindent flag, checking for readline support.
952 951
953 952 If called with no arguments, it acts as a toggle."""
954 953
955 954 if not self.has_readline:
956 955 if os.name == 'posix':
957 956 warn("The auto-indent feature requires the readline library")
958 957 self.autoindent = 0
959 958 return
960 959 if value is None:
961 960 self.autoindent = not self.autoindent
962 961 else:
963 962 self.autoindent = value
964 963
965 964 def rc_set_toggle(self,rc_field,value=None):
966 965 """Set or toggle a field in IPython's rc config. structure.
967 966
968 967 If called with no arguments, it acts as a toggle.
969 968
970 969 If called with a non-existent field, the resulting AttributeError
971 970 exception will propagate out."""
972 971
973 972 rc_val = getattr(self.rc,rc_field)
974 973 if value is None:
975 974 value = not rc_val
976 975 setattr(self.rc,rc_field,value)
977 976
978 977 def user_setup(self,ipythondir,rc_suffix,mode='install'):
979 978 """Install the user configuration directory.
980 979
981 980 Can be called when running for the first time or to upgrade the user's
982 981 .ipython/ directory with the mode parameter. Valid modes are 'install'
983 982 and 'upgrade'."""
984 983
985 984 def wait():
986 985 try:
987 986 raw_input("Please press <RETURN> to start IPython.")
988 987 except EOFError:
989 988 print >> Term.cout
990 989 print '*'*70
991 990
992 991 cwd = os.getcwd() # remember where we started
993 992 glb = glob.glob
994 993 print '*'*70
995 994 if mode == 'install':
996 995 print \
997 996 """Welcome to IPython. I will try to create a personal configuration directory
998 997 where you can customize many aspects of IPython's functionality in:\n"""
999 998 else:
1000 999 print 'I am going to upgrade your configuration in:'
1001 1000
1002 1001 print ipythondir
1003 1002
1004 1003 rcdirend = os.path.join('IPython','UserConfig')
1005 1004 cfg = lambda d: os.path.join(d,rcdirend)
1006 1005 try:
1007 1006 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
1008 1007 except IOError:
1009 1008 warning = """
1010 1009 Installation error. IPython's directory was not found.
1011 1010
1012 1011 Check the following:
1013 1012
1014 1013 The ipython/IPython directory should be in a directory belonging to your
1015 1014 PYTHONPATH environment variable (that is, it should be in a directory
1016 1015 belonging to sys.path). You can copy it explicitly there or just link to it.
1017 1016
1018 1017 IPython will proceed with builtin defaults.
1019 1018 """
1020 1019 warn(warning)
1021 1020 wait()
1022 1021 return
1023 1022
1024 1023 if mode == 'install':
1025 1024 try:
1026 1025 shutil.copytree(rcdir,ipythondir)
1027 1026 os.chdir(ipythondir)
1028 1027 rc_files = glb("ipythonrc*")
1029 1028 for rc_file in rc_files:
1030 1029 os.rename(rc_file,rc_file+rc_suffix)
1031 1030 except:
1032 1031 warning = """
1033 1032
1034 1033 There was a problem with the installation:
1035 1034 %s
1036 1035 Try to correct it or contact the developers if you think it's a bug.
1037 1036 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
1038 1037 warn(warning)
1039 1038 wait()
1040 1039 return
1041 1040
1042 1041 elif mode == 'upgrade':
1043 1042 try:
1044 1043 os.chdir(ipythondir)
1045 1044 except:
1046 1045 print """
1047 1046 Can not upgrade: changing to directory %s failed. Details:
1048 1047 %s
1049 1048 """ % (ipythondir,sys.exc_info()[1])
1050 1049 wait()
1051 1050 return
1052 1051 else:
1053 1052 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
1054 1053 for new_full_path in sources:
1055 1054 new_filename = os.path.basename(new_full_path)
1056 1055 if new_filename.startswith('ipythonrc'):
1057 1056 new_filename = new_filename + rc_suffix
1058 1057 # The config directory should only contain files, skip any
1059 1058 # directories which may be there (like CVS)
1060 1059 if os.path.isdir(new_full_path):
1061 1060 continue
1062 1061 if os.path.exists(new_filename):
1063 1062 old_file = new_filename+'.old'
1064 1063 if os.path.exists(old_file):
1065 1064 os.remove(old_file)
1066 1065 os.rename(new_filename,old_file)
1067 1066 shutil.copy(new_full_path,new_filename)
1068 1067 else:
1069 1068 raise ValueError,'unrecognized mode for install:',`mode`
1070 1069
1071 1070 # Fix line-endings to those native to each platform in the config
1072 1071 # directory.
1073 1072 try:
1074 1073 os.chdir(ipythondir)
1075 1074 except:
1076 1075 print """
1077 1076 Problem: changing to directory %s failed.
1078 1077 Details:
1079 1078 %s
1080 1079
1081 1080 Some configuration files may have incorrect line endings. This should not
1082 1081 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1])
1083 1082 wait()
1084 1083 else:
1085 1084 for fname in glb('ipythonrc*'):
1086 1085 try:
1087 1086 native_line_ends(fname,backup=0)
1088 1087 except IOError:
1089 1088 pass
1090 1089
1091 1090 if mode == 'install':
1092 1091 print """
1093 1092 Successful installation!
1094 1093
1095 1094 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
1096 1095 IPython manual (there are both HTML and PDF versions supplied with the
1097 1096 distribution) to make sure that your system environment is properly configured
1098 1097 to take advantage of IPython's features.
1099 1098
1100 1099 Important note: the configuration system has changed! The old system is
1101 1100 still in place, but its setting may be partly overridden by the settings in
1102 1101 "~/.ipython/ipy_user_conf.py" config file. Please take a look at the file
1103 1102 if some of the new settings bother you.
1104 1103
1105 1104 """
1106 1105 else:
1107 1106 print """
1108 1107 Successful upgrade!
1109 1108
1110 1109 All files in your directory:
1111 1110 %(ipythondir)s
1112 1111 which would have been overwritten by the upgrade were backed up with a .old
1113 1112 extension. If you had made particular customizations in those files you may
1114 1113 want to merge them back into the new files.""" % locals()
1115 1114 wait()
1116 1115 os.chdir(cwd)
1117 1116 # end user_setup()
1118 1117
1119 1118 def atexit_operations(self):
1120 1119 """This will be executed at the time of exit.
1121 1120
1122 1121 Saving of persistent data should be performed here. """
1123 1122
1124 1123 #print '*** IPython exit cleanup ***' # dbg
1125 1124 # input history
1126 1125 self.savehist()
1127 1126
1128 1127 # Cleanup all tempfiles left around
1129 1128 for tfile in self.tempfiles:
1130 1129 try:
1131 1130 os.unlink(tfile)
1132 1131 except OSError:
1133 1132 pass
1134 1133
1135 1134 # save the "persistent data" catch-all dictionary
1136 1135 self.hooks.shutdown_hook()
1137 1136
1138 1137 def savehist(self):
1139 1138 """Save input history to a file (via readline library)."""
1140 1139 try:
1141 1140 self.readline.write_history_file(self.histfile)
1142 1141 except:
1143 1142 print 'Unable to save IPython command history to file: ' + \
1144 1143 `self.histfile`
1145 1144
1146 1145 def pre_readline(self):
1147 1146 """readline hook to be used at the start of each line.
1148 1147
1149 1148 Currently it handles auto-indent only."""
1150 1149
1151 1150 #debugx('self.indent_current_nsp','pre_readline:')
1152 1151 self.readline.insert_text(self.indent_current_str())
1153 1152
1154 1153 def init_readline(self):
1155 1154 """Command history completion/saving/reloading."""
1156 1155
1157 1156 import IPython.rlineimpl as readline
1158 1157 if not readline.have_readline:
1159 1158 self.has_readline = 0
1160 1159 self.readline = None
1161 1160 # no point in bugging windows users with this every time:
1162 1161 warn('Readline services not available on this platform.')
1163 1162 else:
1164 1163 sys.modules['readline'] = readline
1165 1164 import atexit
1166 1165 from IPython.completer import IPCompleter
1167 1166 self.Completer = IPCompleter(self,
1168 1167 self.user_ns,
1169 1168 self.user_global_ns,
1170 1169 self.rc.readline_omit__names,
1171 1170 self.alias_table)
1172 1171
1173 1172 # Platform-specific configuration
1174 1173 if os.name == 'nt':
1175 1174 self.readline_startup_hook = readline.set_pre_input_hook
1176 1175 else:
1177 1176 self.readline_startup_hook = readline.set_startup_hook
1178 1177
1179 1178 # Load user's initrc file (readline config)
1180 1179 inputrc_name = os.environ.get('INPUTRC')
1181 1180 if inputrc_name is None:
1182 1181 home_dir = get_home_dir()
1183 1182 if home_dir is not None:
1184 1183 inputrc_name = os.path.join(home_dir,'.inputrc')
1185 1184 if os.path.isfile(inputrc_name):
1186 1185 try:
1187 1186 readline.read_init_file(inputrc_name)
1188 1187 except:
1189 1188 warn('Problems reading readline initialization file <%s>'
1190 1189 % inputrc_name)
1191 1190
1192 1191 self.has_readline = 1
1193 1192 self.readline = readline
1194 1193 # save this in sys so embedded copies can restore it properly
1195 1194 sys.ipcompleter = self.Completer.complete
1196 1195 readline.set_completer(self.Completer.complete)
1197 1196
1198 1197 # Configure readline according to user's prefs
1199 1198 for rlcommand in self.rc.readline_parse_and_bind:
1200 1199 readline.parse_and_bind(rlcommand)
1201 1200
1202 1201 # remove some chars from the delimiters list
1203 1202 delims = readline.get_completer_delims()
1204 1203 delims = delims.translate(string._idmap,
1205 1204 self.rc.readline_remove_delims)
1206 1205 readline.set_completer_delims(delims)
1207 1206 # otherwise we end up with a monster history after a while:
1208 1207 readline.set_history_length(1000)
1209 1208 try:
1210 1209 #print '*** Reading readline history' # dbg
1211 1210 readline.read_history_file(self.histfile)
1212 1211 except IOError:
1213 1212 pass # It doesn't exist yet.
1214 1213
1215 1214 atexit.register(self.atexit_operations)
1216 1215 del atexit
1217 1216
1218 1217 # Configure auto-indent for all platforms
1219 1218 self.set_autoindent(self.rc.autoindent)
1220 1219
1221 1220 def _should_recompile(self,e):
1222 1221 """Utility routine for edit_syntax_error"""
1223 1222
1224 1223 if e.filename in ('<ipython console>','<input>','<string>',
1225 1224 '<console>','<BackgroundJob compilation>',
1226 1225 None):
1227 1226
1228 1227 return False
1229 1228 try:
1230 1229 if (self.rc.autoedit_syntax and
1231 1230 not ask_yes_no('Return to editor to correct syntax error? '
1232 1231 '[Y/n] ','y')):
1233 1232 return False
1234 1233 except EOFError:
1235 1234 return False
1236 1235
1237 1236 def int0(x):
1238 1237 try:
1239 1238 return int(x)
1240 1239 except TypeError:
1241 1240 return 0
1242 1241 # always pass integer line and offset values to editor hook
1243 1242 self.hooks.fix_error_editor(e.filename,
1244 1243 int0(e.lineno),int0(e.offset),e.msg)
1245 1244 return True
1246 1245
1247 1246 def edit_syntax_error(self):
1248 1247 """The bottom half of the syntax error handler called in the main loop.
1249 1248
1250 1249 Loop until syntax error is fixed or user cancels.
1251 1250 """
1252 1251
1253 1252 while self.SyntaxTB.last_syntax_error:
1254 1253 # copy and clear last_syntax_error
1255 1254 err = self.SyntaxTB.clear_err_state()
1256 1255 if not self._should_recompile(err):
1257 1256 return
1258 1257 try:
1259 1258 # may set last_syntax_error again if a SyntaxError is raised
1260 1259 self.safe_execfile(err.filename,self.shell.user_ns)
1261 1260 except:
1262 1261 self.showtraceback()
1263 1262 else:
1264 1263 try:
1265 1264 f = file(err.filename)
1266 1265 try:
1267 1266 sys.displayhook(f.read())
1268 1267 finally:
1269 1268 f.close()
1270 1269 except:
1271 1270 self.showtraceback()
1272 1271
1273 1272 def showsyntaxerror(self, filename=None):
1274 1273 """Display the syntax error that just occurred.
1275 1274
1276 1275 This doesn't display a stack trace because there isn't one.
1277 1276
1278 1277 If a filename is given, it is stuffed in the exception instead
1279 1278 of what was there before (because Python's parser always uses
1280 1279 "<string>" when reading from a string).
1281 1280 """
1282 1281 etype, value, last_traceback = sys.exc_info()
1283 1282
1284 1283 # See note about these variables in showtraceback() below
1285 1284 sys.last_type = etype
1286 1285 sys.last_value = value
1287 1286 sys.last_traceback = last_traceback
1288 1287
1289 1288 if filename and etype is SyntaxError:
1290 1289 # Work hard to stuff the correct filename in the exception
1291 1290 try:
1292 1291 msg, (dummy_filename, lineno, offset, line) = value
1293 1292 except:
1294 1293 # Not the format we expect; leave it alone
1295 1294 pass
1296 1295 else:
1297 1296 # Stuff in the right filename
1298 1297 try:
1299 1298 # Assume SyntaxError is a class exception
1300 1299 value = SyntaxError(msg, (filename, lineno, offset, line))
1301 1300 except:
1302 1301 # If that failed, assume SyntaxError is a string
1303 1302 value = msg, (filename, lineno, offset, line)
1304 1303 self.SyntaxTB(etype,value,[])
1305 1304
1306 1305 def debugger(self):
1307 1306 """Call the pdb debugger."""
1308 1307
1309 1308 if not self.rc.pdb:
1310 1309 return
1311 1310 pdb.pm()
1312 1311
1313 1312 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1314 1313 """Display the exception that just occurred.
1315 1314
1316 1315 If nothing is known about the exception, this is the method which
1317 1316 should be used throughout the code for presenting user tracebacks,
1318 1317 rather than directly invoking the InteractiveTB object.
1319 1318
1320 1319 A specific showsyntaxerror() also exists, but this method can take
1321 1320 care of calling it if needed, so unless you are explicitly catching a
1322 1321 SyntaxError exception, don't try to analyze the stack manually and
1323 1322 simply call this method."""
1324 1323
1325 1324 # Though this won't be called by syntax errors in the input line,
1326 1325 # there may be SyntaxError cases whith imported code.
1327 1326 if exc_tuple is None:
1328 1327 etype, value, tb = sys.exc_info()
1329 1328 else:
1330 1329 etype, value, tb = exc_tuple
1331 1330 if etype is SyntaxError:
1332 1331 self.showsyntaxerror(filename)
1333 1332 else:
1334 1333 # WARNING: these variables are somewhat deprecated and not
1335 1334 # necessarily safe to use in a threaded environment, but tools
1336 1335 # like pdb depend on their existence, so let's set them. If we
1337 1336 # find problems in the field, we'll need to revisit their use.
1338 1337 sys.last_type = etype
1339 1338 sys.last_value = value
1340 1339 sys.last_traceback = tb
1341 1340
1342 1341 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1343 1342 if self.InteractiveTB.call_pdb and self.has_readline:
1344 1343 # pdb mucks up readline, fix it back
1345 1344 self.readline.set_completer(self.Completer.complete)
1346 1345
1347 1346 def mainloop(self,banner=None):
1348 1347 """Creates the local namespace and starts the mainloop.
1349 1348
1350 1349 If an optional banner argument is given, it will override the
1351 1350 internally created default banner."""
1352 1351
1353 1352 if self.rc.c: # Emulate Python's -c option
1354 1353 self.exec_init_cmd()
1355 1354 if banner is None:
1356 1355 if not self.rc.banner:
1357 1356 banner = ''
1358 1357 # banner is string? Use it directly!
1359 1358 elif isinstance(self.rc.banner,basestring):
1360 1359 banner = self.rc.banner
1361 1360 else:
1362 1361 banner = self.BANNER+self.banner2
1363 1362
1364 1363 self.interact(banner)
1365 1364
1366 1365 def exec_init_cmd(self):
1367 1366 """Execute a command given at the command line.
1368 1367
1369 1368 This emulates Python's -c option."""
1370 1369
1371 1370 #sys.argv = ['-c']
1372 1371 self.push(self.rc.c)
1373 1372
1374 1373 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1375 1374 """Embeds IPython into a running python program.
1376 1375
1377 1376 Input:
1378 1377
1379 1378 - header: An optional header message can be specified.
1380 1379
1381 1380 - local_ns, global_ns: working namespaces. If given as None, the
1382 1381 IPython-initialized one is updated with __main__.__dict__, so that
1383 1382 program variables become visible but user-specific configuration
1384 1383 remains possible.
1385 1384
1386 1385 - stack_depth: specifies how many levels in the stack to go to
1387 1386 looking for namespaces (when local_ns and global_ns are None). This
1388 1387 allows an intermediate caller to make sure that this function gets
1389 1388 the namespace from the intended level in the stack. By default (0)
1390 1389 it will get its locals and globals from the immediate caller.
1391 1390
1392 1391 Warning: it's possible to use this in a program which is being run by
1393 1392 IPython itself (via %run), but some funny things will happen (a few
1394 1393 globals get overwritten). In the future this will be cleaned up, as
1395 1394 there is no fundamental reason why it can't work perfectly."""
1396 1395
1397 1396 # Get locals and globals from caller
1398 1397 if local_ns is None or global_ns is None:
1399 1398 call_frame = sys._getframe(stack_depth).f_back
1400 1399
1401 1400 if local_ns is None:
1402 1401 local_ns = call_frame.f_locals
1403 1402 if global_ns is None:
1404 1403 global_ns = call_frame.f_globals
1405 1404
1406 1405 # Update namespaces and fire up interpreter
1407 1406
1408 1407 # The global one is easy, we can just throw it in
1409 1408 self.user_global_ns = global_ns
1410 1409
1411 1410 # but the user/local one is tricky: ipython needs it to store internal
1412 1411 # data, but we also need the locals. We'll copy locals in the user
1413 1412 # one, but will track what got copied so we can delete them at exit.
1414 1413 # This is so that a later embedded call doesn't see locals from a
1415 1414 # previous call (which most likely existed in a separate scope).
1416 1415 local_varnames = local_ns.keys()
1417 1416 self.user_ns.update(local_ns)
1418 1417
1419 1418 # Patch for global embedding to make sure that things don't overwrite
1420 1419 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1421 1420 # FIXME. Test this a bit more carefully (the if.. is new)
1422 1421 if local_ns is None and global_ns is None:
1423 1422 self.user_global_ns.update(__main__.__dict__)
1424 1423
1425 1424 # make sure the tab-completer has the correct frame information, so it
1426 1425 # actually completes using the frame's locals/globals
1427 1426 self.set_completer_frame()
1428 1427
1429 1428 # before activating the interactive mode, we need to make sure that
1430 1429 # all names in the builtin namespace needed by ipython point to
1431 1430 # ourselves, and not to other instances.
1432 1431 self.add_builtins()
1433 1432
1434 1433 self.interact(header)
1435 1434
1436 1435 # now, purge out the user namespace from anything we might have added
1437 1436 # from the caller's local namespace
1438 1437 delvar = self.user_ns.pop
1439 1438 for var in local_varnames:
1440 1439 delvar(var,None)
1441 1440 # and clean builtins we may have overridden
1442 1441 self.clean_builtins()
1443 1442
1444 1443 def interact(self, banner=None):
1445 1444 """Closely emulate the interactive Python console.
1446 1445
1447 1446 The optional banner argument specify the banner to print
1448 1447 before the first interaction; by default it prints a banner
1449 1448 similar to the one printed by the real Python interpreter,
1450 1449 followed by the current class name in parentheses (so as not
1451 1450 to confuse this with the real interpreter -- since it's so
1452 1451 close!).
1453 1452
1454 1453 """
1455 1454 cprt = 'Type "copyright", "credits" or "license" for more information.'
1456 1455 if banner is None:
1457 1456 self.write("Python %s on %s\n%s\n(%s)\n" %
1458 1457 (sys.version, sys.platform, cprt,
1459 1458 self.__class__.__name__))
1460 1459 else:
1461 1460 self.write(banner)
1462 1461
1463 1462 more = 0
1464 1463
1465 1464 # Mark activity in the builtins
1466 1465 __builtin__.__dict__['__IPYTHON__active'] += 1
1467 1466
1468 1467 # exit_now is set by a call to %Exit or %Quit
1469 1468 self.exit_now = False
1470 1469 while not self.exit_now:
1471 1470 if more:
1472 1471 prompt = self.outputcache.prompt2
1473 1472 if self.autoindent:
1474 1473 self.readline_startup_hook(self.pre_readline)
1475 1474 else:
1476 1475 prompt = self.outputcache.prompt1
1477 1476 try:
1478 1477 line = self.raw_input(prompt,more)
1479 1478 if self.autoindent:
1480 1479 self.readline_startup_hook(None)
1481 1480 except KeyboardInterrupt:
1482 1481 self.write('\nKeyboardInterrupt\n')
1483 1482 self.resetbuffer()
1484 1483 # keep cache in sync with the prompt counter:
1485 1484 self.outputcache.prompt_count -= 1
1486 1485
1487 1486 if self.autoindent:
1488 1487 self.indent_current_nsp = 0
1489 1488 more = 0
1490 1489 except EOFError:
1491 1490 if self.autoindent:
1492 1491 self.readline_startup_hook(None)
1493 1492 self.write('\n')
1494 1493 self.exit()
1495 1494 except bdb.BdbQuit:
1496 1495 warn('The Python debugger has exited with a BdbQuit exception.\n'
1497 1496 'Because of how pdb handles the stack, it is impossible\n'
1498 1497 'for IPython to properly format this particular exception.\n'
1499 1498 'IPython will resume normal operation.')
1500 1499 except:
1501 1500 # exceptions here are VERY RARE, but they can be triggered
1502 1501 # asynchronously by signal handlers, for example.
1503 1502 self.showtraceback()
1504 1503 else:
1505 1504 more = self.push(line)
1506 1505 if (self.SyntaxTB.last_syntax_error and
1507 1506 self.rc.autoedit_syntax):
1508 1507 self.edit_syntax_error()
1509 1508
1510 1509 # We are off again...
1511 1510 __builtin__.__dict__['__IPYTHON__active'] -= 1
1512 1511
1513 1512 def excepthook(self, etype, value, tb):
1514 1513 """One more defense for GUI apps that call sys.excepthook.
1515 1514
1516 1515 GUI frameworks like wxPython trap exceptions and call
1517 1516 sys.excepthook themselves. I guess this is a feature that
1518 1517 enables them to keep running after exceptions that would
1519 1518 otherwise kill their mainloop. This is a bother for IPython
1520 1519 which excepts to catch all of the program exceptions with a try:
1521 1520 except: statement.
1522 1521
1523 1522 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1524 1523 any app directly invokes sys.excepthook, it will look to the user like
1525 1524 IPython crashed. In order to work around this, we can disable the
1526 1525 CrashHandler and replace it with this excepthook instead, which prints a
1527 1526 regular traceback using our InteractiveTB. In this fashion, apps which
1528 1527 call sys.excepthook will generate a regular-looking exception from
1529 1528 IPython, and the CrashHandler will only be triggered by real IPython
1530 1529 crashes.
1531 1530
1532 1531 This hook should be used sparingly, only in places which are not likely
1533 1532 to be true IPython errors.
1534 1533 """
1535 1534 self.showtraceback((etype,value,tb),tb_offset=0)
1536 1535
1537 1536 def transform_alias(self, alias,rest=''):
1538 1537 """ Transform alias to system command string
1539 1538
1540 1539 """
1541 1540 nargs,cmd = self.alias_table[alias]
1542 1541 if ' ' in cmd and os.path.isfile(cmd):
1543 1542 cmd = '"%s"' % cmd
1544 1543
1545 1544 # Expand the %l special to be the user's input line
1546 1545 if cmd.find('%l') >= 0:
1547 1546 cmd = cmd.replace('%l',rest)
1548 1547 rest = ''
1549 1548 if nargs==0:
1550 1549 # Simple, argument-less aliases
1551 1550 cmd = '%s %s' % (cmd,rest)
1552 1551 else:
1553 1552 # Handle aliases with positional arguments
1554 1553 args = rest.split(None,nargs)
1555 1554 if len(args)< nargs:
1556 1555 error('Alias <%s> requires %s arguments, %s given.' %
1557 1556 (alias,nargs,len(args)))
1558 1557 return None
1559 1558 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
1560 1559 # Now call the macro, evaluating in the user's namespace
1561 1560
1562 1561 return cmd
1563 1562
1564 1563 def call_alias(self,alias,rest=''):
1565 1564 """Call an alias given its name and the rest of the line.
1566 1565
1567 1566 This is only used to provide backwards compatibility for users of
1568 1567 ipalias(), use of which is not recommended for anymore."""
1569 1568
1570 1569 # Now call the macro, evaluating in the user's namespace
1571 1570 cmd = self.transform_alias(alias, rest)
1572 1571 try:
1573 1572 self.system(cmd)
1574 1573 except:
1575 1574 self.showtraceback()
1576 1575
1577 1576 def indent_current_str(self):
1578 1577 """return the current level of indentation as a string"""
1579 1578 return self.indent_current_nsp * ' '
1580 1579
1581 1580 def autoindent_update(self,line):
1582 1581 """Keep track of the indent level."""
1583 1582
1584 1583 #debugx('line')
1585 1584 #debugx('self.indent_current_nsp')
1586 1585 if self.autoindent:
1587 1586 if line:
1588 1587 inisp = num_ini_spaces(line)
1589 1588 if inisp < self.indent_current_nsp:
1590 1589 self.indent_current_nsp = inisp
1591 1590
1592 1591 if line[-1] == ':':
1593 1592 self.indent_current_nsp += 4
1594 1593 elif dedent_re.match(line):
1595 1594 self.indent_current_nsp -= 4
1596 1595 else:
1597 1596 self.indent_current_nsp = 0
1598 1597
1599 1598 def runlines(self,lines):
1600 1599 """Run a string of one or more lines of source.
1601 1600
1602 1601 This method is capable of running a string containing multiple source
1603 1602 lines, as if they had been entered at the IPython prompt. Since it
1604 1603 exposes IPython's processing machinery, the given strings can contain
1605 1604 magic calls (%magic), special shell access (!cmd), etc."""
1606 1605
1607 1606 # We must start with a clean buffer, in case this is run from an
1608 1607 # interactive IPython session (via a magic, for example).
1609 1608 self.resetbuffer()
1610 1609 lines = lines.split('\n')
1611 1610 more = 0
1612 1611 for line in lines:
1613 1612 # skip blank lines so we don't mess up the prompt counter, but do
1614 1613 # NOT skip even a blank line if we are in a code block (more is
1615 1614 # true)
1616 1615 if line or more:
1617 1616 more = self.push(self.prefilter(line,more))
1618 1617 # IPython's runsource returns None if there was an error
1619 1618 # compiling the code. This allows us to stop processing right
1620 1619 # away, so the user gets the error message at the right place.
1621 1620 if more is None:
1622 1621 break
1623 1622 # final newline in case the input didn't have it, so that the code
1624 1623 # actually does get executed
1625 1624 if more:
1626 1625 self.push('\n')
1627 1626
1628 1627 def runsource(self, source, filename='<input>', symbol='single'):
1629 1628 """Compile and run some source in the interpreter.
1630 1629
1631 1630 Arguments are as for compile_command().
1632 1631
1633 1632 One several things can happen:
1634 1633
1635 1634 1) The input is incorrect; compile_command() raised an
1636 1635 exception (SyntaxError or OverflowError). A syntax traceback
1637 1636 will be printed by calling the showsyntaxerror() method.
1638 1637
1639 1638 2) The input is incomplete, and more input is required;
1640 1639 compile_command() returned None. Nothing happens.
1641 1640
1642 1641 3) The input is complete; compile_command() returned a code
1643 1642 object. The code is executed by calling self.runcode() (which
1644 1643 also handles run-time exceptions, except for SystemExit).
1645 1644
1646 1645 The return value is:
1647 1646
1648 1647 - True in case 2
1649 1648
1650 1649 - False in the other cases, unless an exception is raised, where
1651 1650 None is returned instead. This can be used by external callers to
1652 1651 know whether to continue feeding input or not.
1653 1652
1654 1653 The return value can be used to decide whether to use sys.ps1 or
1655 1654 sys.ps2 to prompt the next line."""
1656 1655
1657 1656 try:
1658 1657 code = self.compile(source,filename,symbol)
1659 1658 except (OverflowError, SyntaxError, ValueError):
1660 1659 # Case 1
1661 1660 self.showsyntaxerror(filename)
1662 1661 return None
1663 1662
1664 1663 if code is None:
1665 1664 # Case 2
1666 1665 return True
1667 1666
1668 1667 # Case 3
1669 1668 # We store the code object so that threaded shells and
1670 1669 # custom exception handlers can access all this info if needed.
1671 1670 # The source corresponding to this can be obtained from the
1672 1671 # buffer attribute as '\n'.join(self.buffer).
1673 1672 self.code_to_run = code
1674 1673 # now actually execute the code object
1675 1674 if self.runcode(code) == 0:
1676 1675 return False
1677 1676 else:
1678 1677 return None
1679 1678
1680 1679 def runcode(self,code_obj):
1681 1680 """Execute a code object.
1682 1681
1683 1682 When an exception occurs, self.showtraceback() is called to display a
1684 1683 traceback.
1685 1684
1686 1685 Return value: a flag indicating whether the code to be run completed
1687 1686 successfully:
1688 1687
1689 1688 - 0: successful execution.
1690 1689 - 1: an error occurred.
1691 1690 """
1692 1691
1693 1692 # Set our own excepthook in case the user code tries to call it
1694 1693 # directly, so that the IPython crash handler doesn't get triggered
1695 1694 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1696 1695
1697 1696 # we save the original sys.excepthook in the instance, in case config
1698 1697 # code (such as magics) needs access to it.
1699 1698 self.sys_excepthook = old_excepthook
1700 1699 outflag = 1 # happens in more places, so it's easier as default
1701 1700 try:
1702 1701 try:
1703 1702 # Embedded instances require separate global/local namespaces
1704 1703 # so they can see both the surrounding (local) namespace and
1705 1704 # the module-level globals when called inside another function.
1706 1705 if self.embedded:
1707 1706 exec code_obj in self.user_global_ns, self.user_ns
1708 1707 # Normal (non-embedded) instances should only have a single
1709 1708 # namespace for user code execution, otherwise functions won't
1710 1709 # see interactive top-level globals.
1711 1710 else:
1712 1711 exec code_obj in self.user_ns
1713 1712 finally:
1714 1713 # Reset our crash handler in place
1715 1714 sys.excepthook = old_excepthook
1716 1715 except SystemExit:
1717 1716 self.resetbuffer()
1718 1717 self.showtraceback()
1719 1718 warn("Type exit or quit to exit IPython "
1720 1719 "(%Exit or %Quit do so unconditionally).",level=1)
1721 1720 except self.custom_exceptions:
1722 1721 etype,value,tb = sys.exc_info()
1723 1722 self.CustomTB(etype,value,tb)
1724 1723 except:
1725 1724 self.showtraceback()
1726 1725 else:
1727 1726 outflag = 0
1728 1727 if softspace(sys.stdout, 0):
1729 1728 print
1730 1729 # Flush out code object which has been run (and source)
1731 1730 self.code_to_run = None
1732 1731 return outflag
1733 1732
1734 1733 def push(self, line):
1735 1734 """Push a line to the interpreter.
1736 1735
1737 1736 The line should not have a trailing newline; it may have
1738 1737 internal newlines. The line is appended to a buffer and the
1739 1738 interpreter's runsource() method is called with the
1740 1739 concatenated contents of the buffer as source. If this
1741 1740 indicates that the command was executed or invalid, the buffer
1742 1741 is reset; otherwise, the command is incomplete, and the buffer
1743 1742 is left as it was after the line was appended. The return
1744 1743 value is 1 if more input is required, 0 if the line was dealt
1745 1744 with in some way (this is the same as runsource()).
1746 1745 """
1747 1746
1748 1747 # autoindent management should be done here, and not in the
1749 1748 # interactive loop, since that one is only seen by keyboard input. We
1750 1749 # need this done correctly even for code run via runlines (which uses
1751 1750 # push).
1752 1751
1753 1752 #print 'push line: <%s>' % line # dbg
1754 1753 self.autoindent_update(line)
1755 1754
1756 1755 self.buffer.append(line)
1757 1756 more = self.runsource('\n'.join(self.buffer), self.filename)
1758 1757 if not more:
1759 1758 self.resetbuffer()
1760 1759 return more
1761 1760
1762 1761 def resetbuffer(self):
1763 1762 """Reset the input buffer."""
1764 1763 self.buffer[:] = []
1765 1764
1766 1765 def raw_input(self,prompt='',continue_prompt=False):
1767 1766 """Write a prompt and read a line.
1768 1767
1769 1768 The returned line does not include the trailing newline.
1770 1769 When the user enters the EOF key sequence, EOFError is raised.
1771 1770
1772 1771 Optional inputs:
1773 1772
1774 1773 - prompt(''): a string to be printed to prompt the user.
1775 1774
1776 1775 - continue_prompt(False): whether this line is the first one or a
1777 1776 continuation in a sequence of inputs.
1778 1777 """
1779 1778
1780 1779 line = raw_input_original(prompt)
1781 1780
1782 1781 # Try to be reasonably smart about not re-indenting pasted input more
1783 1782 # than necessary. We do this by trimming out the auto-indent initial
1784 1783 # spaces, if the user's actual input started itself with whitespace.
1785 1784 #debugx('self.buffer[-1]')
1786 1785
1787 1786 if self.autoindent:
1788 1787 if num_ini_spaces(line) > self.indent_current_nsp:
1789 1788 line = line[self.indent_current_nsp:]
1790 1789 self.indent_current_nsp = 0
1791 1790
1792 1791 # store the unfiltered input before the user has any chance to modify
1793 1792 # it.
1794 1793 if line.strip():
1795 1794 if continue_prompt:
1796 1795 self.input_hist_raw[-1] += '%s\n' % line
1797 1796 else:
1798 1797 self.input_hist_raw.append('%s\n' % line)
1799 1798
1800 1799 try:
1801 1800 lineout = self.prefilter(line,continue_prompt)
1802 1801 except:
1803 1802 # blanket except, in case a user-defined prefilter crashes, so it
1804 1803 # can't take all of ipython with it.
1805 1804 self.showtraceback()
1806 1805 return lineout
1807 1806
1808 1807 def split_user_input(self,line):
1809 1808 """Split user input into pre-char, function part and rest."""
1810 1809
1811 1810 lsplit = self.line_split.match(line)
1812 1811 if lsplit is None: # no regexp match returns None
1813 1812 try:
1814 1813 iFun,theRest = line.split(None,1)
1815 1814 except ValueError:
1816 1815 iFun,theRest = line,''
1817 1816 pre = re.match('^(\s*)(.*)',line).groups()[0]
1818 1817 else:
1819 1818 pre,iFun,theRest = lsplit.groups()
1820 1819
1821 1820 #print 'line:<%s>' % line # dbg
1822 1821 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun.strip(),theRest) # dbg
1823 1822 return pre,iFun.strip(),theRest
1824 1823
1825 1824 def _prefilter(self, line, continue_prompt):
1826 1825 """Calls different preprocessors, depending on the form of line."""
1827 1826
1828 1827 # All handlers *must* return a value, even if it's blank ('').
1829 1828
1830 1829 # Lines are NOT logged here. Handlers should process the line as
1831 1830 # needed, update the cache AND log it (so that the input cache array
1832 1831 # stays synced).
1833 1832
1834 1833 # This function is _very_ delicate, and since it's also the one which
1835 1834 # determines IPython's response to user input, it must be as efficient
1836 1835 # as possible. For this reason it has _many_ returns in it, trying
1837 1836 # always to exit as quickly as it can figure out what it needs to do.
1838 1837
1839 1838 # This function is the main responsible for maintaining IPython's
1840 1839 # behavior respectful of Python's semantics. So be _very_ careful if
1841 1840 # making changes to anything here.
1842 1841
1843 1842 #.....................................................................
1844 1843 # Code begins
1845 1844
1846 1845 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
1847 1846
1848 1847 # save the line away in case we crash, so the post-mortem handler can
1849 1848 # record it
1850 1849 self._last_input_line = line
1851 1850
1852 1851 #print '***line: <%s>' % line # dbg
1853 1852
1854 1853 # the input history needs to track even empty lines
1855 1854 stripped = line.strip()
1856 1855
1857 1856 if not stripped:
1858 1857 if not continue_prompt:
1859 1858 self.outputcache.prompt_count -= 1
1860 1859 return self.handle_normal(line,continue_prompt)
1861 1860 #return self.handle_normal('',continue_prompt)
1862 1861
1863 1862 # print '***cont',continue_prompt # dbg
1864 1863 # special handlers are only allowed for single line statements
1865 1864 if continue_prompt and not self.rc.multi_line_specials:
1866 1865 return self.handle_normal(line,continue_prompt)
1867 1866
1868 1867
1869 1868 # For the rest, we need the structure of the input
1870 1869 pre,iFun,theRest = self.split_user_input(line)
1871 1870
1872 1871 # See whether any pre-existing handler can take care of it
1873 1872
1874 1873 rewritten = self.hooks.input_prefilter(stripped)
1875 1874 if rewritten != stripped: # ok, some prefilter did something
1876 1875 rewritten = pre + rewritten # add indentation
1877 1876 return self.handle_normal(rewritten)
1878 1877
1879 1878 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1880 1879
1881 1880 # First check for explicit escapes in the last/first character
1882 1881 handler = None
1883 1882 if line[-1] == self.ESC_HELP:
1884 1883 handler = self.esc_handlers.get(line[-1]) # the ? can be at the end
1885 1884 if handler is None:
1886 1885 # look at the first character of iFun, NOT of line, so we skip
1887 1886 # leading whitespace in multiline input
1888 1887 handler = self.esc_handlers.get(iFun[0:1])
1889 1888 if handler is not None:
1890 1889 return handler(line,continue_prompt,pre,iFun,theRest)
1891 1890 # Emacs ipython-mode tags certain input lines
1892 1891 if line.endswith('# PYTHON-MODE'):
1893 1892 return self.handle_emacs(line,continue_prompt)
1894 1893
1895 1894 # Next, check if we can automatically execute this thing
1896 1895
1897 1896 # Allow ! in multi-line statements if multi_line_specials is on:
1898 1897 if continue_prompt and self.rc.multi_line_specials and \
1899 1898 iFun.startswith(self.ESC_SHELL):
1900 1899 return self.handle_shell_escape(line,continue_prompt,
1901 1900 pre=pre,iFun=iFun,
1902 1901 theRest=theRest)
1903 1902
1904 1903 # Let's try to find if the input line is a magic fn
1905 1904 oinfo = None
1906 1905 if hasattr(self,'magic_'+iFun):
1907 1906 # WARNING: _ofind uses getattr(), so it can consume generators and
1908 1907 # cause other side effects.
1909 1908 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1910 1909 if oinfo['ismagic']:
1911 1910 # Be careful not to call magics when a variable assignment is
1912 1911 # being made (ls='hi', for example)
1913 1912 if self.rc.automagic and \
1914 1913 (len(theRest)==0 or theRest[0] not in '!=()<>,') and \
1915 1914 (self.rc.multi_line_specials or not continue_prompt):
1916 1915 return self.handle_magic(line,continue_prompt,
1917 1916 pre,iFun,theRest)
1918 1917 else:
1919 1918 return self.handle_normal(line,continue_prompt)
1920 1919
1921 1920 # If the rest of the line begins with an (in)equality, assginment or
1922 1921 # function call, we should not call _ofind but simply execute it.
1923 1922 # This avoids spurious geattr() accesses on objects upon assignment.
1924 1923 #
1925 1924 # It also allows users to assign to either alias or magic names true
1926 1925 # python variables (the magic/alias systems always take second seat to
1927 1926 # true python code).
1928 1927 if theRest and theRest[0] in '!=()':
1929 1928 return self.handle_normal(line,continue_prompt)
1930 1929
1931 1930 if oinfo is None:
1932 1931 # let's try to ensure that _oinfo is ONLY called when autocall is
1933 1932 # on. Since it has inevitable potential side effects, at least
1934 1933 # having autocall off should be a guarantee to the user that no
1935 1934 # weird things will happen.
1936 1935
1937 1936 if self.rc.autocall:
1938 1937 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1939 1938 else:
1940 1939 # in this case, all that's left is either an alias or
1941 1940 # processing the line normally.
1942 1941 if iFun in self.alias_table:
1943 1942 # if autocall is off, by not running _ofind we won't know
1944 1943 # whether the given name may also exist in one of the
1945 1944 # user's namespace. At this point, it's best to do a
1946 1945 # quick check just to be sure that we don't let aliases
1947 1946 # shadow variables.
1948 1947 head = iFun.split('.',1)[0]
1949 1948 if head in self.user_ns or head in self.internal_ns \
1950 1949 or head in __builtin__.__dict__:
1951 1950 return self.handle_normal(line,continue_prompt)
1952 1951 else:
1953 1952 return self.handle_alias(line,continue_prompt,
1954 1953 pre,iFun,theRest)
1955 1954
1956 1955 else:
1957 1956 return self.handle_normal(line,continue_prompt)
1958 1957
1959 1958 if not oinfo['found']:
1960 1959 return self.handle_normal(line,continue_prompt)
1961 1960 else:
1962 1961 #print 'pre<%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1963 1962 if oinfo['isalias']:
1964 1963 return self.handle_alias(line,continue_prompt,
1965 1964 pre,iFun,theRest)
1966 1965
1967 1966 if (self.rc.autocall
1968 1967 and
1969 1968 (
1970 1969 #only consider exclusion re if not "," or ";" autoquoting
1971 1970 (pre == self.ESC_QUOTE or pre == self.ESC_QUOTE2
1972 1971 or pre == self.ESC_PAREN) or
1973 1972 (not self.re_exclude_auto.match(theRest)))
1974 1973 and
1975 1974 self.re_fun_name.match(iFun) and
1976 1975 callable(oinfo['obj'])) :
1977 1976 #print 'going auto' # dbg
1978 1977 return self.handle_auto(line,continue_prompt,
1979 1978 pre,iFun,theRest,oinfo['obj'])
1980 1979 else:
1981 1980 #print 'was callable?', callable(oinfo['obj']) # dbg
1982 1981 return self.handle_normal(line,continue_prompt)
1983 1982
1984 1983 # If we get here, we have a normal Python line. Log and return.
1985 1984 return self.handle_normal(line,continue_prompt)
1986 1985
1987 1986 def _prefilter_dumb(self, line, continue_prompt):
1988 1987 """simple prefilter function, for debugging"""
1989 1988 return self.handle_normal(line,continue_prompt)
1990 1989
1991 1990 # Set the default prefilter() function (this can be user-overridden)
1992 1991 prefilter = _prefilter
1993 1992
1994 1993 def handle_normal(self,line,continue_prompt=None,
1995 1994 pre=None,iFun=None,theRest=None):
1996 1995 """Handle normal input lines. Use as a template for handlers."""
1997 1996
1998 1997 # With autoindent on, we need some way to exit the input loop, and I
1999 1998 # don't want to force the user to have to backspace all the way to
2000 1999 # clear the line. The rule will be in this case, that either two
2001 2000 # lines of pure whitespace in a row, or a line of pure whitespace but
2002 2001 # of a size different to the indent level, will exit the input loop.
2003 2002
2004 2003 if (continue_prompt and self.autoindent and line.isspace() and
2005 2004 (0 < abs(len(line) - self.indent_current_nsp) <= 2 or
2006 2005 (self.buffer[-1]).isspace() )):
2007 2006 line = ''
2008 2007
2009 2008 self.log(line,continue_prompt)
2010 2009 return line
2011 2010
2012 2011 def handle_alias(self,line,continue_prompt=None,
2013 2012 pre=None,iFun=None,theRest=None):
2014 2013 """Handle alias input lines. """
2015 2014
2016 2015 # pre is needed, because it carries the leading whitespace. Otherwise
2017 2016 # aliases won't work in indented sections.
2018 2017 transformed = self.transform_alias(iFun, theRest)
2019 2018 line_out = '%s_ip.system(%s)' % (pre, make_quoted_expr( transformed ))
2020 2019 self.log(line_out,continue_prompt)
2021 2020 return line_out
2022 2021
2023 2022 def handle_shell_escape(self, line, continue_prompt=None,
2024 2023 pre=None,iFun=None,theRest=None):
2025 2024 """Execute the line in a shell, empty return value"""
2026 2025
2027 2026 #print 'line in :', `line` # dbg
2028 2027 # Example of a special handler. Others follow a similar pattern.
2029 2028 if line.lstrip().startswith('!!'):
2030 2029 # rewrite iFun/theRest to properly hold the call to %sx and
2031 2030 # the actual command to be executed, so handle_magic can work
2032 2031 # correctly
2033 2032 theRest = '%s %s' % (iFun[2:],theRest)
2034 2033 iFun = 'sx'
2035 2034 return self.handle_magic('%ssx %s' % (self.ESC_MAGIC,
2036 2035 line.lstrip()[2:]),
2037 2036 continue_prompt,pre,iFun,theRest)
2038 2037 else:
2039 2038 cmd=line.lstrip().lstrip('!')
2040 2039 line_out = '%s_ip.system(%s)' % (pre,make_quoted_expr(cmd))
2041 2040 # update cache/log and return
2042 2041 self.log(line_out,continue_prompt)
2043 2042 return line_out
2044 2043
2045 2044 def handle_magic(self, line, continue_prompt=None,
2046 2045 pre=None,iFun=None,theRest=None):
2047 2046 """Execute magic functions."""
2048 2047
2049 2048
2050 2049 cmd = '%s_ip.magic(%s)' % (pre,make_quoted_expr(iFun + " " + theRest))
2051 2050 self.log(cmd,continue_prompt)
2052 2051 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
2053 2052 return cmd
2054 2053
2055 2054 def handle_auto(self, line, continue_prompt=None,
2056 2055 pre=None,iFun=None,theRest=None,obj=None):
2057 2056 """Hande lines which can be auto-executed, quoting if requested."""
2058 2057
2059 2058 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2060 2059
2061 2060 # This should only be active for single-line input!
2062 2061 if continue_prompt:
2063 2062 self.log(line,continue_prompt)
2064 2063 return line
2065 2064
2066 2065 auto_rewrite = True
2067 2066
2068 2067 if pre == self.ESC_QUOTE:
2069 2068 # Auto-quote splitting on whitespace
2070 2069 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
2071 2070 elif pre == self.ESC_QUOTE2:
2072 2071 # Auto-quote whole string
2073 2072 newcmd = '%s("%s")' % (iFun,theRest)
2074 2073 elif pre == self.ESC_PAREN:
2075 2074 newcmd = '%s(%s)' % (iFun,",".join(theRest.split()))
2076 2075 else:
2077 2076 # Auto-paren.
2078 2077 # We only apply it to argument-less calls if the autocall
2079 2078 # parameter is set to 2. We only need to check that autocall is <
2080 2079 # 2, since this function isn't called unless it's at least 1.
2081 2080 if not theRest and (self.rc.autocall < 2):
2082 2081 newcmd = '%s %s' % (iFun,theRest)
2083 2082 auto_rewrite = False
2084 2083 else:
2085 2084 if theRest.startswith('['):
2086 2085 if hasattr(obj,'__getitem__'):
2087 2086 # Don't autocall in this case: item access for an object
2088 2087 # which is BOTH callable and implements __getitem__.
2089 2088 newcmd = '%s %s' % (iFun,theRest)
2090 2089 auto_rewrite = False
2091 2090 else:
2092 2091 # if the object doesn't support [] access, go ahead and
2093 2092 # autocall
2094 2093 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
2095 2094 elif theRest.endswith(';'):
2096 2095 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
2097 2096 else:
2098 2097 newcmd = '%s(%s)' % (iFun.rstrip(), theRest)
2099 2098
2100 2099 if auto_rewrite:
2101 2100 print >>Term.cout, self.outputcache.prompt1.auto_rewrite() + newcmd
2102 2101 # log what is now valid Python, not the actual user input (without the
2103 2102 # final newline)
2104 2103 self.log(newcmd,continue_prompt)
2105 2104 return newcmd
2106 2105
2107 2106 def handle_help(self, line, continue_prompt=None,
2108 2107 pre=None,iFun=None,theRest=None):
2109 2108 """Try to get some help for the object.
2110 2109
2111 2110 obj? or ?obj -> basic information.
2112 2111 obj?? or ??obj -> more details.
2113 2112 """
2114 2113
2115 2114 # We need to make sure that we don't process lines which would be
2116 2115 # otherwise valid python, such as "x=1 # what?"
2117 2116 try:
2118 2117 codeop.compile_command(line)
2119 2118 except SyntaxError:
2120 2119 # We should only handle as help stuff which is NOT valid syntax
2121 2120 if line[0]==self.ESC_HELP:
2122 2121 line = line[1:]
2123 2122 elif line[-1]==self.ESC_HELP:
2124 2123 line = line[:-1]
2125 2124 self.log('#?'+line)
2126 2125 if line:
2127 2126 self.magic_pinfo(line)
2128 2127 else:
2129 2128 page(self.usage,screen_lines=self.rc.screen_length)
2130 2129 return '' # Empty string is needed here!
2131 2130 except:
2132 2131 # Pass any other exceptions through to the normal handler
2133 2132 return self.handle_normal(line,continue_prompt)
2134 2133 else:
2135 2134 # If the code compiles ok, we should handle it normally
2136 2135 return self.handle_normal(line,continue_prompt)
2137 2136
2138 2137 def getapi(self):
2139 2138 """ Get an IPApi object for this shell instance
2140 2139
2141 2140 Getting an IPApi object is always preferable to accessing the shell
2142 2141 directly, but this holds true especially for extensions.
2143 2142
2144 2143 It should always be possible to implement an extension with IPApi
2145 2144 alone. If not, contact maintainer to request an addition.
2146 2145
2147 2146 """
2148 2147 return self.api
2149 2148
2150 2149 def handle_emacs(self,line,continue_prompt=None,
2151 2150 pre=None,iFun=None,theRest=None):
2152 2151 """Handle input lines marked by python-mode."""
2153 2152
2154 2153 # Currently, nothing is done. Later more functionality can be added
2155 2154 # here if needed.
2156 2155
2157 2156 # The input cache shouldn't be updated
2158 2157
2159 2158 return line
2160 2159
2161 2160 def mktempfile(self,data=None):
2162 2161 """Make a new tempfile and return its filename.
2163 2162
2164 2163 This makes a call to tempfile.mktemp, but it registers the created
2165 2164 filename internally so ipython cleans it up at exit time.
2166 2165
2167 2166 Optional inputs:
2168 2167
2169 2168 - data(None): if data is given, it gets written out to the temp file
2170 2169 immediately, and the file is closed again."""
2171 2170
2172 2171 filename = tempfile.mktemp('.py','ipython_edit_')
2173 2172 self.tempfiles.append(filename)
2174 2173
2175 2174 if data:
2176 2175 tmp_file = open(filename,'w')
2177 2176 tmp_file.write(data)
2178 2177 tmp_file.close()
2179 2178 return filename
2180 2179
2181 2180 def write(self,data):
2182 2181 """Write a string to the default output"""
2183 2182 Term.cout.write(data)
2184 2183
2185 2184 def write_err(self,data):
2186 2185 """Write a string to the default error output"""
2187 2186 Term.cerr.write(data)
2188 2187
2189 2188 def exit(self):
2190 2189 """Handle interactive exit.
2191 2190
2192 2191 This method sets the exit_now attribute."""
2193 2192
2194 2193 if self.rc.confirm_exit:
2195 2194 if ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2196 2195 self.exit_now = True
2197 2196 else:
2198 2197 self.exit_now = True
2199 2198 return self.exit_now
2200 2199
2201 2200 def safe_execfile(self,fname,*where,**kw):
2202 2201 fname = os.path.expanduser(fname)
2203 2202
2204 2203 # find things also in current directory
2205 2204 dname = os.path.dirname(fname)
2206 2205 if not sys.path.count(dname):
2207 2206 sys.path.append(dname)
2208 2207
2209 2208 try:
2210 2209 xfile = open(fname)
2211 2210 except:
2212 2211 print >> Term.cerr, \
2213 2212 'Could not open file <%s> for safe execution.' % fname
2214 2213 return None
2215 2214
2216 2215 kw.setdefault('islog',0)
2217 2216 kw.setdefault('quiet',1)
2218 2217 kw.setdefault('exit_ignore',0)
2219 2218 first = xfile.readline()
2220 2219 loghead = str(self.loghead_tpl).split('\n',1)[0].strip()
2221 2220 xfile.close()
2222 2221 # line by line execution
2223 2222 if first.startswith(loghead) or kw['islog']:
2224 2223 print 'Loading log file <%s> one line at a time...' % fname
2225 2224 if kw['quiet']:
2226 2225 stdout_save = sys.stdout
2227 2226 sys.stdout = StringIO.StringIO()
2228 2227 try:
2229 2228 globs,locs = where[0:2]
2230 2229 except:
2231 2230 try:
2232 2231 globs = locs = where[0]
2233 2232 except:
2234 2233 globs = locs = globals()
2235 2234 badblocks = []
2236 2235
2237 2236 # we also need to identify indented blocks of code when replaying
2238 2237 # logs and put them together before passing them to an exec
2239 2238 # statement. This takes a bit of regexp and look-ahead work in the
2240 2239 # file. It's easiest if we swallow the whole thing in memory
2241 2240 # first, and manually walk through the lines list moving the
2242 2241 # counter ourselves.
2243 2242 indent_re = re.compile('\s+\S')
2244 2243 xfile = open(fname)
2245 2244 filelines = xfile.readlines()
2246 2245 xfile.close()
2247 2246 nlines = len(filelines)
2248 2247 lnum = 0
2249 2248 while lnum < nlines:
2250 2249 line = filelines[lnum]
2251 2250 lnum += 1
2252 2251 # don't re-insert logger status info into cache
2253 2252 if line.startswith('#log#'):
2254 2253 continue
2255 2254 else:
2256 2255 # build a block of code (maybe a single line) for execution
2257 2256 block = line
2258 2257 try:
2259 2258 next = filelines[lnum] # lnum has already incremented
2260 2259 except:
2261 2260 next = None
2262 2261 while next and indent_re.match(next):
2263 2262 block += next
2264 2263 lnum += 1
2265 2264 try:
2266 2265 next = filelines[lnum]
2267 2266 except:
2268 2267 next = None
2269 2268 # now execute the block of one or more lines
2270 2269 try:
2271 2270 exec block in globs,locs
2272 2271 except SystemExit:
2273 2272 pass
2274 2273 except:
2275 2274 badblocks.append(block.rstrip())
2276 2275 if kw['quiet']: # restore stdout
2277 2276 sys.stdout.close()
2278 2277 sys.stdout = stdout_save
2279 2278 print 'Finished replaying log file <%s>' % fname
2280 2279 if badblocks:
2281 2280 print >> sys.stderr, ('\nThe following lines/blocks in file '
2282 2281 '<%s> reported errors:' % fname)
2283 2282
2284 2283 for badline in badblocks:
2285 2284 print >> sys.stderr, badline
2286 2285 else: # regular file execution
2287 2286 try:
2288 2287 execfile(fname,*where)
2289 2288 except SyntaxError:
2290 2289 self.showsyntaxerror()
2291 2290 warn('Failure executing file: <%s>' % fname)
2292 2291 except SystemExit,status:
2293 2292 if not kw['exit_ignore']:
2294 2293 self.showtraceback()
2295 2294 warn('Failure executing file: <%s>' % fname)
2296 2295 except:
2297 2296 self.showtraceback()
2298 2297 warn('Failure executing file: <%s>' % fname)
2299 2298
2300 2299 #************************* end of file <iplib.py> *****************************
@@ -1,641 +1,641 b''
1 1 # -*- coding: utf-8 -*-
2 2 #*****************************************************************************
3 3 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
4 4 #
5 5 # Distributed under the terms of the BSD License. The full license is in
6 6 # the file COPYING, distributed as part of this software.
7 7 #*****************************************************************************
8 8
9 # $Id: usage.py 1301 2006-05-15 17:21:55Z vivainio $
9 # $Id: usage.py 1332 2006-05-30 01:41:28Z fperez $
10 10
11 11 from IPython import Release
12 12 __author__ = '%s <%s>' % Release.authors['Fernando']
13 13 __license__ = Release.license
14 14 __version__ = Release.version
15 15
16 16 __doc__ = """
17 17 IPython -- An enhanced Interactive Python
18 18 =========================================
19 19
20 20 A Python shell with automatic history (input and output), dynamic object
21 21 introspection, easier configuration, command completion, access to the system
22 22 shell and more.
23 23
24 24 IPython can also be embedded in running programs. See EMBEDDING below.
25 25
26 26
27 27 USAGE
28 28 ipython [options] files
29 29
30 30 If invoked with no options, it executes all the files listed in
31 31 sequence and drops you into the interpreter while still acknowledging
32 32 any options you may have set in your ipythonrc file. This behavior is
33 33 different from standard Python, which when called as python -i will
34 34 only execute one file and will ignore your configuration setup.
35 35
36 36 Please note that some of the configuration options are not available at
37 37 the command line, simply because they are not practical here. Look into
38 38 your ipythonrc configuration file for details on those. This file
39 39 typically installed in the $HOME/.ipython directory.
40 40
41 41 For Windows users, $HOME resolves to C:\\Documents and
42 42 Settings\\YourUserName in most instances, and _ipython is used instead
43 43 of .ipython, since some Win32 programs have problems with dotted names
44 44 in directories.
45 45
46 46 In the rest of this text, we will refer to this directory as
47 47 IPYTHONDIR.
48 48
49 49
50 50 SPECIAL THREADING OPTIONS
51 51 The following special options are ONLY valid at the beginning of the
52 52 command line, and not later. This is because they control the initial-
53 53 ization of ipython itself, before the normal option-handling mechanism
54 54 is active.
55 55
56 56 -gthread, -qthread, -wthread, -pylab
57 57
58 58 Only ONE of these can be given, and it can only be given as the
59 59 first option passed to IPython (it will have no effect in any
60 60 other position). They provide threading support for the GTK, QT
61 61 and WXWidgets toolkits, and for the matplotlib library.
62 62
63 63 With any of the first three options, IPython starts running a
64 64 separate thread for the graphical toolkit's operation, so that
65 65 you can open and control graphical elements from within an
66 66 IPython command line, without blocking. All three provide
67 67 essentially the same functionality, respectively for GTK, QT and
68 68 WXWidgets (via their Python interfaces).
69 69
70 70 Note that with -wthread, you can additionally use the -wxversion
71 71 option to request a specific version of wx to be used. This
72 72 requires that you have the 'wxversion' Python module installed,
73 73 which is part of recent wxPython distributions.
74 74
75 75 If -pylab is given, IPython loads special support for the mat-
76 76 plotlib library (http://matplotlib.sourceforge.net), allowing
77 77 interactive usage of any of its backends as defined in the
78 78 user's .matplotlibrc file. It automatically activates GTK, QT
79 79 or WX threading for IPyhton if the choice of matplotlib backend
80 80 requires it. It also modifies the %run command to correctly
81 81 execute (without blocking) any matplotlib-based script which
82 82 calls show() at the end.
83 83
84 84 -tk The -g/q/wthread options, and -pylab (if matplotlib is
85 85 configured to use GTK, QT or WX), will normally block Tk
86 86 graphical interfaces. This means that when GTK, QT or WX
87 87 threading is active, any attempt to open a Tk GUI will result in
88 88 a dead window, and possibly cause the Python interpreter to
89 89 crash. An extra option, -tk, is available to address this
90 90 issue. It can ONLY be given as a SECOND option after any of the
91 91 above (-gthread, -qthread, -wthread or -pylab).
92 92
93 93 If -tk is given, IPython will try to coordinate Tk threading
94 94 with GTK, QT or WX. This is however potentially unreliable, and
95 95 you will have to test on your platform and Python configuration
96 96 to determine whether it works for you. Debian users have
97 97 reported success, apparently due to the fact that Debian builds
98 98 all of Tcl, Tk, Tkinter and Python with pthreads support. Under
99 99 other Linux environments (such as Fedora Core 2/3), this option
100 100 has caused random crashes and lockups of the Python interpreter.
101 101 Under other operating systems (Mac OSX and Windows), you'll need
102 102 to try it to find out, since currently no user reports are
103 103 available.
104 104
105 105 There is unfortunately no way for IPython to determine at run-
106 106 time whether -tk will work reliably or not, so you will need to
107 107 do some experiments before relying on it for regular work.
108 108
109 109 A WARNING ABOUT SIGNALS AND THREADS
110 110
111 111 When any of the thread systems (GTK, QT or WX) are active, either
112 112 directly or via -pylab with a threaded backend, it is impossible to
113 113 interrupt long-running Python code via Ctrl-C. IPython can not pass
114 114 the KeyboardInterrupt exception (or the underlying SIGINT) across
115 115 threads, so any long-running process started from IPython will run to
116 116 completion, or will have to be killed via an external (OS-based)
117 117 mechanism.
118 118
119 119 To the best of my knowledge, this limitation is imposed by the Python
120 120 interpreter itself, and it comes from the difficulty of writing
121 121 portable signal/threaded code. If any user is an expert on this topic
122 122 and can suggest a better solution, I would love to hear about it. In
123 123 the IPython sources, look at the Shell.py module, and in particular at
124 124 the runcode() method.
125 125
126 126 REGULAR OPTIONS
127 127 After the above threading options have been given, regular options can
128 128 follow in any order. All options can be abbreviated to their shortest
129 129 non-ambiguous form and are case-sensitive. One or two dashes can be
130 130 used. Some options have an alternate short form, indicated after a |.
131 131
132 132 Most options can also be set from your ipythonrc configuration file.
133 133 See the provided examples for assistance. Options given on the comman-
134 134 dline override the values set in the ipythonrc file.
135 135
136 136 All options with a [no] prepended can be specified in negated form
137 137 (using -nooption instead of -option) to turn the feature off.
138 138
139 139 -h, --help
140 140 Show summary of options.
141 141
142 142 -pylab This can only be given as the first option passed to IPython (it
143 143 will have no effect in any other position). It adds special sup-
144 144 port for the matplotlib library (http://matplotlib.source-
145 145 forge.net), allowing interactive usage of any of its backends as
146 146 defined in the user's .matplotlibrc file. It automatically
147 147 activates GTK or WX threading for IPyhton if the choice of mat-
148 148 plotlib backend requires it. It also modifies the @run command
149 149 to correctly execute (without blocking) any matplotlib-based
150 150 script which calls show() at the end.
151 151
152 152 -autocall <val>
153 153 Make IPython automatically call any callable object even if you
154 154 didn't type explicit parentheses. For example, 'str 43' becomes
155 155 'str(43)' automatically. The value can be '0' to disable the
156 156 feature, '1' for 'smart' autocall, where it is not applied if
157 157 there are no more arguments on the line, and '2' for 'full'
158 158 autocall, where all callable objects are automatically called
159 159 (even if no arguments are present). The default is '1'.
160 160
161 161 -[no]autoindent
162 162 Turn automatic indentation on/off.
163 163
164 164 -[no]automagic
165 165 Make magic commands automatic (without needing their first char-
166 166 acter to be %). Type %magic at the IPython prompt for more
167 167 information.
168 168
169 169 -[no]autoedit_syntax
170 170 When a syntax error occurs after editing a file, automatically
171 171 open the file to the trouble causing line for convenient fixing.
172 172
173 173 -[no]banner
174 174 Print the intial information banner (default on).
175 175
176 176 -c <command>
177 177 Execute the given command string, and set sys.argv to ['c'].
178 178 This is similar to the -c option in the normal Python inter-
179 179 preter.
180 180
181 181 -cache_size|cs <n>
182 182 Size of the output cache (maximum number of entries to hold in
183 183 memory). The default is 1000, you can change it permanently in
184 184 your config file. Setting it to 0 completely disables the
185 185 caching system, and the minimum value accepted is 20 (if you
186 186 provide a value less than 20, it is reset to 0 and a warning is
187 187 issued). This limit is defined because otherwise you'll spend
188 188 more time re-flushing a too small cache than working.
189 189
190 190 -classic|cl
191 191 Gives IPython a similar feel to the classic Python prompt.
192 192
193 193 -colors <scheme>
194 194 Color scheme for prompts and exception reporting. Currently
195 195 implemented: NoColor, Linux, and LightBG.
196 196
197 197 -[no]color_info
198 198 IPython can display information about objects via a set of func-
199 199 tions, and optionally can use colors for this, syntax highlight-
200 200 ing source code and various other elements. However, because
201 201 this information is passed through a pager (like 'less') and
202 202 many pagers get confused with color codes, this option is off by
203 203 default. You can test it and turn it on permanently in your
204 204 ipythonrc file if it works for you. As a reference, the 'less'
205 205 pager supplied with Mandrake 8.2 works ok, but that in RedHat
206 206 7.2 doesn't.
207 207
208 208 Test it and turn it on permanently if it works with your system.
209 209 The magic function @color_info allows you to toggle this inter-
210 210 actively for testing.
211 211
212 212 -[no]confirm_exit
213 213 Set to confirm when you try to exit IPython with an EOF (Con-
214 214 trol-D in Unix, Control-Z/Enter in Windows). Note that using the
215 215 magic functions @Exit or @Quit you can force a direct exit,
216 216 bypassing any confirmation.
217 217
218 218 -[no]debug
219 219 Show information about the loading process. Very useful to pin
220 220 down problems with your configuration files or to get details
221 221 about session restores.
222 222
223 223 -[no]deep_reload
224 224 IPython can use the deep_reload module which reloads changes in
225 225 modules recursively (it replaces the reload() function, so you
226 226 don't need to change anything to use it). deep_reload() forces a
227 227 full reload of modules whose code may have changed, which the
228 228 default reload() function does not.
229 229
230 230 When deep_reload is off, IPython will use the normal reload(),
231 231 but deep_reload will still be available as dreload(). This fea-
232 232 ture is off by default [which means that you have both normal
233 233 reload() and dreload()].
234 234
235 235 -editor <name>
236 236 Which editor to use with the @edit command. By default, IPython
237 237 will honor your EDITOR environment variable (if not set, vi is
238 238 the Unix default and notepad the Windows one). Since this editor
239 239 is invoked on the fly by IPython and is meant for editing small
240 240 code snippets, you may want to use a small, lightweight editor
241 241 here (in case your default EDITOR is something like Emacs).
242 242
243 243 -ipythondir <name>
244 244 The name of your IPython configuration directory IPYTHONDIR.
245 245 This can also be specified through the environment variable
246 246 IPYTHONDIR.
247 247
248 248 -log|l Generate a log file of all input. The file is named
249 249 ipython_log.py in your current directory (which prevents logs
250 250 from multiple IPython sessions from trampling each other). You
251 251 can use this to later restore a session by loading your logfile
252 252 as a file to be executed with option -logplay (see below).
253 253
254 254 -logfile|lf
255 255 Specify the name of your logfile.
256 256
257 257 -logplay|lp
258 258 Replay a previous log. For restoring a session as close as pos-
259 259 sible to the state you left it in, use this option (don't just
260 260 run the logfile). With -logplay, IPython will try to reconstruct
261 261 the previous working environment in full, not just execute the
262 262 commands in the logfile.
263 263 When a session is restored, logging is automatically turned on
264 264 again with the name of the logfile it was invoked with (it is
265 265 read from the log header). So once you've turned logging on for
266 266 a session, you can quit IPython and reload it as many times as
267 267 you want and it will continue to log its history and restore
268 268 from the beginning every time.
269 269
270 270 Caveats: there are limitations in this option. The history vari-
271 271 ables _i*,_* and _dh don't get restored properly. In the future
272 272 we will try to implement full session saving by writing and
273 273 retrieving a failed because of inherent limitations of Python's
274 274 Pickle module, so this may have to wait.
275 275
276 276 -[no]messages
277 277 Print messages which IPython collects about its startup process
278 278 (default on).
279 279
280 280 -[no]pdb
281 281 Automatically call the pdb debugger after every uncaught excep-
282 282 tion. If you are used to debugging using pdb, this puts you
283 283 automatically inside of it after any call (either in IPython or
284 284 in code called by it) which triggers an exception which goes
285 285 uncaught.
286 286
287 287 -[no]pprint
288 288 IPython can optionally use the pprint (pretty printer) module
289 289 for displaying results. pprint tends to give a nicer display of
290 290 nested data structures. If you like it, you can turn it on per-
291 291 manently in your config file (default off).
292 292
293 293 -profile|p <name>
294 294 Assume that your config file is ipythonrc-<name> (looks in cur-
295 295 rent dir first, then in IPYTHONDIR). This is a quick way to keep
296 296 and load multiple config files for different tasks, especially
297 297 if you use the include option of config files. You can keep a
298 298 basic IPYTHONDIR/ipythonrc file and then have other 'profiles'
299 299 which include this one and load extra things for particular
300 300 tasks. For example:
301 301
302 302 1) $HOME/.ipython/ipythonrc : load basic things you always want.
303 303 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-
304 304 related modules.
305 305 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
306 306 plotting modules.
307 307
308 308 Since it is possible to create an endless loop by having circu-
309 309 lar file inclusions, IPython will stop if it reaches 15 recur-
310 310 sive inclusions.
311 311
312 312 -prompt_in1|pi1 <string>
313 313 Specify the string used for input prompts. Note that if you are
314 314 using numbered prompts, the number is represented with a '\#' in
315 315 the string. Don't forget to quote strings with spaces embedded
316 316 in them. Default: 'In [\#]:'.
317 317
318 318 Most bash-like escapes can be used to customize IPython's
319 319 prompts, as well as a few additional ones which are IPython-spe-
320 320 cific. All valid prompt escapes are described in detail in the
321 321 Customization section of the IPython HTML/PDF manual.
322 322
323 323 -prompt_in2|pi2 <string>
324 324 Similar to the previous option, but used for the continuation
325 325 prompts. The special sequence '\D' is similar to '\#', but with
326 326 all digits replaced dots (so you can have your continuation
327 327 prompt aligned with your input prompt). Default: ' .\D.:'
328 328 (note three spaces at the start for alignment with 'In [\#]').
329 329
330 330 -prompt_out|po <string>
331 331 String used for output prompts, also uses numbers like
332 332 prompt_in1. Default: 'Out[\#]:'.
333 333
334 334 -quick Start in bare bones mode (no config file loaded).
335 335
336 336 -rcfile <name>
337 337 Name of your IPython resource configuration file. normally
338 338 IPython loads ipythonrc (from current directory) or
339 339 IPYTHONDIR/ipythonrc. If the loading of your config file fails,
340 340 IPython starts with a bare bones configuration (no modules
341 341 loaded at all).
342 342
343 343 -[no]readline
344 344 Use the readline library, which is needed to support name com-
345 345 pletion and command history, among other things. It is enabled
346 346 by default, but may cause problems for users of X/Emacs in
347 347 Python comint or shell buffers.
348 348
349 349 Note that emacs 'eterm' buffers (opened with M-x term) support
350 350 IPython's readline and syntax coloring fine, only 'emacs' (M-x
351 351 shell and C-c !) buffers do not.
352 352
353 353 -screen_length|sl <n>
354 354 Number of lines of your screen. This is used to control print-
355 355 ing of very long strings. Strings longer than this number of
356 356 lines will be sent through a pager instead of directly printed.
357 357
358 358 The default value for this is 0, which means IPython will auto-
359 359 detect your screen size every time it needs to print certain
360 360 potentially long strings (this doesn't change the behavior of
361 361 the 'print' keyword, it's only triggered internally). If for
362 362 some reason this isn't working well (it needs curses support),
363 363 specify it yourself. Otherwise don't change the default.
364 364
365 365 -separate_in|si <string>
366 366 Separator before input prompts. Default '0.
367 367
368 368 -separate_out|so <string>
369 369 Separator before output prompts. Default: 0 (nothing).
370 370
371 371 -separate_out2|so2 <string>
372 372 Separator after output prompts. Default: 0 (nothing).
373 373
374 374 -nosep Shorthand for '-separate_in 0 -separate_out 0 -separate_out2 0'.
375 375 Simply removes all input/output separators.
376 376
377 377 -upgrade
378 378 Allows you to upgrade your IPYTHONDIR configuration when you
379 379 install a new version of IPython. Since new versions may
380 380 include new command lines options or example files, this copies
381 381 updated ipythonrc-type files. However, it backs up (with a .old
382 382 extension) all files which it overwrites so that you can merge
383 383 back any custimizations you might have in your personal files.
384 384
385 385 -Version
386 386 Print version information and exit.
387 387
388 388 -wxversion <string>
389 389 Select a specific version of wxPython (used in conjunction with
390 390 -wthread). Requires the wxversion module, part of recent
391 391 wxPython distributions.
392 392
393 393 -xmode <modename>
394 394 Mode for exception reporting. The valid modes are Plain, Con-
395 395 text, and Verbose.
396 396
397 397 - Plain: similar to python's normal traceback printing.
398 398
399 399 - Context: prints 5 lines of context source code around each
400 400 line in the traceback.
401 401
402 402 - Verbose: similar to Context, but additionally prints the vari-
403 403 ables currently visible where the exception happened (shortening
404 404 their strings if too long). This can potentially be very slow,
405 405 if you happen to have a huge data structure whose string repre-
406 406 sentation is complex to compute. Your computer may appear to
407 407 freeze for a while with cpu usage at 100%. If this occurs, you
408 408 can cancel the traceback with Ctrl-C (maybe hitting it more than
409 409 once).
410 410
411 411
412 412 EMBEDDING
413 413 It is possible to start an IPython instance inside your own Python pro-
414 414 grams. In the documentation example files there are some illustrations
415 415 on how to do this.
416 416
417 417 This feature allows you to evalutate dynamically the state of your
418 418 code, operate with your variables, analyze them, etc. Note however
419 419 that any changes you make to values while in the shell do NOT propagate
420 420 back to the running code, so it is safe to modify your values because
421 421 you won't break your code in bizarre ways by doing so.
422 422 """
423 423
424 424 cmd_line_usage = __doc__
425 425
426 426 #---------------------------------------------------------------------------
427 427 interactive_usage = """
428 428 IPython -- An enhanced Interactive Python
429 429 =========================================
430 430
431 431 IPython offers a combination of convenient shell features, special commands
432 432 and a history mechanism for both input (command history) and output (results
433 433 caching, similar to Mathematica). It is intended to be a fully compatible
434 434 replacement for the standard Python interpreter, while offering vastly
435 435 improved functionality and flexibility.
436 436
437 437 At your system command line, type 'ipython -help' to see the command line
438 438 options available. This document only describes interactive features.
439 439
440 440 Warning: IPython relies on the existence of a global variable called __IP which
441 441 controls the shell itself. If you redefine __IP to anything, bizarre behavior
442 442 will quickly occur.
443 443
444 444 MAIN FEATURES
445 445
446 446 * Access to the standard Python help. As of Python 2.1, a help system is
447 447 available with access to object docstrings and the Python manuals. Simply
448 448 type 'help' (no quotes) to access it.
449 449
450 450 * Magic commands: type %magic for information on the magic subsystem.
451 451
452 452 * System command aliases, via the %alias command or the ipythonrc config file.
453 453
454 454 * Dynamic object information:
455 455
456 456 Typing ?word or word? prints detailed information about an object. If
457 457 certain strings in the object are too long (docstrings, code, etc.) they get
458 458 snipped in the center for brevity.
459 459
460 460 Typing ??word or word?? gives access to the full information without
461 461 snipping long strings. Long strings are sent to the screen through the less
462 462 pager if longer than the screen, printed otherwise.
463 463
464 464 The ?/?? system gives access to the full source code for any object (if
465 465 available), shows function prototypes and other useful information.
466 466
467 467 If you just want to see an object's docstring, type '%pdoc object' (without
468 468 quotes, and without % if you have automagic on).
469 469
470 470 Both %pdoc and ?/?? give you access to documentation even on things which are
471 471 not explicitely defined. Try for example typing {}.get? or after import os,
472 472 type os.path.abspath??. The magic functions %pdef, %source and %file operate
473 473 similarly.
474 474
475 475 * Completion in the local namespace, by typing TAB at the prompt.
476 476
477 477 At any time, hitting tab will complete any available python commands or
478 478 variable names, and show you a list of the possible completions if there's
479 479 no unambiguous one. It will also complete filenames in the current directory.
480 480
481 481 This feature requires the readline and rlcomplete modules, so it won't work
482 482 if your Python lacks readline support (such as under Windows).
483 483
484 484 * Search previous command history in two ways (also requires readline):
485 485
486 486 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
487 487 search through only the history items that match what you've typed so
488 488 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
489 489 normal arrow keys.
490 490
491 491 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
492 492 your history for lines that match what you've typed so far, completing as
493 493 much as it can.
494 494
495 495 * Persistent command history across sessions (readline required).
496 496
497 497 * Logging of input with the ability to save and restore a working session.
498 498
499 499 * System escape with !. Typing !ls will run 'ls' in the current directory.
500 500
501 501 * The reload command does a 'deep' reload of a module: changes made to the
502 502 module since you imported will actually be available without having to exit.
503 503
504 504 * Verbose and colored exception traceback printouts. See the magic xmode and
505 505 xcolor functions for details (just type %magic).
506 506
507 507 * Input caching system:
508 508
509 509 IPython offers numbered prompts (In/Out) with input and output caching. All
510 510 input is saved and can be retrieved as variables (besides the usual arrow
511 511 key recall).
512 512
513 513 The following GLOBAL variables always exist (so don't overwrite them!):
514 514 _i: stores previous input.
515 515 _ii: next previous.
516 516 _iii: next-next previous.
517 517 _ih : a list of all input _ih[n] is the input from line n.
518 518
519 519 Additionally, global variables named _i<n> are dynamically created (<n>
520 520 being the prompt counter), such that _i<n> == _ih[<n>]
521 521
522 522 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
523 523
524 524 You can create macros which contain multiple input lines from this history,
525 525 for later re-execution, with the %macro function.
526 526
527 527 The history function %hist allows you to see any part of your input history
528 528 by printing a range of the _i variables. Note that inputs which contain
529 529 magic functions (%) appear in the history with a prepended comment. This is
530 530 because they aren't really valid Python code, so you can't exec them.
531 531
532 532 * Output caching system:
533 533
534 534 For output that is returned from actions, a system similar to the input
535 535 cache exists but using _ instead of _i. Only actions that produce a result
536 536 (NOT assignments, for example) are cached. If you are familiar with
537 537 Mathematica, IPython's _ variables behave exactly like Mathematica's %
538 538 variables.
539 539
540 540 The following GLOBAL variables always exist (so don't overwrite them!):
541 541 _ (one underscore): previous output.
542 542 __ (two underscores): next previous.
543 543 ___ (three underscores): next-next previous.
544 544
545 545 Global variables named _<n> are dynamically created (<n> being the prompt
546 546 counter), such that the result of output <n> is always available as _<n>.
547 547
548 548 Finally, a global dictionary named _oh exists with entries for all lines
549 549 which generated output.
550 550
551 551 * Directory history:
552 552
553 553 Your history of visited directories is kept in the global list _dh, and the
554 554 magic %cd command can be used to go to any entry in that list.
555 555
556 556 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
557 557
558 558 1. Auto-parentheses
559 559 Callable objects (i.e. functions, methods, etc) can be invoked like
560 560 this (notice the commas between the arguments):
561 561 >>> callable_ob arg1, arg2, arg3
562 562 and the input will be translated to this:
563 563 --> callable_ob(arg1, arg2, arg3)
564 564 You can force auto-parentheses by using '/' as the first character
565 565 of a line. For example:
566 566 >>> /globals # becomes 'globals()'
567 567 Note that the '/' MUST be the first character on the line! This
568 568 won't work:
569 569 >>> print /globals # syntax error
570 570
571 571 In most cases the automatic algorithm should work, so you should
572 572 rarely need to explicitly invoke /. One notable exception is if you
573 573 are trying to call a function with a list of tuples as arguments (the
574 574 parenthesis will confuse IPython):
575 575 In [1]: zip (1,2,3),(4,5,6) # won't work
576 576 but this will work:
577 577 In [2]: /zip (1,2,3),(4,5,6)
578 578 ------> zip ((1,2,3),(4,5,6))
579 579 Out[2]= [(1, 4), (2, 5), (3, 6)]
580 580
581 581 IPython tells you that it has altered your command line by
582 582 displaying the new command line preceded by -->. e.g.:
583 583 In [18]: callable list
584 584 -------> callable (list)
585 585
586 586 2. Auto-Quoting
587 587 You can force auto-quoting of a function's arguments by using ',' as
588 588 the first character of a line. For example:
589 589 >>> ,my_function /home/me # becomes my_function("/home/me")
590 590
591 591 If you use ';' instead, the whole argument is quoted as a single
592 592 string (while ',' splits on whitespace):
593 593 >>> ,my_function a b c # becomes my_function("a","b","c")
594 594 >>> ;my_function a b c # becomes my_function("a b c")
595 595
596 596 Note that the ',' MUST be the first character on the line! This
597 597 won't work:
598 598 >>> x = ,my_function /home/me # syntax error
599 599 """
600 600
601 601 quick_reference = r"""
602 602 IPython -- An enhanced Interactive Python - Quick Reference Card
603 603 ================================================================
604 604
605 605 obj?, obj??, ?obj,??obj : Get help, or more help for object
606 606 ?os.p* : List names in os starting with p
607 607
608 608 Example magic:
609 609
610 610 %alias d ls -F : 'd' is now an alias for 'ls -F'
611 611 alias d ls -F : Works if 'alias' not a python name
612 612 alist = %alias : Get list of aliases to 'alist'
613 613
614 614 System commands:
615 615
616 616 !cp a.txt b/ : System command escape, calls os.system()
617 617 cp a.txt b/ : after %rehashx, most system commands work without !
618 618 cp ${f}.txt $bar : Variable expansion in magics and system commands
619 619 files = !ls /usr : Capture sytem command output
620 620 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
621 621 cd /usr/share : Obvious, also 'cd d:\home\_ipython' works
622 622
623 623 History:
624 624
625 625 _i, _ii, _iii : Previous, next previous, next next previous input
626 626 _ih[4], _ih[2:5] : Input history line 4, lines 2-4
627 627 _, __, ___ : previous, next previous, next next previous output
628 628 _dh : Directory history
629 629 _oh : Output history
630 630 %hist : Command history
631 631
632 632 Autocall:
633 633
634 634 f 1,2 : f(1,2)
635 635 /f 1,2 : f(1,2) (forced autoparen)
636 636 ,f 1 2 : f("1","2")
637 637 ;f 1 2 : f("1 2")
638 638
639 639 """
640 640
641 641
1 NO CONTENT: modified file
The requested commit or file is too big and content was truncated. Show full diff
1 NO CONTENT: modified file
1 NO CONTENT: modified file
The requested commit or file is too big and content was truncated. Show full diff
1 NO CONTENT: modified file
The requested commit or file is too big and content was truncated. Show full diff
General Comments 0
You need to be logged in to leave comments. Login now