##// END OF EJS Templates
Rename history retrieval methods, and improve docstrings.
Thomas Kluyver -
Show More
@@ -1,667 +1,709 b''
1 """ History related magics and functionality """
1 """ History related magics and functionality """
2 #-----------------------------------------------------------------------------
2 #-----------------------------------------------------------------------------
3 # Copyright (C) 2010 The IPython Development Team.
3 # Copyright (C) 2010 The IPython Development Team.
4 #
4 #
5 # Distributed under the terms of the BSD License.
5 # Distributed under the terms of the BSD License.
6 #
6 #
7 # The full license is in the file COPYING.txt, distributed with this software.
7 # The full license is in the file COPYING.txt, distributed with this software.
8 #-----------------------------------------------------------------------------
8 #-----------------------------------------------------------------------------
9
9
10 #-----------------------------------------------------------------------------
10 #-----------------------------------------------------------------------------
11 # Imports
11 # Imports
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 from __future__ import print_function
13 from __future__ import print_function
14
14
15 # Stdlib imports
15 # Stdlib imports
16 import datetime
16 import datetime
17 import json
17 import json
18 import os
18 import os
19 import re
19 import re
20 import sqlite3
20 import sqlite3
21
21
22 from collections import defaultdict
22 from collections import defaultdict
23
23
24 # Our own packages
24 # Our own packages
25 from IPython.config.configurable import Configurable
25 from IPython.config.configurable import Configurable
26 import IPython.utils.io
26 import IPython.utils.io
27
27
28 from IPython.testing import decorators as testdec
28 from IPython.testing import decorators as testdec
29 from IPython.utils.io import ask_yes_no
29 from IPython.utils.io import ask_yes_no
30 from IPython.utils.traitlets import Bool, Dict, Instance, Int, List, Unicode
30 from IPython.utils.traitlets import Bool, Dict, Instance, Int, List, Unicode
31 from IPython.utils.warn import warn
31 from IPython.utils.warn import warn
32
32
33 #-----------------------------------------------------------------------------
33 #-----------------------------------------------------------------------------
34 # Classes and functions
34 # Classes and functions
35 #-----------------------------------------------------------------------------
35 #-----------------------------------------------------------------------------
36
36
37 class HistoryManager(Configurable):
37 class HistoryManager(Configurable):
38 """A class to organize all history-related functionality in one place.
38 """A class to organize all history-related functionality in one place.
39 """
39 """
40 # Public interface
40 # Public interface
41
41
42 # An instance of the IPython shell we are attached to
42 # An instance of the IPython shell we are attached to
43 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
43 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
44 # Lists to hold processed and raw history. These start with a blank entry
44 # Lists to hold processed and raw history. These start with a blank entry
45 # so that we can index them starting from 1
45 # so that we can index them starting from 1
46 input_hist_parsed = List([""])
46 input_hist_parsed = List([""])
47 input_hist_raw = List([""])
47 input_hist_raw = List([""])
48 # A list of directories visited during session
48 # A list of directories visited during session
49 dir_hist = List()
49 dir_hist = List()
50 # A dict of output history, keyed with ints from the shell's
50 # A dict of output history, keyed with ints from the shell's
51 # execution count. If there are several outputs from one command,
51 # execution count. If there are several outputs from one command,
52 # only the last one is stored.
52 # only the last one is stored.
53 output_hist = Dict()
53 output_hist = Dict()
54 # Contains all outputs, in lists of reprs.
54 # Contains all outputs, in lists of reprs.
55 output_hist_reprs = Instance(defaultdict)
55 output_hist_reprs = Instance(defaultdict)
56
56
57 # String holding the path to the history file
57 # String holding the path to the history file
58 hist_file = Unicode()
58 hist_file = Unicode()
59 # The SQLite database
59 # The SQLite database
60 db = Instance(sqlite3.Connection)
60 db = Instance(sqlite3.Connection)
61 # The number of the current session in the history database
61 # The number of the current session in the history database
62 session_number = Int()
62 session_number = Int()
63 # Should we log output to the database? (default no)
63 # Should we log output to the database? (default no)
64 db_log_output = Bool(False, config=True)
64 db_log_output = Bool(False, config=True)
65 # Write to database every x commands (higher values save disk access & power)
65 # Write to database every x commands (higher values save disk access & power)
66 # Values of 1 or less effectively disable caching.
66 # Values of 1 or less effectively disable caching.
67 db_cache_size = Int(0, config=True)
67 db_cache_size = Int(0, config=True)
68 # The input and output caches
68 # The input and output caches
69 db_input_cache = List()
69 db_input_cache = List()
70 db_output_cache = List()
70 db_output_cache = List()
71
71
72 # Private interface
72 # Private interface
73 # Variables used to store the three last inputs from the user. On each new
73 # Variables used to store the three last inputs from the user. On each new
74 # history update, we populate the user's namespace with these, shifted as
74 # history update, we populate the user's namespace with these, shifted as
75 # necessary.
75 # necessary.
76 _i00, _i, _ii, _iii = '','','',''
76 _i00, _i, _ii, _iii = '','','',''
77
77
78 # A set with all forms of the exit command, so that we don't store them in
78 # A set with all forms of the exit command, so that we don't store them in
79 # the history (it's annoying to rewind the first entry and land on an exit
79 # the history (it's annoying to rewind the first entry and land on an exit
80 # call).
80 # call).
81 _exit_commands = None
81 _exit_commands = None
82
82
83 def __init__(self, shell, config=None):
83 def __init__(self, shell, config=None):
84 """Create a new history manager associated with a shell instance.
84 """Create a new history manager associated with a shell instance.
85 """
85 """
86 # We need a pointer back to the shell for various tasks.
86 # We need a pointer back to the shell for various tasks.
87 super(HistoryManager, self).__init__(shell=shell, config=config)
87 super(HistoryManager, self).__init__(shell=shell, config=config)
88
88
89 # list of visited directories
89 # list of visited directories
90 try:
90 try:
91 self.dir_hist = [os.getcwd()]
91 self.dir_hist = [os.getcwd()]
92 except OSError:
92 except OSError:
93 self.dir_hist = []
93 self.dir_hist = []
94
94
95 # Now the history file
95 # Now the history file
96 if shell.profile:
96 if shell.profile:
97 histfname = 'history-%s' % shell.profile
97 histfname = 'history-%s' % shell.profile
98 else:
98 else:
99 histfname = 'history'
99 histfname = 'history'
100 self.hist_file = os.path.join(shell.ipython_dir, histfname + '.sqlite')
100 self.hist_file = os.path.join(shell.ipython_dir, histfname + '.sqlite')
101 self.init_db()
101 self.init_db()
102 self.new_session()
102 self.new_session()
103
103
104 self._i00, self._i, self._ii, self._iii = '','','',''
104 self._i00, self._i, self._ii, self._iii = '','','',''
105 self.output_hist_reprs = defaultdict(list)
105 self.output_hist_reprs = defaultdict(list)
106
106
107 self._exit_commands = set(['Quit', 'quit', 'Exit', 'exit', '%Quit',
107 self._exit_commands = set(['Quit', 'quit', 'Exit', 'exit', '%Quit',
108 '%quit', '%Exit', '%exit'])
108 '%quit', '%Exit', '%exit'])
109
109
110 def init_db(self):
110 def init_db(self):
111 """Connect to the database, and create tables if necessary."""
111 """Connect to the database, and create tables if necessary."""
112 self.db = sqlite3.connect(self.hist_file)
112 self.db = sqlite3.connect(self.hist_file)
113 self.db.execute("""CREATE TABLE IF NOT EXISTS sessions (session integer
113 self.db.execute("""CREATE TABLE IF NOT EXISTS sessions (session integer
114 primary key autoincrement, start timestamp,
114 primary key autoincrement, start timestamp,
115 end timestamp, num_cmds integer, remark text)""")
115 end timestamp, num_cmds integer, remark text)""")
116 self.db.execute("""CREATE TABLE IF NOT EXISTS history
116 self.db.execute("""CREATE TABLE IF NOT EXISTS history
117 (session integer, line integer, source text, source_raw text,
117 (session integer, line integer, source text, source_raw text,
118 PRIMARY KEY (session, line))""")
118 PRIMARY KEY (session, line))""")
119 # Output history is optional, but ensure the table's there so it can be
119 # Output history is optional, but ensure the table's there so it can be
120 # enabled later.
120 # enabled later.
121 self.db.execute("""CREATE TABLE IF NOT EXISTS output_history
121 self.db.execute("""CREATE TABLE IF NOT EXISTS output_history
122 (session integer, line integer, output text,
122 (session integer, line integer, output text,
123 PRIMARY KEY (session, line))""")
123 PRIMARY KEY (session, line))""")
124 self.db.commit()
124 self.db.commit()
125
125
126 def new_session(self):
126 def new_session(self):
127 """Get a new session number."""
127 """Get a new session number."""
128 with self.db:
128 with self.db:
129 cur = self.db.execute("""INSERT INTO sessions VALUES (NULL, ?, NULL,
129 cur = self.db.execute("""INSERT INTO sessions VALUES (NULL, ?, NULL,
130 NULL, "") """, (datetime.datetime.now(),))
130 NULL, "") """, (datetime.datetime.now(),))
131 self.session_number = cur.lastrowid
131 self.session_number = cur.lastrowid
132
132
133 def end_session(self):
133 def end_session(self):
134 """Close the database session, filling in the end time and line count."""
134 """Close the database session, filling in the end time and line count."""
135 self.writeout_cache()
135 self.writeout_cache()
136 with self.db:
136 with self.db:
137 self.db.execute("""UPDATE sessions SET end=?, num_cmds=? WHERE
137 self.db.execute("""UPDATE sessions SET end=?, num_cmds=? WHERE
138 session==?""", (datetime.datetime.now(),
138 session==?""", (datetime.datetime.now(),
139 len(self.input_hist_parsed)-1, self.session_number))
139 len(self.input_hist_parsed)-1, self.session_number))
140 self.session_number = 0
140 self.session_number = 0
141
141
142 def name_session(self, name):
142 def name_session(self, name):
143 """Give the current session a name in the history database."""
143 """Give the current session a name in the history database."""
144 with self.db:
144 with self.db:
145 self.db.execute("UPDATE sessions SET remark=? WHERE session==?",
145 self.db.execute("UPDATE sessions SET remark=? WHERE session==?",
146 (name, self.session_number))
146 (name, self.session_number))
147
147
148 def reset(self, new_session=True):
148 def reset(self, new_session=True):
149 """Clear the session history, releasing all object references, and
149 """Clear the session history, releasing all object references, and
150 optionally open a new session."""
150 optionally open a new session."""
151 if self.session_number:
151 if self.session_number:
152 self.end_session()
152 self.end_session()
153 self.input_hist_parsed[:] = [""]
153 self.input_hist_parsed[:] = [""]
154 self.input_hist_raw[:] = [""]
154 self.input_hist_raw[:] = [""]
155 self.output_hist.clear()
155 self.output_hist.clear()
156 # The directory history can't be completely empty
156 # The directory history can't be completely empty
157 self.dir_hist[:] = [os.getcwd()]
157 self.dir_hist[:] = [os.getcwd()]
158
158
159 if new_session:
159 if new_session:
160 self.new_session()
160 self.new_session()
161
161
162 ## -------------------------------
162 ## -------------------------------
163 ## Methods for retrieving history:
163 ## Methods for retrieving history:
164 ## -------------------------------
164 ## -------------------------------
165 def _get_hist_sql(self, sql, params, raw=True, output=False):
165 def _run_sql(self, sql, params, raw=True, output=False):
166 """Prepares and runs an SQL query for the history database.
166 """Prepares and runs an SQL query for the history database.
167
167
168 Parameters
168 Parameters
169 ----------
169 ----------
170 sql : str
170 sql : str
171 Any filtering expressions to go after SELECT ... FROM ...
171 Any filtering expressions to go after SELECT ... FROM ...
172 params : tuple
172 params : tuple
173 Parameters passed to the SQL query (to replace "?")
173 Parameters passed to the SQL query (to replace "?")
174 raw : bool
174 raw, output : bool
175 If True, get raw input.
175 See :meth:`get_range`
176 output : bool
177 If True, include output where available.
178
176
179 Returns
177 Returns
180 -------
178 -------
181 An iterator over 3-tuples: (session, line_number, command), or if output
179 Tuples as :meth:`get_range`
182 is True, (session, line_number, (command, output)).
183 """
180 """
184 toget = 'source_raw' if raw else 'source'
181 toget = 'source_raw' if raw else 'source'
185 sqlfrom = "history"
182 sqlfrom = "history"
186 if output:
183 if output:
187 sqlfrom = "history LEFT JOIN output_history USING (session, line)"
184 sqlfrom = "history LEFT JOIN output_history USING (session, line)"
188 toget = "history.%s, output_history.output" % toget
185 toget = "history.%s, output_history.output" % toget
189 cur = self.db.execute("SELECT session, line, %s FROM %s " %\
186 cur = self.db.execute("SELECT session, line, %s FROM %s " %\
190 (toget, sqlfrom) + sql, params)
187 (toget, sqlfrom) + sql, params)
191 if output: # Regroup into 3-tuples, and parse JSON
188 if output: # Regroup into 3-tuples, and parse JSON
192 loads = lambda out: json.loads(out) if out else None
189 loads = lambda out: json.loads(out) if out else None
193 return ((ses, lin, (inp, loads(out))) \
190 return ((ses, lin, (inp, loads(out))) \
194 for ses, lin, inp, out in cur)
191 for ses, lin, inp, out in cur)
195 return cur
192 return cur
196
193
197
194
198 def get_hist_tail(self, n=10, raw=True, output=False, include_latest=False):
195 def get_tail(self, n=10, raw=True, output=False, include_latest=False):
199 """Get the last n lines from the history database.
196 """Get the last n lines from the history database.
200
197
201 If include_latest is False (default), n+1 lines are fetched, and
198 Parameters
202 the latest one is discarded. This is intended to be used where
199 ----------
203 the function is called by a user command, which it should not
200 n : int
204 return."""
201 The number of lines to get
202 raw, output : bool
203 See :meth:`get_range`
204 include_latest : bool
205 If False (default), n+1 lines are fetched, and the latest one
206 is discarded. This is intended to be used where the function
207 is called by a user command, which it should not return.
208
209 Returns
210 -------
211 Tuples as :meth:`get_range`
212 """
205 self.writeout_cache()
213 self.writeout_cache()
206 if not include_latest:
214 if not include_latest:
207 n += 1
215 n += 1
208 cur = self._get_hist_sql("ORDER BY session DESC, line DESC LIMIT ?",
216 cur = self._run_sql("ORDER BY session DESC, line DESC LIMIT ?",
209 (n,), raw=raw, output=output)
217 (n,), raw=raw, output=output)
210 if not include_latest:
218 if not include_latest:
211 return reversed(list(cur)[1:])
219 return reversed(list(cur)[1:])
212 return reversed(list(cur))
220 return reversed(list(cur))
213
221
214 def get_hist_search(self, pattern="*", raw=True, search_raw=True,
222 def search(self, pattern="*", raw=True, search_raw=True,
215 output=False):
223 output=False):
216 """Search the database using unix glob-style matching (wildcards
224 """Search the database using unix glob-style matching (wildcards
217 * and ?).
225 * and ?).
218
226
227 Parameters
228 ----------
229 pattern : str
230 The wildcarded pattern to match when searching
231 search_raw : bool
232 If True, search the raw input, otherwise, the parsed input
233 raw, output : bool
234 See :meth:`get_range`
235
219 Returns
236 Returns
220 -------
237 -------
221 An iterator over tuples: (session, line_number, command)
238 Tuples as :meth:`get_range`
222 """
239 """
223 tosearch = "source_raw" if search_raw else "source"
240 tosearch = "source_raw" if search_raw else "source"
224 if output:
241 if output:
225 tosearch = "history." + tosearch
242 tosearch = "history." + tosearch
226 self.writeout_cache()
243 self.writeout_cache()
227 return self._get_hist_sql("WHERE %s GLOB ?" % tosearch, (pattern,),
244 return self._run_sql("WHERE %s GLOB ?" % tosearch, (pattern,),
228 raw=raw, output=output)
245 raw=raw, output=output)
229
246
230 def _get_hist_session(self, start=1, stop=None, raw=True, output=False):
247 def _get_range_session(self, start=1, stop=None, raw=True, output=False):
231 """Get input and output history from the current session. Called by
248 """Get input and output history from the current session. Called by
232 get_history, and takes similar parameters."""
249 get_range, and takes similar parameters."""
233 input_hist = self.input_hist_raw if raw else self.input_hist_parsed
250 input_hist = self.input_hist_raw if raw else self.input_hist_parsed
234
251
235 n = len(input_hist)
252 n = len(input_hist)
236 if start < 0:
253 if start < 0:
237 start += n
254 start += n
238 if not stop:
255 if not stop:
239 stop = n
256 stop = n
240 elif stop < 0:
257 elif stop < 0:
241 stop += n
258 stop += n
242
259
243 for i in range(start, stop):
260 for i in range(start, stop):
244 if output:
261 if output:
245 line = (input_hist[i], self.output_hist_reprs.get(i))
262 line = (input_hist[i], self.output_hist_reprs.get(i))
246 else:
263 else:
247 line = input_hist[i]
264 line = input_hist[i]
248 yield (0, i, line)
265 yield (0, i, line)
249
266
250 def get_history(self, session=0, start=1, stop=None, raw=True,output=False):
267 def get_range(self, session=0, start=1, stop=None, raw=True,output=False):
251 """Retrieve input by session.
268 """Retrieve input by session.
252
269
253 Parameters
270 Parameters
254 ----------
271 ----------
255 session : int
272 session : int
256 Session number to retrieve. The current session is 0, and negative
273 Session number to retrieve. The current session is 0, and negative
257 numbers count back from current session, so -1 is previous session.
274 numbers count back from current session, so -1 is previous session.
258 start : int
275 start : int
259 First line to retrieve.
276 First line to retrieve.
260 stop : int
277 stop : int
261 End of line range (excluded from output itself). If None, retrieve
278 End of line range (excluded from output itself). If None, retrieve
262 to the end of the session.
279 to the end of the session.
263 raw : bool
280 raw : bool
264 If True, return untranslated input
281 If True, return untranslated input
265 output : bool
282 output : bool
266 If True, attempt to include output. This will be 'real' Python
283 If True, attempt to include output. This will be 'real' Python
267 objects for the current session, or text reprs from previous
284 objects for the current session, or text reprs from previous
268 sessions if db_log_output was enabled at the time. Where no output
285 sessions if db_log_output was enabled at the time. Where no output
269 is found, None is used.
286 is found, None is used.
270
287
271 Returns
288 Returns
272 -------
289 -------
273 An iterator over the desired lines. Each line is a 3-tuple, either
290 An iterator over the desired lines. Each line is a 3-tuple, either
274 (session, line, input) if output is False, or
291 (session, line, input) if output is False, or
275 (session, line, (input, output)) if output is True.
292 (session, line, (input, output)) if output is True.
276 """
293 """
277 if session == 0 or session==self.session_number: # Current session
294 if session == 0 or session==self.session_number: # Current session
278 return self._get_hist_session(start, stop, raw, output)
295 return self._get_range_session(start, stop, raw, output)
279 if session < 0:
296 if session < 0:
280 session += self.session_number
297 session += self.session_number
281
298
282 if stop:
299 if stop:
283 lineclause = "line >= ? AND line < ?"
300 lineclause = "line >= ? AND line < ?"
284 params = (session, start, stop)
301 params = (session, start, stop)
285 else:
302 else:
286 lineclause = "line>=?"
303 lineclause = "line>=?"
287 params = (session, start)
304 params = (session, start)
288
305
289 return self._get_hist_sql("WHERE session==? AND %s""" % lineclause,
306 return self._run_sql("WHERE session==? AND %s""" % lineclause,
290 params, raw=raw, output=output)
307 params, raw=raw, output=output)
291
308
292 def get_hist_from_rangestr(self, rangestr, raw=True, output=False):
309 def get_range_by_str(self, rangestr, raw=True, output=False):
293 """Get lines of history from a string of ranges, as used by magic
310 """Get lines of history from a string of ranges, as used by magic
294 commands %hist, %save, %macro, etc."""
311 commands %hist, %save, %macro, etc.
312
313 Parameters
314 ----------
315 rangestr : str
316 A string specifying ranges, e.g. "5 ~2/1-4". See
317 :func:`magic_history` for full details.
318 raw, output : bool
319 As :meth:`get_range`
320
321 Returns
322 -------
323 Tuples as :meth:`get_range`
324 """
295 for sess, s, e in extract_hist_ranges(rangestr):
325 for sess, s, e in extract_hist_ranges(rangestr):
296 for line in self.get_history(sess, s, e, raw=raw, output=output):
326 for line in self.get_range(sess, s, e, raw=raw, output=output):
297 yield line
327 yield line
298
328
299 ## ----------------------------
329 ## ----------------------------
300 ## Methods for storing history:
330 ## Methods for storing history:
301 ## ----------------------------
331 ## ----------------------------
302 def store_inputs(self, line_num, source, source_raw=None):
332 def store_inputs(self, line_num, source, source_raw=None):
303 """Store source and raw input in history and create input cache
333 """Store source and raw input in history and create input cache
304 variables _i*.
334 variables _i*.
305
335
306 Parameters
336 Parameters
307 ----------
337 ----------
308 line_num : int
338 line_num : int
309 The prompt number of this input.
339 The prompt number of this input.
310
340
311 source : str
341 source : str
312 Python input.
342 Python input.
313
343
314 source_raw : str, optional
344 source_raw : str, optional
315 If given, this is the raw input without any IPython transformations
345 If given, this is the raw input without any IPython transformations
316 applied to it. If not given, ``source`` is used.
346 applied to it. If not given, ``source`` is used.
317 """
347 """
318 if source_raw is None:
348 if source_raw is None:
319 source_raw = source
349 source_raw = source
320 source = source.rstrip('\n')
350 source = source.rstrip('\n')
321 source_raw = source_raw.rstrip('\n')
351 source_raw = source_raw.rstrip('\n')
322
352
323 # do not store exit/quit commands
353 # do not store exit/quit commands
324 if source_raw.strip() in self._exit_commands:
354 if source_raw.strip() in self._exit_commands:
325 return
355 return
326
356
327 self.input_hist_parsed.append(source)
357 self.input_hist_parsed.append(source)
328 self.input_hist_raw.append(source_raw)
358 self.input_hist_raw.append(source_raw)
329
359
330 self.db_input_cache.append((self.session_number, line_num,
360 self.db_input_cache.append((self.session_number, line_num,
331 source, source_raw))
361 source, source_raw))
332 # Trigger to flush cache and write to DB.
362 # Trigger to flush cache and write to DB.
333 if len(self.db_input_cache) >= self.db_cache_size:
363 if len(self.db_input_cache) >= self.db_cache_size:
334 self.writeout_cache()
364 self.writeout_cache()
335
365
336 # update the auto _i variables
366 # update the auto _i variables
337 self._iii = self._ii
367 self._iii = self._ii
338 self._ii = self._i
368 self._ii = self._i
339 self._i = self._i00
369 self._i = self._i00
340 self._i00 = source_raw
370 self._i00 = source_raw
341
371
342 # hackish access to user namespace to create _i1,_i2... dynamically
372 # hackish access to user namespace to create _i1,_i2... dynamically
343 new_i = '_i%s' % line_num
373 new_i = '_i%s' % line_num
344 to_main = {'_i': self._i,
374 to_main = {'_i': self._i,
345 '_ii': self._ii,
375 '_ii': self._ii,
346 '_iii': self._iii,
376 '_iii': self._iii,
347 new_i : self._i00 }
377 new_i : self._i00 }
348 self.shell.user_ns.update(to_main)
378 self.shell.user_ns.update(to_main)
349
379
350 def store_output(self, line_num):
380 def store_output(self, line_num):
351 """If database output logging is enabled, this saves all the
381 """If database output logging is enabled, this saves all the
352 outputs from the indicated prompt number to the database. It's
382 outputs from the indicated prompt number to the database. It's
353 called by run_cell after code has been executed."""
383 called by run_cell after code has been executed.
384
385 Parameters
386 ----------
387 line_num : int
388 The line number from which to save outputs
389 """
354 if (not self.db_log_output) or not self.output_hist_reprs[line_num]:
390 if (not self.db_log_output) or not self.output_hist_reprs[line_num]:
355 return
391 return
356 output = json.dumps(self.output_hist_reprs[line_num])
392 output = json.dumps(self.output_hist_reprs[line_num])
357 db_row = (self.session_number, line_num, output)
393 db_row = (self.session_number, line_num, output)
358 if self.db_cache_size > 1:
394 if self.db_cache_size > 1:
359 self.db_output_cache.append(db_row)
395 self.db_output_cache.append(db_row)
360 else:
396 else:
361 with self.db:
397 with self.db:
362 self.db.execute("INSERT INTO output_history VALUES (?,?,?)", db_row)
398 self.db.execute("INSERT INTO output_history VALUES (?,?,?)", db_row)
363
399
364 def writeout_cache(self):
400 def writeout_cache(self):
365 #print(self.db_input_cache)
401 #print(self.db_input_cache)
366 with self.db:
402 with self.db:
367 self.db.executemany("INSERT INTO history VALUES (?, ?, ?, ?)",
403 self.db.executemany("INSERT INTO history VALUES (?, ?, ?, ?)",
368 self.db_input_cache)
404 self.db_input_cache)
369 self.db.executemany("INSERT INTO output_history VALUES (?, ?, ?)",
405 self.db.executemany("INSERT INTO output_history VALUES (?, ?, ?)",
370 self.db_output_cache)
406 self.db_output_cache)
371 self.db_input_cache = []
407 self.db_input_cache = []
372 self.db_output_cache = []
408 self.db_output_cache = []
373
409
374
410
375 # To match, e.g. ~5/8-~2/3
411 # To match, e.g. ~5/8-~2/3
376 range_re = re.compile(r"""
412 range_re = re.compile(r"""
377 ((?P<startsess>~?\d+)/)?
413 ((?P<startsess>~?\d+)/)?
378 (?P<start>\d+) # Only the start line num is compulsory
414 (?P<start>\d+) # Only the start line num is compulsory
379 ((?P<sep>[\-:])
415 ((?P<sep>[\-:])
380 ((?P<endsess>~?\d+)/)?
416 ((?P<endsess>~?\d+)/)?
381 (?P<end>\d+))?
417 (?P<end>\d+))?
382 """, re.VERBOSE)
418 """, re.VERBOSE)
383
419
384 def extract_hist_ranges(ranges_str):
420 def extract_hist_ranges(ranges_str):
385 """Turn a string of history ranges into 3-tuples of (session, start, stop).
421 """Turn a string of history ranges into 3-tuples of (session, start, stop).
386
422
387 Examples
423 Examples
388 --------
424 --------
389 list(extract_input_ranges("~8/5-~7/4 2"))
425 list(extract_input_ranges("~8/5-~7/4 2"))
390 [(-8, 5, None), (-7, 1, 4), (0, 2, 3)]
426 [(-8, 5, None), (-7, 1, 4), (0, 2, 3)]
391 """
427 """
392 for range_str in ranges_str.split():
428 for range_str in ranges_str.split():
393 rmatch = range_re.match(range_str)
429 rmatch = range_re.match(range_str)
394 if not rmatch:
430 if not rmatch:
395 continue
431 continue
396 start = int(rmatch.group("start"))
432 start = int(rmatch.group("start"))
397 end = rmatch.group("end")
433 end = rmatch.group("end")
398 end = int(end) if end else start+1 # If no end specified, get (a, a+1)
434 end = int(end) if end else start+1 # If no end specified, get (a, a+1)
399 if rmatch.group("sep") == "-": # 1-3 == 1:4 --> [1, 2, 3]
435 if rmatch.group("sep") == "-": # 1-3 == 1:4 --> [1, 2, 3]
400 end += 1
436 end += 1
401 startsess = rmatch.group("startsess") or "0"
437 startsess = rmatch.group("startsess") or "0"
402 endsess = rmatch.group("endsess") or startsess
438 endsess = rmatch.group("endsess") or startsess
403 startsess = int(startsess.replace("~","-"))
439 startsess = int(startsess.replace("~","-"))
404 endsess = int(endsess.replace("~","-"))
440 endsess = int(endsess.replace("~","-"))
405 assert endsess >= startsess
441 assert endsess >= startsess
406
442
407 if endsess == startsess:
443 if endsess == startsess:
408 yield (startsess, start, end)
444 yield (startsess, start, end)
409 continue
445 continue
410 # Multiple sessions in one range:
446 # Multiple sessions in one range:
411 yield (startsess, start, None)
447 yield (startsess, start, None)
412 for sess in range(startsess+1, endsess):
448 for sess in range(startsess+1, endsess):
413 yield (sess, 1, None)
449 yield (sess, 1, None)
414 yield (endsess, 1, end)
450 yield (endsess, 1, end)
415
451
416 def _format_lineno(session, line):
452 def _format_lineno(session, line):
417 """Helper function to format line numbers properly."""
453 """Helper function to format line numbers properly."""
418 if session == 0:
454 if session == 0:
419 return str(line)
455 return str(line)
420 return "%s#%s" % (session, line)
456 return "%s#%s" % (session, line)
421
457
422 @testdec.skip_doctest
458 @testdec.skip_doctest
423 def magic_history(self, parameter_s = ''):
459 def magic_history(self, parameter_s = ''):
424 """Print input history (_i<n> variables), with most recent last.
460 """Print input history (_i<n> variables), with most recent last.
425
461
426 %history -> print at most 40 inputs (some may be multi-line)\\
462 %history -> print at most 40 inputs (some may be multi-line)\\
427 %history n -> print at most n inputs\\
463 %history n -> print at most n inputs\\
428 %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
464 %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
429
465
430 By default, input history is printed without line numbers so it can be
466 By default, input history is printed without line numbers so it can be
431 directly pasted into an editor.
467 directly pasted into an editor. Use -n to show them.
468
469 Ranges of history can be indicated using the syntax:
470 4 : Line 4, current session
471 4-6 : Lines 4-6, current session
472 243/1-5: Lines 1-5, session 243
473 ~2/7 : Line 7, session 2 before current
474 ~8/1-~6/5 : From the first line of 8 sessions ago, to the fifth line
475 of 6 sessions ago.
476 Multiple ranges can be entered, separated by spaces
432
477
433 With -n, each input's number <n> is shown, and is accessible as the
478 The same syntax is used by %macro, %save, %edit, %rerun
434 automatically generated variable _i<n> as well as In[<n>]. Multi-line
435 statements are printed starting at a new line for easy copy/paste.
436
479
437 Options:
480 Options:
438
481
439 -n: print line numbers for each input.
482 -n: print line numbers for each input.
440 This feature is only available if numbered prompts are in use.
483 This feature is only available if numbered prompts are in use.
441
484
442 -o: also print outputs for each input.
485 -o: also print outputs for each input.
443
486
444 -p: print classic '>>>' python prompts before each input. This is useful
487 -p: print classic '>>>' python prompts before each input. This is useful
445 for making documentation, and in conjunction with -o, for producing
488 for making documentation, and in conjunction with -o, for producing
446 doctest-ready output.
489 doctest-ready output.
447
490
448 -r: (default) print the 'raw' history, i.e. the actual commands you typed.
491 -r: (default) print the 'raw' history, i.e. the actual commands you typed.
449
492
450 -t: print the 'translated' history, as IPython understands it. IPython
493 -t: print the 'translated' history, as IPython understands it. IPython
451 filters your input and converts it all into valid Python source before
494 filters your input and converts it all into valid Python source before
452 executing it (things like magics or aliases are turned into function
495 executing it (things like magics or aliases are turned into function
453 calls, for example). With this option, you'll see the native history
496 calls, for example). With this option, you'll see the native history
454 instead of the user-entered version: '%cd /' will be seen as
497 instead of the user-entered version: '%cd /' will be seen as
455 'get_ipython().magic("%cd /")' instead of '%cd /'.
498 'get_ipython().magic("%cd /")' instead of '%cd /'.
456
499
457 -g: treat the arg as a pattern to grep for in (full) history.
500 -g: treat the arg as a pattern to grep for in (full) history.
458 This includes the saved history (almost all commands ever written).
501 This includes the saved history (almost all commands ever written).
459 Use '%hist -g' to show full saved history (may be very long).
502 Use '%hist -g' to show full saved history (may be very long).
460
503
461 -l: get the last n lines from all sessions. Specify n as a single arg, or
504 -l: get the last n lines from all sessions. Specify n as a single arg, or
462 the default is the last 10 lines.
505 the default is the last 10 lines.
463
506
464 -f FILENAME: instead of printing the output to the screen, redirect it to
507 -f FILENAME: instead of printing the output to the screen, redirect it to
465 the given file. The file is always overwritten, though IPython asks for
508 the given file. The file is always overwritten, though IPython asks for
466 confirmation first if it already exists.
509 confirmation first if it already exists.
467
510
468 Examples
511 Examples
469 --------
512 --------
470 ::
513 ::
471
514
472 In [6]: %hist -n 4 6
515 In [6]: %hist -n 4 6
473 4:a = 12
516 4:a = 12
474 5:print a**2
517 5:print a**2
475
518
476 """
519 """
477
520
478 if not self.shell.displayhook.do_full_cache:
521 if not self.shell.displayhook.do_full_cache:
479 print('This feature is only available if numbered prompts are in use.')
522 print('This feature is only available if numbered prompts are in use.')
480 return
523 return
481 opts,args = self.parse_options(parameter_s,'noprtglf:',mode='string')
524 opts,args = self.parse_options(parameter_s,'noprtglf:',mode='string')
482
525
483 # For brevity
526 # For brevity
484 history_manager = self.shell.history_manager
527 history_manager = self.shell.history_manager
485
528
486 def _format_lineno(session, line):
529 def _format_lineno(session, line):
487 """Helper function to format line numbers properly."""
530 """Helper function to format line numbers properly."""
488 if session in (0, history_manager.session_number):
531 if session in (0, history_manager.session_number):
489 return str(line)
532 return str(line)
490 return "%s/%s" % (session, line)
533 return "%s/%s" % (session, line)
491
534
492 # Check if output to specific file was requested.
535 # Check if output to specific file was requested.
493 try:
536 try:
494 outfname = opts['f']
537 outfname = opts['f']
495 except KeyError:
538 except KeyError:
496 outfile = IPython.utils.io.Term.cout # default
539 outfile = IPython.utils.io.Term.cout # default
497 # We don't want to close stdout at the end!
540 # We don't want to close stdout at the end!
498 close_at_end = False
541 close_at_end = False
499 else:
542 else:
500 if os.path.exists(outfname):
543 if os.path.exists(outfname):
501 if not ask_yes_no("File %r exists. Overwrite?" % outfname):
544 if not ask_yes_no("File %r exists. Overwrite?" % outfname):
502 print('Aborting.')
545 print('Aborting.')
503 return
546 return
504
547
505 outfile = open(outfname,'w')
548 outfile = open(outfname,'w')
506 close_at_end = True
549 close_at_end = True
507
550
508 print_nums = 'n' in opts
551 print_nums = 'n' in opts
509 get_output = 'o' in opts
552 get_output = 'o' in opts
510 pyprompts = 'p' in opts
553 pyprompts = 'p' in opts
511 # Raw history is the default
554 # Raw history is the default
512 raw = not('t' in opts)
555 raw = not('t' in opts)
513
556
514 default_length = 40
557 default_length = 40
515 pattern = None
558 pattern = None
516
559
517 if 'g' in opts: # Glob search
560 if 'g' in opts: # Glob search
518 pattern = "*" + args + "*" if args else "*"
561 pattern = "*" + args + "*" if args else "*"
519 hist = history_manager.get_hist_search(pattern, raw=raw,
562 hist = history_manager.search(pattern, raw=raw, output=get_output)
520 output=get_output)
521 elif 'l' in opts: # Get 'tail'
563 elif 'l' in opts: # Get 'tail'
522 try:
564 try:
523 n = int(args)
565 n = int(args)
524 except ValueError, IndexError:
566 except ValueError, IndexError:
525 n = 10
567 n = 10
526 hist = history_manager.get_hist_tail(n, raw=raw, output=get_output)
568 hist = history_manager.get_tail(n, raw=raw, output=get_output)
527 else:
569 else:
528 if args: # Get history by ranges
570 if args: # Get history by ranges
529 hist = history_manager.get_hist_from_rangestr(args, raw, get_output)
571 hist = history_manager.get_range_by_str(args, raw, get_output)
530 else: # Just get history for the current session
572 else: # Just get history for the current session
531 hist = history_manager.get_history(raw=raw, output=get_output)
573 hist = history_manager.get_range(raw=raw, output=get_output)
532
574
533 # We could be displaying the entire history, so let's not try to pull it
575 # We could be displaying the entire history, so let's not try to pull it
534 # into a list in memory. Anything that needs more space will just misalign.
576 # into a list in memory. Anything that needs more space will just misalign.
535 width = 4
577 width = 4
536
578
537 for session, lineno, inline in hist:
579 for session, lineno, inline in hist:
538 # Print user history with tabs expanded to 4 spaces. The GUI clients
580 # Print user history with tabs expanded to 4 spaces. The GUI clients
539 # use hard tabs for easier usability in auto-indented code, but we want
581 # use hard tabs for easier usability in auto-indented code, but we want
540 # to produce PEP-8 compliant history for safe pasting into an editor.
582 # to produce PEP-8 compliant history for safe pasting into an editor.
541 if get_output:
583 if get_output:
542 inline, output = inline
584 inline, output = inline
543 inline = inline.expandtabs(4).rstrip()
585 inline = inline.expandtabs(4).rstrip()
544
586
545 multiline = "\n" in inline
587 multiline = "\n" in inline
546 line_sep = '\n' if multiline else ' '
588 line_sep = '\n' if multiline else ' '
547 if print_nums:
589 if print_nums:
548 print('%s:%s' % (_format_lineno(session, lineno).rjust(width),
590 print('%s:%s' % (_format_lineno(session, lineno).rjust(width),
549 line_sep), file=outfile, end='')
591 line_sep), file=outfile, end='')
550 if pyprompts:
592 if pyprompts:
551 print(">>> ", end="", file=outfile)
593 print(">>> ", end="", file=outfile)
552 if multiline:
594 if multiline:
553 inline = "\n... ".join(inline.splitlines()) + "\n..."
595 inline = "\n... ".join(inline.splitlines()) + "\n..."
554 print(inline, file=outfile)
596 print(inline, file=outfile)
555 if get_output and output:
597 if get_output and output:
556 print("\n".join(output), file=outfile)
598 print("\n".join(output), file=outfile)
557
599
558 if close_at_end:
600 if close_at_end:
559 outfile.close()
601 outfile.close()
560
602
561
603
562 def magic_rep(self, arg):
604 def magic_rep(self, arg):
563 r""" Repeat a command, or get command to input line for editing
605 r""" Repeat a command, or get command to input line for editing
564
606
565 - %rep (no arguments):
607 - %rep (no arguments):
566
608
567 Place a string version of last computation result (stored in the special '_'
609 Place a string version of last computation result (stored in the special '_'
568 variable) to the next input prompt. Allows you to create elaborate command
610 variable) to the next input prompt. Allows you to create elaborate command
569 lines without using copy-paste::
611 lines without using copy-paste::
570
612
571 In[1]: l = ["hei", "vaan"]
613 In[1]: l = ["hei", "vaan"]
572 In[2]: "".join(l)
614 In[2]: "".join(l)
573 Out[2]: heivaan
615 Out[2]: heivaan
574 In[3]: %rep
616 In[3]: %rep
575 In[4]: heivaan_ <== cursor blinking
617 In[4]: heivaan_ <== cursor blinking
576
618
577 %rep 45
619 %rep 45
578
620
579 Place history line 45 on the next input prompt. Use %hist to find
621 Place history line 45 on the next input prompt. Use %hist to find
580 out the number.
622 out the number.
581
623
582 %rep 1-4 6-7 3
624 %rep 1-4
583
625
584 Combine the specified lines into one cell, and place it on the next
626 Combine the specified lines into one cell, and place it on the next
585 input prompt. History slice syntax is the same as in %macro and %save.
627 input prompt. See %history for the slice syntax.
586
628
587 %rep foo+bar
629 %rep foo+bar
588
630
589 If foo+bar can be evaluated in the user namespace, the result is
631 If foo+bar can be evaluated in the user namespace, the result is
590 placed at the next input prompt. Otherwise, the history is searched
632 placed at the next input prompt. Otherwise, the history is searched
591 for lines which contain that substring, and the most recent one is
633 for lines which contain that substring, and the most recent one is
592 placed at the next input prompt.
634 placed at the next input prompt.
593 """
635 """
594 if not arg: # Last output
636 if not arg: # Last output
595 self.set_next_input(str(self.shell.user_ns["_"]))
637 self.set_next_input(str(self.shell.user_ns["_"]))
596 return
638 return
597 # Get history range
639 # Get history range
598 histlines = self.history_manager.get_hist_from_rangestr(arg)
640 histlines = self.history_manager.get_range_by_str(arg)
599 cmd = "\n".join(x[2] for x in histlines)
641 cmd = "\n".join(x[2] for x in histlines)
600 if cmd:
642 if cmd:
601 self.set_next_input(cmd.rstrip())
643 self.set_next_input(cmd.rstrip())
602 return
644 return
603
645
604 try: # Variable in user namespace
646 try: # Variable in user namespace
605 cmd = str(eval(arg, self.shell.user_ns))
647 cmd = str(eval(arg, self.shell.user_ns))
606 except Exception: # Search for term in history
648 except Exception: # Search for term in history
607 histlines = self.history_manager.get_hist_search("*"+arg+"*")
649 histlines = self.history_manager.search("*"+arg+"*")
608 for h in reversed([x[2] for x in histlines]):
650 for h in reversed([x[2] for x in histlines]):
609 if 'rep' in h:
651 if 'rep' in h:
610 continue
652 continue
611 self.set_next_input(h.rstrip())
653 self.set_next_input(h.rstrip())
612 return
654 return
613 else:
655 else:
614 self.set_next_input(cmd.rstrip())
656 self.set_next_input(cmd.rstrip())
615 print("Couldn't evaluate or find in history:", arg)
657 print("Couldn't evaluate or find in history:", arg)
616
658
617 def magic_rerun(self, parameter_s=''):
659 def magic_rerun(self, parameter_s=''):
618 """Re-run previous input
660 """Re-run previous input
619
661
620 By default, you can specify ranges of input history to be repeated
662 By default, you can specify ranges of input history to be repeated
621 (as with %hist). With no arguments, it will repeat the last line.
663 (as with %history). With no arguments, it will repeat the last line.
622
664
623 Options:
665 Options:
624
666
625 -l <n> : Repeat the last n lines of input, not including the
667 -l <n> : Repeat the last n lines of input, not including the
626 current command.
668 current command.
627
669
628 -g foo : Repeat the most recent line which contains foo
670 -g foo : Repeat the most recent line which contains foo
629 """
671 """
630 opts, args = self.parse_options(parameter_s, 'l:g:', mode='string')
672 opts, args = self.parse_options(parameter_s, 'l:g:', mode='string')
631 if "l" in opts: # Last n lines
673 if "l" in opts: # Last n lines
632 n = int(opts['l'])
674 n = int(opts['l'])
633 hist = self.history_manager.get_hist_tail(n)
675 hist = self.history_manager.get_tail(n)
634 elif "g" in opts: # Search
676 elif "g" in opts: # Search
635 p = "*"+opts['g']+"*"
677 p = "*"+opts['g']+"*"
636 hist = list(self.history_manager.get_hist_search(p))
678 hist = list(self.history_manager.search(p))
637 for l in reversed(hist):
679 for l in reversed(hist):
638 if "rerun" not in l[2]:
680 if "rerun" not in l[2]:
639 hist = [l] # The last match which isn't a %rerun
681 hist = [l] # The last match which isn't a %rerun
640 break
682 break
641 else:
683 else:
642 hist = [] # No matches except %rerun
684 hist = [] # No matches except %rerun
643 elif args: # Specify history ranges
685 elif args: # Specify history ranges
644 hist = self.history_manager.get_hist_from_rangestr(args)
686 hist = self.history_manager.get_range_by_str(args)
645 else: # Last line
687 else: # Last line
646 hist = self.history_manager.get_hist_tail(1)
688 hist = self.history_manager.get_tail(1)
647 hist = [x[2] for x in hist]
689 hist = [x[2] for x in hist]
648 if not hist:
690 if not hist:
649 print("No lines in history match specification")
691 print("No lines in history match specification")
650 return
692 return
651 histlines = "\n".join(hist)
693 histlines = "\n".join(hist)
652 print("=== Executing: ===")
694 print("=== Executing: ===")
653 print(histlines)
695 print(histlines)
654 print("=== Output: ===")
696 print("=== Output: ===")
655 self.run_cell("\n".join(hist), store_history=False)
697 self.run_cell("\n".join(hist), store_history=False)
656
698
657
699
658 def init_ipython(ip):
700 def init_ipython(ip):
659 ip.define_magic("rep", magic_rep)
701 ip.define_magic("rep", magic_rep)
660 ip.define_magic("recall", magic_rep)
702 ip.define_magic("recall", magic_rep)
661 ip.define_magic("rerun", magic_rerun)
703 ip.define_magic("rerun", magic_rerun)
662 ip.define_magic("hist",magic_history) # Alternative name
704 ip.define_magic("hist",magic_history) # Alternative name
663 ip.define_magic("history",magic_history)
705 ip.define_magic("history",magic_history)
664
706
665 # XXX - ipy_completers are in quarantine, need to be updated to new apis
707 # XXX - ipy_completers are in quarantine, need to be updated to new apis
666 #import ipy_completers
708 #import ipy_completers
667 #ipy_completers.quick_completer('%hist' ,'-g -t -r -n')
709 #ipy_completers.quick_completer('%hist' ,'-g -t -r -n')
@@ -1,2527 +1,2527 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Main IPython class."""
2 """Main IPython class."""
3
3
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 # Copyright (C) 2008-2011 The IPython Development Team
7 # Copyright (C) 2008-2011 The IPython Development Team
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import with_statement
17 from __future__ import with_statement
18 from __future__ import absolute_import
18 from __future__ import absolute_import
19
19
20 import __builtin__
20 import __builtin__
21 import __future__
21 import __future__
22 import abc
22 import abc
23 import atexit
23 import atexit
24 import codeop
24 import codeop
25 import os
25 import os
26 import re
26 import re
27 import sys
27 import sys
28 import tempfile
28 import tempfile
29 import types
29 import types
30 from contextlib import nested
30 from contextlib import nested
31
31
32 from IPython.config.configurable import Configurable
32 from IPython.config.configurable import Configurable
33 from IPython.core import debugger, oinspect
33 from IPython.core import debugger, oinspect
34 from IPython.core import history as ipcorehist
34 from IPython.core import history as ipcorehist
35 from IPython.core import page
35 from IPython.core import page
36 from IPython.core import prefilter
36 from IPython.core import prefilter
37 from IPython.core import shadowns
37 from IPython.core import shadowns
38 from IPython.core import ultratb
38 from IPython.core import ultratb
39 from IPython.core.alias import AliasManager
39 from IPython.core.alias import AliasManager
40 from IPython.core.builtin_trap import BuiltinTrap
40 from IPython.core.builtin_trap import BuiltinTrap
41 from IPython.core.compilerop import CachingCompiler
41 from IPython.core.compilerop import CachingCompiler
42 from IPython.core.display_trap import DisplayTrap
42 from IPython.core.display_trap import DisplayTrap
43 from IPython.core.displayhook import DisplayHook
43 from IPython.core.displayhook import DisplayHook
44 from IPython.core.displaypub import DisplayPublisher
44 from IPython.core.displaypub import DisplayPublisher
45 from IPython.core.error import TryNext, UsageError
45 from IPython.core.error import TryNext, UsageError
46 from IPython.core.extensions import ExtensionManager
46 from IPython.core.extensions import ExtensionManager
47 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
47 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
48 from IPython.core.formatters import DisplayFormatter
48 from IPython.core.formatters import DisplayFormatter
49 from IPython.core.history import HistoryManager
49 from IPython.core.history import HistoryManager
50 from IPython.core.inputsplitter import IPythonInputSplitter
50 from IPython.core.inputsplitter import IPythonInputSplitter
51 from IPython.core.logger import Logger
51 from IPython.core.logger import Logger
52 from IPython.core.magic import Magic
52 from IPython.core.magic import Magic
53 from IPython.core.payload import PayloadManager
53 from IPython.core.payload import PayloadManager
54 from IPython.core.plugin import PluginManager
54 from IPython.core.plugin import PluginManager
55 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
55 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
56 from IPython.external.Itpl import ItplNS
56 from IPython.external.Itpl import ItplNS
57 from IPython.utils import PyColorize
57 from IPython.utils import PyColorize
58 from IPython.utils import io
58 from IPython.utils import io
59 from IPython.utils.doctestreload import doctest_reload
59 from IPython.utils.doctestreload import doctest_reload
60 from IPython.utils.io import ask_yes_no, rprint
60 from IPython.utils.io import ask_yes_no, rprint
61 from IPython.utils.ipstruct import Struct
61 from IPython.utils.ipstruct import Struct
62 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
62 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
63 from IPython.utils.pickleshare import PickleShareDB
63 from IPython.utils.pickleshare import PickleShareDB
64 from IPython.utils.process import system, getoutput
64 from IPython.utils.process import system, getoutput
65 from IPython.utils.strdispatch import StrDispatch
65 from IPython.utils.strdispatch import StrDispatch
66 from IPython.utils.syspathcontext import prepended_to_syspath
66 from IPython.utils.syspathcontext import prepended_to_syspath
67 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
67 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
68 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
68 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
69 List, Unicode, Instance, Type)
69 List, Unicode, Instance, Type)
70 from IPython.utils.warn import warn, error, fatal
70 from IPython.utils.warn import warn, error, fatal
71 import IPython.core.hooks
71 import IPython.core.hooks
72
72
73 #-----------------------------------------------------------------------------
73 #-----------------------------------------------------------------------------
74 # Globals
74 # Globals
75 #-----------------------------------------------------------------------------
75 #-----------------------------------------------------------------------------
76
76
77 # compiled regexps for autoindent management
77 # compiled regexps for autoindent management
78 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
78 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
79
79
80 #-----------------------------------------------------------------------------
80 #-----------------------------------------------------------------------------
81 # Utilities
81 # Utilities
82 #-----------------------------------------------------------------------------
82 #-----------------------------------------------------------------------------
83
83
84 # store the builtin raw_input globally, and use this always, in case user code
84 # store the builtin raw_input globally, and use this always, in case user code
85 # overwrites it (like wx.py.PyShell does)
85 # overwrites it (like wx.py.PyShell does)
86 raw_input_original = raw_input
86 raw_input_original = raw_input
87
87
88 def softspace(file, newvalue):
88 def softspace(file, newvalue):
89 """Copied from code.py, to remove the dependency"""
89 """Copied from code.py, to remove the dependency"""
90
90
91 oldvalue = 0
91 oldvalue = 0
92 try:
92 try:
93 oldvalue = file.softspace
93 oldvalue = file.softspace
94 except AttributeError:
94 except AttributeError:
95 pass
95 pass
96 try:
96 try:
97 file.softspace = newvalue
97 file.softspace = newvalue
98 except (AttributeError, TypeError):
98 except (AttributeError, TypeError):
99 # "attribute-less object" or "read-only attributes"
99 # "attribute-less object" or "read-only attributes"
100 pass
100 pass
101 return oldvalue
101 return oldvalue
102
102
103
103
104 def no_op(*a, **kw): pass
104 def no_op(*a, **kw): pass
105
105
106 class SpaceInInput(Exception): pass
106 class SpaceInInput(Exception): pass
107
107
108 class Bunch: pass
108 class Bunch: pass
109
109
110
110
111 def get_default_colors():
111 def get_default_colors():
112 if sys.platform=='darwin':
112 if sys.platform=='darwin':
113 return "LightBG"
113 return "LightBG"
114 elif os.name=='nt':
114 elif os.name=='nt':
115 return 'Linux'
115 return 'Linux'
116 else:
116 else:
117 return 'Linux'
117 return 'Linux'
118
118
119
119
120 class SeparateStr(Str):
120 class SeparateStr(Str):
121 """A Str subclass to validate separate_in, separate_out, etc.
121 """A Str subclass to validate separate_in, separate_out, etc.
122
122
123 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
123 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
124 """
124 """
125
125
126 def validate(self, obj, value):
126 def validate(self, obj, value):
127 if value == '0': value = ''
127 if value == '0': value = ''
128 value = value.replace('\\n','\n')
128 value = value.replace('\\n','\n')
129 return super(SeparateStr, self).validate(obj, value)
129 return super(SeparateStr, self).validate(obj, value)
130
130
131 class MultipleInstanceError(Exception):
131 class MultipleInstanceError(Exception):
132 pass
132 pass
133
133
134
134
135 #-----------------------------------------------------------------------------
135 #-----------------------------------------------------------------------------
136 # Main IPython class
136 # Main IPython class
137 #-----------------------------------------------------------------------------
137 #-----------------------------------------------------------------------------
138
138
139 class InteractiveShell(Configurable, Magic):
139 class InteractiveShell(Configurable, Magic):
140 """An enhanced, interactive shell for Python."""
140 """An enhanced, interactive shell for Python."""
141
141
142 _instance = None
142 _instance = None
143 autocall = Enum((0,1,2), default_value=1, config=True)
143 autocall = Enum((0,1,2), default_value=1, config=True)
144 # TODO: remove all autoindent logic and put into frontends.
144 # TODO: remove all autoindent logic and put into frontends.
145 # We can't do this yet because even runlines uses the autoindent.
145 # We can't do this yet because even runlines uses the autoindent.
146 autoindent = CBool(True, config=True)
146 autoindent = CBool(True, config=True)
147 automagic = CBool(True, config=True)
147 automagic = CBool(True, config=True)
148 cache_size = Int(1000, config=True)
148 cache_size = Int(1000, config=True)
149 color_info = CBool(True, config=True)
149 color_info = CBool(True, config=True)
150 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
150 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
151 default_value=get_default_colors(), config=True)
151 default_value=get_default_colors(), config=True)
152 debug = CBool(False, config=True)
152 debug = CBool(False, config=True)
153 deep_reload = CBool(False, config=True)
153 deep_reload = CBool(False, config=True)
154 display_formatter = Instance(DisplayFormatter)
154 display_formatter = Instance(DisplayFormatter)
155 displayhook_class = Type(DisplayHook)
155 displayhook_class = Type(DisplayHook)
156 display_pub_class = Type(DisplayPublisher)
156 display_pub_class = Type(DisplayPublisher)
157
157
158 exit_now = CBool(False)
158 exit_now = CBool(False)
159 # Monotonically increasing execution counter
159 # Monotonically increasing execution counter
160 execution_count = Int(1)
160 execution_count = Int(1)
161 filename = Str("<ipython console>")
161 filename = Str("<ipython console>")
162 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
162 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
163
163
164 # Input splitter, to split entire cells of input into either individual
164 # Input splitter, to split entire cells of input into either individual
165 # interactive statements or whole blocks.
165 # interactive statements or whole blocks.
166 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
166 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
167 (), {})
167 (), {})
168 logstart = CBool(False, config=True)
168 logstart = CBool(False, config=True)
169 logfile = Str('', config=True)
169 logfile = Str('', config=True)
170 logappend = Str('', config=True)
170 logappend = Str('', config=True)
171 object_info_string_level = Enum((0,1,2), default_value=0,
171 object_info_string_level = Enum((0,1,2), default_value=0,
172 config=True)
172 config=True)
173 pdb = CBool(False, config=True)
173 pdb = CBool(False, config=True)
174
174
175 profile = Str('', config=True)
175 profile = Str('', config=True)
176 prompt_in1 = Str('In [\\#]: ', config=True)
176 prompt_in1 = Str('In [\\#]: ', config=True)
177 prompt_in2 = Str(' .\\D.: ', config=True)
177 prompt_in2 = Str(' .\\D.: ', config=True)
178 prompt_out = Str('Out[\\#]: ', config=True)
178 prompt_out = Str('Out[\\#]: ', config=True)
179 prompts_pad_left = CBool(True, config=True)
179 prompts_pad_left = CBool(True, config=True)
180 quiet = CBool(False, config=True)
180 quiet = CBool(False, config=True)
181
181
182 history_length = Int(10000, config=True)
182 history_length = Int(10000, config=True)
183
183
184 # The readline stuff will eventually be moved to the terminal subclass
184 # The readline stuff will eventually be moved to the terminal subclass
185 # but for now, we can't do that as readline is welded in everywhere.
185 # but for now, we can't do that as readline is welded in everywhere.
186 readline_use = CBool(True, config=True)
186 readline_use = CBool(True, config=True)
187 readline_merge_completions = CBool(True, config=True)
187 readline_merge_completions = CBool(True, config=True)
188 readline_omit__names = Enum((0,1,2), default_value=2, config=True)
188 readline_omit__names = Enum((0,1,2), default_value=2, config=True)
189 readline_remove_delims = Str('-/~', config=True)
189 readline_remove_delims = Str('-/~', config=True)
190 readline_parse_and_bind = List([
190 readline_parse_and_bind = List([
191 'tab: complete',
191 'tab: complete',
192 '"\C-l": clear-screen',
192 '"\C-l": clear-screen',
193 'set show-all-if-ambiguous on',
193 'set show-all-if-ambiguous on',
194 '"\C-o": tab-insert',
194 '"\C-o": tab-insert',
195 '"\M-i": " "',
195 '"\M-i": " "',
196 '"\M-o": "\d\d\d\d"',
196 '"\M-o": "\d\d\d\d"',
197 '"\M-I": "\d\d\d\d"',
197 '"\M-I": "\d\d\d\d"',
198 '"\C-r": reverse-search-history',
198 '"\C-r": reverse-search-history',
199 '"\C-s": forward-search-history',
199 '"\C-s": forward-search-history',
200 '"\C-p": history-search-backward',
200 '"\C-p": history-search-backward',
201 '"\C-n": history-search-forward',
201 '"\C-n": history-search-forward',
202 '"\e[A": history-search-backward',
202 '"\e[A": history-search-backward',
203 '"\e[B": history-search-forward',
203 '"\e[B": history-search-forward',
204 '"\C-k": kill-line',
204 '"\C-k": kill-line',
205 '"\C-u": unix-line-discard',
205 '"\C-u": unix-line-discard',
206 ], allow_none=False, config=True)
206 ], allow_none=False, config=True)
207
207
208 # TODO: this part of prompt management should be moved to the frontends.
208 # TODO: this part of prompt management should be moved to the frontends.
209 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
209 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
210 separate_in = SeparateStr('\n', config=True)
210 separate_in = SeparateStr('\n', config=True)
211 separate_out = SeparateStr('', config=True)
211 separate_out = SeparateStr('', config=True)
212 separate_out2 = SeparateStr('', config=True)
212 separate_out2 = SeparateStr('', config=True)
213 wildcards_case_sensitive = CBool(True, config=True)
213 wildcards_case_sensitive = CBool(True, config=True)
214 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
214 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
215 default_value='Context', config=True)
215 default_value='Context', config=True)
216
216
217 # Subcomponents of InteractiveShell
217 # Subcomponents of InteractiveShell
218 alias_manager = Instance('IPython.core.alias.AliasManager')
218 alias_manager = Instance('IPython.core.alias.AliasManager')
219 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
219 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
220 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
220 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
221 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
221 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
222 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
222 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
223 plugin_manager = Instance('IPython.core.plugin.PluginManager')
223 plugin_manager = Instance('IPython.core.plugin.PluginManager')
224 payload_manager = Instance('IPython.core.payload.PayloadManager')
224 payload_manager = Instance('IPython.core.payload.PayloadManager')
225 history_manager = Instance('IPython.core.history.HistoryManager')
225 history_manager = Instance('IPython.core.history.HistoryManager')
226
226
227 # Private interface
227 # Private interface
228 _post_execute = set()
228 _post_execute = set()
229
229
230 def __init__(self, config=None, ipython_dir=None,
230 def __init__(self, config=None, ipython_dir=None,
231 user_ns=None, user_global_ns=None,
231 user_ns=None, user_global_ns=None,
232 custom_exceptions=((), None)):
232 custom_exceptions=((), None)):
233
233
234 # This is where traits with a config_key argument are updated
234 # This is where traits with a config_key argument are updated
235 # from the values on config.
235 # from the values on config.
236 super(InteractiveShell, self).__init__(config=config)
236 super(InteractiveShell, self).__init__(config=config)
237
237
238 # These are relatively independent and stateless
238 # These are relatively independent and stateless
239 self.init_ipython_dir(ipython_dir)
239 self.init_ipython_dir(ipython_dir)
240 self.init_instance_attrs()
240 self.init_instance_attrs()
241 self.init_environment()
241 self.init_environment()
242
242
243 # Create namespaces (user_ns, user_global_ns, etc.)
243 # Create namespaces (user_ns, user_global_ns, etc.)
244 self.init_create_namespaces(user_ns, user_global_ns)
244 self.init_create_namespaces(user_ns, user_global_ns)
245 # This has to be done after init_create_namespaces because it uses
245 # This has to be done after init_create_namespaces because it uses
246 # something in self.user_ns, but before init_sys_modules, which
246 # something in self.user_ns, but before init_sys_modules, which
247 # is the first thing to modify sys.
247 # is the first thing to modify sys.
248 # TODO: When we override sys.stdout and sys.stderr before this class
248 # TODO: When we override sys.stdout and sys.stderr before this class
249 # is created, we are saving the overridden ones here. Not sure if this
249 # is created, we are saving the overridden ones here. Not sure if this
250 # is what we want to do.
250 # is what we want to do.
251 self.save_sys_module_state()
251 self.save_sys_module_state()
252 self.init_sys_modules()
252 self.init_sys_modules()
253
253
254 # While we're trying to have each part of the code directly access what
254 # While we're trying to have each part of the code directly access what
255 # it needs without keeping redundant references to objects, we have too
255 # it needs without keeping redundant references to objects, we have too
256 # much legacy code that expects ip.db to exist.
256 # much legacy code that expects ip.db to exist.
257 self.db = PickleShareDB(os.path.join(self.ipython_dir, 'db'))
257 self.db = PickleShareDB(os.path.join(self.ipython_dir, 'db'))
258
258
259 self.init_history()
259 self.init_history()
260 self.init_encoding()
260 self.init_encoding()
261 self.init_prefilter()
261 self.init_prefilter()
262
262
263 Magic.__init__(self, self)
263 Magic.__init__(self, self)
264
264
265 self.init_syntax_highlighting()
265 self.init_syntax_highlighting()
266 self.init_hooks()
266 self.init_hooks()
267 self.init_pushd_popd_magic()
267 self.init_pushd_popd_magic()
268 # self.init_traceback_handlers use to be here, but we moved it below
268 # self.init_traceback_handlers use to be here, but we moved it below
269 # because it and init_io have to come after init_readline.
269 # because it and init_io have to come after init_readline.
270 self.init_user_ns()
270 self.init_user_ns()
271 self.init_logger()
271 self.init_logger()
272 self.init_alias()
272 self.init_alias()
273 self.init_builtins()
273 self.init_builtins()
274
274
275 # pre_config_initialization
275 # pre_config_initialization
276
276
277 # The next section should contain everything that was in ipmaker.
277 # The next section should contain everything that was in ipmaker.
278 self.init_logstart()
278 self.init_logstart()
279
279
280 # The following was in post_config_initialization
280 # The following was in post_config_initialization
281 self.init_inspector()
281 self.init_inspector()
282 # init_readline() must come before init_io(), because init_io uses
282 # init_readline() must come before init_io(), because init_io uses
283 # readline related things.
283 # readline related things.
284 self.init_readline()
284 self.init_readline()
285 # init_completer must come after init_readline, because it needs to
285 # init_completer must come after init_readline, because it needs to
286 # know whether readline is present or not system-wide to configure the
286 # know whether readline is present or not system-wide to configure the
287 # completers, since the completion machinery can now operate
287 # completers, since the completion machinery can now operate
288 # independently of readline (e.g. over the network)
288 # independently of readline (e.g. over the network)
289 self.init_completer()
289 self.init_completer()
290 # TODO: init_io() needs to happen before init_traceback handlers
290 # TODO: init_io() needs to happen before init_traceback handlers
291 # because the traceback handlers hardcode the stdout/stderr streams.
291 # because the traceback handlers hardcode the stdout/stderr streams.
292 # This logic in in debugger.Pdb and should eventually be changed.
292 # This logic in in debugger.Pdb and should eventually be changed.
293 self.init_io()
293 self.init_io()
294 self.init_traceback_handlers(custom_exceptions)
294 self.init_traceback_handlers(custom_exceptions)
295 self.init_prompts()
295 self.init_prompts()
296 self.init_display_formatter()
296 self.init_display_formatter()
297 self.init_display_pub()
297 self.init_display_pub()
298 self.init_displayhook()
298 self.init_displayhook()
299 self.init_reload_doctest()
299 self.init_reload_doctest()
300 self.init_magics()
300 self.init_magics()
301 self.init_pdb()
301 self.init_pdb()
302 self.init_extension_manager()
302 self.init_extension_manager()
303 self.init_plugin_manager()
303 self.init_plugin_manager()
304 self.init_payload()
304 self.init_payload()
305 self.hooks.late_startup_hook()
305 self.hooks.late_startup_hook()
306 atexit.register(self.atexit_operations)
306 atexit.register(self.atexit_operations)
307
307
308 @classmethod
308 @classmethod
309 def instance(cls, *args, **kwargs):
309 def instance(cls, *args, **kwargs):
310 """Returns a global InteractiveShell instance."""
310 """Returns a global InteractiveShell instance."""
311 if cls._instance is None:
311 if cls._instance is None:
312 inst = cls(*args, **kwargs)
312 inst = cls(*args, **kwargs)
313 # Now make sure that the instance will also be returned by
313 # Now make sure that the instance will also be returned by
314 # the subclasses instance attribute.
314 # the subclasses instance attribute.
315 for subclass in cls.mro():
315 for subclass in cls.mro():
316 if issubclass(cls, subclass) and \
316 if issubclass(cls, subclass) and \
317 issubclass(subclass, InteractiveShell):
317 issubclass(subclass, InteractiveShell):
318 subclass._instance = inst
318 subclass._instance = inst
319 else:
319 else:
320 break
320 break
321 if isinstance(cls._instance, cls):
321 if isinstance(cls._instance, cls):
322 return cls._instance
322 return cls._instance
323 else:
323 else:
324 raise MultipleInstanceError(
324 raise MultipleInstanceError(
325 'Multiple incompatible subclass instances of '
325 'Multiple incompatible subclass instances of '
326 'InteractiveShell are being created.'
326 'InteractiveShell are being created.'
327 )
327 )
328
328
329 @classmethod
329 @classmethod
330 def initialized(cls):
330 def initialized(cls):
331 return hasattr(cls, "_instance")
331 return hasattr(cls, "_instance")
332
332
333 def get_ipython(self):
333 def get_ipython(self):
334 """Return the currently running IPython instance."""
334 """Return the currently running IPython instance."""
335 return self
335 return self
336
336
337 #-------------------------------------------------------------------------
337 #-------------------------------------------------------------------------
338 # Trait changed handlers
338 # Trait changed handlers
339 #-------------------------------------------------------------------------
339 #-------------------------------------------------------------------------
340
340
341 def _ipython_dir_changed(self, name, new):
341 def _ipython_dir_changed(self, name, new):
342 if not os.path.isdir(new):
342 if not os.path.isdir(new):
343 os.makedirs(new, mode = 0777)
343 os.makedirs(new, mode = 0777)
344
344
345 def set_autoindent(self,value=None):
345 def set_autoindent(self,value=None):
346 """Set the autoindent flag, checking for readline support.
346 """Set the autoindent flag, checking for readline support.
347
347
348 If called with no arguments, it acts as a toggle."""
348 If called with no arguments, it acts as a toggle."""
349
349
350 if not self.has_readline:
350 if not self.has_readline:
351 if os.name == 'posix':
351 if os.name == 'posix':
352 warn("The auto-indent feature requires the readline library")
352 warn("The auto-indent feature requires the readline library")
353 self.autoindent = 0
353 self.autoindent = 0
354 return
354 return
355 if value is None:
355 if value is None:
356 self.autoindent = not self.autoindent
356 self.autoindent = not self.autoindent
357 else:
357 else:
358 self.autoindent = value
358 self.autoindent = value
359
359
360 #-------------------------------------------------------------------------
360 #-------------------------------------------------------------------------
361 # init_* methods called by __init__
361 # init_* methods called by __init__
362 #-------------------------------------------------------------------------
362 #-------------------------------------------------------------------------
363
363
364 def init_ipython_dir(self, ipython_dir):
364 def init_ipython_dir(self, ipython_dir):
365 if ipython_dir is not None:
365 if ipython_dir is not None:
366 self.ipython_dir = ipython_dir
366 self.ipython_dir = ipython_dir
367 self.config.Global.ipython_dir = self.ipython_dir
367 self.config.Global.ipython_dir = self.ipython_dir
368 return
368 return
369
369
370 if hasattr(self.config.Global, 'ipython_dir'):
370 if hasattr(self.config.Global, 'ipython_dir'):
371 self.ipython_dir = self.config.Global.ipython_dir
371 self.ipython_dir = self.config.Global.ipython_dir
372 else:
372 else:
373 self.ipython_dir = get_ipython_dir()
373 self.ipython_dir = get_ipython_dir()
374
374
375 # All children can just read this
375 # All children can just read this
376 self.config.Global.ipython_dir = self.ipython_dir
376 self.config.Global.ipython_dir = self.ipython_dir
377
377
378 def init_instance_attrs(self):
378 def init_instance_attrs(self):
379 self.more = False
379 self.more = False
380
380
381 # command compiler
381 # command compiler
382 self.compile = CachingCompiler()
382 self.compile = CachingCompiler()
383
383
384 # User input buffers
384 # User input buffers
385 # NOTE: these variables are slated for full removal, once we are 100%
385 # NOTE: these variables are slated for full removal, once we are 100%
386 # sure that the new execution logic is solid. We will delte runlines,
386 # sure that the new execution logic is solid. We will delte runlines,
387 # push_line and these buffers, as all input will be managed by the
387 # push_line and these buffers, as all input will be managed by the
388 # frontends via an inputsplitter instance.
388 # frontends via an inputsplitter instance.
389 self.buffer = []
389 self.buffer = []
390 self.buffer_raw = []
390 self.buffer_raw = []
391
391
392 # Make an empty namespace, which extension writers can rely on both
392 # Make an empty namespace, which extension writers can rely on both
393 # existing and NEVER being used by ipython itself. This gives them a
393 # existing and NEVER being used by ipython itself. This gives them a
394 # convenient location for storing additional information and state
394 # convenient location for storing additional information and state
395 # their extensions may require, without fear of collisions with other
395 # their extensions may require, without fear of collisions with other
396 # ipython names that may develop later.
396 # ipython names that may develop later.
397 self.meta = Struct()
397 self.meta = Struct()
398
398
399 # Object variable to store code object waiting execution. This is
399 # Object variable to store code object waiting execution. This is
400 # used mainly by the multithreaded shells, but it can come in handy in
400 # used mainly by the multithreaded shells, but it can come in handy in
401 # other situations. No need to use a Queue here, since it's a single
401 # other situations. No need to use a Queue here, since it's a single
402 # item which gets cleared once run.
402 # item which gets cleared once run.
403 self.code_to_run = None
403 self.code_to_run = None
404
404
405 # Temporary files used for various purposes. Deleted at exit.
405 # Temporary files used for various purposes. Deleted at exit.
406 self.tempfiles = []
406 self.tempfiles = []
407
407
408 # Keep track of readline usage (later set by init_readline)
408 # Keep track of readline usage (later set by init_readline)
409 self.has_readline = False
409 self.has_readline = False
410
410
411 # keep track of where we started running (mainly for crash post-mortem)
411 # keep track of where we started running (mainly for crash post-mortem)
412 # This is not being used anywhere currently.
412 # This is not being used anywhere currently.
413 self.starting_dir = os.getcwd()
413 self.starting_dir = os.getcwd()
414
414
415 # Indentation management
415 # Indentation management
416 self.indent_current_nsp = 0
416 self.indent_current_nsp = 0
417
417
418 def init_environment(self):
418 def init_environment(self):
419 """Any changes we need to make to the user's environment."""
419 """Any changes we need to make to the user's environment."""
420 pass
420 pass
421
421
422 def init_encoding(self):
422 def init_encoding(self):
423 # Get system encoding at startup time. Certain terminals (like Emacs
423 # Get system encoding at startup time. Certain terminals (like Emacs
424 # under Win32 have it set to None, and we need to have a known valid
424 # under Win32 have it set to None, and we need to have a known valid
425 # encoding to use in the raw_input() method
425 # encoding to use in the raw_input() method
426 try:
426 try:
427 self.stdin_encoding = sys.stdin.encoding or 'ascii'
427 self.stdin_encoding = sys.stdin.encoding or 'ascii'
428 except AttributeError:
428 except AttributeError:
429 self.stdin_encoding = 'ascii'
429 self.stdin_encoding = 'ascii'
430
430
431 def init_syntax_highlighting(self):
431 def init_syntax_highlighting(self):
432 # Python source parser/formatter for syntax highlighting
432 # Python source parser/formatter for syntax highlighting
433 pyformat = PyColorize.Parser().format
433 pyformat = PyColorize.Parser().format
434 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
434 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
435
435
436 def init_pushd_popd_magic(self):
436 def init_pushd_popd_magic(self):
437 # for pushd/popd management
437 # for pushd/popd management
438 try:
438 try:
439 self.home_dir = get_home_dir()
439 self.home_dir = get_home_dir()
440 except HomeDirError, msg:
440 except HomeDirError, msg:
441 fatal(msg)
441 fatal(msg)
442
442
443 self.dir_stack = []
443 self.dir_stack = []
444
444
445 def init_logger(self):
445 def init_logger(self):
446 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
446 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
447 logmode='rotate')
447 logmode='rotate')
448
448
449 def init_logstart(self):
449 def init_logstart(self):
450 """Initialize logging in case it was requested at the command line.
450 """Initialize logging in case it was requested at the command line.
451 """
451 """
452 if self.logappend:
452 if self.logappend:
453 self.magic_logstart(self.logappend + ' append')
453 self.magic_logstart(self.logappend + ' append')
454 elif self.logfile:
454 elif self.logfile:
455 self.magic_logstart(self.logfile)
455 self.magic_logstart(self.logfile)
456 elif self.logstart:
456 elif self.logstart:
457 self.magic_logstart()
457 self.magic_logstart()
458
458
459 def init_builtins(self):
459 def init_builtins(self):
460 self.builtin_trap = BuiltinTrap(shell=self)
460 self.builtin_trap = BuiltinTrap(shell=self)
461
461
462 def init_inspector(self):
462 def init_inspector(self):
463 # Object inspector
463 # Object inspector
464 self.inspector = oinspect.Inspector(oinspect.InspectColors,
464 self.inspector = oinspect.Inspector(oinspect.InspectColors,
465 PyColorize.ANSICodeColors,
465 PyColorize.ANSICodeColors,
466 'NoColor',
466 'NoColor',
467 self.object_info_string_level)
467 self.object_info_string_level)
468
468
469 def init_io(self):
469 def init_io(self):
470 # This will just use sys.stdout and sys.stderr. If you want to
470 # This will just use sys.stdout and sys.stderr. If you want to
471 # override sys.stdout and sys.stderr themselves, you need to do that
471 # override sys.stdout and sys.stderr themselves, you need to do that
472 # *before* instantiating this class, because Term holds onto
472 # *before* instantiating this class, because Term holds onto
473 # references to the underlying streams.
473 # references to the underlying streams.
474 if sys.platform == 'win32' and self.has_readline:
474 if sys.platform == 'win32' and self.has_readline:
475 Term = io.IOTerm(cout=self.readline._outputfile,
475 Term = io.IOTerm(cout=self.readline._outputfile,
476 cerr=self.readline._outputfile)
476 cerr=self.readline._outputfile)
477 else:
477 else:
478 Term = io.IOTerm()
478 Term = io.IOTerm()
479 io.Term = Term
479 io.Term = Term
480
480
481 def init_prompts(self):
481 def init_prompts(self):
482 # TODO: This is a pass for now because the prompts are managed inside
482 # TODO: This is a pass for now because the prompts are managed inside
483 # the DisplayHook. Once there is a separate prompt manager, this
483 # the DisplayHook. Once there is a separate prompt manager, this
484 # will initialize that object and all prompt related information.
484 # will initialize that object and all prompt related information.
485 pass
485 pass
486
486
487 def init_display_formatter(self):
487 def init_display_formatter(self):
488 self.display_formatter = DisplayFormatter(config=self.config)
488 self.display_formatter = DisplayFormatter(config=self.config)
489
489
490 def init_display_pub(self):
490 def init_display_pub(self):
491 self.display_pub = self.display_pub_class(config=self.config)
491 self.display_pub = self.display_pub_class(config=self.config)
492
492
493 def init_displayhook(self):
493 def init_displayhook(self):
494 # Initialize displayhook, set in/out prompts and printing system
494 # Initialize displayhook, set in/out prompts and printing system
495 self.displayhook = self.displayhook_class(
495 self.displayhook = self.displayhook_class(
496 config=self.config,
496 config=self.config,
497 shell=self,
497 shell=self,
498 cache_size=self.cache_size,
498 cache_size=self.cache_size,
499 input_sep = self.separate_in,
499 input_sep = self.separate_in,
500 output_sep = self.separate_out,
500 output_sep = self.separate_out,
501 output_sep2 = self.separate_out2,
501 output_sep2 = self.separate_out2,
502 ps1 = self.prompt_in1,
502 ps1 = self.prompt_in1,
503 ps2 = self.prompt_in2,
503 ps2 = self.prompt_in2,
504 ps_out = self.prompt_out,
504 ps_out = self.prompt_out,
505 pad_left = self.prompts_pad_left
505 pad_left = self.prompts_pad_left
506 )
506 )
507 # This is a context manager that installs/revmoes the displayhook at
507 # This is a context manager that installs/revmoes the displayhook at
508 # the appropriate time.
508 # the appropriate time.
509 self.display_trap = DisplayTrap(hook=self.displayhook)
509 self.display_trap = DisplayTrap(hook=self.displayhook)
510
510
511 def init_reload_doctest(self):
511 def init_reload_doctest(self):
512 # Do a proper resetting of doctest, including the necessary displayhook
512 # Do a proper resetting of doctest, including the necessary displayhook
513 # monkeypatching
513 # monkeypatching
514 try:
514 try:
515 doctest_reload()
515 doctest_reload()
516 except ImportError:
516 except ImportError:
517 warn("doctest module does not exist.")
517 warn("doctest module does not exist.")
518
518
519 #-------------------------------------------------------------------------
519 #-------------------------------------------------------------------------
520 # Things related to injections into the sys module
520 # Things related to injections into the sys module
521 #-------------------------------------------------------------------------
521 #-------------------------------------------------------------------------
522
522
523 def save_sys_module_state(self):
523 def save_sys_module_state(self):
524 """Save the state of hooks in the sys module.
524 """Save the state of hooks in the sys module.
525
525
526 This has to be called after self.user_ns is created.
526 This has to be called after self.user_ns is created.
527 """
527 """
528 self._orig_sys_module_state = {}
528 self._orig_sys_module_state = {}
529 self._orig_sys_module_state['stdin'] = sys.stdin
529 self._orig_sys_module_state['stdin'] = sys.stdin
530 self._orig_sys_module_state['stdout'] = sys.stdout
530 self._orig_sys_module_state['stdout'] = sys.stdout
531 self._orig_sys_module_state['stderr'] = sys.stderr
531 self._orig_sys_module_state['stderr'] = sys.stderr
532 self._orig_sys_module_state['excepthook'] = sys.excepthook
532 self._orig_sys_module_state['excepthook'] = sys.excepthook
533 try:
533 try:
534 self._orig_sys_modules_main_name = self.user_ns['__name__']
534 self._orig_sys_modules_main_name = self.user_ns['__name__']
535 except KeyError:
535 except KeyError:
536 pass
536 pass
537
537
538 def restore_sys_module_state(self):
538 def restore_sys_module_state(self):
539 """Restore the state of the sys module."""
539 """Restore the state of the sys module."""
540 try:
540 try:
541 for k, v in self._orig_sys_module_state.iteritems():
541 for k, v in self._orig_sys_module_state.iteritems():
542 setattr(sys, k, v)
542 setattr(sys, k, v)
543 except AttributeError:
543 except AttributeError:
544 pass
544 pass
545 # Reset what what done in self.init_sys_modules
545 # Reset what what done in self.init_sys_modules
546 try:
546 try:
547 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
547 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
548 except (AttributeError, KeyError):
548 except (AttributeError, KeyError):
549 pass
549 pass
550
550
551 #-------------------------------------------------------------------------
551 #-------------------------------------------------------------------------
552 # Things related to hooks
552 # Things related to hooks
553 #-------------------------------------------------------------------------
553 #-------------------------------------------------------------------------
554
554
555 def init_hooks(self):
555 def init_hooks(self):
556 # hooks holds pointers used for user-side customizations
556 # hooks holds pointers used for user-side customizations
557 self.hooks = Struct()
557 self.hooks = Struct()
558
558
559 self.strdispatchers = {}
559 self.strdispatchers = {}
560
560
561 # Set all default hooks, defined in the IPython.hooks module.
561 # Set all default hooks, defined in the IPython.hooks module.
562 hooks = IPython.core.hooks
562 hooks = IPython.core.hooks
563 for hook_name in hooks.__all__:
563 for hook_name in hooks.__all__:
564 # default hooks have priority 100, i.e. low; user hooks should have
564 # default hooks have priority 100, i.e. low; user hooks should have
565 # 0-100 priority
565 # 0-100 priority
566 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
566 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
567
567
568 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
568 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
569 """set_hook(name,hook) -> sets an internal IPython hook.
569 """set_hook(name,hook) -> sets an internal IPython hook.
570
570
571 IPython exposes some of its internal API as user-modifiable hooks. By
571 IPython exposes some of its internal API as user-modifiable hooks. By
572 adding your function to one of these hooks, you can modify IPython's
572 adding your function to one of these hooks, you can modify IPython's
573 behavior to call at runtime your own routines."""
573 behavior to call at runtime your own routines."""
574
574
575 # At some point in the future, this should validate the hook before it
575 # At some point in the future, this should validate the hook before it
576 # accepts it. Probably at least check that the hook takes the number
576 # accepts it. Probably at least check that the hook takes the number
577 # of args it's supposed to.
577 # of args it's supposed to.
578
578
579 f = types.MethodType(hook,self)
579 f = types.MethodType(hook,self)
580
580
581 # check if the hook is for strdispatcher first
581 # check if the hook is for strdispatcher first
582 if str_key is not None:
582 if str_key is not None:
583 sdp = self.strdispatchers.get(name, StrDispatch())
583 sdp = self.strdispatchers.get(name, StrDispatch())
584 sdp.add_s(str_key, f, priority )
584 sdp.add_s(str_key, f, priority )
585 self.strdispatchers[name] = sdp
585 self.strdispatchers[name] = sdp
586 return
586 return
587 if re_key is not None:
587 if re_key is not None:
588 sdp = self.strdispatchers.get(name, StrDispatch())
588 sdp = self.strdispatchers.get(name, StrDispatch())
589 sdp.add_re(re.compile(re_key), f, priority )
589 sdp.add_re(re.compile(re_key), f, priority )
590 self.strdispatchers[name] = sdp
590 self.strdispatchers[name] = sdp
591 return
591 return
592
592
593 dp = getattr(self.hooks, name, None)
593 dp = getattr(self.hooks, name, None)
594 if name not in IPython.core.hooks.__all__:
594 if name not in IPython.core.hooks.__all__:
595 print "Warning! Hook '%s' is not one of %s" % \
595 print "Warning! Hook '%s' is not one of %s" % \
596 (name, IPython.core.hooks.__all__ )
596 (name, IPython.core.hooks.__all__ )
597 if not dp:
597 if not dp:
598 dp = IPython.core.hooks.CommandChainDispatcher()
598 dp = IPython.core.hooks.CommandChainDispatcher()
599
599
600 try:
600 try:
601 dp.add(f,priority)
601 dp.add(f,priority)
602 except AttributeError:
602 except AttributeError:
603 # it was not commandchain, plain old func - replace
603 # it was not commandchain, plain old func - replace
604 dp = f
604 dp = f
605
605
606 setattr(self.hooks,name, dp)
606 setattr(self.hooks,name, dp)
607
607
608 def register_post_execute(self, func):
608 def register_post_execute(self, func):
609 """Register a function for calling after code execution.
609 """Register a function for calling after code execution.
610 """
610 """
611 if not callable(func):
611 if not callable(func):
612 raise ValueError('argument %s must be callable' % func)
612 raise ValueError('argument %s must be callable' % func)
613 self._post_execute.add(func)
613 self._post_execute.add(func)
614
614
615 #-------------------------------------------------------------------------
615 #-------------------------------------------------------------------------
616 # Things related to the "main" module
616 # Things related to the "main" module
617 #-------------------------------------------------------------------------
617 #-------------------------------------------------------------------------
618
618
619 def new_main_mod(self,ns=None):
619 def new_main_mod(self,ns=None):
620 """Return a new 'main' module object for user code execution.
620 """Return a new 'main' module object for user code execution.
621 """
621 """
622 main_mod = self._user_main_module
622 main_mod = self._user_main_module
623 init_fakemod_dict(main_mod,ns)
623 init_fakemod_dict(main_mod,ns)
624 return main_mod
624 return main_mod
625
625
626 def cache_main_mod(self,ns,fname):
626 def cache_main_mod(self,ns,fname):
627 """Cache a main module's namespace.
627 """Cache a main module's namespace.
628
628
629 When scripts are executed via %run, we must keep a reference to the
629 When scripts are executed via %run, we must keep a reference to the
630 namespace of their __main__ module (a FakeModule instance) around so
630 namespace of their __main__ module (a FakeModule instance) around so
631 that Python doesn't clear it, rendering objects defined therein
631 that Python doesn't clear it, rendering objects defined therein
632 useless.
632 useless.
633
633
634 This method keeps said reference in a private dict, keyed by the
634 This method keeps said reference in a private dict, keyed by the
635 absolute path of the module object (which corresponds to the script
635 absolute path of the module object (which corresponds to the script
636 path). This way, for multiple executions of the same script we only
636 path). This way, for multiple executions of the same script we only
637 keep one copy of the namespace (the last one), thus preventing memory
637 keep one copy of the namespace (the last one), thus preventing memory
638 leaks from old references while allowing the objects from the last
638 leaks from old references while allowing the objects from the last
639 execution to be accessible.
639 execution to be accessible.
640
640
641 Note: we can not allow the actual FakeModule instances to be deleted,
641 Note: we can not allow the actual FakeModule instances to be deleted,
642 because of how Python tears down modules (it hard-sets all their
642 because of how Python tears down modules (it hard-sets all their
643 references to None without regard for reference counts). This method
643 references to None without regard for reference counts). This method
644 must therefore make a *copy* of the given namespace, to allow the
644 must therefore make a *copy* of the given namespace, to allow the
645 original module's __dict__ to be cleared and reused.
645 original module's __dict__ to be cleared and reused.
646
646
647
647
648 Parameters
648 Parameters
649 ----------
649 ----------
650 ns : a namespace (a dict, typically)
650 ns : a namespace (a dict, typically)
651
651
652 fname : str
652 fname : str
653 Filename associated with the namespace.
653 Filename associated with the namespace.
654
654
655 Examples
655 Examples
656 --------
656 --------
657
657
658 In [10]: import IPython
658 In [10]: import IPython
659
659
660 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
660 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
661
661
662 In [12]: IPython.__file__ in _ip._main_ns_cache
662 In [12]: IPython.__file__ in _ip._main_ns_cache
663 Out[12]: True
663 Out[12]: True
664 """
664 """
665 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
665 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
666
666
667 def clear_main_mod_cache(self):
667 def clear_main_mod_cache(self):
668 """Clear the cache of main modules.
668 """Clear the cache of main modules.
669
669
670 Mainly for use by utilities like %reset.
670 Mainly for use by utilities like %reset.
671
671
672 Examples
672 Examples
673 --------
673 --------
674
674
675 In [15]: import IPython
675 In [15]: import IPython
676
676
677 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
677 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
678
678
679 In [17]: len(_ip._main_ns_cache) > 0
679 In [17]: len(_ip._main_ns_cache) > 0
680 Out[17]: True
680 Out[17]: True
681
681
682 In [18]: _ip.clear_main_mod_cache()
682 In [18]: _ip.clear_main_mod_cache()
683
683
684 In [19]: len(_ip._main_ns_cache) == 0
684 In [19]: len(_ip._main_ns_cache) == 0
685 Out[19]: True
685 Out[19]: True
686 """
686 """
687 self._main_ns_cache.clear()
687 self._main_ns_cache.clear()
688
688
689 #-------------------------------------------------------------------------
689 #-------------------------------------------------------------------------
690 # Things related to debugging
690 # Things related to debugging
691 #-------------------------------------------------------------------------
691 #-------------------------------------------------------------------------
692
692
693 def init_pdb(self):
693 def init_pdb(self):
694 # Set calling of pdb on exceptions
694 # Set calling of pdb on exceptions
695 # self.call_pdb is a property
695 # self.call_pdb is a property
696 self.call_pdb = self.pdb
696 self.call_pdb = self.pdb
697
697
698 def _get_call_pdb(self):
698 def _get_call_pdb(self):
699 return self._call_pdb
699 return self._call_pdb
700
700
701 def _set_call_pdb(self,val):
701 def _set_call_pdb(self,val):
702
702
703 if val not in (0,1,False,True):
703 if val not in (0,1,False,True):
704 raise ValueError,'new call_pdb value must be boolean'
704 raise ValueError,'new call_pdb value must be boolean'
705
705
706 # store value in instance
706 # store value in instance
707 self._call_pdb = val
707 self._call_pdb = val
708
708
709 # notify the actual exception handlers
709 # notify the actual exception handlers
710 self.InteractiveTB.call_pdb = val
710 self.InteractiveTB.call_pdb = val
711
711
712 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
712 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
713 'Control auto-activation of pdb at exceptions')
713 'Control auto-activation of pdb at exceptions')
714
714
715 def debugger(self,force=False):
715 def debugger(self,force=False):
716 """Call the pydb/pdb debugger.
716 """Call the pydb/pdb debugger.
717
717
718 Keywords:
718 Keywords:
719
719
720 - force(False): by default, this routine checks the instance call_pdb
720 - force(False): by default, this routine checks the instance call_pdb
721 flag and does not actually invoke the debugger if the flag is false.
721 flag and does not actually invoke the debugger if the flag is false.
722 The 'force' option forces the debugger to activate even if the flag
722 The 'force' option forces the debugger to activate even if the flag
723 is false.
723 is false.
724 """
724 """
725
725
726 if not (force or self.call_pdb):
726 if not (force or self.call_pdb):
727 return
727 return
728
728
729 if not hasattr(sys,'last_traceback'):
729 if not hasattr(sys,'last_traceback'):
730 error('No traceback has been produced, nothing to debug.')
730 error('No traceback has been produced, nothing to debug.')
731 return
731 return
732
732
733 # use pydb if available
733 # use pydb if available
734 if debugger.has_pydb:
734 if debugger.has_pydb:
735 from pydb import pm
735 from pydb import pm
736 else:
736 else:
737 # fallback to our internal debugger
737 # fallback to our internal debugger
738 pm = lambda : self.InteractiveTB.debugger(force=True)
738 pm = lambda : self.InteractiveTB.debugger(force=True)
739 self.history_saving_wrapper(pm)()
739 self.history_saving_wrapper(pm)()
740
740
741 #-------------------------------------------------------------------------
741 #-------------------------------------------------------------------------
742 # Things related to IPython's various namespaces
742 # Things related to IPython's various namespaces
743 #-------------------------------------------------------------------------
743 #-------------------------------------------------------------------------
744
744
745 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
745 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
746 # Create the namespace where the user will operate. user_ns is
746 # Create the namespace where the user will operate. user_ns is
747 # normally the only one used, and it is passed to the exec calls as
747 # normally the only one used, and it is passed to the exec calls as
748 # the locals argument. But we do carry a user_global_ns namespace
748 # the locals argument. But we do carry a user_global_ns namespace
749 # given as the exec 'globals' argument, This is useful in embedding
749 # given as the exec 'globals' argument, This is useful in embedding
750 # situations where the ipython shell opens in a context where the
750 # situations where the ipython shell opens in a context where the
751 # distinction between locals and globals is meaningful. For
751 # distinction between locals and globals is meaningful. For
752 # non-embedded contexts, it is just the same object as the user_ns dict.
752 # non-embedded contexts, it is just the same object as the user_ns dict.
753
753
754 # FIXME. For some strange reason, __builtins__ is showing up at user
754 # FIXME. For some strange reason, __builtins__ is showing up at user
755 # level as a dict instead of a module. This is a manual fix, but I
755 # level as a dict instead of a module. This is a manual fix, but I
756 # should really track down where the problem is coming from. Alex
756 # should really track down where the problem is coming from. Alex
757 # Schmolck reported this problem first.
757 # Schmolck reported this problem first.
758
758
759 # A useful post by Alex Martelli on this topic:
759 # A useful post by Alex Martelli on this topic:
760 # Re: inconsistent value from __builtins__
760 # Re: inconsistent value from __builtins__
761 # Von: Alex Martelli <aleaxit@yahoo.com>
761 # Von: Alex Martelli <aleaxit@yahoo.com>
762 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
762 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
763 # Gruppen: comp.lang.python
763 # Gruppen: comp.lang.python
764
764
765 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
765 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
766 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
766 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
767 # > <type 'dict'>
767 # > <type 'dict'>
768 # > >>> print type(__builtins__)
768 # > >>> print type(__builtins__)
769 # > <type 'module'>
769 # > <type 'module'>
770 # > Is this difference in return value intentional?
770 # > Is this difference in return value intentional?
771
771
772 # Well, it's documented that '__builtins__' can be either a dictionary
772 # Well, it's documented that '__builtins__' can be either a dictionary
773 # or a module, and it's been that way for a long time. Whether it's
773 # or a module, and it's been that way for a long time. Whether it's
774 # intentional (or sensible), I don't know. In any case, the idea is
774 # intentional (or sensible), I don't know. In any case, the idea is
775 # that if you need to access the built-in namespace directly, you
775 # that if you need to access the built-in namespace directly, you
776 # should start with "import __builtin__" (note, no 's') which will
776 # should start with "import __builtin__" (note, no 's') which will
777 # definitely give you a module. Yeah, it's somewhat confusing:-(.
777 # definitely give you a module. Yeah, it's somewhat confusing:-(.
778
778
779 # These routines return properly built dicts as needed by the rest of
779 # These routines return properly built dicts as needed by the rest of
780 # the code, and can also be used by extension writers to generate
780 # the code, and can also be used by extension writers to generate
781 # properly initialized namespaces.
781 # properly initialized namespaces.
782 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
782 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
783 user_global_ns)
783 user_global_ns)
784
784
785 # Assign namespaces
785 # Assign namespaces
786 # This is the namespace where all normal user variables live
786 # This is the namespace where all normal user variables live
787 self.user_ns = user_ns
787 self.user_ns = user_ns
788 self.user_global_ns = user_global_ns
788 self.user_global_ns = user_global_ns
789
789
790 # An auxiliary namespace that checks what parts of the user_ns were
790 # An auxiliary namespace that checks what parts of the user_ns were
791 # loaded at startup, so we can list later only variables defined in
791 # loaded at startup, so we can list later only variables defined in
792 # actual interactive use. Since it is always a subset of user_ns, it
792 # actual interactive use. Since it is always a subset of user_ns, it
793 # doesn't need to be separately tracked in the ns_table.
793 # doesn't need to be separately tracked in the ns_table.
794 self.user_ns_hidden = {}
794 self.user_ns_hidden = {}
795
795
796 # A namespace to keep track of internal data structures to prevent
796 # A namespace to keep track of internal data structures to prevent
797 # them from cluttering user-visible stuff. Will be updated later
797 # them from cluttering user-visible stuff. Will be updated later
798 self.internal_ns = {}
798 self.internal_ns = {}
799
799
800 # Now that FakeModule produces a real module, we've run into a nasty
800 # Now that FakeModule produces a real module, we've run into a nasty
801 # problem: after script execution (via %run), the module where the user
801 # problem: after script execution (via %run), the module where the user
802 # code ran is deleted. Now that this object is a true module (needed
802 # code ran is deleted. Now that this object is a true module (needed
803 # so docetst and other tools work correctly), the Python module
803 # so docetst and other tools work correctly), the Python module
804 # teardown mechanism runs over it, and sets to None every variable
804 # teardown mechanism runs over it, and sets to None every variable
805 # present in that module. Top-level references to objects from the
805 # present in that module. Top-level references to objects from the
806 # script survive, because the user_ns is updated with them. However,
806 # script survive, because the user_ns is updated with them. However,
807 # calling functions defined in the script that use other things from
807 # calling functions defined in the script that use other things from
808 # the script will fail, because the function's closure had references
808 # the script will fail, because the function's closure had references
809 # to the original objects, which are now all None. So we must protect
809 # to the original objects, which are now all None. So we must protect
810 # these modules from deletion by keeping a cache.
810 # these modules from deletion by keeping a cache.
811 #
811 #
812 # To avoid keeping stale modules around (we only need the one from the
812 # To avoid keeping stale modules around (we only need the one from the
813 # last run), we use a dict keyed with the full path to the script, so
813 # last run), we use a dict keyed with the full path to the script, so
814 # only the last version of the module is held in the cache. Note,
814 # only the last version of the module is held in the cache. Note,
815 # however, that we must cache the module *namespace contents* (their
815 # however, that we must cache the module *namespace contents* (their
816 # __dict__). Because if we try to cache the actual modules, old ones
816 # __dict__). Because if we try to cache the actual modules, old ones
817 # (uncached) could be destroyed while still holding references (such as
817 # (uncached) could be destroyed while still holding references (such as
818 # those held by GUI objects that tend to be long-lived)>
818 # those held by GUI objects that tend to be long-lived)>
819 #
819 #
820 # The %reset command will flush this cache. See the cache_main_mod()
820 # The %reset command will flush this cache. See the cache_main_mod()
821 # and clear_main_mod_cache() methods for details on use.
821 # and clear_main_mod_cache() methods for details on use.
822
822
823 # This is the cache used for 'main' namespaces
823 # This is the cache used for 'main' namespaces
824 self._main_ns_cache = {}
824 self._main_ns_cache = {}
825 # And this is the single instance of FakeModule whose __dict__ we keep
825 # And this is the single instance of FakeModule whose __dict__ we keep
826 # copying and clearing for reuse on each %run
826 # copying and clearing for reuse on each %run
827 self._user_main_module = FakeModule()
827 self._user_main_module = FakeModule()
828
828
829 # A table holding all the namespaces IPython deals with, so that
829 # A table holding all the namespaces IPython deals with, so that
830 # introspection facilities can search easily.
830 # introspection facilities can search easily.
831 self.ns_table = {'user':user_ns,
831 self.ns_table = {'user':user_ns,
832 'user_global':user_global_ns,
832 'user_global':user_global_ns,
833 'internal':self.internal_ns,
833 'internal':self.internal_ns,
834 'builtin':__builtin__.__dict__
834 'builtin':__builtin__.__dict__
835 }
835 }
836
836
837 # Similarly, track all namespaces where references can be held and that
837 # Similarly, track all namespaces where references can be held and that
838 # we can safely clear (so it can NOT include builtin). This one can be
838 # we can safely clear (so it can NOT include builtin). This one can be
839 # a simple list. Note that the main execution namespaces, user_ns and
839 # a simple list. Note that the main execution namespaces, user_ns and
840 # user_global_ns, can NOT be listed here, as clearing them blindly
840 # user_global_ns, can NOT be listed here, as clearing them blindly
841 # causes errors in object __del__ methods. Instead, the reset() method
841 # causes errors in object __del__ methods. Instead, the reset() method
842 # clears them manually and carefully.
842 # clears them manually and carefully.
843 self.ns_refs_table = [ self.user_ns_hidden,
843 self.ns_refs_table = [ self.user_ns_hidden,
844 self.internal_ns, self._main_ns_cache ]
844 self.internal_ns, self._main_ns_cache ]
845
845
846 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
846 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
847 """Return a valid local and global user interactive namespaces.
847 """Return a valid local and global user interactive namespaces.
848
848
849 This builds a dict with the minimal information needed to operate as a
849 This builds a dict with the minimal information needed to operate as a
850 valid IPython user namespace, which you can pass to the various
850 valid IPython user namespace, which you can pass to the various
851 embedding classes in ipython. The default implementation returns the
851 embedding classes in ipython. The default implementation returns the
852 same dict for both the locals and the globals to allow functions to
852 same dict for both the locals and the globals to allow functions to
853 refer to variables in the namespace. Customized implementations can
853 refer to variables in the namespace. Customized implementations can
854 return different dicts. The locals dictionary can actually be anything
854 return different dicts. The locals dictionary can actually be anything
855 following the basic mapping protocol of a dict, but the globals dict
855 following the basic mapping protocol of a dict, but the globals dict
856 must be a true dict, not even a subclass. It is recommended that any
856 must be a true dict, not even a subclass. It is recommended that any
857 custom object for the locals namespace synchronize with the globals
857 custom object for the locals namespace synchronize with the globals
858 dict somehow.
858 dict somehow.
859
859
860 Raises TypeError if the provided globals namespace is not a true dict.
860 Raises TypeError if the provided globals namespace is not a true dict.
861
861
862 Parameters
862 Parameters
863 ----------
863 ----------
864 user_ns : dict-like, optional
864 user_ns : dict-like, optional
865 The current user namespace. The items in this namespace should
865 The current user namespace. The items in this namespace should
866 be included in the output. If None, an appropriate blank
866 be included in the output. If None, an appropriate blank
867 namespace should be created.
867 namespace should be created.
868 user_global_ns : dict, optional
868 user_global_ns : dict, optional
869 The current user global namespace. The items in this namespace
869 The current user global namespace. The items in this namespace
870 should be included in the output. If None, an appropriate
870 should be included in the output. If None, an appropriate
871 blank namespace should be created.
871 blank namespace should be created.
872
872
873 Returns
873 Returns
874 -------
874 -------
875 A pair of dictionary-like object to be used as the local namespace
875 A pair of dictionary-like object to be used as the local namespace
876 of the interpreter and a dict to be used as the global namespace.
876 of the interpreter and a dict to be used as the global namespace.
877 """
877 """
878
878
879
879
880 # We must ensure that __builtin__ (without the final 's') is always
880 # We must ensure that __builtin__ (without the final 's') is always
881 # available and pointing to the __builtin__ *module*. For more details:
881 # available and pointing to the __builtin__ *module*. For more details:
882 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
882 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
883
883
884 if user_ns is None:
884 if user_ns is None:
885 # Set __name__ to __main__ to better match the behavior of the
885 # Set __name__ to __main__ to better match the behavior of the
886 # normal interpreter.
886 # normal interpreter.
887 user_ns = {'__name__' :'__main__',
887 user_ns = {'__name__' :'__main__',
888 '__builtin__' : __builtin__,
888 '__builtin__' : __builtin__,
889 '__builtins__' : __builtin__,
889 '__builtins__' : __builtin__,
890 }
890 }
891 else:
891 else:
892 user_ns.setdefault('__name__','__main__')
892 user_ns.setdefault('__name__','__main__')
893 user_ns.setdefault('__builtin__',__builtin__)
893 user_ns.setdefault('__builtin__',__builtin__)
894 user_ns.setdefault('__builtins__',__builtin__)
894 user_ns.setdefault('__builtins__',__builtin__)
895
895
896 if user_global_ns is None:
896 if user_global_ns is None:
897 user_global_ns = user_ns
897 user_global_ns = user_ns
898 if type(user_global_ns) is not dict:
898 if type(user_global_ns) is not dict:
899 raise TypeError("user_global_ns must be a true dict; got %r"
899 raise TypeError("user_global_ns must be a true dict; got %r"
900 % type(user_global_ns))
900 % type(user_global_ns))
901
901
902 return user_ns, user_global_ns
902 return user_ns, user_global_ns
903
903
904 def init_sys_modules(self):
904 def init_sys_modules(self):
905 # We need to insert into sys.modules something that looks like a
905 # We need to insert into sys.modules something that looks like a
906 # module but which accesses the IPython namespace, for shelve and
906 # module but which accesses the IPython namespace, for shelve and
907 # pickle to work interactively. Normally they rely on getting
907 # pickle to work interactively. Normally they rely on getting
908 # everything out of __main__, but for embedding purposes each IPython
908 # everything out of __main__, but for embedding purposes each IPython
909 # instance has its own private namespace, so we can't go shoving
909 # instance has its own private namespace, so we can't go shoving
910 # everything into __main__.
910 # everything into __main__.
911
911
912 # note, however, that we should only do this for non-embedded
912 # note, however, that we should only do this for non-embedded
913 # ipythons, which really mimic the __main__.__dict__ with their own
913 # ipythons, which really mimic the __main__.__dict__ with their own
914 # namespace. Embedded instances, on the other hand, should not do
914 # namespace. Embedded instances, on the other hand, should not do
915 # this because they need to manage the user local/global namespaces
915 # this because they need to manage the user local/global namespaces
916 # only, but they live within a 'normal' __main__ (meaning, they
916 # only, but they live within a 'normal' __main__ (meaning, they
917 # shouldn't overtake the execution environment of the script they're
917 # shouldn't overtake the execution environment of the script they're
918 # embedded in).
918 # embedded in).
919
919
920 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
920 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
921
921
922 try:
922 try:
923 main_name = self.user_ns['__name__']
923 main_name = self.user_ns['__name__']
924 except KeyError:
924 except KeyError:
925 raise KeyError('user_ns dictionary MUST have a "__name__" key')
925 raise KeyError('user_ns dictionary MUST have a "__name__" key')
926 else:
926 else:
927 sys.modules[main_name] = FakeModule(self.user_ns)
927 sys.modules[main_name] = FakeModule(self.user_ns)
928
928
929 def init_user_ns(self):
929 def init_user_ns(self):
930 """Initialize all user-visible namespaces to their minimum defaults.
930 """Initialize all user-visible namespaces to their minimum defaults.
931
931
932 Certain history lists are also initialized here, as they effectively
932 Certain history lists are also initialized here, as they effectively
933 act as user namespaces.
933 act as user namespaces.
934
934
935 Notes
935 Notes
936 -----
936 -----
937 All data structures here are only filled in, they are NOT reset by this
937 All data structures here are only filled in, they are NOT reset by this
938 method. If they were not empty before, data will simply be added to
938 method. If they were not empty before, data will simply be added to
939 therm.
939 therm.
940 """
940 """
941 # This function works in two parts: first we put a few things in
941 # This function works in two parts: first we put a few things in
942 # user_ns, and we sync that contents into user_ns_hidden so that these
942 # user_ns, and we sync that contents into user_ns_hidden so that these
943 # initial variables aren't shown by %who. After the sync, we add the
943 # initial variables aren't shown by %who. After the sync, we add the
944 # rest of what we *do* want the user to see with %who even on a new
944 # rest of what we *do* want the user to see with %who even on a new
945 # session (probably nothing, so theye really only see their own stuff)
945 # session (probably nothing, so theye really only see their own stuff)
946
946
947 # The user dict must *always* have a __builtin__ reference to the
947 # The user dict must *always* have a __builtin__ reference to the
948 # Python standard __builtin__ namespace, which must be imported.
948 # Python standard __builtin__ namespace, which must be imported.
949 # This is so that certain operations in prompt evaluation can be
949 # This is so that certain operations in prompt evaluation can be
950 # reliably executed with builtins. Note that we can NOT use
950 # reliably executed with builtins. Note that we can NOT use
951 # __builtins__ (note the 's'), because that can either be a dict or a
951 # __builtins__ (note the 's'), because that can either be a dict or a
952 # module, and can even mutate at runtime, depending on the context
952 # module, and can even mutate at runtime, depending on the context
953 # (Python makes no guarantees on it). In contrast, __builtin__ is
953 # (Python makes no guarantees on it). In contrast, __builtin__ is
954 # always a module object, though it must be explicitly imported.
954 # always a module object, though it must be explicitly imported.
955
955
956 # For more details:
956 # For more details:
957 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
957 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
958 ns = dict(__builtin__ = __builtin__)
958 ns = dict(__builtin__ = __builtin__)
959
959
960 # Put 'help' in the user namespace
960 # Put 'help' in the user namespace
961 try:
961 try:
962 from site import _Helper
962 from site import _Helper
963 ns['help'] = _Helper()
963 ns['help'] = _Helper()
964 except ImportError:
964 except ImportError:
965 warn('help() not available - check site.py')
965 warn('help() not available - check site.py')
966
966
967 # make global variables for user access to the histories
967 # make global variables for user access to the histories
968 ns['_ih'] = self.history_manager.input_hist_parsed
968 ns['_ih'] = self.history_manager.input_hist_parsed
969 ns['_oh'] = self.history_manager.output_hist
969 ns['_oh'] = self.history_manager.output_hist
970 ns['_dh'] = self.history_manager.dir_hist
970 ns['_dh'] = self.history_manager.dir_hist
971
971
972 ns['_sh'] = shadowns
972 ns['_sh'] = shadowns
973
973
974 # user aliases to input and output histories. These shouldn't show up
974 # user aliases to input and output histories. These shouldn't show up
975 # in %who, as they can have very large reprs.
975 # in %who, as they can have very large reprs.
976 ns['In'] = self.history_manager.input_hist_parsed
976 ns['In'] = self.history_manager.input_hist_parsed
977 ns['Out'] = self.history_manager.output_hist
977 ns['Out'] = self.history_manager.output_hist
978
978
979 # Store myself as the public api!!!
979 # Store myself as the public api!!!
980 ns['get_ipython'] = self.get_ipython
980 ns['get_ipython'] = self.get_ipython
981
981
982 # Sync what we've added so far to user_ns_hidden so these aren't seen
982 # Sync what we've added so far to user_ns_hidden so these aren't seen
983 # by %who
983 # by %who
984 self.user_ns_hidden.update(ns)
984 self.user_ns_hidden.update(ns)
985
985
986 # Anything put into ns now would show up in %who. Think twice before
986 # Anything put into ns now would show up in %who. Think twice before
987 # putting anything here, as we really want %who to show the user their
987 # putting anything here, as we really want %who to show the user their
988 # stuff, not our variables.
988 # stuff, not our variables.
989
989
990 # Finally, update the real user's namespace
990 # Finally, update the real user's namespace
991 self.user_ns.update(ns)
991 self.user_ns.update(ns)
992
992
993 def reset(self, new_session=True):
993 def reset(self, new_session=True):
994 """Clear all internal namespaces.
994 """Clear all internal namespaces.
995
995
996 Note that this is much more aggressive than %reset, since it clears
996 Note that this is much more aggressive than %reset, since it clears
997 fully all namespaces, as well as all input/output lists.
997 fully all namespaces, as well as all input/output lists.
998
998
999 If new_session is True, a new history session will be opened.
999 If new_session is True, a new history session will be opened.
1000 """
1000 """
1001 # Clear histories
1001 # Clear histories
1002 self.history_manager.reset(new_session)
1002 self.history_manager.reset(new_session)
1003
1003
1004 # Reset counter used to index all histories
1004 # Reset counter used to index all histories
1005 self.execution_count = 0
1005 self.execution_count = 0
1006
1006
1007 # Restore the user namespaces to minimal usability
1007 # Restore the user namespaces to minimal usability
1008 for ns in self.ns_refs_table:
1008 for ns in self.ns_refs_table:
1009 ns.clear()
1009 ns.clear()
1010
1010
1011 # The main execution namespaces must be cleared very carefully,
1011 # The main execution namespaces must be cleared very carefully,
1012 # skipping the deletion of the builtin-related keys, because doing so
1012 # skipping the deletion of the builtin-related keys, because doing so
1013 # would cause errors in many object's __del__ methods.
1013 # would cause errors in many object's __del__ methods.
1014 for ns in [self.user_ns, self.user_global_ns]:
1014 for ns in [self.user_ns, self.user_global_ns]:
1015 drop_keys = set(ns.keys())
1015 drop_keys = set(ns.keys())
1016 drop_keys.discard('__builtin__')
1016 drop_keys.discard('__builtin__')
1017 drop_keys.discard('__builtins__')
1017 drop_keys.discard('__builtins__')
1018 for k in drop_keys:
1018 for k in drop_keys:
1019 del ns[k]
1019 del ns[k]
1020
1020
1021 # Restore the user namespaces to minimal usability
1021 # Restore the user namespaces to minimal usability
1022 self.init_user_ns()
1022 self.init_user_ns()
1023
1023
1024 # Restore the default and user aliases
1024 # Restore the default and user aliases
1025 self.alias_manager.clear_aliases()
1025 self.alias_manager.clear_aliases()
1026 self.alias_manager.init_aliases()
1026 self.alias_manager.init_aliases()
1027
1027
1028 def reset_selective(self, regex=None):
1028 def reset_selective(self, regex=None):
1029 """Clear selective variables from internal namespaces based on a
1029 """Clear selective variables from internal namespaces based on a
1030 specified regular expression.
1030 specified regular expression.
1031
1031
1032 Parameters
1032 Parameters
1033 ----------
1033 ----------
1034 regex : string or compiled pattern, optional
1034 regex : string or compiled pattern, optional
1035 A regular expression pattern that will be used in searching
1035 A regular expression pattern that will be used in searching
1036 variable names in the users namespaces.
1036 variable names in the users namespaces.
1037 """
1037 """
1038 if regex is not None:
1038 if regex is not None:
1039 try:
1039 try:
1040 m = re.compile(regex)
1040 m = re.compile(regex)
1041 except TypeError:
1041 except TypeError:
1042 raise TypeError('regex must be a string or compiled pattern')
1042 raise TypeError('regex must be a string or compiled pattern')
1043 # Search for keys in each namespace that match the given regex
1043 # Search for keys in each namespace that match the given regex
1044 # If a match is found, delete the key/value pair.
1044 # If a match is found, delete the key/value pair.
1045 for ns in self.ns_refs_table:
1045 for ns in self.ns_refs_table:
1046 for var in ns:
1046 for var in ns:
1047 if m.search(var):
1047 if m.search(var):
1048 del ns[var]
1048 del ns[var]
1049
1049
1050 def push(self, variables, interactive=True):
1050 def push(self, variables, interactive=True):
1051 """Inject a group of variables into the IPython user namespace.
1051 """Inject a group of variables into the IPython user namespace.
1052
1052
1053 Parameters
1053 Parameters
1054 ----------
1054 ----------
1055 variables : dict, str or list/tuple of str
1055 variables : dict, str or list/tuple of str
1056 The variables to inject into the user's namespace. If a dict, a
1056 The variables to inject into the user's namespace. If a dict, a
1057 simple update is done. If a str, the string is assumed to have
1057 simple update is done. If a str, the string is assumed to have
1058 variable names separated by spaces. A list/tuple of str can also
1058 variable names separated by spaces. A list/tuple of str can also
1059 be used to give the variable names. If just the variable names are
1059 be used to give the variable names. If just the variable names are
1060 give (list/tuple/str) then the variable values looked up in the
1060 give (list/tuple/str) then the variable values looked up in the
1061 callers frame.
1061 callers frame.
1062 interactive : bool
1062 interactive : bool
1063 If True (default), the variables will be listed with the ``who``
1063 If True (default), the variables will be listed with the ``who``
1064 magic.
1064 magic.
1065 """
1065 """
1066 vdict = None
1066 vdict = None
1067
1067
1068 # We need a dict of name/value pairs to do namespace updates.
1068 # We need a dict of name/value pairs to do namespace updates.
1069 if isinstance(variables, dict):
1069 if isinstance(variables, dict):
1070 vdict = variables
1070 vdict = variables
1071 elif isinstance(variables, (basestring, list, tuple)):
1071 elif isinstance(variables, (basestring, list, tuple)):
1072 if isinstance(variables, basestring):
1072 if isinstance(variables, basestring):
1073 vlist = variables.split()
1073 vlist = variables.split()
1074 else:
1074 else:
1075 vlist = variables
1075 vlist = variables
1076 vdict = {}
1076 vdict = {}
1077 cf = sys._getframe(1)
1077 cf = sys._getframe(1)
1078 for name in vlist:
1078 for name in vlist:
1079 try:
1079 try:
1080 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1080 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1081 except:
1081 except:
1082 print ('Could not get variable %s from %s' %
1082 print ('Could not get variable %s from %s' %
1083 (name,cf.f_code.co_name))
1083 (name,cf.f_code.co_name))
1084 else:
1084 else:
1085 raise ValueError('variables must be a dict/str/list/tuple')
1085 raise ValueError('variables must be a dict/str/list/tuple')
1086
1086
1087 # Propagate variables to user namespace
1087 # Propagate variables to user namespace
1088 self.user_ns.update(vdict)
1088 self.user_ns.update(vdict)
1089
1089
1090 # And configure interactive visibility
1090 # And configure interactive visibility
1091 config_ns = self.user_ns_hidden
1091 config_ns = self.user_ns_hidden
1092 if interactive:
1092 if interactive:
1093 for name, val in vdict.iteritems():
1093 for name, val in vdict.iteritems():
1094 config_ns.pop(name, None)
1094 config_ns.pop(name, None)
1095 else:
1095 else:
1096 for name,val in vdict.iteritems():
1096 for name,val in vdict.iteritems():
1097 config_ns[name] = val
1097 config_ns[name] = val
1098
1098
1099 #-------------------------------------------------------------------------
1099 #-------------------------------------------------------------------------
1100 # Things related to object introspection
1100 # Things related to object introspection
1101 #-------------------------------------------------------------------------
1101 #-------------------------------------------------------------------------
1102
1102
1103 def _ofind(self, oname, namespaces=None):
1103 def _ofind(self, oname, namespaces=None):
1104 """Find an object in the available namespaces.
1104 """Find an object in the available namespaces.
1105
1105
1106 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1106 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1107
1107
1108 Has special code to detect magic functions.
1108 Has special code to detect magic functions.
1109 """
1109 """
1110 #oname = oname.strip()
1110 #oname = oname.strip()
1111 #print '1- oname: <%r>' % oname # dbg
1111 #print '1- oname: <%r>' % oname # dbg
1112 try:
1112 try:
1113 oname = oname.strip().encode('ascii')
1113 oname = oname.strip().encode('ascii')
1114 #print '2- oname: <%r>' % oname # dbg
1114 #print '2- oname: <%r>' % oname # dbg
1115 except UnicodeEncodeError:
1115 except UnicodeEncodeError:
1116 print 'Python identifiers can only contain ascii characters.'
1116 print 'Python identifiers can only contain ascii characters.'
1117 return dict(found=False)
1117 return dict(found=False)
1118
1118
1119 alias_ns = None
1119 alias_ns = None
1120 if namespaces is None:
1120 if namespaces is None:
1121 # Namespaces to search in:
1121 # Namespaces to search in:
1122 # Put them in a list. The order is important so that we
1122 # Put them in a list. The order is important so that we
1123 # find things in the same order that Python finds them.
1123 # find things in the same order that Python finds them.
1124 namespaces = [ ('Interactive', self.user_ns),
1124 namespaces = [ ('Interactive', self.user_ns),
1125 ('IPython internal', self.internal_ns),
1125 ('IPython internal', self.internal_ns),
1126 ('Python builtin', __builtin__.__dict__),
1126 ('Python builtin', __builtin__.__dict__),
1127 ('Alias', self.alias_manager.alias_table),
1127 ('Alias', self.alias_manager.alias_table),
1128 ]
1128 ]
1129 alias_ns = self.alias_manager.alias_table
1129 alias_ns = self.alias_manager.alias_table
1130
1130
1131 # initialize results to 'null'
1131 # initialize results to 'null'
1132 found = False; obj = None; ospace = None; ds = None;
1132 found = False; obj = None; ospace = None; ds = None;
1133 ismagic = False; isalias = False; parent = None
1133 ismagic = False; isalias = False; parent = None
1134
1134
1135 # We need to special-case 'print', which as of python2.6 registers as a
1135 # We need to special-case 'print', which as of python2.6 registers as a
1136 # function but should only be treated as one if print_function was
1136 # function but should only be treated as one if print_function was
1137 # loaded with a future import. In this case, just bail.
1137 # loaded with a future import. In this case, just bail.
1138 if (oname == 'print' and not (self.compile.compiler_flags &
1138 if (oname == 'print' and not (self.compile.compiler_flags &
1139 __future__.CO_FUTURE_PRINT_FUNCTION)):
1139 __future__.CO_FUTURE_PRINT_FUNCTION)):
1140 return {'found':found, 'obj':obj, 'namespace':ospace,
1140 return {'found':found, 'obj':obj, 'namespace':ospace,
1141 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1141 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1142
1142
1143 # Look for the given name by splitting it in parts. If the head is
1143 # Look for the given name by splitting it in parts. If the head is
1144 # found, then we look for all the remaining parts as members, and only
1144 # found, then we look for all the remaining parts as members, and only
1145 # declare success if we can find them all.
1145 # declare success if we can find them all.
1146 oname_parts = oname.split('.')
1146 oname_parts = oname.split('.')
1147 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1147 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1148 for nsname,ns in namespaces:
1148 for nsname,ns in namespaces:
1149 try:
1149 try:
1150 obj = ns[oname_head]
1150 obj = ns[oname_head]
1151 except KeyError:
1151 except KeyError:
1152 continue
1152 continue
1153 else:
1153 else:
1154 #print 'oname_rest:', oname_rest # dbg
1154 #print 'oname_rest:', oname_rest # dbg
1155 for part in oname_rest:
1155 for part in oname_rest:
1156 try:
1156 try:
1157 parent = obj
1157 parent = obj
1158 obj = getattr(obj,part)
1158 obj = getattr(obj,part)
1159 except:
1159 except:
1160 # Blanket except b/c some badly implemented objects
1160 # Blanket except b/c some badly implemented objects
1161 # allow __getattr__ to raise exceptions other than
1161 # allow __getattr__ to raise exceptions other than
1162 # AttributeError, which then crashes IPython.
1162 # AttributeError, which then crashes IPython.
1163 break
1163 break
1164 else:
1164 else:
1165 # If we finish the for loop (no break), we got all members
1165 # If we finish the for loop (no break), we got all members
1166 found = True
1166 found = True
1167 ospace = nsname
1167 ospace = nsname
1168 if ns == alias_ns:
1168 if ns == alias_ns:
1169 isalias = True
1169 isalias = True
1170 break # namespace loop
1170 break # namespace loop
1171
1171
1172 # Try to see if it's magic
1172 # Try to see if it's magic
1173 if not found:
1173 if not found:
1174 if oname.startswith(ESC_MAGIC):
1174 if oname.startswith(ESC_MAGIC):
1175 oname = oname[1:]
1175 oname = oname[1:]
1176 obj = getattr(self,'magic_'+oname,None)
1176 obj = getattr(self,'magic_'+oname,None)
1177 if obj is not None:
1177 if obj is not None:
1178 found = True
1178 found = True
1179 ospace = 'IPython internal'
1179 ospace = 'IPython internal'
1180 ismagic = True
1180 ismagic = True
1181
1181
1182 # Last try: special-case some literals like '', [], {}, etc:
1182 # Last try: special-case some literals like '', [], {}, etc:
1183 if not found and oname_head in ["''",'""','[]','{}','()']:
1183 if not found and oname_head in ["''",'""','[]','{}','()']:
1184 obj = eval(oname_head)
1184 obj = eval(oname_head)
1185 found = True
1185 found = True
1186 ospace = 'Interactive'
1186 ospace = 'Interactive'
1187
1187
1188 return {'found':found, 'obj':obj, 'namespace':ospace,
1188 return {'found':found, 'obj':obj, 'namespace':ospace,
1189 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1189 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1190
1190
1191 def _ofind_property(self, oname, info):
1191 def _ofind_property(self, oname, info):
1192 """Second part of object finding, to look for property details."""
1192 """Second part of object finding, to look for property details."""
1193 if info.found:
1193 if info.found:
1194 # Get the docstring of the class property if it exists.
1194 # Get the docstring of the class property if it exists.
1195 path = oname.split('.')
1195 path = oname.split('.')
1196 root = '.'.join(path[:-1])
1196 root = '.'.join(path[:-1])
1197 if info.parent is not None:
1197 if info.parent is not None:
1198 try:
1198 try:
1199 target = getattr(info.parent, '__class__')
1199 target = getattr(info.parent, '__class__')
1200 # The object belongs to a class instance.
1200 # The object belongs to a class instance.
1201 try:
1201 try:
1202 target = getattr(target, path[-1])
1202 target = getattr(target, path[-1])
1203 # The class defines the object.
1203 # The class defines the object.
1204 if isinstance(target, property):
1204 if isinstance(target, property):
1205 oname = root + '.__class__.' + path[-1]
1205 oname = root + '.__class__.' + path[-1]
1206 info = Struct(self._ofind(oname))
1206 info = Struct(self._ofind(oname))
1207 except AttributeError: pass
1207 except AttributeError: pass
1208 except AttributeError: pass
1208 except AttributeError: pass
1209
1209
1210 # We return either the new info or the unmodified input if the object
1210 # We return either the new info or the unmodified input if the object
1211 # hadn't been found
1211 # hadn't been found
1212 return info
1212 return info
1213
1213
1214 def _object_find(self, oname, namespaces=None):
1214 def _object_find(self, oname, namespaces=None):
1215 """Find an object and return a struct with info about it."""
1215 """Find an object and return a struct with info about it."""
1216 inf = Struct(self._ofind(oname, namespaces))
1216 inf = Struct(self._ofind(oname, namespaces))
1217 return Struct(self._ofind_property(oname, inf))
1217 return Struct(self._ofind_property(oname, inf))
1218
1218
1219 def _inspect(self, meth, oname, namespaces=None, **kw):
1219 def _inspect(self, meth, oname, namespaces=None, **kw):
1220 """Generic interface to the inspector system.
1220 """Generic interface to the inspector system.
1221
1221
1222 This function is meant to be called by pdef, pdoc & friends."""
1222 This function is meant to be called by pdef, pdoc & friends."""
1223 info = self._object_find(oname)
1223 info = self._object_find(oname)
1224 if info.found:
1224 if info.found:
1225 pmethod = getattr(self.inspector, meth)
1225 pmethod = getattr(self.inspector, meth)
1226 formatter = format_screen if info.ismagic else None
1226 formatter = format_screen if info.ismagic else None
1227 if meth == 'pdoc':
1227 if meth == 'pdoc':
1228 pmethod(info.obj, oname, formatter)
1228 pmethod(info.obj, oname, formatter)
1229 elif meth == 'pinfo':
1229 elif meth == 'pinfo':
1230 pmethod(info.obj, oname, formatter, info, **kw)
1230 pmethod(info.obj, oname, formatter, info, **kw)
1231 else:
1231 else:
1232 pmethod(info.obj, oname)
1232 pmethod(info.obj, oname)
1233 else:
1233 else:
1234 print 'Object `%s` not found.' % oname
1234 print 'Object `%s` not found.' % oname
1235 return 'not found' # so callers can take other action
1235 return 'not found' # so callers can take other action
1236
1236
1237 def object_inspect(self, oname):
1237 def object_inspect(self, oname):
1238 info = self._object_find(oname)
1238 info = self._object_find(oname)
1239 if info.found:
1239 if info.found:
1240 return self.inspector.info(info.obj, oname, info=info)
1240 return self.inspector.info(info.obj, oname, info=info)
1241 else:
1241 else:
1242 return oinspect.object_info(name=oname, found=False)
1242 return oinspect.object_info(name=oname, found=False)
1243
1243
1244 #-------------------------------------------------------------------------
1244 #-------------------------------------------------------------------------
1245 # Things related to history management
1245 # Things related to history management
1246 #-------------------------------------------------------------------------
1246 #-------------------------------------------------------------------------
1247
1247
1248 def init_history(self):
1248 def init_history(self):
1249 """Sets up the command history, and starts regular autosaves."""
1249 """Sets up the command history, and starts regular autosaves."""
1250 self.history_manager = HistoryManager(shell=self, config=self.config)
1250 self.history_manager = HistoryManager(shell=self, config=self.config)
1251
1251
1252 def history_saving_wrapper(self, func):
1252 def history_saving_wrapper(self, func):
1253 """ Wrap func for readline history saving
1253 """ Wrap func for readline history saving
1254
1254
1255 Convert func into callable that saves & restores
1255 Convert func into callable that saves & restores
1256 history around the call """
1256 history around the call """
1257
1257
1258 if self.has_readline:
1258 if self.has_readline:
1259 from IPython.utils import rlineimpl as readline
1259 from IPython.utils import rlineimpl as readline
1260 else:
1260 else:
1261 return func
1261 return func
1262
1262
1263 def wrapper():
1263 def wrapper():
1264 self.save_history()
1264 self.save_history()
1265 try:
1265 try:
1266 func()
1266 func()
1267 finally:
1267 finally:
1268 self.reload_history()
1268 self.reload_history()
1269 return wrapper
1269 return wrapper
1270
1270
1271
1271
1272 #-------------------------------------------------------------------------
1272 #-------------------------------------------------------------------------
1273 # Things related to exception handling and tracebacks (not debugging)
1273 # Things related to exception handling and tracebacks (not debugging)
1274 #-------------------------------------------------------------------------
1274 #-------------------------------------------------------------------------
1275
1275
1276 def init_traceback_handlers(self, custom_exceptions):
1276 def init_traceback_handlers(self, custom_exceptions):
1277 # Syntax error handler.
1277 # Syntax error handler.
1278 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1278 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1279
1279
1280 # The interactive one is initialized with an offset, meaning we always
1280 # The interactive one is initialized with an offset, meaning we always
1281 # want to remove the topmost item in the traceback, which is our own
1281 # want to remove the topmost item in the traceback, which is our own
1282 # internal code. Valid modes: ['Plain','Context','Verbose']
1282 # internal code. Valid modes: ['Plain','Context','Verbose']
1283 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1283 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1284 color_scheme='NoColor',
1284 color_scheme='NoColor',
1285 tb_offset = 1,
1285 tb_offset = 1,
1286 check_cache=self.compile.check_cache)
1286 check_cache=self.compile.check_cache)
1287
1287
1288 # The instance will store a pointer to the system-wide exception hook,
1288 # The instance will store a pointer to the system-wide exception hook,
1289 # so that runtime code (such as magics) can access it. This is because
1289 # so that runtime code (such as magics) can access it. This is because
1290 # during the read-eval loop, it may get temporarily overwritten.
1290 # during the read-eval loop, it may get temporarily overwritten.
1291 self.sys_excepthook = sys.excepthook
1291 self.sys_excepthook = sys.excepthook
1292
1292
1293 # and add any custom exception handlers the user may have specified
1293 # and add any custom exception handlers the user may have specified
1294 self.set_custom_exc(*custom_exceptions)
1294 self.set_custom_exc(*custom_exceptions)
1295
1295
1296 # Set the exception mode
1296 # Set the exception mode
1297 self.InteractiveTB.set_mode(mode=self.xmode)
1297 self.InteractiveTB.set_mode(mode=self.xmode)
1298
1298
1299 def set_custom_exc(self, exc_tuple, handler):
1299 def set_custom_exc(self, exc_tuple, handler):
1300 """set_custom_exc(exc_tuple,handler)
1300 """set_custom_exc(exc_tuple,handler)
1301
1301
1302 Set a custom exception handler, which will be called if any of the
1302 Set a custom exception handler, which will be called if any of the
1303 exceptions in exc_tuple occur in the mainloop (specifically, in the
1303 exceptions in exc_tuple occur in the mainloop (specifically, in the
1304 run_code() method.
1304 run_code() method.
1305
1305
1306 Inputs:
1306 Inputs:
1307
1307
1308 - exc_tuple: a *tuple* of valid exceptions to call the defined
1308 - exc_tuple: a *tuple* of valid exceptions to call the defined
1309 handler for. It is very important that you use a tuple, and NOT A
1309 handler for. It is very important that you use a tuple, and NOT A
1310 LIST here, because of the way Python's except statement works. If
1310 LIST here, because of the way Python's except statement works. If
1311 you only want to trap a single exception, use a singleton tuple:
1311 you only want to trap a single exception, use a singleton tuple:
1312
1312
1313 exc_tuple == (MyCustomException,)
1313 exc_tuple == (MyCustomException,)
1314
1314
1315 - handler: this must be defined as a function with the following
1315 - handler: this must be defined as a function with the following
1316 basic interface::
1316 basic interface::
1317
1317
1318 def my_handler(self, etype, value, tb, tb_offset=None)
1318 def my_handler(self, etype, value, tb, tb_offset=None)
1319 ...
1319 ...
1320 # The return value must be
1320 # The return value must be
1321 return structured_traceback
1321 return structured_traceback
1322
1322
1323 This will be made into an instance method (via types.MethodType)
1323 This will be made into an instance method (via types.MethodType)
1324 of IPython itself, and it will be called if any of the exceptions
1324 of IPython itself, and it will be called if any of the exceptions
1325 listed in the exc_tuple are caught. If the handler is None, an
1325 listed in the exc_tuple are caught. If the handler is None, an
1326 internal basic one is used, which just prints basic info.
1326 internal basic one is used, which just prints basic info.
1327
1327
1328 WARNING: by putting in your own exception handler into IPython's main
1328 WARNING: by putting in your own exception handler into IPython's main
1329 execution loop, you run a very good chance of nasty crashes. This
1329 execution loop, you run a very good chance of nasty crashes. This
1330 facility should only be used if you really know what you are doing."""
1330 facility should only be used if you really know what you are doing."""
1331
1331
1332 assert type(exc_tuple)==type(()) , \
1332 assert type(exc_tuple)==type(()) , \
1333 "The custom exceptions must be given AS A TUPLE."
1333 "The custom exceptions must be given AS A TUPLE."
1334
1334
1335 def dummy_handler(self,etype,value,tb):
1335 def dummy_handler(self,etype,value,tb):
1336 print '*** Simple custom exception handler ***'
1336 print '*** Simple custom exception handler ***'
1337 print 'Exception type :',etype
1337 print 'Exception type :',etype
1338 print 'Exception value:',value
1338 print 'Exception value:',value
1339 print 'Traceback :',tb
1339 print 'Traceback :',tb
1340 print 'Source code :','\n'.join(self.buffer)
1340 print 'Source code :','\n'.join(self.buffer)
1341
1341
1342 if handler is None: handler = dummy_handler
1342 if handler is None: handler = dummy_handler
1343
1343
1344 self.CustomTB = types.MethodType(handler,self)
1344 self.CustomTB = types.MethodType(handler,self)
1345 self.custom_exceptions = exc_tuple
1345 self.custom_exceptions = exc_tuple
1346
1346
1347 def excepthook(self, etype, value, tb):
1347 def excepthook(self, etype, value, tb):
1348 """One more defense for GUI apps that call sys.excepthook.
1348 """One more defense for GUI apps that call sys.excepthook.
1349
1349
1350 GUI frameworks like wxPython trap exceptions and call
1350 GUI frameworks like wxPython trap exceptions and call
1351 sys.excepthook themselves. I guess this is a feature that
1351 sys.excepthook themselves. I guess this is a feature that
1352 enables them to keep running after exceptions that would
1352 enables them to keep running after exceptions that would
1353 otherwise kill their mainloop. This is a bother for IPython
1353 otherwise kill their mainloop. This is a bother for IPython
1354 which excepts to catch all of the program exceptions with a try:
1354 which excepts to catch all of the program exceptions with a try:
1355 except: statement.
1355 except: statement.
1356
1356
1357 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1357 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1358 any app directly invokes sys.excepthook, it will look to the user like
1358 any app directly invokes sys.excepthook, it will look to the user like
1359 IPython crashed. In order to work around this, we can disable the
1359 IPython crashed. In order to work around this, we can disable the
1360 CrashHandler and replace it with this excepthook instead, which prints a
1360 CrashHandler and replace it with this excepthook instead, which prints a
1361 regular traceback using our InteractiveTB. In this fashion, apps which
1361 regular traceback using our InteractiveTB. In this fashion, apps which
1362 call sys.excepthook will generate a regular-looking exception from
1362 call sys.excepthook will generate a regular-looking exception from
1363 IPython, and the CrashHandler will only be triggered by real IPython
1363 IPython, and the CrashHandler will only be triggered by real IPython
1364 crashes.
1364 crashes.
1365
1365
1366 This hook should be used sparingly, only in places which are not likely
1366 This hook should be used sparingly, only in places which are not likely
1367 to be true IPython errors.
1367 to be true IPython errors.
1368 """
1368 """
1369 self.showtraceback((etype,value,tb),tb_offset=0)
1369 self.showtraceback((etype,value,tb),tb_offset=0)
1370
1370
1371 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1371 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1372 exception_only=False):
1372 exception_only=False):
1373 """Display the exception that just occurred.
1373 """Display the exception that just occurred.
1374
1374
1375 If nothing is known about the exception, this is the method which
1375 If nothing is known about the exception, this is the method which
1376 should be used throughout the code for presenting user tracebacks,
1376 should be used throughout the code for presenting user tracebacks,
1377 rather than directly invoking the InteractiveTB object.
1377 rather than directly invoking the InteractiveTB object.
1378
1378
1379 A specific showsyntaxerror() also exists, but this method can take
1379 A specific showsyntaxerror() also exists, but this method can take
1380 care of calling it if needed, so unless you are explicitly catching a
1380 care of calling it if needed, so unless you are explicitly catching a
1381 SyntaxError exception, don't try to analyze the stack manually and
1381 SyntaxError exception, don't try to analyze the stack manually and
1382 simply call this method."""
1382 simply call this method."""
1383
1383
1384 try:
1384 try:
1385 if exc_tuple is None:
1385 if exc_tuple is None:
1386 etype, value, tb = sys.exc_info()
1386 etype, value, tb = sys.exc_info()
1387 else:
1387 else:
1388 etype, value, tb = exc_tuple
1388 etype, value, tb = exc_tuple
1389
1389
1390 if etype is None:
1390 if etype is None:
1391 if hasattr(sys, 'last_type'):
1391 if hasattr(sys, 'last_type'):
1392 etype, value, tb = sys.last_type, sys.last_value, \
1392 etype, value, tb = sys.last_type, sys.last_value, \
1393 sys.last_traceback
1393 sys.last_traceback
1394 else:
1394 else:
1395 self.write_err('No traceback available to show.\n')
1395 self.write_err('No traceback available to show.\n')
1396 return
1396 return
1397
1397
1398 if etype is SyntaxError:
1398 if etype is SyntaxError:
1399 # Though this won't be called by syntax errors in the input
1399 # Though this won't be called by syntax errors in the input
1400 # line, there may be SyntaxError cases whith imported code.
1400 # line, there may be SyntaxError cases whith imported code.
1401 self.showsyntaxerror(filename)
1401 self.showsyntaxerror(filename)
1402 elif etype is UsageError:
1402 elif etype is UsageError:
1403 print "UsageError:", value
1403 print "UsageError:", value
1404 else:
1404 else:
1405 # WARNING: these variables are somewhat deprecated and not
1405 # WARNING: these variables are somewhat deprecated and not
1406 # necessarily safe to use in a threaded environment, but tools
1406 # necessarily safe to use in a threaded environment, but tools
1407 # like pdb depend on their existence, so let's set them. If we
1407 # like pdb depend on their existence, so let's set them. If we
1408 # find problems in the field, we'll need to revisit their use.
1408 # find problems in the field, we'll need to revisit their use.
1409 sys.last_type = etype
1409 sys.last_type = etype
1410 sys.last_value = value
1410 sys.last_value = value
1411 sys.last_traceback = tb
1411 sys.last_traceback = tb
1412
1412
1413 if etype in self.custom_exceptions:
1413 if etype in self.custom_exceptions:
1414 # FIXME: Old custom traceback objects may just return a
1414 # FIXME: Old custom traceback objects may just return a
1415 # string, in that case we just put it into a list
1415 # string, in that case we just put it into a list
1416 stb = self.CustomTB(etype, value, tb, tb_offset)
1416 stb = self.CustomTB(etype, value, tb, tb_offset)
1417 if isinstance(ctb, basestring):
1417 if isinstance(ctb, basestring):
1418 stb = [stb]
1418 stb = [stb]
1419 else:
1419 else:
1420 if exception_only:
1420 if exception_only:
1421 stb = ['An exception has occurred, use %tb to see '
1421 stb = ['An exception has occurred, use %tb to see '
1422 'the full traceback.\n']
1422 'the full traceback.\n']
1423 stb.extend(self.InteractiveTB.get_exception_only(etype,
1423 stb.extend(self.InteractiveTB.get_exception_only(etype,
1424 value))
1424 value))
1425 else:
1425 else:
1426 stb = self.InteractiveTB.structured_traceback(etype,
1426 stb = self.InteractiveTB.structured_traceback(etype,
1427 value, tb, tb_offset=tb_offset)
1427 value, tb, tb_offset=tb_offset)
1428 # FIXME: the pdb calling should be done by us, not by
1428 # FIXME: the pdb calling should be done by us, not by
1429 # the code computing the traceback.
1429 # the code computing the traceback.
1430 if self.InteractiveTB.call_pdb:
1430 if self.InteractiveTB.call_pdb:
1431 # pdb mucks up readline, fix it back
1431 # pdb mucks up readline, fix it back
1432 self.set_readline_completer()
1432 self.set_readline_completer()
1433
1433
1434 # Actually show the traceback
1434 # Actually show the traceback
1435 self._showtraceback(etype, value, stb)
1435 self._showtraceback(etype, value, stb)
1436
1436
1437 except KeyboardInterrupt:
1437 except KeyboardInterrupt:
1438 self.write_err("\nKeyboardInterrupt\n")
1438 self.write_err("\nKeyboardInterrupt\n")
1439
1439
1440 def _showtraceback(self, etype, evalue, stb):
1440 def _showtraceback(self, etype, evalue, stb):
1441 """Actually show a traceback.
1441 """Actually show a traceback.
1442
1442
1443 Subclasses may override this method to put the traceback on a different
1443 Subclasses may override this method to put the traceback on a different
1444 place, like a side channel.
1444 place, like a side channel.
1445 """
1445 """
1446 print >> io.Term.cout, self.InteractiveTB.stb2text(stb)
1446 print >> io.Term.cout, self.InteractiveTB.stb2text(stb)
1447
1447
1448 def showsyntaxerror(self, filename=None):
1448 def showsyntaxerror(self, filename=None):
1449 """Display the syntax error that just occurred.
1449 """Display the syntax error that just occurred.
1450
1450
1451 This doesn't display a stack trace because there isn't one.
1451 This doesn't display a stack trace because there isn't one.
1452
1452
1453 If a filename is given, it is stuffed in the exception instead
1453 If a filename is given, it is stuffed in the exception instead
1454 of what was there before (because Python's parser always uses
1454 of what was there before (because Python's parser always uses
1455 "<string>" when reading from a string).
1455 "<string>" when reading from a string).
1456 """
1456 """
1457 etype, value, last_traceback = sys.exc_info()
1457 etype, value, last_traceback = sys.exc_info()
1458
1458
1459 # See note about these variables in showtraceback() above
1459 # See note about these variables in showtraceback() above
1460 sys.last_type = etype
1460 sys.last_type = etype
1461 sys.last_value = value
1461 sys.last_value = value
1462 sys.last_traceback = last_traceback
1462 sys.last_traceback = last_traceback
1463
1463
1464 if filename and etype is SyntaxError:
1464 if filename and etype is SyntaxError:
1465 # Work hard to stuff the correct filename in the exception
1465 # Work hard to stuff the correct filename in the exception
1466 try:
1466 try:
1467 msg, (dummy_filename, lineno, offset, line) = value
1467 msg, (dummy_filename, lineno, offset, line) = value
1468 except:
1468 except:
1469 # Not the format we expect; leave it alone
1469 # Not the format we expect; leave it alone
1470 pass
1470 pass
1471 else:
1471 else:
1472 # Stuff in the right filename
1472 # Stuff in the right filename
1473 try:
1473 try:
1474 # Assume SyntaxError is a class exception
1474 # Assume SyntaxError is a class exception
1475 value = SyntaxError(msg, (filename, lineno, offset, line))
1475 value = SyntaxError(msg, (filename, lineno, offset, line))
1476 except:
1476 except:
1477 # If that failed, assume SyntaxError is a string
1477 # If that failed, assume SyntaxError is a string
1478 value = msg, (filename, lineno, offset, line)
1478 value = msg, (filename, lineno, offset, line)
1479 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1479 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1480 self._showtraceback(etype, value, stb)
1480 self._showtraceback(etype, value, stb)
1481
1481
1482 #-------------------------------------------------------------------------
1482 #-------------------------------------------------------------------------
1483 # Things related to readline
1483 # Things related to readline
1484 #-------------------------------------------------------------------------
1484 #-------------------------------------------------------------------------
1485
1485
1486 def init_readline(self):
1486 def init_readline(self):
1487 """Command history completion/saving/reloading."""
1487 """Command history completion/saving/reloading."""
1488
1488
1489 if self.readline_use:
1489 if self.readline_use:
1490 import IPython.utils.rlineimpl as readline
1490 import IPython.utils.rlineimpl as readline
1491
1491
1492 self.rl_next_input = None
1492 self.rl_next_input = None
1493 self.rl_do_indent = False
1493 self.rl_do_indent = False
1494
1494
1495 if not self.readline_use or not readline.have_readline:
1495 if not self.readline_use or not readline.have_readline:
1496 self.has_readline = False
1496 self.has_readline = False
1497 self.readline = None
1497 self.readline = None
1498 # Set a number of methods that depend on readline to be no-op
1498 # Set a number of methods that depend on readline to be no-op
1499 self.set_readline_completer = no_op
1499 self.set_readline_completer = no_op
1500 self.set_custom_completer = no_op
1500 self.set_custom_completer = no_op
1501 self.set_completer_frame = no_op
1501 self.set_completer_frame = no_op
1502 warn('Readline services not available or not loaded.')
1502 warn('Readline services not available or not loaded.')
1503 else:
1503 else:
1504 self.has_readline = True
1504 self.has_readline = True
1505 self.readline = readline
1505 self.readline = readline
1506 sys.modules['readline'] = readline
1506 sys.modules['readline'] = readline
1507
1507
1508 # Platform-specific configuration
1508 # Platform-specific configuration
1509 if os.name == 'nt':
1509 if os.name == 'nt':
1510 # FIXME - check with Frederick to see if we can harmonize
1510 # FIXME - check with Frederick to see if we can harmonize
1511 # naming conventions with pyreadline to avoid this
1511 # naming conventions with pyreadline to avoid this
1512 # platform-dependent check
1512 # platform-dependent check
1513 self.readline_startup_hook = readline.set_pre_input_hook
1513 self.readline_startup_hook = readline.set_pre_input_hook
1514 else:
1514 else:
1515 self.readline_startup_hook = readline.set_startup_hook
1515 self.readline_startup_hook = readline.set_startup_hook
1516
1516
1517 # Load user's initrc file (readline config)
1517 # Load user's initrc file (readline config)
1518 # Or if libedit is used, load editrc.
1518 # Or if libedit is used, load editrc.
1519 inputrc_name = os.environ.get('INPUTRC')
1519 inputrc_name = os.environ.get('INPUTRC')
1520 if inputrc_name is None:
1520 if inputrc_name is None:
1521 home_dir = get_home_dir()
1521 home_dir = get_home_dir()
1522 if home_dir is not None:
1522 if home_dir is not None:
1523 inputrc_name = '.inputrc'
1523 inputrc_name = '.inputrc'
1524 if readline.uses_libedit:
1524 if readline.uses_libedit:
1525 inputrc_name = '.editrc'
1525 inputrc_name = '.editrc'
1526 inputrc_name = os.path.join(home_dir, inputrc_name)
1526 inputrc_name = os.path.join(home_dir, inputrc_name)
1527 if os.path.isfile(inputrc_name):
1527 if os.path.isfile(inputrc_name):
1528 try:
1528 try:
1529 readline.read_init_file(inputrc_name)
1529 readline.read_init_file(inputrc_name)
1530 except:
1530 except:
1531 warn('Problems reading readline initialization file <%s>'
1531 warn('Problems reading readline initialization file <%s>'
1532 % inputrc_name)
1532 % inputrc_name)
1533
1533
1534 # Configure readline according to user's prefs
1534 # Configure readline according to user's prefs
1535 # This is only done if GNU readline is being used. If libedit
1535 # This is only done if GNU readline is being used. If libedit
1536 # is being used (as on Leopard) the readline config is
1536 # is being used (as on Leopard) the readline config is
1537 # not run as the syntax for libedit is different.
1537 # not run as the syntax for libedit is different.
1538 if not readline.uses_libedit:
1538 if not readline.uses_libedit:
1539 for rlcommand in self.readline_parse_and_bind:
1539 for rlcommand in self.readline_parse_and_bind:
1540 #print "loading rl:",rlcommand # dbg
1540 #print "loading rl:",rlcommand # dbg
1541 readline.parse_and_bind(rlcommand)
1541 readline.parse_and_bind(rlcommand)
1542
1542
1543 # Remove some chars from the delimiters list. If we encounter
1543 # Remove some chars from the delimiters list. If we encounter
1544 # unicode chars, discard them.
1544 # unicode chars, discard them.
1545 delims = readline.get_completer_delims().encode("ascii", "ignore")
1545 delims = readline.get_completer_delims().encode("ascii", "ignore")
1546 delims = delims.translate(None, self.readline_remove_delims)
1546 delims = delims.translate(None, self.readline_remove_delims)
1547 delims = delims.replace(ESC_MAGIC, '')
1547 delims = delims.replace(ESC_MAGIC, '')
1548 readline.set_completer_delims(delims)
1548 readline.set_completer_delims(delims)
1549 # otherwise we end up with a monster history after a while:
1549 # otherwise we end up with a monster history after a while:
1550 readline.set_history_length(self.history_length)
1550 readline.set_history_length(self.history_length)
1551
1551
1552 # Load the last 1000 lines from history
1552 # Load the last 1000 lines from history
1553 for _, _, cell in self.history_manager.get_hist_tail(1000,
1553 for _, _, cell in self.history_manager.get_tail(1000,
1554 include_latest=True):
1554 include_latest=True):
1555 if cell.strip(): # Ignore blank lines
1555 if cell.strip(): # Ignore blank lines
1556 for line in cell.splitlines():
1556 for line in cell.splitlines():
1557 readline.add_history(line)
1557 readline.add_history(line)
1558
1558
1559 # Configure auto-indent for all platforms
1559 # Configure auto-indent for all platforms
1560 self.set_autoindent(self.autoindent)
1560 self.set_autoindent(self.autoindent)
1561
1561
1562 def set_next_input(self, s):
1562 def set_next_input(self, s):
1563 """ Sets the 'default' input string for the next command line.
1563 """ Sets the 'default' input string for the next command line.
1564
1564
1565 Requires readline.
1565 Requires readline.
1566
1566
1567 Example:
1567 Example:
1568
1568
1569 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1569 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1570 [D:\ipython]|2> Hello Word_ # cursor is here
1570 [D:\ipython]|2> Hello Word_ # cursor is here
1571 """
1571 """
1572
1572
1573 self.rl_next_input = s
1573 self.rl_next_input = s
1574
1574
1575 # Maybe move this to the terminal subclass?
1575 # Maybe move this to the terminal subclass?
1576 def pre_readline(self):
1576 def pre_readline(self):
1577 """readline hook to be used at the start of each line.
1577 """readline hook to be used at the start of each line.
1578
1578
1579 Currently it handles auto-indent only."""
1579 Currently it handles auto-indent only."""
1580
1580
1581 if self.rl_do_indent:
1581 if self.rl_do_indent:
1582 self.readline.insert_text(self._indent_current_str())
1582 self.readline.insert_text(self._indent_current_str())
1583 if self.rl_next_input is not None:
1583 if self.rl_next_input is not None:
1584 self.readline.insert_text(self.rl_next_input)
1584 self.readline.insert_text(self.rl_next_input)
1585 self.rl_next_input = None
1585 self.rl_next_input = None
1586
1586
1587 def _indent_current_str(self):
1587 def _indent_current_str(self):
1588 """return the current level of indentation as a string"""
1588 """return the current level of indentation as a string"""
1589 return self.input_splitter.indent_spaces * ' '
1589 return self.input_splitter.indent_spaces * ' '
1590
1590
1591 #-------------------------------------------------------------------------
1591 #-------------------------------------------------------------------------
1592 # Things related to text completion
1592 # Things related to text completion
1593 #-------------------------------------------------------------------------
1593 #-------------------------------------------------------------------------
1594
1594
1595 def init_completer(self):
1595 def init_completer(self):
1596 """Initialize the completion machinery.
1596 """Initialize the completion machinery.
1597
1597
1598 This creates completion machinery that can be used by client code,
1598 This creates completion machinery that can be used by client code,
1599 either interactively in-process (typically triggered by the readline
1599 either interactively in-process (typically triggered by the readline
1600 library), programatically (such as in test suites) or out-of-prcess
1600 library), programatically (such as in test suites) or out-of-prcess
1601 (typically over the network by remote frontends).
1601 (typically over the network by remote frontends).
1602 """
1602 """
1603 from IPython.core.completer import IPCompleter
1603 from IPython.core.completer import IPCompleter
1604 from IPython.core.completerlib import (module_completer,
1604 from IPython.core.completerlib import (module_completer,
1605 magic_run_completer, cd_completer)
1605 magic_run_completer, cd_completer)
1606
1606
1607 self.Completer = IPCompleter(self,
1607 self.Completer = IPCompleter(self,
1608 self.user_ns,
1608 self.user_ns,
1609 self.user_global_ns,
1609 self.user_global_ns,
1610 self.readline_omit__names,
1610 self.readline_omit__names,
1611 self.alias_manager.alias_table,
1611 self.alias_manager.alias_table,
1612 self.has_readline)
1612 self.has_readline)
1613
1613
1614 # Add custom completers to the basic ones built into IPCompleter
1614 # Add custom completers to the basic ones built into IPCompleter
1615 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1615 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1616 self.strdispatchers['complete_command'] = sdisp
1616 self.strdispatchers['complete_command'] = sdisp
1617 self.Completer.custom_completers = sdisp
1617 self.Completer.custom_completers = sdisp
1618
1618
1619 self.set_hook('complete_command', module_completer, str_key = 'import')
1619 self.set_hook('complete_command', module_completer, str_key = 'import')
1620 self.set_hook('complete_command', module_completer, str_key = 'from')
1620 self.set_hook('complete_command', module_completer, str_key = 'from')
1621 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1621 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1622 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1622 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1623
1623
1624 # Only configure readline if we truly are using readline. IPython can
1624 # Only configure readline if we truly are using readline. IPython can
1625 # do tab-completion over the network, in GUIs, etc, where readline
1625 # do tab-completion over the network, in GUIs, etc, where readline
1626 # itself may be absent
1626 # itself may be absent
1627 if self.has_readline:
1627 if self.has_readline:
1628 self.set_readline_completer()
1628 self.set_readline_completer()
1629
1629
1630 def complete(self, text, line=None, cursor_pos=None):
1630 def complete(self, text, line=None, cursor_pos=None):
1631 """Return the completed text and a list of completions.
1631 """Return the completed text and a list of completions.
1632
1632
1633 Parameters
1633 Parameters
1634 ----------
1634 ----------
1635
1635
1636 text : string
1636 text : string
1637 A string of text to be completed on. It can be given as empty and
1637 A string of text to be completed on. It can be given as empty and
1638 instead a line/position pair are given. In this case, the
1638 instead a line/position pair are given. In this case, the
1639 completer itself will split the line like readline does.
1639 completer itself will split the line like readline does.
1640
1640
1641 line : string, optional
1641 line : string, optional
1642 The complete line that text is part of.
1642 The complete line that text is part of.
1643
1643
1644 cursor_pos : int, optional
1644 cursor_pos : int, optional
1645 The position of the cursor on the input line.
1645 The position of the cursor on the input line.
1646
1646
1647 Returns
1647 Returns
1648 -------
1648 -------
1649 text : string
1649 text : string
1650 The actual text that was completed.
1650 The actual text that was completed.
1651
1651
1652 matches : list
1652 matches : list
1653 A sorted list with all possible completions.
1653 A sorted list with all possible completions.
1654
1654
1655 The optional arguments allow the completion to take more context into
1655 The optional arguments allow the completion to take more context into
1656 account, and are part of the low-level completion API.
1656 account, and are part of the low-level completion API.
1657
1657
1658 This is a wrapper around the completion mechanism, similar to what
1658 This is a wrapper around the completion mechanism, similar to what
1659 readline does at the command line when the TAB key is hit. By
1659 readline does at the command line when the TAB key is hit. By
1660 exposing it as a method, it can be used by other non-readline
1660 exposing it as a method, it can be used by other non-readline
1661 environments (such as GUIs) for text completion.
1661 environments (such as GUIs) for text completion.
1662
1662
1663 Simple usage example:
1663 Simple usage example:
1664
1664
1665 In [1]: x = 'hello'
1665 In [1]: x = 'hello'
1666
1666
1667 In [2]: _ip.complete('x.l')
1667 In [2]: _ip.complete('x.l')
1668 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1668 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1669 """
1669 """
1670
1670
1671 # Inject names into __builtin__ so we can complete on the added names.
1671 # Inject names into __builtin__ so we can complete on the added names.
1672 with self.builtin_trap:
1672 with self.builtin_trap:
1673 return self.Completer.complete(text, line, cursor_pos)
1673 return self.Completer.complete(text, line, cursor_pos)
1674
1674
1675 def set_custom_completer(self, completer, pos=0):
1675 def set_custom_completer(self, completer, pos=0):
1676 """Adds a new custom completer function.
1676 """Adds a new custom completer function.
1677
1677
1678 The position argument (defaults to 0) is the index in the completers
1678 The position argument (defaults to 0) is the index in the completers
1679 list where you want the completer to be inserted."""
1679 list where you want the completer to be inserted."""
1680
1680
1681 newcomp = types.MethodType(completer,self.Completer)
1681 newcomp = types.MethodType(completer,self.Completer)
1682 self.Completer.matchers.insert(pos,newcomp)
1682 self.Completer.matchers.insert(pos,newcomp)
1683
1683
1684 def set_readline_completer(self):
1684 def set_readline_completer(self):
1685 """Reset readline's completer to be our own."""
1685 """Reset readline's completer to be our own."""
1686 self.readline.set_completer(self.Completer.rlcomplete)
1686 self.readline.set_completer(self.Completer.rlcomplete)
1687
1687
1688 def set_completer_frame(self, frame=None):
1688 def set_completer_frame(self, frame=None):
1689 """Set the frame of the completer."""
1689 """Set the frame of the completer."""
1690 if frame:
1690 if frame:
1691 self.Completer.namespace = frame.f_locals
1691 self.Completer.namespace = frame.f_locals
1692 self.Completer.global_namespace = frame.f_globals
1692 self.Completer.global_namespace = frame.f_globals
1693 else:
1693 else:
1694 self.Completer.namespace = self.user_ns
1694 self.Completer.namespace = self.user_ns
1695 self.Completer.global_namespace = self.user_global_ns
1695 self.Completer.global_namespace = self.user_global_ns
1696
1696
1697 #-------------------------------------------------------------------------
1697 #-------------------------------------------------------------------------
1698 # Things related to magics
1698 # Things related to magics
1699 #-------------------------------------------------------------------------
1699 #-------------------------------------------------------------------------
1700
1700
1701 def init_magics(self):
1701 def init_magics(self):
1702 # FIXME: Move the color initialization to the DisplayHook, which
1702 # FIXME: Move the color initialization to the DisplayHook, which
1703 # should be split into a prompt manager and displayhook. We probably
1703 # should be split into a prompt manager and displayhook. We probably
1704 # even need a centralize colors management object.
1704 # even need a centralize colors management object.
1705 self.magic_colors(self.colors)
1705 self.magic_colors(self.colors)
1706 # History was moved to a separate module
1706 # History was moved to a separate module
1707 from . import history
1707 from . import history
1708 history.init_ipython(self)
1708 history.init_ipython(self)
1709
1709
1710 def magic(self,arg_s):
1710 def magic(self,arg_s):
1711 """Call a magic function by name.
1711 """Call a magic function by name.
1712
1712
1713 Input: a string containing the name of the magic function to call and
1713 Input: a string containing the name of the magic function to call and
1714 any additional arguments to be passed to the magic.
1714 any additional arguments to be passed to the magic.
1715
1715
1716 magic('name -opt foo bar') is equivalent to typing at the ipython
1716 magic('name -opt foo bar') is equivalent to typing at the ipython
1717 prompt:
1717 prompt:
1718
1718
1719 In[1]: %name -opt foo bar
1719 In[1]: %name -opt foo bar
1720
1720
1721 To call a magic without arguments, simply use magic('name').
1721 To call a magic without arguments, simply use magic('name').
1722
1722
1723 This provides a proper Python function to call IPython's magics in any
1723 This provides a proper Python function to call IPython's magics in any
1724 valid Python code you can type at the interpreter, including loops and
1724 valid Python code you can type at the interpreter, including loops and
1725 compound statements.
1725 compound statements.
1726 """
1726 """
1727 args = arg_s.split(' ',1)
1727 args = arg_s.split(' ',1)
1728 magic_name = args[0]
1728 magic_name = args[0]
1729 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1729 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1730
1730
1731 try:
1731 try:
1732 magic_args = args[1]
1732 magic_args = args[1]
1733 except IndexError:
1733 except IndexError:
1734 magic_args = ''
1734 magic_args = ''
1735 fn = getattr(self,'magic_'+magic_name,None)
1735 fn = getattr(self,'magic_'+magic_name,None)
1736 if fn is None:
1736 if fn is None:
1737 error("Magic function `%s` not found." % magic_name)
1737 error("Magic function `%s` not found." % magic_name)
1738 else:
1738 else:
1739 magic_args = self.var_expand(magic_args,1)
1739 magic_args = self.var_expand(magic_args,1)
1740 with nested(self.builtin_trap,):
1740 with nested(self.builtin_trap,):
1741 result = fn(magic_args)
1741 result = fn(magic_args)
1742 return result
1742 return result
1743
1743
1744 def define_magic(self, magicname, func):
1744 def define_magic(self, magicname, func):
1745 """Expose own function as magic function for ipython
1745 """Expose own function as magic function for ipython
1746
1746
1747 def foo_impl(self,parameter_s=''):
1747 def foo_impl(self,parameter_s=''):
1748 'My very own magic!. (Use docstrings, IPython reads them).'
1748 'My very own magic!. (Use docstrings, IPython reads them).'
1749 print 'Magic function. Passed parameter is between < >:'
1749 print 'Magic function. Passed parameter is between < >:'
1750 print '<%s>' % parameter_s
1750 print '<%s>' % parameter_s
1751 print 'The self object is:',self
1751 print 'The self object is:',self
1752
1752
1753 self.define_magic('foo',foo_impl)
1753 self.define_magic('foo',foo_impl)
1754 """
1754 """
1755
1755
1756 import new
1756 import new
1757 im = types.MethodType(func,self)
1757 im = types.MethodType(func,self)
1758 old = getattr(self, "magic_" + magicname, None)
1758 old = getattr(self, "magic_" + magicname, None)
1759 setattr(self, "magic_" + magicname, im)
1759 setattr(self, "magic_" + magicname, im)
1760 return old
1760 return old
1761
1761
1762 #-------------------------------------------------------------------------
1762 #-------------------------------------------------------------------------
1763 # Things related to macros
1763 # Things related to macros
1764 #-------------------------------------------------------------------------
1764 #-------------------------------------------------------------------------
1765
1765
1766 def define_macro(self, name, themacro):
1766 def define_macro(self, name, themacro):
1767 """Define a new macro
1767 """Define a new macro
1768
1768
1769 Parameters
1769 Parameters
1770 ----------
1770 ----------
1771 name : str
1771 name : str
1772 The name of the macro.
1772 The name of the macro.
1773 themacro : str or Macro
1773 themacro : str or Macro
1774 The action to do upon invoking the macro. If a string, a new
1774 The action to do upon invoking the macro. If a string, a new
1775 Macro object is created by passing the string to it.
1775 Macro object is created by passing the string to it.
1776 """
1776 """
1777
1777
1778 from IPython.core import macro
1778 from IPython.core import macro
1779
1779
1780 if isinstance(themacro, basestring):
1780 if isinstance(themacro, basestring):
1781 themacro = macro.Macro(themacro)
1781 themacro = macro.Macro(themacro)
1782 if not isinstance(themacro, macro.Macro):
1782 if not isinstance(themacro, macro.Macro):
1783 raise ValueError('A macro must be a string or a Macro instance.')
1783 raise ValueError('A macro must be a string or a Macro instance.')
1784 self.user_ns[name] = themacro
1784 self.user_ns[name] = themacro
1785
1785
1786 #-------------------------------------------------------------------------
1786 #-------------------------------------------------------------------------
1787 # Things related to the running of system commands
1787 # Things related to the running of system commands
1788 #-------------------------------------------------------------------------
1788 #-------------------------------------------------------------------------
1789
1789
1790 def system(self, cmd):
1790 def system(self, cmd):
1791 """Call the given cmd in a subprocess.
1791 """Call the given cmd in a subprocess.
1792
1792
1793 Parameters
1793 Parameters
1794 ----------
1794 ----------
1795 cmd : str
1795 cmd : str
1796 Command to execute (can not end in '&', as bacground processes are
1796 Command to execute (can not end in '&', as bacground processes are
1797 not supported.
1797 not supported.
1798 """
1798 """
1799 # We do not support backgrounding processes because we either use
1799 # We do not support backgrounding processes because we either use
1800 # pexpect or pipes to read from. Users can always just call
1800 # pexpect or pipes to read from. Users can always just call
1801 # os.system() if they really want a background process.
1801 # os.system() if they really want a background process.
1802 if cmd.endswith('&'):
1802 if cmd.endswith('&'):
1803 raise OSError("Background processes not supported.")
1803 raise OSError("Background processes not supported.")
1804
1804
1805 return system(self.var_expand(cmd, depth=2))
1805 return system(self.var_expand(cmd, depth=2))
1806
1806
1807 def getoutput(self, cmd, split=True):
1807 def getoutput(self, cmd, split=True):
1808 """Get output (possibly including stderr) from a subprocess.
1808 """Get output (possibly including stderr) from a subprocess.
1809
1809
1810 Parameters
1810 Parameters
1811 ----------
1811 ----------
1812 cmd : str
1812 cmd : str
1813 Command to execute (can not end in '&', as background processes are
1813 Command to execute (can not end in '&', as background processes are
1814 not supported.
1814 not supported.
1815 split : bool, optional
1815 split : bool, optional
1816
1816
1817 If True, split the output into an IPython SList. Otherwise, an
1817 If True, split the output into an IPython SList. Otherwise, an
1818 IPython LSString is returned. These are objects similar to normal
1818 IPython LSString is returned. These are objects similar to normal
1819 lists and strings, with a few convenience attributes for easier
1819 lists and strings, with a few convenience attributes for easier
1820 manipulation of line-based output. You can use '?' on them for
1820 manipulation of line-based output. You can use '?' on them for
1821 details.
1821 details.
1822 """
1822 """
1823 if cmd.endswith('&'):
1823 if cmd.endswith('&'):
1824 raise OSError("Background processes not supported.")
1824 raise OSError("Background processes not supported.")
1825 out = getoutput(self.var_expand(cmd, depth=2))
1825 out = getoutput(self.var_expand(cmd, depth=2))
1826 if split:
1826 if split:
1827 out = SList(out.splitlines())
1827 out = SList(out.splitlines())
1828 else:
1828 else:
1829 out = LSString(out)
1829 out = LSString(out)
1830 return out
1830 return out
1831
1831
1832 #-------------------------------------------------------------------------
1832 #-------------------------------------------------------------------------
1833 # Things related to aliases
1833 # Things related to aliases
1834 #-------------------------------------------------------------------------
1834 #-------------------------------------------------------------------------
1835
1835
1836 def init_alias(self):
1836 def init_alias(self):
1837 self.alias_manager = AliasManager(shell=self, config=self.config)
1837 self.alias_manager = AliasManager(shell=self, config=self.config)
1838 self.ns_table['alias'] = self.alias_manager.alias_table,
1838 self.ns_table['alias'] = self.alias_manager.alias_table,
1839
1839
1840 #-------------------------------------------------------------------------
1840 #-------------------------------------------------------------------------
1841 # Things related to extensions and plugins
1841 # Things related to extensions and plugins
1842 #-------------------------------------------------------------------------
1842 #-------------------------------------------------------------------------
1843
1843
1844 def init_extension_manager(self):
1844 def init_extension_manager(self):
1845 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1845 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1846
1846
1847 def init_plugin_manager(self):
1847 def init_plugin_manager(self):
1848 self.plugin_manager = PluginManager(config=self.config)
1848 self.plugin_manager = PluginManager(config=self.config)
1849
1849
1850 #-------------------------------------------------------------------------
1850 #-------------------------------------------------------------------------
1851 # Things related to payloads
1851 # Things related to payloads
1852 #-------------------------------------------------------------------------
1852 #-------------------------------------------------------------------------
1853
1853
1854 def init_payload(self):
1854 def init_payload(self):
1855 self.payload_manager = PayloadManager(config=self.config)
1855 self.payload_manager = PayloadManager(config=self.config)
1856
1856
1857 #-------------------------------------------------------------------------
1857 #-------------------------------------------------------------------------
1858 # Things related to the prefilter
1858 # Things related to the prefilter
1859 #-------------------------------------------------------------------------
1859 #-------------------------------------------------------------------------
1860
1860
1861 def init_prefilter(self):
1861 def init_prefilter(self):
1862 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1862 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1863 # Ultimately this will be refactored in the new interpreter code, but
1863 # Ultimately this will be refactored in the new interpreter code, but
1864 # for now, we should expose the main prefilter method (there's legacy
1864 # for now, we should expose the main prefilter method (there's legacy
1865 # code out there that may rely on this).
1865 # code out there that may rely on this).
1866 self.prefilter = self.prefilter_manager.prefilter_lines
1866 self.prefilter = self.prefilter_manager.prefilter_lines
1867
1867
1868 def auto_rewrite_input(self, cmd):
1868 def auto_rewrite_input(self, cmd):
1869 """Print to the screen the rewritten form of the user's command.
1869 """Print to the screen the rewritten form of the user's command.
1870
1870
1871 This shows visual feedback by rewriting input lines that cause
1871 This shows visual feedback by rewriting input lines that cause
1872 automatic calling to kick in, like::
1872 automatic calling to kick in, like::
1873
1873
1874 /f x
1874 /f x
1875
1875
1876 into::
1876 into::
1877
1877
1878 ------> f(x)
1878 ------> f(x)
1879
1879
1880 after the user's input prompt. This helps the user understand that the
1880 after the user's input prompt. This helps the user understand that the
1881 input line was transformed automatically by IPython.
1881 input line was transformed automatically by IPython.
1882 """
1882 """
1883 rw = self.displayhook.prompt1.auto_rewrite() + cmd
1883 rw = self.displayhook.prompt1.auto_rewrite() + cmd
1884
1884
1885 try:
1885 try:
1886 # plain ascii works better w/ pyreadline, on some machines, so
1886 # plain ascii works better w/ pyreadline, on some machines, so
1887 # we use it and only print uncolored rewrite if we have unicode
1887 # we use it and only print uncolored rewrite if we have unicode
1888 rw = str(rw)
1888 rw = str(rw)
1889 print >> IPython.utils.io.Term.cout, rw
1889 print >> IPython.utils.io.Term.cout, rw
1890 except UnicodeEncodeError:
1890 except UnicodeEncodeError:
1891 print "------> " + cmd
1891 print "------> " + cmd
1892
1892
1893 #-------------------------------------------------------------------------
1893 #-------------------------------------------------------------------------
1894 # Things related to extracting values/expressions from kernel and user_ns
1894 # Things related to extracting values/expressions from kernel and user_ns
1895 #-------------------------------------------------------------------------
1895 #-------------------------------------------------------------------------
1896
1896
1897 def _simple_error(self):
1897 def _simple_error(self):
1898 etype, value = sys.exc_info()[:2]
1898 etype, value = sys.exc_info()[:2]
1899 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1899 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1900
1900
1901 def user_variables(self, names):
1901 def user_variables(self, names):
1902 """Get a list of variable names from the user's namespace.
1902 """Get a list of variable names from the user's namespace.
1903
1903
1904 Parameters
1904 Parameters
1905 ----------
1905 ----------
1906 names : list of strings
1906 names : list of strings
1907 A list of names of variables to be read from the user namespace.
1907 A list of names of variables to be read from the user namespace.
1908
1908
1909 Returns
1909 Returns
1910 -------
1910 -------
1911 A dict, keyed by the input names and with the repr() of each value.
1911 A dict, keyed by the input names and with the repr() of each value.
1912 """
1912 """
1913 out = {}
1913 out = {}
1914 user_ns = self.user_ns
1914 user_ns = self.user_ns
1915 for varname in names:
1915 for varname in names:
1916 try:
1916 try:
1917 value = repr(user_ns[varname])
1917 value = repr(user_ns[varname])
1918 except:
1918 except:
1919 value = self._simple_error()
1919 value = self._simple_error()
1920 out[varname] = value
1920 out[varname] = value
1921 return out
1921 return out
1922
1922
1923 def user_expressions(self, expressions):
1923 def user_expressions(self, expressions):
1924 """Evaluate a dict of expressions in the user's namespace.
1924 """Evaluate a dict of expressions in the user's namespace.
1925
1925
1926 Parameters
1926 Parameters
1927 ----------
1927 ----------
1928 expressions : dict
1928 expressions : dict
1929 A dict with string keys and string values. The expression values
1929 A dict with string keys and string values. The expression values
1930 should be valid Python expressions, each of which will be evaluated
1930 should be valid Python expressions, each of which will be evaluated
1931 in the user namespace.
1931 in the user namespace.
1932
1932
1933 Returns
1933 Returns
1934 -------
1934 -------
1935 A dict, keyed like the input expressions dict, with the repr() of each
1935 A dict, keyed like the input expressions dict, with the repr() of each
1936 value.
1936 value.
1937 """
1937 """
1938 out = {}
1938 out = {}
1939 user_ns = self.user_ns
1939 user_ns = self.user_ns
1940 global_ns = self.user_global_ns
1940 global_ns = self.user_global_ns
1941 for key, expr in expressions.iteritems():
1941 for key, expr in expressions.iteritems():
1942 try:
1942 try:
1943 value = repr(eval(expr, global_ns, user_ns))
1943 value = repr(eval(expr, global_ns, user_ns))
1944 except:
1944 except:
1945 value = self._simple_error()
1945 value = self._simple_error()
1946 out[key] = value
1946 out[key] = value
1947 return out
1947 return out
1948
1948
1949 #-------------------------------------------------------------------------
1949 #-------------------------------------------------------------------------
1950 # Things related to the running of code
1950 # Things related to the running of code
1951 #-------------------------------------------------------------------------
1951 #-------------------------------------------------------------------------
1952
1952
1953 def ex(self, cmd):
1953 def ex(self, cmd):
1954 """Execute a normal python statement in user namespace."""
1954 """Execute a normal python statement in user namespace."""
1955 with nested(self.builtin_trap,):
1955 with nested(self.builtin_trap,):
1956 exec cmd in self.user_global_ns, self.user_ns
1956 exec cmd in self.user_global_ns, self.user_ns
1957
1957
1958 def ev(self, expr):
1958 def ev(self, expr):
1959 """Evaluate python expression expr in user namespace.
1959 """Evaluate python expression expr in user namespace.
1960
1960
1961 Returns the result of evaluation
1961 Returns the result of evaluation
1962 """
1962 """
1963 with nested(self.builtin_trap,):
1963 with nested(self.builtin_trap,):
1964 return eval(expr, self.user_global_ns, self.user_ns)
1964 return eval(expr, self.user_global_ns, self.user_ns)
1965
1965
1966 def safe_execfile(self, fname, *where, **kw):
1966 def safe_execfile(self, fname, *where, **kw):
1967 """A safe version of the builtin execfile().
1967 """A safe version of the builtin execfile().
1968
1968
1969 This version will never throw an exception, but instead print
1969 This version will never throw an exception, but instead print
1970 helpful error messages to the screen. This only works on pure
1970 helpful error messages to the screen. This only works on pure
1971 Python files with the .py extension.
1971 Python files with the .py extension.
1972
1972
1973 Parameters
1973 Parameters
1974 ----------
1974 ----------
1975 fname : string
1975 fname : string
1976 The name of the file to be executed.
1976 The name of the file to be executed.
1977 where : tuple
1977 where : tuple
1978 One or two namespaces, passed to execfile() as (globals,locals).
1978 One or two namespaces, passed to execfile() as (globals,locals).
1979 If only one is given, it is passed as both.
1979 If only one is given, it is passed as both.
1980 exit_ignore : bool (False)
1980 exit_ignore : bool (False)
1981 If True, then silence SystemExit for non-zero status (it is always
1981 If True, then silence SystemExit for non-zero status (it is always
1982 silenced for zero status, as it is so common).
1982 silenced for zero status, as it is so common).
1983 """
1983 """
1984 kw.setdefault('exit_ignore', False)
1984 kw.setdefault('exit_ignore', False)
1985
1985
1986 fname = os.path.abspath(os.path.expanduser(fname))
1986 fname = os.path.abspath(os.path.expanduser(fname))
1987
1987
1988 # Make sure we have a .py file
1988 # Make sure we have a .py file
1989 if not fname.endswith('.py'):
1989 if not fname.endswith('.py'):
1990 warn('File must end with .py to be run using execfile: <%s>' % fname)
1990 warn('File must end with .py to be run using execfile: <%s>' % fname)
1991
1991
1992 # Make sure we can open the file
1992 # Make sure we can open the file
1993 try:
1993 try:
1994 with open(fname) as thefile:
1994 with open(fname) as thefile:
1995 pass
1995 pass
1996 except:
1996 except:
1997 warn('Could not open file <%s> for safe execution.' % fname)
1997 warn('Could not open file <%s> for safe execution.' % fname)
1998 return
1998 return
1999
1999
2000 # Find things also in current directory. This is needed to mimic the
2000 # Find things also in current directory. This is needed to mimic the
2001 # behavior of running a script from the system command line, where
2001 # behavior of running a script from the system command line, where
2002 # Python inserts the script's directory into sys.path
2002 # Python inserts the script's directory into sys.path
2003 dname = os.path.dirname(fname)
2003 dname = os.path.dirname(fname)
2004
2004
2005 with prepended_to_syspath(dname):
2005 with prepended_to_syspath(dname):
2006 try:
2006 try:
2007 execfile(fname,*where)
2007 execfile(fname,*where)
2008 except SystemExit, status:
2008 except SystemExit, status:
2009 # If the call was made with 0 or None exit status (sys.exit(0)
2009 # If the call was made with 0 or None exit status (sys.exit(0)
2010 # or sys.exit() ), don't bother showing a traceback, as both of
2010 # or sys.exit() ), don't bother showing a traceback, as both of
2011 # these are considered normal by the OS:
2011 # these are considered normal by the OS:
2012 # > python -c'import sys;sys.exit(0)'; echo $?
2012 # > python -c'import sys;sys.exit(0)'; echo $?
2013 # 0
2013 # 0
2014 # > python -c'import sys;sys.exit()'; echo $?
2014 # > python -c'import sys;sys.exit()'; echo $?
2015 # 0
2015 # 0
2016 # For other exit status, we show the exception unless
2016 # For other exit status, we show the exception unless
2017 # explicitly silenced, but only in short form.
2017 # explicitly silenced, but only in short form.
2018 if status.code not in (0, None) and not kw['exit_ignore']:
2018 if status.code not in (0, None) and not kw['exit_ignore']:
2019 self.showtraceback(exception_only=True)
2019 self.showtraceback(exception_only=True)
2020 except:
2020 except:
2021 self.showtraceback()
2021 self.showtraceback()
2022
2022
2023 def safe_execfile_ipy(self, fname):
2023 def safe_execfile_ipy(self, fname):
2024 """Like safe_execfile, but for .ipy files with IPython syntax.
2024 """Like safe_execfile, but for .ipy files with IPython syntax.
2025
2025
2026 Parameters
2026 Parameters
2027 ----------
2027 ----------
2028 fname : str
2028 fname : str
2029 The name of the file to execute. The filename must have a
2029 The name of the file to execute. The filename must have a
2030 .ipy extension.
2030 .ipy extension.
2031 """
2031 """
2032 fname = os.path.abspath(os.path.expanduser(fname))
2032 fname = os.path.abspath(os.path.expanduser(fname))
2033
2033
2034 # Make sure we have a .py file
2034 # Make sure we have a .py file
2035 if not fname.endswith('.ipy'):
2035 if not fname.endswith('.ipy'):
2036 warn('File must end with .py to be run using execfile: <%s>' % fname)
2036 warn('File must end with .py to be run using execfile: <%s>' % fname)
2037
2037
2038 # Make sure we can open the file
2038 # Make sure we can open the file
2039 try:
2039 try:
2040 with open(fname) as thefile:
2040 with open(fname) as thefile:
2041 pass
2041 pass
2042 except:
2042 except:
2043 warn('Could not open file <%s> for safe execution.' % fname)
2043 warn('Could not open file <%s> for safe execution.' % fname)
2044 return
2044 return
2045
2045
2046 # Find things also in current directory. This is needed to mimic the
2046 # Find things also in current directory. This is needed to mimic the
2047 # behavior of running a script from the system command line, where
2047 # behavior of running a script from the system command line, where
2048 # Python inserts the script's directory into sys.path
2048 # Python inserts the script's directory into sys.path
2049 dname = os.path.dirname(fname)
2049 dname = os.path.dirname(fname)
2050
2050
2051 with prepended_to_syspath(dname):
2051 with prepended_to_syspath(dname):
2052 try:
2052 try:
2053 with open(fname) as thefile:
2053 with open(fname) as thefile:
2054 # self.run_cell currently captures all exceptions
2054 # self.run_cell currently captures all exceptions
2055 # raised in user code. It would be nice if there were
2055 # raised in user code. It would be nice if there were
2056 # versions of runlines, execfile that did raise, so
2056 # versions of runlines, execfile that did raise, so
2057 # we could catch the errors.
2057 # we could catch the errors.
2058 self.run_cell(thefile.read())
2058 self.run_cell(thefile.read())
2059 except:
2059 except:
2060 self.showtraceback()
2060 self.showtraceback()
2061 warn('Unknown failure executing file: <%s>' % fname)
2061 warn('Unknown failure executing file: <%s>' % fname)
2062
2062
2063 def run_cell(self, cell, store_history=True):
2063 def run_cell(self, cell, store_history=True):
2064 """Run the contents of an entire multiline 'cell' of code, and store it
2064 """Run the contents of an entire multiline 'cell' of code, and store it
2065 in the history.
2065 in the history.
2066
2066
2067 The cell is split into separate blocks which can be executed
2067 The cell is split into separate blocks which can be executed
2068 individually. Then, based on how many blocks there are, they are
2068 individually. Then, based on how many blocks there are, they are
2069 executed as follows:
2069 executed as follows:
2070
2070
2071 - A single block: 'single' mode. If it is also a single line, dynamic
2071 - A single block: 'single' mode. If it is also a single line, dynamic
2072 transformations, including automagic and macros, will be applied.
2072 transformations, including automagic and macros, will be applied.
2073
2073
2074 If there's more than one block, it depends:
2074 If there's more than one block, it depends:
2075
2075
2076 - if the last one is no more than two lines long, run all but the last
2076 - if the last one is no more than two lines long, run all but the last
2077 in 'exec' mode and the very last one in 'single' mode. This makes it
2077 in 'exec' mode and the very last one in 'single' mode. This makes it
2078 easy to type simple expressions at the end to see computed values. -
2078 easy to type simple expressions at the end to see computed values. -
2079 otherwise (last one is also multiline), run all in 'exec' mode
2079 otherwise (last one is also multiline), run all in 'exec' mode
2080
2080
2081 When code is executed in 'single' mode, :func:`sys.displayhook` fires,
2081 When code is executed in 'single' mode, :func:`sys.displayhook` fires,
2082 results are displayed and output prompts are computed. In 'exec' mode,
2082 results are displayed and output prompts are computed. In 'exec' mode,
2083 no results are displayed unless :func:`print` is called explicitly;
2083 no results are displayed unless :func:`print` is called explicitly;
2084 this mode is more akin to running a script.
2084 this mode is more akin to running a script.
2085
2085
2086 Parameters
2086 Parameters
2087 ----------
2087 ----------
2088 cell : str
2088 cell : str
2089 A single or multiline string.
2089 A single or multiline string.
2090 """
2090 """
2091 # Store the untransformed code
2091 # Store the untransformed code
2092 raw_cell = cell
2092 raw_cell = cell
2093
2093
2094 # We only do dynamic transforms on a single line. We need to do this
2094 # We only do dynamic transforms on a single line. We need to do this
2095 # first, because a macro can be expanded to several lines, which then
2095 # first, because a macro can be expanded to several lines, which then
2096 # need to be split into blocks again.
2096 # need to be split into blocks again.
2097 if len(cell.splitlines()) <= 1:
2097 if len(cell.splitlines()) <= 1:
2098 temp = self.input_splitter.split_blocks(cell)
2098 temp = self.input_splitter.split_blocks(cell)
2099 cell = self.prefilter_manager.prefilter_line(temp[0])
2099 cell = self.prefilter_manager.prefilter_line(temp[0])
2100
2100
2101 # We need to break up the input into executable blocks that can be run
2101 # We need to break up the input into executable blocks that can be run
2102 # in 'single' mode, to provide comfortable user behavior.
2102 # in 'single' mode, to provide comfortable user behavior.
2103 blocks = self.input_splitter.split_blocks(cell)
2103 blocks = self.input_splitter.split_blocks(cell)
2104
2104
2105 if not blocks:
2105 if not blocks:
2106 return
2106 return
2107
2107
2108 # Store the 'ipython' version of the cell as well, since that's what
2108 # Store the 'ipython' version of the cell as well, since that's what
2109 # needs to go into the translated history and get executed (the
2109 # needs to go into the translated history and get executed (the
2110 # original cell may contain non-python syntax).
2110 # original cell may contain non-python syntax).
2111 cell = ''.join(blocks)
2111 cell = ''.join(blocks)
2112
2112
2113 # Store raw and processed history
2113 # Store raw and processed history
2114 if store_history:
2114 if store_history:
2115 self.history_manager.store_inputs(self.execution_count,
2115 self.history_manager.store_inputs(self.execution_count,
2116 cell, raw_cell)
2116 cell, raw_cell)
2117
2117
2118 self.logger.log(cell, raw_cell)
2118 self.logger.log(cell, raw_cell)
2119
2119
2120 # All user code execution must happen with our context managers active
2120 # All user code execution must happen with our context managers active
2121 with nested(self.builtin_trap, self.display_trap):
2121 with nested(self.builtin_trap, self.display_trap):
2122
2122
2123 # Single-block input should behave like an interactive prompt
2123 # Single-block input should behave like an interactive prompt
2124 if len(blocks) == 1:
2124 if len(blocks) == 1:
2125 out = self.run_source(blocks[0])
2125 out = self.run_source(blocks[0])
2126 # Write output to the database. Does nothing unless
2126 # Write output to the database. Does nothing unless
2127 # history output logging is enabled.
2127 # history output logging is enabled.
2128 if store_history:
2128 if store_history:
2129 self.history_manager.store_output(self.execution_count)
2129 self.history_manager.store_output(self.execution_count)
2130 # since we return here, we need to update the execution count
2130 # since we return here, we need to update the execution count
2131 self.execution_count += 1
2131 self.execution_count += 1
2132 return out
2132 return out
2133
2133
2134 # In multi-block input, if the last block is a simple (one-two
2134 # In multi-block input, if the last block is a simple (one-two
2135 # lines) expression, run it in single mode so it produces output.
2135 # lines) expression, run it in single mode so it produces output.
2136 # Otherwise just run it all in 'exec' mode. This seems like a
2136 # Otherwise just run it all in 'exec' mode. This seems like a
2137 # reasonable usability design.
2137 # reasonable usability design.
2138 last = blocks[-1]
2138 last = blocks[-1]
2139 last_nlines = len(last.splitlines())
2139 last_nlines = len(last.splitlines())
2140
2140
2141 if last_nlines < 2:
2141 if last_nlines < 2:
2142 # Here we consider the cell split between 'body' and 'last',
2142 # Here we consider the cell split between 'body' and 'last',
2143 # store all history and execute 'body', and if successful, then
2143 # store all history and execute 'body', and if successful, then
2144 # proceed to execute 'last'.
2144 # proceed to execute 'last'.
2145
2145
2146 # Get the main body to run as a cell
2146 # Get the main body to run as a cell
2147 ipy_body = ''.join(blocks[:-1])
2147 ipy_body = ''.join(blocks[:-1])
2148 retcode = self.run_source(ipy_body, symbol='exec',
2148 retcode = self.run_source(ipy_body, symbol='exec',
2149 post_execute=False)
2149 post_execute=False)
2150 if retcode==0:
2150 if retcode==0:
2151 # Last expression compiled as 'single' so it produces output
2151 # Last expression compiled as 'single' so it produces output
2152 self.run_source(last)
2152 self.run_source(last)
2153 else:
2153 else:
2154 # Run the whole cell as one entity, storing both raw and
2154 # Run the whole cell as one entity, storing both raw and
2155 # processed input in history
2155 # processed input in history
2156 self.run_source(ipy_cell, symbol='exec')
2156 self.run_source(ipy_cell, symbol='exec')
2157
2157
2158 # Write output to the database. Does nothing unless
2158 # Write output to the database. Does nothing unless
2159 # history output logging is enabled.
2159 # history output logging is enabled.
2160 if store_history:
2160 if store_history:
2161 self.history_manager.store_output(self.execution_count)
2161 self.history_manager.store_output(self.execution_count)
2162 # Each cell is a *single* input, regardless of how many lines it has
2162 # Each cell is a *single* input, regardless of how many lines it has
2163 self.execution_count += 1
2163 self.execution_count += 1
2164
2164
2165 # PENDING REMOVAL: this method is slated for deletion, once our new
2165 # PENDING REMOVAL: this method is slated for deletion, once our new
2166 # input logic has been 100% moved to frontends and is stable.
2166 # input logic has been 100% moved to frontends and is stable.
2167 def runlines(self, lines, clean=False):
2167 def runlines(self, lines, clean=False):
2168 """Run a string of one or more lines of source.
2168 """Run a string of one or more lines of source.
2169
2169
2170 This method is capable of running a string containing multiple source
2170 This method is capable of running a string containing multiple source
2171 lines, as if they had been entered at the IPython prompt. Since it
2171 lines, as if they had been entered at the IPython prompt. Since it
2172 exposes IPython's processing machinery, the given strings can contain
2172 exposes IPython's processing machinery, the given strings can contain
2173 magic calls (%magic), special shell access (!cmd), etc.
2173 magic calls (%magic), special shell access (!cmd), etc.
2174 """
2174 """
2175
2175
2176 if not isinstance(lines, (list, tuple)):
2176 if not isinstance(lines, (list, tuple)):
2177 lines = lines.splitlines()
2177 lines = lines.splitlines()
2178
2178
2179 if clean:
2179 if clean:
2180 lines = self._cleanup_ipy_script(lines)
2180 lines = self._cleanup_ipy_script(lines)
2181
2181
2182 # We must start with a clean buffer, in case this is run from an
2182 # We must start with a clean buffer, in case this is run from an
2183 # interactive IPython session (via a magic, for example).
2183 # interactive IPython session (via a magic, for example).
2184 self.reset_buffer()
2184 self.reset_buffer()
2185
2185
2186 # Since we will prefilter all lines, store the user's raw input too
2186 # Since we will prefilter all lines, store the user's raw input too
2187 # before we apply any transformations
2187 # before we apply any transformations
2188 self.buffer_raw[:] = [ l+'\n' for l in lines]
2188 self.buffer_raw[:] = [ l+'\n' for l in lines]
2189
2189
2190 more = False
2190 more = False
2191 prefilter_lines = self.prefilter_manager.prefilter_lines
2191 prefilter_lines = self.prefilter_manager.prefilter_lines
2192 with nested(self.builtin_trap, self.display_trap):
2192 with nested(self.builtin_trap, self.display_trap):
2193 for line in lines:
2193 for line in lines:
2194 # skip blank lines so we don't mess up the prompt counter, but
2194 # skip blank lines so we don't mess up the prompt counter, but
2195 # do NOT skip even a blank line if we are in a code block (more
2195 # do NOT skip even a blank line if we are in a code block (more
2196 # is true)
2196 # is true)
2197
2197
2198 if line or more:
2198 if line or more:
2199 more = self.push_line(prefilter_lines(line, more))
2199 more = self.push_line(prefilter_lines(line, more))
2200 # IPython's run_source returns None if there was an error
2200 # IPython's run_source returns None if there was an error
2201 # compiling the code. This allows us to stop processing
2201 # compiling the code. This allows us to stop processing
2202 # right away, so the user gets the error message at the
2202 # right away, so the user gets the error message at the
2203 # right place.
2203 # right place.
2204 if more is None:
2204 if more is None:
2205 break
2205 break
2206 # final newline in case the input didn't have it, so that the code
2206 # final newline in case the input didn't have it, so that the code
2207 # actually does get executed
2207 # actually does get executed
2208 if more:
2208 if more:
2209 self.push_line('\n')
2209 self.push_line('\n')
2210
2210
2211 def run_source(self, source, filename=None,
2211 def run_source(self, source, filename=None,
2212 symbol='single', post_execute=True):
2212 symbol='single', post_execute=True):
2213 """Compile and run some source in the interpreter.
2213 """Compile and run some source in the interpreter.
2214
2214
2215 Arguments are as for compile_command().
2215 Arguments are as for compile_command().
2216
2216
2217 One several things can happen:
2217 One several things can happen:
2218
2218
2219 1) The input is incorrect; compile_command() raised an
2219 1) The input is incorrect; compile_command() raised an
2220 exception (SyntaxError or OverflowError). A syntax traceback
2220 exception (SyntaxError or OverflowError). A syntax traceback
2221 will be printed by calling the showsyntaxerror() method.
2221 will be printed by calling the showsyntaxerror() method.
2222
2222
2223 2) The input is incomplete, and more input is required;
2223 2) The input is incomplete, and more input is required;
2224 compile_command() returned None. Nothing happens.
2224 compile_command() returned None. Nothing happens.
2225
2225
2226 3) The input is complete; compile_command() returned a code
2226 3) The input is complete; compile_command() returned a code
2227 object. The code is executed by calling self.run_code() (which
2227 object. The code is executed by calling self.run_code() (which
2228 also handles run-time exceptions, except for SystemExit).
2228 also handles run-time exceptions, except for SystemExit).
2229
2229
2230 The return value is:
2230 The return value is:
2231
2231
2232 - True in case 2
2232 - True in case 2
2233
2233
2234 - False in the other cases, unless an exception is raised, where
2234 - False in the other cases, unless an exception is raised, where
2235 None is returned instead. This can be used by external callers to
2235 None is returned instead. This can be used by external callers to
2236 know whether to continue feeding input or not.
2236 know whether to continue feeding input or not.
2237
2237
2238 The return value can be used to decide whether to use sys.ps1 or
2238 The return value can be used to decide whether to use sys.ps1 or
2239 sys.ps2 to prompt the next line."""
2239 sys.ps2 to prompt the next line."""
2240
2240
2241 # We need to ensure that the source is unicode from here on.
2241 # We need to ensure that the source is unicode from here on.
2242 if type(source)==str:
2242 if type(source)==str:
2243 usource = source.decode(self.stdin_encoding)
2243 usource = source.decode(self.stdin_encoding)
2244 else:
2244 else:
2245 usource = source
2245 usource = source
2246
2246
2247 if 0: # dbg
2247 if 0: # dbg
2248 print 'Source:', repr(source) # dbg
2248 print 'Source:', repr(source) # dbg
2249 print 'USource:', repr(usource) # dbg
2249 print 'USource:', repr(usource) # dbg
2250 print 'type:', type(source) # dbg
2250 print 'type:', type(source) # dbg
2251 print 'encoding', self.stdin_encoding # dbg
2251 print 'encoding', self.stdin_encoding # dbg
2252
2252
2253 try:
2253 try:
2254 code = self.compile(usource, symbol, self.execution_count)
2254 code = self.compile(usource, symbol, self.execution_count)
2255 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2255 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2256 # Case 1
2256 # Case 1
2257 self.showsyntaxerror(filename)
2257 self.showsyntaxerror(filename)
2258 return None
2258 return None
2259
2259
2260 if code is None:
2260 if code is None:
2261 # Case 2
2261 # Case 2
2262 return True
2262 return True
2263
2263
2264 # Case 3
2264 # Case 3
2265 # We store the code object so that threaded shells and
2265 # We store the code object so that threaded shells and
2266 # custom exception handlers can access all this info if needed.
2266 # custom exception handlers can access all this info if needed.
2267 # The source corresponding to this can be obtained from the
2267 # The source corresponding to this can be obtained from the
2268 # buffer attribute as '\n'.join(self.buffer).
2268 # buffer attribute as '\n'.join(self.buffer).
2269 self.code_to_run = code
2269 self.code_to_run = code
2270 # now actually execute the code object
2270 # now actually execute the code object
2271 if self.run_code(code, post_execute) == 0:
2271 if self.run_code(code, post_execute) == 0:
2272 return False
2272 return False
2273 else:
2273 else:
2274 return None
2274 return None
2275
2275
2276 # For backwards compatibility
2276 # For backwards compatibility
2277 runsource = run_source
2277 runsource = run_source
2278
2278
2279 def run_code(self, code_obj, post_execute=True):
2279 def run_code(self, code_obj, post_execute=True):
2280 """Execute a code object.
2280 """Execute a code object.
2281
2281
2282 When an exception occurs, self.showtraceback() is called to display a
2282 When an exception occurs, self.showtraceback() is called to display a
2283 traceback.
2283 traceback.
2284
2284
2285 Return value: a flag indicating whether the code to be run completed
2285 Return value: a flag indicating whether the code to be run completed
2286 successfully:
2286 successfully:
2287
2287
2288 - 0: successful execution.
2288 - 0: successful execution.
2289 - 1: an error occurred.
2289 - 1: an error occurred.
2290 """
2290 """
2291
2291
2292 # Set our own excepthook in case the user code tries to call it
2292 # Set our own excepthook in case the user code tries to call it
2293 # directly, so that the IPython crash handler doesn't get triggered
2293 # directly, so that the IPython crash handler doesn't get triggered
2294 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2294 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2295
2295
2296 # we save the original sys.excepthook in the instance, in case config
2296 # we save the original sys.excepthook in the instance, in case config
2297 # code (such as magics) needs access to it.
2297 # code (such as magics) needs access to it.
2298 self.sys_excepthook = old_excepthook
2298 self.sys_excepthook = old_excepthook
2299 outflag = 1 # happens in more places, so it's easier as default
2299 outflag = 1 # happens in more places, so it's easier as default
2300 try:
2300 try:
2301 try:
2301 try:
2302 self.hooks.pre_run_code_hook()
2302 self.hooks.pre_run_code_hook()
2303 #rprint('Running code', repr(code_obj)) # dbg
2303 #rprint('Running code', repr(code_obj)) # dbg
2304 exec code_obj in self.user_global_ns, self.user_ns
2304 exec code_obj in self.user_global_ns, self.user_ns
2305 finally:
2305 finally:
2306 # Reset our crash handler in place
2306 # Reset our crash handler in place
2307 sys.excepthook = old_excepthook
2307 sys.excepthook = old_excepthook
2308 except SystemExit:
2308 except SystemExit:
2309 self.reset_buffer()
2309 self.reset_buffer()
2310 self.showtraceback(exception_only=True)
2310 self.showtraceback(exception_only=True)
2311 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2311 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2312 except self.custom_exceptions:
2312 except self.custom_exceptions:
2313 etype,value,tb = sys.exc_info()
2313 etype,value,tb = sys.exc_info()
2314 self.CustomTB(etype,value,tb)
2314 self.CustomTB(etype,value,tb)
2315 except:
2315 except:
2316 self.showtraceback()
2316 self.showtraceback()
2317 else:
2317 else:
2318 outflag = 0
2318 outflag = 0
2319 if softspace(sys.stdout, 0):
2319 if softspace(sys.stdout, 0):
2320 print
2320 print
2321
2321
2322 # Execute any registered post-execution functions. Here, any errors
2322 # Execute any registered post-execution functions. Here, any errors
2323 # are reported only minimally and just on the terminal, because the
2323 # are reported only minimally and just on the terminal, because the
2324 # main exception channel may be occupied with a user traceback.
2324 # main exception channel may be occupied with a user traceback.
2325 # FIXME: we need to think this mechanism a little more carefully.
2325 # FIXME: we need to think this mechanism a little more carefully.
2326 if post_execute:
2326 if post_execute:
2327 for func in self._post_execute:
2327 for func in self._post_execute:
2328 try:
2328 try:
2329 func()
2329 func()
2330 except:
2330 except:
2331 head = '[ ERROR ] Evaluating post_execute function: %s' % \
2331 head = '[ ERROR ] Evaluating post_execute function: %s' % \
2332 func
2332 func
2333 print >> io.Term.cout, head
2333 print >> io.Term.cout, head
2334 print >> io.Term.cout, self._simple_error()
2334 print >> io.Term.cout, self._simple_error()
2335 print >> io.Term.cout, 'Removing from post_execute'
2335 print >> io.Term.cout, 'Removing from post_execute'
2336 self._post_execute.remove(func)
2336 self._post_execute.remove(func)
2337
2337
2338 # Flush out code object which has been run (and source)
2338 # Flush out code object which has been run (and source)
2339 self.code_to_run = None
2339 self.code_to_run = None
2340 return outflag
2340 return outflag
2341
2341
2342 # For backwards compatibility
2342 # For backwards compatibility
2343 runcode = run_code
2343 runcode = run_code
2344
2344
2345 # PENDING REMOVAL: this method is slated for deletion, once our new
2345 # PENDING REMOVAL: this method is slated for deletion, once our new
2346 # input logic has been 100% moved to frontends and is stable.
2346 # input logic has been 100% moved to frontends and is stable.
2347 def push_line(self, line):
2347 def push_line(self, line):
2348 """Push a line to the interpreter.
2348 """Push a line to the interpreter.
2349
2349
2350 The line should not have a trailing newline; it may have
2350 The line should not have a trailing newline; it may have
2351 internal newlines. The line is appended to a buffer and the
2351 internal newlines. The line is appended to a buffer and the
2352 interpreter's run_source() method is called with the
2352 interpreter's run_source() method is called with the
2353 concatenated contents of the buffer as source. If this
2353 concatenated contents of the buffer as source. If this
2354 indicates that the command was executed or invalid, the buffer
2354 indicates that the command was executed or invalid, the buffer
2355 is reset; otherwise, the command is incomplete, and the buffer
2355 is reset; otherwise, the command is incomplete, and the buffer
2356 is left as it was after the line was appended. The return
2356 is left as it was after the line was appended. The return
2357 value is 1 if more input is required, 0 if the line was dealt
2357 value is 1 if more input is required, 0 if the line was dealt
2358 with in some way (this is the same as run_source()).
2358 with in some way (this is the same as run_source()).
2359 """
2359 """
2360
2360
2361 # autoindent management should be done here, and not in the
2361 # autoindent management should be done here, and not in the
2362 # interactive loop, since that one is only seen by keyboard input. We
2362 # interactive loop, since that one is only seen by keyboard input. We
2363 # need this done correctly even for code run via runlines (which uses
2363 # need this done correctly even for code run via runlines (which uses
2364 # push).
2364 # push).
2365
2365
2366 #print 'push line: <%s>' % line # dbg
2366 #print 'push line: <%s>' % line # dbg
2367 self.buffer.append(line)
2367 self.buffer.append(line)
2368 full_source = '\n'.join(self.buffer)
2368 full_source = '\n'.join(self.buffer)
2369 more = self.run_source(full_source, self.filename)
2369 more = self.run_source(full_source, self.filename)
2370 if not more:
2370 if not more:
2371 self.history_manager.store_inputs(self.execution_count,
2371 self.history_manager.store_inputs(self.execution_count,
2372 '\n'.join(self.buffer_raw), full_source)
2372 '\n'.join(self.buffer_raw), full_source)
2373 self.reset_buffer()
2373 self.reset_buffer()
2374 self.execution_count += 1
2374 self.execution_count += 1
2375 return more
2375 return more
2376
2376
2377 def reset_buffer(self):
2377 def reset_buffer(self):
2378 """Reset the input buffer."""
2378 """Reset the input buffer."""
2379 self.buffer[:] = []
2379 self.buffer[:] = []
2380 self.buffer_raw[:] = []
2380 self.buffer_raw[:] = []
2381 self.input_splitter.reset()
2381 self.input_splitter.reset()
2382
2382
2383 # For backwards compatibility
2383 # For backwards compatibility
2384 resetbuffer = reset_buffer
2384 resetbuffer = reset_buffer
2385
2385
2386 def _is_secondary_block_start(self, s):
2386 def _is_secondary_block_start(self, s):
2387 if not s.endswith(':'):
2387 if not s.endswith(':'):
2388 return False
2388 return False
2389 if (s.startswith('elif') or
2389 if (s.startswith('elif') or
2390 s.startswith('else') or
2390 s.startswith('else') or
2391 s.startswith('except') or
2391 s.startswith('except') or
2392 s.startswith('finally')):
2392 s.startswith('finally')):
2393 return True
2393 return True
2394
2394
2395 def _cleanup_ipy_script(self, script):
2395 def _cleanup_ipy_script(self, script):
2396 """Make a script safe for self.runlines()
2396 """Make a script safe for self.runlines()
2397
2397
2398 Currently, IPython is lines based, with blocks being detected by
2398 Currently, IPython is lines based, with blocks being detected by
2399 empty lines. This is a problem for block based scripts that may
2399 empty lines. This is a problem for block based scripts that may
2400 not have empty lines after blocks. This script adds those empty
2400 not have empty lines after blocks. This script adds those empty
2401 lines to make scripts safe for running in the current line based
2401 lines to make scripts safe for running in the current line based
2402 IPython.
2402 IPython.
2403 """
2403 """
2404 res = []
2404 res = []
2405 lines = script.splitlines()
2405 lines = script.splitlines()
2406 level = 0
2406 level = 0
2407
2407
2408 for l in lines:
2408 for l in lines:
2409 lstripped = l.lstrip()
2409 lstripped = l.lstrip()
2410 stripped = l.strip()
2410 stripped = l.strip()
2411 if not stripped:
2411 if not stripped:
2412 continue
2412 continue
2413 newlevel = len(l) - len(lstripped)
2413 newlevel = len(l) - len(lstripped)
2414 if level > 0 and newlevel == 0 and \
2414 if level > 0 and newlevel == 0 and \
2415 not self._is_secondary_block_start(stripped):
2415 not self._is_secondary_block_start(stripped):
2416 # add empty line
2416 # add empty line
2417 res.append('')
2417 res.append('')
2418 res.append(l)
2418 res.append(l)
2419 level = newlevel
2419 level = newlevel
2420
2420
2421 return '\n'.join(res) + '\n'
2421 return '\n'.join(res) + '\n'
2422
2422
2423 #-------------------------------------------------------------------------
2423 #-------------------------------------------------------------------------
2424 # Things related to GUI support and pylab
2424 # Things related to GUI support and pylab
2425 #-------------------------------------------------------------------------
2425 #-------------------------------------------------------------------------
2426
2426
2427 def enable_pylab(self, gui=None):
2427 def enable_pylab(self, gui=None):
2428 raise NotImplementedError('Implement enable_pylab in a subclass')
2428 raise NotImplementedError('Implement enable_pylab in a subclass')
2429
2429
2430 #-------------------------------------------------------------------------
2430 #-------------------------------------------------------------------------
2431 # Utilities
2431 # Utilities
2432 #-------------------------------------------------------------------------
2432 #-------------------------------------------------------------------------
2433
2433
2434 def var_expand(self,cmd,depth=0):
2434 def var_expand(self,cmd,depth=0):
2435 """Expand python variables in a string.
2435 """Expand python variables in a string.
2436
2436
2437 The depth argument indicates how many frames above the caller should
2437 The depth argument indicates how many frames above the caller should
2438 be walked to look for the local namespace where to expand variables.
2438 be walked to look for the local namespace where to expand variables.
2439
2439
2440 The global namespace for expansion is always the user's interactive
2440 The global namespace for expansion is always the user's interactive
2441 namespace.
2441 namespace.
2442 """
2442 """
2443
2443
2444 return str(ItplNS(cmd,
2444 return str(ItplNS(cmd,
2445 self.user_ns, # globals
2445 self.user_ns, # globals
2446 # Skip our own frame in searching for locals:
2446 # Skip our own frame in searching for locals:
2447 sys._getframe(depth+1).f_locals # locals
2447 sys._getframe(depth+1).f_locals # locals
2448 ))
2448 ))
2449
2449
2450 def mktempfile(self, data=None, prefix='ipython_edit_'):
2450 def mktempfile(self, data=None, prefix='ipython_edit_'):
2451 """Make a new tempfile and return its filename.
2451 """Make a new tempfile and return its filename.
2452
2452
2453 This makes a call to tempfile.mktemp, but it registers the created
2453 This makes a call to tempfile.mktemp, but it registers the created
2454 filename internally so ipython cleans it up at exit time.
2454 filename internally so ipython cleans it up at exit time.
2455
2455
2456 Optional inputs:
2456 Optional inputs:
2457
2457
2458 - data(None): if data is given, it gets written out to the temp file
2458 - data(None): if data is given, it gets written out to the temp file
2459 immediately, and the file is closed again."""
2459 immediately, and the file is closed again."""
2460
2460
2461 filename = tempfile.mktemp('.py', prefix)
2461 filename = tempfile.mktemp('.py', prefix)
2462 self.tempfiles.append(filename)
2462 self.tempfiles.append(filename)
2463
2463
2464 if data:
2464 if data:
2465 tmp_file = open(filename,'w')
2465 tmp_file = open(filename,'w')
2466 tmp_file.write(data)
2466 tmp_file.write(data)
2467 tmp_file.close()
2467 tmp_file.close()
2468 return filename
2468 return filename
2469
2469
2470 # TODO: This should be removed when Term is refactored.
2470 # TODO: This should be removed when Term is refactored.
2471 def write(self,data):
2471 def write(self,data):
2472 """Write a string to the default output"""
2472 """Write a string to the default output"""
2473 io.Term.cout.write(data)
2473 io.Term.cout.write(data)
2474
2474
2475 # TODO: This should be removed when Term is refactored.
2475 # TODO: This should be removed when Term is refactored.
2476 def write_err(self,data):
2476 def write_err(self,data):
2477 """Write a string to the default error output"""
2477 """Write a string to the default error output"""
2478 io.Term.cerr.write(data)
2478 io.Term.cerr.write(data)
2479
2479
2480 def ask_yes_no(self,prompt,default=True):
2480 def ask_yes_no(self,prompt,default=True):
2481 if self.quiet:
2481 if self.quiet:
2482 return True
2482 return True
2483 return ask_yes_no(prompt,default)
2483 return ask_yes_no(prompt,default)
2484
2484
2485 def show_usage(self):
2485 def show_usage(self):
2486 """Show a usage message"""
2486 """Show a usage message"""
2487 page.page(IPython.core.usage.interactive_usage)
2487 page.page(IPython.core.usage.interactive_usage)
2488
2488
2489 #-------------------------------------------------------------------------
2489 #-------------------------------------------------------------------------
2490 # Things related to IPython exiting
2490 # Things related to IPython exiting
2491 #-------------------------------------------------------------------------
2491 #-------------------------------------------------------------------------
2492 def atexit_operations(self):
2492 def atexit_operations(self):
2493 """This will be executed at the time of exit.
2493 """This will be executed at the time of exit.
2494
2494
2495 Cleanup operations and saving of persistent data that is done
2495 Cleanup operations and saving of persistent data that is done
2496 unconditionally by IPython should be performed here.
2496 unconditionally by IPython should be performed here.
2497
2497
2498 For things that may depend on startup flags or platform specifics (such
2498 For things that may depend on startup flags or platform specifics (such
2499 as having readline or not), register a separate atexit function in the
2499 as having readline or not), register a separate atexit function in the
2500 code that has the appropriate information, rather than trying to
2500 code that has the appropriate information, rather than trying to
2501 clutter
2501 clutter
2502 """
2502 """
2503 # Cleanup all tempfiles left around
2503 # Cleanup all tempfiles left around
2504 for tfile in self.tempfiles:
2504 for tfile in self.tempfiles:
2505 try:
2505 try:
2506 os.unlink(tfile)
2506 os.unlink(tfile)
2507 except OSError:
2507 except OSError:
2508 pass
2508 pass
2509
2509
2510 # Close the history session (this stores the end time and line count)
2510 # Close the history session (this stores the end time and line count)
2511 self.history_manager.end_session()
2511 self.history_manager.end_session()
2512
2512
2513 # Clear all user namespaces to release all references cleanly.
2513 # Clear all user namespaces to release all references cleanly.
2514 self.reset(new_session=False)
2514 self.reset(new_session=False)
2515
2515
2516 # Run user hooks
2516 # Run user hooks
2517 self.hooks.shutdown_hook()
2517 self.hooks.shutdown_hook()
2518
2518
2519 def cleanup(self):
2519 def cleanup(self):
2520 self.restore_sys_module_state()
2520 self.restore_sys_module_state()
2521
2521
2522
2522
2523 class InteractiveShellABC(object):
2523 class InteractiveShellABC(object):
2524 """An abstract base class for InteractiveShell."""
2524 """An abstract base class for InteractiveShell."""
2525 __metaclass__ = abc.ABCMeta
2525 __metaclass__ = abc.ABCMeta
2526
2526
2527 InteractiveShellABC.register(InteractiveShell)
2527 InteractiveShellABC.register(InteractiveShell)
@@ -1,3456 +1,3450 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """Magic functions for InteractiveShell.
2 """Magic functions for InteractiveShell.
3 """
3 """
4
4
5 #-----------------------------------------------------------------------------
5 #-----------------------------------------------------------------------------
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
7 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
8 # Copyright (C) 2008-2009 The IPython Development Team
8 # Copyright (C) 2008-2009 The IPython Development Team
9
9
10 # Distributed under the terms of the BSD License. The full license is in
10 # Distributed under the terms of the BSD License. The full license is in
11 # the file COPYING, distributed as part of this software.
11 # the file COPYING, distributed as part of this software.
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13
13
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15 # Imports
15 # Imports
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17
17
18 import __builtin__
18 import __builtin__
19 import __future__
19 import __future__
20 import bdb
20 import bdb
21 import inspect
21 import inspect
22 import os
22 import os
23 import sys
23 import sys
24 import shutil
24 import shutil
25 import re
25 import re
26 import time
26 import time
27 import textwrap
27 import textwrap
28 import types
28 import types
29 from cStringIO import StringIO
29 from cStringIO import StringIO
30 from getopt import getopt,GetoptError
30 from getopt import getopt,GetoptError
31 from pprint import pformat
31 from pprint import pformat
32
32
33 # cProfile was added in Python2.5
33 # cProfile was added in Python2.5
34 try:
34 try:
35 import cProfile as profile
35 import cProfile as profile
36 import pstats
36 import pstats
37 except ImportError:
37 except ImportError:
38 # profile isn't bundled by default in Debian for license reasons
38 # profile isn't bundled by default in Debian for license reasons
39 try:
39 try:
40 import profile,pstats
40 import profile,pstats
41 except ImportError:
41 except ImportError:
42 profile = pstats = None
42 profile = pstats = None
43
43
44 import IPython
44 import IPython
45 from IPython.core import debugger, oinspect
45 from IPython.core import debugger, oinspect
46 from IPython.core.error import TryNext
46 from IPython.core.error import TryNext
47 from IPython.core.error import UsageError
47 from IPython.core.error import UsageError
48 from IPython.core.fakemodule import FakeModule
48 from IPython.core.fakemodule import FakeModule
49 from IPython.core.macro import Macro
49 from IPython.core.macro import Macro
50 from IPython.core import page
50 from IPython.core import page
51 from IPython.core.prefilter import ESC_MAGIC
51 from IPython.core.prefilter import ESC_MAGIC
52 from IPython.lib.pylabtools import mpl_runner
52 from IPython.lib.pylabtools import mpl_runner
53 from IPython.external.Itpl import itpl, printpl
53 from IPython.external.Itpl import itpl, printpl
54 from IPython.testing import decorators as testdec
54 from IPython.testing import decorators as testdec
55 from IPython.utils.io import file_read, nlprint
55 from IPython.utils.io import file_read, nlprint
56 import IPython.utils.io
56 import IPython.utils.io
57 from IPython.utils.path import get_py_filename
57 from IPython.utils.path import get_py_filename
58 from IPython.utils.process import arg_split, abbrev_cwd
58 from IPython.utils.process import arg_split, abbrev_cwd
59 from IPython.utils.terminal import set_term_title
59 from IPython.utils.terminal import set_term_title
60 from IPython.utils.text import LSString, SList, format_screen
60 from IPython.utils.text import LSString, SList, format_screen
61 from IPython.utils.timing import clock, clock2
61 from IPython.utils.timing import clock, clock2
62 from IPython.utils.warn import warn, error
62 from IPython.utils.warn import warn, error
63 from IPython.utils.ipstruct import Struct
63 from IPython.utils.ipstruct import Struct
64 import IPython.utils.generics
64 import IPython.utils.generics
65
65
66 #-----------------------------------------------------------------------------
66 #-----------------------------------------------------------------------------
67 # Utility functions
67 # Utility functions
68 #-----------------------------------------------------------------------------
68 #-----------------------------------------------------------------------------
69
69
70 def on_off(tag):
70 def on_off(tag):
71 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
71 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
72 return ['OFF','ON'][tag]
72 return ['OFF','ON'][tag]
73
73
74 class Bunch: pass
74 class Bunch: pass
75
75
76 def compress_dhist(dh):
76 def compress_dhist(dh):
77 head, tail = dh[:-10], dh[-10:]
77 head, tail = dh[:-10], dh[-10:]
78
78
79 newhead = []
79 newhead = []
80 done = set()
80 done = set()
81 for h in head:
81 for h in head:
82 if h in done:
82 if h in done:
83 continue
83 continue
84 newhead.append(h)
84 newhead.append(h)
85 done.add(h)
85 done.add(h)
86
86
87 return newhead + tail
87 return newhead + tail
88
88
89
89
90 #***************************************************************************
90 #***************************************************************************
91 # Main class implementing Magic functionality
91 # Main class implementing Magic functionality
92
92
93 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
93 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
94 # on construction of the main InteractiveShell object. Something odd is going
94 # on construction of the main InteractiveShell object. Something odd is going
95 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
95 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
96 # eventually this needs to be clarified.
96 # eventually this needs to be clarified.
97 # BG: This is because InteractiveShell inherits from this, but is itself a
97 # BG: This is because InteractiveShell inherits from this, but is itself a
98 # Configurable. This messes up the MRO in some way. The fix is that we need to
98 # Configurable. This messes up the MRO in some way. The fix is that we need to
99 # make Magic a configurable that InteractiveShell does not subclass.
99 # make Magic a configurable that InteractiveShell does not subclass.
100
100
101 class Magic:
101 class Magic:
102 """Magic functions for InteractiveShell.
102 """Magic functions for InteractiveShell.
103
103
104 Shell functions which can be reached as %function_name. All magic
104 Shell functions which can be reached as %function_name. All magic
105 functions should accept a string, which they can parse for their own
105 functions should accept a string, which they can parse for their own
106 needs. This can make some functions easier to type, eg `%cd ../`
106 needs. This can make some functions easier to type, eg `%cd ../`
107 vs. `%cd("../")`
107 vs. `%cd("../")`
108
108
109 ALL definitions MUST begin with the prefix magic_. The user won't need it
109 ALL definitions MUST begin with the prefix magic_. The user won't need it
110 at the command line, but it is is needed in the definition. """
110 at the command line, but it is is needed in the definition. """
111
111
112 # class globals
112 # class globals
113 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
113 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
114 'Automagic is ON, % prefix NOT needed for magic functions.']
114 'Automagic is ON, % prefix NOT needed for magic functions.']
115
115
116 #......................................................................
116 #......................................................................
117 # some utility functions
117 # some utility functions
118
118
119 def __init__(self,shell):
119 def __init__(self,shell):
120
120
121 self.options_table = {}
121 self.options_table = {}
122 if profile is None:
122 if profile is None:
123 self.magic_prun = self.profile_missing_notice
123 self.magic_prun = self.profile_missing_notice
124 self.shell = shell
124 self.shell = shell
125
125
126 # namespace for holding state we may need
126 # namespace for holding state we may need
127 self._magic_state = Bunch()
127 self._magic_state = Bunch()
128
128
129 def profile_missing_notice(self, *args, **kwargs):
129 def profile_missing_notice(self, *args, **kwargs):
130 error("""\
130 error("""\
131 The profile module could not be found. It has been removed from the standard
131 The profile module could not be found. It has been removed from the standard
132 python packages because of its non-free license. To use profiling, install the
132 python packages because of its non-free license. To use profiling, install the
133 python-profiler package from non-free.""")
133 python-profiler package from non-free.""")
134
134
135 def default_option(self,fn,optstr):
135 def default_option(self,fn,optstr):
136 """Make an entry in the options_table for fn, with value optstr"""
136 """Make an entry in the options_table for fn, with value optstr"""
137
137
138 if fn not in self.lsmagic():
138 if fn not in self.lsmagic():
139 error("%s is not a magic function" % fn)
139 error("%s is not a magic function" % fn)
140 self.options_table[fn] = optstr
140 self.options_table[fn] = optstr
141
141
142 def lsmagic(self):
142 def lsmagic(self):
143 """Return a list of currently available magic functions.
143 """Return a list of currently available magic functions.
144
144
145 Gives a list of the bare names after mangling (['ls','cd', ...], not
145 Gives a list of the bare names after mangling (['ls','cd', ...], not
146 ['magic_ls','magic_cd',...]"""
146 ['magic_ls','magic_cd',...]"""
147
147
148 # FIXME. This needs a cleanup, in the way the magics list is built.
148 # FIXME. This needs a cleanup, in the way the magics list is built.
149
149
150 # magics in class definition
150 # magics in class definition
151 class_magic = lambda fn: fn.startswith('magic_') and \
151 class_magic = lambda fn: fn.startswith('magic_') and \
152 callable(Magic.__dict__[fn])
152 callable(Magic.__dict__[fn])
153 # in instance namespace (run-time user additions)
153 # in instance namespace (run-time user additions)
154 inst_magic = lambda fn: fn.startswith('magic_') and \
154 inst_magic = lambda fn: fn.startswith('magic_') and \
155 callable(self.__dict__[fn])
155 callable(self.__dict__[fn])
156 # and bound magics by user (so they can access self):
156 # and bound magics by user (so they can access self):
157 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
157 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
158 callable(self.__class__.__dict__[fn])
158 callable(self.__class__.__dict__[fn])
159 magics = filter(class_magic,Magic.__dict__.keys()) + \
159 magics = filter(class_magic,Magic.__dict__.keys()) + \
160 filter(inst_magic,self.__dict__.keys()) + \
160 filter(inst_magic,self.__dict__.keys()) + \
161 filter(inst_bound_magic,self.__class__.__dict__.keys())
161 filter(inst_bound_magic,self.__class__.__dict__.keys())
162 out = []
162 out = []
163 for fn in set(magics):
163 for fn in set(magics):
164 out.append(fn.replace('magic_','',1))
164 out.append(fn.replace('magic_','',1))
165 out.sort()
165 out.sort()
166 return out
166 return out
167
167
168 def extract_input_lines(self, range_str, raw=False):
168 def extract_input_lines(self, range_str, raw=False):
169 """Return as a string a set of input history slices.
169 """Return as a string a set of input history slices.
170
170
171 Inputs:
171 Inputs:
172
172
173 - range_str: the set of slices is given as a string, like
173 - range_str: the set of slices is given as a string, like
174 "~5/6-~4/2 4:8 9", since this function is for use by magic functions
174 "~5/6-~4/2 4:8 9", since this function is for use by magic functions
175 which get their arguments as strings. The number before the / is the
175 which get their arguments as strings. The number before the / is the
176 session number: ~n goes n back from the current session.
176 session number: ~n goes n back from the current session.
177
177
178 Optional inputs:
178 Optional inputs:
179
179
180 - raw(False): by default, the processed input is used. If this is
180 - raw(False): by default, the processed input is used. If this is
181 true, the raw input history is used instead.
181 true, the raw input history is used instead.
182
182
183 Note that slices can be called with two notations:
183 Note that slices can be called with two notations:
184
184
185 N:M -> standard python form, means including items N...(M-1).
185 N:M -> standard python form, means including items N...(M-1).
186
186
187 N-M -> include items N..M (closed endpoint)."""
187 N-M -> include items N..M (closed endpoint)."""
188 lines = self.shell.history_manager.\
188 lines = self.shell.history_manager.\
189 get_hist_from_rangestr(range_str, raw=raw)
189 get_range_by_str(range_str, raw=raw)
190 return "\n".join(x for _, _, x in lines)
190 return "\n".join(x for _, _, x in lines)
191
191
192 def arg_err(self,func):
192 def arg_err(self,func):
193 """Print docstring if incorrect arguments were passed"""
193 """Print docstring if incorrect arguments were passed"""
194 print 'Error in arguments:'
194 print 'Error in arguments:'
195 print oinspect.getdoc(func)
195 print oinspect.getdoc(func)
196
196
197 def format_latex(self,strng):
197 def format_latex(self,strng):
198 """Format a string for latex inclusion."""
198 """Format a string for latex inclusion."""
199
199
200 # Characters that need to be escaped for latex:
200 # Characters that need to be escaped for latex:
201 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
201 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
202 # Magic command names as headers:
202 # Magic command names as headers:
203 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
203 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
204 re.MULTILINE)
204 re.MULTILINE)
205 # Magic commands
205 # Magic commands
206 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
206 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
207 re.MULTILINE)
207 re.MULTILINE)
208 # Paragraph continue
208 # Paragraph continue
209 par_re = re.compile(r'\\$',re.MULTILINE)
209 par_re = re.compile(r'\\$',re.MULTILINE)
210
210
211 # The "\n" symbol
211 # The "\n" symbol
212 newline_re = re.compile(r'\\n')
212 newline_re = re.compile(r'\\n')
213
213
214 # Now build the string for output:
214 # Now build the string for output:
215 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
215 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
216 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
216 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
217 strng)
217 strng)
218 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
218 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
219 strng = par_re.sub(r'\\\\',strng)
219 strng = par_re.sub(r'\\\\',strng)
220 strng = escape_re.sub(r'\\\1',strng)
220 strng = escape_re.sub(r'\\\1',strng)
221 strng = newline_re.sub(r'\\textbackslash{}n',strng)
221 strng = newline_re.sub(r'\\textbackslash{}n',strng)
222 return strng
222 return strng
223
223
224 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
224 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
225 """Parse options passed to an argument string.
225 """Parse options passed to an argument string.
226
226
227 The interface is similar to that of getopt(), but it returns back a
227 The interface is similar to that of getopt(), but it returns back a
228 Struct with the options as keys and the stripped argument string still
228 Struct with the options as keys and the stripped argument string still
229 as a string.
229 as a string.
230
230
231 arg_str is quoted as a true sys.argv vector by using shlex.split.
231 arg_str is quoted as a true sys.argv vector by using shlex.split.
232 This allows us to easily expand variables, glob files, quote
232 This allows us to easily expand variables, glob files, quote
233 arguments, etc.
233 arguments, etc.
234
234
235 Options:
235 Options:
236 -mode: default 'string'. If given as 'list', the argument string is
236 -mode: default 'string'. If given as 'list', the argument string is
237 returned as a list (split on whitespace) instead of a string.
237 returned as a list (split on whitespace) instead of a string.
238
238
239 -list_all: put all option values in lists. Normally only options
239 -list_all: put all option values in lists. Normally only options
240 appearing more than once are put in a list.
240 appearing more than once are put in a list.
241
241
242 -posix (True): whether to split the input line in POSIX mode or not,
242 -posix (True): whether to split the input line in POSIX mode or not,
243 as per the conventions outlined in the shlex module from the
243 as per the conventions outlined in the shlex module from the
244 standard library."""
244 standard library."""
245
245
246 # inject default options at the beginning of the input line
246 # inject default options at the beginning of the input line
247 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
247 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
248 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
248 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
249
249
250 mode = kw.get('mode','string')
250 mode = kw.get('mode','string')
251 if mode not in ['string','list']:
251 if mode not in ['string','list']:
252 raise ValueError,'incorrect mode given: %s' % mode
252 raise ValueError,'incorrect mode given: %s' % mode
253 # Get options
253 # Get options
254 list_all = kw.get('list_all',0)
254 list_all = kw.get('list_all',0)
255 posix = kw.get('posix', os.name == 'posix')
255 posix = kw.get('posix', os.name == 'posix')
256
256
257 # Check if we have more than one argument to warrant extra processing:
257 # Check if we have more than one argument to warrant extra processing:
258 odict = {} # Dictionary with options
258 odict = {} # Dictionary with options
259 args = arg_str.split()
259 args = arg_str.split()
260 if len(args) >= 1:
260 if len(args) >= 1:
261 # If the list of inputs only has 0 or 1 thing in it, there's no
261 # If the list of inputs only has 0 or 1 thing in it, there's no
262 # need to look for options
262 # need to look for options
263 argv = arg_split(arg_str,posix)
263 argv = arg_split(arg_str,posix)
264 # Do regular option processing
264 # Do regular option processing
265 try:
265 try:
266 opts,args = getopt(argv,opt_str,*long_opts)
266 opts,args = getopt(argv,opt_str,*long_opts)
267 except GetoptError,e:
267 except GetoptError,e:
268 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
268 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
269 " ".join(long_opts)))
269 " ".join(long_opts)))
270 for o,a in opts:
270 for o,a in opts:
271 if o.startswith('--'):
271 if o.startswith('--'):
272 o = o[2:]
272 o = o[2:]
273 else:
273 else:
274 o = o[1:]
274 o = o[1:]
275 try:
275 try:
276 odict[o].append(a)
276 odict[o].append(a)
277 except AttributeError:
277 except AttributeError:
278 odict[o] = [odict[o],a]
278 odict[o] = [odict[o],a]
279 except KeyError:
279 except KeyError:
280 if list_all:
280 if list_all:
281 odict[o] = [a]
281 odict[o] = [a]
282 else:
282 else:
283 odict[o] = a
283 odict[o] = a
284
284
285 # Prepare opts,args for return
285 # Prepare opts,args for return
286 opts = Struct(odict)
286 opts = Struct(odict)
287 if mode == 'string':
287 if mode == 'string':
288 args = ' '.join(args)
288 args = ' '.join(args)
289
289
290 return opts,args
290 return opts,args
291
291
292 #......................................................................
292 #......................................................................
293 # And now the actual magic functions
293 # And now the actual magic functions
294
294
295 # Functions for IPython shell work (vars,funcs, config, etc)
295 # Functions for IPython shell work (vars,funcs, config, etc)
296 def magic_lsmagic(self, parameter_s = ''):
296 def magic_lsmagic(self, parameter_s = ''):
297 """List currently available magic functions."""
297 """List currently available magic functions."""
298 mesc = ESC_MAGIC
298 mesc = ESC_MAGIC
299 print 'Available magic functions:\n'+mesc+\
299 print 'Available magic functions:\n'+mesc+\
300 (' '+mesc).join(self.lsmagic())
300 (' '+mesc).join(self.lsmagic())
301 print '\n' + Magic.auto_status[self.shell.automagic]
301 print '\n' + Magic.auto_status[self.shell.automagic]
302 return None
302 return None
303
303
304 def magic_magic(self, parameter_s = ''):
304 def magic_magic(self, parameter_s = ''):
305 """Print information about the magic function system.
305 """Print information about the magic function system.
306
306
307 Supported formats: -latex, -brief, -rest
307 Supported formats: -latex, -brief, -rest
308 """
308 """
309
309
310 mode = ''
310 mode = ''
311 try:
311 try:
312 if parameter_s.split()[0] == '-latex':
312 if parameter_s.split()[0] == '-latex':
313 mode = 'latex'
313 mode = 'latex'
314 if parameter_s.split()[0] == '-brief':
314 if parameter_s.split()[0] == '-brief':
315 mode = 'brief'
315 mode = 'brief'
316 if parameter_s.split()[0] == '-rest':
316 if parameter_s.split()[0] == '-rest':
317 mode = 'rest'
317 mode = 'rest'
318 rest_docs = []
318 rest_docs = []
319 except:
319 except:
320 pass
320 pass
321
321
322 magic_docs = []
322 magic_docs = []
323 for fname in self.lsmagic():
323 for fname in self.lsmagic():
324 mname = 'magic_' + fname
324 mname = 'magic_' + fname
325 for space in (Magic,self,self.__class__):
325 for space in (Magic,self,self.__class__):
326 try:
326 try:
327 fn = space.__dict__[mname]
327 fn = space.__dict__[mname]
328 except KeyError:
328 except KeyError:
329 pass
329 pass
330 else:
330 else:
331 break
331 break
332 if mode == 'brief':
332 if mode == 'brief':
333 # only first line
333 # only first line
334 if fn.__doc__:
334 if fn.__doc__:
335 fndoc = fn.__doc__.split('\n',1)[0]
335 fndoc = fn.__doc__.split('\n',1)[0]
336 else:
336 else:
337 fndoc = 'No documentation'
337 fndoc = 'No documentation'
338 else:
338 else:
339 if fn.__doc__:
339 if fn.__doc__:
340 fndoc = fn.__doc__.rstrip()
340 fndoc = fn.__doc__.rstrip()
341 else:
341 else:
342 fndoc = 'No documentation'
342 fndoc = 'No documentation'
343
343
344
344
345 if mode == 'rest':
345 if mode == 'rest':
346 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
346 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
347 fname,fndoc))
347 fname,fndoc))
348
348
349 else:
349 else:
350 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
350 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
351 fname,fndoc))
351 fname,fndoc))
352
352
353 magic_docs = ''.join(magic_docs)
353 magic_docs = ''.join(magic_docs)
354
354
355 if mode == 'rest':
355 if mode == 'rest':
356 return "".join(rest_docs)
356 return "".join(rest_docs)
357
357
358 if mode == 'latex':
358 if mode == 'latex':
359 print self.format_latex(magic_docs)
359 print self.format_latex(magic_docs)
360 return
360 return
361 else:
361 else:
362 magic_docs = format_screen(magic_docs)
362 magic_docs = format_screen(magic_docs)
363 if mode == 'brief':
363 if mode == 'brief':
364 return magic_docs
364 return magic_docs
365
365
366 outmsg = """
366 outmsg = """
367 IPython's 'magic' functions
367 IPython's 'magic' functions
368 ===========================
368 ===========================
369
369
370 The magic function system provides a series of functions which allow you to
370 The magic function system provides a series of functions which allow you to
371 control the behavior of IPython itself, plus a lot of system-type
371 control the behavior of IPython itself, plus a lot of system-type
372 features. All these functions are prefixed with a % character, but parameters
372 features. All these functions are prefixed with a % character, but parameters
373 are given without parentheses or quotes.
373 are given without parentheses or quotes.
374
374
375 NOTE: If you have 'automagic' enabled (via the command line option or with the
375 NOTE: If you have 'automagic' enabled (via the command line option or with the
376 %automagic function), you don't need to type in the % explicitly. By default,
376 %automagic function), you don't need to type in the % explicitly. By default,
377 IPython ships with automagic on, so you should only rarely need the % escape.
377 IPython ships with automagic on, so you should only rarely need the % escape.
378
378
379 Example: typing '%cd mydir' (without the quotes) changes you working directory
379 Example: typing '%cd mydir' (without the quotes) changes you working directory
380 to 'mydir', if it exists.
380 to 'mydir', if it exists.
381
381
382 You can define your own magic functions to extend the system. See the supplied
382 You can define your own magic functions to extend the system. See the supplied
383 ipythonrc and example-magic.py files for details (in your ipython
383 ipythonrc and example-magic.py files for details (in your ipython
384 configuration directory, typically $HOME/.config/ipython on Linux or $HOME/.ipython elsewhere).
384 configuration directory, typically $HOME/.config/ipython on Linux or $HOME/.ipython elsewhere).
385
385
386 You can also define your own aliased names for magic functions. In your
386 You can also define your own aliased names for magic functions. In your
387 ipythonrc file, placing a line like:
387 ipythonrc file, placing a line like:
388
388
389 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
389 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
390
390
391 will define %pf as a new name for %profile.
391 will define %pf as a new name for %profile.
392
392
393 You can also call magics in code using the magic() function, which IPython
393 You can also call magics in code using the magic() function, which IPython
394 automatically adds to the builtin namespace. Type 'magic?' for details.
394 automatically adds to the builtin namespace. Type 'magic?' for details.
395
395
396 For a list of the available magic functions, use %lsmagic. For a description
396 For a list of the available magic functions, use %lsmagic. For a description
397 of any of them, type %magic_name?, e.g. '%cd?'.
397 of any of them, type %magic_name?, e.g. '%cd?'.
398
398
399 Currently the magic system has the following functions:\n"""
399 Currently the magic system has the following functions:\n"""
400
400
401 mesc = ESC_MAGIC
401 mesc = ESC_MAGIC
402 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
402 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
403 "\n\n%s%s\n\n%s" % (outmsg,
403 "\n\n%s%s\n\n%s" % (outmsg,
404 magic_docs,mesc,mesc,
404 magic_docs,mesc,mesc,
405 (' '+mesc).join(self.lsmagic()),
405 (' '+mesc).join(self.lsmagic()),
406 Magic.auto_status[self.shell.automagic] ) )
406 Magic.auto_status[self.shell.automagic] ) )
407 page.page(outmsg)
407 page.page(outmsg)
408
408
409 def magic_automagic(self, parameter_s = ''):
409 def magic_automagic(self, parameter_s = ''):
410 """Make magic functions callable without having to type the initial %.
410 """Make magic functions callable without having to type the initial %.
411
411
412 Without argumentsl toggles on/off (when off, you must call it as
412 Without argumentsl toggles on/off (when off, you must call it as
413 %automagic, of course). With arguments it sets the value, and you can
413 %automagic, of course). With arguments it sets the value, and you can
414 use any of (case insensitive):
414 use any of (case insensitive):
415
415
416 - on,1,True: to activate
416 - on,1,True: to activate
417
417
418 - off,0,False: to deactivate.
418 - off,0,False: to deactivate.
419
419
420 Note that magic functions have lowest priority, so if there's a
420 Note that magic functions have lowest priority, so if there's a
421 variable whose name collides with that of a magic fn, automagic won't
421 variable whose name collides with that of a magic fn, automagic won't
422 work for that function (you get the variable instead). However, if you
422 work for that function (you get the variable instead). However, if you
423 delete the variable (del var), the previously shadowed magic function
423 delete the variable (del var), the previously shadowed magic function
424 becomes visible to automagic again."""
424 becomes visible to automagic again."""
425
425
426 arg = parameter_s.lower()
426 arg = parameter_s.lower()
427 if parameter_s in ('on','1','true'):
427 if parameter_s in ('on','1','true'):
428 self.shell.automagic = True
428 self.shell.automagic = True
429 elif parameter_s in ('off','0','false'):
429 elif parameter_s in ('off','0','false'):
430 self.shell.automagic = False
430 self.shell.automagic = False
431 else:
431 else:
432 self.shell.automagic = not self.shell.automagic
432 self.shell.automagic = not self.shell.automagic
433 print '\n' + Magic.auto_status[self.shell.automagic]
433 print '\n' + Magic.auto_status[self.shell.automagic]
434
434
435 @testdec.skip_doctest
435 @testdec.skip_doctest
436 def magic_autocall(self, parameter_s = ''):
436 def magic_autocall(self, parameter_s = ''):
437 """Make functions callable without having to type parentheses.
437 """Make functions callable without having to type parentheses.
438
438
439 Usage:
439 Usage:
440
440
441 %autocall [mode]
441 %autocall [mode]
442
442
443 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
443 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
444 value is toggled on and off (remembering the previous state).
444 value is toggled on and off (remembering the previous state).
445
445
446 In more detail, these values mean:
446 In more detail, these values mean:
447
447
448 0 -> fully disabled
448 0 -> fully disabled
449
449
450 1 -> active, but do not apply if there are no arguments on the line.
450 1 -> active, but do not apply if there are no arguments on the line.
451
451
452 In this mode, you get:
452 In this mode, you get:
453
453
454 In [1]: callable
454 In [1]: callable
455 Out[1]: <built-in function callable>
455 Out[1]: <built-in function callable>
456
456
457 In [2]: callable 'hello'
457 In [2]: callable 'hello'
458 ------> callable('hello')
458 ------> callable('hello')
459 Out[2]: False
459 Out[2]: False
460
460
461 2 -> Active always. Even if no arguments are present, the callable
461 2 -> Active always. Even if no arguments are present, the callable
462 object is called:
462 object is called:
463
463
464 In [2]: float
464 In [2]: float
465 ------> float()
465 ------> float()
466 Out[2]: 0.0
466 Out[2]: 0.0
467
467
468 Note that even with autocall off, you can still use '/' at the start of
468 Note that even with autocall off, you can still use '/' at the start of
469 a line to treat the first argument on the command line as a function
469 a line to treat the first argument on the command line as a function
470 and add parentheses to it:
470 and add parentheses to it:
471
471
472 In [8]: /str 43
472 In [8]: /str 43
473 ------> str(43)
473 ------> str(43)
474 Out[8]: '43'
474 Out[8]: '43'
475
475
476 # all-random (note for auto-testing)
476 # all-random (note for auto-testing)
477 """
477 """
478
478
479 if parameter_s:
479 if parameter_s:
480 arg = int(parameter_s)
480 arg = int(parameter_s)
481 else:
481 else:
482 arg = 'toggle'
482 arg = 'toggle'
483
483
484 if not arg in (0,1,2,'toggle'):
484 if not arg in (0,1,2,'toggle'):
485 error('Valid modes: (0->Off, 1->Smart, 2->Full')
485 error('Valid modes: (0->Off, 1->Smart, 2->Full')
486 return
486 return
487
487
488 if arg in (0,1,2):
488 if arg in (0,1,2):
489 self.shell.autocall = arg
489 self.shell.autocall = arg
490 else: # toggle
490 else: # toggle
491 if self.shell.autocall:
491 if self.shell.autocall:
492 self._magic_state.autocall_save = self.shell.autocall
492 self._magic_state.autocall_save = self.shell.autocall
493 self.shell.autocall = 0
493 self.shell.autocall = 0
494 else:
494 else:
495 try:
495 try:
496 self.shell.autocall = self._magic_state.autocall_save
496 self.shell.autocall = self._magic_state.autocall_save
497 except AttributeError:
497 except AttributeError:
498 self.shell.autocall = self._magic_state.autocall_save = 1
498 self.shell.autocall = self._magic_state.autocall_save = 1
499
499
500 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
500 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
501
501
502
502
503 def magic_page(self, parameter_s=''):
503 def magic_page(self, parameter_s=''):
504 """Pretty print the object and display it through a pager.
504 """Pretty print the object and display it through a pager.
505
505
506 %page [options] OBJECT
506 %page [options] OBJECT
507
507
508 If no object is given, use _ (last output).
508 If no object is given, use _ (last output).
509
509
510 Options:
510 Options:
511
511
512 -r: page str(object), don't pretty-print it."""
512 -r: page str(object), don't pretty-print it."""
513
513
514 # After a function contributed by Olivier Aubert, slightly modified.
514 # After a function contributed by Olivier Aubert, slightly modified.
515
515
516 # Process options/args
516 # Process options/args
517 opts,args = self.parse_options(parameter_s,'r')
517 opts,args = self.parse_options(parameter_s,'r')
518 raw = 'r' in opts
518 raw = 'r' in opts
519
519
520 oname = args and args or '_'
520 oname = args and args or '_'
521 info = self._ofind(oname)
521 info = self._ofind(oname)
522 if info['found']:
522 if info['found']:
523 txt = (raw and str or pformat)( info['obj'] )
523 txt = (raw and str or pformat)( info['obj'] )
524 page.page(txt)
524 page.page(txt)
525 else:
525 else:
526 print 'Object `%s` not found' % oname
526 print 'Object `%s` not found' % oname
527
527
528 def magic_profile(self, parameter_s=''):
528 def magic_profile(self, parameter_s=''):
529 """Print your currently active IPython profile."""
529 """Print your currently active IPython profile."""
530 if self.shell.profile:
530 if self.shell.profile:
531 printpl('Current IPython profile: $self.shell.profile.')
531 printpl('Current IPython profile: $self.shell.profile.')
532 else:
532 else:
533 print 'No profile active.'
533 print 'No profile active.'
534
534
535 def magic_pinfo(self, parameter_s='', namespaces=None):
535 def magic_pinfo(self, parameter_s='', namespaces=None):
536 """Provide detailed information about an object.
536 """Provide detailed information about an object.
537
537
538 '%pinfo object' is just a synonym for object? or ?object."""
538 '%pinfo object' is just a synonym for object? or ?object."""
539
539
540 #print 'pinfo par: <%s>' % parameter_s # dbg
540 #print 'pinfo par: <%s>' % parameter_s # dbg
541
541
542
542
543 # detail_level: 0 -> obj? , 1 -> obj??
543 # detail_level: 0 -> obj? , 1 -> obj??
544 detail_level = 0
544 detail_level = 0
545 # We need to detect if we got called as 'pinfo pinfo foo', which can
545 # We need to detect if we got called as 'pinfo pinfo foo', which can
546 # happen if the user types 'pinfo foo?' at the cmd line.
546 # happen if the user types 'pinfo foo?' at the cmd line.
547 pinfo,qmark1,oname,qmark2 = \
547 pinfo,qmark1,oname,qmark2 = \
548 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
548 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
549 if pinfo or qmark1 or qmark2:
549 if pinfo or qmark1 or qmark2:
550 detail_level = 1
550 detail_level = 1
551 if "*" in oname:
551 if "*" in oname:
552 self.magic_psearch(oname)
552 self.magic_psearch(oname)
553 else:
553 else:
554 self.shell._inspect('pinfo', oname, detail_level=detail_level,
554 self.shell._inspect('pinfo', oname, detail_level=detail_level,
555 namespaces=namespaces)
555 namespaces=namespaces)
556
556
557 def magic_pinfo2(self, parameter_s='', namespaces=None):
557 def magic_pinfo2(self, parameter_s='', namespaces=None):
558 """Provide extra detailed information about an object.
558 """Provide extra detailed information about an object.
559
559
560 '%pinfo2 object' is just a synonym for object?? or ??object."""
560 '%pinfo2 object' is just a synonym for object?? or ??object."""
561 self.shell._inspect('pinfo', parameter_s, detail_level=1,
561 self.shell._inspect('pinfo', parameter_s, detail_level=1,
562 namespaces=namespaces)
562 namespaces=namespaces)
563
563
564 @testdec.skip_doctest
564 @testdec.skip_doctest
565 def magic_pdef(self, parameter_s='', namespaces=None):
565 def magic_pdef(self, parameter_s='', namespaces=None):
566 """Print the definition header for any callable object.
566 """Print the definition header for any callable object.
567
567
568 If the object is a class, print the constructor information.
568 If the object is a class, print the constructor information.
569
569
570 Examples
570 Examples
571 --------
571 --------
572 ::
572 ::
573
573
574 In [3]: %pdef urllib.urlopen
574 In [3]: %pdef urllib.urlopen
575 urllib.urlopen(url, data=None, proxies=None)
575 urllib.urlopen(url, data=None, proxies=None)
576 """
576 """
577 self._inspect('pdef',parameter_s, namespaces)
577 self._inspect('pdef',parameter_s, namespaces)
578
578
579 def magic_pdoc(self, parameter_s='', namespaces=None):
579 def magic_pdoc(self, parameter_s='', namespaces=None):
580 """Print the docstring for an object.
580 """Print the docstring for an object.
581
581
582 If the given object is a class, it will print both the class and the
582 If the given object is a class, it will print both the class and the
583 constructor docstrings."""
583 constructor docstrings."""
584 self._inspect('pdoc',parameter_s, namespaces)
584 self._inspect('pdoc',parameter_s, namespaces)
585
585
586 def magic_psource(self, parameter_s='', namespaces=None):
586 def magic_psource(self, parameter_s='', namespaces=None):
587 """Print (or run through pager) the source code for an object."""
587 """Print (or run through pager) the source code for an object."""
588 self._inspect('psource',parameter_s, namespaces)
588 self._inspect('psource',parameter_s, namespaces)
589
589
590 def magic_pfile(self, parameter_s=''):
590 def magic_pfile(self, parameter_s=''):
591 """Print (or run through pager) the file where an object is defined.
591 """Print (or run through pager) the file where an object is defined.
592
592
593 The file opens at the line where the object definition begins. IPython
593 The file opens at the line where the object definition begins. IPython
594 will honor the environment variable PAGER if set, and otherwise will
594 will honor the environment variable PAGER if set, and otherwise will
595 do its best to print the file in a convenient form.
595 do its best to print the file in a convenient form.
596
596
597 If the given argument is not an object currently defined, IPython will
597 If the given argument is not an object currently defined, IPython will
598 try to interpret it as a filename (automatically adding a .py extension
598 try to interpret it as a filename (automatically adding a .py extension
599 if needed). You can thus use %pfile as a syntax highlighting code
599 if needed). You can thus use %pfile as a syntax highlighting code
600 viewer."""
600 viewer."""
601
601
602 # first interpret argument as an object name
602 # first interpret argument as an object name
603 out = self._inspect('pfile',parameter_s)
603 out = self._inspect('pfile',parameter_s)
604 # if not, try the input as a filename
604 # if not, try the input as a filename
605 if out == 'not found':
605 if out == 'not found':
606 try:
606 try:
607 filename = get_py_filename(parameter_s)
607 filename = get_py_filename(parameter_s)
608 except IOError,msg:
608 except IOError,msg:
609 print msg
609 print msg
610 return
610 return
611 page.page(self.shell.inspector.format(file(filename).read()))
611 page.page(self.shell.inspector.format(file(filename).read()))
612
612
613 def magic_psearch(self, parameter_s=''):
613 def magic_psearch(self, parameter_s=''):
614 """Search for object in namespaces by wildcard.
614 """Search for object in namespaces by wildcard.
615
615
616 %psearch [options] PATTERN [OBJECT TYPE]
616 %psearch [options] PATTERN [OBJECT TYPE]
617
617
618 Note: ? can be used as a synonym for %psearch, at the beginning or at
618 Note: ? can be used as a synonym for %psearch, at the beginning or at
619 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
619 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
620 rest of the command line must be unchanged (options come first), so
620 rest of the command line must be unchanged (options come first), so
621 for example the following forms are equivalent
621 for example the following forms are equivalent
622
622
623 %psearch -i a* function
623 %psearch -i a* function
624 -i a* function?
624 -i a* function?
625 ?-i a* function
625 ?-i a* function
626
626
627 Arguments:
627 Arguments:
628
628
629 PATTERN
629 PATTERN
630
630
631 where PATTERN is a string containing * as a wildcard similar to its
631 where PATTERN is a string containing * as a wildcard similar to its
632 use in a shell. The pattern is matched in all namespaces on the
632 use in a shell. The pattern is matched in all namespaces on the
633 search path. By default objects starting with a single _ are not
633 search path. By default objects starting with a single _ are not
634 matched, many IPython generated objects have a single
634 matched, many IPython generated objects have a single
635 underscore. The default is case insensitive matching. Matching is
635 underscore. The default is case insensitive matching. Matching is
636 also done on the attributes of objects and not only on the objects
636 also done on the attributes of objects and not only on the objects
637 in a module.
637 in a module.
638
638
639 [OBJECT TYPE]
639 [OBJECT TYPE]
640
640
641 Is the name of a python type from the types module. The name is
641 Is the name of a python type from the types module. The name is
642 given in lowercase without the ending type, ex. StringType is
642 given in lowercase without the ending type, ex. StringType is
643 written string. By adding a type here only objects matching the
643 written string. By adding a type here only objects matching the
644 given type are matched. Using all here makes the pattern match all
644 given type are matched. Using all here makes the pattern match all
645 types (this is the default).
645 types (this is the default).
646
646
647 Options:
647 Options:
648
648
649 -a: makes the pattern match even objects whose names start with a
649 -a: makes the pattern match even objects whose names start with a
650 single underscore. These names are normally ommitted from the
650 single underscore. These names are normally ommitted from the
651 search.
651 search.
652
652
653 -i/-c: make the pattern case insensitive/sensitive. If neither of
653 -i/-c: make the pattern case insensitive/sensitive. If neither of
654 these options is given, the default is read from your ipythonrc
654 these options is given, the default is read from your ipythonrc
655 file. The option name which sets this value is
655 file. The option name which sets this value is
656 'wildcards_case_sensitive'. If this option is not specified in your
656 'wildcards_case_sensitive'. If this option is not specified in your
657 ipythonrc file, IPython's internal default is to do a case sensitive
657 ipythonrc file, IPython's internal default is to do a case sensitive
658 search.
658 search.
659
659
660 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
660 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
661 specifiy can be searched in any of the following namespaces:
661 specifiy can be searched in any of the following namespaces:
662 'builtin', 'user', 'user_global','internal', 'alias', where
662 'builtin', 'user', 'user_global','internal', 'alias', where
663 'builtin' and 'user' are the search defaults. Note that you should
663 'builtin' and 'user' are the search defaults. Note that you should
664 not use quotes when specifying namespaces.
664 not use quotes when specifying namespaces.
665
665
666 'Builtin' contains the python module builtin, 'user' contains all
666 'Builtin' contains the python module builtin, 'user' contains all
667 user data, 'alias' only contain the shell aliases and no python
667 user data, 'alias' only contain the shell aliases and no python
668 objects, 'internal' contains objects used by IPython. The
668 objects, 'internal' contains objects used by IPython. The
669 'user_global' namespace is only used by embedded IPython instances,
669 'user_global' namespace is only used by embedded IPython instances,
670 and it contains module-level globals. You can add namespaces to the
670 and it contains module-level globals. You can add namespaces to the
671 search with -s or exclude them with -e (these options can be given
671 search with -s or exclude them with -e (these options can be given
672 more than once).
672 more than once).
673
673
674 Examples:
674 Examples:
675
675
676 %psearch a* -> objects beginning with an a
676 %psearch a* -> objects beginning with an a
677 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
677 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
678 %psearch a* function -> all functions beginning with an a
678 %psearch a* function -> all functions beginning with an a
679 %psearch re.e* -> objects beginning with an e in module re
679 %psearch re.e* -> objects beginning with an e in module re
680 %psearch r*.e* -> objects that start with e in modules starting in r
680 %psearch r*.e* -> objects that start with e in modules starting in r
681 %psearch r*.* string -> all strings in modules beginning with r
681 %psearch r*.* string -> all strings in modules beginning with r
682
682
683 Case sensitve search:
683 Case sensitve search:
684
684
685 %psearch -c a* list all object beginning with lower case a
685 %psearch -c a* list all object beginning with lower case a
686
686
687 Show objects beginning with a single _:
687 Show objects beginning with a single _:
688
688
689 %psearch -a _* list objects beginning with a single underscore"""
689 %psearch -a _* list objects beginning with a single underscore"""
690 try:
690 try:
691 parameter_s = parameter_s.encode('ascii')
691 parameter_s = parameter_s.encode('ascii')
692 except UnicodeEncodeError:
692 except UnicodeEncodeError:
693 print 'Python identifiers can only contain ascii characters.'
693 print 'Python identifiers can only contain ascii characters.'
694 return
694 return
695
695
696 # default namespaces to be searched
696 # default namespaces to be searched
697 def_search = ['user','builtin']
697 def_search = ['user','builtin']
698
698
699 # Process options/args
699 # Process options/args
700 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
700 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
701 opt = opts.get
701 opt = opts.get
702 shell = self.shell
702 shell = self.shell
703 psearch = shell.inspector.psearch
703 psearch = shell.inspector.psearch
704
704
705 # select case options
705 # select case options
706 if opts.has_key('i'):
706 if opts.has_key('i'):
707 ignore_case = True
707 ignore_case = True
708 elif opts.has_key('c'):
708 elif opts.has_key('c'):
709 ignore_case = False
709 ignore_case = False
710 else:
710 else:
711 ignore_case = not shell.wildcards_case_sensitive
711 ignore_case = not shell.wildcards_case_sensitive
712
712
713 # Build list of namespaces to search from user options
713 # Build list of namespaces to search from user options
714 def_search.extend(opt('s',[]))
714 def_search.extend(opt('s',[]))
715 ns_exclude = ns_exclude=opt('e',[])
715 ns_exclude = ns_exclude=opt('e',[])
716 ns_search = [nm for nm in def_search if nm not in ns_exclude]
716 ns_search = [nm for nm in def_search if nm not in ns_exclude]
717
717
718 # Call the actual search
718 # Call the actual search
719 try:
719 try:
720 psearch(args,shell.ns_table,ns_search,
720 psearch(args,shell.ns_table,ns_search,
721 show_all=opt('a'),ignore_case=ignore_case)
721 show_all=opt('a'),ignore_case=ignore_case)
722 except:
722 except:
723 shell.showtraceback()
723 shell.showtraceback()
724
724
725 @testdec.skip_doctest
725 @testdec.skip_doctest
726 def magic_who_ls(self, parameter_s=''):
726 def magic_who_ls(self, parameter_s=''):
727 """Return a sorted list of all interactive variables.
727 """Return a sorted list of all interactive variables.
728
728
729 If arguments are given, only variables of types matching these
729 If arguments are given, only variables of types matching these
730 arguments are returned.
730 arguments are returned.
731
731
732 Examples
732 Examples
733 --------
733 --------
734
734
735 Define two variables and list them with who_ls::
735 Define two variables and list them with who_ls::
736
736
737 In [1]: alpha = 123
737 In [1]: alpha = 123
738
738
739 In [2]: beta = 'test'
739 In [2]: beta = 'test'
740
740
741 In [3]: %who_ls
741 In [3]: %who_ls
742 Out[3]: ['alpha', 'beta']
742 Out[3]: ['alpha', 'beta']
743
743
744 In [4]: %who_ls int
744 In [4]: %who_ls int
745 Out[4]: ['alpha']
745 Out[4]: ['alpha']
746
746
747 In [5]: %who_ls str
747 In [5]: %who_ls str
748 Out[5]: ['beta']
748 Out[5]: ['beta']
749 """
749 """
750
750
751 user_ns = self.shell.user_ns
751 user_ns = self.shell.user_ns
752 internal_ns = self.shell.internal_ns
752 internal_ns = self.shell.internal_ns
753 user_ns_hidden = self.shell.user_ns_hidden
753 user_ns_hidden = self.shell.user_ns_hidden
754 out = [ i for i in user_ns
754 out = [ i for i in user_ns
755 if not i.startswith('_') \
755 if not i.startswith('_') \
756 and not (i in internal_ns or i in user_ns_hidden) ]
756 and not (i in internal_ns or i in user_ns_hidden) ]
757
757
758 typelist = parameter_s.split()
758 typelist = parameter_s.split()
759 if typelist:
759 if typelist:
760 typeset = set(typelist)
760 typeset = set(typelist)
761 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
761 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
762
762
763 out.sort()
763 out.sort()
764 return out
764 return out
765
765
766 @testdec.skip_doctest
766 @testdec.skip_doctest
767 def magic_who(self, parameter_s=''):
767 def magic_who(self, parameter_s=''):
768 """Print all interactive variables, with some minimal formatting.
768 """Print all interactive variables, with some minimal formatting.
769
769
770 If any arguments are given, only variables whose type matches one of
770 If any arguments are given, only variables whose type matches one of
771 these are printed. For example:
771 these are printed. For example:
772
772
773 %who function str
773 %who function str
774
774
775 will only list functions and strings, excluding all other types of
775 will only list functions and strings, excluding all other types of
776 variables. To find the proper type names, simply use type(var) at a
776 variables. To find the proper type names, simply use type(var) at a
777 command line to see how python prints type names. For example:
777 command line to see how python prints type names. For example:
778
778
779 In [1]: type('hello')\\
779 In [1]: type('hello')\\
780 Out[1]: <type 'str'>
780 Out[1]: <type 'str'>
781
781
782 indicates that the type name for strings is 'str'.
782 indicates that the type name for strings is 'str'.
783
783
784 %who always excludes executed names loaded through your configuration
784 %who always excludes executed names loaded through your configuration
785 file and things which are internal to IPython.
785 file and things which are internal to IPython.
786
786
787 This is deliberate, as typically you may load many modules and the
787 This is deliberate, as typically you may load many modules and the
788 purpose of %who is to show you only what you've manually defined.
788 purpose of %who is to show you only what you've manually defined.
789
789
790 Examples
790 Examples
791 --------
791 --------
792
792
793 Define two variables and list them with who::
793 Define two variables and list them with who::
794
794
795 In [1]: alpha = 123
795 In [1]: alpha = 123
796
796
797 In [2]: beta = 'test'
797 In [2]: beta = 'test'
798
798
799 In [3]: %who
799 In [3]: %who
800 alpha beta
800 alpha beta
801
801
802 In [4]: %who int
802 In [4]: %who int
803 alpha
803 alpha
804
804
805 In [5]: %who str
805 In [5]: %who str
806 beta
806 beta
807 """
807 """
808
808
809 varlist = self.magic_who_ls(parameter_s)
809 varlist = self.magic_who_ls(parameter_s)
810 if not varlist:
810 if not varlist:
811 if parameter_s:
811 if parameter_s:
812 print 'No variables match your requested type.'
812 print 'No variables match your requested type.'
813 else:
813 else:
814 print 'Interactive namespace is empty.'
814 print 'Interactive namespace is empty.'
815 return
815 return
816
816
817 # if we have variables, move on...
817 # if we have variables, move on...
818 count = 0
818 count = 0
819 for i in varlist:
819 for i in varlist:
820 print i+'\t',
820 print i+'\t',
821 count += 1
821 count += 1
822 if count > 8:
822 if count > 8:
823 count = 0
823 count = 0
824 print
824 print
825 print
825 print
826
826
827 @testdec.skip_doctest
827 @testdec.skip_doctest
828 def magic_whos(self, parameter_s=''):
828 def magic_whos(self, parameter_s=''):
829 """Like %who, but gives some extra information about each variable.
829 """Like %who, but gives some extra information about each variable.
830
830
831 The same type filtering of %who can be applied here.
831 The same type filtering of %who can be applied here.
832
832
833 For all variables, the type is printed. Additionally it prints:
833 For all variables, the type is printed. Additionally it prints:
834
834
835 - For {},[],(): their length.
835 - For {},[],(): their length.
836
836
837 - For numpy and Numeric arrays, a summary with shape, number of
837 - For numpy and Numeric arrays, a summary with shape, number of
838 elements, typecode and size in memory.
838 elements, typecode and size in memory.
839
839
840 - Everything else: a string representation, snipping their middle if
840 - Everything else: a string representation, snipping their middle if
841 too long.
841 too long.
842
842
843 Examples
843 Examples
844 --------
844 --------
845
845
846 Define two variables and list them with whos::
846 Define two variables and list them with whos::
847
847
848 In [1]: alpha = 123
848 In [1]: alpha = 123
849
849
850 In [2]: beta = 'test'
850 In [2]: beta = 'test'
851
851
852 In [3]: %whos
852 In [3]: %whos
853 Variable Type Data/Info
853 Variable Type Data/Info
854 --------------------------------
854 --------------------------------
855 alpha int 123
855 alpha int 123
856 beta str test
856 beta str test
857 """
857 """
858
858
859 varnames = self.magic_who_ls(parameter_s)
859 varnames = self.magic_who_ls(parameter_s)
860 if not varnames:
860 if not varnames:
861 if parameter_s:
861 if parameter_s:
862 print 'No variables match your requested type.'
862 print 'No variables match your requested type.'
863 else:
863 else:
864 print 'Interactive namespace is empty.'
864 print 'Interactive namespace is empty.'
865 return
865 return
866
866
867 # if we have variables, move on...
867 # if we have variables, move on...
868
868
869 # for these types, show len() instead of data:
869 # for these types, show len() instead of data:
870 seq_types = [types.DictType,types.ListType,types.TupleType]
870 seq_types = [types.DictType,types.ListType,types.TupleType]
871
871
872 # for numpy/Numeric arrays, display summary info
872 # for numpy/Numeric arrays, display summary info
873 try:
873 try:
874 import numpy
874 import numpy
875 except ImportError:
875 except ImportError:
876 ndarray_type = None
876 ndarray_type = None
877 else:
877 else:
878 ndarray_type = numpy.ndarray.__name__
878 ndarray_type = numpy.ndarray.__name__
879 try:
879 try:
880 import Numeric
880 import Numeric
881 except ImportError:
881 except ImportError:
882 array_type = None
882 array_type = None
883 else:
883 else:
884 array_type = Numeric.ArrayType.__name__
884 array_type = Numeric.ArrayType.__name__
885
885
886 # Find all variable names and types so we can figure out column sizes
886 # Find all variable names and types so we can figure out column sizes
887 def get_vars(i):
887 def get_vars(i):
888 return self.shell.user_ns[i]
888 return self.shell.user_ns[i]
889
889
890 # some types are well known and can be shorter
890 # some types are well known and can be shorter
891 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
891 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
892 def type_name(v):
892 def type_name(v):
893 tn = type(v).__name__
893 tn = type(v).__name__
894 return abbrevs.get(tn,tn)
894 return abbrevs.get(tn,tn)
895
895
896 varlist = map(get_vars,varnames)
896 varlist = map(get_vars,varnames)
897
897
898 typelist = []
898 typelist = []
899 for vv in varlist:
899 for vv in varlist:
900 tt = type_name(vv)
900 tt = type_name(vv)
901
901
902 if tt=='instance':
902 if tt=='instance':
903 typelist.append( abbrevs.get(str(vv.__class__),
903 typelist.append( abbrevs.get(str(vv.__class__),
904 str(vv.__class__)))
904 str(vv.__class__)))
905 else:
905 else:
906 typelist.append(tt)
906 typelist.append(tt)
907
907
908 # column labels and # of spaces as separator
908 # column labels and # of spaces as separator
909 varlabel = 'Variable'
909 varlabel = 'Variable'
910 typelabel = 'Type'
910 typelabel = 'Type'
911 datalabel = 'Data/Info'
911 datalabel = 'Data/Info'
912 colsep = 3
912 colsep = 3
913 # variable format strings
913 # variable format strings
914 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
914 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
915 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
915 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
916 aformat = "%s: %s elems, type `%s`, %s bytes"
916 aformat = "%s: %s elems, type `%s`, %s bytes"
917 # find the size of the columns to format the output nicely
917 # find the size of the columns to format the output nicely
918 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
918 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
919 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
919 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
920 # table header
920 # table header
921 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
921 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
922 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
922 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
923 # and the table itself
923 # and the table itself
924 kb = 1024
924 kb = 1024
925 Mb = 1048576 # kb**2
925 Mb = 1048576 # kb**2
926 for vname,var,vtype in zip(varnames,varlist,typelist):
926 for vname,var,vtype in zip(varnames,varlist,typelist):
927 print itpl(vformat),
927 print itpl(vformat),
928 if vtype in seq_types:
928 if vtype in seq_types:
929 print len(var)
929 print len(var)
930 elif vtype in [array_type,ndarray_type]:
930 elif vtype in [array_type,ndarray_type]:
931 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
931 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
932 if vtype==ndarray_type:
932 if vtype==ndarray_type:
933 # numpy
933 # numpy
934 vsize = var.size
934 vsize = var.size
935 vbytes = vsize*var.itemsize
935 vbytes = vsize*var.itemsize
936 vdtype = var.dtype
936 vdtype = var.dtype
937 else:
937 else:
938 # Numeric
938 # Numeric
939 vsize = Numeric.size(var)
939 vsize = Numeric.size(var)
940 vbytes = vsize*var.itemsize()
940 vbytes = vsize*var.itemsize()
941 vdtype = var.typecode()
941 vdtype = var.typecode()
942
942
943 if vbytes < 100000:
943 if vbytes < 100000:
944 print aformat % (vshape,vsize,vdtype,vbytes)
944 print aformat % (vshape,vsize,vdtype,vbytes)
945 else:
945 else:
946 print aformat % (vshape,vsize,vdtype,vbytes),
946 print aformat % (vshape,vsize,vdtype,vbytes),
947 if vbytes < Mb:
947 if vbytes < Mb:
948 print '(%s kb)' % (vbytes/kb,)
948 print '(%s kb)' % (vbytes/kb,)
949 else:
949 else:
950 print '(%s Mb)' % (vbytes/Mb,)
950 print '(%s Mb)' % (vbytes/Mb,)
951 else:
951 else:
952 try:
952 try:
953 vstr = str(var)
953 vstr = str(var)
954 except UnicodeEncodeError:
954 except UnicodeEncodeError:
955 vstr = unicode(var).encode(sys.getdefaultencoding(),
955 vstr = unicode(var).encode(sys.getdefaultencoding(),
956 'backslashreplace')
956 'backslashreplace')
957 vstr = vstr.replace('\n','\\n')
957 vstr = vstr.replace('\n','\\n')
958 if len(vstr) < 50:
958 if len(vstr) < 50:
959 print vstr
959 print vstr
960 else:
960 else:
961 printpl(vfmt_short)
961 printpl(vfmt_short)
962
962
963 def magic_reset(self, parameter_s=''):
963 def magic_reset(self, parameter_s=''):
964 """Resets the namespace by removing all names defined by the user.
964 """Resets the namespace by removing all names defined by the user.
965
965
966 Input/Output history are left around in case you need them.
966 Input/Output history are left around in case you need them.
967
967
968 Parameters
968 Parameters
969 ----------
969 ----------
970 -y : force reset without asking for confirmation.
970 -y : force reset without asking for confirmation.
971
971
972 Examples
972 Examples
973 --------
973 --------
974 In [6]: a = 1
974 In [6]: a = 1
975
975
976 In [7]: a
976 In [7]: a
977 Out[7]: 1
977 Out[7]: 1
978
978
979 In [8]: 'a' in _ip.user_ns
979 In [8]: 'a' in _ip.user_ns
980 Out[8]: True
980 Out[8]: True
981
981
982 In [9]: %reset -f
982 In [9]: %reset -f
983
983
984 In [10]: 'a' in _ip.user_ns
984 In [10]: 'a' in _ip.user_ns
985 Out[10]: False
985 Out[10]: False
986 """
986 """
987
987
988 if parameter_s == '-f':
988 if parameter_s == '-f':
989 ans = True
989 ans = True
990 else:
990 else:
991 ans = self.shell.ask_yes_no(
991 ans = self.shell.ask_yes_no(
992 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
992 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
993 if not ans:
993 if not ans:
994 print 'Nothing done.'
994 print 'Nothing done.'
995 return
995 return
996 user_ns = self.shell.user_ns
996 user_ns = self.shell.user_ns
997 for i in self.magic_who_ls():
997 for i in self.magic_who_ls():
998 del(user_ns[i])
998 del(user_ns[i])
999
999
1000 # Also flush the private list of module references kept for script
1000 # Also flush the private list of module references kept for script
1001 # execution protection
1001 # execution protection
1002 self.shell.clear_main_mod_cache()
1002 self.shell.clear_main_mod_cache()
1003
1003
1004 def magic_reset_selective(self, parameter_s=''):
1004 def magic_reset_selective(self, parameter_s=''):
1005 """Resets the namespace by removing names defined by the user.
1005 """Resets the namespace by removing names defined by the user.
1006
1006
1007 Input/Output history are left around in case you need them.
1007 Input/Output history are left around in case you need them.
1008
1008
1009 %reset_selective [-f] regex
1009 %reset_selective [-f] regex
1010
1010
1011 No action is taken if regex is not included
1011 No action is taken if regex is not included
1012
1012
1013 Options
1013 Options
1014 -f : force reset without asking for confirmation.
1014 -f : force reset without asking for confirmation.
1015
1015
1016 Examples
1016 Examples
1017 --------
1017 --------
1018
1018
1019 We first fully reset the namespace so your output looks identical to
1019 We first fully reset the namespace so your output looks identical to
1020 this example for pedagogical reasons; in practice you do not need a
1020 this example for pedagogical reasons; in practice you do not need a
1021 full reset.
1021 full reset.
1022
1022
1023 In [1]: %reset -f
1023 In [1]: %reset -f
1024
1024
1025 Now, with a clean namespace we can make a few variables and use
1025 Now, with a clean namespace we can make a few variables and use
1026 %reset_selective to only delete names that match our regexp:
1026 %reset_selective to only delete names that match our regexp:
1027
1027
1028 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1028 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1029
1029
1030 In [3]: who_ls
1030 In [3]: who_ls
1031 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1031 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1032
1032
1033 In [4]: %reset_selective -f b[2-3]m
1033 In [4]: %reset_selective -f b[2-3]m
1034
1034
1035 In [5]: who_ls
1035 In [5]: who_ls
1036 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1036 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1037
1037
1038 In [6]: %reset_selective -f d
1038 In [6]: %reset_selective -f d
1039
1039
1040 In [7]: who_ls
1040 In [7]: who_ls
1041 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1041 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1042
1042
1043 In [8]: %reset_selective -f c
1043 In [8]: %reset_selective -f c
1044
1044
1045 In [9]: who_ls
1045 In [9]: who_ls
1046 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1046 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1047
1047
1048 In [10]: %reset_selective -f b
1048 In [10]: %reset_selective -f b
1049
1049
1050 In [11]: who_ls
1050 In [11]: who_ls
1051 Out[11]: ['a']
1051 Out[11]: ['a']
1052 """
1052 """
1053
1053
1054 opts, regex = self.parse_options(parameter_s,'f')
1054 opts, regex = self.parse_options(parameter_s,'f')
1055
1055
1056 if opts.has_key('f'):
1056 if opts.has_key('f'):
1057 ans = True
1057 ans = True
1058 else:
1058 else:
1059 ans = self.shell.ask_yes_no(
1059 ans = self.shell.ask_yes_no(
1060 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1060 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1061 if not ans:
1061 if not ans:
1062 print 'Nothing done.'
1062 print 'Nothing done.'
1063 return
1063 return
1064 user_ns = self.shell.user_ns
1064 user_ns = self.shell.user_ns
1065 if not regex:
1065 if not regex:
1066 print 'No regex pattern specified. Nothing done.'
1066 print 'No regex pattern specified. Nothing done.'
1067 return
1067 return
1068 else:
1068 else:
1069 try:
1069 try:
1070 m = re.compile(regex)
1070 m = re.compile(regex)
1071 except TypeError:
1071 except TypeError:
1072 raise TypeError('regex must be a string or compiled pattern')
1072 raise TypeError('regex must be a string or compiled pattern')
1073 for i in self.magic_who_ls():
1073 for i in self.magic_who_ls():
1074 if m.search(i):
1074 if m.search(i):
1075 del(user_ns[i])
1075 del(user_ns[i])
1076
1076
1077 def magic_logstart(self,parameter_s=''):
1077 def magic_logstart(self,parameter_s=''):
1078 """Start logging anywhere in a session.
1078 """Start logging anywhere in a session.
1079
1079
1080 %logstart [-o|-r|-t] [log_name [log_mode]]
1080 %logstart [-o|-r|-t] [log_name [log_mode]]
1081
1081
1082 If no name is given, it defaults to a file named 'ipython_log.py' in your
1082 If no name is given, it defaults to a file named 'ipython_log.py' in your
1083 current directory, in 'rotate' mode (see below).
1083 current directory, in 'rotate' mode (see below).
1084
1084
1085 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1085 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1086 history up to that point and then continues logging.
1086 history up to that point and then continues logging.
1087
1087
1088 %logstart takes a second optional parameter: logging mode. This can be one
1088 %logstart takes a second optional parameter: logging mode. This can be one
1089 of (note that the modes are given unquoted):\\
1089 of (note that the modes are given unquoted):\\
1090 append: well, that says it.\\
1090 append: well, that says it.\\
1091 backup: rename (if exists) to name~ and start name.\\
1091 backup: rename (if exists) to name~ and start name.\\
1092 global: single logfile in your home dir, appended to.\\
1092 global: single logfile in your home dir, appended to.\\
1093 over : overwrite existing log.\\
1093 over : overwrite existing log.\\
1094 rotate: create rotating logs name.1~, name.2~, etc.
1094 rotate: create rotating logs name.1~, name.2~, etc.
1095
1095
1096 Options:
1096 Options:
1097
1097
1098 -o: log also IPython's output. In this mode, all commands which
1098 -o: log also IPython's output. In this mode, all commands which
1099 generate an Out[NN] prompt are recorded to the logfile, right after
1099 generate an Out[NN] prompt are recorded to the logfile, right after
1100 their corresponding input line. The output lines are always
1100 their corresponding input line. The output lines are always
1101 prepended with a '#[Out]# ' marker, so that the log remains valid
1101 prepended with a '#[Out]# ' marker, so that the log remains valid
1102 Python code.
1102 Python code.
1103
1103
1104 Since this marker is always the same, filtering only the output from
1104 Since this marker is always the same, filtering only the output from
1105 a log is very easy, using for example a simple awk call:
1105 a log is very easy, using for example a simple awk call:
1106
1106
1107 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1107 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1108
1108
1109 -r: log 'raw' input. Normally, IPython's logs contain the processed
1109 -r: log 'raw' input. Normally, IPython's logs contain the processed
1110 input, so that user lines are logged in their final form, converted
1110 input, so that user lines are logged in their final form, converted
1111 into valid Python. For example, %Exit is logged as
1111 into valid Python. For example, %Exit is logged as
1112 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1112 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1113 exactly as typed, with no transformations applied.
1113 exactly as typed, with no transformations applied.
1114
1114
1115 -t: put timestamps before each input line logged (these are put in
1115 -t: put timestamps before each input line logged (these are put in
1116 comments)."""
1116 comments)."""
1117
1117
1118 opts,par = self.parse_options(parameter_s,'ort')
1118 opts,par = self.parse_options(parameter_s,'ort')
1119 log_output = 'o' in opts
1119 log_output = 'o' in opts
1120 log_raw_input = 'r' in opts
1120 log_raw_input = 'r' in opts
1121 timestamp = 't' in opts
1121 timestamp = 't' in opts
1122
1122
1123 logger = self.shell.logger
1123 logger = self.shell.logger
1124
1124
1125 # if no args are given, the defaults set in the logger constructor by
1125 # if no args are given, the defaults set in the logger constructor by
1126 # ipytohn remain valid
1126 # ipytohn remain valid
1127 if par:
1127 if par:
1128 try:
1128 try:
1129 logfname,logmode = par.split()
1129 logfname,logmode = par.split()
1130 except:
1130 except:
1131 logfname = par
1131 logfname = par
1132 logmode = 'backup'
1132 logmode = 'backup'
1133 else:
1133 else:
1134 logfname = logger.logfname
1134 logfname = logger.logfname
1135 logmode = logger.logmode
1135 logmode = logger.logmode
1136 # put logfname into rc struct as if it had been called on the command
1136 # put logfname into rc struct as if it had been called on the command
1137 # line, so it ends up saved in the log header Save it in case we need
1137 # line, so it ends up saved in the log header Save it in case we need
1138 # to restore it...
1138 # to restore it...
1139 old_logfile = self.shell.logfile
1139 old_logfile = self.shell.logfile
1140 if logfname:
1140 if logfname:
1141 logfname = os.path.expanduser(logfname)
1141 logfname = os.path.expanduser(logfname)
1142 self.shell.logfile = logfname
1142 self.shell.logfile = logfname
1143
1143
1144 loghead = '# IPython log file\n\n'
1144 loghead = '# IPython log file\n\n'
1145 try:
1145 try:
1146 started = logger.logstart(logfname,loghead,logmode,
1146 started = logger.logstart(logfname,loghead,logmode,
1147 log_output,timestamp,log_raw_input)
1147 log_output,timestamp,log_raw_input)
1148 except:
1148 except:
1149 self.shell.logfile = old_logfile
1149 self.shell.logfile = old_logfile
1150 warn("Couldn't start log: %s" % sys.exc_info()[1])
1150 warn("Couldn't start log: %s" % sys.exc_info()[1])
1151 else:
1151 else:
1152 # log input history up to this point, optionally interleaving
1152 # log input history up to this point, optionally interleaving
1153 # output if requested
1153 # output if requested
1154
1154
1155 if timestamp:
1155 if timestamp:
1156 # disable timestamping for the previous history, since we've
1156 # disable timestamping for the previous history, since we've
1157 # lost those already (no time machine here).
1157 # lost those already (no time machine here).
1158 logger.timestamp = False
1158 logger.timestamp = False
1159
1159
1160 if log_raw_input:
1160 if log_raw_input:
1161 input_hist = self.shell.history_manager.input_hist_raw
1161 input_hist = self.shell.history_manager.input_hist_raw
1162 else:
1162 else:
1163 input_hist = self.shell.history_manager.input_hist_parsed
1163 input_hist = self.shell.history_manager.input_hist_parsed
1164
1164
1165 if log_output:
1165 if log_output:
1166 log_write = logger.log_write
1166 log_write = logger.log_write
1167 output_hist = self.shell.history_manager.output_hist
1167 output_hist = self.shell.history_manager.output_hist
1168 for n in range(1,len(input_hist)-1):
1168 for n in range(1,len(input_hist)-1):
1169 log_write(input_hist[n].rstrip())
1169 log_write(input_hist[n].rstrip())
1170 if n in output_hist:
1170 if n in output_hist:
1171 log_write(repr(output_hist[n]),'output')
1171 log_write(repr(output_hist[n]),'output')
1172 else:
1172 else:
1173 logger.log_write(''.join(input_hist[1:]))
1173 logger.log_write(''.join(input_hist[1:]))
1174 if timestamp:
1174 if timestamp:
1175 # re-enable timestamping
1175 # re-enable timestamping
1176 logger.timestamp = True
1176 logger.timestamp = True
1177
1177
1178 print ('Activating auto-logging. '
1178 print ('Activating auto-logging. '
1179 'Current session state plus future input saved.')
1179 'Current session state plus future input saved.')
1180 logger.logstate()
1180 logger.logstate()
1181
1181
1182 def magic_logstop(self,parameter_s=''):
1182 def magic_logstop(self,parameter_s=''):
1183 """Fully stop logging and close log file.
1183 """Fully stop logging and close log file.
1184
1184
1185 In order to start logging again, a new %logstart call needs to be made,
1185 In order to start logging again, a new %logstart call needs to be made,
1186 possibly (though not necessarily) with a new filename, mode and other
1186 possibly (though not necessarily) with a new filename, mode and other
1187 options."""
1187 options."""
1188 self.logger.logstop()
1188 self.logger.logstop()
1189
1189
1190 def magic_logoff(self,parameter_s=''):
1190 def magic_logoff(self,parameter_s=''):
1191 """Temporarily stop logging.
1191 """Temporarily stop logging.
1192
1192
1193 You must have previously started logging."""
1193 You must have previously started logging."""
1194 self.shell.logger.switch_log(0)
1194 self.shell.logger.switch_log(0)
1195
1195
1196 def magic_logon(self,parameter_s=''):
1196 def magic_logon(self,parameter_s=''):
1197 """Restart logging.
1197 """Restart logging.
1198
1198
1199 This function is for restarting logging which you've temporarily
1199 This function is for restarting logging which you've temporarily
1200 stopped with %logoff. For starting logging for the first time, you
1200 stopped with %logoff. For starting logging for the first time, you
1201 must use the %logstart function, which allows you to specify an
1201 must use the %logstart function, which allows you to specify an
1202 optional log filename."""
1202 optional log filename."""
1203
1203
1204 self.shell.logger.switch_log(1)
1204 self.shell.logger.switch_log(1)
1205
1205
1206 def magic_logstate(self,parameter_s=''):
1206 def magic_logstate(self,parameter_s=''):
1207 """Print the status of the logging system."""
1207 """Print the status of the logging system."""
1208
1208
1209 self.shell.logger.logstate()
1209 self.shell.logger.logstate()
1210
1210
1211 def magic_pdb(self, parameter_s=''):
1211 def magic_pdb(self, parameter_s=''):
1212 """Control the automatic calling of the pdb interactive debugger.
1212 """Control the automatic calling of the pdb interactive debugger.
1213
1213
1214 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1214 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1215 argument it works as a toggle.
1215 argument it works as a toggle.
1216
1216
1217 When an exception is triggered, IPython can optionally call the
1217 When an exception is triggered, IPython can optionally call the
1218 interactive pdb debugger after the traceback printout. %pdb toggles
1218 interactive pdb debugger after the traceback printout. %pdb toggles
1219 this feature on and off.
1219 this feature on and off.
1220
1220
1221 The initial state of this feature is set in your ipythonrc
1221 The initial state of this feature is set in your ipythonrc
1222 configuration file (the variable is called 'pdb').
1222 configuration file (the variable is called 'pdb').
1223
1223
1224 If you want to just activate the debugger AFTER an exception has fired,
1224 If you want to just activate the debugger AFTER an exception has fired,
1225 without having to type '%pdb on' and rerunning your code, you can use
1225 without having to type '%pdb on' and rerunning your code, you can use
1226 the %debug magic."""
1226 the %debug magic."""
1227
1227
1228 par = parameter_s.strip().lower()
1228 par = parameter_s.strip().lower()
1229
1229
1230 if par:
1230 if par:
1231 try:
1231 try:
1232 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1232 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1233 except KeyError:
1233 except KeyError:
1234 print ('Incorrect argument. Use on/1, off/0, '
1234 print ('Incorrect argument. Use on/1, off/0, '
1235 'or nothing for a toggle.')
1235 'or nothing for a toggle.')
1236 return
1236 return
1237 else:
1237 else:
1238 # toggle
1238 # toggle
1239 new_pdb = not self.shell.call_pdb
1239 new_pdb = not self.shell.call_pdb
1240
1240
1241 # set on the shell
1241 # set on the shell
1242 self.shell.call_pdb = new_pdb
1242 self.shell.call_pdb = new_pdb
1243 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1243 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1244
1244
1245 def magic_debug(self, parameter_s=''):
1245 def magic_debug(self, parameter_s=''):
1246 """Activate the interactive debugger in post-mortem mode.
1246 """Activate the interactive debugger in post-mortem mode.
1247
1247
1248 If an exception has just occurred, this lets you inspect its stack
1248 If an exception has just occurred, this lets you inspect its stack
1249 frames interactively. Note that this will always work only on the last
1249 frames interactively. Note that this will always work only on the last
1250 traceback that occurred, so you must call this quickly after an
1250 traceback that occurred, so you must call this quickly after an
1251 exception that you wish to inspect has fired, because if another one
1251 exception that you wish to inspect has fired, because if another one
1252 occurs, it clobbers the previous one.
1252 occurs, it clobbers the previous one.
1253
1253
1254 If you want IPython to automatically do this on every exception, see
1254 If you want IPython to automatically do this on every exception, see
1255 the %pdb magic for more details.
1255 the %pdb magic for more details.
1256 """
1256 """
1257 self.shell.debugger(force=True)
1257 self.shell.debugger(force=True)
1258
1258
1259 @testdec.skip_doctest
1259 @testdec.skip_doctest
1260 def magic_prun(self, parameter_s ='',user_mode=1,
1260 def magic_prun(self, parameter_s ='',user_mode=1,
1261 opts=None,arg_lst=None,prog_ns=None):
1261 opts=None,arg_lst=None,prog_ns=None):
1262
1262
1263 """Run a statement through the python code profiler.
1263 """Run a statement through the python code profiler.
1264
1264
1265 Usage:
1265 Usage:
1266 %prun [options] statement
1266 %prun [options] statement
1267
1267
1268 The given statement (which doesn't require quote marks) is run via the
1268 The given statement (which doesn't require quote marks) is run via the
1269 python profiler in a manner similar to the profile.run() function.
1269 python profiler in a manner similar to the profile.run() function.
1270 Namespaces are internally managed to work correctly; profile.run
1270 Namespaces are internally managed to work correctly; profile.run
1271 cannot be used in IPython because it makes certain assumptions about
1271 cannot be used in IPython because it makes certain assumptions about
1272 namespaces which do not hold under IPython.
1272 namespaces which do not hold under IPython.
1273
1273
1274 Options:
1274 Options:
1275
1275
1276 -l <limit>: you can place restrictions on what or how much of the
1276 -l <limit>: you can place restrictions on what or how much of the
1277 profile gets printed. The limit value can be:
1277 profile gets printed. The limit value can be:
1278
1278
1279 * A string: only information for function names containing this string
1279 * A string: only information for function names containing this string
1280 is printed.
1280 is printed.
1281
1281
1282 * An integer: only these many lines are printed.
1282 * An integer: only these many lines are printed.
1283
1283
1284 * A float (between 0 and 1): this fraction of the report is printed
1284 * A float (between 0 and 1): this fraction of the report is printed
1285 (for example, use a limit of 0.4 to see the topmost 40% only).
1285 (for example, use a limit of 0.4 to see the topmost 40% only).
1286
1286
1287 You can combine several limits with repeated use of the option. For
1287 You can combine several limits with repeated use of the option. For
1288 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1288 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1289 information about class constructors.
1289 information about class constructors.
1290
1290
1291 -r: return the pstats.Stats object generated by the profiling. This
1291 -r: return the pstats.Stats object generated by the profiling. This
1292 object has all the information about the profile in it, and you can
1292 object has all the information about the profile in it, and you can
1293 later use it for further analysis or in other functions.
1293 later use it for further analysis or in other functions.
1294
1294
1295 -s <key>: sort profile by given key. You can provide more than one key
1295 -s <key>: sort profile by given key. You can provide more than one key
1296 by using the option several times: '-s key1 -s key2 -s key3...'. The
1296 by using the option several times: '-s key1 -s key2 -s key3...'. The
1297 default sorting key is 'time'.
1297 default sorting key is 'time'.
1298
1298
1299 The following is copied verbatim from the profile documentation
1299 The following is copied verbatim from the profile documentation
1300 referenced below:
1300 referenced below:
1301
1301
1302 When more than one key is provided, additional keys are used as
1302 When more than one key is provided, additional keys are used as
1303 secondary criteria when the there is equality in all keys selected
1303 secondary criteria when the there is equality in all keys selected
1304 before them.
1304 before them.
1305
1305
1306 Abbreviations can be used for any key names, as long as the
1306 Abbreviations can be used for any key names, as long as the
1307 abbreviation is unambiguous. The following are the keys currently
1307 abbreviation is unambiguous. The following are the keys currently
1308 defined:
1308 defined:
1309
1309
1310 Valid Arg Meaning
1310 Valid Arg Meaning
1311 "calls" call count
1311 "calls" call count
1312 "cumulative" cumulative time
1312 "cumulative" cumulative time
1313 "file" file name
1313 "file" file name
1314 "module" file name
1314 "module" file name
1315 "pcalls" primitive call count
1315 "pcalls" primitive call count
1316 "line" line number
1316 "line" line number
1317 "name" function name
1317 "name" function name
1318 "nfl" name/file/line
1318 "nfl" name/file/line
1319 "stdname" standard name
1319 "stdname" standard name
1320 "time" internal time
1320 "time" internal time
1321
1321
1322 Note that all sorts on statistics are in descending order (placing
1322 Note that all sorts on statistics are in descending order (placing
1323 most time consuming items first), where as name, file, and line number
1323 most time consuming items first), where as name, file, and line number
1324 searches are in ascending order (i.e., alphabetical). The subtle
1324 searches are in ascending order (i.e., alphabetical). The subtle
1325 distinction between "nfl" and "stdname" is that the standard name is a
1325 distinction between "nfl" and "stdname" is that the standard name is a
1326 sort of the name as printed, which means that the embedded line
1326 sort of the name as printed, which means that the embedded line
1327 numbers get compared in an odd way. For example, lines 3, 20, and 40
1327 numbers get compared in an odd way. For example, lines 3, 20, and 40
1328 would (if the file names were the same) appear in the string order
1328 would (if the file names were the same) appear in the string order
1329 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1329 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1330 line numbers. In fact, sort_stats("nfl") is the same as
1330 line numbers. In fact, sort_stats("nfl") is the same as
1331 sort_stats("name", "file", "line").
1331 sort_stats("name", "file", "line").
1332
1332
1333 -T <filename>: save profile results as shown on screen to a text
1333 -T <filename>: save profile results as shown on screen to a text
1334 file. The profile is still shown on screen.
1334 file. The profile is still shown on screen.
1335
1335
1336 -D <filename>: save (via dump_stats) profile statistics to given
1336 -D <filename>: save (via dump_stats) profile statistics to given
1337 filename. This data is in a format understod by the pstats module, and
1337 filename. This data is in a format understod by the pstats module, and
1338 is generated by a call to the dump_stats() method of profile
1338 is generated by a call to the dump_stats() method of profile
1339 objects. The profile is still shown on screen.
1339 objects. The profile is still shown on screen.
1340
1340
1341 If you want to run complete programs under the profiler's control, use
1341 If you want to run complete programs under the profiler's control, use
1342 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1342 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1343 contains profiler specific options as described here.
1343 contains profiler specific options as described here.
1344
1344
1345 You can read the complete documentation for the profile module with::
1345 You can read the complete documentation for the profile module with::
1346
1346
1347 In [1]: import profile; profile.help()
1347 In [1]: import profile; profile.help()
1348 """
1348 """
1349
1349
1350 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1350 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1351 # protect user quote marks
1351 # protect user quote marks
1352 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1352 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1353
1353
1354 if user_mode: # regular user call
1354 if user_mode: # regular user call
1355 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1355 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1356 list_all=1)
1356 list_all=1)
1357 namespace = self.shell.user_ns
1357 namespace = self.shell.user_ns
1358 else: # called to run a program by %run -p
1358 else: # called to run a program by %run -p
1359 try:
1359 try:
1360 filename = get_py_filename(arg_lst[0])
1360 filename = get_py_filename(arg_lst[0])
1361 except IOError,msg:
1361 except IOError,msg:
1362 error(msg)
1362 error(msg)
1363 return
1363 return
1364
1364
1365 arg_str = 'execfile(filename,prog_ns)'
1365 arg_str = 'execfile(filename,prog_ns)'
1366 namespace = locals()
1366 namespace = locals()
1367
1367
1368 opts.merge(opts_def)
1368 opts.merge(opts_def)
1369
1369
1370 prof = profile.Profile()
1370 prof = profile.Profile()
1371 try:
1371 try:
1372 prof = prof.runctx(arg_str,namespace,namespace)
1372 prof = prof.runctx(arg_str,namespace,namespace)
1373 sys_exit = ''
1373 sys_exit = ''
1374 except SystemExit:
1374 except SystemExit:
1375 sys_exit = """*** SystemExit exception caught in code being profiled."""
1375 sys_exit = """*** SystemExit exception caught in code being profiled."""
1376
1376
1377 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1377 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1378
1378
1379 lims = opts.l
1379 lims = opts.l
1380 if lims:
1380 if lims:
1381 lims = [] # rebuild lims with ints/floats/strings
1381 lims = [] # rebuild lims with ints/floats/strings
1382 for lim in opts.l:
1382 for lim in opts.l:
1383 try:
1383 try:
1384 lims.append(int(lim))
1384 lims.append(int(lim))
1385 except ValueError:
1385 except ValueError:
1386 try:
1386 try:
1387 lims.append(float(lim))
1387 lims.append(float(lim))
1388 except ValueError:
1388 except ValueError:
1389 lims.append(lim)
1389 lims.append(lim)
1390
1390
1391 # Trap output.
1391 # Trap output.
1392 stdout_trap = StringIO()
1392 stdout_trap = StringIO()
1393
1393
1394 if hasattr(stats,'stream'):
1394 if hasattr(stats,'stream'):
1395 # In newer versions of python, the stats object has a 'stream'
1395 # In newer versions of python, the stats object has a 'stream'
1396 # attribute to write into.
1396 # attribute to write into.
1397 stats.stream = stdout_trap
1397 stats.stream = stdout_trap
1398 stats.print_stats(*lims)
1398 stats.print_stats(*lims)
1399 else:
1399 else:
1400 # For older versions, we manually redirect stdout during printing
1400 # For older versions, we manually redirect stdout during printing
1401 sys_stdout = sys.stdout
1401 sys_stdout = sys.stdout
1402 try:
1402 try:
1403 sys.stdout = stdout_trap
1403 sys.stdout = stdout_trap
1404 stats.print_stats(*lims)
1404 stats.print_stats(*lims)
1405 finally:
1405 finally:
1406 sys.stdout = sys_stdout
1406 sys.stdout = sys_stdout
1407
1407
1408 output = stdout_trap.getvalue()
1408 output = stdout_trap.getvalue()
1409 output = output.rstrip()
1409 output = output.rstrip()
1410
1410
1411 page.page(output)
1411 page.page(output)
1412 print sys_exit,
1412 print sys_exit,
1413
1413
1414 dump_file = opts.D[0]
1414 dump_file = opts.D[0]
1415 text_file = opts.T[0]
1415 text_file = opts.T[0]
1416 if dump_file:
1416 if dump_file:
1417 prof.dump_stats(dump_file)
1417 prof.dump_stats(dump_file)
1418 print '\n*** Profile stats marshalled to file',\
1418 print '\n*** Profile stats marshalled to file',\
1419 `dump_file`+'.',sys_exit
1419 `dump_file`+'.',sys_exit
1420 if text_file:
1420 if text_file:
1421 pfile = file(text_file,'w')
1421 pfile = file(text_file,'w')
1422 pfile.write(output)
1422 pfile.write(output)
1423 pfile.close()
1423 pfile.close()
1424 print '\n*** Profile printout saved to text file',\
1424 print '\n*** Profile printout saved to text file',\
1425 `text_file`+'.',sys_exit
1425 `text_file`+'.',sys_exit
1426
1426
1427 if opts.has_key('r'):
1427 if opts.has_key('r'):
1428 return stats
1428 return stats
1429 else:
1429 else:
1430 return None
1430 return None
1431
1431
1432 @testdec.skip_doctest
1432 @testdec.skip_doctest
1433 def magic_run(self, parameter_s ='',runner=None,
1433 def magic_run(self, parameter_s ='',runner=None,
1434 file_finder=get_py_filename):
1434 file_finder=get_py_filename):
1435 """Run the named file inside IPython as a program.
1435 """Run the named file inside IPython as a program.
1436
1436
1437 Usage:\\
1437 Usage:\\
1438 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1438 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1439
1439
1440 Parameters after the filename are passed as command-line arguments to
1440 Parameters after the filename are passed as command-line arguments to
1441 the program (put in sys.argv). Then, control returns to IPython's
1441 the program (put in sys.argv). Then, control returns to IPython's
1442 prompt.
1442 prompt.
1443
1443
1444 This is similar to running at a system prompt:\\
1444 This is similar to running at a system prompt:\\
1445 $ python file args\\
1445 $ python file args\\
1446 but with the advantage of giving you IPython's tracebacks, and of
1446 but with the advantage of giving you IPython's tracebacks, and of
1447 loading all variables into your interactive namespace for further use
1447 loading all variables into your interactive namespace for further use
1448 (unless -p is used, see below).
1448 (unless -p is used, see below).
1449
1449
1450 The file is executed in a namespace initially consisting only of
1450 The file is executed in a namespace initially consisting only of
1451 __name__=='__main__' and sys.argv constructed as indicated. It thus
1451 __name__=='__main__' and sys.argv constructed as indicated. It thus
1452 sees its environment as if it were being run as a stand-alone program
1452 sees its environment as if it were being run as a stand-alone program
1453 (except for sharing global objects such as previously imported
1453 (except for sharing global objects such as previously imported
1454 modules). But after execution, the IPython interactive namespace gets
1454 modules). But after execution, the IPython interactive namespace gets
1455 updated with all variables defined in the program (except for __name__
1455 updated with all variables defined in the program (except for __name__
1456 and sys.argv). This allows for very convenient loading of code for
1456 and sys.argv). This allows for very convenient loading of code for
1457 interactive work, while giving each program a 'clean sheet' to run in.
1457 interactive work, while giving each program a 'clean sheet' to run in.
1458
1458
1459 Options:
1459 Options:
1460
1460
1461 -n: __name__ is NOT set to '__main__', but to the running file's name
1461 -n: __name__ is NOT set to '__main__', but to the running file's name
1462 without extension (as python does under import). This allows running
1462 without extension (as python does under import). This allows running
1463 scripts and reloading the definitions in them without calling code
1463 scripts and reloading the definitions in them without calling code
1464 protected by an ' if __name__ == "__main__" ' clause.
1464 protected by an ' if __name__ == "__main__" ' clause.
1465
1465
1466 -i: run the file in IPython's namespace instead of an empty one. This
1466 -i: run the file in IPython's namespace instead of an empty one. This
1467 is useful if you are experimenting with code written in a text editor
1467 is useful if you are experimenting with code written in a text editor
1468 which depends on variables defined interactively.
1468 which depends on variables defined interactively.
1469
1469
1470 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1470 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1471 being run. This is particularly useful if IPython is being used to
1471 being run. This is particularly useful if IPython is being used to
1472 run unittests, which always exit with a sys.exit() call. In such
1472 run unittests, which always exit with a sys.exit() call. In such
1473 cases you are interested in the output of the test results, not in
1473 cases you are interested in the output of the test results, not in
1474 seeing a traceback of the unittest module.
1474 seeing a traceback of the unittest module.
1475
1475
1476 -t: print timing information at the end of the run. IPython will give
1476 -t: print timing information at the end of the run. IPython will give
1477 you an estimated CPU time consumption for your script, which under
1477 you an estimated CPU time consumption for your script, which under
1478 Unix uses the resource module to avoid the wraparound problems of
1478 Unix uses the resource module to avoid the wraparound problems of
1479 time.clock(). Under Unix, an estimate of time spent on system tasks
1479 time.clock(). Under Unix, an estimate of time spent on system tasks
1480 is also given (for Windows platforms this is reported as 0.0).
1480 is also given (for Windows platforms this is reported as 0.0).
1481
1481
1482 If -t is given, an additional -N<N> option can be given, where <N>
1482 If -t is given, an additional -N<N> option can be given, where <N>
1483 must be an integer indicating how many times you want the script to
1483 must be an integer indicating how many times you want the script to
1484 run. The final timing report will include total and per run results.
1484 run. The final timing report will include total and per run results.
1485
1485
1486 For example (testing the script uniq_stable.py):
1486 For example (testing the script uniq_stable.py):
1487
1487
1488 In [1]: run -t uniq_stable
1488 In [1]: run -t uniq_stable
1489
1489
1490 IPython CPU timings (estimated):\\
1490 IPython CPU timings (estimated):\\
1491 User : 0.19597 s.\\
1491 User : 0.19597 s.\\
1492 System: 0.0 s.\\
1492 System: 0.0 s.\\
1493
1493
1494 In [2]: run -t -N5 uniq_stable
1494 In [2]: run -t -N5 uniq_stable
1495
1495
1496 IPython CPU timings (estimated):\\
1496 IPython CPU timings (estimated):\\
1497 Total runs performed: 5\\
1497 Total runs performed: 5\\
1498 Times : Total Per run\\
1498 Times : Total Per run\\
1499 User : 0.910862 s, 0.1821724 s.\\
1499 User : 0.910862 s, 0.1821724 s.\\
1500 System: 0.0 s, 0.0 s.
1500 System: 0.0 s, 0.0 s.
1501
1501
1502 -d: run your program under the control of pdb, the Python debugger.
1502 -d: run your program under the control of pdb, the Python debugger.
1503 This allows you to execute your program step by step, watch variables,
1503 This allows you to execute your program step by step, watch variables,
1504 etc. Internally, what IPython does is similar to calling:
1504 etc. Internally, what IPython does is similar to calling:
1505
1505
1506 pdb.run('execfile("YOURFILENAME")')
1506 pdb.run('execfile("YOURFILENAME")')
1507
1507
1508 with a breakpoint set on line 1 of your file. You can change the line
1508 with a breakpoint set on line 1 of your file. You can change the line
1509 number for this automatic breakpoint to be <N> by using the -bN option
1509 number for this automatic breakpoint to be <N> by using the -bN option
1510 (where N must be an integer). For example:
1510 (where N must be an integer). For example:
1511
1511
1512 %run -d -b40 myscript
1512 %run -d -b40 myscript
1513
1513
1514 will set the first breakpoint at line 40 in myscript.py. Note that
1514 will set the first breakpoint at line 40 in myscript.py. Note that
1515 the first breakpoint must be set on a line which actually does
1515 the first breakpoint must be set on a line which actually does
1516 something (not a comment or docstring) for it to stop execution.
1516 something (not a comment or docstring) for it to stop execution.
1517
1517
1518 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1518 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1519 first enter 'c' (without qoutes) to start execution up to the first
1519 first enter 'c' (without qoutes) to start execution up to the first
1520 breakpoint.
1520 breakpoint.
1521
1521
1522 Entering 'help' gives information about the use of the debugger. You
1522 Entering 'help' gives information about the use of the debugger. You
1523 can easily see pdb's full documentation with "import pdb;pdb.help()"
1523 can easily see pdb's full documentation with "import pdb;pdb.help()"
1524 at a prompt.
1524 at a prompt.
1525
1525
1526 -p: run program under the control of the Python profiler module (which
1526 -p: run program under the control of the Python profiler module (which
1527 prints a detailed report of execution times, function calls, etc).
1527 prints a detailed report of execution times, function calls, etc).
1528
1528
1529 You can pass other options after -p which affect the behavior of the
1529 You can pass other options after -p which affect the behavior of the
1530 profiler itself. See the docs for %prun for details.
1530 profiler itself. See the docs for %prun for details.
1531
1531
1532 In this mode, the program's variables do NOT propagate back to the
1532 In this mode, the program's variables do NOT propagate back to the
1533 IPython interactive namespace (because they remain in the namespace
1533 IPython interactive namespace (because they remain in the namespace
1534 where the profiler executes them).
1534 where the profiler executes them).
1535
1535
1536 Internally this triggers a call to %prun, see its documentation for
1536 Internally this triggers a call to %prun, see its documentation for
1537 details on the options available specifically for profiling.
1537 details on the options available specifically for profiling.
1538
1538
1539 There is one special usage for which the text above doesn't apply:
1539 There is one special usage for which the text above doesn't apply:
1540 if the filename ends with .ipy, the file is run as ipython script,
1540 if the filename ends with .ipy, the file is run as ipython script,
1541 just as if the commands were written on IPython prompt.
1541 just as if the commands were written on IPython prompt.
1542 """
1542 """
1543
1543
1544 # get arguments and set sys.argv for program to be run.
1544 # get arguments and set sys.argv for program to be run.
1545 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1545 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1546 mode='list',list_all=1)
1546 mode='list',list_all=1)
1547
1547
1548 try:
1548 try:
1549 filename = file_finder(arg_lst[0])
1549 filename = file_finder(arg_lst[0])
1550 except IndexError:
1550 except IndexError:
1551 warn('you must provide at least a filename.')
1551 warn('you must provide at least a filename.')
1552 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1552 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1553 return
1553 return
1554 except IOError,msg:
1554 except IOError,msg:
1555 error(msg)
1555 error(msg)
1556 return
1556 return
1557
1557
1558 if filename.lower().endswith('.ipy'):
1558 if filename.lower().endswith('.ipy'):
1559 self.shell.safe_execfile_ipy(filename)
1559 self.shell.safe_execfile_ipy(filename)
1560 return
1560 return
1561
1561
1562 # Control the response to exit() calls made by the script being run
1562 # Control the response to exit() calls made by the script being run
1563 exit_ignore = opts.has_key('e')
1563 exit_ignore = opts.has_key('e')
1564
1564
1565 # Make sure that the running script gets a proper sys.argv as if it
1565 # Make sure that the running script gets a proper sys.argv as if it
1566 # were run from a system shell.
1566 # were run from a system shell.
1567 save_argv = sys.argv # save it for later restoring
1567 save_argv = sys.argv # save it for later restoring
1568 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1568 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1569
1569
1570 if opts.has_key('i'):
1570 if opts.has_key('i'):
1571 # Run in user's interactive namespace
1571 # Run in user's interactive namespace
1572 prog_ns = self.shell.user_ns
1572 prog_ns = self.shell.user_ns
1573 __name__save = self.shell.user_ns['__name__']
1573 __name__save = self.shell.user_ns['__name__']
1574 prog_ns['__name__'] = '__main__'
1574 prog_ns['__name__'] = '__main__'
1575 main_mod = self.shell.new_main_mod(prog_ns)
1575 main_mod = self.shell.new_main_mod(prog_ns)
1576 else:
1576 else:
1577 # Run in a fresh, empty namespace
1577 # Run in a fresh, empty namespace
1578 if opts.has_key('n'):
1578 if opts.has_key('n'):
1579 name = os.path.splitext(os.path.basename(filename))[0]
1579 name = os.path.splitext(os.path.basename(filename))[0]
1580 else:
1580 else:
1581 name = '__main__'
1581 name = '__main__'
1582
1582
1583 main_mod = self.shell.new_main_mod()
1583 main_mod = self.shell.new_main_mod()
1584 prog_ns = main_mod.__dict__
1584 prog_ns = main_mod.__dict__
1585 prog_ns['__name__'] = name
1585 prog_ns['__name__'] = name
1586
1586
1587 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1587 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1588 # set the __file__ global in the script's namespace
1588 # set the __file__ global in the script's namespace
1589 prog_ns['__file__'] = filename
1589 prog_ns['__file__'] = filename
1590
1590
1591 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1591 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1592 # that, if we overwrite __main__, we replace it at the end
1592 # that, if we overwrite __main__, we replace it at the end
1593 main_mod_name = prog_ns['__name__']
1593 main_mod_name = prog_ns['__name__']
1594
1594
1595 if main_mod_name == '__main__':
1595 if main_mod_name == '__main__':
1596 restore_main = sys.modules['__main__']
1596 restore_main = sys.modules['__main__']
1597 else:
1597 else:
1598 restore_main = False
1598 restore_main = False
1599
1599
1600 # This needs to be undone at the end to prevent holding references to
1600 # This needs to be undone at the end to prevent holding references to
1601 # every single object ever created.
1601 # every single object ever created.
1602 sys.modules[main_mod_name] = main_mod
1602 sys.modules[main_mod_name] = main_mod
1603
1603
1604 stats = None
1604 stats = None
1605 try:
1605 try:
1606 #self.shell.save_history()
1606 #self.shell.save_history()
1607
1607
1608 if opts.has_key('p'):
1608 if opts.has_key('p'):
1609 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1609 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1610 else:
1610 else:
1611 if opts.has_key('d'):
1611 if opts.has_key('d'):
1612 deb = debugger.Pdb(self.shell.colors)
1612 deb = debugger.Pdb(self.shell.colors)
1613 # reset Breakpoint state, which is moronically kept
1613 # reset Breakpoint state, which is moronically kept
1614 # in a class
1614 # in a class
1615 bdb.Breakpoint.next = 1
1615 bdb.Breakpoint.next = 1
1616 bdb.Breakpoint.bplist = {}
1616 bdb.Breakpoint.bplist = {}
1617 bdb.Breakpoint.bpbynumber = [None]
1617 bdb.Breakpoint.bpbynumber = [None]
1618 # Set an initial breakpoint to stop execution
1618 # Set an initial breakpoint to stop execution
1619 maxtries = 10
1619 maxtries = 10
1620 bp = int(opts.get('b',[1])[0])
1620 bp = int(opts.get('b',[1])[0])
1621 checkline = deb.checkline(filename,bp)
1621 checkline = deb.checkline(filename,bp)
1622 if not checkline:
1622 if not checkline:
1623 for bp in range(bp+1,bp+maxtries+1):
1623 for bp in range(bp+1,bp+maxtries+1):
1624 if deb.checkline(filename,bp):
1624 if deb.checkline(filename,bp):
1625 break
1625 break
1626 else:
1626 else:
1627 msg = ("\nI failed to find a valid line to set "
1627 msg = ("\nI failed to find a valid line to set "
1628 "a breakpoint\n"
1628 "a breakpoint\n"
1629 "after trying up to line: %s.\n"
1629 "after trying up to line: %s.\n"
1630 "Please set a valid breakpoint manually "
1630 "Please set a valid breakpoint manually "
1631 "with the -b option." % bp)
1631 "with the -b option." % bp)
1632 error(msg)
1632 error(msg)
1633 return
1633 return
1634 # if we find a good linenumber, set the breakpoint
1634 # if we find a good linenumber, set the breakpoint
1635 deb.do_break('%s:%s' % (filename,bp))
1635 deb.do_break('%s:%s' % (filename,bp))
1636 # Start file run
1636 # Start file run
1637 print "NOTE: Enter 'c' at the",
1637 print "NOTE: Enter 'c' at the",
1638 print "%s prompt to start your script." % deb.prompt
1638 print "%s prompt to start your script." % deb.prompt
1639 try:
1639 try:
1640 deb.run('execfile("%s")' % filename,prog_ns)
1640 deb.run('execfile("%s")' % filename,prog_ns)
1641
1641
1642 except:
1642 except:
1643 etype, value, tb = sys.exc_info()
1643 etype, value, tb = sys.exc_info()
1644 # Skip three frames in the traceback: the %run one,
1644 # Skip three frames in the traceback: the %run one,
1645 # one inside bdb.py, and the command-line typed by the
1645 # one inside bdb.py, and the command-line typed by the
1646 # user (run by exec in pdb itself).
1646 # user (run by exec in pdb itself).
1647 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1647 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1648 else:
1648 else:
1649 if runner is None:
1649 if runner is None:
1650 runner = self.shell.safe_execfile
1650 runner = self.shell.safe_execfile
1651 if opts.has_key('t'):
1651 if opts.has_key('t'):
1652 # timed execution
1652 # timed execution
1653 try:
1653 try:
1654 nruns = int(opts['N'][0])
1654 nruns = int(opts['N'][0])
1655 if nruns < 1:
1655 if nruns < 1:
1656 error('Number of runs must be >=1')
1656 error('Number of runs must be >=1')
1657 return
1657 return
1658 except (KeyError):
1658 except (KeyError):
1659 nruns = 1
1659 nruns = 1
1660 if nruns == 1:
1660 if nruns == 1:
1661 t0 = clock2()
1661 t0 = clock2()
1662 runner(filename,prog_ns,prog_ns,
1662 runner(filename,prog_ns,prog_ns,
1663 exit_ignore=exit_ignore)
1663 exit_ignore=exit_ignore)
1664 t1 = clock2()
1664 t1 = clock2()
1665 t_usr = t1[0]-t0[0]
1665 t_usr = t1[0]-t0[0]
1666 t_sys = t1[1]-t0[1]
1666 t_sys = t1[1]-t0[1]
1667 print "\nIPython CPU timings (estimated):"
1667 print "\nIPython CPU timings (estimated):"
1668 print " User : %10s s." % t_usr
1668 print " User : %10s s." % t_usr
1669 print " System: %10s s." % t_sys
1669 print " System: %10s s." % t_sys
1670 else:
1670 else:
1671 runs = range(nruns)
1671 runs = range(nruns)
1672 t0 = clock2()
1672 t0 = clock2()
1673 for nr in runs:
1673 for nr in runs:
1674 runner(filename,prog_ns,prog_ns,
1674 runner(filename,prog_ns,prog_ns,
1675 exit_ignore=exit_ignore)
1675 exit_ignore=exit_ignore)
1676 t1 = clock2()
1676 t1 = clock2()
1677 t_usr = t1[0]-t0[0]
1677 t_usr = t1[0]-t0[0]
1678 t_sys = t1[1]-t0[1]
1678 t_sys = t1[1]-t0[1]
1679 print "\nIPython CPU timings (estimated):"
1679 print "\nIPython CPU timings (estimated):"
1680 print "Total runs performed:",nruns
1680 print "Total runs performed:",nruns
1681 print " Times : %10s %10s" % ('Total','Per run')
1681 print " Times : %10s %10s" % ('Total','Per run')
1682 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1682 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1683 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1683 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1684
1684
1685 else:
1685 else:
1686 # regular execution
1686 # regular execution
1687 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1687 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1688
1688
1689 if opts.has_key('i'):
1689 if opts.has_key('i'):
1690 self.shell.user_ns['__name__'] = __name__save
1690 self.shell.user_ns['__name__'] = __name__save
1691 else:
1691 else:
1692 # The shell MUST hold a reference to prog_ns so after %run
1692 # The shell MUST hold a reference to prog_ns so after %run
1693 # exits, the python deletion mechanism doesn't zero it out
1693 # exits, the python deletion mechanism doesn't zero it out
1694 # (leaving dangling references).
1694 # (leaving dangling references).
1695 self.shell.cache_main_mod(prog_ns,filename)
1695 self.shell.cache_main_mod(prog_ns,filename)
1696 # update IPython interactive namespace
1696 # update IPython interactive namespace
1697
1697
1698 # Some forms of read errors on the file may mean the
1698 # Some forms of read errors on the file may mean the
1699 # __name__ key was never set; using pop we don't have to
1699 # __name__ key was never set; using pop we don't have to
1700 # worry about a possible KeyError.
1700 # worry about a possible KeyError.
1701 prog_ns.pop('__name__', None)
1701 prog_ns.pop('__name__', None)
1702
1702
1703 self.shell.user_ns.update(prog_ns)
1703 self.shell.user_ns.update(prog_ns)
1704 finally:
1704 finally:
1705 # It's a bit of a mystery why, but __builtins__ can change from
1705 # It's a bit of a mystery why, but __builtins__ can change from
1706 # being a module to becoming a dict missing some key data after
1706 # being a module to becoming a dict missing some key data after
1707 # %run. As best I can see, this is NOT something IPython is doing
1707 # %run. As best I can see, this is NOT something IPython is doing
1708 # at all, and similar problems have been reported before:
1708 # at all, and similar problems have been reported before:
1709 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1709 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1710 # Since this seems to be done by the interpreter itself, the best
1710 # Since this seems to be done by the interpreter itself, the best
1711 # we can do is to at least restore __builtins__ for the user on
1711 # we can do is to at least restore __builtins__ for the user on
1712 # exit.
1712 # exit.
1713 self.shell.user_ns['__builtins__'] = __builtin__
1713 self.shell.user_ns['__builtins__'] = __builtin__
1714
1714
1715 # Ensure key global structures are restored
1715 # Ensure key global structures are restored
1716 sys.argv = save_argv
1716 sys.argv = save_argv
1717 if restore_main:
1717 if restore_main:
1718 sys.modules['__main__'] = restore_main
1718 sys.modules['__main__'] = restore_main
1719 else:
1719 else:
1720 # Remove from sys.modules the reference to main_mod we'd
1720 # Remove from sys.modules the reference to main_mod we'd
1721 # added. Otherwise it will trap references to objects
1721 # added. Otherwise it will trap references to objects
1722 # contained therein.
1722 # contained therein.
1723 del sys.modules[main_mod_name]
1723 del sys.modules[main_mod_name]
1724
1724
1725 #self.shell.reload_history()
1725 #self.shell.reload_history()
1726
1726
1727 return stats
1727 return stats
1728
1728
1729 @testdec.skip_doctest
1729 @testdec.skip_doctest
1730 def magic_timeit(self, parameter_s =''):
1730 def magic_timeit(self, parameter_s =''):
1731 """Time execution of a Python statement or expression
1731 """Time execution of a Python statement or expression
1732
1732
1733 Usage:\\
1733 Usage:\\
1734 %timeit [-n<N> -r<R> [-t|-c]] statement
1734 %timeit [-n<N> -r<R> [-t|-c]] statement
1735
1735
1736 Time execution of a Python statement or expression using the timeit
1736 Time execution of a Python statement or expression using the timeit
1737 module.
1737 module.
1738
1738
1739 Options:
1739 Options:
1740 -n<N>: execute the given statement <N> times in a loop. If this value
1740 -n<N>: execute the given statement <N> times in a loop. If this value
1741 is not given, a fitting value is chosen.
1741 is not given, a fitting value is chosen.
1742
1742
1743 -r<R>: repeat the loop iteration <R> times and take the best result.
1743 -r<R>: repeat the loop iteration <R> times and take the best result.
1744 Default: 3
1744 Default: 3
1745
1745
1746 -t: use time.time to measure the time, which is the default on Unix.
1746 -t: use time.time to measure the time, which is the default on Unix.
1747 This function measures wall time.
1747 This function measures wall time.
1748
1748
1749 -c: use time.clock to measure the time, which is the default on
1749 -c: use time.clock to measure the time, which is the default on
1750 Windows and measures wall time. On Unix, resource.getrusage is used
1750 Windows and measures wall time. On Unix, resource.getrusage is used
1751 instead and returns the CPU user time.
1751 instead and returns the CPU user time.
1752
1752
1753 -p<P>: use a precision of <P> digits to display the timing result.
1753 -p<P>: use a precision of <P> digits to display the timing result.
1754 Default: 3
1754 Default: 3
1755
1755
1756
1756
1757 Examples:
1757 Examples:
1758
1758
1759 In [1]: %timeit pass
1759 In [1]: %timeit pass
1760 10000000 loops, best of 3: 53.3 ns per loop
1760 10000000 loops, best of 3: 53.3 ns per loop
1761
1761
1762 In [2]: u = None
1762 In [2]: u = None
1763
1763
1764 In [3]: %timeit u is None
1764 In [3]: %timeit u is None
1765 10000000 loops, best of 3: 184 ns per loop
1765 10000000 loops, best of 3: 184 ns per loop
1766
1766
1767 In [4]: %timeit -r 4 u == None
1767 In [4]: %timeit -r 4 u == None
1768 1000000 loops, best of 4: 242 ns per loop
1768 1000000 loops, best of 4: 242 ns per loop
1769
1769
1770 In [5]: import time
1770 In [5]: import time
1771
1771
1772 In [6]: %timeit -n1 time.sleep(2)
1772 In [6]: %timeit -n1 time.sleep(2)
1773 1 loops, best of 3: 2 s per loop
1773 1 loops, best of 3: 2 s per loop
1774
1774
1775
1775
1776 The times reported by %timeit will be slightly higher than those
1776 The times reported by %timeit will be slightly higher than those
1777 reported by the timeit.py script when variables are accessed. This is
1777 reported by the timeit.py script when variables are accessed. This is
1778 due to the fact that %timeit executes the statement in the namespace
1778 due to the fact that %timeit executes the statement in the namespace
1779 of the shell, compared with timeit.py, which uses a single setup
1779 of the shell, compared with timeit.py, which uses a single setup
1780 statement to import function or create variables. Generally, the bias
1780 statement to import function or create variables. Generally, the bias
1781 does not matter as long as results from timeit.py are not mixed with
1781 does not matter as long as results from timeit.py are not mixed with
1782 those from %timeit."""
1782 those from %timeit."""
1783
1783
1784 import timeit
1784 import timeit
1785 import math
1785 import math
1786
1786
1787 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1787 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1788 # certain terminals. Until we figure out a robust way of
1788 # certain terminals. Until we figure out a robust way of
1789 # auto-detecting if the terminal can deal with it, use plain 'us' for
1789 # auto-detecting if the terminal can deal with it, use plain 'us' for
1790 # microseconds. I am really NOT happy about disabling the proper
1790 # microseconds. I am really NOT happy about disabling the proper
1791 # 'micro' prefix, but crashing is worse... If anyone knows what the
1791 # 'micro' prefix, but crashing is worse... If anyone knows what the
1792 # right solution for this is, I'm all ears...
1792 # right solution for this is, I'm all ears...
1793 #
1793 #
1794 # Note: using
1794 # Note: using
1795 #
1795 #
1796 # s = u'\xb5'
1796 # s = u'\xb5'
1797 # s.encode(sys.getdefaultencoding())
1797 # s.encode(sys.getdefaultencoding())
1798 #
1798 #
1799 # is not sufficient, as I've seen terminals where that fails but
1799 # is not sufficient, as I've seen terminals where that fails but
1800 # print s
1800 # print s
1801 #
1801 #
1802 # succeeds
1802 # succeeds
1803 #
1803 #
1804 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1804 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1805
1805
1806 #units = [u"s", u"ms",u'\xb5',"ns"]
1806 #units = [u"s", u"ms",u'\xb5',"ns"]
1807 units = [u"s", u"ms",u'us',"ns"]
1807 units = [u"s", u"ms",u'us',"ns"]
1808
1808
1809 scaling = [1, 1e3, 1e6, 1e9]
1809 scaling = [1, 1e3, 1e6, 1e9]
1810
1810
1811 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1811 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1812 posix=False)
1812 posix=False)
1813 if stmt == "":
1813 if stmt == "":
1814 return
1814 return
1815 timefunc = timeit.default_timer
1815 timefunc = timeit.default_timer
1816 number = int(getattr(opts, "n", 0))
1816 number = int(getattr(opts, "n", 0))
1817 repeat = int(getattr(opts, "r", timeit.default_repeat))
1817 repeat = int(getattr(opts, "r", timeit.default_repeat))
1818 precision = int(getattr(opts, "p", 3))
1818 precision = int(getattr(opts, "p", 3))
1819 if hasattr(opts, "t"):
1819 if hasattr(opts, "t"):
1820 timefunc = time.time
1820 timefunc = time.time
1821 if hasattr(opts, "c"):
1821 if hasattr(opts, "c"):
1822 timefunc = clock
1822 timefunc = clock
1823
1823
1824 timer = timeit.Timer(timer=timefunc)
1824 timer = timeit.Timer(timer=timefunc)
1825 # this code has tight coupling to the inner workings of timeit.Timer,
1825 # this code has tight coupling to the inner workings of timeit.Timer,
1826 # but is there a better way to achieve that the code stmt has access
1826 # but is there a better way to achieve that the code stmt has access
1827 # to the shell namespace?
1827 # to the shell namespace?
1828
1828
1829 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1829 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1830 'setup': "pass"}
1830 'setup': "pass"}
1831 # Track compilation time so it can be reported if too long
1831 # Track compilation time so it can be reported if too long
1832 # Minimum time above which compilation time will be reported
1832 # Minimum time above which compilation time will be reported
1833 tc_min = 0.1
1833 tc_min = 0.1
1834
1834
1835 t0 = clock()
1835 t0 = clock()
1836 code = compile(src, "<magic-timeit>", "exec")
1836 code = compile(src, "<magic-timeit>", "exec")
1837 tc = clock()-t0
1837 tc = clock()-t0
1838
1838
1839 ns = {}
1839 ns = {}
1840 exec code in self.shell.user_ns, ns
1840 exec code in self.shell.user_ns, ns
1841 timer.inner = ns["inner"]
1841 timer.inner = ns["inner"]
1842
1842
1843 if number == 0:
1843 if number == 0:
1844 # determine number so that 0.2 <= total time < 2.0
1844 # determine number so that 0.2 <= total time < 2.0
1845 number = 1
1845 number = 1
1846 for i in range(1, 10):
1846 for i in range(1, 10):
1847 if timer.timeit(number) >= 0.2:
1847 if timer.timeit(number) >= 0.2:
1848 break
1848 break
1849 number *= 10
1849 number *= 10
1850
1850
1851 best = min(timer.repeat(repeat, number)) / number
1851 best = min(timer.repeat(repeat, number)) / number
1852
1852
1853 if best > 0.0 and best < 1000.0:
1853 if best > 0.0 and best < 1000.0:
1854 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1854 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1855 elif best >= 1000.0:
1855 elif best >= 1000.0:
1856 order = 0
1856 order = 0
1857 else:
1857 else:
1858 order = 3
1858 order = 3
1859 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1859 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1860 precision,
1860 precision,
1861 best * scaling[order],
1861 best * scaling[order],
1862 units[order])
1862 units[order])
1863 if tc > tc_min:
1863 if tc > tc_min:
1864 print "Compiler time: %.2f s" % tc
1864 print "Compiler time: %.2f s" % tc
1865
1865
1866 @testdec.skip_doctest
1866 @testdec.skip_doctest
1867 def magic_time(self,parameter_s = ''):
1867 def magic_time(self,parameter_s = ''):
1868 """Time execution of a Python statement or expression.
1868 """Time execution of a Python statement or expression.
1869
1869
1870 The CPU and wall clock times are printed, and the value of the
1870 The CPU and wall clock times are printed, and the value of the
1871 expression (if any) is returned. Note that under Win32, system time
1871 expression (if any) is returned. Note that under Win32, system time
1872 is always reported as 0, since it can not be measured.
1872 is always reported as 0, since it can not be measured.
1873
1873
1874 This function provides very basic timing functionality. In Python
1874 This function provides very basic timing functionality. In Python
1875 2.3, the timeit module offers more control and sophistication, so this
1875 2.3, the timeit module offers more control and sophistication, so this
1876 could be rewritten to use it (patches welcome).
1876 could be rewritten to use it (patches welcome).
1877
1877
1878 Some examples:
1878 Some examples:
1879
1879
1880 In [1]: time 2**128
1880 In [1]: time 2**128
1881 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1881 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1882 Wall time: 0.00
1882 Wall time: 0.00
1883 Out[1]: 340282366920938463463374607431768211456L
1883 Out[1]: 340282366920938463463374607431768211456L
1884
1884
1885 In [2]: n = 1000000
1885 In [2]: n = 1000000
1886
1886
1887 In [3]: time sum(range(n))
1887 In [3]: time sum(range(n))
1888 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1888 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1889 Wall time: 1.37
1889 Wall time: 1.37
1890 Out[3]: 499999500000L
1890 Out[3]: 499999500000L
1891
1891
1892 In [4]: time print 'hello world'
1892 In [4]: time print 'hello world'
1893 hello world
1893 hello world
1894 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1894 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1895 Wall time: 0.00
1895 Wall time: 0.00
1896
1896
1897 Note that the time needed by Python to compile the given expression
1897 Note that the time needed by Python to compile the given expression
1898 will be reported if it is more than 0.1s. In this example, the
1898 will be reported if it is more than 0.1s. In this example, the
1899 actual exponentiation is done by Python at compilation time, so while
1899 actual exponentiation is done by Python at compilation time, so while
1900 the expression can take a noticeable amount of time to compute, that
1900 the expression can take a noticeable amount of time to compute, that
1901 time is purely due to the compilation:
1901 time is purely due to the compilation:
1902
1902
1903 In [5]: time 3**9999;
1903 In [5]: time 3**9999;
1904 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1904 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1905 Wall time: 0.00 s
1905 Wall time: 0.00 s
1906
1906
1907 In [6]: time 3**999999;
1907 In [6]: time 3**999999;
1908 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1908 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1909 Wall time: 0.00 s
1909 Wall time: 0.00 s
1910 Compiler : 0.78 s
1910 Compiler : 0.78 s
1911 """
1911 """
1912
1912
1913 # fail immediately if the given expression can't be compiled
1913 # fail immediately if the given expression can't be compiled
1914
1914
1915 expr = self.shell.prefilter(parameter_s,False)
1915 expr = self.shell.prefilter(parameter_s,False)
1916
1916
1917 # Minimum time above which compilation time will be reported
1917 # Minimum time above which compilation time will be reported
1918 tc_min = 0.1
1918 tc_min = 0.1
1919
1919
1920 try:
1920 try:
1921 mode = 'eval'
1921 mode = 'eval'
1922 t0 = clock()
1922 t0 = clock()
1923 code = compile(expr,'<timed eval>',mode)
1923 code = compile(expr,'<timed eval>',mode)
1924 tc = clock()-t0
1924 tc = clock()-t0
1925 except SyntaxError:
1925 except SyntaxError:
1926 mode = 'exec'
1926 mode = 'exec'
1927 t0 = clock()
1927 t0 = clock()
1928 code = compile(expr,'<timed exec>',mode)
1928 code = compile(expr,'<timed exec>',mode)
1929 tc = clock()-t0
1929 tc = clock()-t0
1930 # skew measurement as little as possible
1930 # skew measurement as little as possible
1931 glob = self.shell.user_ns
1931 glob = self.shell.user_ns
1932 clk = clock2
1932 clk = clock2
1933 wtime = time.time
1933 wtime = time.time
1934 # time execution
1934 # time execution
1935 wall_st = wtime()
1935 wall_st = wtime()
1936 if mode=='eval':
1936 if mode=='eval':
1937 st = clk()
1937 st = clk()
1938 out = eval(code,glob)
1938 out = eval(code,glob)
1939 end = clk()
1939 end = clk()
1940 else:
1940 else:
1941 st = clk()
1941 st = clk()
1942 exec code in glob
1942 exec code in glob
1943 end = clk()
1943 end = clk()
1944 out = None
1944 out = None
1945 wall_end = wtime()
1945 wall_end = wtime()
1946 # Compute actual times and report
1946 # Compute actual times and report
1947 wall_time = wall_end-wall_st
1947 wall_time = wall_end-wall_st
1948 cpu_user = end[0]-st[0]
1948 cpu_user = end[0]-st[0]
1949 cpu_sys = end[1]-st[1]
1949 cpu_sys = end[1]-st[1]
1950 cpu_tot = cpu_user+cpu_sys
1950 cpu_tot = cpu_user+cpu_sys
1951 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1951 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1952 (cpu_user,cpu_sys,cpu_tot)
1952 (cpu_user,cpu_sys,cpu_tot)
1953 print "Wall time: %.2f s" % wall_time
1953 print "Wall time: %.2f s" % wall_time
1954 if tc > tc_min:
1954 if tc > tc_min:
1955 print "Compiler : %.2f s" % tc
1955 print "Compiler : %.2f s" % tc
1956 return out
1956 return out
1957
1957
1958 @testdec.skip_doctest
1958 @testdec.skip_doctest
1959 def magic_macro(self,parameter_s = ''):
1959 def magic_macro(self,parameter_s = ''):
1960 """Define a set of input lines as a macro for future re-execution.
1960 """Define a set of input lines as a macro for future re-execution.
1961
1961
1962 Usage:\\
1962 Usage:\\
1963 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1963 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1964
1964
1965 Options:
1965 Options:
1966
1966
1967 -r: use 'raw' input. By default, the 'processed' history is used,
1967 -r: use 'raw' input. By default, the 'processed' history is used,
1968 so that magics are loaded in their transformed version to valid
1968 so that magics are loaded in their transformed version to valid
1969 Python. If this option is given, the raw input as typed as the
1969 Python. If this option is given, the raw input as typed as the
1970 command line is used instead.
1970 command line is used instead.
1971
1971
1972 This will define a global variable called `name` which is a string
1972 This will define a global variable called `name` which is a string
1973 made of joining the slices and lines you specify (n1,n2,... numbers
1973 made of joining the slices and lines you specify (n1,n2,... numbers
1974 above) from your input history into a single string. This variable
1974 above) from your input history into a single string. This variable
1975 acts like an automatic function which re-executes those lines as if
1975 acts like an automatic function which re-executes those lines as if
1976 you had typed them. You just type 'name' at the prompt and the code
1976 you had typed them. You just type 'name' at the prompt and the code
1977 executes.
1977 executes.
1978
1978
1979 The notation for indicating number ranges is: n1-n2 means 'use line
1979 The syntax for indicating input ranges is described in %history.
1980 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1981 using the lines numbered 5,6 and 7.
1982
1980
1983 Note: as a 'hidden' feature, you can also use traditional python slice
1981 Note: as a 'hidden' feature, you can also use traditional python slice
1984 notation, where N:M means numbers N through M-1.
1982 notation, where N:M means numbers N through M-1.
1985
1983
1986 For example, if your history contains (%hist prints it):
1984 For example, if your history contains (%hist prints it):
1987
1985
1988 44: x=1
1986 44: x=1
1989 45: y=3
1987 45: y=3
1990 46: z=x+y
1988 46: z=x+y
1991 47: print x
1989 47: print x
1992 48: a=5
1990 48: a=5
1993 49: print 'x',x,'y',y
1991 49: print 'x',x,'y',y
1994
1992
1995 you can create a macro with lines 44 through 47 (included) and line 49
1993 you can create a macro with lines 44 through 47 (included) and line 49
1996 called my_macro with:
1994 called my_macro with:
1997
1995
1998 In [55]: %macro my_macro 44-47 49
1996 In [55]: %macro my_macro 44-47 49
1999
1997
2000 Now, typing `my_macro` (without quotes) will re-execute all this code
1998 Now, typing `my_macro` (without quotes) will re-execute all this code
2001 in one pass.
1999 in one pass.
2002
2000
2003 You don't need to give the line-numbers in order, and any given line
2001 You don't need to give the line-numbers in order, and any given line
2004 number can appear multiple times. You can assemble macros with any
2002 number can appear multiple times. You can assemble macros with any
2005 lines from your input history in any order.
2003 lines from your input history in any order.
2006
2004
2007 The macro is a simple object which holds its value in an attribute,
2005 The macro is a simple object which holds its value in an attribute,
2008 but IPython's display system checks for macros and executes them as
2006 but IPython's display system checks for macros and executes them as
2009 code instead of printing them when you type their name.
2007 code instead of printing them when you type their name.
2010
2008
2011 You can view a macro's contents by explicitly printing it with:
2009 You can view a macro's contents by explicitly printing it with:
2012
2010
2013 'print macro_name'.
2011 'print macro_name'.
2014
2012
2015 For one-off cases which DON'T contain magic function calls in them you
2013 For one-off cases which DON'T contain magic function calls in them you
2016 can obtain similar results by explicitly executing slices from your
2014 can obtain similar results by explicitly executing slices from your
2017 input history with:
2015 input history with:
2018
2016
2019 In [60]: exec In[44:48]+In[49]"""
2017 In [60]: exec In[44:48]+In[49]"""
2020
2018
2021 opts,args = self.parse_options(parameter_s,'r',mode='list')
2019 opts,args = self.parse_options(parameter_s,'r',mode='list')
2022 if not args: # List existing macros
2020 if not args: # List existing macros
2023 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2021 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2024 isinstance(v, Macro))
2022 isinstance(v, Macro))
2025 if len(args) == 1:
2023 if len(args) == 1:
2026 raise UsageError(
2024 raise UsageError(
2027 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2025 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2028 name, ranges = args[0], " ".join(args[1:])
2026 name, ranges = args[0], " ".join(args[1:])
2029
2027
2030 #print 'rng',ranges # dbg
2028 #print 'rng',ranges # dbg
2031 lines = self.extract_input_lines(ranges,'r' in opts)
2029 lines = self.extract_input_lines(ranges,'r' in opts)
2032 macro = Macro(lines)
2030 macro = Macro(lines)
2033 self.shell.define_macro(name, macro)
2031 self.shell.define_macro(name, macro)
2034 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2032 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2035 print 'Macro contents:'
2033 print 'Macro contents:'
2036 print macro,
2034 print macro,
2037
2035
2038 def magic_save(self,parameter_s = ''):
2036 def magic_save(self,parameter_s = ''):
2039 """Save a set of lines to a given filename.
2037 """Save a set of lines to a given filename.
2040
2038
2041 Usage:\\
2039 Usage:\\
2042 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2040 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2043
2041
2044 Options:
2042 Options:
2045
2043
2046 -r: use 'raw' input. By default, the 'processed' history is used,
2044 -r: use 'raw' input. By default, the 'processed' history is used,
2047 so that magics are loaded in their transformed version to valid
2045 so that magics are loaded in their transformed version to valid
2048 Python. If this option is given, the raw input as typed as the
2046 Python. If this option is given, the raw input as typed as the
2049 command line is used instead.
2047 command line is used instead.
2050
2048
2051 This function uses the same syntax as %macro for line extraction, but
2049 This function uses the same syntax as %history for input ranges,
2052 instead of creating a macro it saves the resulting string to the
2050 then saves the lines to the filename you specify.
2053 filename you specify.
2054
2051
2055 It adds a '.py' extension to the file if you don't do so yourself, and
2052 It adds a '.py' extension to the file if you don't do so yourself, and
2056 it asks for confirmation before overwriting existing files."""
2053 it asks for confirmation before overwriting existing files."""
2057
2054
2058 opts,args = self.parse_options(parameter_s,'r',mode='list')
2055 opts,args = self.parse_options(parameter_s,'r',mode='list')
2059 fname,ranges = args[0], " ".join(args[1:])
2056 fname,ranges = args[0], " ".join(args[1:])
2060 if not fname.endswith('.py'):
2057 if not fname.endswith('.py'):
2061 fname += '.py'
2058 fname += '.py'
2062 if os.path.isfile(fname):
2059 if os.path.isfile(fname):
2063 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2060 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2064 if ans.lower() not in ['y','yes']:
2061 if ans.lower() not in ['y','yes']:
2065 print 'Operation cancelled.'
2062 print 'Operation cancelled.'
2066 return
2063 return
2067 cmds = self.extract_input_lines(ranges, 'r' in opts)
2064 cmds = self.extract_input_lines(ranges, 'r' in opts)
2068 with open(fname,'w') as f:
2065 with open(fname,'w') as f:
2069 f.write(cmds)
2066 f.write(cmds)
2070 print 'The following commands were written to file `%s`:' % fname
2067 print 'The following commands were written to file `%s`:' % fname
2071 print cmds
2068 print cmds
2072
2069
2073 def _edit_macro(self,mname,macro):
2070 def _edit_macro(self,mname,macro):
2074 """open an editor with the macro data in a file"""
2071 """open an editor with the macro data in a file"""
2075 filename = self.shell.mktempfile(macro.value)
2072 filename = self.shell.mktempfile(macro.value)
2076 self.shell.hooks.editor(filename)
2073 self.shell.hooks.editor(filename)
2077
2074
2078 # and make a new macro object, to replace the old one
2075 # and make a new macro object, to replace the old one
2079 mfile = open(filename)
2076 mfile = open(filename)
2080 mvalue = mfile.read()
2077 mvalue = mfile.read()
2081 mfile.close()
2078 mfile.close()
2082 self.shell.user_ns[mname] = Macro(mvalue)
2079 self.shell.user_ns[mname] = Macro(mvalue)
2083
2080
2084 def magic_ed(self,parameter_s=''):
2081 def magic_ed(self,parameter_s=''):
2085 """Alias to %edit."""
2082 """Alias to %edit."""
2086 return self.magic_edit(parameter_s)
2083 return self.magic_edit(parameter_s)
2087
2084
2088 @testdec.skip_doctest
2085 @testdec.skip_doctest
2089 def magic_edit(self,parameter_s='',last_call=['','']):
2086 def magic_edit(self,parameter_s='',last_call=['','']):
2090 """Bring up an editor and execute the resulting code.
2087 """Bring up an editor and execute the resulting code.
2091
2088
2092 Usage:
2089 Usage:
2093 %edit [options] [args]
2090 %edit [options] [args]
2094
2091
2095 %edit runs IPython's editor hook. The default version of this hook is
2092 %edit runs IPython's editor hook. The default version of this hook is
2096 set to call the __IPYTHON__.rc.editor command. This is read from your
2093 set to call the __IPYTHON__.rc.editor command. This is read from your
2097 environment variable $EDITOR. If this isn't found, it will default to
2094 environment variable $EDITOR. If this isn't found, it will default to
2098 vi under Linux/Unix and to notepad under Windows. See the end of this
2095 vi under Linux/Unix and to notepad under Windows. See the end of this
2099 docstring for how to change the editor hook.
2096 docstring for how to change the editor hook.
2100
2097
2101 You can also set the value of this editor via the command line option
2098 You can also set the value of this editor via the command line option
2102 '-editor' or in your ipythonrc file. This is useful if you wish to use
2099 '-editor' or in your ipythonrc file. This is useful if you wish to use
2103 specifically for IPython an editor different from your typical default
2100 specifically for IPython an editor different from your typical default
2104 (and for Windows users who typically don't set environment variables).
2101 (and for Windows users who typically don't set environment variables).
2105
2102
2106 This command allows you to conveniently edit multi-line code right in
2103 This command allows you to conveniently edit multi-line code right in
2107 your IPython session.
2104 your IPython session.
2108
2105
2109 If called without arguments, %edit opens up an empty editor with a
2106 If called without arguments, %edit opens up an empty editor with a
2110 temporary file and will execute the contents of this file when you
2107 temporary file and will execute the contents of this file when you
2111 close it (don't forget to save it!).
2108 close it (don't forget to save it!).
2112
2109
2113
2110
2114 Options:
2111 Options:
2115
2112
2116 -n <number>: open the editor at a specified line number. By default,
2113 -n <number>: open the editor at a specified line number. By default,
2117 the IPython editor hook uses the unix syntax 'editor +N filename', but
2114 the IPython editor hook uses the unix syntax 'editor +N filename', but
2118 you can configure this by providing your own modified hook if your
2115 you can configure this by providing your own modified hook if your
2119 favorite editor supports line-number specifications with a different
2116 favorite editor supports line-number specifications with a different
2120 syntax.
2117 syntax.
2121
2118
2122 -p: this will call the editor with the same data as the previous time
2119 -p: this will call the editor with the same data as the previous time
2123 it was used, regardless of how long ago (in your current session) it
2120 it was used, regardless of how long ago (in your current session) it
2124 was.
2121 was.
2125
2122
2126 -r: use 'raw' input. This option only applies to input taken from the
2123 -r: use 'raw' input. This option only applies to input taken from the
2127 user's history. By default, the 'processed' history is used, so that
2124 user's history. By default, the 'processed' history is used, so that
2128 magics are loaded in their transformed version to valid Python. If
2125 magics are loaded in their transformed version to valid Python. If
2129 this option is given, the raw input as typed as the command line is
2126 this option is given, the raw input as typed as the command line is
2130 used instead. When you exit the editor, it will be executed by
2127 used instead. When you exit the editor, it will be executed by
2131 IPython's own processor.
2128 IPython's own processor.
2132
2129
2133 -x: do not execute the edited code immediately upon exit. This is
2130 -x: do not execute the edited code immediately upon exit. This is
2134 mainly useful if you are editing programs which need to be called with
2131 mainly useful if you are editing programs which need to be called with
2135 command line arguments, which you can then do using %run.
2132 command line arguments, which you can then do using %run.
2136
2133
2137
2134
2138 Arguments:
2135 Arguments:
2139
2136
2140 If arguments are given, the following possibilites exist:
2137 If arguments are given, the following possibilites exist:
2141
2138
2142 - The arguments are numbers or pairs of colon-separated numbers (like
2139 - If the argument is a filename, IPython will load that into the
2143 1 4:8 9). These are interpreted as lines of previous input to be
2140 editor. It will execute its contents with execfile() when you exit,
2144 loaded into the editor. The syntax is the same of the %macro command.
2141 loading any code in the file into your interactive namespace.
2142
2143 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
2144 The syntax is the same as in the %history magic.
2145
2145
2146 - If the argument doesn't start with a number, it is evaluated as a
2146 - If the argument is a string variable, its contents are loaded
2147 variable and its contents loaded into the editor. You can thus edit
2147 into the editor. You can thus edit any string which contains
2148 any string which contains python code (including the result of
2148 python code (including the result of previous edits).
2149 previous edits).
2150
2149
2151 - If the argument is the name of an object (other than a string),
2150 - If the argument is the name of an object (other than a string),
2152 IPython will try to locate the file where it was defined and open the
2151 IPython will try to locate the file where it was defined and open the
2153 editor at the point where it is defined. You can use `%edit function`
2152 editor at the point where it is defined. You can use `%edit function`
2154 to load an editor exactly at the point where 'function' is defined,
2153 to load an editor exactly at the point where 'function' is defined,
2155 edit it and have the file be executed automatically.
2154 edit it and have the file be executed automatically.
2156
2155
2157 If the object is a macro (see %macro for details), this opens up your
2156 If the object is a macro (see %macro for details), this opens up your
2158 specified editor with a temporary file containing the macro's data.
2157 specified editor with a temporary file containing the macro's data.
2159 Upon exit, the macro is reloaded with the contents of the file.
2158 Upon exit, the macro is reloaded with the contents of the file.
2160
2159
2161 Note: opening at an exact line is only supported under Unix, and some
2160 Note: opening at an exact line is only supported under Unix, and some
2162 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2161 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2163 '+NUMBER' parameter necessary for this feature. Good editors like
2162 '+NUMBER' parameter necessary for this feature. Good editors like
2164 (X)Emacs, vi, jed, pico and joe all do.
2163 (X)Emacs, vi, jed, pico and joe all do.
2165
2164
2166 - If the argument is not found as a variable, IPython will look for a
2167 file with that name (adding .py if necessary) and load it into the
2168 editor. It will execute its contents with execfile() when you exit,
2169 loading any code in the file into your interactive namespace.
2170
2171 After executing your code, %edit will return as output the code you
2165 After executing your code, %edit will return as output the code you
2172 typed in the editor (except when it was an existing file). This way
2166 typed in the editor (except when it was an existing file). This way
2173 you can reload the code in further invocations of %edit as a variable,
2167 you can reload the code in further invocations of %edit as a variable,
2174 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2168 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2175 the output.
2169 the output.
2176
2170
2177 Note that %edit is also available through the alias %ed.
2171 Note that %edit is also available through the alias %ed.
2178
2172
2179 This is an example of creating a simple function inside the editor and
2173 This is an example of creating a simple function inside the editor and
2180 then modifying it. First, start up the editor:
2174 then modifying it. First, start up the editor:
2181
2175
2182 In [1]: ed
2176 In [1]: ed
2183 Editing... done. Executing edited code...
2177 Editing... done. Executing edited code...
2184 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2178 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2185
2179
2186 We can then call the function foo():
2180 We can then call the function foo():
2187
2181
2188 In [2]: foo()
2182 In [2]: foo()
2189 foo() was defined in an editing session
2183 foo() was defined in an editing session
2190
2184
2191 Now we edit foo. IPython automatically loads the editor with the
2185 Now we edit foo. IPython automatically loads the editor with the
2192 (temporary) file where foo() was previously defined:
2186 (temporary) file where foo() was previously defined:
2193
2187
2194 In [3]: ed foo
2188 In [3]: ed foo
2195 Editing... done. Executing edited code...
2189 Editing... done. Executing edited code...
2196
2190
2197 And if we call foo() again we get the modified version:
2191 And if we call foo() again we get the modified version:
2198
2192
2199 In [4]: foo()
2193 In [4]: foo()
2200 foo() has now been changed!
2194 foo() has now been changed!
2201
2195
2202 Here is an example of how to edit a code snippet successive
2196 Here is an example of how to edit a code snippet successive
2203 times. First we call the editor:
2197 times. First we call the editor:
2204
2198
2205 In [5]: ed
2199 In [5]: ed
2206 Editing... done. Executing edited code...
2200 Editing... done. Executing edited code...
2207 hello
2201 hello
2208 Out[5]: "print 'hello'n"
2202 Out[5]: "print 'hello'n"
2209
2203
2210 Now we call it again with the previous output (stored in _):
2204 Now we call it again with the previous output (stored in _):
2211
2205
2212 In [6]: ed _
2206 In [6]: ed _
2213 Editing... done. Executing edited code...
2207 Editing... done. Executing edited code...
2214 hello world
2208 hello world
2215 Out[6]: "print 'hello world'n"
2209 Out[6]: "print 'hello world'n"
2216
2210
2217 Now we call it with the output #8 (stored in _8, also as Out[8]):
2211 Now we call it with the output #8 (stored in _8, also as Out[8]):
2218
2212
2219 In [7]: ed _8
2213 In [7]: ed _8
2220 Editing... done. Executing edited code...
2214 Editing... done. Executing edited code...
2221 hello again
2215 hello again
2222 Out[7]: "print 'hello again'n"
2216 Out[7]: "print 'hello again'n"
2223
2217
2224
2218
2225 Changing the default editor hook:
2219 Changing the default editor hook:
2226
2220
2227 If you wish to write your own editor hook, you can put it in a
2221 If you wish to write your own editor hook, you can put it in a
2228 configuration file which you load at startup time. The default hook
2222 configuration file which you load at startup time. The default hook
2229 is defined in the IPython.core.hooks module, and you can use that as a
2223 is defined in the IPython.core.hooks module, and you can use that as a
2230 starting example for further modifications. That file also has
2224 starting example for further modifications. That file also has
2231 general instructions on how to set a new hook for use once you've
2225 general instructions on how to set a new hook for use once you've
2232 defined it."""
2226 defined it."""
2233
2227
2234 # FIXME: This function has become a convoluted mess. It needs a
2228 # FIXME: This function has become a convoluted mess. It needs a
2235 # ground-up rewrite with clean, simple logic.
2229 # ground-up rewrite with clean, simple logic.
2236
2230
2237 def make_filename(arg):
2231 def make_filename(arg):
2238 "Make a filename from the given args"
2232 "Make a filename from the given args"
2239 try:
2233 try:
2240 filename = get_py_filename(arg)
2234 filename = get_py_filename(arg)
2241 except IOError:
2235 except IOError:
2242 if args.endswith('.py'):
2236 if args.endswith('.py'):
2243 filename = arg
2237 filename = arg
2244 else:
2238 else:
2245 filename = None
2239 filename = None
2246 return filename
2240 return filename
2247
2241
2248 # custom exceptions
2242 # custom exceptions
2249 class DataIsObject(Exception): pass
2243 class DataIsObject(Exception): pass
2250
2244
2251 opts,args = self.parse_options(parameter_s,'prxn:')
2245 opts,args = self.parse_options(parameter_s,'prxn:')
2252 # Set a few locals from the options for convenience:
2246 # Set a few locals from the options for convenience:
2253 opts_prev = 'p' in opts
2247 opts_prev = 'p' in opts
2254 opts_raw = 'r' in opts
2248 opts_raw = 'r' in opts
2255
2249
2256 # Default line number value
2250 # Default line number value
2257 lineno = opts.get('n',None)
2251 lineno = opts.get('n',None)
2258
2252
2259 if opts_prev:
2253 if opts_prev:
2260 args = '_%s' % last_call[0]
2254 args = '_%s' % last_call[0]
2261 if not self.shell.user_ns.has_key(args):
2255 if not self.shell.user_ns.has_key(args):
2262 args = last_call[1]
2256 args = last_call[1]
2263
2257
2264 # use last_call to remember the state of the previous call, but don't
2258 # use last_call to remember the state of the previous call, but don't
2265 # let it be clobbered by successive '-p' calls.
2259 # let it be clobbered by successive '-p' calls.
2266 try:
2260 try:
2267 last_call[0] = self.shell.displayhook.prompt_count
2261 last_call[0] = self.shell.displayhook.prompt_count
2268 if not opts_prev:
2262 if not opts_prev:
2269 last_call[1] = parameter_s
2263 last_call[1] = parameter_s
2270 except:
2264 except:
2271 pass
2265 pass
2272
2266
2273 # by default this is done with temp files, except when the given
2267 # by default this is done with temp files, except when the given
2274 # arg is a filename
2268 # arg is a filename
2275 use_temp = True
2269 use_temp = True
2276
2270
2277 data = ''
2271 data = ''
2278 if args.endswith('.py'):
2272 if args.endswith('.py'):
2279 filename = make_filename(args)
2273 filename = make_filename(args)
2280 use_temp = False
2274 use_temp = False
2281 elif args:
2275 elif args:
2282 # Mode where user specifies ranges of lines, like in %macro.
2276 # Mode where user specifies ranges of lines, like in %macro.
2283 data = self.extract_input_lines(args, opts_raw)
2277 data = self.extract_input_lines(args, opts_raw)
2284 if not data:
2278 if not data:
2285 try:
2279 try:
2286 # Load the parameter given as a variable. If not a string,
2280 # Load the parameter given as a variable. If not a string,
2287 # process it as an object instead (below)
2281 # process it as an object instead (below)
2288
2282
2289 #print '*** args',args,'type',type(args) # dbg
2283 #print '*** args',args,'type',type(args) # dbg
2290 data = eval(args, self.shell.user_ns)
2284 data = eval(args, self.shell.user_ns)
2291 if not isinstance(data, basestring):
2285 if not isinstance(data, basestring):
2292 raise DataIsObject
2286 raise DataIsObject
2293
2287
2294 except (NameError,SyntaxError):
2288 except (NameError,SyntaxError):
2295 # given argument is not a variable, try as a filename
2289 # given argument is not a variable, try as a filename
2296 filename = make_filename(args)
2290 filename = make_filename(args)
2297 if filename is None:
2291 if filename is None:
2298 warn("Argument given (%s) can't be found as a variable "
2292 warn("Argument given (%s) can't be found as a variable "
2299 "or as a filename." % args)
2293 "or as a filename." % args)
2300 return
2294 return
2301 use_temp = False
2295 use_temp = False
2302
2296
2303 except DataIsObject:
2297 except DataIsObject:
2304 # macros have a special edit function
2298 # macros have a special edit function
2305 if isinstance(data, Macro):
2299 if isinstance(data, Macro):
2306 self._edit_macro(args,data)
2300 self._edit_macro(args,data)
2307 return
2301 return
2308
2302
2309 # For objects, try to edit the file where they are defined
2303 # For objects, try to edit the file where they are defined
2310 try:
2304 try:
2311 filename = inspect.getabsfile(data)
2305 filename = inspect.getabsfile(data)
2312 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2306 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2313 # class created by %edit? Try to find source
2307 # class created by %edit? Try to find source
2314 # by looking for method definitions instead, the
2308 # by looking for method definitions instead, the
2315 # __module__ in those classes is FakeModule.
2309 # __module__ in those classes is FakeModule.
2316 attrs = [getattr(data, aname) for aname in dir(data)]
2310 attrs = [getattr(data, aname) for aname in dir(data)]
2317 for attr in attrs:
2311 for attr in attrs:
2318 if not inspect.ismethod(attr):
2312 if not inspect.ismethod(attr):
2319 continue
2313 continue
2320 filename = inspect.getabsfile(attr)
2314 filename = inspect.getabsfile(attr)
2321 if filename and 'fakemodule' not in filename.lower():
2315 if filename and 'fakemodule' not in filename.lower():
2322 # change the attribute to be the edit target instead
2316 # change the attribute to be the edit target instead
2323 data = attr
2317 data = attr
2324 break
2318 break
2325
2319
2326 datafile = 1
2320 datafile = 1
2327 except TypeError:
2321 except TypeError:
2328 filename = make_filename(args)
2322 filename = make_filename(args)
2329 datafile = 1
2323 datafile = 1
2330 warn('Could not find file where `%s` is defined.\n'
2324 warn('Could not find file where `%s` is defined.\n'
2331 'Opening a file named `%s`' % (args,filename))
2325 'Opening a file named `%s`' % (args,filename))
2332 # Now, make sure we can actually read the source (if it was in
2326 # Now, make sure we can actually read the source (if it was in
2333 # a temp file it's gone by now).
2327 # a temp file it's gone by now).
2334 if datafile:
2328 if datafile:
2335 try:
2329 try:
2336 if lineno is None:
2330 if lineno is None:
2337 lineno = inspect.getsourcelines(data)[1]
2331 lineno = inspect.getsourcelines(data)[1]
2338 except IOError:
2332 except IOError:
2339 filename = make_filename(args)
2333 filename = make_filename(args)
2340 if filename is None:
2334 if filename is None:
2341 warn('The file `%s` where `%s` was defined cannot '
2335 warn('The file `%s` where `%s` was defined cannot '
2342 'be read.' % (filename,data))
2336 'be read.' % (filename,data))
2343 return
2337 return
2344 use_temp = False
2338 use_temp = False
2345
2339
2346 if use_temp:
2340 if use_temp:
2347 filename = self.shell.mktempfile(data)
2341 filename = self.shell.mktempfile(data)
2348 print 'IPython will make a temporary file named:',filename
2342 print 'IPython will make a temporary file named:',filename
2349
2343
2350 # do actual editing here
2344 # do actual editing here
2351 print 'Editing...',
2345 print 'Editing...',
2352 sys.stdout.flush()
2346 sys.stdout.flush()
2353 try:
2347 try:
2354 # Quote filenames that may have spaces in them
2348 # Quote filenames that may have spaces in them
2355 if ' ' in filename:
2349 if ' ' in filename:
2356 filename = "%s" % filename
2350 filename = "%s" % filename
2357 self.shell.hooks.editor(filename,lineno)
2351 self.shell.hooks.editor(filename,lineno)
2358 except TryNext:
2352 except TryNext:
2359 warn('Could not open editor')
2353 warn('Could not open editor')
2360 return
2354 return
2361
2355
2362 # XXX TODO: should this be generalized for all string vars?
2356 # XXX TODO: should this be generalized for all string vars?
2363 # For now, this is special-cased to blocks created by cpaste
2357 # For now, this is special-cased to blocks created by cpaste
2364 if args.strip() == 'pasted_block':
2358 if args.strip() == 'pasted_block':
2365 self.shell.user_ns['pasted_block'] = file_read(filename)
2359 self.shell.user_ns['pasted_block'] = file_read(filename)
2366
2360
2367 if 'x' in opts: # -x prevents actual execution
2361 if 'x' in opts: # -x prevents actual execution
2368 print
2362 print
2369 else:
2363 else:
2370 print 'done. Executing edited code...'
2364 print 'done. Executing edited code...'
2371 if opts_raw:
2365 if opts_raw:
2372 self.shell.run_cell(file_read(filename),
2366 self.shell.run_cell(file_read(filename),
2373 store_history=False)
2367 store_history=False)
2374 else:
2368 else:
2375 self.shell.safe_execfile(filename,self.shell.user_ns,
2369 self.shell.safe_execfile(filename,self.shell.user_ns,
2376 self.shell.user_ns)
2370 self.shell.user_ns)
2377
2371
2378
2372
2379 if use_temp:
2373 if use_temp:
2380 try:
2374 try:
2381 return open(filename).read()
2375 return open(filename).read()
2382 except IOError,msg:
2376 except IOError,msg:
2383 if msg.filename == filename:
2377 if msg.filename == filename:
2384 warn('File not found. Did you forget to save?')
2378 warn('File not found. Did you forget to save?')
2385 return
2379 return
2386 else:
2380 else:
2387 self.shell.showtraceback()
2381 self.shell.showtraceback()
2388
2382
2389 def magic_xmode(self,parameter_s = ''):
2383 def magic_xmode(self,parameter_s = ''):
2390 """Switch modes for the exception handlers.
2384 """Switch modes for the exception handlers.
2391
2385
2392 Valid modes: Plain, Context and Verbose.
2386 Valid modes: Plain, Context and Verbose.
2393
2387
2394 If called without arguments, acts as a toggle."""
2388 If called without arguments, acts as a toggle."""
2395
2389
2396 def xmode_switch_err(name):
2390 def xmode_switch_err(name):
2397 warn('Error changing %s exception modes.\n%s' %
2391 warn('Error changing %s exception modes.\n%s' %
2398 (name,sys.exc_info()[1]))
2392 (name,sys.exc_info()[1]))
2399
2393
2400 shell = self.shell
2394 shell = self.shell
2401 new_mode = parameter_s.strip().capitalize()
2395 new_mode = parameter_s.strip().capitalize()
2402 try:
2396 try:
2403 shell.InteractiveTB.set_mode(mode=new_mode)
2397 shell.InteractiveTB.set_mode(mode=new_mode)
2404 print 'Exception reporting mode:',shell.InteractiveTB.mode
2398 print 'Exception reporting mode:',shell.InteractiveTB.mode
2405 except:
2399 except:
2406 xmode_switch_err('user')
2400 xmode_switch_err('user')
2407
2401
2408 def magic_colors(self,parameter_s = ''):
2402 def magic_colors(self,parameter_s = ''):
2409 """Switch color scheme for prompts, info system and exception handlers.
2403 """Switch color scheme for prompts, info system and exception handlers.
2410
2404
2411 Currently implemented schemes: NoColor, Linux, LightBG.
2405 Currently implemented schemes: NoColor, Linux, LightBG.
2412
2406
2413 Color scheme names are not case-sensitive.
2407 Color scheme names are not case-sensitive.
2414
2408
2415 Examples
2409 Examples
2416 --------
2410 --------
2417 To get a plain black and white terminal::
2411 To get a plain black and white terminal::
2418
2412
2419 %colors nocolor
2413 %colors nocolor
2420 """
2414 """
2421
2415
2422 def color_switch_err(name):
2416 def color_switch_err(name):
2423 warn('Error changing %s color schemes.\n%s' %
2417 warn('Error changing %s color schemes.\n%s' %
2424 (name,sys.exc_info()[1]))
2418 (name,sys.exc_info()[1]))
2425
2419
2426
2420
2427 new_scheme = parameter_s.strip()
2421 new_scheme = parameter_s.strip()
2428 if not new_scheme:
2422 if not new_scheme:
2429 raise UsageError(
2423 raise UsageError(
2430 "%colors: you must specify a color scheme. See '%colors?'")
2424 "%colors: you must specify a color scheme. See '%colors?'")
2431 return
2425 return
2432 # local shortcut
2426 # local shortcut
2433 shell = self.shell
2427 shell = self.shell
2434
2428
2435 import IPython.utils.rlineimpl as readline
2429 import IPython.utils.rlineimpl as readline
2436
2430
2437 if not readline.have_readline and sys.platform == "win32":
2431 if not readline.have_readline and sys.platform == "win32":
2438 msg = """\
2432 msg = """\
2439 Proper color support under MS Windows requires the pyreadline library.
2433 Proper color support under MS Windows requires the pyreadline library.
2440 You can find it at:
2434 You can find it at:
2441 http://ipython.scipy.org/moin/PyReadline/Intro
2435 http://ipython.scipy.org/moin/PyReadline/Intro
2442 Gary's readline needs the ctypes module, from:
2436 Gary's readline needs the ctypes module, from:
2443 http://starship.python.net/crew/theller/ctypes
2437 http://starship.python.net/crew/theller/ctypes
2444 (Note that ctypes is already part of Python versions 2.5 and newer).
2438 (Note that ctypes is already part of Python versions 2.5 and newer).
2445
2439
2446 Defaulting color scheme to 'NoColor'"""
2440 Defaulting color scheme to 'NoColor'"""
2447 new_scheme = 'NoColor'
2441 new_scheme = 'NoColor'
2448 warn(msg)
2442 warn(msg)
2449
2443
2450 # readline option is 0
2444 # readline option is 0
2451 if not shell.has_readline:
2445 if not shell.has_readline:
2452 new_scheme = 'NoColor'
2446 new_scheme = 'NoColor'
2453
2447
2454 # Set prompt colors
2448 # Set prompt colors
2455 try:
2449 try:
2456 shell.displayhook.set_colors(new_scheme)
2450 shell.displayhook.set_colors(new_scheme)
2457 except:
2451 except:
2458 color_switch_err('prompt')
2452 color_switch_err('prompt')
2459 else:
2453 else:
2460 shell.colors = \
2454 shell.colors = \
2461 shell.displayhook.color_table.active_scheme_name
2455 shell.displayhook.color_table.active_scheme_name
2462 # Set exception colors
2456 # Set exception colors
2463 try:
2457 try:
2464 shell.InteractiveTB.set_colors(scheme = new_scheme)
2458 shell.InteractiveTB.set_colors(scheme = new_scheme)
2465 shell.SyntaxTB.set_colors(scheme = new_scheme)
2459 shell.SyntaxTB.set_colors(scheme = new_scheme)
2466 except:
2460 except:
2467 color_switch_err('exception')
2461 color_switch_err('exception')
2468
2462
2469 # Set info (for 'object?') colors
2463 # Set info (for 'object?') colors
2470 if shell.color_info:
2464 if shell.color_info:
2471 try:
2465 try:
2472 shell.inspector.set_active_scheme(new_scheme)
2466 shell.inspector.set_active_scheme(new_scheme)
2473 except:
2467 except:
2474 color_switch_err('object inspector')
2468 color_switch_err('object inspector')
2475 else:
2469 else:
2476 shell.inspector.set_active_scheme('NoColor')
2470 shell.inspector.set_active_scheme('NoColor')
2477
2471
2478 def magic_pprint(self, parameter_s=''):
2472 def magic_pprint(self, parameter_s=''):
2479 """Toggle pretty printing on/off."""
2473 """Toggle pretty printing on/off."""
2480 ptformatter = self.shell.display_formatter.formatters['text/plain']
2474 ptformatter = self.shell.display_formatter.formatters['text/plain']
2481 ptformatter.pprint = bool(1 - ptformatter.pprint)
2475 ptformatter.pprint = bool(1 - ptformatter.pprint)
2482 print 'Pretty printing has been turned', \
2476 print 'Pretty printing has been turned', \
2483 ['OFF','ON'][ptformatter.pprint]
2477 ['OFF','ON'][ptformatter.pprint]
2484
2478
2485 def magic_Exit(self, parameter_s=''):
2479 def magic_Exit(self, parameter_s=''):
2486 """Exit IPython."""
2480 """Exit IPython."""
2487
2481
2488 self.shell.ask_exit()
2482 self.shell.ask_exit()
2489
2483
2490 # Add aliases as magics so all common forms work: exit, quit, Exit, Quit.
2484 # Add aliases as magics so all common forms work: exit, quit, Exit, Quit.
2491 magic_exit = magic_quit = magic_Quit = magic_Exit
2485 magic_exit = magic_quit = magic_Quit = magic_Exit
2492
2486
2493 #......................................................................
2487 #......................................................................
2494 # Functions to implement unix shell-type things
2488 # Functions to implement unix shell-type things
2495
2489
2496 @testdec.skip_doctest
2490 @testdec.skip_doctest
2497 def magic_alias(self, parameter_s = ''):
2491 def magic_alias(self, parameter_s = ''):
2498 """Define an alias for a system command.
2492 """Define an alias for a system command.
2499
2493
2500 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2494 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2501
2495
2502 Then, typing 'alias_name params' will execute the system command 'cmd
2496 Then, typing 'alias_name params' will execute the system command 'cmd
2503 params' (from your underlying operating system).
2497 params' (from your underlying operating system).
2504
2498
2505 Aliases have lower precedence than magic functions and Python normal
2499 Aliases have lower precedence than magic functions and Python normal
2506 variables, so if 'foo' is both a Python variable and an alias, the
2500 variables, so if 'foo' is both a Python variable and an alias, the
2507 alias can not be executed until 'del foo' removes the Python variable.
2501 alias can not be executed until 'del foo' removes the Python variable.
2508
2502
2509 You can use the %l specifier in an alias definition to represent the
2503 You can use the %l specifier in an alias definition to represent the
2510 whole line when the alias is called. For example:
2504 whole line when the alias is called. For example:
2511
2505
2512 In [2]: alias bracket echo "Input in brackets: <%l>"
2506 In [2]: alias bracket echo "Input in brackets: <%l>"
2513 In [3]: bracket hello world
2507 In [3]: bracket hello world
2514 Input in brackets: <hello world>
2508 Input in brackets: <hello world>
2515
2509
2516 You can also define aliases with parameters using %s specifiers (one
2510 You can also define aliases with parameters using %s specifiers (one
2517 per parameter):
2511 per parameter):
2518
2512
2519 In [1]: alias parts echo first %s second %s
2513 In [1]: alias parts echo first %s second %s
2520 In [2]: %parts A B
2514 In [2]: %parts A B
2521 first A second B
2515 first A second B
2522 In [3]: %parts A
2516 In [3]: %parts A
2523 Incorrect number of arguments: 2 expected.
2517 Incorrect number of arguments: 2 expected.
2524 parts is an alias to: 'echo first %s second %s'
2518 parts is an alias to: 'echo first %s second %s'
2525
2519
2526 Note that %l and %s are mutually exclusive. You can only use one or
2520 Note that %l and %s are mutually exclusive. You can only use one or
2527 the other in your aliases.
2521 the other in your aliases.
2528
2522
2529 Aliases expand Python variables just like system calls using ! or !!
2523 Aliases expand Python variables just like system calls using ! or !!
2530 do: all expressions prefixed with '$' get expanded. For details of
2524 do: all expressions prefixed with '$' get expanded. For details of
2531 the semantic rules, see PEP-215:
2525 the semantic rules, see PEP-215:
2532 http://www.python.org/peps/pep-0215.html. This is the library used by
2526 http://www.python.org/peps/pep-0215.html. This is the library used by
2533 IPython for variable expansion. If you want to access a true shell
2527 IPython for variable expansion. If you want to access a true shell
2534 variable, an extra $ is necessary to prevent its expansion by IPython:
2528 variable, an extra $ is necessary to prevent its expansion by IPython:
2535
2529
2536 In [6]: alias show echo
2530 In [6]: alias show echo
2537 In [7]: PATH='A Python string'
2531 In [7]: PATH='A Python string'
2538 In [8]: show $PATH
2532 In [8]: show $PATH
2539 A Python string
2533 A Python string
2540 In [9]: show $$PATH
2534 In [9]: show $$PATH
2541 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2535 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2542
2536
2543 You can use the alias facility to acess all of $PATH. See the %rehash
2537 You can use the alias facility to acess all of $PATH. See the %rehash
2544 and %rehashx functions, which automatically create aliases for the
2538 and %rehashx functions, which automatically create aliases for the
2545 contents of your $PATH.
2539 contents of your $PATH.
2546
2540
2547 If called with no parameters, %alias prints the current alias table."""
2541 If called with no parameters, %alias prints the current alias table."""
2548
2542
2549 par = parameter_s.strip()
2543 par = parameter_s.strip()
2550 if not par:
2544 if not par:
2551 stored = self.db.get('stored_aliases', {} )
2545 stored = self.db.get('stored_aliases', {} )
2552 aliases = sorted(self.shell.alias_manager.aliases)
2546 aliases = sorted(self.shell.alias_manager.aliases)
2553 # for k, v in stored:
2547 # for k, v in stored:
2554 # atab.append(k, v[0])
2548 # atab.append(k, v[0])
2555
2549
2556 print "Total number of aliases:", len(aliases)
2550 print "Total number of aliases:", len(aliases)
2557 sys.stdout.flush()
2551 sys.stdout.flush()
2558 return aliases
2552 return aliases
2559
2553
2560 # Now try to define a new one
2554 # Now try to define a new one
2561 try:
2555 try:
2562 alias,cmd = par.split(None, 1)
2556 alias,cmd = par.split(None, 1)
2563 except:
2557 except:
2564 print oinspect.getdoc(self.magic_alias)
2558 print oinspect.getdoc(self.magic_alias)
2565 else:
2559 else:
2566 self.shell.alias_manager.soft_define_alias(alias, cmd)
2560 self.shell.alias_manager.soft_define_alias(alias, cmd)
2567 # end magic_alias
2561 # end magic_alias
2568
2562
2569 def magic_unalias(self, parameter_s = ''):
2563 def magic_unalias(self, parameter_s = ''):
2570 """Remove an alias"""
2564 """Remove an alias"""
2571
2565
2572 aname = parameter_s.strip()
2566 aname = parameter_s.strip()
2573 self.shell.alias_manager.undefine_alias(aname)
2567 self.shell.alias_manager.undefine_alias(aname)
2574 stored = self.db.get('stored_aliases', {} )
2568 stored = self.db.get('stored_aliases', {} )
2575 if aname in stored:
2569 if aname in stored:
2576 print "Removing %stored alias",aname
2570 print "Removing %stored alias",aname
2577 del stored[aname]
2571 del stored[aname]
2578 self.db['stored_aliases'] = stored
2572 self.db['stored_aliases'] = stored
2579
2573
2580 def magic_rehashx(self, parameter_s = ''):
2574 def magic_rehashx(self, parameter_s = ''):
2581 """Update the alias table with all executable files in $PATH.
2575 """Update the alias table with all executable files in $PATH.
2582
2576
2583 This version explicitly checks that every entry in $PATH is a file
2577 This version explicitly checks that every entry in $PATH is a file
2584 with execute access (os.X_OK), so it is much slower than %rehash.
2578 with execute access (os.X_OK), so it is much slower than %rehash.
2585
2579
2586 Under Windows, it checks executability as a match agains a
2580 Under Windows, it checks executability as a match agains a
2587 '|'-separated string of extensions, stored in the IPython config
2581 '|'-separated string of extensions, stored in the IPython config
2588 variable win_exec_ext. This defaults to 'exe|com|bat'.
2582 variable win_exec_ext. This defaults to 'exe|com|bat'.
2589
2583
2590 This function also resets the root module cache of module completer,
2584 This function also resets the root module cache of module completer,
2591 used on slow filesystems.
2585 used on slow filesystems.
2592 """
2586 """
2593 from IPython.core.alias import InvalidAliasError
2587 from IPython.core.alias import InvalidAliasError
2594
2588
2595 # for the benefit of module completer in ipy_completers.py
2589 # for the benefit of module completer in ipy_completers.py
2596 del self.db['rootmodules']
2590 del self.db['rootmodules']
2597
2591
2598 path = [os.path.abspath(os.path.expanduser(p)) for p in
2592 path = [os.path.abspath(os.path.expanduser(p)) for p in
2599 os.environ.get('PATH','').split(os.pathsep)]
2593 os.environ.get('PATH','').split(os.pathsep)]
2600 path = filter(os.path.isdir,path)
2594 path = filter(os.path.isdir,path)
2601
2595
2602 syscmdlist = []
2596 syscmdlist = []
2603 # Now define isexec in a cross platform manner.
2597 # Now define isexec in a cross platform manner.
2604 if os.name == 'posix':
2598 if os.name == 'posix':
2605 isexec = lambda fname:os.path.isfile(fname) and \
2599 isexec = lambda fname:os.path.isfile(fname) and \
2606 os.access(fname,os.X_OK)
2600 os.access(fname,os.X_OK)
2607 else:
2601 else:
2608 try:
2602 try:
2609 winext = os.environ['pathext'].replace(';','|').replace('.','')
2603 winext = os.environ['pathext'].replace(';','|').replace('.','')
2610 except KeyError:
2604 except KeyError:
2611 winext = 'exe|com|bat|py'
2605 winext = 'exe|com|bat|py'
2612 if 'py' not in winext:
2606 if 'py' not in winext:
2613 winext += '|py'
2607 winext += '|py'
2614 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2608 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2615 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2609 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2616 savedir = os.getcwd()
2610 savedir = os.getcwd()
2617
2611
2618 # Now walk the paths looking for executables to alias.
2612 # Now walk the paths looking for executables to alias.
2619 try:
2613 try:
2620 # write the whole loop for posix/Windows so we don't have an if in
2614 # write the whole loop for posix/Windows so we don't have an if in
2621 # the innermost part
2615 # the innermost part
2622 if os.name == 'posix':
2616 if os.name == 'posix':
2623 for pdir in path:
2617 for pdir in path:
2624 os.chdir(pdir)
2618 os.chdir(pdir)
2625 for ff in os.listdir(pdir):
2619 for ff in os.listdir(pdir):
2626 if isexec(ff):
2620 if isexec(ff):
2627 try:
2621 try:
2628 # Removes dots from the name since ipython
2622 # Removes dots from the name since ipython
2629 # will assume names with dots to be python.
2623 # will assume names with dots to be python.
2630 self.shell.alias_manager.define_alias(
2624 self.shell.alias_manager.define_alias(
2631 ff.replace('.',''), ff)
2625 ff.replace('.',''), ff)
2632 except InvalidAliasError:
2626 except InvalidAliasError:
2633 pass
2627 pass
2634 else:
2628 else:
2635 syscmdlist.append(ff)
2629 syscmdlist.append(ff)
2636 else:
2630 else:
2637 no_alias = self.shell.alias_manager.no_alias
2631 no_alias = self.shell.alias_manager.no_alias
2638 for pdir in path:
2632 for pdir in path:
2639 os.chdir(pdir)
2633 os.chdir(pdir)
2640 for ff in os.listdir(pdir):
2634 for ff in os.listdir(pdir):
2641 base, ext = os.path.splitext(ff)
2635 base, ext = os.path.splitext(ff)
2642 if isexec(ff) and base.lower() not in no_alias:
2636 if isexec(ff) and base.lower() not in no_alias:
2643 if ext.lower() == '.exe':
2637 if ext.lower() == '.exe':
2644 ff = base
2638 ff = base
2645 try:
2639 try:
2646 # Removes dots from the name since ipython
2640 # Removes dots from the name since ipython
2647 # will assume names with dots to be python.
2641 # will assume names with dots to be python.
2648 self.shell.alias_manager.define_alias(
2642 self.shell.alias_manager.define_alias(
2649 base.lower().replace('.',''), ff)
2643 base.lower().replace('.',''), ff)
2650 except InvalidAliasError:
2644 except InvalidAliasError:
2651 pass
2645 pass
2652 syscmdlist.append(ff)
2646 syscmdlist.append(ff)
2653 db = self.db
2647 db = self.db
2654 db['syscmdlist'] = syscmdlist
2648 db['syscmdlist'] = syscmdlist
2655 finally:
2649 finally:
2656 os.chdir(savedir)
2650 os.chdir(savedir)
2657
2651
2658 @testdec.skip_doctest
2652 @testdec.skip_doctest
2659 def magic_pwd(self, parameter_s = ''):
2653 def magic_pwd(self, parameter_s = ''):
2660 """Return the current working directory path.
2654 """Return the current working directory path.
2661
2655
2662 Examples
2656 Examples
2663 --------
2657 --------
2664 ::
2658 ::
2665
2659
2666 In [9]: pwd
2660 In [9]: pwd
2667 Out[9]: '/home/tsuser/sprint/ipython'
2661 Out[9]: '/home/tsuser/sprint/ipython'
2668 """
2662 """
2669 return os.getcwd()
2663 return os.getcwd()
2670
2664
2671 @testdec.skip_doctest
2665 @testdec.skip_doctest
2672 def magic_cd(self, parameter_s=''):
2666 def magic_cd(self, parameter_s=''):
2673 """Change the current working directory.
2667 """Change the current working directory.
2674
2668
2675 This command automatically maintains an internal list of directories
2669 This command automatically maintains an internal list of directories
2676 you visit during your IPython session, in the variable _dh. The
2670 you visit during your IPython session, in the variable _dh. The
2677 command %dhist shows this history nicely formatted. You can also
2671 command %dhist shows this history nicely formatted. You can also
2678 do 'cd -<tab>' to see directory history conveniently.
2672 do 'cd -<tab>' to see directory history conveniently.
2679
2673
2680 Usage:
2674 Usage:
2681
2675
2682 cd 'dir': changes to directory 'dir'.
2676 cd 'dir': changes to directory 'dir'.
2683
2677
2684 cd -: changes to the last visited directory.
2678 cd -: changes to the last visited directory.
2685
2679
2686 cd -<n>: changes to the n-th directory in the directory history.
2680 cd -<n>: changes to the n-th directory in the directory history.
2687
2681
2688 cd --foo: change to directory that matches 'foo' in history
2682 cd --foo: change to directory that matches 'foo' in history
2689
2683
2690 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2684 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2691 (note: cd <bookmark_name> is enough if there is no
2685 (note: cd <bookmark_name> is enough if there is no
2692 directory <bookmark_name>, but a bookmark with the name exists.)
2686 directory <bookmark_name>, but a bookmark with the name exists.)
2693 'cd -b <tab>' allows you to tab-complete bookmark names.
2687 'cd -b <tab>' allows you to tab-complete bookmark names.
2694
2688
2695 Options:
2689 Options:
2696
2690
2697 -q: quiet. Do not print the working directory after the cd command is
2691 -q: quiet. Do not print the working directory after the cd command is
2698 executed. By default IPython's cd command does print this directory,
2692 executed. By default IPython's cd command does print this directory,
2699 since the default prompts do not display path information.
2693 since the default prompts do not display path information.
2700
2694
2701 Note that !cd doesn't work for this purpose because the shell where
2695 Note that !cd doesn't work for this purpose because the shell where
2702 !command runs is immediately discarded after executing 'command'.
2696 !command runs is immediately discarded after executing 'command'.
2703
2697
2704 Examples
2698 Examples
2705 --------
2699 --------
2706 ::
2700 ::
2707
2701
2708 In [10]: cd parent/child
2702 In [10]: cd parent/child
2709 /home/tsuser/parent/child
2703 /home/tsuser/parent/child
2710 """
2704 """
2711
2705
2712 parameter_s = parameter_s.strip()
2706 parameter_s = parameter_s.strip()
2713 #bkms = self.shell.persist.get("bookmarks",{})
2707 #bkms = self.shell.persist.get("bookmarks",{})
2714
2708
2715 oldcwd = os.getcwd()
2709 oldcwd = os.getcwd()
2716 numcd = re.match(r'(-)(\d+)$',parameter_s)
2710 numcd = re.match(r'(-)(\d+)$',parameter_s)
2717 # jump in directory history by number
2711 # jump in directory history by number
2718 if numcd:
2712 if numcd:
2719 nn = int(numcd.group(2))
2713 nn = int(numcd.group(2))
2720 try:
2714 try:
2721 ps = self.shell.user_ns['_dh'][nn]
2715 ps = self.shell.user_ns['_dh'][nn]
2722 except IndexError:
2716 except IndexError:
2723 print 'The requested directory does not exist in history.'
2717 print 'The requested directory does not exist in history.'
2724 return
2718 return
2725 else:
2719 else:
2726 opts = {}
2720 opts = {}
2727 elif parameter_s.startswith('--'):
2721 elif parameter_s.startswith('--'):
2728 ps = None
2722 ps = None
2729 fallback = None
2723 fallback = None
2730 pat = parameter_s[2:]
2724 pat = parameter_s[2:]
2731 dh = self.shell.user_ns['_dh']
2725 dh = self.shell.user_ns['_dh']
2732 # first search only by basename (last component)
2726 # first search only by basename (last component)
2733 for ent in reversed(dh):
2727 for ent in reversed(dh):
2734 if pat in os.path.basename(ent) and os.path.isdir(ent):
2728 if pat in os.path.basename(ent) and os.path.isdir(ent):
2735 ps = ent
2729 ps = ent
2736 break
2730 break
2737
2731
2738 if fallback is None and pat in ent and os.path.isdir(ent):
2732 if fallback is None and pat in ent and os.path.isdir(ent):
2739 fallback = ent
2733 fallback = ent
2740
2734
2741 # if we have no last part match, pick the first full path match
2735 # if we have no last part match, pick the first full path match
2742 if ps is None:
2736 if ps is None:
2743 ps = fallback
2737 ps = fallback
2744
2738
2745 if ps is None:
2739 if ps is None:
2746 print "No matching entry in directory history"
2740 print "No matching entry in directory history"
2747 return
2741 return
2748 else:
2742 else:
2749 opts = {}
2743 opts = {}
2750
2744
2751
2745
2752 else:
2746 else:
2753 #turn all non-space-escaping backslashes to slashes,
2747 #turn all non-space-escaping backslashes to slashes,
2754 # for c:\windows\directory\names\
2748 # for c:\windows\directory\names\
2755 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2749 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2756 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2750 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2757 # jump to previous
2751 # jump to previous
2758 if ps == '-':
2752 if ps == '-':
2759 try:
2753 try:
2760 ps = self.shell.user_ns['_dh'][-2]
2754 ps = self.shell.user_ns['_dh'][-2]
2761 except IndexError:
2755 except IndexError:
2762 raise UsageError('%cd -: No previous directory to change to.')
2756 raise UsageError('%cd -: No previous directory to change to.')
2763 # jump to bookmark if needed
2757 # jump to bookmark if needed
2764 else:
2758 else:
2765 if not os.path.isdir(ps) or opts.has_key('b'):
2759 if not os.path.isdir(ps) or opts.has_key('b'):
2766 bkms = self.db.get('bookmarks', {})
2760 bkms = self.db.get('bookmarks', {})
2767
2761
2768 if bkms.has_key(ps):
2762 if bkms.has_key(ps):
2769 target = bkms[ps]
2763 target = bkms[ps]
2770 print '(bookmark:%s) -> %s' % (ps,target)
2764 print '(bookmark:%s) -> %s' % (ps,target)
2771 ps = target
2765 ps = target
2772 else:
2766 else:
2773 if opts.has_key('b'):
2767 if opts.has_key('b'):
2774 raise UsageError("Bookmark '%s' not found. "
2768 raise UsageError("Bookmark '%s' not found. "
2775 "Use '%%bookmark -l' to see your bookmarks." % ps)
2769 "Use '%%bookmark -l' to see your bookmarks." % ps)
2776
2770
2777 # at this point ps should point to the target dir
2771 # at this point ps should point to the target dir
2778 if ps:
2772 if ps:
2779 try:
2773 try:
2780 os.chdir(os.path.expanduser(ps))
2774 os.chdir(os.path.expanduser(ps))
2781 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2775 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2782 set_term_title('IPython: ' + abbrev_cwd())
2776 set_term_title('IPython: ' + abbrev_cwd())
2783 except OSError:
2777 except OSError:
2784 print sys.exc_info()[1]
2778 print sys.exc_info()[1]
2785 else:
2779 else:
2786 cwd = os.getcwd()
2780 cwd = os.getcwd()
2787 dhist = self.shell.user_ns['_dh']
2781 dhist = self.shell.user_ns['_dh']
2788 if oldcwd != cwd:
2782 if oldcwd != cwd:
2789 dhist.append(cwd)
2783 dhist.append(cwd)
2790 self.db['dhist'] = compress_dhist(dhist)[-100:]
2784 self.db['dhist'] = compress_dhist(dhist)[-100:]
2791
2785
2792 else:
2786 else:
2793 os.chdir(self.shell.home_dir)
2787 os.chdir(self.shell.home_dir)
2794 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2788 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2795 set_term_title('IPython: ' + '~')
2789 set_term_title('IPython: ' + '~')
2796 cwd = os.getcwd()
2790 cwd = os.getcwd()
2797 dhist = self.shell.user_ns['_dh']
2791 dhist = self.shell.user_ns['_dh']
2798
2792
2799 if oldcwd != cwd:
2793 if oldcwd != cwd:
2800 dhist.append(cwd)
2794 dhist.append(cwd)
2801 self.db['dhist'] = compress_dhist(dhist)[-100:]
2795 self.db['dhist'] = compress_dhist(dhist)[-100:]
2802 if not 'q' in opts and self.shell.user_ns['_dh']:
2796 if not 'q' in opts and self.shell.user_ns['_dh']:
2803 print self.shell.user_ns['_dh'][-1]
2797 print self.shell.user_ns['_dh'][-1]
2804
2798
2805
2799
2806 def magic_env(self, parameter_s=''):
2800 def magic_env(self, parameter_s=''):
2807 """List environment variables."""
2801 """List environment variables."""
2808
2802
2809 return os.environ.data
2803 return os.environ.data
2810
2804
2811 def magic_pushd(self, parameter_s=''):
2805 def magic_pushd(self, parameter_s=''):
2812 """Place the current dir on stack and change directory.
2806 """Place the current dir on stack and change directory.
2813
2807
2814 Usage:\\
2808 Usage:\\
2815 %pushd ['dirname']
2809 %pushd ['dirname']
2816 """
2810 """
2817
2811
2818 dir_s = self.shell.dir_stack
2812 dir_s = self.shell.dir_stack
2819 tgt = os.path.expanduser(parameter_s)
2813 tgt = os.path.expanduser(parameter_s)
2820 cwd = os.getcwd().replace(self.home_dir,'~')
2814 cwd = os.getcwd().replace(self.home_dir,'~')
2821 if tgt:
2815 if tgt:
2822 self.magic_cd(parameter_s)
2816 self.magic_cd(parameter_s)
2823 dir_s.insert(0,cwd)
2817 dir_s.insert(0,cwd)
2824 return self.magic_dirs()
2818 return self.magic_dirs()
2825
2819
2826 def magic_popd(self, parameter_s=''):
2820 def magic_popd(self, parameter_s=''):
2827 """Change to directory popped off the top of the stack.
2821 """Change to directory popped off the top of the stack.
2828 """
2822 """
2829 if not self.shell.dir_stack:
2823 if not self.shell.dir_stack:
2830 raise UsageError("%popd on empty stack")
2824 raise UsageError("%popd on empty stack")
2831 top = self.shell.dir_stack.pop(0)
2825 top = self.shell.dir_stack.pop(0)
2832 self.magic_cd(top)
2826 self.magic_cd(top)
2833 print "popd ->",top
2827 print "popd ->",top
2834
2828
2835 def magic_dirs(self, parameter_s=''):
2829 def magic_dirs(self, parameter_s=''):
2836 """Return the current directory stack."""
2830 """Return the current directory stack."""
2837
2831
2838 return self.shell.dir_stack
2832 return self.shell.dir_stack
2839
2833
2840 def magic_dhist(self, parameter_s=''):
2834 def magic_dhist(self, parameter_s=''):
2841 """Print your history of visited directories.
2835 """Print your history of visited directories.
2842
2836
2843 %dhist -> print full history\\
2837 %dhist -> print full history\\
2844 %dhist n -> print last n entries only\\
2838 %dhist n -> print last n entries only\\
2845 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2839 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2846
2840
2847 This history is automatically maintained by the %cd command, and
2841 This history is automatically maintained by the %cd command, and
2848 always available as the global list variable _dh. You can use %cd -<n>
2842 always available as the global list variable _dh. You can use %cd -<n>
2849 to go to directory number <n>.
2843 to go to directory number <n>.
2850
2844
2851 Note that most of time, you should view directory history by entering
2845 Note that most of time, you should view directory history by entering
2852 cd -<TAB>.
2846 cd -<TAB>.
2853
2847
2854 """
2848 """
2855
2849
2856 dh = self.shell.user_ns['_dh']
2850 dh = self.shell.user_ns['_dh']
2857 if parameter_s:
2851 if parameter_s:
2858 try:
2852 try:
2859 args = map(int,parameter_s.split())
2853 args = map(int,parameter_s.split())
2860 except:
2854 except:
2861 self.arg_err(Magic.magic_dhist)
2855 self.arg_err(Magic.magic_dhist)
2862 return
2856 return
2863 if len(args) == 1:
2857 if len(args) == 1:
2864 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2858 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2865 elif len(args) == 2:
2859 elif len(args) == 2:
2866 ini,fin = args
2860 ini,fin = args
2867 else:
2861 else:
2868 self.arg_err(Magic.magic_dhist)
2862 self.arg_err(Magic.magic_dhist)
2869 return
2863 return
2870 else:
2864 else:
2871 ini,fin = 0,len(dh)
2865 ini,fin = 0,len(dh)
2872 nlprint(dh,
2866 nlprint(dh,
2873 header = 'Directory history (kept in _dh)',
2867 header = 'Directory history (kept in _dh)',
2874 start=ini,stop=fin)
2868 start=ini,stop=fin)
2875
2869
2876 @testdec.skip_doctest
2870 @testdec.skip_doctest
2877 def magic_sc(self, parameter_s=''):
2871 def magic_sc(self, parameter_s=''):
2878 """Shell capture - execute a shell command and capture its output.
2872 """Shell capture - execute a shell command and capture its output.
2879
2873
2880 DEPRECATED. Suboptimal, retained for backwards compatibility.
2874 DEPRECATED. Suboptimal, retained for backwards compatibility.
2881
2875
2882 You should use the form 'var = !command' instead. Example:
2876 You should use the form 'var = !command' instead. Example:
2883
2877
2884 "%sc -l myfiles = ls ~" should now be written as
2878 "%sc -l myfiles = ls ~" should now be written as
2885
2879
2886 "myfiles = !ls ~"
2880 "myfiles = !ls ~"
2887
2881
2888 myfiles.s, myfiles.l and myfiles.n still apply as documented
2882 myfiles.s, myfiles.l and myfiles.n still apply as documented
2889 below.
2883 below.
2890
2884
2891 --
2885 --
2892 %sc [options] varname=command
2886 %sc [options] varname=command
2893
2887
2894 IPython will run the given command using commands.getoutput(), and
2888 IPython will run the given command using commands.getoutput(), and
2895 will then update the user's interactive namespace with a variable
2889 will then update the user's interactive namespace with a variable
2896 called varname, containing the value of the call. Your command can
2890 called varname, containing the value of the call. Your command can
2897 contain shell wildcards, pipes, etc.
2891 contain shell wildcards, pipes, etc.
2898
2892
2899 The '=' sign in the syntax is mandatory, and the variable name you
2893 The '=' sign in the syntax is mandatory, and the variable name you
2900 supply must follow Python's standard conventions for valid names.
2894 supply must follow Python's standard conventions for valid names.
2901
2895
2902 (A special format without variable name exists for internal use)
2896 (A special format without variable name exists for internal use)
2903
2897
2904 Options:
2898 Options:
2905
2899
2906 -l: list output. Split the output on newlines into a list before
2900 -l: list output. Split the output on newlines into a list before
2907 assigning it to the given variable. By default the output is stored
2901 assigning it to the given variable. By default the output is stored
2908 as a single string.
2902 as a single string.
2909
2903
2910 -v: verbose. Print the contents of the variable.
2904 -v: verbose. Print the contents of the variable.
2911
2905
2912 In most cases you should not need to split as a list, because the
2906 In most cases you should not need to split as a list, because the
2913 returned value is a special type of string which can automatically
2907 returned value is a special type of string which can automatically
2914 provide its contents either as a list (split on newlines) or as a
2908 provide its contents either as a list (split on newlines) or as a
2915 space-separated string. These are convenient, respectively, either
2909 space-separated string. These are convenient, respectively, either
2916 for sequential processing or to be passed to a shell command.
2910 for sequential processing or to be passed to a shell command.
2917
2911
2918 For example:
2912 For example:
2919
2913
2920 # all-random
2914 # all-random
2921
2915
2922 # Capture into variable a
2916 # Capture into variable a
2923 In [1]: sc a=ls *py
2917 In [1]: sc a=ls *py
2924
2918
2925 # a is a string with embedded newlines
2919 # a is a string with embedded newlines
2926 In [2]: a
2920 In [2]: a
2927 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2921 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2928
2922
2929 # which can be seen as a list:
2923 # which can be seen as a list:
2930 In [3]: a.l
2924 In [3]: a.l
2931 Out[3]: ['setup.py', 'win32_manual_post_install.py']
2925 Out[3]: ['setup.py', 'win32_manual_post_install.py']
2932
2926
2933 # or as a whitespace-separated string:
2927 # or as a whitespace-separated string:
2934 In [4]: a.s
2928 In [4]: a.s
2935 Out[4]: 'setup.py win32_manual_post_install.py'
2929 Out[4]: 'setup.py win32_manual_post_install.py'
2936
2930
2937 # a.s is useful to pass as a single command line:
2931 # a.s is useful to pass as a single command line:
2938 In [5]: !wc -l $a.s
2932 In [5]: !wc -l $a.s
2939 146 setup.py
2933 146 setup.py
2940 130 win32_manual_post_install.py
2934 130 win32_manual_post_install.py
2941 276 total
2935 276 total
2942
2936
2943 # while the list form is useful to loop over:
2937 # while the list form is useful to loop over:
2944 In [6]: for f in a.l:
2938 In [6]: for f in a.l:
2945 ...: !wc -l $f
2939 ...: !wc -l $f
2946 ...:
2940 ...:
2947 146 setup.py
2941 146 setup.py
2948 130 win32_manual_post_install.py
2942 130 win32_manual_post_install.py
2949
2943
2950 Similiarly, the lists returned by the -l option are also special, in
2944 Similiarly, the lists returned by the -l option are also special, in
2951 the sense that you can equally invoke the .s attribute on them to
2945 the sense that you can equally invoke the .s attribute on them to
2952 automatically get a whitespace-separated string from their contents:
2946 automatically get a whitespace-separated string from their contents:
2953
2947
2954 In [7]: sc -l b=ls *py
2948 In [7]: sc -l b=ls *py
2955
2949
2956 In [8]: b
2950 In [8]: b
2957 Out[8]: ['setup.py', 'win32_manual_post_install.py']
2951 Out[8]: ['setup.py', 'win32_manual_post_install.py']
2958
2952
2959 In [9]: b.s
2953 In [9]: b.s
2960 Out[9]: 'setup.py win32_manual_post_install.py'
2954 Out[9]: 'setup.py win32_manual_post_install.py'
2961
2955
2962 In summary, both the lists and strings used for ouptut capture have
2956 In summary, both the lists and strings used for ouptut capture have
2963 the following special attributes:
2957 the following special attributes:
2964
2958
2965 .l (or .list) : value as list.
2959 .l (or .list) : value as list.
2966 .n (or .nlstr): value as newline-separated string.
2960 .n (or .nlstr): value as newline-separated string.
2967 .s (or .spstr): value as space-separated string.
2961 .s (or .spstr): value as space-separated string.
2968 """
2962 """
2969
2963
2970 opts,args = self.parse_options(parameter_s,'lv')
2964 opts,args = self.parse_options(parameter_s,'lv')
2971 # Try to get a variable name and command to run
2965 # Try to get a variable name and command to run
2972 try:
2966 try:
2973 # the variable name must be obtained from the parse_options
2967 # the variable name must be obtained from the parse_options
2974 # output, which uses shlex.split to strip options out.
2968 # output, which uses shlex.split to strip options out.
2975 var,_ = args.split('=',1)
2969 var,_ = args.split('=',1)
2976 var = var.strip()
2970 var = var.strip()
2977 # But the the command has to be extracted from the original input
2971 # But the the command has to be extracted from the original input
2978 # parameter_s, not on what parse_options returns, to avoid the
2972 # parameter_s, not on what parse_options returns, to avoid the
2979 # quote stripping which shlex.split performs on it.
2973 # quote stripping which shlex.split performs on it.
2980 _,cmd = parameter_s.split('=',1)
2974 _,cmd = parameter_s.split('=',1)
2981 except ValueError:
2975 except ValueError:
2982 var,cmd = '',''
2976 var,cmd = '',''
2983 # If all looks ok, proceed
2977 # If all looks ok, proceed
2984 split = 'l' in opts
2978 split = 'l' in opts
2985 out = self.shell.getoutput(cmd, split=split)
2979 out = self.shell.getoutput(cmd, split=split)
2986 if opts.has_key('v'):
2980 if opts.has_key('v'):
2987 print '%s ==\n%s' % (var,pformat(out))
2981 print '%s ==\n%s' % (var,pformat(out))
2988 if var:
2982 if var:
2989 self.shell.user_ns.update({var:out})
2983 self.shell.user_ns.update({var:out})
2990 else:
2984 else:
2991 return out
2985 return out
2992
2986
2993 def magic_sx(self, parameter_s=''):
2987 def magic_sx(self, parameter_s=''):
2994 """Shell execute - run a shell command and capture its output.
2988 """Shell execute - run a shell command and capture its output.
2995
2989
2996 %sx command
2990 %sx command
2997
2991
2998 IPython will run the given command using commands.getoutput(), and
2992 IPython will run the given command using commands.getoutput(), and
2999 return the result formatted as a list (split on '\\n'). Since the
2993 return the result formatted as a list (split on '\\n'). Since the
3000 output is _returned_, it will be stored in ipython's regular output
2994 output is _returned_, it will be stored in ipython's regular output
3001 cache Out[N] and in the '_N' automatic variables.
2995 cache Out[N] and in the '_N' automatic variables.
3002
2996
3003 Notes:
2997 Notes:
3004
2998
3005 1) If an input line begins with '!!', then %sx is automatically
2999 1) If an input line begins with '!!', then %sx is automatically
3006 invoked. That is, while:
3000 invoked. That is, while:
3007 !ls
3001 !ls
3008 causes ipython to simply issue system('ls'), typing
3002 causes ipython to simply issue system('ls'), typing
3009 !!ls
3003 !!ls
3010 is a shorthand equivalent to:
3004 is a shorthand equivalent to:
3011 %sx ls
3005 %sx ls
3012
3006
3013 2) %sx differs from %sc in that %sx automatically splits into a list,
3007 2) %sx differs from %sc in that %sx automatically splits into a list,
3014 like '%sc -l'. The reason for this is to make it as easy as possible
3008 like '%sc -l'. The reason for this is to make it as easy as possible
3015 to process line-oriented shell output via further python commands.
3009 to process line-oriented shell output via further python commands.
3016 %sc is meant to provide much finer control, but requires more
3010 %sc is meant to provide much finer control, but requires more
3017 typing.
3011 typing.
3018
3012
3019 3) Just like %sc -l, this is a list with special attributes:
3013 3) Just like %sc -l, this is a list with special attributes:
3020
3014
3021 .l (or .list) : value as list.
3015 .l (or .list) : value as list.
3022 .n (or .nlstr): value as newline-separated string.
3016 .n (or .nlstr): value as newline-separated string.
3023 .s (or .spstr): value as whitespace-separated string.
3017 .s (or .spstr): value as whitespace-separated string.
3024
3018
3025 This is very useful when trying to use such lists as arguments to
3019 This is very useful when trying to use such lists as arguments to
3026 system commands."""
3020 system commands."""
3027
3021
3028 if parameter_s:
3022 if parameter_s:
3029 return self.shell.getoutput(parameter_s)
3023 return self.shell.getoutput(parameter_s)
3030
3024
3031
3025
3032 def magic_bookmark(self, parameter_s=''):
3026 def magic_bookmark(self, parameter_s=''):
3033 """Manage IPython's bookmark system.
3027 """Manage IPython's bookmark system.
3034
3028
3035 %bookmark <name> - set bookmark to current dir
3029 %bookmark <name> - set bookmark to current dir
3036 %bookmark <name> <dir> - set bookmark to <dir>
3030 %bookmark <name> <dir> - set bookmark to <dir>
3037 %bookmark -l - list all bookmarks
3031 %bookmark -l - list all bookmarks
3038 %bookmark -d <name> - remove bookmark
3032 %bookmark -d <name> - remove bookmark
3039 %bookmark -r - remove all bookmarks
3033 %bookmark -r - remove all bookmarks
3040
3034
3041 You can later on access a bookmarked folder with:
3035 You can later on access a bookmarked folder with:
3042 %cd -b <name>
3036 %cd -b <name>
3043 or simply '%cd <name>' if there is no directory called <name> AND
3037 or simply '%cd <name>' if there is no directory called <name> AND
3044 there is such a bookmark defined.
3038 there is such a bookmark defined.
3045
3039
3046 Your bookmarks persist through IPython sessions, but they are
3040 Your bookmarks persist through IPython sessions, but they are
3047 associated with each profile."""
3041 associated with each profile."""
3048
3042
3049 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3043 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3050 if len(args) > 2:
3044 if len(args) > 2:
3051 raise UsageError("%bookmark: too many arguments")
3045 raise UsageError("%bookmark: too many arguments")
3052
3046
3053 bkms = self.db.get('bookmarks',{})
3047 bkms = self.db.get('bookmarks',{})
3054
3048
3055 if opts.has_key('d'):
3049 if opts.has_key('d'):
3056 try:
3050 try:
3057 todel = args[0]
3051 todel = args[0]
3058 except IndexError:
3052 except IndexError:
3059 raise UsageError(
3053 raise UsageError(
3060 "%bookmark -d: must provide a bookmark to delete")
3054 "%bookmark -d: must provide a bookmark to delete")
3061 else:
3055 else:
3062 try:
3056 try:
3063 del bkms[todel]
3057 del bkms[todel]
3064 except KeyError:
3058 except KeyError:
3065 raise UsageError(
3059 raise UsageError(
3066 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3060 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3067
3061
3068 elif opts.has_key('r'):
3062 elif opts.has_key('r'):
3069 bkms = {}
3063 bkms = {}
3070 elif opts.has_key('l'):
3064 elif opts.has_key('l'):
3071 bks = bkms.keys()
3065 bks = bkms.keys()
3072 bks.sort()
3066 bks.sort()
3073 if bks:
3067 if bks:
3074 size = max(map(len,bks))
3068 size = max(map(len,bks))
3075 else:
3069 else:
3076 size = 0
3070 size = 0
3077 fmt = '%-'+str(size)+'s -> %s'
3071 fmt = '%-'+str(size)+'s -> %s'
3078 print 'Current bookmarks:'
3072 print 'Current bookmarks:'
3079 for bk in bks:
3073 for bk in bks:
3080 print fmt % (bk,bkms[bk])
3074 print fmt % (bk,bkms[bk])
3081 else:
3075 else:
3082 if not args:
3076 if not args:
3083 raise UsageError("%bookmark: You must specify the bookmark name")
3077 raise UsageError("%bookmark: You must specify the bookmark name")
3084 elif len(args)==1:
3078 elif len(args)==1:
3085 bkms[args[0]] = os.getcwd()
3079 bkms[args[0]] = os.getcwd()
3086 elif len(args)==2:
3080 elif len(args)==2:
3087 bkms[args[0]] = args[1]
3081 bkms[args[0]] = args[1]
3088 self.db['bookmarks'] = bkms
3082 self.db['bookmarks'] = bkms
3089
3083
3090 def magic_pycat(self, parameter_s=''):
3084 def magic_pycat(self, parameter_s=''):
3091 """Show a syntax-highlighted file through a pager.
3085 """Show a syntax-highlighted file through a pager.
3092
3086
3093 This magic is similar to the cat utility, but it will assume the file
3087 This magic is similar to the cat utility, but it will assume the file
3094 to be Python source and will show it with syntax highlighting. """
3088 to be Python source and will show it with syntax highlighting. """
3095
3089
3096 try:
3090 try:
3097 filename = get_py_filename(parameter_s)
3091 filename = get_py_filename(parameter_s)
3098 cont = file_read(filename)
3092 cont = file_read(filename)
3099 except IOError:
3093 except IOError:
3100 try:
3094 try:
3101 cont = eval(parameter_s,self.user_ns)
3095 cont = eval(parameter_s,self.user_ns)
3102 except NameError:
3096 except NameError:
3103 cont = None
3097 cont = None
3104 if cont is None:
3098 if cont is None:
3105 print "Error: no such file or variable"
3099 print "Error: no such file or variable"
3106 return
3100 return
3107
3101
3108 page.page(self.shell.pycolorize(cont))
3102 page.page(self.shell.pycolorize(cont))
3109
3103
3110 def _rerun_pasted(self):
3104 def _rerun_pasted(self):
3111 """ Rerun a previously pasted command.
3105 """ Rerun a previously pasted command.
3112 """
3106 """
3113 b = self.user_ns.get('pasted_block', None)
3107 b = self.user_ns.get('pasted_block', None)
3114 if b is None:
3108 if b is None:
3115 raise UsageError('No previous pasted block available')
3109 raise UsageError('No previous pasted block available')
3116 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3110 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3117 exec b in self.user_ns
3111 exec b in self.user_ns
3118
3112
3119 def _get_pasted_lines(self, sentinel):
3113 def _get_pasted_lines(self, sentinel):
3120 """ Yield pasted lines until the user enters the given sentinel value.
3114 """ Yield pasted lines until the user enters the given sentinel value.
3121 """
3115 """
3122 from IPython.core import interactiveshell
3116 from IPython.core import interactiveshell
3123 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3117 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3124 while True:
3118 while True:
3125 l = interactiveshell.raw_input_original(':')
3119 l = interactiveshell.raw_input_original(':')
3126 if l == sentinel:
3120 if l == sentinel:
3127 return
3121 return
3128 else:
3122 else:
3129 yield l
3123 yield l
3130
3124
3131 def _strip_pasted_lines_for_code(self, raw_lines):
3125 def _strip_pasted_lines_for_code(self, raw_lines):
3132 """ Strip non-code parts of a sequence of lines to return a block of
3126 """ Strip non-code parts of a sequence of lines to return a block of
3133 code.
3127 code.
3134 """
3128 """
3135 # Regular expressions that declare text we strip from the input:
3129 # Regular expressions that declare text we strip from the input:
3136 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3130 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3137 r'^\s*(\s?>)+', # Python input prompt
3131 r'^\s*(\s?>)+', # Python input prompt
3138 r'^\s*\.{3,}', # Continuation prompts
3132 r'^\s*\.{3,}', # Continuation prompts
3139 r'^\++',
3133 r'^\++',
3140 ]
3134 ]
3141
3135
3142 strip_from_start = map(re.compile,strip_re)
3136 strip_from_start = map(re.compile,strip_re)
3143
3137
3144 lines = []
3138 lines = []
3145 for l in raw_lines:
3139 for l in raw_lines:
3146 for pat in strip_from_start:
3140 for pat in strip_from_start:
3147 l = pat.sub('',l)
3141 l = pat.sub('',l)
3148 lines.append(l)
3142 lines.append(l)
3149
3143
3150 block = "\n".join(lines) + '\n'
3144 block = "\n".join(lines) + '\n'
3151 #print "block:\n",block
3145 #print "block:\n",block
3152 return block
3146 return block
3153
3147
3154 def _execute_block(self, block, par):
3148 def _execute_block(self, block, par):
3155 """ Execute a block, or store it in a variable, per the user's request.
3149 """ Execute a block, or store it in a variable, per the user's request.
3156 """
3150 """
3157 if not par:
3151 if not par:
3158 b = textwrap.dedent(block)
3152 b = textwrap.dedent(block)
3159 self.user_ns['pasted_block'] = b
3153 self.user_ns['pasted_block'] = b
3160 exec b in self.user_ns
3154 exec b in self.user_ns
3161 else:
3155 else:
3162 self.user_ns[par] = SList(block.splitlines())
3156 self.user_ns[par] = SList(block.splitlines())
3163 print "Block assigned to '%s'" % par
3157 print "Block assigned to '%s'" % par
3164
3158
3165 def magic_quickref(self,arg):
3159 def magic_quickref(self,arg):
3166 """ Show a quick reference sheet """
3160 """ Show a quick reference sheet """
3167 import IPython.core.usage
3161 import IPython.core.usage
3168 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3162 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3169
3163
3170 page.page(qr)
3164 page.page(qr)
3171
3165
3172 def magic_doctest_mode(self,parameter_s=''):
3166 def magic_doctest_mode(self,parameter_s=''):
3173 """Toggle doctest mode on and off.
3167 """Toggle doctest mode on and off.
3174
3168
3175 This mode is intended to make IPython behave as much as possible like a
3169 This mode is intended to make IPython behave as much as possible like a
3176 plain Python shell, from the perspective of how its prompts, exceptions
3170 plain Python shell, from the perspective of how its prompts, exceptions
3177 and output look. This makes it easy to copy and paste parts of a
3171 and output look. This makes it easy to copy and paste parts of a
3178 session into doctests. It does so by:
3172 session into doctests. It does so by:
3179
3173
3180 - Changing the prompts to the classic ``>>>`` ones.
3174 - Changing the prompts to the classic ``>>>`` ones.
3181 - Changing the exception reporting mode to 'Plain'.
3175 - Changing the exception reporting mode to 'Plain'.
3182 - Disabling pretty-printing of output.
3176 - Disabling pretty-printing of output.
3183
3177
3184 Note that IPython also supports the pasting of code snippets that have
3178 Note that IPython also supports the pasting of code snippets that have
3185 leading '>>>' and '...' prompts in them. This means that you can paste
3179 leading '>>>' and '...' prompts in them. This means that you can paste
3186 doctests from files or docstrings (even if they have leading
3180 doctests from files or docstrings (even if they have leading
3187 whitespace), and the code will execute correctly. You can then use
3181 whitespace), and the code will execute correctly. You can then use
3188 '%history -t' to see the translated history; this will give you the
3182 '%history -t' to see the translated history; this will give you the
3189 input after removal of all the leading prompts and whitespace, which
3183 input after removal of all the leading prompts and whitespace, which
3190 can be pasted back into an editor.
3184 can be pasted back into an editor.
3191
3185
3192 With these features, you can switch into this mode easily whenever you
3186 With these features, you can switch into this mode easily whenever you
3193 need to do testing and changes to doctests, without having to leave
3187 need to do testing and changes to doctests, without having to leave
3194 your existing IPython session.
3188 your existing IPython session.
3195 """
3189 """
3196
3190
3197 from IPython.utils.ipstruct import Struct
3191 from IPython.utils.ipstruct import Struct
3198
3192
3199 # Shorthands
3193 # Shorthands
3200 shell = self.shell
3194 shell = self.shell
3201 oc = shell.displayhook
3195 oc = shell.displayhook
3202 meta = shell.meta
3196 meta = shell.meta
3203 disp_formatter = self.shell.display_formatter
3197 disp_formatter = self.shell.display_formatter
3204 ptformatter = disp_formatter.formatters['text/plain']
3198 ptformatter = disp_formatter.formatters['text/plain']
3205 # dstore is a data store kept in the instance metadata bag to track any
3199 # dstore is a data store kept in the instance metadata bag to track any
3206 # changes we make, so we can undo them later.
3200 # changes we make, so we can undo them later.
3207 dstore = meta.setdefault('doctest_mode',Struct())
3201 dstore = meta.setdefault('doctest_mode',Struct())
3208 save_dstore = dstore.setdefault
3202 save_dstore = dstore.setdefault
3209
3203
3210 # save a few values we'll need to recover later
3204 # save a few values we'll need to recover later
3211 mode = save_dstore('mode',False)
3205 mode = save_dstore('mode',False)
3212 save_dstore('rc_pprint',ptformatter.pprint)
3206 save_dstore('rc_pprint',ptformatter.pprint)
3213 save_dstore('xmode',shell.InteractiveTB.mode)
3207 save_dstore('xmode',shell.InteractiveTB.mode)
3214 save_dstore('rc_separate_out',shell.separate_out)
3208 save_dstore('rc_separate_out',shell.separate_out)
3215 save_dstore('rc_separate_out2',shell.separate_out2)
3209 save_dstore('rc_separate_out2',shell.separate_out2)
3216 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3210 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3217 save_dstore('rc_separate_in',shell.separate_in)
3211 save_dstore('rc_separate_in',shell.separate_in)
3218 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3212 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3219
3213
3220 if mode == False:
3214 if mode == False:
3221 # turn on
3215 # turn on
3222 oc.prompt1.p_template = '>>> '
3216 oc.prompt1.p_template = '>>> '
3223 oc.prompt2.p_template = '... '
3217 oc.prompt2.p_template = '... '
3224 oc.prompt_out.p_template = ''
3218 oc.prompt_out.p_template = ''
3225
3219
3226 # Prompt separators like plain python
3220 # Prompt separators like plain python
3227 oc.input_sep = oc.prompt1.sep = ''
3221 oc.input_sep = oc.prompt1.sep = ''
3228 oc.output_sep = ''
3222 oc.output_sep = ''
3229 oc.output_sep2 = ''
3223 oc.output_sep2 = ''
3230
3224
3231 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3225 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3232 oc.prompt_out.pad_left = False
3226 oc.prompt_out.pad_left = False
3233
3227
3234 ptformatter.pprint = False
3228 ptformatter.pprint = False
3235 disp_formatter.plain_text_only = True
3229 disp_formatter.plain_text_only = True
3236
3230
3237 shell.magic_xmode('Plain')
3231 shell.magic_xmode('Plain')
3238 else:
3232 else:
3239 # turn off
3233 # turn off
3240 oc.prompt1.p_template = shell.prompt_in1
3234 oc.prompt1.p_template = shell.prompt_in1
3241 oc.prompt2.p_template = shell.prompt_in2
3235 oc.prompt2.p_template = shell.prompt_in2
3242 oc.prompt_out.p_template = shell.prompt_out
3236 oc.prompt_out.p_template = shell.prompt_out
3243
3237
3244 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3238 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3245
3239
3246 oc.output_sep = dstore.rc_separate_out
3240 oc.output_sep = dstore.rc_separate_out
3247 oc.output_sep2 = dstore.rc_separate_out2
3241 oc.output_sep2 = dstore.rc_separate_out2
3248
3242
3249 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3243 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3250 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3244 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3251
3245
3252 ptformatter.pprint = dstore.rc_pprint
3246 ptformatter.pprint = dstore.rc_pprint
3253 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3247 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3254
3248
3255 shell.magic_xmode(dstore.xmode)
3249 shell.magic_xmode(dstore.xmode)
3256
3250
3257 # Store new mode and inform
3251 # Store new mode and inform
3258 dstore.mode = bool(1-int(mode))
3252 dstore.mode = bool(1-int(mode))
3259 mode_label = ['OFF','ON'][dstore.mode]
3253 mode_label = ['OFF','ON'][dstore.mode]
3260 print 'Doctest mode is:', mode_label
3254 print 'Doctest mode is:', mode_label
3261
3255
3262 def magic_gui(self, parameter_s=''):
3256 def magic_gui(self, parameter_s=''):
3263 """Enable or disable IPython GUI event loop integration.
3257 """Enable or disable IPython GUI event loop integration.
3264
3258
3265 %gui [GUINAME]
3259 %gui [GUINAME]
3266
3260
3267 This magic replaces IPython's threaded shells that were activated
3261 This magic replaces IPython's threaded shells that were activated
3268 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3262 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3269 can now be enabled, disabled and swtiched at runtime and keyboard
3263 can now be enabled, disabled and swtiched at runtime and keyboard
3270 interrupts should work without any problems. The following toolkits
3264 interrupts should work without any problems. The following toolkits
3271 are supported: wxPython, PyQt4, PyGTK, and Tk::
3265 are supported: wxPython, PyQt4, PyGTK, and Tk::
3272
3266
3273 %gui wx # enable wxPython event loop integration
3267 %gui wx # enable wxPython event loop integration
3274 %gui qt4|qt # enable PyQt4 event loop integration
3268 %gui qt4|qt # enable PyQt4 event loop integration
3275 %gui gtk # enable PyGTK event loop integration
3269 %gui gtk # enable PyGTK event loop integration
3276 %gui tk # enable Tk event loop integration
3270 %gui tk # enable Tk event loop integration
3277 %gui # disable all event loop integration
3271 %gui # disable all event loop integration
3278
3272
3279 WARNING: after any of these has been called you can simply create
3273 WARNING: after any of these has been called you can simply create
3280 an application object, but DO NOT start the event loop yourself, as
3274 an application object, but DO NOT start the event loop yourself, as
3281 we have already handled that.
3275 we have already handled that.
3282 """
3276 """
3283 from IPython.lib.inputhook import enable_gui
3277 from IPython.lib.inputhook import enable_gui
3284 opts, arg = self.parse_options(parameter_s, '')
3278 opts, arg = self.parse_options(parameter_s, '')
3285 if arg=='': arg = None
3279 if arg=='': arg = None
3286 return enable_gui(arg)
3280 return enable_gui(arg)
3287
3281
3288 def magic_load_ext(self, module_str):
3282 def magic_load_ext(self, module_str):
3289 """Load an IPython extension by its module name."""
3283 """Load an IPython extension by its module name."""
3290 return self.extension_manager.load_extension(module_str)
3284 return self.extension_manager.load_extension(module_str)
3291
3285
3292 def magic_unload_ext(self, module_str):
3286 def magic_unload_ext(self, module_str):
3293 """Unload an IPython extension by its module name."""
3287 """Unload an IPython extension by its module name."""
3294 self.extension_manager.unload_extension(module_str)
3288 self.extension_manager.unload_extension(module_str)
3295
3289
3296 def magic_reload_ext(self, module_str):
3290 def magic_reload_ext(self, module_str):
3297 """Reload an IPython extension by its module name."""
3291 """Reload an IPython extension by its module name."""
3298 self.extension_manager.reload_extension(module_str)
3292 self.extension_manager.reload_extension(module_str)
3299
3293
3300 @testdec.skip_doctest
3294 @testdec.skip_doctest
3301 def magic_install_profiles(self, s):
3295 def magic_install_profiles(self, s):
3302 """Install the default IPython profiles into the .ipython dir.
3296 """Install the default IPython profiles into the .ipython dir.
3303
3297
3304 If the default profiles have already been installed, they will not
3298 If the default profiles have already been installed, they will not
3305 be overwritten. You can force overwriting them by using the ``-o``
3299 be overwritten. You can force overwriting them by using the ``-o``
3306 option::
3300 option::
3307
3301
3308 In [1]: %install_profiles -o
3302 In [1]: %install_profiles -o
3309 """
3303 """
3310 if '-o' in s:
3304 if '-o' in s:
3311 overwrite = True
3305 overwrite = True
3312 else:
3306 else:
3313 overwrite = False
3307 overwrite = False
3314 from IPython.config import profile
3308 from IPython.config import profile
3315 profile_dir = os.path.split(profile.__file__)[0]
3309 profile_dir = os.path.split(profile.__file__)[0]
3316 ipython_dir = self.ipython_dir
3310 ipython_dir = self.ipython_dir
3317 files = os.listdir(profile_dir)
3311 files = os.listdir(profile_dir)
3318
3312
3319 to_install = []
3313 to_install = []
3320 for f in files:
3314 for f in files:
3321 if f.startswith('ipython_config'):
3315 if f.startswith('ipython_config'):
3322 src = os.path.join(profile_dir, f)
3316 src = os.path.join(profile_dir, f)
3323 dst = os.path.join(ipython_dir, f)
3317 dst = os.path.join(ipython_dir, f)
3324 if (not os.path.isfile(dst)) or overwrite:
3318 if (not os.path.isfile(dst)) or overwrite:
3325 to_install.append((f, src, dst))
3319 to_install.append((f, src, dst))
3326 if len(to_install)>0:
3320 if len(to_install)>0:
3327 print "Installing profiles to: ", ipython_dir
3321 print "Installing profiles to: ", ipython_dir
3328 for (f, src, dst) in to_install:
3322 for (f, src, dst) in to_install:
3329 shutil.copy(src, dst)
3323 shutil.copy(src, dst)
3330 print " %s" % f
3324 print " %s" % f
3331
3325
3332 def magic_install_default_config(self, s):
3326 def magic_install_default_config(self, s):
3333 """Install IPython's default config file into the .ipython dir.
3327 """Install IPython's default config file into the .ipython dir.
3334
3328
3335 If the default config file (:file:`ipython_config.py`) is already
3329 If the default config file (:file:`ipython_config.py`) is already
3336 installed, it will not be overwritten. You can force overwriting
3330 installed, it will not be overwritten. You can force overwriting
3337 by using the ``-o`` option::
3331 by using the ``-o`` option::
3338
3332
3339 In [1]: %install_default_config
3333 In [1]: %install_default_config
3340 """
3334 """
3341 if '-o' in s:
3335 if '-o' in s:
3342 overwrite = True
3336 overwrite = True
3343 else:
3337 else:
3344 overwrite = False
3338 overwrite = False
3345 from IPython.config import default
3339 from IPython.config import default
3346 config_dir = os.path.split(default.__file__)[0]
3340 config_dir = os.path.split(default.__file__)[0]
3347 ipython_dir = self.ipython_dir
3341 ipython_dir = self.ipython_dir
3348 default_config_file_name = 'ipython_config.py'
3342 default_config_file_name = 'ipython_config.py'
3349 src = os.path.join(config_dir, default_config_file_name)
3343 src = os.path.join(config_dir, default_config_file_name)
3350 dst = os.path.join(ipython_dir, default_config_file_name)
3344 dst = os.path.join(ipython_dir, default_config_file_name)
3351 if (not os.path.isfile(dst)) or overwrite:
3345 if (not os.path.isfile(dst)) or overwrite:
3352 shutil.copy(src, dst)
3346 shutil.copy(src, dst)
3353 print "Installing default config file: %s" % dst
3347 print "Installing default config file: %s" % dst
3354
3348
3355 # Pylab support: simple wrappers that activate pylab, load gui input
3349 # Pylab support: simple wrappers that activate pylab, load gui input
3356 # handling and modify slightly %run
3350 # handling and modify slightly %run
3357
3351
3358 @testdec.skip_doctest
3352 @testdec.skip_doctest
3359 def _pylab_magic_run(self, parameter_s=''):
3353 def _pylab_magic_run(self, parameter_s=''):
3360 Magic.magic_run(self, parameter_s,
3354 Magic.magic_run(self, parameter_s,
3361 runner=mpl_runner(self.shell.safe_execfile))
3355 runner=mpl_runner(self.shell.safe_execfile))
3362
3356
3363 _pylab_magic_run.__doc__ = magic_run.__doc__
3357 _pylab_magic_run.__doc__ = magic_run.__doc__
3364
3358
3365 @testdec.skip_doctest
3359 @testdec.skip_doctest
3366 def magic_pylab(self, s):
3360 def magic_pylab(self, s):
3367 """Load numpy and matplotlib to work interactively.
3361 """Load numpy and matplotlib to work interactively.
3368
3362
3369 %pylab [GUINAME]
3363 %pylab [GUINAME]
3370
3364
3371 This function lets you activate pylab (matplotlib, numpy and
3365 This function lets you activate pylab (matplotlib, numpy and
3372 interactive support) at any point during an IPython session.
3366 interactive support) at any point during an IPython session.
3373
3367
3374 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3368 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3375 pylab and mlab, as well as all names from numpy and pylab.
3369 pylab and mlab, as well as all names from numpy and pylab.
3376
3370
3377 Parameters
3371 Parameters
3378 ----------
3372 ----------
3379 guiname : optional
3373 guiname : optional
3380 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk' or
3374 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk' or
3381 'tk'). If given, the corresponding Matplotlib backend is used,
3375 'tk'). If given, the corresponding Matplotlib backend is used,
3382 otherwise matplotlib's default (which you can override in your
3376 otherwise matplotlib's default (which you can override in your
3383 matplotlib config file) is used.
3377 matplotlib config file) is used.
3384
3378
3385 Examples
3379 Examples
3386 --------
3380 --------
3387 In this case, where the MPL default is TkAgg:
3381 In this case, where the MPL default is TkAgg:
3388 In [2]: %pylab
3382 In [2]: %pylab
3389
3383
3390 Welcome to pylab, a matplotlib-based Python environment.
3384 Welcome to pylab, a matplotlib-based Python environment.
3391 Backend in use: TkAgg
3385 Backend in use: TkAgg
3392 For more information, type 'help(pylab)'.
3386 For more information, type 'help(pylab)'.
3393
3387
3394 But you can explicitly request a different backend:
3388 But you can explicitly request a different backend:
3395 In [3]: %pylab qt
3389 In [3]: %pylab qt
3396
3390
3397 Welcome to pylab, a matplotlib-based Python environment.
3391 Welcome to pylab, a matplotlib-based Python environment.
3398 Backend in use: Qt4Agg
3392 Backend in use: Qt4Agg
3399 For more information, type 'help(pylab)'.
3393 For more information, type 'help(pylab)'.
3400 """
3394 """
3401 self.shell.enable_pylab(s)
3395 self.shell.enable_pylab(s)
3402
3396
3403 def magic_tb(self, s):
3397 def magic_tb(self, s):
3404 """Print the last traceback with the currently active exception mode.
3398 """Print the last traceback with the currently active exception mode.
3405
3399
3406 See %xmode for changing exception reporting modes."""
3400 See %xmode for changing exception reporting modes."""
3407 self.shell.showtraceback()
3401 self.shell.showtraceback()
3408
3402
3409 @testdec.skip_doctest
3403 @testdec.skip_doctest
3410 def magic_precision(self, s=''):
3404 def magic_precision(self, s=''):
3411 """Set floating point precision for pretty printing.
3405 """Set floating point precision for pretty printing.
3412
3406
3413 Can set either integer precision or a format string.
3407 Can set either integer precision or a format string.
3414
3408
3415 If numpy has been imported and precision is an int,
3409 If numpy has been imported and precision is an int,
3416 numpy display precision will also be set, via ``numpy.set_printoptions``.
3410 numpy display precision will also be set, via ``numpy.set_printoptions``.
3417
3411
3418 If no argument is given, defaults will be restored.
3412 If no argument is given, defaults will be restored.
3419
3413
3420 Examples
3414 Examples
3421 --------
3415 --------
3422 ::
3416 ::
3423
3417
3424 In [1]: from math import pi
3418 In [1]: from math import pi
3425
3419
3426 In [2]: %precision 3
3420 In [2]: %precision 3
3427 Out[2]: '%.3f'
3421 Out[2]: '%.3f'
3428
3422
3429 In [3]: pi
3423 In [3]: pi
3430 Out[3]: 3.142
3424 Out[3]: 3.142
3431
3425
3432 In [4]: %precision %i
3426 In [4]: %precision %i
3433 Out[4]: '%i'
3427 Out[4]: '%i'
3434
3428
3435 In [5]: pi
3429 In [5]: pi
3436 Out[5]: 3
3430 Out[5]: 3
3437
3431
3438 In [6]: %precision %e
3432 In [6]: %precision %e
3439 Out[6]: '%e'
3433 Out[6]: '%e'
3440
3434
3441 In [7]: pi**10
3435 In [7]: pi**10
3442 Out[7]: 9.364805e+04
3436 Out[7]: 9.364805e+04
3443
3437
3444 In [8]: %precision
3438 In [8]: %precision
3445 Out[8]: '%r'
3439 Out[8]: '%r'
3446
3440
3447 In [9]: pi**10
3441 In [9]: pi**10
3448 Out[9]: 93648.047476082982
3442 Out[9]: 93648.047476082982
3449
3443
3450 """
3444 """
3451
3445
3452 ptformatter = self.shell.display_formatter.formatters['text/plain']
3446 ptformatter = self.shell.display_formatter.formatters['text/plain']
3453 ptformatter.float_precision = s
3447 ptformatter.float_precision = s
3454 return ptformatter.float_format
3448 return ptformatter.float_format
3455
3449
3456 # end Magic
3450 # end Magic
@@ -1,109 +1,109 b''
1 """Tests for the IPython tab-completion machinery.
1 """Tests for the IPython tab-completion machinery.
2 """
2 """
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Module imports
4 # Module imports
5 #-----------------------------------------------------------------------------
5 #-----------------------------------------------------------------------------
6
6
7 # stdlib
7 # stdlib
8 import os
8 import os
9 import sys
9 import sys
10 import unittest
10 import unittest
11
11
12 # third party
12 # third party
13 import nose.tools as nt
13 import nose.tools as nt
14
14
15 # our own packages
15 # our own packages
16 from IPython.utils.tempdir import TemporaryDirectory
16 from IPython.utils.tempdir import TemporaryDirectory
17 from IPython.core.history import HistoryManager, extract_hist_ranges
17 from IPython.core.history import HistoryManager, extract_hist_ranges
18
18
19 def test_history():
19 def test_history():
20
20
21 ip = get_ipython()
21 ip = get_ipython()
22 with TemporaryDirectory() as tmpdir:
22 with TemporaryDirectory() as tmpdir:
23 #tmpdir = '/software/temp'
23 #tmpdir = '/software/temp'
24 histfile = os.path.realpath(os.path.join(tmpdir, 'history.sqlite'))
24 histfile = os.path.realpath(os.path.join(tmpdir, 'history.sqlite'))
25 # Ensure that we restore the history management that we mess with in
25 # Ensure that we restore the history management that we mess with in
26 # this test doesn't affect the IPython instance used by the test suite
26 # this test doesn't affect the IPython instance used by the test suite
27 # beyond this test.
27 # beyond this test.
28 hist_manager_ori = ip.history_manager
28 hist_manager_ori = ip.history_manager
29 try:
29 try:
30 ip.history_manager = HistoryManager(shell=ip)
30 ip.history_manager = HistoryManager(shell=ip)
31 ip.history_manager.hist_file = histfile
31 ip.history_manager.hist_file = histfile
32 ip.history_manager.init_db() # Has to be called after changing file
32 ip.history_manager.init_db() # Has to be called after changing file
33 ip.history_manager.reset()
33 ip.history_manager.reset()
34 print 'test',histfile
34 print 'test',histfile
35 hist = ['a=1', 'def f():\n test = 1\n return test', 'b=2']
35 hist = ['a=1', 'def f():\n test = 1\n return test', 'b=2']
36 for i, h in enumerate(hist, start=1):
36 for i, h in enumerate(hist, start=1):
37 ip.history_manager.store_inputs(i, h)
37 ip.history_manager.store_inputs(i, h)
38
38
39 ip.history_manager.db_log_output = True
39 ip.history_manager.db_log_output = True
40 # Doesn't match the input, but we'll just check it's stored.
40 # Doesn't match the input, but we'll just check it's stored.
41 ip.history_manager.output_hist_reprs[3].append("spam")
41 ip.history_manager.output_hist_reprs[3].append("spam")
42 ip.history_manager.store_output(3)
42 ip.history_manager.store_output(3)
43
43
44 nt.assert_equal(ip.history_manager.input_hist_raw, [''] + hist)
44 nt.assert_equal(ip.history_manager.input_hist_raw, [''] + hist)
45
45
46 # Check lines were written to DB
46 # Check lines were written to DB
47 c = ip.history_manager.db.execute("SELECT source_raw FROM history")
47 c = ip.history_manager.db.execute("SELECT source_raw FROM history")
48 nt.assert_equal([x for x, in c], hist)
48 nt.assert_equal([x for x, in c], hist)
49
49
50 # New session
50 # New session
51 ip.history_manager.reset()
51 ip.history_manager.reset()
52 newcmds = ["z=5","class X(object):\n pass", "k='p'"]
52 newcmds = ["z=5","class X(object):\n pass", "k='p'"]
53 for i, cmd in enumerate(newcmds, start=1):
53 for i, cmd in enumerate(newcmds, start=1):
54 ip.history_manager.store_inputs(i, cmd)
54 ip.history_manager.store_inputs(i, cmd)
55 gothist = ip.history_manager.get_history(start=1, stop=4)
55 gothist = ip.history_manager.get_range(start=1, stop=4)
56 nt.assert_equal(list(gothist), zip([0,0,0],[1,2,3], newcmds))
56 nt.assert_equal(list(gothist), zip([0,0,0],[1,2,3], newcmds))
57 # Previous session:
57 # Previous session:
58 gothist = ip.history_manager.get_history(-1, 1, 4)
58 gothist = ip.history_manager.get_range(-1, 1, 4)
59 nt.assert_equal(list(gothist), zip([1,1,1],[1,2,3], hist))
59 nt.assert_equal(list(gothist), zip([1,1,1],[1,2,3], hist))
60
60
61 # Check get_hist_tail
61 # Check get_hist_tail
62 gothist = ip.history_manager.get_hist_tail(4, output=True,
62 gothist = ip.history_manager.get_tail(4, output=True,
63 include_latest=True)
63 include_latest=True)
64 expected = [(1, 3, (hist[-1], ["spam"])),
64 expected = [(1, 3, (hist[-1], ["spam"])),
65 (2, 1, (newcmds[0], None)),
65 (2, 1, (newcmds[0], None)),
66 (2, 2, (newcmds[1], None)),
66 (2, 2, (newcmds[1], None)),
67 (2, 3, (newcmds[2], None)),]
67 (2, 3, (newcmds[2], None)),]
68 nt.assert_equal(list(gothist), expected)
68 nt.assert_equal(list(gothist), expected)
69
69
70 gothist = ip.history_manager.get_hist_tail(2)
70 gothist = ip.history_manager.get_tail(2)
71 expected = [(2, 1, newcmds[0]),
71 expected = [(2, 1, newcmds[0]),
72 (2, 2, newcmds[1])]
72 (2, 2, newcmds[1])]
73 nt.assert_equal(list(gothist), expected)
73 nt.assert_equal(list(gothist), expected)
74
74
75 # Check get_hist_search
75 # Check get_hist_search
76 gothist = ip.history_manager.get_hist_search("*test*")
76 gothist = ip.history_manager.search("*test*")
77 nt.assert_equal(list(gothist), [(1,2,hist[1])] )
77 nt.assert_equal(list(gothist), [(1,2,hist[1])] )
78 gothist = ip.history_manager.get_hist_search("b*", output=True)
78 gothist = ip.history_manager.search("b*", output=True)
79 nt.assert_equal(list(gothist), [(1,3,(hist[2],["spam"]))] )
79 nt.assert_equal(list(gothist), [(1,3,(hist[2],["spam"]))] )
80
80
81 # Cross testing: check that magic %save can get previous session.
81 # Cross testing: check that magic %save can get previous session.
82 testfilename = os.path.realpath(os.path.join(tmpdir, "test.py"))
82 testfilename = os.path.realpath(os.path.join(tmpdir, "test.py"))
83 ip.magic_save(testfilename + " ~1/1-3")
83 ip.magic_save(testfilename + " ~1/1-3")
84 testfile = open(testfilename, "r")
84 testfile = open(testfilename, "r")
85 nt.assert_equal(testfile.read(), "\n".join(hist))
85 nt.assert_equal(testfile.read(), "\n".join(hist))
86 finally:
86 finally:
87 # Restore history manager
87 # Restore history manager
88 ip.history_manager = hist_manager_ori
88 ip.history_manager = hist_manager_ori
89
89
90 def test_extract_hist_ranges():
90 def test_extract_hist_ranges():
91 instr = "1 2/3 ~4/5-6 ~4/7-~4/9 ~9/2-~7/5"
91 instr = "1 2/3 ~4/5-6 ~4/7-~4/9 ~9/2-~7/5"
92 expected = [(0, 1, 2), # 0 == current session
92 expected = [(0, 1, 2), # 0 == current session
93 (2, 3, 4),
93 (2, 3, 4),
94 (-4, 5, 7),
94 (-4, 5, 7),
95 (-4, 7, 10),
95 (-4, 7, 10),
96 (-9, 2, None), # None == to end
96 (-9, 2, None), # None == to end
97 (-8, 1, None),
97 (-8, 1, None),
98 (-7, 1, 6)]
98 (-7, 1, 6)]
99 actual = list(extract_hist_ranges(instr))
99 actual = list(extract_hist_ranges(instr))
100 nt.assert_equal(actual, expected)
100 nt.assert_equal(actual, expected)
101
101
102 def test_magic_rerun():
102 def test_magic_rerun():
103 """Simple test for %rerun (no args -> rerun last line)"""
103 """Simple test for %rerun (no args -> rerun last line)"""
104 ip = get_ipython()
104 ip = get_ipython()
105 ip.run_cell("a = 10")
105 ip.run_cell("a = 10")
106 ip.run_cell("a += 1")
106 ip.run_cell("a += 1")
107 nt.assert_equal(ip.user_ns["a"], 11)
107 nt.assert_equal(ip.user_ns["a"], 11)
108 ip.run_cell("%rerun")
108 ip.run_cell("%rerun")
109 nt.assert_equal(ip.user_ns["a"], 12)
109 nt.assert_equal(ip.user_ns["a"], 12)
@@ -1,643 +1,643 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 """A simple interactive kernel that talks to a frontend over 0MQ.
2 """A simple interactive kernel that talks to a frontend over 0MQ.
3
3
4 Things to do:
4 Things to do:
5
5
6 * Implement `set_parent` logic. Right before doing exec, the Kernel should
6 * Implement `set_parent` logic. Right before doing exec, the Kernel should
7 call set_parent on all the PUB objects with the message about to be executed.
7 call set_parent on all the PUB objects with the message about to be executed.
8 * Implement random port and security key logic.
8 * Implement random port and security key logic.
9 * Implement control messages.
9 * Implement control messages.
10 * Implement event loop and poll version.
10 * Implement event loop and poll version.
11 """
11 """
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16 from __future__ import print_function
16 from __future__ import print_function
17
17
18 # Standard library imports.
18 # Standard library imports.
19 import __builtin__
19 import __builtin__
20 import atexit
20 import atexit
21 import sys
21 import sys
22 import time
22 import time
23 import traceback
23 import traceback
24 import logging
24 import logging
25 # System library imports.
25 # System library imports.
26 import zmq
26 import zmq
27
27
28 # Local imports.
28 # Local imports.
29 from IPython.config.configurable import Configurable
29 from IPython.config.configurable import Configurable
30 from IPython.utils import io
30 from IPython.utils import io
31 from IPython.utils.jsonutil import json_clean
31 from IPython.utils.jsonutil import json_clean
32 from IPython.lib import pylabtools
32 from IPython.lib import pylabtools
33 from IPython.utils.traitlets import Instance, Float
33 from IPython.utils.traitlets import Instance, Float
34 from entry_point import (base_launch_kernel, make_argument_parser, make_kernel,
34 from entry_point import (base_launch_kernel, make_argument_parser, make_kernel,
35 start_kernel)
35 start_kernel)
36 from iostream import OutStream
36 from iostream import OutStream
37 from session import Session, Message
37 from session import Session, Message
38 from zmqshell import ZMQInteractiveShell
38 from zmqshell import ZMQInteractiveShell
39
39
40 #-----------------------------------------------------------------------------
40 #-----------------------------------------------------------------------------
41 # Globals
41 # Globals
42 #-----------------------------------------------------------------------------
42 #-----------------------------------------------------------------------------
43
43
44 # Module-level logger
44 # Module-level logger
45 logger = logging.getLogger(__name__)
45 logger = logging.getLogger(__name__)
46
46
47 #-----------------------------------------------------------------------------
47 #-----------------------------------------------------------------------------
48 # Main kernel class
48 # Main kernel class
49 #-----------------------------------------------------------------------------
49 #-----------------------------------------------------------------------------
50
50
51 class Kernel(Configurable):
51 class Kernel(Configurable):
52
52
53 #---------------------------------------------------------------------------
53 #---------------------------------------------------------------------------
54 # Kernel interface
54 # Kernel interface
55 #---------------------------------------------------------------------------
55 #---------------------------------------------------------------------------
56
56
57 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
57 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
58 session = Instance(Session)
58 session = Instance(Session)
59 reply_socket = Instance('zmq.Socket')
59 reply_socket = Instance('zmq.Socket')
60 pub_socket = Instance('zmq.Socket')
60 pub_socket = Instance('zmq.Socket')
61 req_socket = Instance('zmq.Socket')
61 req_socket = Instance('zmq.Socket')
62
62
63 # Private interface
63 # Private interface
64
64
65 # Time to sleep after flushing the stdout/err buffers in each execute
65 # Time to sleep after flushing the stdout/err buffers in each execute
66 # cycle. While this introduces a hard limit on the minimal latency of the
66 # cycle. While this introduces a hard limit on the minimal latency of the
67 # execute cycle, it helps prevent output synchronization problems for
67 # execute cycle, it helps prevent output synchronization problems for
68 # clients.
68 # clients.
69 # Units are in seconds. The minimum zmq latency on local host is probably
69 # Units are in seconds. The minimum zmq latency on local host is probably
70 # ~150 microseconds, set this to 500us for now. We may need to increase it
70 # ~150 microseconds, set this to 500us for now. We may need to increase it
71 # a little if it's not enough after more interactive testing.
71 # a little if it's not enough after more interactive testing.
72 _execute_sleep = Float(0.0005, config=True)
72 _execute_sleep = Float(0.0005, config=True)
73
73
74 # Frequency of the kernel's event loop.
74 # Frequency of the kernel's event loop.
75 # Units are in seconds, kernel subclasses for GUI toolkits may need to
75 # Units are in seconds, kernel subclasses for GUI toolkits may need to
76 # adapt to milliseconds.
76 # adapt to milliseconds.
77 _poll_interval = Float(0.05, config=True)
77 _poll_interval = Float(0.05, config=True)
78
78
79 # If the shutdown was requested over the network, we leave here the
79 # If the shutdown was requested over the network, we leave here the
80 # necessary reply message so it can be sent by our registered atexit
80 # necessary reply message so it can be sent by our registered atexit
81 # handler. This ensures that the reply is only sent to clients truly at
81 # handler. This ensures that the reply is only sent to clients truly at
82 # the end of our shutdown process (which happens after the underlying
82 # the end of our shutdown process (which happens after the underlying
83 # IPython shell's own shutdown).
83 # IPython shell's own shutdown).
84 _shutdown_message = None
84 _shutdown_message = None
85
85
86 # This is a dict of port number that the kernel is listening on. It is set
86 # This is a dict of port number that the kernel is listening on. It is set
87 # by record_ports and used by connect_request.
87 # by record_ports and used by connect_request.
88 _recorded_ports = None
88 _recorded_ports = None
89
89
90
90
91 def __init__(self, **kwargs):
91 def __init__(self, **kwargs):
92 super(Kernel, self).__init__(**kwargs)
92 super(Kernel, self).__init__(**kwargs)
93
93
94 # Before we even start up the shell, register *first* our exit handlers
94 # Before we even start up the shell, register *first* our exit handlers
95 # so they come before the shell's
95 # so they come before the shell's
96 atexit.register(self._at_shutdown)
96 atexit.register(self._at_shutdown)
97
97
98 # Initialize the InteractiveShell subclass
98 # Initialize the InteractiveShell subclass
99 self.shell = ZMQInteractiveShell.instance()
99 self.shell = ZMQInteractiveShell.instance()
100 self.shell.displayhook.session = self.session
100 self.shell.displayhook.session = self.session
101 self.shell.displayhook.pub_socket = self.pub_socket
101 self.shell.displayhook.pub_socket = self.pub_socket
102 self.shell.display_pub.session = self.session
102 self.shell.display_pub.session = self.session
103 self.shell.display_pub.pub_socket = self.pub_socket
103 self.shell.display_pub.pub_socket = self.pub_socket
104
104
105 # TMP - hack while developing
105 # TMP - hack while developing
106 self.shell._reply_content = None
106 self.shell._reply_content = None
107
107
108 # Build dict of handlers for message types
108 # Build dict of handlers for message types
109 msg_types = [ 'execute_request', 'complete_request',
109 msg_types = [ 'execute_request', 'complete_request',
110 'object_info_request', 'history_tail_request',
110 'object_info_request', 'history_tail_request',
111 'connect_request', 'shutdown_request']
111 'connect_request', 'shutdown_request']
112 self.handlers = {}
112 self.handlers = {}
113 for msg_type in msg_types:
113 for msg_type in msg_types:
114 self.handlers[msg_type] = getattr(self, msg_type)
114 self.handlers[msg_type] = getattr(self, msg_type)
115
115
116 def do_one_iteration(self):
116 def do_one_iteration(self):
117 """Do one iteration of the kernel's evaluation loop.
117 """Do one iteration of the kernel's evaluation loop.
118 """
118 """
119 ident,msg = self.session.recv(self.reply_socket, zmq.NOBLOCK)
119 ident,msg = self.session.recv(self.reply_socket, zmq.NOBLOCK)
120 if msg is None:
120 if msg is None:
121 return
121 return
122
122
123 # This assert will raise in versions of zeromq 2.0.7 and lesser.
123 # This assert will raise in versions of zeromq 2.0.7 and lesser.
124 # We now require 2.0.8 or above, so we can uncomment for safety.
124 # We now require 2.0.8 or above, so we can uncomment for safety.
125 # print(ident,msg, file=sys.__stdout__)
125 # print(ident,msg, file=sys.__stdout__)
126 assert ident is not None, "Missing message part."
126 assert ident is not None, "Missing message part."
127
127
128 # Print some info about this message and leave a '--->' marker, so it's
128 # Print some info about this message and leave a '--->' marker, so it's
129 # easier to trace visually the message chain when debugging. Each
129 # easier to trace visually the message chain when debugging. Each
130 # handler prints its message at the end.
130 # handler prints its message at the end.
131 # Eventually we'll move these from stdout to a logger.
131 # Eventually we'll move these from stdout to a logger.
132 logger.debug('\n*** MESSAGE TYPE:'+str(msg['msg_type'])+'***')
132 logger.debug('\n*** MESSAGE TYPE:'+str(msg['msg_type'])+'***')
133 logger.debug(' Content: '+str(msg['content'])+'\n --->\n ')
133 logger.debug(' Content: '+str(msg['content'])+'\n --->\n ')
134
134
135 # Find and call actual handler for message
135 # Find and call actual handler for message
136 handler = self.handlers.get(msg['msg_type'], None)
136 handler = self.handlers.get(msg['msg_type'], None)
137 if handler is None:
137 if handler is None:
138 logger.error("UNKNOWN MESSAGE TYPE:" +str(msg))
138 logger.error("UNKNOWN MESSAGE TYPE:" +str(msg))
139 else:
139 else:
140 handler(ident, msg)
140 handler(ident, msg)
141
141
142 # Check whether we should exit, in case the incoming message set the
142 # Check whether we should exit, in case the incoming message set the
143 # exit flag on
143 # exit flag on
144 if self.shell.exit_now:
144 if self.shell.exit_now:
145 logger.debug('\nExiting IPython kernel...')
145 logger.debug('\nExiting IPython kernel...')
146 # We do a normal, clean exit, which allows any actions registered
146 # We do a normal, clean exit, which allows any actions registered
147 # via atexit (such as history saving) to take place.
147 # via atexit (such as history saving) to take place.
148 sys.exit(0)
148 sys.exit(0)
149
149
150
150
151 def start(self):
151 def start(self):
152 """ Start the kernel main loop.
152 """ Start the kernel main loop.
153 """
153 """
154 while True:
154 while True:
155 time.sleep(self._poll_interval)
155 time.sleep(self._poll_interval)
156 self.do_one_iteration()
156 self.do_one_iteration()
157
157
158 def record_ports(self, xrep_port, pub_port, req_port, hb_port):
158 def record_ports(self, xrep_port, pub_port, req_port, hb_port):
159 """Record the ports that this kernel is using.
159 """Record the ports that this kernel is using.
160
160
161 The creator of the Kernel instance must call this methods if they
161 The creator of the Kernel instance must call this methods if they
162 want the :meth:`connect_request` method to return the port numbers.
162 want the :meth:`connect_request` method to return the port numbers.
163 """
163 """
164 self._recorded_ports = {
164 self._recorded_ports = {
165 'xrep_port' : xrep_port,
165 'xrep_port' : xrep_port,
166 'pub_port' : pub_port,
166 'pub_port' : pub_port,
167 'req_port' : req_port,
167 'req_port' : req_port,
168 'hb_port' : hb_port
168 'hb_port' : hb_port
169 }
169 }
170
170
171 #---------------------------------------------------------------------------
171 #---------------------------------------------------------------------------
172 # Kernel request handlers
172 # Kernel request handlers
173 #---------------------------------------------------------------------------
173 #---------------------------------------------------------------------------
174
174
175 def _publish_pyin(self, code, parent):
175 def _publish_pyin(self, code, parent):
176 """Publish the code request on the pyin stream."""
176 """Publish the code request on the pyin stream."""
177
177
178 pyin_msg = self.session.send(self.pub_socket, u'pyin',{u'code':code}, parent=parent)
178 pyin_msg = self.session.send(self.pub_socket, u'pyin',{u'code':code}, parent=parent)
179
179
180 def execute_request(self, ident, parent):
180 def execute_request(self, ident, parent):
181
181
182 status_msg = self.session.send(self.pub_socket,
182 status_msg = self.session.send(self.pub_socket,
183 u'status',
183 u'status',
184 {u'execution_state':u'busy'},
184 {u'execution_state':u'busy'},
185 parent=parent
185 parent=parent
186 )
186 )
187
187
188 try:
188 try:
189 content = parent[u'content']
189 content = parent[u'content']
190 code = content[u'code']
190 code = content[u'code']
191 silent = content[u'silent']
191 silent = content[u'silent']
192 except:
192 except:
193 logger.error("Got bad msg: ")
193 logger.error("Got bad msg: ")
194 logger.error(str(Message(parent)))
194 logger.error(str(Message(parent)))
195 return
195 return
196
196
197 shell = self.shell # we'll need this a lot here
197 shell = self.shell # we'll need this a lot here
198
198
199 # Replace raw_input. Note that is not sufficient to replace
199 # Replace raw_input. Note that is not sufficient to replace
200 # raw_input in the user namespace.
200 # raw_input in the user namespace.
201 raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
201 raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
202 __builtin__.raw_input = raw_input
202 __builtin__.raw_input = raw_input
203
203
204 # Set the parent message of the display hook and out streams.
204 # Set the parent message of the display hook and out streams.
205 shell.displayhook.set_parent(parent)
205 shell.displayhook.set_parent(parent)
206 shell.display_pub.set_parent(parent)
206 shell.display_pub.set_parent(parent)
207 sys.stdout.set_parent(parent)
207 sys.stdout.set_parent(parent)
208 sys.stderr.set_parent(parent)
208 sys.stderr.set_parent(parent)
209
209
210 # Re-broadcast our input for the benefit of listening clients, and
210 # Re-broadcast our input for the benefit of listening clients, and
211 # start computing output
211 # start computing output
212 if not silent:
212 if not silent:
213 self._publish_pyin(code, parent)
213 self._publish_pyin(code, parent)
214
214
215 reply_content = {}
215 reply_content = {}
216 try:
216 try:
217 if silent:
217 if silent:
218 # run_code uses 'exec' mode, so no displayhook will fire, and it
218 # run_code uses 'exec' mode, so no displayhook will fire, and it
219 # doesn't call logging or history manipulations. Print
219 # doesn't call logging or history manipulations. Print
220 # statements in that code will obviously still execute.
220 # statements in that code will obviously still execute.
221 shell.run_code(code)
221 shell.run_code(code)
222 else:
222 else:
223 # FIXME: the shell calls the exception handler itself.
223 # FIXME: the shell calls the exception handler itself.
224 shell._reply_content = None
224 shell._reply_content = None
225 shell.run_cell(code)
225 shell.run_cell(code)
226 except:
226 except:
227 status = u'error'
227 status = u'error'
228 # FIXME: this code right now isn't being used yet by default,
228 # FIXME: this code right now isn't being used yet by default,
229 # because the runlines() call above directly fires off exception
229 # because the runlines() call above directly fires off exception
230 # reporting. This code, therefore, is only active in the scenario
230 # reporting. This code, therefore, is only active in the scenario
231 # where runlines itself has an unhandled exception. We need to
231 # where runlines itself has an unhandled exception. We need to
232 # uniformize this, for all exception construction to come from a
232 # uniformize this, for all exception construction to come from a
233 # single location in the codbase.
233 # single location in the codbase.
234 etype, evalue, tb = sys.exc_info()
234 etype, evalue, tb = sys.exc_info()
235 tb_list = traceback.format_exception(etype, evalue, tb)
235 tb_list = traceback.format_exception(etype, evalue, tb)
236 reply_content.update(shell._showtraceback(etype, evalue, tb_list))
236 reply_content.update(shell._showtraceback(etype, evalue, tb_list))
237 else:
237 else:
238 status = u'ok'
238 status = u'ok'
239
239
240 reply_content[u'status'] = status
240 reply_content[u'status'] = status
241
241
242 # Return the execution counter so clients can display prompts
242 # Return the execution counter so clients can display prompts
243 reply_content['execution_count'] = shell.execution_count -1
243 reply_content['execution_count'] = shell.execution_count -1
244
244
245 # FIXME - fish exception info out of shell, possibly left there by
245 # FIXME - fish exception info out of shell, possibly left there by
246 # runlines. We'll need to clean up this logic later.
246 # runlines. We'll need to clean up this logic later.
247 if shell._reply_content is not None:
247 if shell._reply_content is not None:
248 reply_content.update(shell._reply_content)
248 reply_content.update(shell._reply_content)
249
249
250 # At this point, we can tell whether the main code execution succeeded
250 # At this point, we can tell whether the main code execution succeeded
251 # or not. If it did, we proceed to evaluate user_variables/expressions
251 # or not. If it did, we proceed to evaluate user_variables/expressions
252 if reply_content['status'] == 'ok':
252 if reply_content['status'] == 'ok':
253 reply_content[u'user_variables'] = \
253 reply_content[u'user_variables'] = \
254 shell.user_variables(content[u'user_variables'])
254 shell.user_variables(content[u'user_variables'])
255 reply_content[u'user_expressions'] = \
255 reply_content[u'user_expressions'] = \
256 shell.user_expressions(content[u'user_expressions'])
256 shell.user_expressions(content[u'user_expressions'])
257 else:
257 else:
258 # If there was an error, don't even try to compute variables or
258 # If there was an error, don't even try to compute variables or
259 # expressions
259 # expressions
260 reply_content[u'user_variables'] = {}
260 reply_content[u'user_variables'] = {}
261 reply_content[u'user_expressions'] = {}
261 reply_content[u'user_expressions'] = {}
262
262
263 # Payloads should be retrieved regardless of outcome, so we can both
263 # Payloads should be retrieved regardless of outcome, so we can both
264 # recover partial output (that could have been generated early in a
264 # recover partial output (that could have been generated early in a
265 # block, before an error) and clear the payload system always.
265 # block, before an error) and clear the payload system always.
266 reply_content[u'payload'] = shell.payload_manager.read_payload()
266 reply_content[u'payload'] = shell.payload_manager.read_payload()
267 # Be agressive about clearing the payload because we don't want
267 # Be agressive about clearing the payload because we don't want
268 # it to sit in memory until the next execute_request comes in.
268 # it to sit in memory until the next execute_request comes in.
269 shell.payload_manager.clear_payload()
269 shell.payload_manager.clear_payload()
270
270
271 # Flush output before sending the reply.
271 # Flush output before sending the reply.
272 sys.stdout.flush()
272 sys.stdout.flush()
273 sys.stderr.flush()
273 sys.stderr.flush()
274 # FIXME: on rare occasions, the flush doesn't seem to make it to the
274 # FIXME: on rare occasions, the flush doesn't seem to make it to the
275 # clients... This seems to mitigate the problem, but we definitely need
275 # clients... This seems to mitigate the problem, but we definitely need
276 # to better understand what's going on.
276 # to better understand what's going on.
277 if self._execute_sleep:
277 if self._execute_sleep:
278 time.sleep(self._execute_sleep)
278 time.sleep(self._execute_sleep)
279
279
280 # Send the reply.
280 # Send the reply.
281 reply_msg = self.session.send(self.reply_socket, u'execute_reply',
281 reply_msg = self.session.send(self.reply_socket, u'execute_reply',
282 reply_content, parent, ident=ident)
282 reply_content, parent, ident=ident)
283 logger.debug(str(reply_msg))
283 logger.debug(str(reply_msg))
284
284
285 if reply_msg['content']['status'] == u'error':
285 if reply_msg['content']['status'] == u'error':
286 self._abort_queue()
286 self._abort_queue()
287
287
288 status_msg = self.session.send(self.pub_socket,
288 status_msg = self.session.send(self.pub_socket,
289 u'status',
289 u'status',
290 {u'execution_state':u'idle'},
290 {u'execution_state':u'idle'},
291 parent=parent
291 parent=parent
292 )
292 )
293
293
294 def complete_request(self, ident, parent):
294 def complete_request(self, ident, parent):
295 txt, matches = self._complete(parent)
295 txt, matches = self._complete(parent)
296 matches = {'matches' : matches,
296 matches = {'matches' : matches,
297 'matched_text' : txt,
297 'matched_text' : txt,
298 'status' : 'ok'}
298 'status' : 'ok'}
299 completion_msg = self.session.send(self.reply_socket, 'complete_reply',
299 completion_msg = self.session.send(self.reply_socket, 'complete_reply',
300 matches, parent, ident)
300 matches, parent, ident)
301 logger.debug(str(completion_msg))
301 logger.debug(str(completion_msg))
302
302
303 def object_info_request(self, ident, parent):
303 def object_info_request(self, ident, parent):
304 object_info = self.shell.object_inspect(parent['content']['oname'])
304 object_info = self.shell.object_inspect(parent['content']['oname'])
305 # Before we send this object over, we scrub it for JSON usage
305 # Before we send this object over, we scrub it for JSON usage
306 oinfo = json_clean(object_info)
306 oinfo = json_clean(object_info)
307 msg = self.session.send(self.reply_socket, 'object_info_reply',
307 msg = self.session.send(self.reply_socket, 'object_info_reply',
308 oinfo, parent, ident)
308 oinfo, parent, ident)
309 logger.debug(msg)
309 logger.debug(msg)
310
310
311 def history_tail_request(self, ident, parent):
311 def history_tail_request(self, ident, parent):
312 # We need to pull these out, as passing **kwargs doesn't work with
312 # We need to pull these out, as passing **kwargs doesn't work with
313 # unicode keys before Python 2.6.5.
313 # unicode keys before Python 2.6.5.
314 n = parent['content']['n']
314 n = parent['content']['n']
315 raw = parent['content']['raw']
315 raw = parent['content']['raw']
316 output = parent['content']['output']
316 output = parent['content']['output']
317 hist = self.shell.history_manager.get_hist_tail(n, raw=raw, output=output)
317 hist = self.shell.history_manager.get_tail(n, raw=raw, output=output)
318 content = {'history' : list(hist)}
318 content = {'history' : list(hist)}
319 msg = self.session.send(self.reply_socket, 'history_tail_reply',
319 msg = self.session.send(self.reply_socket, 'history_tail_reply',
320 content, parent, ident)
320 content, parent, ident)
321 logger.debug(str(msg))
321 logger.debug(str(msg))
322
322
323 def connect_request(self, ident, parent):
323 def connect_request(self, ident, parent):
324 if self._recorded_ports is not None:
324 if self._recorded_ports is not None:
325 content = self._recorded_ports.copy()
325 content = self._recorded_ports.copy()
326 else:
326 else:
327 content = {}
327 content = {}
328 msg = self.session.send(self.reply_socket, 'connect_reply',
328 msg = self.session.send(self.reply_socket, 'connect_reply',
329 content, parent, ident)
329 content, parent, ident)
330 logger.debug(msg)
330 logger.debug(msg)
331
331
332 def shutdown_request(self, ident, parent):
332 def shutdown_request(self, ident, parent):
333 self.shell.exit_now = True
333 self.shell.exit_now = True
334 self._shutdown_message = self.session.msg(u'shutdown_reply', parent['content'], parent)
334 self._shutdown_message = self.session.msg(u'shutdown_reply', parent['content'], parent)
335 sys.exit(0)
335 sys.exit(0)
336
336
337 #---------------------------------------------------------------------------
337 #---------------------------------------------------------------------------
338 # Protected interface
338 # Protected interface
339 #---------------------------------------------------------------------------
339 #---------------------------------------------------------------------------
340
340
341 def _abort_queue(self):
341 def _abort_queue(self):
342 while True:
342 while True:
343 ident,msg = self.session.recv(self.reply_socket, zmq.NOBLOCK)
343 ident,msg = self.session.recv(self.reply_socket, zmq.NOBLOCK)
344 if msg is None:
344 if msg is None:
345 break
345 break
346 else:
346 else:
347 assert ident is not None, \
347 assert ident is not None, \
348 "Unexpected missing message part."
348 "Unexpected missing message part."
349
349
350 logger.debug("Aborting:\n"+str(Message(msg)))
350 logger.debug("Aborting:\n"+str(Message(msg)))
351 msg_type = msg['msg_type']
351 msg_type = msg['msg_type']
352 reply_type = msg_type.split('_')[0] + '_reply'
352 reply_type = msg_type.split('_')[0] + '_reply'
353 reply_msg = self.session.send(self.reply_socket, reply_type,
353 reply_msg = self.session.send(self.reply_socket, reply_type,
354 {'status' : 'aborted'}, msg, ident=ident)
354 {'status' : 'aborted'}, msg, ident=ident)
355 logger.debug(reply_msg)
355 logger.debug(reply_msg)
356 # We need to wait a bit for requests to come in. This can probably
356 # We need to wait a bit for requests to come in. This can probably
357 # be set shorter for true asynchronous clients.
357 # be set shorter for true asynchronous clients.
358 time.sleep(0.1)
358 time.sleep(0.1)
359
359
360 def _raw_input(self, prompt, ident, parent):
360 def _raw_input(self, prompt, ident, parent):
361 # Flush output before making the request.
361 # Flush output before making the request.
362 sys.stderr.flush()
362 sys.stderr.flush()
363 sys.stdout.flush()
363 sys.stdout.flush()
364
364
365 # Send the input request.
365 # Send the input request.
366 content = dict(prompt=prompt)
366 content = dict(prompt=prompt)
367 msg = self.session.send(self.req_socket, u'input_request', content, parent)
367 msg = self.session.send(self.req_socket, u'input_request', content, parent)
368
368
369 # Await a response.
369 # Await a response.
370 ident, reply = self.session.recv(self.req_socket, 0)
370 ident, reply = self.session.recv(self.req_socket, 0)
371 try:
371 try:
372 value = reply['content']['value']
372 value = reply['content']['value']
373 except:
373 except:
374 logger.error("Got bad raw_input reply: ")
374 logger.error("Got bad raw_input reply: ")
375 logger.error(str(Message(parent)))
375 logger.error(str(Message(parent)))
376 value = ''
376 value = ''
377 return value
377 return value
378
378
379 def _complete(self, msg):
379 def _complete(self, msg):
380 c = msg['content']
380 c = msg['content']
381 try:
381 try:
382 cpos = int(c['cursor_pos'])
382 cpos = int(c['cursor_pos'])
383 except:
383 except:
384 # If we don't get something that we can convert to an integer, at
384 # If we don't get something that we can convert to an integer, at
385 # least attempt the completion guessing the cursor is at the end of
385 # least attempt the completion guessing the cursor is at the end of
386 # the text, if there's any, and otherwise of the line
386 # the text, if there's any, and otherwise of the line
387 cpos = len(c['text'])
387 cpos = len(c['text'])
388 if cpos==0:
388 if cpos==0:
389 cpos = len(c['line'])
389 cpos = len(c['line'])
390 return self.shell.complete(c['text'], c['line'], cpos)
390 return self.shell.complete(c['text'], c['line'], cpos)
391
391
392 def _object_info(self, context):
392 def _object_info(self, context):
393 symbol, leftover = self._symbol_from_context(context)
393 symbol, leftover = self._symbol_from_context(context)
394 if symbol is not None and not leftover:
394 if symbol is not None and not leftover:
395 doc = getattr(symbol, '__doc__', '')
395 doc = getattr(symbol, '__doc__', '')
396 else:
396 else:
397 doc = ''
397 doc = ''
398 object_info = dict(docstring = doc)
398 object_info = dict(docstring = doc)
399 return object_info
399 return object_info
400
400
401 def _symbol_from_context(self, context):
401 def _symbol_from_context(self, context):
402 if not context:
402 if not context:
403 return None, context
403 return None, context
404
404
405 base_symbol_string = context[0]
405 base_symbol_string = context[0]
406 symbol = self.shell.user_ns.get(base_symbol_string, None)
406 symbol = self.shell.user_ns.get(base_symbol_string, None)
407 if symbol is None:
407 if symbol is None:
408 symbol = __builtin__.__dict__.get(base_symbol_string, None)
408 symbol = __builtin__.__dict__.get(base_symbol_string, None)
409 if symbol is None:
409 if symbol is None:
410 return None, context
410 return None, context
411
411
412 context = context[1:]
412 context = context[1:]
413 for i, name in enumerate(context):
413 for i, name in enumerate(context):
414 new_symbol = getattr(symbol, name, None)
414 new_symbol = getattr(symbol, name, None)
415 if new_symbol is None:
415 if new_symbol is None:
416 return symbol, context[i:]
416 return symbol, context[i:]
417 else:
417 else:
418 symbol = new_symbol
418 symbol = new_symbol
419
419
420 return symbol, []
420 return symbol, []
421
421
422 def _at_shutdown(self):
422 def _at_shutdown(self):
423 """Actions taken at shutdown by the kernel, called by python's atexit.
423 """Actions taken at shutdown by the kernel, called by python's atexit.
424 """
424 """
425 # io.rprint("Kernel at_shutdown") # dbg
425 # io.rprint("Kernel at_shutdown") # dbg
426 if self._shutdown_message is not None:
426 if self._shutdown_message is not None:
427 self.session.send(self.reply_socket, self._shutdown_message)
427 self.session.send(self.reply_socket, self._shutdown_message)
428 self.session.send(self.pub_socket, self._shutdown_message)
428 self.session.send(self.pub_socket, self._shutdown_message)
429 logger.debug(str(self._shutdown_message))
429 logger.debug(str(self._shutdown_message))
430 # A very short sleep to give zmq time to flush its message buffers
430 # A very short sleep to give zmq time to flush its message buffers
431 # before Python truly shuts down.
431 # before Python truly shuts down.
432 time.sleep(0.01)
432 time.sleep(0.01)
433
433
434
434
435 class QtKernel(Kernel):
435 class QtKernel(Kernel):
436 """A Kernel subclass with Qt support."""
436 """A Kernel subclass with Qt support."""
437
437
438 def start(self):
438 def start(self):
439 """Start a kernel with QtPy4 event loop integration."""
439 """Start a kernel with QtPy4 event loop integration."""
440
440
441 from PyQt4 import QtCore
441 from PyQt4 import QtCore
442 from IPython.lib.guisupport import get_app_qt4, start_event_loop_qt4
442 from IPython.lib.guisupport import get_app_qt4, start_event_loop_qt4
443
443
444 self.app = get_app_qt4([" "])
444 self.app = get_app_qt4([" "])
445 self.app.setQuitOnLastWindowClosed(False)
445 self.app.setQuitOnLastWindowClosed(False)
446 self.timer = QtCore.QTimer()
446 self.timer = QtCore.QTimer()
447 self.timer.timeout.connect(self.do_one_iteration)
447 self.timer.timeout.connect(self.do_one_iteration)
448 # Units for the timer are in milliseconds
448 # Units for the timer are in milliseconds
449 self.timer.start(1000*self._poll_interval)
449 self.timer.start(1000*self._poll_interval)
450 start_event_loop_qt4(self.app)
450 start_event_loop_qt4(self.app)
451
451
452
452
453 class WxKernel(Kernel):
453 class WxKernel(Kernel):
454 """A Kernel subclass with Wx support."""
454 """A Kernel subclass with Wx support."""
455
455
456 def start(self):
456 def start(self):
457 """Start a kernel with wx event loop support."""
457 """Start a kernel with wx event loop support."""
458
458
459 import wx
459 import wx
460 from IPython.lib.guisupport import start_event_loop_wx
460 from IPython.lib.guisupport import start_event_loop_wx
461
461
462 doi = self.do_one_iteration
462 doi = self.do_one_iteration
463 # Wx uses milliseconds
463 # Wx uses milliseconds
464 poll_interval = int(1000*self._poll_interval)
464 poll_interval = int(1000*self._poll_interval)
465
465
466 # We have to put the wx.Timer in a wx.Frame for it to fire properly.
466 # We have to put the wx.Timer in a wx.Frame for it to fire properly.
467 # We make the Frame hidden when we create it in the main app below.
467 # We make the Frame hidden when we create it in the main app below.
468 class TimerFrame(wx.Frame):
468 class TimerFrame(wx.Frame):
469 def __init__(self, func):
469 def __init__(self, func):
470 wx.Frame.__init__(self, None, -1)
470 wx.Frame.__init__(self, None, -1)
471 self.timer = wx.Timer(self)
471 self.timer = wx.Timer(self)
472 # Units for the timer are in milliseconds
472 # Units for the timer are in milliseconds
473 self.timer.Start(poll_interval)
473 self.timer.Start(poll_interval)
474 self.Bind(wx.EVT_TIMER, self.on_timer)
474 self.Bind(wx.EVT_TIMER, self.on_timer)
475 self.func = func
475 self.func = func
476
476
477 def on_timer(self, event):
477 def on_timer(self, event):
478 self.func()
478 self.func()
479
479
480 # We need a custom wx.App to create our Frame subclass that has the
480 # We need a custom wx.App to create our Frame subclass that has the
481 # wx.Timer to drive the ZMQ event loop.
481 # wx.Timer to drive the ZMQ event loop.
482 class IPWxApp(wx.App):
482 class IPWxApp(wx.App):
483 def OnInit(self):
483 def OnInit(self):
484 self.frame = TimerFrame(doi)
484 self.frame = TimerFrame(doi)
485 self.frame.Show(False)
485 self.frame.Show(False)
486 return True
486 return True
487
487
488 # The redirect=False here makes sure that wx doesn't replace
488 # The redirect=False here makes sure that wx doesn't replace
489 # sys.stdout/stderr with its own classes.
489 # sys.stdout/stderr with its own classes.
490 self.app = IPWxApp(redirect=False)
490 self.app = IPWxApp(redirect=False)
491 start_event_loop_wx(self.app)
491 start_event_loop_wx(self.app)
492
492
493
493
494 class TkKernel(Kernel):
494 class TkKernel(Kernel):
495 """A Kernel subclass with Tk support."""
495 """A Kernel subclass with Tk support."""
496
496
497 def start(self):
497 def start(self):
498 """Start a Tk enabled event loop."""
498 """Start a Tk enabled event loop."""
499
499
500 import Tkinter
500 import Tkinter
501 doi = self.do_one_iteration
501 doi = self.do_one_iteration
502 # Tk uses milliseconds
502 # Tk uses milliseconds
503 poll_interval = int(1000*self._poll_interval)
503 poll_interval = int(1000*self._poll_interval)
504 # For Tkinter, we create a Tk object and call its withdraw method.
504 # For Tkinter, we create a Tk object and call its withdraw method.
505 class Timer(object):
505 class Timer(object):
506 def __init__(self, func):
506 def __init__(self, func):
507 self.app = Tkinter.Tk()
507 self.app = Tkinter.Tk()
508 self.app.withdraw()
508 self.app.withdraw()
509 self.func = func
509 self.func = func
510
510
511 def on_timer(self):
511 def on_timer(self):
512 self.func()
512 self.func()
513 self.app.after(poll_interval, self.on_timer)
513 self.app.after(poll_interval, self.on_timer)
514
514
515 def start(self):
515 def start(self):
516 self.on_timer() # Call it once to get things going.
516 self.on_timer() # Call it once to get things going.
517 self.app.mainloop()
517 self.app.mainloop()
518
518
519 self.timer = Timer(doi)
519 self.timer = Timer(doi)
520 self.timer.start()
520 self.timer.start()
521
521
522
522
523 class GTKKernel(Kernel):
523 class GTKKernel(Kernel):
524 """A Kernel subclass with GTK support."""
524 """A Kernel subclass with GTK support."""
525
525
526 def start(self):
526 def start(self):
527 """Start the kernel, coordinating with the GTK event loop"""
527 """Start the kernel, coordinating with the GTK event loop"""
528 from .gui.gtkembed import GTKEmbed
528 from .gui.gtkembed import GTKEmbed
529
529
530 gtk_kernel = GTKEmbed(self)
530 gtk_kernel = GTKEmbed(self)
531 gtk_kernel.start()
531 gtk_kernel.start()
532
532
533
533
534 #-----------------------------------------------------------------------------
534 #-----------------------------------------------------------------------------
535 # Kernel main and launch functions
535 # Kernel main and launch functions
536 #-----------------------------------------------------------------------------
536 #-----------------------------------------------------------------------------
537
537
538 def launch_kernel(ip=None, xrep_port=0, pub_port=0, req_port=0, hb_port=0,
538 def launch_kernel(ip=None, xrep_port=0, pub_port=0, req_port=0, hb_port=0,
539 independent=False, pylab=False, colors=None):
539 independent=False, pylab=False, colors=None):
540 """Launches a localhost kernel, binding to the specified ports.
540 """Launches a localhost kernel, binding to the specified ports.
541
541
542 Parameters
542 Parameters
543 ----------
543 ----------
544 ip : str, optional
544 ip : str, optional
545 The ip address the kernel will bind to.
545 The ip address the kernel will bind to.
546
546
547 xrep_port : int, optional
547 xrep_port : int, optional
548 The port to use for XREP channel.
548 The port to use for XREP channel.
549
549
550 pub_port : int, optional
550 pub_port : int, optional
551 The port to use for the SUB channel.
551 The port to use for the SUB channel.
552
552
553 req_port : int, optional
553 req_port : int, optional
554 The port to use for the REQ (raw input) channel.
554 The port to use for the REQ (raw input) channel.
555
555
556 hb_port : int, optional
556 hb_port : int, optional
557 The port to use for the hearbeat REP channel.
557 The port to use for the hearbeat REP channel.
558
558
559 independent : bool, optional (default False)
559 independent : bool, optional (default False)
560 If set, the kernel process is guaranteed to survive if this process
560 If set, the kernel process is guaranteed to survive if this process
561 dies. If not set, an effort is made to ensure that the kernel is killed
561 dies. If not set, an effort is made to ensure that the kernel is killed
562 when this process dies. Note that in this case it is still good practice
562 when this process dies. Note that in this case it is still good practice
563 to kill kernels manually before exiting.
563 to kill kernels manually before exiting.
564
564
565 pylab : bool or string, optional (default False)
565 pylab : bool or string, optional (default False)
566 If not False, the kernel will be launched with pylab enabled. If a
566 If not False, the kernel will be launched with pylab enabled. If a
567 string is passed, matplotlib will use the specified backend. Otherwise,
567 string is passed, matplotlib will use the specified backend. Otherwise,
568 matplotlib's default backend will be used.
568 matplotlib's default backend will be used.
569
569
570 colors : None or string, optional (default None)
570 colors : None or string, optional (default None)
571 If not None, specify the color scheme. One of (NoColor, LightBG, Linux)
571 If not None, specify the color scheme. One of (NoColor, LightBG, Linux)
572
572
573 Returns
573 Returns
574 -------
574 -------
575 A tuple of form:
575 A tuple of form:
576 (kernel_process, xrep_port, pub_port, req_port)
576 (kernel_process, xrep_port, pub_port, req_port)
577 where kernel_process is a Popen object and the ports are integers.
577 where kernel_process is a Popen object and the ports are integers.
578 """
578 """
579 extra_arguments = []
579 extra_arguments = []
580 if pylab:
580 if pylab:
581 extra_arguments.append('--pylab')
581 extra_arguments.append('--pylab')
582 if isinstance(pylab, basestring):
582 if isinstance(pylab, basestring):
583 extra_arguments.append(pylab)
583 extra_arguments.append(pylab)
584 if ip is not None:
584 if ip is not None:
585 extra_arguments.append('--ip')
585 extra_arguments.append('--ip')
586 if isinstance(ip, basestring):
586 if isinstance(ip, basestring):
587 extra_arguments.append(ip)
587 extra_arguments.append(ip)
588 if colors is not None:
588 if colors is not None:
589 extra_arguments.append('--colors')
589 extra_arguments.append('--colors')
590 extra_arguments.append(colors)
590 extra_arguments.append(colors)
591 return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
591 return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
592 xrep_port, pub_port, req_port, hb_port,
592 xrep_port, pub_port, req_port, hb_port,
593 independent, extra_arguments)
593 independent, extra_arguments)
594
594
595
595
596 def main():
596 def main():
597 """ The IPython kernel main entry point.
597 """ The IPython kernel main entry point.
598 """
598 """
599 parser = make_argument_parser()
599 parser = make_argument_parser()
600 parser.add_argument('--pylab', type=str, metavar='GUI', nargs='?',
600 parser.add_argument('--pylab', type=str, metavar='GUI', nargs='?',
601 const='auto', help = \
601 const='auto', help = \
602 "Pre-load matplotlib and numpy for interactive use. If GUI is not \
602 "Pre-load matplotlib and numpy for interactive use. If GUI is not \
603 given, the GUI backend is matplotlib's, otherwise use one of: \
603 given, the GUI backend is matplotlib's, otherwise use one of: \
604 ['tk', 'gtk', 'qt', 'wx', 'inline'].")
604 ['tk', 'gtk', 'qt', 'wx', 'inline'].")
605 parser.add_argument('--colors',
605 parser.add_argument('--colors',
606 type=str, dest='colors',
606 type=str, dest='colors',
607 help="Set the color scheme (NoColor, Linux, and LightBG).",
607 help="Set the color scheme (NoColor, Linux, and LightBG).",
608 metavar='ZMQInteractiveShell.colors')
608 metavar='ZMQInteractiveShell.colors')
609 namespace = parser.parse_args()
609 namespace = parser.parse_args()
610
610
611 kernel_class = Kernel
611 kernel_class = Kernel
612
612
613 kernel_classes = {
613 kernel_classes = {
614 'qt' : QtKernel,
614 'qt' : QtKernel,
615 'qt4': QtKernel,
615 'qt4': QtKernel,
616 'inline': Kernel,
616 'inline': Kernel,
617 'wx' : WxKernel,
617 'wx' : WxKernel,
618 'tk' : TkKernel,
618 'tk' : TkKernel,
619 'gtk': GTKKernel,
619 'gtk': GTKKernel,
620 }
620 }
621 if namespace.pylab:
621 if namespace.pylab:
622 if namespace.pylab == 'auto':
622 if namespace.pylab == 'auto':
623 gui, backend = pylabtools.find_gui_and_backend()
623 gui, backend = pylabtools.find_gui_and_backend()
624 else:
624 else:
625 gui, backend = pylabtools.find_gui_and_backend(namespace.pylab)
625 gui, backend = pylabtools.find_gui_and_backend(namespace.pylab)
626 kernel_class = kernel_classes.get(gui)
626 kernel_class = kernel_classes.get(gui)
627 if kernel_class is None:
627 if kernel_class is None:
628 raise ValueError('GUI is not supported: %r' % gui)
628 raise ValueError('GUI is not supported: %r' % gui)
629 pylabtools.activate_matplotlib(backend)
629 pylabtools.activate_matplotlib(backend)
630 if namespace.colors:
630 if namespace.colors:
631 ZMQInteractiveShell.colors=namespace.colors
631 ZMQInteractiveShell.colors=namespace.colors
632
632
633 kernel = make_kernel(namespace, kernel_class, OutStream)
633 kernel = make_kernel(namespace, kernel_class, OutStream)
634
634
635 if namespace.pylab:
635 if namespace.pylab:
636 pylabtools.import_pylab(kernel.shell.user_ns, backend,
636 pylabtools.import_pylab(kernel.shell.user_ns, backend,
637 shell=kernel.shell)
637 shell=kernel.shell)
638
638
639 start_kernel(namespace, kernel)
639 start_kernel(namespace, kernel)
640
640
641
641
642 if __name__ == '__main__':
642 if __name__ == '__main__':
643 main()
643 main()
General Comments 0
You need to be logged in to leave comments. Login now