##// END OF EJS Templates
Fix more failures due to direct shell access in magics.
Fernando Perez -
Show More
@@ -1,982 +1,982 b''
1 """ History related magics and functionality """
1 """ History related magics and functionality """
2 #-----------------------------------------------------------------------------
2 #-----------------------------------------------------------------------------
3 # Copyright (C) 2010-2011 The IPython Development Team.
3 # Copyright (C) 2010-2011 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 atexit
16 import atexit
17 import datetime
17 import datetime
18 from io import open as io_open
18 from io import open as io_open
19 import os
19 import os
20 import re
20 import re
21 try:
21 try:
22 import sqlite3
22 import sqlite3
23 except ImportError:
23 except ImportError:
24 sqlite3 = None
24 sqlite3 = None
25 import threading
25 import threading
26
26
27 # Our own packages
27 # Our own packages
28 from IPython.core.error import StdinNotImplementedError
28 from IPython.core.error import StdinNotImplementedError
29 from IPython.config.configurable import Configurable
29 from IPython.config.configurable import Configurable
30 from IPython.external.decorator import decorator
30 from IPython.external.decorator import decorator
31 from IPython.testing.skipdoctest import skip_doctest
31 from IPython.testing.skipdoctest import skip_doctest
32 from IPython.utils import io
32 from IPython.utils import io
33 from IPython.utils.path import locate_profile
33 from IPython.utils.path import locate_profile
34 from IPython.utils.traitlets import Bool, Dict, Instance, Integer, List, Unicode
34 from IPython.utils.traitlets import Bool, Dict, Instance, Integer, List, Unicode
35 from IPython.utils.warn import warn
35 from IPython.utils.warn import warn
36
36
37 #-----------------------------------------------------------------------------
37 #-----------------------------------------------------------------------------
38 # Classes and functions
38 # Classes and functions
39 #-----------------------------------------------------------------------------
39 #-----------------------------------------------------------------------------
40
40
41 class DummyDB(object):
41 class DummyDB(object):
42 """Dummy DB that will act as a black hole for history.
42 """Dummy DB that will act as a black hole for history.
43
43
44 Only used in the absence of sqlite"""
44 Only used in the absence of sqlite"""
45 def execute(*args, **kwargs):
45 def execute(*args, **kwargs):
46 return []
46 return []
47
47
48 def commit(self, *args, **kwargs):
48 def commit(self, *args, **kwargs):
49 pass
49 pass
50
50
51 def __enter__(self, *args, **kwargs):
51 def __enter__(self, *args, **kwargs):
52 pass
52 pass
53
53
54 def __exit__(self, *args, **kwargs):
54 def __exit__(self, *args, **kwargs):
55 pass
55 pass
56
56
57
57
58 @decorator
58 @decorator
59 def needs_sqlite(f,*a,**kw):
59 def needs_sqlite(f,*a,**kw):
60 """return an empty list in the absence of sqlite"""
60 """return an empty list in the absence of sqlite"""
61 if sqlite3 is None:
61 if sqlite3 is None:
62 return []
62 return []
63 else:
63 else:
64 return f(*a,**kw)
64 return f(*a,**kw)
65
65
66
66
67 class HistoryAccessor(Configurable):
67 class HistoryAccessor(Configurable):
68 """Access the history database without adding to it.
68 """Access the history database without adding to it.
69
69
70 This is intended for use by standalone history tools. IPython shells use
70 This is intended for use by standalone history tools. IPython shells use
71 HistoryManager, below, which is a subclass of this."""
71 HistoryManager, below, which is a subclass of this."""
72
72
73 # String holding the path to the history file
73 # String holding the path to the history file
74 hist_file = Unicode(config=True,
74 hist_file = Unicode(config=True,
75 help="""Path to file to use for SQLite history database.
75 help="""Path to file to use for SQLite history database.
76
76
77 By default, IPython will put the history database in the IPython profile
77 By default, IPython will put the history database in the IPython profile
78 directory. If you would rather share one history among profiles,
78 directory. If you would rather share one history among profiles,
79 you ca set this value in each, so that they are consistent.
79 you ca set this value in each, so that they are consistent.
80
80
81 Due to an issue with fcntl, SQLite is known to misbehave on some NFS mounts.
81 Due to an issue with fcntl, SQLite is known to misbehave on some NFS mounts.
82 If you see IPython hanging, try setting this to something on a local disk,
82 If you see IPython hanging, try setting this to something on a local disk,
83 e.g::
83 e.g::
84
84
85 ipython --HistoryManager.hist_file=/tmp/ipython_hist.sqlite
85 ipython --HistoryManager.hist_file=/tmp/ipython_hist.sqlite
86
86
87 """)
87 """)
88
88
89 # The SQLite database
89 # The SQLite database
90 if sqlite3:
90 if sqlite3:
91 db = Instance(sqlite3.Connection)
91 db = Instance(sqlite3.Connection)
92 else:
92 else:
93 db = Instance(DummyDB)
93 db = Instance(DummyDB)
94
94
95 def __init__(self, profile='default', hist_file=u'', config=None, **traits):
95 def __init__(self, profile='default', hist_file=u'', config=None, **traits):
96 """Create a new history accessor.
96 """Create a new history accessor.
97
97
98 Parameters
98 Parameters
99 ----------
99 ----------
100 profile : str
100 profile : str
101 The name of the profile from which to open history.
101 The name of the profile from which to open history.
102 hist_file : str
102 hist_file : str
103 Path to an SQLite history database stored by IPython. If specified,
103 Path to an SQLite history database stored by IPython. If specified,
104 hist_file overrides profile.
104 hist_file overrides profile.
105 config :
105 config :
106 Config object. hist_file can also be set through this.
106 Config object. hist_file can also be set through this.
107 """
107 """
108 # We need a pointer back to the shell for various tasks.
108 # We need a pointer back to the shell for various tasks.
109 super(HistoryAccessor, self).__init__(config=config, **traits)
109 super(HistoryAccessor, self).__init__(config=config, **traits)
110 # defer setting hist_file from kwarg until after init,
110 # defer setting hist_file from kwarg until after init,
111 # otherwise the default kwarg value would clobber any value
111 # otherwise the default kwarg value would clobber any value
112 # set by config
112 # set by config
113 if hist_file:
113 if hist_file:
114 self.hist_file = hist_file
114 self.hist_file = hist_file
115
115
116 if self.hist_file == u'':
116 if self.hist_file == u'':
117 # No one has set the hist_file, yet.
117 # No one has set the hist_file, yet.
118 self.hist_file = self._get_hist_file_name(profile)
118 self.hist_file = self._get_hist_file_name(profile)
119
119
120 if sqlite3 is None:
120 if sqlite3 is None:
121 warn("IPython History requires SQLite, your history will not be saved\n")
121 warn("IPython History requires SQLite, your history will not be saved\n")
122 self.db = DummyDB()
122 self.db = DummyDB()
123 return
123 return
124
124
125 try:
125 try:
126 self.init_db()
126 self.init_db()
127 except sqlite3.DatabaseError:
127 except sqlite3.DatabaseError:
128 if os.path.isfile(self.hist_file):
128 if os.path.isfile(self.hist_file):
129 # Try to move the file out of the way
129 # Try to move the file out of the way
130 base,ext = os.path.splitext(self.hist_file)
130 base,ext = os.path.splitext(self.hist_file)
131 newpath = base + '-corrupt' + ext
131 newpath = base + '-corrupt' + ext
132 os.rename(self.hist_file, newpath)
132 os.rename(self.hist_file, newpath)
133 print("ERROR! History file wasn't a valid SQLite database.",
133 print("ERROR! History file wasn't a valid SQLite database.",
134 "It was moved to %s" % newpath, "and a new file created.")
134 "It was moved to %s" % newpath, "and a new file created.")
135 self.init_db()
135 self.init_db()
136 else:
136 else:
137 # The hist_file is probably :memory: or something else.
137 # The hist_file is probably :memory: or something else.
138 raise
138 raise
139
139
140 def _get_hist_file_name(self, profile='default'):
140 def _get_hist_file_name(self, profile='default'):
141 """Find the history file for the given profile name.
141 """Find the history file for the given profile name.
142
142
143 This is overridden by the HistoryManager subclass, to use the shell's
143 This is overridden by the HistoryManager subclass, to use the shell's
144 active profile.
144 active profile.
145
145
146 Parameters
146 Parameters
147 ----------
147 ----------
148 profile : str
148 profile : str
149 The name of a profile which has a history file.
149 The name of a profile which has a history file.
150 """
150 """
151 return os.path.join(locate_profile(profile), 'history.sqlite')
151 return os.path.join(locate_profile(profile), 'history.sqlite')
152
152
153 def init_db(self):
153 def init_db(self):
154 """Connect to the database, and create tables if necessary."""
154 """Connect to the database, and create tables if necessary."""
155 # use detect_types so that timestamps return datetime objects
155 # use detect_types so that timestamps return datetime objects
156 self.db = sqlite3.connect(self.hist_file, detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
156 self.db = sqlite3.connect(self.hist_file, detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
157 self.db.execute("""CREATE TABLE IF NOT EXISTS sessions (session integer
157 self.db.execute("""CREATE TABLE IF NOT EXISTS sessions (session integer
158 primary key autoincrement, start timestamp,
158 primary key autoincrement, start timestamp,
159 end timestamp, num_cmds integer, remark text)""")
159 end timestamp, num_cmds integer, remark text)""")
160 self.db.execute("""CREATE TABLE IF NOT EXISTS history
160 self.db.execute("""CREATE TABLE IF NOT EXISTS history
161 (session integer, line integer, source text, source_raw text,
161 (session integer, line integer, source text, source_raw text,
162 PRIMARY KEY (session, line))""")
162 PRIMARY KEY (session, line))""")
163 # Output history is optional, but ensure the table's there so it can be
163 # Output history is optional, but ensure the table's there so it can be
164 # enabled later.
164 # enabled later.
165 self.db.execute("""CREATE TABLE IF NOT EXISTS output_history
165 self.db.execute("""CREATE TABLE IF NOT EXISTS output_history
166 (session integer, line integer, output text,
166 (session integer, line integer, output text,
167 PRIMARY KEY (session, line))""")
167 PRIMARY KEY (session, line))""")
168 self.db.commit()
168 self.db.commit()
169
169
170 def writeout_cache(self):
170 def writeout_cache(self):
171 """Overridden by HistoryManager to dump the cache before certain
171 """Overridden by HistoryManager to dump the cache before certain
172 database lookups."""
172 database lookups."""
173 pass
173 pass
174
174
175 ## -------------------------------
175 ## -------------------------------
176 ## Methods for retrieving history:
176 ## Methods for retrieving history:
177 ## -------------------------------
177 ## -------------------------------
178 def _run_sql(self, sql, params, raw=True, output=False):
178 def _run_sql(self, sql, params, raw=True, output=False):
179 """Prepares and runs an SQL query for the history database.
179 """Prepares and runs an SQL query for the history database.
180
180
181 Parameters
181 Parameters
182 ----------
182 ----------
183 sql : str
183 sql : str
184 Any filtering expressions to go after SELECT ... FROM ...
184 Any filtering expressions to go after SELECT ... FROM ...
185 params : tuple
185 params : tuple
186 Parameters passed to the SQL query (to replace "?")
186 Parameters passed to the SQL query (to replace "?")
187 raw, output : bool
187 raw, output : bool
188 See :meth:`get_range`
188 See :meth:`get_range`
189
189
190 Returns
190 Returns
191 -------
191 -------
192 Tuples as :meth:`get_range`
192 Tuples as :meth:`get_range`
193 """
193 """
194 toget = 'source_raw' if raw else 'source'
194 toget = 'source_raw' if raw else 'source'
195 sqlfrom = "history"
195 sqlfrom = "history"
196 if output:
196 if output:
197 sqlfrom = "history LEFT JOIN output_history USING (session, line)"
197 sqlfrom = "history LEFT JOIN output_history USING (session, line)"
198 toget = "history.%s, output_history.output" % toget
198 toget = "history.%s, output_history.output" % toget
199 cur = self.db.execute("SELECT session, line, %s FROM %s " %\
199 cur = self.db.execute("SELECT session, line, %s FROM %s " %\
200 (toget, sqlfrom) + sql, params)
200 (toget, sqlfrom) + sql, params)
201 if output: # Regroup into 3-tuples, and parse JSON
201 if output: # Regroup into 3-tuples, and parse JSON
202 return ((ses, lin, (inp, out)) for ses, lin, inp, out in cur)
202 return ((ses, lin, (inp, out)) for ses, lin, inp, out in cur)
203 return cur
203 return cur
204
204
205 @needs_sqlite
205 @needs_sqlite
206 def get_session_info(self, session=0):
206 def get_session_info(self, session=0):
207 """get info about a session
207 """get info about a session
208
208
209 Parameters
209 Parameters
210 ----------
210 ----------
211
211
212 session : int
212 session : int
213 Session number to retrieve. The current session is 0, and negative
213 Session number to retrieve. The current session is 0, and negative
214 numbers count back from current session, so -1 is previous session.
214 numbers count back from current session, so -1 is previous session.
215
215
216 Returns
216 Returns
217 -------
217 -------
218
218
219 (session_id [int], start [datetime], end [datetime], num_cmds [int], remark [unicode])
219 (session_id [int], start [datetime], end [datetime], num_cmds [int], remark [unicode])
220
220
221 Sessions that are running or did not exit cleanly will have `end=None`
221 Sessions that are running or did not exit cleanly will have `end=None`
222 and `num_cmds=None`.
222 and `num_cmds=None`.
223
223
224 """
224 """
225
225
226 if session <= 0:
226 if session <= 0:
227 session += self.session_number
227 session += self.session_number
228
228
229 query = "SELECT * from sessions where session == ?"
229 query = "SELECT * from sessions where session == ?"
230 return self.db.execute(query, (session,)).fetchone()
230 return self.db.execute(query, (session,)).fetchone()
231
231
232 def get_tail(self, n=10, raw=True, output=False, include_latest=False):
232 def get_tail(self, n=10, raw=True, output=False, include_latest=False):
233 """Get the last n lines from the history database.
233 """Get the last n lines from the history database.
234
234
235 Parameters
235 Parameters
236 ----------
236 ----------
237 n : int
237 n : int
238 The number of lines to get
238 The number of lines to get
239 raw, output : bool
239 raw, output : bool
240 See :meth:`get_range`
240 See :meth:`get_range`
241 include_latest : bool
241 include_latest : bool
242 If False (default), n+1 lines are fetched, and the latest one
242 If False (default), n+1 lines are fetched, and the latest one
243 is discarded. This is intended to be used where the function
243 is discarded. This is intended to be used where the function
244 is called by a user command, which it should not return.
244 is called by a user command, which it should not return.
245
245
246 Returns
246 Returns
247 -------
247 -------
248 Tuples as :meth:`get_range`
248 Tuples as :meth:`get_range`
249 """
249 """
250 self.writeout_cache()
250 self.writeout_cache()
251 if not include_latest:
251 if not include_latest:
252 n += 1
252 n += 1
253 cur = self._run_sql("ORDER BY session DESC, line DESC LIMIT ?",
253 cur = self._run_sql("ORDER BY session DESC, line DESC LIMIT ?",
254 (n,), raw=raw, output=output)
254 (n,), raw=raw, output=output)
255 if not include_latest:
255 if not include_latest:
256 return reversed(list(cur)[1:])
256 return reversed(list(cur)[1:])
257 return reversed(list(cur))
257 return reversed(list(cur))
258
258
259 def search(self, pattern="*", raw=True, search_raw=True,
259 def search(self, pattern="*", raw=True, search_raw=True,
260 output=False):
260 output=False):
261 """Search the database using unix glob-style matching (wildcards
261 """Search the database using unix glob-style matching (wildcards
262 * and ?).
262 * and ?).
263
263
264 Parameters
264 Parameters
265 ----------
265 ----------
266 pattern : str
266 pattern : str
267 The wildcarded pattern to match when searching
267 The wildcarded pattern to match when searching
268 search_raw : bool
268 search_raw : bool
269 If True, search the raw input, otherwise, the parsed input
269 If True, search the raw input, otherwise, the parsed input
270 raw, output : bool
270 raw, output : bool
271 See :meth:`get_range`
271 See :meth:`get_range`
272
272
273 Returns
273 Returns
274 -------
274 -------
275 Tuples as :meth:`get_range`
275 Tuples as :meth:`get_range`
276 """
276 """
277 tosearch = "source_raw" if search_raw else "source"
277 tosearch = "source_raw" if search_raw else "source"
278 if output:
278 if output:
279 tosearch = "history." + tosearch
279 tosearch = "history." + tosearch
280 self.writeout_cache()
280 self.writeout_cache()
281 return self._run_sql("WHERE %s GLOB ?" % tosearch, (pattern,),
281 return self._run_sql("WHERE %s GLOB ?" % tosearch, (pattern,),
282 raw=raw, output=output)
282 raw=raw, output=output)
283
283
284 def get_range(self, session, start=1, stop=None, raw=True,output=False):
284 def get_range(self, session, start=1, stop=None, raw=True,output=False):
285 """Retrieve input by session.
285 """Retrieve input by session.
286
286
287 Parameters
287 Parameters
288 ----------
288 ----------
289 session : int
289 session : int
290 Session number to retrieve.
290 Session number to retrieve.
291 start : int
291 start : int
292 First line to retrieve.
292 First line to retrieve.
293 stop : int
293 stop : int
294 End of line range (excluded from output itself). If None, retrieve
294 End of line range (excluded from output itself). If None, retrieve
295 to the end of the session.
295 to the end of the session.
296 raw : bool
296 raw : bool
297 If True, return untranslated input
297 If True, return untranslated input
298 output : bool
298 output : bool
299 If True, attempt to include output. This will be 'real' Python
299 If True, attempt to include output. This will be 'real' Python
300 objects for the current session, or text reprs from previous
300 objects for the current session, or text reprs from previous
301 sessions if db_log_output was enabled at the time. Where no output
301 sessions if db_log_output was enabled at the time. Where no output
302 is found, None is used.
302 is found, None is used.
303
303
304 Returns
304 Returns
305 -------
305 -------
306 An iterator over the desired lines. Each line is a 3-tuple, either
306 An iterator over the desired lines. Each line is a 3-tuple, either
307 (session, line, input) if output is False, or
307 (session, line, input) if output is False, or
308 (session, line, (input, output)) if output is True.
308 (session, line, (input, output)) if output is True.
309 """
309 """
310 if stop:
310 if stop:
311 lineclause = "line >= ? AND line < ?"
311 lineclause = "line >= ? AND line < ?"
312 params = (session, start, stop)
312 params = (session, start, stop)
313 else:
313 else:
314 lineclause = "line>=?"
314 lineclause = "line>=?"
315 params = (session, start)
315 params = (session, start)
316
316
317 return self._run_sql("WHERE session==? AND %s""" % lineclause,
317 return self._run_sql("WHERE session==? AND %s""" % lineclause,
318 params, raw=raw, output=output)
318 params, raw=raw, output=output)
319
319
320 def get_range_by_str(self, rangestr, raw=True, output=False):
320 def get_range_by_str(self, rangestr, raw=True, output=False):
321 """Get lines of history from a string of ranges, as used by magic
321 """Get lines of history from a string of ranges, as used by magic
322 commands %hist, %save, %macro, etc.
322 commands %hist, %save, %macro, etc.
323
323
324 Parameters
324 Parameters
325 ----------
325 ----------
326 rangestr : str
326 rangestr : str
327 A string specifying ranges, e.g. "5 ~2/1-4". See
327 A string specifying ranges, e.g. "5 ~2/1-4". See
328 :func:`magic_history` for full details.
328 :func:`magic_history` for full details.
329 raw, output : bool
329 raw, output : bool
330 As :meth:`get_range`
330 As :meth:`get_range`
331
331
332 Returns
332 Returns
333 -------
333 -------
334 Tuples as :meth:`get_range`
334 Tuples as :meth:`get_range`
335 """
335 """
336 for sess, s, e in extract_hist_ranges(rangestr):
336 for sess, s, e in extract_hist_ranges(rangestr):
337 for line in self.get_range(sess, s, e, raw=raw, output=output):
337 for line in self.get_range(sess, s, e, raw=raw, output=output):
338 yield line
338 yield line
339
339
340
340
341 class HistoryManager(HistoryAccessor):
341 class HistoryManager(HistoryAccessor):
342 """A class to organize all history-related functionality in one place.
342 """A class to organize all history-related functionality in one place.
343 """
343 """
344 # Public interface
344 # Public interface
345
345
346 # An instance of the IPython shell we are attached to
346 # An instance of the IPython shell we are attached to
347 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
347 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
348 # Lists to hold processed and raw history. These start with a blank entry
348 # Lists to hold processed and raw history. These start with a blank entry
349 # so that we can index them starting from 1
349 # so that we can index them starting from 1
350 input_hist_parsed = List([""])
350 input_hist_parsed = List([""])
351 input_hist_raw = List([""])
351 input_hist_raw = List([""])
352 # A list of directories visited during session
352 # A list of directories visited during session
353 dir_hist = List()
353 dir_hist = List()
354 def _dir_hist_default(self):
354 def _dir_hist_default(self):
355 try:
355 try:
356 return [os.getcwdu()]
356 return [os.getcwdu()]
357 except OSError:
357 except OSError:
358 return []
358 return []
359
359
360 # A dict of output history, keyed with ints from the shell's
360 # A dict of output history, keyed with ints from the shell's
361 # execution count.
361 # execution count.
362 output_hist = Dict()
362 output_hist = Dict()
363 # The text/plain repr of outputs.
363 # The text/plain repr of outputs.
364 output_hist_reprs = Dict()
364 output_hist_reprs = Dict()
365
365
366 # The number of the current session in the history database
366 # The number of the current session in the history database
367 session_number = Integer()
367 session_number = Integer()
368 # Should we log output to the database? (default no)
368 # Should we log output to the database? (default no)
369 db_log_output = Bool(False, config=True)
369 db_log_output = Bool(False, config=True)
370 # Write to database every x commands (higher values save disk access & power)
370 # Write to database every x commands (higher values save disk access & power)
371 # Values of 1 or less effectively disable caching.
371 # Values of 1 or less effectively disable caching.
372 db_cache_size = Integer(0, config=True)
372 db_cache_size = Integer(0, config=True)
373 # The input and output caches
373 # The input and output caches
374 db_input_cache = List()
374 db_input_cache = List()
375 db_output_cache = List()
375 db_output_cache = List()
376
376
377 # History saving in separate thread
377 # History saving in separate thread
378 save_thread = Instance('IPython.core.history.HistorySavingThread')
378 save_thread = Instance('IPython.core.history.HistorySavingThread')
379 try: # Event is a function returning an instance of _Event...
379 try: # Event is a function returning an instance of _Event...
380 save_flag = Instance(threading._Event)
380 save_flag = Instance(threading._Event)
381 except AttributeError: # ...until Python 3.3, when it's a class.
381 except AttributeError: # ...until Python 3.3, when it's a class.
382 save_flag = Instance(threading.Event)
382 save_flag = Instance(threading.Event)
383
383
384 # Private interface
384 # Private interface
385 # Variables used to store the three last inputs from the user. On each new
385 # Variables used to store the three last inputs from the user. On each new
386 # history update, we populate the user's namespace with these, shifted as
386 # history update, we populate the user's namespace with these, shifted as
387 # necessary.
387 # necessary.
388 _i00 = Unicode(u'')
388 _i00 = Unicode(u'')
389 _i = Unicode(u'')
389 _i = Unicode(u'')
390 _ii = Unicode(u'')
390 _ii = Unicode(u'')
391 _iii = Unicode(u'')
391 _iii = Unicode(u'')
392
392
393 # A regex matching all forms of the exit command, so that we don't store
393 # A regex matching all forms of the exit command, so that we don't store
394 # them in the history (it's annoying to rewind the first entry and land on
394 # them in the history (it's annoying to rewind the first entry and land on
395 # an exit call).
395 # an exit call).
396 _exit_re = re.compile(r"(exit|quit)(\s*\(.*\))?$")
396 _exit_re = re.compile(r"(exit|quit)(\s*\(.*\))?$")
397
397
398 def __init__(self, shell=None, config=None, **traits):
398 def __init__(self, shell=None, config=None, **traits):
399 """Create a new history manager associated with a shell instance.
399 """Create a new history manager associated with a shell instance.
400 """
400 """
401 # We need a pointer back to the shell for various tasks.
401 # We need a pointer back to the shell for various tasks.
402 super(HistoryManager, self).__init__(shell=shell, config=config,
402 super(HistoryManager, self).__init__(shell=shell, config=config,
403 **traits)
403 **traits)
404 self.save_flag = threading.Event()
404 self.save_flag = threading.Event()
405 self.db_input_cache_lock = threading.Lock()
405 self.db_input_cache_lock = threading.Lock()
406 self.db_output_cache_lock = threading.Lock()
406 self.db_output_cache_lock = threading.Lock()
407 if self.hist_file != ':memory:':
407 if self.hist_file != ':memory:':
408 self.save_thread = HistorySavingThread(self)
408 self.save_thread = HistorySavingThread(self)
409 self.save_thread.start()
409 self.save_thread.start()
410
410
411 self.new_session()
411 self.new_session()
412
412
413 def _get_hist_file_name(self, profile=None):
413 def _get_hist_file_name(self, profile=None):
414 """Get default history file name based on the Shell's profile.
414 """Get default history file name based on the Shell's profile.
415
415
416 The profile parameter is ignored, but must exist for compatibility with
416 The profile parameter is ignored, but must exist for compatibility with
417 the parent class."""
417 the parent class."""
418 profile_dir = self.shell.profile_dir.location
418 profile_dir = self.shell.profile_dir.location
419 return os.path.join(profile_dir, 'history.sqlite')
419 return os.path.join(profile_dir, 'history.sqlite')
420
420
421 @needs_sqlite
421 @needs_sqlite
422 def new_session(self, conn=None):
422 def new_session(self, conn=None):
423 """Get a new session number."""
423 """Get a new session number."""
424 if conn is None:
424 if conn is None:
425 conn = self.db
425 conn = self.db
426
426
427 with conn:
427 with conn:
428 cur = conn.execute("""INSERT INTO sessions VALUES (NULL, ?, NULL,
428 cur = conn.execute("""INSERT INTO sessions VALUES (NULL, ?, NULL,
429 NULL, "") """, (datetime.datetime.now(),))
429 NULL, "") """, (datetime.datetime.now(),))
430 self.session_number = cur.lastrowid
430 self.session_number = cur.lastrowid
431
431
432 def end_session(self):
432 def end_session(self):
433 """Close the database session, filling in the end time and line count."""
433 """Close the database session, filling in the end time and line count."""
434 self.writeout_cache()
434 self.writeout_cache()
435 with self.db:
435 with self.db:
436 self.db.execute("""UPDATE sessions SET end=?, num_cmds=? WHERE
436 self.db.execute("""UPDATE sessions SET end=?, num_cmds=? WHERE
437 session==?""", (datetime.datetime.now(),
437 session==?""", (datetime.datetime.now(),
438 len(self.input_hist_parsed)-1, self.session_number))
438 len(self.input_hist_parsed)-1, self.session_number))
439 self.session_number = 0
439 self.session_number = 0
440
440
441 def name_session(self, name):
441 def name_session(self, name):
442 """Give the current session a name in the history database."""
442 """Give the current session a name in the history database."""
443 with self.db:
443 with self.db:
444 self.db.execute("UPDATE sessions SET remark=? WHERE session==?",
444 self.db.execute("UPDATE sessions SET remark=? WHERE session==?",
445 (name, self.session_number))
445 (name, self.session_number))
446
446
447 def reset(self, new_session=True):
447 def reset(self, new_session=True):
448 """Clear the session history, releasing all object references, and
448 """Clear the session history, releasing all object references, and
449 optionally open a new session."""
449 optionally open a new session."""
450 self.output_hist.clear()
450 self.output_hist.clear()
451 # The directory history can't be completely empty
451 # The directory history can't be completely empty
452 self.dir_hist[:] = [os.getcwdu()]
452 self.dir_hist[:] = [os.getcwdu()]
453
453
454 if new_session:
454 if new_session:
455 if self.session_number:
455 if self.session_number:
456 self.end_session()
456 self.end_session()
457 self.input_hist_parsed[:] = [""]
457 self.input_hist_parsed[:] = [""]
458 self.input_hist_raw[:] = [""]
458 self.input_hist_raw[:] = [""]
459 self.new_session()
459 self.new_session()
460
460
461 # ------------------------------
461 # ------------------------------
462 # Methods for retrieving history
462 # Methods for retrieving history
463 # ------------------------------
463 # ------------------------------
464 def _get_range_session(self, start=1, stop=None, raw=True, output=False):
464 def _get_range_session(self, start=1, stop=None, raw=True, output=False):
465 """Get input and output history from the current session. Called by
465 """Get input and output history from the current session. Called by
466 get_range, and takes similar parameters."""
466 get_range, and takes similar parameters."""
467 input_hist = self.input_hist_raw if raw else self.input_hist_parsed
467 input_hist = self.input_hist_raw if raw else self.input_hist_parsed
468
468
469 n = len(input_hist)
469 n = len(input_hist)
470 if start < 0:
470 if start < 0:
471 start += n
471 start += n
472 if not stop or (stop > n):
472 if not stop or (stop > n):
473 stop = n
473 stop = n
474 elif stop < 0:
474 elif stop < 0:
475 stop += n
475 stop += n
476
476
477 for i in range(start, stop):
477 for i in range(start, stop):
478 if output:
478 if output:
479 line = (input_hist[i], self.output_hist_reprs.get(i))
479 line = (input_hist[i], self.output_hist_reprs.get(i))
480 else:
480 else:
481 line = input_hist[i]
481 line = input_hist[i]
482 yield (0, i, line)
482 yield (0, i, line)
483
483
484 def get_range(self, session=0, start=1, stop=None, raw=True,output=False):
484 def get_range(self, session=0, start=1, stop=None, raw=True,output=False):
485 """Retrieve input by session.
485 """Retrieve input by session.
486
486
487 Parameters
487 Parameters
488 ----------
488 ----------
489 session : int
489 session : int
490 Session number to retrieve. The current session is 0, and negative
490 Session number to retrieve. The current session is 0, and negative
491 numbers count back from current session, so -1 is previous session.
491 numbers count back from current session, so -1 is previous session.
492 start : int
492 start : int
493 First line to retrieve.
493 First line to retrieve.
494 stop : int
494 stop : int
495 End of line range (excluded from output itself). If None, retrieve
495 End of line range (excluded from output itself). If None, retrieve
496 to the end of the session.
496 to the end of the session.
497 raw : bool
497 raw : bool
498 If True, return untranslated input
498 If True, return untranslated input
499 output : bool
499 output : bool
500 If True, attempt to include output. This will be 'real' Python
500 If True, attempt to include output. This will be 'real' Python
501 objects for the current session, or text reprs from previous
501 objects for the current session, or text reprs from previous
502 sessions if db_log_output was enabled at the time. Where no output
502 sessions if db_log_output was enabled at the time. Where no output
503 is found, None is used.
503 is found, None is used.
504
504
505 Returns
505 Returns
506 -------
506 -------
507 An iterator over the desired lines. Each line is a 3-tuple, either
507 An iterator over the desired lines. Each line is a 3-tuple, either
508 (session, line, input) if output is False, or
508 (session, line, input) if output is False, or
509 (session, line, (input, output)) if output is True.
509 (session, line, (input, output)) if output is True.
510 """
510 """
511 if session <= 0:
511 if session <= 0:
512 session += self.session_number
512 session += self.session_number
513 if session==self.session_number: # Current session
513 if session==self.session_number: # Current session
514 return self._get_range_session(start, stop, raw, output)
514 return self._get_range_session(start, stop, raw, output)
515 return super(HistoryManager, self).get_range(session, start, stop, raw, output)
515 return super(HistoryManager, self).get_range(session, start, stop, raw, output)
516
516
517 ## ----------------------------
517 ## ----------------------------
518 ## Methods for storing history:
518 ## Methods for storing history:
519 ## ----------------------------
519 ## ----------------------------
520 def store_inputs(self, line_num, source, source_raw=None):
520 def store_inputs(self, line_num, source, source_raw=None):
521 """Store source and raw input in history and create input cache
521 """Store source and raw input in history and create input cache
522 variables _i*.
522 variables _i*.
523
523
524 Parameters
524 Parameters
525 ----------
525 ----------
526 line_num : int
526 line_num : int
527 The prompt number of this input.
527 The prompt number of this input.
528
528
529 source : str
529 source : str
530 Python input.
530 Python input.
531
531
532 source_raw : str, optional
532 source_raw : str, optional
533 If given, this is the raw input without any IPython transformations
533 If given, this is the raw input without any IPython transformations
534 applied to it. If not given, ``source`` is used.
534 applied to it. If not given, ``source`` is used.
535 """
535 """
536 if source_raw is None:
536 if source_raw is None:
537 source_raw = source
537 source_raw = source
538 source = source.rstrip('\n')
538 source = source.rstrip('\n')
539 source_raw = source_raw.rstrip('\n')
539 source_raw = source_raw.rstrip('\n')
540
540
541 # do not store exit/quit commands
541 # do not store exit/quit commands
542 if self._exit_re.match(source_raw.strip()):
542 if self._exit_re.match(source_raw.strip()):
543 return
543 return
544
544
545 self.input_hist_parsed.append(source)
545 self.input_hist_parsed.append(source)
546 self.input_hist_raw.append(source_raw)
546 self.input_hist_raw.append(source_raw)
547
547
548 with self.db_input_cache_lock:
548 with self.db_input_cache_lock:
549 self.db_input_cache.append((line_num, source, source_raw))
549 self.db_input_cache.append((line_num, source, source_raw))
550 # Trigger to flush cache and write to DB.
550 # Trigger to flush cache and write to DB.
551 if len(self.db_input_cache) >= self.db_cache_size:
551 if len(self.db_input_cache) >= self.db_cache_size:
552 self.save_flag.set()
552 self.save_flag.set()
553
553
554 # update the auto _i variables
554 # update the auto _i variables
555 self._iii = self._ii
555 self._iii = self._ii
556 self._ii = self._i
556 self._ii = self._i
557 self._i = self._i00
557 self._i = self._i00
558 self._i00 = source_raw
558 self._i00 = source_raw
559
559
560 # hackish access to user namespace to create _i1,_i2... dynamically
560 # hackish access to user namespace to create _i1,_i2... dynamically
561 new_i = '_i%s' % line_num
561 new_i = '_i%s' % line_num
562 to_main = {'_i': self._i,
562 to_main = {'_i': self._i,
563 '_ii': self._ii,
563 '_ii': self._ii,
564 '_iii': self._iii,
564 '_iii': self._iii,
565 new_i : self._i00 }
565 new_i : self._i00 }
566
566
567 self.shell.push(to_main, interactive=False)
567 self.shell.push(to_main, interactive=False)
568
568
569 def store_output(self, line_num):
569 def store_output(self, line_num):
570 """If database output logging is enabled, this saves all the
570 """If database output logging is enabled, this saves all the
571 outputs from the indicated prompt number to the database. It's
571 outputs from the indicated prompt number to the database. It's
572 called by run_cell after code has been executed.
572 called by run_cell after code has been executed.
573
573
574 Parameters
574 Parameters
575 ----------
575 ----------
576 line_num : int
576 line_num : int
577 The line number from which to save outputs
577 The line number from which to save outputs
578 """
578 """
579 if (not self.db_log_output) or (line_num not in self.output_hist_reprs):
579 if (not self.db_log_output) or (line_num not in self.output_hist_reprs):
580 return
580 return
581 output = self.output_hist_reprs[line_num]
581 output = self.output_hist_reprs[line_num]
582
582
583 with self.db_output_cache_lock:
583 with self.db_output_cache_lock:
584 self.db_output_cache.append((line_num, output))
584 self.db_output_cache.append((line_num, output))
585 if self.db_cache_size <= 1:
585 if self.db_cache_size <= 1:
586 self.save_flag.set()
586 self.save_flag.set()
587
587
588 def _writeout_input_cache(self, conn):
588 def _writeout_input_cache(self, conn):
589 with conn:
589 with conn:
590 for line in self.db_input_cache:
590 for line in self.db_input_cache:
591 conn.execute("INSERT INTO history VALUES (?, ?, ?, ?)",
591 conn.execute("INSERT INTO history VALUES (?, ?, ?, ?)",
592 (self.session_number,)+line)
592 (self.session_number,)+line)
593
593
594 def _writeout_output_cache(self, conn):
594 def _writeout_output_cache(self, conn):
595 with conn:
595 with conn:
596 for line in self.db_output_cache:
596 for line in self.db_output_cache:
597 conn.execute("INSERT INTO output_history VALUES (?, ?, ?)",
597 conn.execute("INSERT INTO output_history VALUES (?, ?, ?)",
598 (self.session_number,)+line)
598 (self.session_number,)+line)
599
599
600 @needs_sqlite
600 @needs_sqlite
601 def writeout_cache(self, conn=None):
601 def writeout_cache(self, conn=None):
602 """Write any entries in the cache to the database."""
602 """Write any entries in the cache to the database."""
603 if conn is None:
603 if conn is None:
604 conn = self.db
604 conn = self.db
605
605
606 with self.db_input_cache_lock:
606 with self.db_input_cache_lock:
607 try:
607 try:
608 self._writeout_input_cache(conn)
608 self._writeout_input_cache(conn)
609 except sqlite3.IntegrityError:
609 except sqlite3.IntegrityError:
610 self.new_session(conn)
610 self.new_session(conn)
611 print("ERROR! Session/line number was not unique in",
611 print("ERROR! Session/line number was not unique in",
612 "database. History logging moved to new session",
612 "database. History logging moved to new session",
613 self.session_number)
613 self.session_number)
614 try: # Try writing to the new session. If this fails, don't recurse
614 try: # Try writing to the new session. If this fails, don't recurse
615 self._writeout_input_cache(conn)
615 self._writeout_input_cache(conn)
616 except sqlite3.IntegrityError:
616 except sqlite3.IntegrityError:
617 pass
617 pass
618 finally:
618 finally:
619 self.db_input_cache = []
619 self.db_input_cache = []
620
620
621 with self.db_output_cache_lock:
621 with self.db_output_cache_lock:
622 try:
622 try:
623 self._writeout_output_cache(conn)
623 self._writeout_output_cache(conn)
624 except sqlite3.IntegrityError:
624 except sqlite3.IntegrityError:
625 print("!! Session/line number for output was not unique",
625 print("!! Session/line number for output was not unique",
626 "in database. Output will not be stored.")
626 "in database. Output will not be stored.")
627 finally:
627 finally:
628 self.db_output_cache = []
628 self.db_output_cache = []
629
629
630
630
631 class HistorySavingThread(threading.Thread):
631 class HistorySavingThread(threading.Thread):
632 """This thread takes care of writing history to the database, so that
632 """This thread takes care of writing history to the database, so that
633 the UI isn't held up while that happens.
633 the UI isn't held up while that happens.
634
634
635 It waits for the HistoryManager's save_flag to be set, then writes out
635 It waits for the HistoryManager's save_flag to be set, then writes out
636 the history cache. The main thread is responsible for setting the flag when
636 the history cache. The main thread is responsible for setting the flag when
637 the cache size reaches a defined threshold."""
637 the cache size reaches a defined threshold."""
638 daemon = True
638 daemon = True
639 stop_now = False
639 stop_now = False
640 def __init__(self, history_manager):
640 def __init__(self, history_manager):
641 super(HistorySavingThread, self).__init__()
641 super(HistorySavingThread, self).__init__()
642 self.history_manager = history_manager
642 self.history_manager = history_manager
643 atexit.register(self.stop)
643 atexit.register(self.stop)
644
644
645 @needs_sqlite
645 @needs_sqlite
646 def run(self):
646 def run(self):
647 # We need a separate db connection per thread:
647 # We need a separate db connection per thread:
648 try:
648 try:
649 self.db = sqlite3.connect(self.history_manager.hist_file)
649 self.db = sqlite3.connect(self.history_manager.hist_file)
650 while True:
650 while True:
651 self.history_manager.save_flag.wait()
651 self.history_manager.save_flag.wait()
652 if self.stop_now:
652 if self.stop_now:
653 return
653 return
654 self.history_manager.save_flag.clear()
654 self.history_manager.save_flag.clear()
655 self.history_manager.writeout_cache(self.db)
655 self.history_manager.writeout_cache(self.db)
656 except Exception as e:
656 except Exception as e:
657 print(("The history saving thread hit an unexpected error (%s)."
657 print(("The history saving thread hit an unexpected error (%s)."
658 "History will not be written to the database.") % repr(e))
658 "History will not be written to the database.") % repr(e))
659
659
660 def stop(self):
660 def stop(self):
661 """This can be called from the main thread to safely stop this thread.
661 """This can be called from the main thread to safely stop this thread.
662
662
663 Note that it does not attempt to write out remaining history before
663 Note that it does not attempt to write out remaining history before
664 exiting. That should be done by calling the HistoryManager's
664 exiting. That should be done by calling the HistoryManager's
665 end_session method."""
665 end_session method."""
666 self.stop_now = True
666 self.stop_now = True
667 self.history_manager.save_flag.set()
667 self.history_manager.save_flag.set()
668 self.join()
668 self.join()
669
669
670
670
671 # To match, e.g. ~5/8-~2/3
671 # To match, e.g. ~5/8-~2/3
672 range_re = re.compile(r"""
672 range_re = re.compile(r"""
673 ((?P<startsess>~?\d+)/)?
673 ((?P<startsess>~?\d+)/)?
674 (?P<start>\d+) # Only the start line num is compulsory
674 (?P<start>\d+) # Only the start line num is compulsory
675 ((?P<sep>[\-:])
675 ((?P<sep>[\-:])
676 ((?P<endsess>~?\d+)/)?
676 ((?P<endsess>~?\d+)/)?
677 (?P<end>\d+))?
677 (?P<end>\d+))?
678 $""", re.VERBOSE)
678 $""", re.VERBOSE)
679
679
680
680
681 def extract_hist_ranges(ranges_str):
681 def extract_hist_ranges(ranges_str):
682 """Turn a string of history ranges into 3-tuples of (session, start, stop).
682 """Turn a string of history ranges into 3-tuples of (session, start, stop).
683
683
684 Examples
684 Examples
685 --------
685 --------
686 list(extract_input_ranges("~8/5-~7/4 2"))
686 list(extract_input_ranges("~8/5-~7/4 2"))
687 [(-8, 5, None), (-7, 1, 4), (0, 2, 3)]
687 [(-8, 5, None), (-7, 1, 4), (0, 2, 3)]
688 """
688 """
689 for range_str in ranges_str.split():
689 for range_str in ranges_str.split():
690 rmatch = range_re.match(range_str)
690 rmatch = range_re.match(range_str)
691 if not rmatch:
691 if not rmatch:
692 continue
692 continue
693 start = int(rmatch.group("start"))
693 start = int(rmatch.group("start"))
694 end = rmatch.group("end")
694 end = rmatch.group("end")
695 end = int(end) if end else start+1 # If no end specified, get (a, a+1)
695 end = int(end) if end else start+1 # If no end specified, get (a, a+1)
696 if rmatch.group("sep") == "-": # 1-3 == 1:4 --> [1, 2, 3]
696 if rmatch.group("sep") == "-": # 1-3 == 1:4 --> [1, 2, 3]
697 end += 1
697 end += 1
698 startsess = rmatch.group("startsess") or "0"
698 startsess = rmatch.group("startsess") or "0"
699 endsess = rmatch.group("endsess") or startsess
699 endsess = rmatch.group("endsess") or startsess
700 startsess = int(startsess.replace("~","-"))
700 startsess = int(startsess.replace("~","-"))
701 endsess = int(endsess.replace("~","-"))
701 endsess = int(endsess.replace("~","-"))
702 assert endsess >= startsess
702 assert endsess >= startsess
703
703
704 if endsess == startsess:
704 if endsess == startsess:
705 yield (startsess, start, end)
705 yield (startsess, start, end)
706 continue
706 continue
707 # Multiple sessions in one range:
707 # Multiple sessions in one range:
708 yield (startsess, start, None)
708 yield (startsess, start, None)
709 for sess in range(startsess+1, endsess):
709 for sess in range(startsess+1, endsess):
710 yield (sess, 1, None)
710 yield (sess, 1, None)
711 yield (endsess, 1, end)
711 yield (endsess, 1, end)
712
712
713
713
714 def _format_lineno(session, line):
714 def _format_lineno(session, line):
715 """Helper function to format line numbers properly."""
715 """Helper function to format line numbers properly."""
716 if session == 0:
716 if session == 0:
717 return str(line)
717 return str(line)
718 return "%s#%s" % (session, line)
718 return "%s#%s" % (session, line)
719
719
720
720
721 @skip_doctest
721 @skip_doctest
722 def magic_history(self, parameter_s = ''):
722 def magic_history(self, parameter_s = ''):
723 """Print input history (_i<n> variables), with most recent last.
723 """Print input history (_i<n> variables), with most recent last.
724
724
725 %history [-o -p -t -n] [-f filename] [range | -g pattern | -l number]
725 %history [-o -p -t -n] [-f filename] [range | -g pattern | -l number]
726
726
727 By default, input history is printed without line numbers so it can be
727 By default, input history is printed without line numbers so it can be
728 directly pasted into an editor. Use -n to show them.
728 directly pasted into an editor. Use -n to show them.
729
729
730 By default, all input history from the current session is displayed.
730 By default, all input history from the current session is displayed.
731 Ranges of history can be indicated using the syntax:
731 Ranges of history can be indicated using the syntax:
732 4 : Line 4, current session
732 4 : Line 4, current session
733 4-6 : Lines 4-6, current session
733 4-6 : Lines 4-6, current session
734 243/1-5: Lines 1-5, session 243
734 243/1-5: Lines 1-5, session 243
735 ~2/7 : Line 7, session 2 before current
735 ~2/7 : Line 7, session 2 before current
736 ~8/1-~6/5 : From the first line of 8 sessions ago, to the fifth line
736 ~8/1-~6/5 : From the first line of 8 sessions ago, to the fifth line
737 of 6 sessions ago.
737 of 6 sessions ago.
738 Multiple ranges can be entered, separated by spaces
738 Multiple ranges can be entered, separated by spaces
739
739
740 The same syntax is used by %macro, %save, %edit, %rerun
740 The same syntax is used by %macro, %save, %edit, %rerun
741
741
742 Options:
742 Options:
743
743
744 -n: print line numbers for each input.
744 -n: print line numbers for each input.
745 This feature is only available if numbered prompts are in use.
745 This feature is only available if numbered prompts are in use.
746
746
747 -o: also print outputs for each input.
747 -o: also print outputs for each input.
748
748
749 -p: print classic '>>>' python prompts before each input. This is useful
749 -p: print classic '>>>' python prompts before each input. This is useful
750 for making documentation, and in conjunction with -o, for producing
750 for making documentation, and in conjunction with -o, for producing
751 doctest-ready output.
751 doctest-ready output.
752
752
753 -r: (default) print the 'raw' history, i.e. the actual commands you typed.
753 -r: (default) print the 'raw' history, i.e. the actual commands you typed.
754
754
755 -t: print the 'translated' history, as IPython understands it. IPython
755 -t: print the 'translated' history, as IPython understands it. IPython
756 filters your input and converts it all into valid Python source before
756 filters your input and converts it all into valid Python source before
757 executing it (things like magics or aliases are turned into function
757 executing it (things like magics or aliases are turned into function
758 calls, for example). With this option, you'll see the native history
758 calls, for example). With this option, you'll see the native history
759 instead of the user-entered version: '%cd /' will be seen as
759 instead of the user-entered version: '%cd /' will be seen as
760 'get_ipython().magic("%cd /")' instead of '%cd /'.
760 'get_ipython().magic("%cd /")' instead of '%cd /'.
761
761
762 -g: treat the arg as a pattern to grep for in (full) history.
762 -g: treat the arg as a pattern to grep for in (full) history.
763 This includes the saved history (almost all commands ever written).
763 This includes the saved history (almost all commands ever written).
764 Use '%hist -g' to show full saved history (may be very long).
764 Use '%hist -g' to show full saved history (may be very long).
765
765
766 -l: get the last n lines from all sessions. Specify n as a single arg, or
766 -l: get the last n lines from all sessions. Specify n as a single arg, or
767 the default is the last 10 lines.
767 the default is the last 10 lines.
768
768
769 -f FILENAME: instead of printing the output to the screen, redirect it to
769 -f FILENAME: instead of printing the output to the screen, redirect it to
770 the given file. The file is always overwritten, though *when it can*,
770 the given file. The file is always overwritten, though *when it can*,
771 IPython asks for confirmation first. In particular, running the command
771 IPython asks for confirmation first. In particular, running the command
772 "history -f FILENAME" from the IPython Notebook interface will replace
772 "history -f FILENAME" from the IPython Notebook interface will replace
773 FILENAME even if it already exists *without* confirmation.
773 FILENAME even if it already exists *without* confirmation.
774
774
775 Examples
775 Examples
776 --------
776 --------
777 ::
777 ::
778
778
779 In [6]: %hist -n 4-6
779 In [6]: %hist -n 4-6
780 4:a = 12
780 4:a = 12
781 5:print a**2
781 5:print a**2
782 6:%hist -n 4-6
782 6:%hist -n 4-6
783
783
784 """
784 """
785
785
786 if not self.shell.displayhook.do_full_cache:
786 if not self.shell.displayhook.do_full_cache:
787 print('This feature is only available if numbered prompts are in use.')
787 print('This feature is only available if numbered prompts are in use.')
788 return
788 return
789 opts,args = self.parse_options(parameter_s,'noprtglf:',mode='string')
789 opts,args = self.parse_options(parameter_s,'noprtglf:',mode='string')
790
790
791 # For brevity
791 # For brevity
792 history_manager = self.shell.history_manager
792 history_manager = self.shell.history_manager
793
793
794 def _format_lineno(session, line):
794 def _format_lineno(session, line):
795 """Helper function to format line numbers properly."""
795 """Helper function to format line numbers properly."""
796 if session in (0, history_manager.session_number):
796 if session in (0, history_manager.session_number):
797 return str(line)
797 return str(line)
798 return "%s/%s" % (session, line)
798 return "%s/%s" % (session, line)
799
799
800 # Check if output to specific file was requested.
800 # Check if output to specific file was requested.
801 try:
801 try:
802 outfname = opts['f']
802 outfname = opts['f']
803 except KeyError:
803 except KeyError:
804 outfile = io.stdout # default
804 outfile = io.stdout # default
805 # We don't want to close stdout at the end!
805 # We don't want to close stdout at the end!
806 close_at_end = False
806 close_at_end = False
807 else:
807 else:
808 if os.path.exists(outfname):
808 if os.path.exists(outfname):
809 try:
809 try:
810 ans = io.ask_yes_no("File %r exists. Overwrite?" % outfname)
810 ans = io.ask_yes_no("File %r exists. Overwrite?" % outfname)
811 except StdinNotImplementedError:
811 except StdinNotImplementedError:
812 ans = True
812 ans = True
813 if not ans:
813 if not ans:
814 print('Aborting.')
814 print('Aborting.')
815 return
815 return
816 print("Overwriting file.")
816 print("Overwriting file.")
817 outfile = io_open(outfname, 'w', encoding='utf-8')
817 outfile = io_open(outfname, 'w', encoding='utf-8')
818 close_at_end = True
818 close_at_end = True
819
819
820 print_nums = 'n' in opts
820 print_nums = 'n' in opts
821 get_output = 'o' in opts
821 get_output = 'o' in opts
822 pyprompts = 'p' in opts
822 pyprompts = 'p' in opts
823 # Raw history is the default
823 # Raw history is the default
824 raw = not('t' in opts)
824 raw = not('t' in opts)
825
825
826 default_length = 40
826 default_length = 40
827 pattern = None
827 pattern = None
828
828
829 if 'g' in opts: # Glob search
829 if 'g' in opts: # Glob search
830 pattern = "*" + args + "*" if args else "*"
830 pattern = "*" + args + "*" if args else "*"
831 hist = history_manager.search(pattern, raw=raw, output=get_output)
831 hist = history_manager.search(pattern, raw=raw, output=get_output)
832 print_nums = True
832 print_nums = True
833 elif 'l' in opts: # Get 'tail'
833 elif 'l' in opts: # Get 'tail'
834 try:
834 try:
835 n = int(args)
835 n = int(args)
836 except ValueError, IndexError:
836 except ValueError, IndexError:
837 n = 10
837 n = 10
838 hist = history_manager.get_tail(n, raw=raw, output=get_output)
838 hist = history_manager.get_tail(n, raw=raw, output=get_output)
839 else:
839 else:
840 if args: # Get history by ranges
840 if args: # Get history by ranges
841 hist = history_manager.get_range_by_str(args, raw, get_output)
841 hist = history_manager.get_range_by_str(args, raw, get_output)
842 else: # Just get history for the current session
842 else: # Just get history for the current session
843 hist = history_manager.get_range(raw=raw, output=get_output)
843 hist = history_manager.get_range(raw=raw, output=get_output)
844
844
845 # We could be displaying the entire history, so let's not try to pull it
845 # We could be displaying the entire history, so let's not try to pull it
846 # into a list in memory. Anything that needs more space will just misalign.
846 # into a list in memory. Anything that needs more space will just misalign.
847 width = 4
847 width = 4
848
848
849 for session, lineno, inline in hist:
849 for session, lineno, inline in hist:
850 # Print user history with tabs expanded to 4 spaces. The GUI clients
850 # Print user history with tabs expanded to 4 spaces. The GUI clients
851 # use hard tabs for easier usability in auto-indented code, but we want
851 # use hard tabs for easier usability in auto-indented code, but we want
852 # to produce PEP-8 compliant history for safe pasting into an editor.
852 # to produce PEP-8 compliant history for safe pasting into an editor.
853 if get_output:
853 if get_output:
854 inline, output = inline
854 inline, output = inline
855 inline = inline.expandtabs(4).rstrip()
855 inline = inline.expandtabs(4).rstrip()
856
856
857 multiline = "\n" in inline
857 multiline = "\n" in inline
858 line_sep = '\n' if multiline else ' '
858 line_sep = '\n' if multiline else ' '
859 if print_nums:
859 if print_nums:
860 print(u'%s:%s' % (_format_lineno(session, lineno).rjust(width),
860 print(u'%s:%s' % (_format_lineno(session, lineno).rjust(width),
861 line_sep), file=outfile, end=u'')
861 line_sep), file=outfile, end=u'')
862 if pyprompts:
862 if pyprompts:
863 print(u">>> ", end=u"", file=outfile)
863 print(u">>> ", end=u"", file=outfile)
864 if multiline:
864 if multiline:
865 inline = "\n... ".join(inline.splitlines()) + "\n..."
865 inline = "\n... ".join(inline.splitlines()) + "\n..."
866 print(inline, file=outfile)
866 print(inline, file=outfile)
867 if get_output and output:
867 if get_output and output:
868 print(output, file=outfile)
868 print(output, file=outfile)
869
869
870 if close_at_end:
870 if close_at_end:
871 outfile.close()
871 outfile.close()
872
872
873
873
874 def magic_rep(self, arg):
874 def magic_rep(self, arg):
875 r"""Repeat a command, or get command to input line for editing.
875 r"""Repeat a command, or get command to input line for editing.
876
876
877 %recall and %rep are equivalent.
877 %recall and %rep are equivalent.
878
878
879 - %recall (no arguments):
879 - %recall (no arguments):
880
880
881 Place a string version of last computation result (stored in the special '_'
881 Place a string version of last computation result (stored in the special '_'
882 variable) to the next input prompt. Allows you to create elaborate command
882 variable) to the next input prompt. Allows you to create elaborate command
883 lines without using copy-paste::
883 lines without using copy-paste::
884
884
885 In[1]: l = ["hei", "vaan"]
885 In[1]: l = ["hei", "vaan"]
886 In[2]: "".join(l)
886 In[2]: "".join(l)
887 Out[2]: heivaan
887 Out[2]: heivaan
888 In[3]: %rep
888 In[3]: %rep
889 In[4]: heivaan_ <== cursor blinking
889 In[4]: heivaan_ <== cursor blinking
890
890
891 %recall 45
891 %recall 45
892
892
893 Place history line 45 on the next input prompt. Use %hist to find
893 Place history line 45 on the next input prompt. Use %hist to find
894 out the number.
894 out the number.
895
895
896 %recall 1-4
896 %recall 1-4
897
897
898 Combine the specified lines into one cell, and place it on the next
898 Combine the specified lines into one cell, and place it on the next
899 input prompt. See %history for the slice syntax.
899 input prompt. See %history for the slice syntax.
900
900
901 %recall foo+bar
901 %recall foo+bar
902
902
903 If foo+bar can be evaluated in the user namespace, the result is
903 If foo+bar can be evaluated in the user namespace, the result is
904 placed at the next input prompt. Otherwise, the history is searched
904 placed at the next input prompt. Otherwise, the history is searched
905 for lines which contain that substring, and the most recent one is
905 for lines which contain that substring, and the most recent one is
906 placed at the next input prompt.
906 placed at the next input prompt.
907 """
907 """
908 if not arg: # Last output
908 if not arg: # Last output
909 self.shell.set_next_input(str(self.shell.user_ns["_"]))
909 self.shell.set_next_input(str(self.shell.user_ns["_"]))
910 return
910 return
911 # Get history range
911 # Get history range
912 histlines = self.history_manager.get_range_by_str(arg)
912 histlines = self.shell.history_manager.get_range_by_str(arg)
913 cmd = "\n".join(x[2] for x in histlines)
913 cmd = "\n".join(x[2] for x in histlines)
914 if cmd:
914 if cmd:
915 self.shell.set_next_input(cmd.rstrip())
915 self.shell.set_next_input(cmd.rstrip())
916 return
916 return
917
917
918 try: # Variable in user namespace
918 try: # Variable in user namespace
919 cmd = str(eval(arg, self.shell.user_ns))
919 cmd = str(eval(arg, self.shell.user_ns))
920 except Exception: # Search for term in history
920 except Exception: # Search for term in history
921 histlines = self.history_manager.search("*"+arg+"*")
921 histlines = self.shell.history_manager.search("*"+arg+"*")
922 for h in reversed([x[2] for x in histlines]):
922 for h in reversed([x[2] for x in histlines]):
923 if 'rep' in h:
923 if 'rep' in h:
924 continue
924 continue
925 self.shell.set_next_input(h.rstrip())
925 self.shell.set_next_input(h.rstrip())
926 return
926 return
927 else:
927 else:
928 self.shell.set_next_input(cmd.rstrip())
928 self.shell.set_next_input(cmd.rstrip())
929 print("Couldn't evaluate or find in history:", arg)
929 print("Couldn't evaluate or find in history:", arg)
930
930
931
931
932 def magic_rerun(self, parameter_s=''):
932 def magic_rerun(self, parameter_s=''):
933 """Re-run previous input
933 """Re-run previous input
934
934
935 By default, you can specify ranges of input history to be repeated
935 By default, you can specify ranges of input history to be repeated
936 (as with %history). With no arguments, it will repeat the last line.
936 (as with %history). With no arguments, it will repeat the last line.
937
937
938 Options:
938 Options:
939
939
940 -l <n> : Repeat the last n lines of input, not including the
940 -l <n> : Repeat the last n lines of input, not including the
941 current command.
941 current command.
942
942
943 -g foo : Repeat the most recent line which contains foo
943 -g foo : Repeat the most recent line which contains foo
944 """
944 """
945 opts, args = self.parse_options(parameter_s, 'l:g:', mode='string')
945 opts, args = self.parse_options(parameter_s, 'l:g:', mode='string')
946 if "l" in opts: # Last n lines
946 if "l" in opts: # Last n lines
947 n = int(opts['l'])
947 n = int(opts['l'])
948 hist = self.history_manager.get_tail(n)
948 hist = self.shell.history_manager.get_tail(n)
949 elif "g" in opts: # Search
949 elif "g" in opts: # Search
950 p = "*"+opts['g']+"*"
950 p = "*"+opts['g']+"*"
951 hist = list(self.history_manager.search(p))
951 hist = list(self.shell.history_manager.search(p))
952 for l in reversed(hist):
952 for l in reversed(hist):
953 if "rerun" not in l[2]:
953 if "rerun" not in l[2]:
954 hist = [l] # The last match which isn't a %rerun
954 hist = [l] # The last match which isn't a %rerun
955 break
955 break
956 else:
956 else:
957 hist = [] # No matches except %rerun
957 hist = [] # No matches except %rerun
958 elif args: # Specify history ranges
958 elif args: # Specify history ranges
959 hist = self.history_manager.get_range_by_str(args)
959 hist = self.shell.history_manager.get_range_by_str(args)
960 else: # Last line
960 else: # Last line
961 hist = self.history_manager.get_tail(1)
961 hist = self.shell.history_manager.get_tail(1)
962 hist = [x[2] for x in hist]
962 hist = [x[2] for x in hist]
963 if not hist:
963 if not hist:
964 print("No lines in history match specification")
964 print("No lines in history match specification")
965 return
965 return
966 histlines = "\n".join(hist)
966 histlines = "\n".join(hist)
967 print("=== Executing: ===")
967 print("=== Executing: ===")
968 print(histlines)
968 print(histlines)
969 print("=== Output: ===")
969 print("=== Output: ===")
970 self.run_cell("\n".join(hist), store_history=False)
970 self.shell.run_cell("\n".join(hist), store_history=False)
971
971
972
972
973 def init_ipython(ip):
973 def init_ipython(ip):
974 ip.define_magic("rep", magic_rep)
974 ip.define_magic("rep", magic_rep)
975 ip.define_magic("recall", magic_rep)
975 ip.define_magic("recall", magic_rep)
976 ip.define_magic("rerun", magic_rerun)
976 ip.define_magic("rerun", magic_rerun)
977 ip.define_magic("hist", magic_history) # Alternative name
977 ip.define_magic("hist", magic_history) # Alternative name
978 ip.define_magic("history", magic_history)
978 ip.define_magic("history", magic_history)
979
979
980 # XXX - ipy_completers are in quarantine, need to be updated to new apis
980 # XXX - ipy_completers are in quarantine, need to be updated to new apis
981 #import ipy_completers
981 #import ipy_completers
982 #ipy_completers.quick_completer('%hist' ,'-g -t -r -n')
982 #ipy_completers.quick_completer('%hist' ,'-g -t -r -n')
@@ -1,3843 +1,3844 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-2011 The IPython Development Team
8 # Copyright (C) 2008-2011 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__ as builtin_mod
18 import __builtin__ as builtin_mod
19 import __future__
19 import __future__
20 import bdb
20 import bdb
21 import inspect
21 import inspect
22 import io
22 import io
23 import json
23 import json
24 import os
24 import os
25 import sys
25 import sys
26 import re
26 import re
27 import time
27 import time
28 import gc
28 import gc
29 from StringIO import StringIO
29 from StringIO 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 from urllib2 import urlopen
32 from urllib2 import urlopen
33
33
34 # cProfile was added in Python2.5
34 # cProfile was added in Python2.5
35 try:
35 try:
36 import cProfile as profile
36 import cProfile as profile
37 import pstats
37 import pstats
38 except ImportError:
38 except ImportError:
39 # profile isn't bundled by default in Debian for license reasons
39 # profile isn't bundled by default in Debian for license reasons
40 try:
40 try:
41 import profile,pstats
41 import profile,pstats
42 except ImportError:
42 except ImportError:
43 profile = pstats = None
43 profile = pstats = None
44
44
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.error import StdinNotImplementedError
48 from IPython.core.error import StdinNotImplementedError
49 from IPython.core.macro import Macro
49 from IPython.core.macro import Macro
50 from IPython.core import magic_arguments, page
50 from IPython.core import magic_arguments, page
51 from IPython.core.prefilter import ESC_MAGIC
51 from IPython.core.prefilter import ESC_MAGIC
52 from IPython.testing.skipdoctest import skip_doctest
52 from IPython.testing.skipdoctest import skip_doctest
53 from IPython.utils import py3compat
53 from IPython.utils import py3compat
54 from IPython.utils.encoding import DEFAULT_ENCODING
54 from IPython.utils.encoding import DEFAULT_ENCODING
55 from IPython.utils.io import file_read, nlprint
55 from IPython.utils.io import file_read, nlprint
56 from IPython.utils.module_paths import find_mod
56 from IPython.utils.module_paths import find_mod
57 from IPython.utils.path import get_py_filename, unquote_filename
57 from IPython.utils.path import get_py_filename, unquote_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 format_screen
60 from IPython.utils.text import 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 from IPython.config.application import Application
64 from IPython.config.application import Application
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 def needs_local_scope(func):
89 def needs_local_scope(func):
90 """Decorator to mark magic functions which need to local scope to run."""
90 """Decorator to mark magic functions which need to local scope to run."""
91 func.needs_local_scope = True
91 func.needs_local_scope = True
92 return func
92 return func
93
93
94
94
95 # Used for exception handling in magic_edit
95 # Used for exception handling in magic_edit
96 class MacroToEdit(ValueError): pass
96 class MacroToEdit(ValueError): pass
97
97
98 #***************************************************************************
98 #***************************************************************************
99 # Main class implementing Magic functionality
99 # Main class implementing Magic functionality
100
100
101 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
101 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
102 # on construction of the main InteractiveShell object. Something odd is going
102 # on construction of the main InteractiveShell object. Something odd is going
103 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
103 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
104 # eventually this needs to be clarified.
104 # eventually this needs to be clarified.
105 # BG: This is because InteractiveShell inherits from this, but is itself a
105 # BG: This is because InteractiveShell inherits from this, but is itself a
106 # Configurable. This messes up the MRO in some way. The fix is that we need to
106 # Configurable. This messes up the MRO in some way. The fix is that we need to
107 # make Magic a configurable that InteractiveShell does not subclass.
107 # make Magic a configurable that InteractiveShell does not subclass.
108
108
109 class Magic(object):
109 class Magic(object):
110 """Magic functions for InteractiveShell.
110 """Magic functions for InteractiveShell.
111
111
112 Shell functions which can be reached as %function_name. All magic
112 Shell functions which can be reached as %function_name. All magic
113 functions should accept a string, which they can parse for their own
113 functions should accept a string, which they can parse for their own
114 needs. This can make some functions easier to type, eg `%cd ../`
114 needs. This can make some functions easier to type, eg `%cd ../`
115 vs. `%cd("../")`
115 vs. `%cd("../")`
116
116
117 ALL definitions MUST begin with the prefix magic_. The user won't need it
117 ALL definitions MUST begin with the prefix magic_. The user won't need it
118 at the command line, but it is is needed in the definition. """
118 at the command line, but it is is needed in the definition. """
119
119
120 # class globals
120 # class globals
121 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
121 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
122 'Automagic is ON, % prefix NOT needed for magic functions.']
122 'Automagic is ON, % prefix NOT needed for magic functions.']
123
123
124
124
125 configurables = None
125 configurables = None
126
126
127 default_runner = None
127 default_runner = None
128 #......................................................................
128 #......................................................................
129 # some utility functions
129 # some utility functions
130
130
131 def __init__(self, shell):
131 def __init__(self, shell):
132
132
133 self.options_table = {}
133 self.options_table = {}
134 if profile is None:
134 if profile is None:
135 self.magic_prun = self.profile_missing_notice
135 self.magic_prun = self.profile_missing_notice
136 self.shell = shell
136 self.shell = shell
137 if self.configurables is None:
137 if self.configurables is None:
138 self.configurables = []
138 self.configurables = []
139
139
140 # namespace for holding state we may need
140 # namespace for holding state we may need
141 self._magic_state = Bunch()
141 self._magic_state = Bunch()
142
142
143 def profile_missing_notice(self, *args, **kwargs):
143 def profile_missing_notice(self, *args, **kwargs):
144 error("""\
144 error("""\
145 The profile module could not be found. It has been removed from the standard
145 The profile module could not be found. It has been removed from the standard
146 python packages because of its non-free license. To use profiling, install the
146 python packages because of its non-free license. To use profiling, install the
147 python-profiler package from non-free.""")
147 python-profiler package from non-free.""")
148
148
149 def default_option(self,fn,optstr):
149 def default_option(self,fn,optstr):
150 """Make an entry in the options_table for fn, with value optstr"""
150 """Make an entry in the options_table for fn, with value optstr"""
151
151
152 if fn not in self.lsmagic():
152 if fn not in self.lsmagic():
153 error("%s is not a magic function" % fn)
153 error("%s is not a magic function" % fn)
154 self.options_table[fn] = optstr
154 self.options_table[fn] = optstr
155
155
156 def lsmagic(self):
156 def lsmagic(self):
157 """Return a list of currently available magic functions.
157 """Return a list of currently available magic functions.
158
158
159 Gives a list of the bare names after mangling (['ls','cd', ...], not
159 Gives a list of the bare names after mangling (['ls','cd', ...], not
160 ['magic_ls','magic_cd',...]"""
160 ['magic_ls','magic_cd',...]"""
161
161
162 # FIXME. This needs a cleanup, in the way the magics list is built.
162 # FIXME. This needs a cleanup, in the way the magics list is built.
163
163
164 # magics in class definition
164 # magics in class definition
165 class_magic = lambda fn: fn.startswith('magic_') and \
165 class_magic = lambda fn: fn.startswith('magic_') and \
166 callable(Magic.__dict__[fn])
166 callable(Magic.__dict__[fn])
167 # in instance namespace (run-time user additions)
167 # in instance namespace (run-time user additions)
168 inst_magic = lambda fn: fn.startswith('magic_') and \
168 inst_magic = lambda fn: fn.startswith('magic_') and \
169 callable(self.__dict__[fn])
169 callable(self.__dict__[fn])
170 # and bound magics by user (so they can access self):
170 # and bound magics by user (so they can access self):
171 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
171 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
172 callable(self.__class__.__dict__[fn])
172 callable(self.__class__.__dict__[fn])
173 magics = filter(class_magic,Magic.__dict__.keys()) + \
173 magics = filter(class_magic,Magic.__dict__.keys()) + \
174 filter(inst_magic,self.__dict__.keys()) + \
174 filter(inst_magic, self.__dict__.keys()) + \
175 filter(inst_bound_magic,self.__class__.__dict__.keys())
175 filter(inst_bound_magic, self.__class__.__dict__.keys())
176 out = []
176 out = []
177 for fn in set(magics):
177 for fn in set(magics):
178 out.append(fn.replace('magic_','',1))
178 out.append(fn.replace('magic_','',1))
179 out.sort()
179 out.sort()
180 return out
180 return out
181
181
182 def extract_input_lines(self, range_str, raw=False):
182 def extract_input_lines(self, range_str, raw=False):
183 """Return as a string a set of input history slices.
183 """Return as a string a set of input history slices.
184
184
185 Parameters
185 Parameters
186 ----------
186 ----------
187 range_str : string
187 range_str : string
188 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
188 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
189 since this function is for use by magic functions which get their
189 since this function is for use by magic functions which get their
190 arguments as strings. The number before the / is the session
190 arguments as strings. The number before the / is the session
191 number: ~n goes n back from the current session.
191 number: ~n goes n back from the current session.
192
192
193 Optional Parameters:
193 Optional Parameters:
194 - raw(False): by default, the processed input is used. If this is
194 - raw(False): by default, the processed input is used. If this is
195 true, the raw input history is used instead.
195 true, the raw input history is used instead.
196
196
197 Note that slices can be called with two notations:
197 Note that slices can be called with two notations:
198
198
199 N:M -> standard python form, means including items N...(M-1).
199 N:M -> standard python form, means including items N...(M-1).
200
200
201 N-M -> include items N..M (closed endpoint)."""
201 N-M -> include items N..M (closed endpoint)."""
202 lines = self.shell.history_manager.\
202 lines = self.shell.history_manager.\
203 get_range_by_str(range_str, raw=raw)
203 get_range_by_str(range_str, raw=raw)
204 return "\n".join(x for _, _, x in lines)
204 return "\n".join(x for _, _, x in lines)
205
205
206 def arg_err(self,func):
206 def arg_err(self,func):
207 """Print docstring if incorrect arguments were passed"""
207 """Print docstring if incorrect arguments were passed"""
208 print 'Error in arguments:'
208 print 'Error in arguments:'
209 print oinspect.getdoc(func)
209 print oinspect.getdoc(func)
210
210
211 def format_latex(self,strng):
211 def format_latex(self,strng):
212 """Format a string for latex inclusion."""
212 """Format a string for latex inclusion."""
213
213
214 # Characters that need to be escaped for latex:
214 # Characters that need to be escaped for latex:
215 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
215 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
216 # Magic command names as headers:
216 # Magic command names as headers:
217 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
217 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
218 re.MULTILINE)
218 re.MULTILINE)
219 # Magic commands
219 # Magic commands
220 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
220 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
221 re.MULTILINE)
221 re.MULTILINE)
222 # Paragraph continue
222 # Paragraph continue
223 par_re = re.compile(r'\\$',re.MULTILINE)
223 par_re = re.compile(r'\\$',re.MULTILINE)
224
224
225 # The "\n" symbol
225 # The "\n" symbol
226 newline_re = re.compile(r'\\n')
226 newline_re = re.compile(r'\\n')
227
227
228 # Now build the string for output:
228 # Now build the string for output:
229 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
229 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
230 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
230 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
231 strng)
231 strng)
232 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
232 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
233 strng = par_re.sub(r'\\\\',strng)
233 strng = par_re.sub(r'\\\\',strng)
234 strng = escape_re.sub(r'\\\1',strng)
234 strng = escape_re.sub(r'\\\1',strng)
235 strng = newline_re.sub(r'\\textbackslash{}n',strng)
235 strng = newline_re.sub(r'\\textbackslash{}n',strng)
236 return strng
236 return strng
237
237
238 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
238 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
239 """Parse options passed to an argument string.
239 """Parse options passed to an argument string.
240
240
241 The interface is similar to that of getopt(), but it returns back a
241 The interface is similar to that of getopt(), but it returns back a
242 Struct with the options as keys and the stripped argument string still
242 Struct with the options as keys and the stripped argument string still
243 as a string.
243 as a string.
244
244
245 arg_str is quoted as a true sys.argv vector by using shlex.split.
245 arg_str is quoted as a true sys.argv vector by using shlex.split.
246 This allows us to easily expand variables, glob files, quote
246 This allows us to easily expand variables, glob files, quote
247 arguments, etc.
247 arguments, etc.
248
248
249 Options:
249 Options:
250 -mode: default 'string'. If given as 'list', the argument string is
250 -mode: default 'string'. If given as 'list', the argument string is
251 returned as a list (split on whitespace) instead of a string.
251 returned as a list (split on whitespace) instead of a string.
252
252
253 -list_all: put all option values in lists. Normally only options
253 -list_all: put all option values in lists. Normally only options
254 appearing more than once are put in a list.
254 appearing more than once are put in a list.
255
255
256 -posix (True): whether to split the input line in POSIX mode or not,
256 -posix (True): whether to split the input line in POSIX mode or not,
257 as per the conventions outlined in the shlex module from the
257 as per the conventions outlined in the shlex module from the
258 standard library."""
258 standard library."""
259
259
260 # inject default options at the beginning of the input line
260 # inject default options at the beginning of the input line
261 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
261 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
262 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
262 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
263
263
264 mode = kw.get('mode','string')
264 mode = kw.get('mode','string')
265 if mode not in ['string','list']:
265 if mode not in ['string','list']:
266 raise ValueError,'incorrect mode given: %s' % mode
266 raise ValueError,'incorrect mode given: %s' % mode
267 # Get options
267 # Get options
268 list_all = kw.get('list_all',0)
268 list_all = kw.get('list_all',0)
269 posix = kw.get('posix', os.name == 'posix')
269 posix = kw.get('posix', os.name == 'posix')
270 strict = kw.get('strict', True)
270 strict = kw.get('strict', True)
271
271
272 # Check if we have more than one argument to warrant extra processing:
272 # Check if we have more than one argument to warrant extra processing:
273 odict = {} # Dictionary with options
273 odict = {} # Dictionary with options
274 args = arg_str.split()
274 args = arg_str.split()
275 if len(args) >= 1:
275 if len(args) >= 1:
276 # If the list of inputs only has 0 or 1 thing in it, there's no
276 # If the list of inputs only has 0 or 1 thing in it, there's no
277 # need to look for options
277 # need to look for options
278 argv = arg_split(arg_str, posix, strict)
278 argv = arg_split(arg_str, posix, strict)
279 # Do regular option processing
279 # Do regular option processing
280 try:
280 try:
281 opts,args = getopt(argv,opt_str,*long_opts)
281 opts,args = getopt(argv,opt_str,*long_opts)
282 except GetoptError,e:
282 except GetoptError,e:
283 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
283 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
284 " ".join(long_opts)))
284 " ".join(long_opts)))
285 for o,a in opts:
285 for o,a in opts:
286 if o.startswith('--'):
286 if o.startswith('--'):
287 o = o[2:]
287 o = o[2:]
288 else:
288 else:
289 o = o[1:]
289 o = o[1:]
290 try:
290 try:
291 odict[o].append(a)
291 odict[o].append(a)
292 except AttributeError:
292 except AttributeError:
293 odict[o] = [odict[o],a]
293 odict[o] = [odict[o],a]
294 except KeyError:
294 except KeyError:
295 if list_all:
295 if list_all:
296 odict[o] = [a]
296 odict[o] = [a]
297 else:
297 else:
298 odict[o] = a
298 odict[o] = a
299
299
300 # Prepare opts,args for return
300 # Prepare opts,args for return
301 opts = Struct(odict)
301 opts = Struct(odict)
302 if mode == 'string':
302 if mode == 'string':
303 args = ' '.join(args)
303 args = ' '.join(args)
304
304
305 return opts,args
305 return opts,args
306
306
307 #......................................................................
307 #......................................................................
308 # And now the actual magic functions
308 # And now the actual magic functions
309
309
310 # Functions for IPython shell work (vars,funcs, config, etc)
310 # Functions for IPython shell work (vars,funcs, config, etc)
311 def magic_lsmagic(self, parameter_s = ''):
311 def magic_lsmagic(self, parameter_s = ''):
312 """List currently available magic functions."""
312 """List currently available magic functions."""
313 mesc = ESC_MAGIC
313 mesc = ESC_MAGIC
314 print 'Available magic functions:\n'+mesc+\
314 print 'Available magic functions:\n'+mesc+\
315 (' '+mesc).join(self.lsmagic())
315 (' '+mesc).join(self.lsmagic())
316 print '\n' + Magic.auto_status[self.shell.automagic]
316 print '\n' + Magic.auto_status[self.shell.automagic]
317 return None
317 return None
318
318
319 def magic_magic(self, parameter_s = ''):
319 def magic_magic(self, parameter_s = ''):
320 """Print information about the magic function system.
320 """Print information about the magic function system.
321
321
322 Supported formats: -latex, -brief, -rest
322 Supported formats: -latex, -brief, -rest
323 """
323 """
324
324
325 mode = ''
325 mode = ''
326 try:
326 try:
327 if parameter_s.split()[0] == '-latex':
327 if parameter_s.split()[0] == '-latex':
328 mode = 'latex'
328 mode = 'latex'
329 if parameter_s.split()[0] == '-brief':
329 if parameter_s.split()[0] == '-brief':
330 mode = 'brief'
330 mode = 'brief'
331 if parameter_s.split()[0] == '-rest':
331 if parameter_s.split()[0] == '-rest':
332 mode = 'rest'
332 mode = 'rest'
333 rest_docs = []
333 rest_docs = []
334 except:
334 except:
335 pass
335 pass
336
336
337 magic_docs = []
337 magic_docs = []
338 for fname in self.lsmagic():
338 for fname in self.lsmagic():
339 mname = 'magic_' + fname
339 mname = 'magic_' + fname
340 for space in (Magic,self,self.__class__):
340 for space in (Magic, self, self.__class__):
341 try:
341 try:
342 fn = space.__dict__[mname]
342 fn = space.__dict__[mname]
343 except KeyError:
343 except KeyError:
344 pass
344 pass
345 else:
345 else:
346 break
346 break
347 if mode == 'brief':
347 if mode == 'brief':
348 # only first line
348 # only first line
349 if fn.__doc__:
349 if fn.__doc__:
350 fndoc = fn.__doc__.split('\n',1)[0]
350 fndoc = fn.__doc__.split('\n',1)[0]
351 else:
351 else:
352 fndoc = 'No documentation'
352 fndoc = 'No documentation'
353 else:
353 else:
354 if fn.__doc__:
354 if fn.__doc__:
355 fndoc = fn.__doc__.rstrip()
355 fndoc = fn.__doc__.rstrip()
356 else:
356 else:
357 fndoc = 'No documentation'
357 fndoc = 'No documentation'
358
358
359
359
360 if mode == 'rest':
360 if mode == 'rest':
361 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
361 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
362 fname,fndoc))
362 fname,fndoc))
363
363
364 else:
364 else:
365 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
365 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
366 fname,fndoc))
366 fname,fndoc))
367
367
368 magic_docs = ''.join(magic_docs)
368 magic_docs = ''.join(magic_docs)
369
369
370 if mode == 'rest':
370 if mode == 'rest':
371 return "".join(rest_docs)
371 return "".join(rest_docs)
372
372
373 if mode == 'latex':
373 if mode == 'latex':
374 print self.format_latex(magic_docs)
374 print self.format_latex(magic_docs)
375 return
375 return
376 else:
376 else:
377 magic_docs = format_screen(magic_docs)
377 magic_docs = format_screen(magic_docs)
378 if mode == 'brief':
378 if mode == 'brief':
379 return magic_docs
379 return magic_docs
380
380
381 outmsg = """
381 outmsg = """
382 IPython's 'magic' functions
382 IPython's 'magic' functions
383 ===========================
383 ===========================
384
384
385 The magic function system provides a series of functions which allow you to
385 The magic function system provides a series of functions which allow you to
386 control the behavior of IPython itself, plus a lot of system-type
386 control the behavior of IPython itself, plus a lot of system-type
387 features. All these functions are prefixed with a % character, but parameters
387 features. All these functions are prefixed with a % character, but parameters
388 are given without parentheses or quotes.
388 are given without parentheses or quotes.
389
389
390 NOTE: If you have 'automagic' enabled (via the command line option or with the
390 NOTE: If you have 'automagic' enabled (via the command line option or with the
391 %automagic function), you don't need to type in the % explicitly. By default,
391 %automagic function), you don't need to type in the % explicitly. By default,
392 IPython ships with automagic on, so you should only rarely need the % escape.
392 IPython ships with automagic on, so you should only rarely need the % escape.
393
393
394 Example: typing '%cd mydir' (without the quotes) changes you working directory
394 Example: typing '%cd mydir' (without the quotes) changes you working directory
395 to 'mydir', if it exists.
395 to 'mydir', if it exists.
396
396
397 For a list of the available magic functions, use %lsmagic. For a description
397 For a list of the available magic functions, use %lsmagic. For a description
398 of any of them, type %magic_name?, e.g. '%cd?'.
398 of any of them, type %magic_name?, e.g. '%cd?'.
399
399
400 Currently the magic system has the following functions:\n"""
400 Currently the magic system has the following functions:\n"""
401
401
402 mesc = ESC_MAGIC
402 mesc = ESC_MAGIC
403 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
403 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
404 "\n\n%s%s\n\n%s" % (outmsg,
404 "\n\n%s%s\n\n%s" % (outmsg,
405 magic_docs,mesc,mesc,
405 magic_docs,mesc,mesc,
406 (' '+mesc).join(self.lsmagic()),
406 (' '+mesc).join(self.lsmagic()),
407 Magic.auto_status[self.shell.automagic] ) )
407 Magic.auto_status[self.shell.automagic] ) )
408 page.page(outmsg)
408 page.page(outmsg)
409
409
410 def magic_automagic(self, parameter_s = ''):
410 def magic_automagic(self, parameter_s = ''):
411 """Make magic functions callable without having to type the initial %.
411 """Make magic functions callable without having to type the initial %.
412
412
413 Without argumentsl toggles on/off (when off, you must call it as
413 Without argumentsl toggles on/off (when off, you must call it as
414 %automagic, of course). With arguments it sets the value, and you can
414 %automagic, of course). With arguments it sets the value, and you can
415 use any of (case insensitive):
415 use any of (case insensitive):
416
416
417 - on,1,True: to activate
417 - on,1,True: to activate
418
418
419 - off,0,False: to deactivate.
419 - off,0,False: to deactivate.
420
420
421 Note that magic functions have lowest priority, so if there's a
421 Note that magic functions have lowest priority, so if there's a
422 variable whose name collides with that of a magic fn, automagic won't
422 variable whose name collides with that of a magic fn, automagic won't
423 work for that function (you get the variable instead). However, if you
423 work for that function (you get the variable instead). However, if you
424 delete the variable (del var), the previously shadowed magic function
424 delete the variable (del var), the previously shadowed magic function
425 becomes visible to automagic again."""
425 becomes visible to automagic again."""
426
426
427 arg = parameter_s.lower()
427 arg = parameter_s.lower()
428 if parameter_s in ('on','1','true'):
428 if parameter_s in ('on','1','true'):
429 self.shell.automagic = True
429 self.shell.automagic = True
430 elif parameter_s in ('off','0','false'):
430 elif parameter_s in ('off','0','false'):
431 self.shell.automagic = False
431 self.shell.automagic = False
432 else:
432 else:
433 self.shell.automagic = not self.shell.automagic
433 self.shell.automagic = not self.shell.automagic
434 print '\n' + Magic.auto_status[self.shell.automagic]
434 print '\n' + Magic.auto_status[self.shell.automagic]
435
435
436 @skip_doctest
436 @skip_doctest
437 def magic_autocall(self, parameter_s = ''):
437 def magic_autocall(self, parameter_s = ''):
438 """Make functions callable without having to type parentheses.
438 """Make functions callable without having to type parentheses.
439
439
440 Usage:
440 Usage:
441
441
442 %autocall [mode]
442 %autocall [mode]
443
443
444 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
444 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
445 value is toggled on and off (remembering the previous state).
445 value is toggled on and off (remembering the previous state).
446
446
447 In more detail, these values mean:
447 In more detail, these values mean:
448
448
449 0 -> fully disabled
449 0 -> fully disabled
450
450
451 1 -> active, but do not apply if there are no arguments on the line.
451 1 -> active, but do not apply if there are no arguments on the line.
452
452
453 In this mode, you get::
453 In this mode, you get::
454
454
455 In [1]: callable
455 In [1]: callable
456 Out[1]: <built-in function callable>
456 Out[1]: <built-in function callable>
457
457
458 In [2]: callable 'hello'
458 In [2]: callable 'hello'
459 ------> callable('hello')
459 ------> callable('hello')
460 Out[2]: False
460 Out[2]: False
461
461
462 2 -> Active always. Even if no arguments are present, the callable
462 2 -> Active always. Even if no arguments are present, the callable
463 object is called::
463 object is called::
464
464
465 In [2]: float
465 In [2]: float
466 ------> float()
466 ------> float()
467 Out[2]: 0.0
467 Out[2]: 0.0
468
468
469 Note that even with autocall off, you can still use '/' at the start of
469 Note that even with autocall off, you can still use '/' at the start of
470 a line to treat the first argument on the command line as a function
470 a line to treat the first argument on the command line as a function
471 and add parentheses to it::
471 and add parentheses to it::
472
472
473 In [8]: /str 43
473 In [8]: /str 43
474 ------> str(43)
474 ------> str(43)
475 Out[8]: '43'
475 Out[8]: '43'
476
476
477 # all-random (note for auto-testing)
477 # all-random (note for auto-testing)
478 """
478 """
479
479
480 if parameter_s:
480 if parameter_s:
481 arg = int(parameter_s)
481 arg = int(parameter_s)
482 else:
482 else:
483 arg = 'toggle'
483 arg = 'toggle'
484
484
485 if not arg in (0,1,2,'toggle'):
485 if not arg in (0,1,2,'toggle'):
486 error('Valid modes: (0->Off, 1->Smart, 2->Full')
486 error('Valid modes: (0->Off, 1->Smart, 2->Full')
487 return
487 return
488
488
489 if arg in (0,1,2):
489 if arg in (0,1,2):
490 self.shell.autocall = arg
490 self.shell.autocall = arg
491 else: # toggle
491 else: # toggle
492 if self.shell.autocall:
492 if self.shell.autocall:
493 self._magic_state.autocall_save = self.shell.autocall
493 self._magic_state.autocall_save = self.shell.autocall
494 self.shell.autocall = 0
494 self.shell.autocall = 0
495 else:
495 else:
496 try:
496 try:
497 self.shell.autocall = self._magic_state.autocall_save
497 self.shell.autocall = self._magic_state.autocall_save
498 except AttributeError:
498 except AttributeError:
499 self.shell.autocall = self._magic_state.autocall_save = 1
499 self.shell.autocall = self._magic_state.autocall_save = 1
500
500
501 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
501 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
502
502
503
503
504 def magic_page(self, parameter_s=''):
504 def magic_page(self, parameter_s=''):
505 """Pretty print the object and display it through a pager.
505 """Pretty print the object and display it through a pager.
506
506
507 %page [options] OBJECT
507 %page [options] OBJECT
508
508
509 If no object is given, use _ (last output).
509 If no object is given, use _ (last output).
510
510
511 Options:
511 Options:
512
512
513 -r: page str(object), don't pretty-print it."""
513 -r: page str(object), don't pretty-print it."""
514
514
515 # After a function contributed by Olivier Aubert, slightly modified.
515 # After a function contributed by Olivier Aubert, slightly modified.
516
516
517 # Process options/args
517 # Process options/args
518 opts,args = self.parse_options(parameter_s,'r')
518 opts,args = self.parse_options(parameter_s,'r')
519 raw = 'r' in opts
519 raw = 'r' in opts
520
520
521 oname = args and args or '_'
521 oname = args and args or '_'
522 info = self._ofind(oname)
522 info = self._ofind(oname)
523 if info['found']:
523 if info['found']:
524 txt = (raw and str or pformat)( info['obj'] )
524 txt = (raw and str or pformat)( info['obj'] )
525 page.page(txt)
525 page.page(txt)
526 else:
526 else:
527 print 'Object `%s` not found' % oname
527 print 'Object `%s` not found' % oname
528
528
529 def magic_profile(self, parameter_s=''):
529 def magic_profile(self, parameter_s=''):
530 """Print your currently active IPython profile."""
530 """Print your currently active IPython profile."""
531 from IPython.core.application import BaseIPythonApplication
531 from IPython.core.application import BaseIPythonApplication
532 if BaseIPythonApplication.initialized():
532 if BaseIPythonApplication.initialized():
533 print BaseIPythonApplication.instance().profile
533 print BaseIPythonApplication.instance().profile
534 else:
534 else:
535 error("profile is an application-level value, but you don't appear to be in an IPython application")
535 error("profile is an application-level value, but you don't appear to be in an IPython application")
536
536
537 def magic_pinfo(self, parameter_s='', namespaces=None):
537 def magic_pinfo(self, parameter_s='', namespaces=None):
538 """Provide detailed information about an object.
538 """Provide detailed information about an object.
539
539
540 '%pinfo object' is just a synonym for object? or ?object."""
540 '%pinfo object' is just a synonym for object? or ?object."""
541
541
542 #print 'pinfo par: <%s>' % parameter_s # dbg
542 #print 'pinfo par: <%s>' % parameter_s # dbg
543
543
544
544
545 # detail_level: 0 -> obj? , 1 -> obj??
545 # detail_level: 0 -> obj? , 1 -> obj??
546 detail_level = 0
546 detail_level = 0
547 # We need to detect if we got called as 'pinfo pinfo foo', which can
547 # We need to detect if we got called as 'pinfo pinfo foo', which can
548 # happen if the user types 'pinfo foo?' at the cmd line.
548 # happen if the user types 'pinfo foo?' at the cmd line.
549 pinfo,qmark1,oname,qmark2 = \
549 pinfo,qmark1,oname,qmark2 = \
550 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
550 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
551 if pinfo or qmark1 or qmark2:
551 if pinfo or qmark1 or qmark2:
552 detail_level = 1
552 detail_level = 1
553 if "*" in oname:
553 if "*" in oname:
554 self.magic_psearch(oname)
554 self.magic_psearch(oname)
555 else:
555 else:
556 self.shell._inspect('pinfo', oname, detail_level=detail_level,
556 self.shell._inspect('pinfo', oname, detail_level=detail_level,
557 namespaces=namespaces)
557 namespaces=namespaces)
558
558
559 def magic_pinfo2(self, parameter_s='', namespaces=None):
559 def magic_pinfo2(self, parameter_s='', namespaces=None):
560 """Provide extra detailed information about an object.
560 """Provide extra detailed information about an object.
561
561
562 '%pinfo2 object' is just a synonym for object?? or ??object."""
562 '%pinfo2 object' is just a synonym for object?? or ??object."""
563 self.shell._inspect('pinfo', parameter_s, detail_level=1,
563 self.shell._inspect('pinfo', parameter_s, detail_level=1,
564 namespaces=namespaces)
564 namespaces=namespaces)
565
565
566 @skip_doctest
566 @skip_doctest
567 def magic_pdef(self, parameter_s='', namespaces=None):
567 def magic_pdef(self, parameter_s='', namespaces=None):
568 """Print the definition header for any callable object.
568 """Print the definition header for any callable object.
569
569
570 If the object is a class, print the constructor information.
570 If the object is a class, print the constructor information.
571
571
572 Examples
572 Examples
573 --------
573 --------
574 ::
574 ::
575
575
576 In [3]: %pdef urllib.urlopen
576 In [3]: %pdef urllib.urlopen
577 urllib.urlopen(url, data=None, proxies=None)
577 urllib.urlopen(url, data=None, proxies=None)
578 """
578 """
579 self._inspect('pdef',parameter_s, namespaces)
579 self._inspect('pdef',parameter_s, namespaces)
580
580
581 def magic_pdoc(self, parameter_s='', namespaces=None):
581 def magic_pdoc(self, parameter_s='', namespaces=None):
582 """Print the docstring for an object.
582 """Print the docstring for an object.
583
583
584 If the given object is a class, it will print both the class and the
584 If the given object is a class, it will print both the class and the
585 constructor docstrings."""
585 constructor docstrings."""
586 self._inspect('pdoc',parameter_s, namespaces)
586 self._inspect('pdoc',parameter_s, namespaces)
587
587
588 def magic_psource(self, parameter_s='', namespaces=None):
588 def magic_psource(self, parameter_s='', namespaces=None):
589 """Print (or run through pager) the source code for an object."""
589 """Print (or run through pager) the source code for an object."""
590 self._inspect('psource',parameter_s, namespaces)
590 self._inspect('psource',parameter_s, namespaces)
591
591
592 def magic_pfile(self, parameter_s=''):
592 def magic_pfile(self, parameter_s=''):
593 """Print (or run through pager) the file where an object is defined.
593 """Print (or run through pager) the file where an object is defined.
594
594
595 The file opens at the line where the object definition begins. IPython
595 The file opens at the line where the object definition begins. IPython
596 will honor the environment variable PAGER if set, and otherwise will
596 will honor the environment variable PAGER if set, and otherwise will
597 do its best to print the file in a convenient form.
597 do its best to print the file in a convenient form.
598
598
599 If the given argument is not an object currently defined, IPython will
599 If the given argument is not an object currently defined, IPython will
600 try to interpret it as a filename (automatically adding a .py extension
600 try to interpret it as a filename (automatically adding a .py extension
601 if needed). You can thus use %pfile as a syntax highlighting code
601 if needed). You can thus use %pfile as a syntax highlighting code
602 viewer."""
602 viewer."""
603
603
604 # first interpret argument as an object name
604 # first interpret argument as an object name
605 out = self._inspect('pfile',parameter_s)
605 out = self._inspect('pfile',parameter_s)
606 # if not, try the input as a filename
606 # if not, try the input as a filename
607 if out == 'not found':
607 if out == 'not found':
608 try:
608 try:
609 filename = get_py_filename(parameter_s)
609 filename = get_py_filename(parameter_s)
610 except IOError,msg:
610 except IOError,msg:
611 print msg
611 print msg
612 return
612 return
613 page.page(self.shell.inspector.format(open(filename).read()))
613 page.page(self.shell.inspector.format(open(filename).read()))
614
614
615 def magic_psearch(self, parameter_s=''):
615 def magic_psearch(self, parameter_s=''):
616 """Search for object in namespaces by wildcard.
616 """Search for object in namespaces by wildcard.
617
617
618 %psearch [options] PATTERN [OBJECT TYPE]
618 %psearch [options] PATTERN [OBJECT TYPE]
619
619
620 Note: ? can be used as a synonym for %psearch, at the beginning or at
620 Note: ? can be used as a synonym for %psearch, at the beginning or at
621 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
621 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
622 rest of the command line must be unchanged (options come first), so
622 rest of the command line must be unchanged (options come first), so
623 for example the following forms are equivalent
623 for example the following forms are equivalent
624
624
625 %psearch -i a* function
625 %psearch -i a* function
626 -i a* function?
626 -i a* function?
627 ?-i a* function
627 ?-i a* function
628
628
629 Arguments:
629 Arguments:
630
630
631 PATTERN
631 PATTERN
632
632
633 where PATTERN is a string containing * as a wildcard similar to its
633 where PATTERN is a string containing * as a wildcard similar to its
634 use in a shell. The pattern is matched in all namespaces on the
634 use in a shell. The pattern is matched in all namespaces on the
635 search path. By default objects starting with a single _ are not
635 search path. By default objects starting with a single _ are not
636 matched, many IPython generated objects have a single
636 matched, many IPython generated objects have a single
637 underscore. The default is case insensitive matching. Matching is
637 underscore. The default is case insensitive matching. Matching is
638 also done on the attributes of objects and not only on the objects
638 also done on the attributes of objects and not only on the objects
639 in a module.
639 in a module.
640
640
641 [OBJECT TYPE]
641 [OBJECT TYPE]
642
642
643 Is the name of a python type from the types module. The name is
643 Is the name of a python type from the types module. The name is
644 given in lowercase without the ending type, ex. StringType is
644 given in lowercase without the ending type, ex. StringType is
645 written string. By adding a type here only objects matching the
645 written string. By adding a type here only objects matching the
646 given type are matched. Using all here makes the pattern match all
646 given type are matched. Using all here makes the pattern match all
647 types (this is the default).
647 types (this is the default).
648
648
649 Options:
649 Options:
650
650
651 -a: makes the pattern match even objects whose names start with a
651 -a: makes the pattern match even objects whose names start with a
652 single underscore. These names are normally omitted from the
652 single underscore. These names are normally omitted from the
653 search.
653 search.
654
654
655 -i/-c: make the pattern case insensitive/sensitive. If neither of
655 -i/-c: make the pattern case insensitive/sensitive. If neither of
656 these options are given, the default is read from your configuration
656 these options are given, the default is read from your configuration
657 file, with the option ``InteractiveShell.wildcards_case_sensitive``.
657 file, with the option ``InteractiveShell.wildcards_case_sensitive``.
658 If this option is not specified in your configuration file, IPython's
658 If this option is not specified in your configuration file, IPython's
659 internal default is to do a case sensitive search.
659 internal default is to do a case sensitive search.
660
660
661 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
661 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
662 specify can be searched in any of the following namespaces:
662 specify can be searched in any of the following namespaces:
663 'builtin', 'user', 'user_global','internal', 'alias', where
663 'builtin', 'user', 'user_global','internal', 'alias', where
664 'builtin' and 'user' are the search defaults. Note that you should
664 'builtin' and 'user' are the search defaults. Note that you should
665 not use quotes when specifying namespaces.
665 not use quotes when specifying namespaces.
666
666
667 'Builtin' contains the python module builtin, 'user' contains all
667 'Builtin' contains the python module builtin, 'user' contains all
668 user data, 'alias' only contain the shell aliases and no python
668 user data, 'alias' only contain the shell aliases and no python
669 objects, 'internal' contains objects used by IPython. The
669 objects, 'internal' contains objects used by IPython. The
670 'user_global' namespace is only used by embedded IPython instances,
670 'user_global' namespace is only used by embedded IPython instances,
671 and it contains module-level globals. You can add namespaces to the
671 and it contains module-level globals. You can add namespaces to the
672 search with -s or exclude them with -e (these options can be given
672 search with -s or exclude them with -e (these options can be given
673 more than once).
673 more than once).
674
674
675 Examples
675 Examples
676 --------
676 --------
677 ::
677 ::
678
678
679 %psearch a* -> objects beginning with an a
679 %psearch a* -> objects beginning with an a
680 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
680 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
681 %psearch a* function -> all functions beginning with an a
681 %psearch a* function -> all functions beginning with an a
682 %psearch re.e* -> objects beginning with an e in module re
682 %psearch re.e* -> objects beginning with an e in module re
683 %psearch r*.e* -> objects that start with e in modules starting in r
683 %psearch r*.e* -> objects that start with e in modules starting in r
684 %psearch r*.* string -> all strings in modules beginning with r
684 %psearch r*.* string -> all strings in modules beginning with r
685
685
686 Case sensitive search::
686 Case sensitive search::
687
687
688 %psearch -c a* list all object beginning with lower case a
688 %psearch -c a* list all object beginning with lower case a
689
689
690 Show objects beginning with a single _::
690 Show objects beginning with a single _::
691
691
692 %psearch -a _* list objects beginning with a single underscore"""
692 %psearch -a _* list objects beginning with a single underscore"""
693 try:
693 try:
694 parameter_s.encode('ascii')
694 parameter_s.encode('ascii')
695 except UnicodeEncodeError:
695 except UnicodeEncodeError:
696 print 'Python identifiers can only contain ascii characters.'
696 print 'Python identifiers can only contain ascii characters.'
697 return
697 return
698
698
699 # default namespaces to be searched
699 # default namespaces to be searched
700 def_search = ['user_local', 'user_global', 'builtin']
700 def_search = ['user_local', 'user_global', 'builtin']
701
701
702 # Process options/args
702 # Process options/args
703 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
703 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
704 opt = opts.get
704 opt = opts.get
705 shell = self.shell
705 shell = self.shell
706 psearch = shell.inspector.psearch
706 psearch = shell.inspector.psearch
707
707
708 # select case options
708 # select case options
709 if opts.has_key('i'):
709 if opts.has_key('i'):
710 ignore_case = True
710 ignore_case = True
711 elif opts.has_key('c'):
711 elif opts.has_key('c'):
712 ignore_case = False
712 ignore_case = False
713 else:
713 else:
714 ignore_case = not shell.wildcards_case_sensitive
714 ignore_case = not shell.wildcards_case_sensitive
715
715
716 # Build list of namespaces to search from user options
716 # Build list of namespaces to search from user options
717 def_search.extend(opt('s',[]))
717 def_search.extend(opt('s',[]))
718 ns_exclude = ns_exclude=opt('e',[])
718 ns_exclude = ns_exclude=opt('e',[])
719 ns_search = [nm for nm in def_search if nm not in ns_exclude]
719 ns_search = [nm for nm in def_search if nm not in ns_exclude]
720
720
721 # Call the actual search
721 # Call the actual search
722 try:
722 try:
723 psearch(args,shell.ns_table,ns_search,
723 psearch(args,shell.ns_table,ns_search,
724 show_all=opt('a'),ignore_case=ignore_case)
724 show_all=opt('a'),ignore_case=ignore_case)
725 except:
725 except:
726 shell.showtraceback()
726 shell.showtraceback()
727
727
728 @skip_doctest
728 @skip_doctest
729 def magic_who_ls(self, parameter_s=''):
729 def magic_who_ls(self, parameter_s=''):
730 """Return a sorted list of all interactive variables.
730 """Return a sorted list of all interactive variables.
731
731
732 If arguments are given, only variables of types matching these
732 If arguments are given, only variables of types matching these
733 arguments are returned.
733 arguments are returned.
734
734
735 Examples
735 Examples
736 --------
736 --------
737
737
738 Define two variables and list them with who_ls::
738 Define two variables and list them with who_ls::
739
739
740 In [1]: alpha = 123
740 In [1]: alpha = 123
741
741
742 In [2]: beta = 'test'
742 In [2]: beta = 'test'
743
743
744 In [3]: %who_ls
744 In [3]: %who_ls
745 Out[3]: ['alpha', 'beta']
745 Out[3]: ['alpha', 'beta']
746
746
747 In [4]: %who_ls int
747 In [4]: %who_ls int
748 Out[4]: ['alpha']
748 Out[4]: ['alpha']
749
749
750 In [5]: %who_ls str
750 In [5]: %who_ls str
751 Out[5]: ['beta']
751 Out[5]: ['beta']
752 """
752 """
753
753
754 user_ns = self.shell.user_ns
754 user_ns = self.shell.user_ns
755 user_ns_hidden = self.shell.user_ns_hidden
755 user_ns_hidden = self.shell.user_ns_hidden
756 out = [ i for i in user_ns
756 out = [ i for i in user_ns
757 if not i.startswith('_') \
757 if not i.startswith('_') \
758 and not i in user_ns_hidden ]
758 and not i in user_ns_hidden ]
759
759
760 typelist = parameter_s.split()
760 typelist = parameter_s.split()
761 if typelist:
761 if typelist:
762 typeset = set(typelist)
762 typeset = set(typelist)
763 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
763 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
764
764
765 out.sort()
765 out.sort()
766 return out
766 return out
767
767
768 @skip_doctest
768 @skip_doctest
769 def magic_who(self, parameter_s=''):
769 def magic_who(self, parameter_s=''):
770 """Print all interactive variables, with some minimal formatting.
770 """Print all interactive variables, with some minimal formatting.
771
771
772 If any arguments are given, only variables whose type matches one of
772 If any arguments are given, only variables whose type matches one of
773 these are printed. For example::
773 these are printed. For example::
774
774
775 %who function str
775 %who function str
776
776
777 will only list functions and strings, excluding all other types of
777 will only list functions and strings, excluding all other types of
778 variables. To find the proper type names, simply use type(var) at a
778 variables. To find the proper type names, simply use type(var) at a
779 command line to see how python prints type names. For example:
779 command line to see how python prints type names. For example:
780
780
781 ::
781 ::
782
782
783 In [1]: type('hello')\\
783 In [1]: type('hello')\\
784 Out[1]: <type 'str'>
784 Out[1]: <type 'str'>
785
785
786 indicates that the type name for strings is 'str'.
786 indicates that the type name for strings is 'str'.
787
787
788 ``%who`` always excludes executed names loaded through your configuration
788 ``%who`` always excludes executed names loaded through your configuration
789 file and things which are internal to IPython.
789 file and things which are internal to IPython.
790
790
791 This is deliberate, as typically you may load many modules and the
791 This is deliberate, as typically you may load many modules and the
792 purpose of %who is to show you only what you've manually defined.
792 purpose of %who is to show you only what you've manually defined.
793
793
794 Examples
794 Examples
795 --------
795 --------
796
796
797 Define two variables and list them with who::
797 Define two variables and list them with who::
798
798
799 In [1]: alpha = 123
799 In [1]: alpha = 123
800
800
801 In [2]: beta = 'test'
801 In [2]: beta = 'test'
802
802
803 In [3]: %who
803 In [3]: %who
804 alpha beta
804 alpha beta
805
805
806 In [4]: %who int
806 In [4]: %who int
807 alpha
807 alpha
808
808
809 In [5]: %who str
809 In [5]: %who str
810 beta
810 beta
811 """
811 """
812
812
813 varlist = self.magic_who_ls(parameter_s)
813 varlist = self.magic_who_ls(parameter_s)
814 if not varlist:
814 if not varlist:
815 if parameter_s:
815 if parameter_s:
816 print 'No variables match your requested type.'
816 print 'No variables match your requested type.'
817 else:
817 else:
818 print 'Interactive namespace is empty.'
818 print 'Interactive namespace is empty.'
819 return
819 return
820
820
821 # if we have variables, move on...
821 # if we have variables, move on...
822 count = 0
822 count = 0
823 for i in varlist:
823 for i in varlist:
824 print i+'\t',
824 print i+'\t',
825 count += 1
825 count += 1
826 if count > 8:
826 if count > 8:
827 count = 0
827 count = 0
828 print
828 print
829 print
829 print
830
830
831 @skip_doctest
831 @skip_doctest
832 def magic_whos(self, parameter_s=''):
832 def magic_whos(self, parameter_s=''):
833 """Like %who, but gives some extra information about each variable.
833 """Like %who, but gives some extra information about each variable.
834
834
835 The same type filtering of %who can be applied here.
835 The same type filtering of %who can be applied here.
836
836
837 For all variables, the type is printed. Additionally it prints:
837 For all variables, the type is printed. Additionally it prints:
838
838
839 - For {},[],(): their length.
839 - For {},[],(): their length.
840
840
841 - For numpy arrays, a summary with shape, number of
841 - For numpy arrays, a summary with shape, number of
842 elements, typecode and size in memory.
842 elements, typecode and size in memory.
843
843
844 - Everything else: a string representation, snipping their middle if
844 - Everything else: a string representation, snipping their middle if
845 too long.
845 too long.
846
846
847 Examples
847 Examples
848 --------
848 --------
849
849
850 Define two variables and list them with whos::
850 Define two variables and list them with whos::
851
851
852 In [1]: alpha = 123
852 In [1]: alpha = 123
853
853
854 In [2]: beta = 'test'
854 In [2]: beta = 'test'
855
855
856 In [3]: %whos
856 In [3]: %whos
857 Variable Type Data/Info
857 Variable Type Data/Info
858 --------------------------------
858 --------------------------------
859 alpha int 123
859 alpha int 123
860 beta str test
860 beta str test
861 """
861 """
862
862
863 varnames = self.magic_who_ls(parameter_s)
863 varnames = self.magic_who_ls(parameter_s)
864 if not varnames:
864 if not varnames:
865 if parameter_s:
865 if parameter_s:
866 print 'No variables match your requested type.'
866 print 'No variables match your requested type.'
867 else:
867 else:
868 print 'Interactive namespace is empty.'
868 print 'Interactive namespace is empty.'
869 return
869 return
870
870
871 # if we have variables, move on...
871 # if we have variables, move on...
872
872
873 # for these types, show len() instead of data:
873 # for these types, show len() instead of data:
874 seq_types = ['dict', 'list', 'tuple']
874 seq_types = ['dict', 'list', 'tuple']
875
875
876 # for numpy arrays, display summary info
876 # for numpy arrays, display summary info
877 ndarray_type = None
877 ndarray_type = None
878 if 'numpy' in sys.modules:
878 if 'numpy' in sys.modules:
879 try:
879 try:
880 from numpy import ndarray
880 from numpy import ndarray
881 except ImportError:
881 except ImportError:
882 pass
882 pass
883 else:
883 else:
884 ndarray_type = ndarray.__name__
884 ndarray_type = ndarray.__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 = "{0:<{varwidth}}{1:<{typewidth}}"
914 vformat = "{0:<{varwidth}}{1:<{typewidth}}"
915 aformat = "%s: %s elems, type `%s`, %s bytes"
915 aformat = "%s: %s elems, type `%s`, %s bytes"
916 # find the size of the columns to format the output nicely
916 # find the size of the columns to format the output nicely
917 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
917 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
918 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
918 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
919 # table header
919 # table header
920 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
920 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
921 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
921 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
922 # and the table itself
922 # and the table itself
923 kb = 1024
923 kb = 1024
924 Mb = 1048576 # kb**2
924 Mb = 1048576 # kb**2
925 for vname,var,vtype in zip(varnames,varlist,typelist):
925 for vname,var,vtype in zip(varnames,varlist,typelist):
926 print vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth),
926 print vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth),
927 if vtype in seq_types:
927 if vtype in seq_types:
928 print "n="+str(len(var))
928 print "n="+str(len(var))
929 elif vtype == ndarray_type:
929 elif vtype == ndarray_type:
930 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
930 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
931 if vtype==ndarray_type:
931 if vtype==ndarray_type:
932 # numpy
932 # numpy
933 vsize = var.size
933 vsize = var.size
934 vbytes = vsize*var.itemsize
934 vbytes = vsize*var.itemsize
935 vdtype = var.dtype
935 vdtype = var.dtype
936
936
937 if vbytes < 100000:
937 if vbytes < 100000:
938 print aformat % (vshape,vsize,vdtype,vbytes)
938 print aformat % (vshape,vsize,vdtype,vbytes)
939 else:
939 else:
940 print aformat % (vshape,vsize,vdtype,vbytes),
940 print aformat % (vshape,vsize,vdtype,vbytes),
941 if vbytes < Mb:
941 if vbytes < Mb:
942 print '(%s kb)' % (vbytes/kb,)
942 print '(%s kb)' % (vbytes/kb,)
943 else:
943 else:
944 print '(%s Mb)' % (vbytes/Mb,)
944 print '(%s Mb)' % (vbytes/Mb,)
945 else:
945 else:
946 try:
946 try:
947 vstr = str(var)
947 vstr = str(var)
948 except UnicodeEncodeError:
948 except UnicodeEncodeError:
949 vstr = unicode(var).encode(DEFAULT_ENCODING,
949 vstr = unicode(var).encode(DEFAULT_ENCODING,
950 'backslashreplace')
950 'backslashreplace')
951 except:
951 except:
952 vstr = "<object with id %d (str() failed)>" % id(var)
952 vstr = "<object with id %d (str() failed)>" % id(var)
953 vstr = vstr.replace('\n','\\n')
953 vstr = vstr.replace('\n','\\n')
954 if len(vstr) < 50:
954 if len(vstr) < 50:
955 print vstr
955 print vstr
956 else:
956 else:
957 print vstr[:25] + "<...>" + vstr[-25:]
957 print vstr[:25] + "<...>" + vstr[-25:]
958
958
959 def magic_reset(self, parameter_s=''):
959 def magic_reset(self, parameter_s=''):
960 """Resets the namespace by removing all names defined by the user, if
960 """Resets the namespace by removing all names defined by the user, if
961 called without arguments, or by removing some types of objects, such
961 called without arguments, or by removing some types of objects, such
962 as everything currently in IPython's In[] and Out[] containers (see
962 as everything currently in IPython's In[] and Out[] containers (see
963 the parameters for details).
963 the parameters for details).
964
964
965 Parameters
965 Parameters
966 ----------
966 ----------
967 -f : force reset without asking for confirmation.
967 -f : force reset without asking for confirmation.
968
968
969 -s : 'Soft' reset: Only clears your namespace, leaving history intact.
969 -s : 'Soft' reset: Only clears your namespace, leaving history intact.
970 References to objects may be kept. By default (without this option),
970 References to objects may be kept. By default (without this option),
971 we do a 'hard' reset, giving you a new session and removing all
971 we do a 'hard' reset, giving you a new session and removing all
972 references to objects from the current session.
972 references to objects from the current session.
973
973
974 in : reset input history
974 in : reset input history
975
975
976 out : reset output history
976 out : reset output history
977
977
978 dhist : reset directory history
978 dhist : reset directory history
979
979
980 array : reset only variables that are NumPy arrays
980 array : reset only variables that are NumPy arrays
981
981
982 See Also
982 See Also
983 --------
983 --------
984 magic_reset_selective : invoked as ``%reset_selective``
984 magic_reset_selective : invoked as ``%reset_selective``
985
985
986 Examples
986 Examples
987 --------
987 --------
988 ::
988 ::
989
989
990 In [6]: a = 1
990 In [6]: a = 1
991
991
992 In [7]: a
992 In [7]: a
993 Out[7]: 1
993 Out[7]: 1
994
994
995 In [8]: 'a' in _ip.user_ns
995 In [8]: 'a' in _ip.user_ns
996 Out[8]: True
996 Out[8]: True
997
997
998 In [9]: %reset -f
998 In [9]: %reset -f
999
999
1000 In [1]: 'a' in _ip.user_ns
1000 In [1]: 'a' in _ip.user_ns
1001 Out[1]: False
1001 Out[1]: False
1002
1002
1003 In [2]: %reset -f in
1003 In [2]: %reset -f in
1004 Flushing input history
1004 Flushing input history
1005
1005
1006 In [3]: %reset -f dhist in
1006 In [3]: %reset -f dhist in
1007 Flushing directory history
1007 Flushing directory history
1008 Flushing input history
1008 Flushing input history
1009
1009
1010 Notes
1010 Notes
1011 -----
1011 -----
1012 Calling this magic from clients that do not implement standard input,
1012 Calling this magic from clients that do not implement standard input,
1013 such as the ipython notebook interface, will reset the namespace
1013 such as the ipython notebook interface, will reset the namespace
1014 without confirmation.
1014 without confirmation.
1015 """
1015 """
1016 opts, args = self.parse_options(parameter_s,'sf', mode='list')
1016 opts, args = self.parse_options(parameter_s,'sf', mode='list')
1017 if 'f' in opts:
1017 if 'f' in opts:
1018 ans = True
1018 ans = True
1019 else:
1019 else:
1020 try:
1020 try:
1021 ans = self.shell.ask_yes_no(
1021 ans = self.shell.ask_yes_no(
1022 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ", default='n')
1022 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ", default='n')
1023 except StdinNotImplementedError:
1023 except StdinNotImplementedError:
1024 ans = True
1024 ans = True
1025 if not ans:
1025 if not ans:
1026 print 'Nothing done.'
1026 print 'Nothing done.'
1027 return
1027 return
1028
1028
1029 if 's' in opts: # Soft reset
1029 if 's' in opts: # Soft reset
1030 user_ns = self.shell.user_ns
1030 user_ns = self.shell.user_ns
1031 for i in self.magic_who_ls():
1031 for i in self.magic_who_ls():
1032 del(user_ns[i])
1032 del(user_ns[i])
1033 elif len(args) == 0: # Hard reset
1033 elif len(args) == 0: # Hard reset
1034 self.shell.reset(new_session = False)
1034 self.shell.reset(new_session = False)
1035
1035
1036 # reset in/out/dhist/array: previously extensinions/clearcmd.py
1036 # reset in/out/dhist/array: previously extensinions/clearcmd.py
1037 ip = self.shell
1037 ip = self.shell
1038 user_ns = self.user_ns # local lookup, heavily used
1038 user_ns = self.shell.user_ns # local lookup, heavily used
1039
1039
1040 for target in args:
1040 for target in args:
1041 target = target.lower() # make matches case insensitive
1041 target = target.lower() # make matches case insensitive
1042 if target == 'out':
1042 if target == 'out':
1043 print "Flushing output cache (%d entries)" % len(user_ns['_oh'])
1043 print "Flushing output cache (%d entries)" % len(user_ns['_oh'])
1044 self.displayhook.flush()
1044 self.shell.displayhook.flush()
1045
1045
1046 elif target == 'in':
1046 elif target == 'in':
1047 print "Flushing input history"
1047 print "Flushing input history"
1048 pc = self.displayhook.prompt_count + 1
1048 pc = self.shell.displayhook.prompt_count + 1
1049 for n in range(1, pc):
1049 for n in range(1, pc):
1050 key = '_i'+repr(n)
1050 key = '_i'+repr(n)
1051 user_ns.pop(key,None)
1051 user_ns.pop(key,None)
1052 user_ns.update(dict(_i=u'',_ii=u'',_iii=u''))
1052 user_ns.update(dict(_i=u'',_ii=u'',_iii=u''))
1053 hm = ip.history_manager
1053 hm = ip.history_manager
1054 # don't delete these, as %save and %macro depending on the length
1054 # don't delete these, as %save and %macro depending on the length
1055 # of these lists to be preserved
1055 # of these lists to be preserved
1056 hm.input_hist_parsed[:] = [''] * pc
1056 hm.input_hist_parsed[:] = [''] * pc
1057 hm.input_hist_raw[:] = [''] * pc
1057 hm.input_hist_raw[:] = [''] * pc
1058 # hm has internal machinery for _i,_ii,_iii, clear it out
1058 # hm has internal machinery for _i,_ii,_iii, clear it out
1059 hm._i = hm._ii = hm._iii = hm._i00 = u''
1059 hm._i = hm._ii = hm._iii = hm._i00 = u''
1060
1060
1061 elif target == 'array':
1061 elif target == 'array':
1062 # Support cleaning up numpy arrays
1062 # Support cleaning up numpy arrays
1063 try:
1063 try:
1064 from numpy import ndarray
1064 from numpy import ndarray
1065 # This must be done with items and not iteritems because we're
1065 # This must be done with items and not iteritems because we're
1066 # going to modify the dict in-place.
1066 # going to modify the dict in-place.
1067 for x,val in user_ns.items():
1067 for x,val in user_ns.items():
1068 if isinstance(val,ndarray):
1068 if isinstance(val,ndarray):
1069 del user_ns[x]
1069 del user_ns[x]
1070 except ImportError:
1070 except ImportError:
1071 print "reset array only works if Numpy is available."
1071 print "reset array only works if Numpy is available."
1072
1072
1073 elif target == 'dhist':
1073 elif target == 'dhist':
1074 print "Flushing directory history"
1074 print "Flushing directory history"
1075 del user_ns['_dh'][:]
1075 del user_ns['_dh'][:]
1076
1076
1077 else:
1077 else:
1078 print "Don't know how to reset ",
1078 print "Don't know how to reset ",
1079 print target + ", please run `%reset?` for details"
1079 print target + ", please run `%reset?` for details"
1080
1080
1081 gc.collect()
1081 gc.collect()
1082
1082
1083 def magic_reset_selective(self, parameter_s=''):
1083 def magic_reset_selective(self, parameter_s=''):
1084 """Resets the namespace by removing names defined by the user.
1084 """Resets the namespace by removing names defined by the user.
1085
1085
1086 Input/Output history are left around in case you need them.
1086 Input/Output history are left around in case you need them.
1087
1087
1088 %reset_selective [-f] regex
1088 %reset_selective [-f] regex
1089
1089
1090 No action is taken if regex is not included
1090 No action is taken if regex is not included
1091
1091
1092 Options
1092 Options
1093 -f : force reset without asking for confirmation.
1093 -f : force reset without asking for confirmation.
1094
1094
1095 See Also
1095 See Also
1096 --------
1096 --------
1097 magic_reset : invoked as ``%reset``
1097 magic_reset : invoked as ``%reset``
1098
1098
1099 Examples
1099 Examples
1100 --------
1100 --------
1101
1101
1102 We first fully reset the namespace so your output looks identical to
1102 We first fully reset the namespace so your output looks identical to
1103 this example for pedagogical reasons; in practice you do not need a
1103 this example for pedagogical reasons; in practice you do not need a
1104 full reset::
1104 full reset::
1105
1105
1106 In [1]: %reset -f
1106 In [1]: %reset -f
1107
1107
1108 Now, with a clean namespace we can make a few variables and use
1108 Now, with a clean namespace we can make a few variables and use
1109 ``%reset_selective`` to only delete names that match our regexp::
1109 ``%reset_selective`` to only delete names that match our regexp::
1110
1110
1111 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1111 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1112
1112
1113 In [3]: who_ls
1113 In [3]: who_ls
1114 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1114 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1115
1115
1116 In [4]: %reset_selective -f b[2-3]m
1116 In [4]: %reset_selective -f b[2-3]m
1117
1117
1118 In [5]: who_ls
1118 In [5]: who_ls
1119 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1119 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1120
1120
1121 In [6]: %reset_selective -f d
1121 In [6]: %reset_selective -f d
1122
1122
1123 In [7]: who_ls
1123 In [7]: who_ls
1124 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1124 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1125
1125
1126 In [8]: %reset_selective -f c
1126 In [8]: %reset_selective -f c
1127
1127
1128 In [9]: who_ls
1128 In [9]: who_ls
1129 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1129 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1130
1130
1131 In [10]: %reset_selective -f b
1131 In [10]: %reset_selective -f b
1132
1132
1133 In [11]: who_ls
1133 In [11]: who_ls
1134 Out[11]: ['a']
1134 Out[11]: ['a']
1135
1135
1136 Notes
1136 Notes
1137 -----
1137 -----
1138 Calling this magic from clients that do not implement standard input,
1138 Calling this magic from clients that do not implement standard input,
1139 such as the ipython notebook interface, will reset the namespace
1139 such as the ipython notebook interface, will reset the namespace
1140 without confirmation.
1140 without confirmation.
1141 """
1141 """
1142
1142
1143 opts, regex = self.parse_options(parameter_s,'f')
1143 opts, regex = self.parse_options(parameter_s,'f')
1144
1144
1145 if opts.has_key('f'):
1145 if opts.has_key('f'):
1146 ans = True
1146 ans = True
1147 else:
1147 else:
1148 try:
1148 try:
1149 ans = self.shell.ask_yes_no(
1149 ans = self.shell.ask_yes_no(
1150 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
1150 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
1151 default='n')
1151 default='n')
1152 except StdinNotImplementedError:
1152 except StdinNotImplementedError:
1153 ans = True
1153 ans = True
1154 if not ans:
1154 if not ans:
1155 print 'Nothing done.'
1155 print 'Nothing done.'
1156 return
1156 return
1157 user_ns = self.shell.user_ns
1157 user_ns = self.shell.user_ns
1158 if not regex:
1158 if not regex:
1159 print 'No regex pattern specified. Nothing done.'
1159 print 'No regex pattern specified. Nothing done.'
1160 return
1160 return
1161 else:
1161 else:
1162 try:
1162 try:
1163 m = re.compile(regex)
1163 m = re.compile(regex)
1164 except TypeError:
1164 except TypeError:
1165 raise TypeError('regex must be a string or compiled pattern')
1165 raise TypeError('regex must be a string or compiled pattern')
1166 for i in self.magic_who_ls():
1166 for i in self.magic_who_ls():
1167 if m.search(i):
1167 if m.search(i):
1168 del(user_ns[i])
1168 del(user_ns[i])
1169
1169
1170 def magic_xdel(self, parameter_s=''):
1170 def magic_xdel(self, parameter_s=''):
1171 """Delete a variable, trying to clear it from anywhere that
1171 """Delete a variable, trying to clear it from anywhere that
1172 IPython's machinery has references to it. By default, this uses
1172 IPython's machinery has references to it. By default, this uses
1173 the identity of the named object in the user namespace to remove
1173 the identity of the named object in the user namespace to remove
1174 references held under other names. The object is also removed
1174 references held under other names. The object is also removed
1175 from the output history.
1175 from the output history.
1176
1176
1177 Options
1177 Options
1178 -n : Delete the specified name from all namespaces, without
1178 -n : Delete the specified name from all namespaces, without
1179 checking their identity.
1179 checking their identity.
1180 """
1180 """
1181 opts, varname = self.parse_options(parameter_s,'n')
1181 opts, varname = self.parse_options(parameter_s,'n')
1182 try:
1182 try:
1183 self.shell.del_var(varname, ('n' in opts))
1183 self.shell.del_var(varname, ('n' in opts))
1184 except (NameError, ValueError) as e:
1184 except (NameError, ValueError) as e:
1185 print type(e).__name__ +": "+ str(e)
1185 print type(e).__name__ +": "+ str(e)
1186
1186
1187 def magic_logstart(self,parameter_s=''):
1187 def magic_logstart(self,parameter_s=''):
1188 """Start logging anywhere in a session.
1188 """Start logging anywhere in a session.
1189
1189
1190 %logstart [-o|-r|-t] [log_name [log_mode]]
1190 %logstart [-o|-r|-t] [log_name [log_mode]]
1191
1191
1192 If no name is given, it defaults to a file named 'ipython_log.py' in your
1192 If no name is given, it defaults to a file named 'ipython_log.py' in your
1193 current directory, in 'rotate' mode (see below).
1193 current directory, in 'rotate' mode (see below).
1194
1194
1195 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1195 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1196 history up to that point and then continues logging.
1196 history up to that point and then continues logging.
1197
1197
1198 %logstart takes a second optional parameter: logging mode. This can be one
1198 %logstart takes a second optional parameter: logging mode. This can be one
1199 of (note that the modes are given unquoted):\\
1199 of (note that the modes are given unquoted):\\
1200 append: well, that says it.\\
1200 append: well, that says it.\\
1201 backup: rename (if exists) to name~ and start name.\\
1201 backup: rename (if exists) to name~ and start name.\\
1202 global: single logfile in your home dir, appended to.\\
1202 global: single logfile in your home dir, appended to.\\
1203 over : overwrite existing log.\\
1203 over : overwrite existing log.\\
1204 rotate: create rotating logs name.1~, name.2~, etc.
1204 rotate: create rotating logs name.1~, name.2~, etc.
1205
1205
1206 Options:
1206 Options:
1207
1207
1208 -o: log also IPython's output. In this mode, all commands which
1208 -o: log also IPython's output. In this mode, all commands which
1209 generate an Out[NN] prompt are recorded to the logfile, right after
1209 generate an Out[NN] prompt are recorded to the logfile, right after
1210 their corresponding input line. The output lines are always
1210 their corresponding input line. The output lines are always
1211 prepended with a '#[Out]# ' marker, so that the log remains valid
1211 prepended with a '#[Out]# ' marker, so that the log remains valid
1212 Python code.
1212 Python code.
1213
1213
1214 Since this marker is always the same, filtering only the output from
1214 Since this marker is always the same, filtering only the output from
1215 a log is very easy, using for example a simple awk call::
1215 a log is very easy, using for example a simple awk call::
1216
1216
1217 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1217 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1218
1218
1219 -r: log 'raw' input. Normally, IPython's logs contain the processed
1219 -r: log 'raw' input. Normally, IPython's logs contain the processed
1220 input, so that user lines are logged in their final form, converted
1220 input, so that user lines are logged in their final form, converted
1221 into valid Python. For example, %Exit is logged as
1221 into valid Python. For example, %Exit is logged as
1222 _ip.magic("Exit"). If the -r flag is given, all input is logged
1222 _ip.magic("Exit"). If the -r flag is given, all input is logged
1223 exactly as typed, with no transformations applied.
1223 exactly as typed, with no transformations applied.
1224
1224
1225 -t: put timestamps before each input line logged (these are put in
1225 -t: put timestamps before each input line logged (these are put in
1226 comments)."""
1226 comments)."""
1227
1227
1228 opts,par = self.parse_options(parameter_s,'ort')
1228 opts,par = self.parse_options(parameter_s,'ort')
1229 log_output = 'o' in opts
1229 log_output = 'o' in opts
1230 log_raw_input = 'r' in opts
1230 log_raw_input = 'r' in opts
1231 timestamp = 't' in opts
1231 timestamp = 't' in opts
1232
1232
1233 logger = self.shell.logger
1233 logger = self.shell.logger
1234
1234
1235 # if no args are given, the defaults set in the logger constructor by
1235 # if no args are given, the defaults set in the logger constructor by
1236 # ipython remain valid
1236 # ipython remain valid
1237 if par:
1237 if par:
1238 try:
1238 try:
1239 logfname,logmode = par.split()
1239 logfname,logmode = par.split()
1240 except:
1240 except:
1241 logfname = par
1241 logfname = par
1242 logmode = 'backup'
1242 logmode = 'backup'
1243 else:
1243 else:
1244 logfname = logger.logfname
1244 logfname = logger.logfname
1245 logmode = logger.logmode
1245 logmode = logger.logmode
1246 # put logfname into rc struct as if it had been called on the command
1246 # put logfname into rc struct as if it had been called on the command
1247 # line, so it ends up saved in the log header Save it in case we need
1247 # line, so it ends up saved in the log header Save it in case we need
1248 # to restore it...
1248 # to restore it...
1249 old_logfile = self.shell.logfile
1249 old_logfile = self.shell.logfile
1250 if logfname:
1250 if logfname:
1251 logfname = os.path.expanduser(logfname)
1251 logfname = os.path.expanduser(logfname)
1252 self.shell.logfile = logfname
1252 self.shell.logfile = logfname
1253
1253
1254 loghead = '# IPython log file\n\n'
1254 loghead = '# IPython log file\n\n'
1255 try:
1255 try:
1256 started = logger.logstart(logfname,loghead,logmode,
1256 started = logger.logstart(logfname,loghead,logmode,
1257 log_output,timestamp,log_raw_input)
1257 log_output,timestamp,log_raw_input)
1258 except:
1258 except:
1259 self.shell.logfile = old_logfile
1259 self.shell.logfile = old_logfile
1260 warn("Couldn't start log: %s" % sys.exc_info()[1])
1260 warn("Couldn't start log: %s" % sys.exc_info()[1])
1261 else:
1261 else:
1262 # log input history up to this point, optionally interleaving
1262 # log input history up to this point, optionally interleaving
1263 # output if requested
1263 # output if requested
1264
1264
1265 if timestamp:
1265 if timestamp:
1266 # disable timestamping for the previous history, since we've
1266 # disable timestamping for the previous history, since we've
1267 # lost those already (no time machine here).
1267 # lost those already (no time machine here).
1268 logger.timestamp = False
1268 logger.timestamp = False
1269
1269
1270 if log_raw_input:
1270 if log_raw_input:
1271 input_hist = self.shell.history_manager.input_hist_raw
1271 input_hist = self.shell.history_manager.input_hist_raw
1272 else:
1272 else:
1273 input_hist = self.shell.history_manager.input_hist_parsed
1273 input_hist = self.shell.history_manager.input_hist_parsed
1274
1274
1275 if log_output:
1275 if log_output:
1276 log_write = logger.log_write
1276 log_write = logger.log_write
1277 output_hist = self.shell.history_manager.output_hist
1277 output_hist = self.shell.history_manager.output_hist
1278 for n in range(1,len(input_hist)-1):
1278 for n in range(1,len(input_hist)-1):
1279 log_write(input_hist[n].rstrip() + '\n')
1279 log_write(input_hist[n].rstrip() + '\n')
1280 if n in output_hist:
1280 if n in output_hist:
1281 log_write(repr(output_hist[n]),'output')
1281 log_write(repr(output_hist[n]),'output')
1282 else:
1282 else:
1283 logger.log_write('\n'.join(input_hist[1:]))
1283 logger.log_write('\n'.join(input_hist[1:]))
1284 logger.log_write('\n')
1284 logger.log_write('\n')
1285 if timestamp:
1285 if timestamp:
1286 # re-enable timestamping
1286 # re-enable timestamping
1287 logger.timestamp = True
1287 logger.timestamp = True
1288
1288
1289 print ('Activating auto-logging. '
1289 print ('Activating auto-logging. '
1290 'Current session state plus future input saved.')
1290 'Current session state plus future input saved.')
1291 logger.logstate()
1291 logger.logstate()
1292
1292
1293 def magic_logstop(self,parameter_s=''):
1293 def magic_logstop(self,parameter_s=''):
1294 """Fully stop logging and close log file.
1294 """Fully stop logging and close log file.
1295
1295
1296 In order to start logging again, a new %logstart call needs to be made,
1296 In order to start logging again, a new %logstart call needs to be made,
1297 possibly (though not necessarily) with a new filename, mode and other
1297 possibly (though not necessarily) with a new filename, mode and other
1298 options."""
1298 options."""
1299 self.logger.logstop()
1299 self.logger.logstop()
1300
1300
1301 def magic_logoff(self,parameter_s=''):
1301 def magic_logoff(self,parameter_s=''):
1302 """Temporarily stop logging.
1302 """Temporarily stop logging.
1303
1303
1304 You must have previously started logging."""
1304 You must have previously started logging."""
1305 self.shell.logger.switch_log(0)
1305 self.shell.logger.switch_log(0)
1306
1306
1307 def magic_logon(self,parameter_s=''):
1307 def magic_logon(self,parameter_s=''):
1308 """Restart logging.
1308 """Restart logging.
1309
1309
1310 This function is for restarting logging which you've temporarily
1310 This function is for restarting logging which you've temporarily
1311 stopped with %logoff. For starting logging for the first time, you
1311 stopped with %logoff. For starting logging for the first time, you
1312 must use the %logstart function, which allows you to specify an
1312 must use the %logstart function, which allows you to specify an
1313 optional log filename."""
1313 optional log filename."""
1314
1314
1315 self.shell.logger.switch_log(1)
1315 self.shell.logger.switch_log(1)
1316
1316
1317 def magic_logstate(self,parameter_s=''):
1317 def magic_logstate(self,parameter_s=''):
1318 """Print the status of the logging system."""
1318 """Print the status of the logging system."""
1319
1319
1320 self.shell.logger.logstate()
1320 self.shell.logger.logstate()
1321
1321
1322 def magic_pdb(self, parameter_s=''):
1322 def magic_pdb(self, parameter_s=''):
1323 """Control the automatic calling of the pdb interactive debugger.
1323 """Control the automatic calling of the pdb interactive debugger.
1324
1324
1325 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1325 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1326 argument it works as a toggle.
1326 argument it works as a toggle.
1327
1327
1328 When an exception is triggered, IPython can optionally call the
1328 When an exception is triggered, IPython can optionally call the
1329 interactive pdb debugger after the traceback printout. %pdb toggles
1329 interactive pdb debugger after the traceback printout. %pdb toggles
1330 this feature on and off.
1330 this feature on and off.
1331
1331
1332 The initial state of this feature is set in your configuration
1332 The initial state of this feature is set in your configuration
1333 file (the option is ``InteractiveShell.pdb``).
1333 file (the option is ``InteractiveShell.pdb``).
1334
1334
1335 If you want to just activate the debugger AFTER an exception has fired,
1335 If you want to just activate the debugger AFTER an exception has fired,
1336 without having to type '%pdb on' and rerunning your code, you can use
1336 without having to type '%pdb on' and rerunning your code, you can use
1337 the %debug magic."""
1337 the %debug magic."""
1338
1338
1339 par = parameter_s.strip().lower()
1339 par = parameter_s.strip().lower()
1340
1340
1341 if par:
1341 if par:
1342 try:
1342 try:
1343 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1343 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1344 except KeyError:
1344 except KeyError:
1345 print ('Incorrect argument. Use on/1, off/0, '
1345 print ('Incorrect argument. Use on/1, off/0, '
1346 'or nothing for a toggle.')
1346 'or nothing for a toggle.')
1347 return
1347 return
1348 else:
1348 else:
1349 # toggle
1349 # toggle
1350 new_pdb = not self.shell.call_pdb
1350 new_pdb = not self.shell.call_pdb
1351
1351
1352 # set on the shell
1352 # set on the shell
1353 self.shell.call_pdb = new_pdb
1353 self.shell.call_pdb = new_pdb
1354 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1354 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1355
1355
1356 def magic_debug(self, parameter_s=''):
1356 def magic_debug(self, parameter_s=''):
1357 """Activate the interactive debugger in post-mortem mode.
1357 """Activate the interactive debugger in post-mortem mode.
1358
1358
1359 If an exception has just occurred, this lets you inspect its stack
1359 If an exception has just occurred, this lets you inspect its stack
1360 frames interactively. Note that this will always work only on the last
1360 frames interactively. Note that this will always work only on the last
1361 traceback that occurred, so you must call this quickly after an
1361 traceback that occurred, so you must call this quickly after an
1362 exception that you wish to inspect has fired, because if another one
1362 exception that you wish to inspect has fired, because if another one
1363 occurs, it clobbers the previous one.
1363 occurs, it clobbers the previous one.
1364
1364
1365 If you want IPython to automatically do this on every exception, see
1365 If you want IPython to automatically do this on every exception, see
1366 the %pdb magic for more details.
1366 the %pdb magic for more details.
1367 """
1367 """
1368 self.shell.debugger(force=True)
1368 self.shell.debugger(force=True)
1369
1369
1370 @skip_doctest
1370 @skip_doctest
1371 def magic_prun(self, parameter_s ='',user_mode=1,
1371 def magic_prun(self, parameter_s ='',user_mode=1,
1372 opts=None,arg_lst=None,prog_ns=None):
1372 opts=None,arg_lst=None,prog_ns=None):
1373
1373
1374 """Run a statement through the python code profiler.
1374 """Run a statement through the python code profiler.
1375
1375
1376 Usage:
1376 Usage:
1377 %prun [options] statement
1377 %prun [options] statement
1378
1378
1379 The given statement (which doesn't require quote marks) is run via the
1379 The given statement (which doesn't require quote marks) is run via the
1380 python profiler in a manner similar to the profile.run() function.
1380 python profiler in a manner similar to the profile.run() function.
1381 Namespaces are internally managed to work correctly; profile.run
1381 Namespaces are internally managed to work correctly; profile.run
1382 cannot be used in IPython because it makes certain assumptions about
1382 cannot be used in IPython because it makes certain assumptions about
1383 namespaces which do not hold under IPython.
1383 namespaces which do not hold under IPython.
1384
1384
1385 Options:
1385 Options:
1386
1386
1387 -l <limit>: you can place restrictions on what or how much of the
1387 -l <limit>: you can place restrictions on what or how much of the
1388 profile gets printed. The limit value can be:
1388 profile gets printed. The limit value can be:
1389
1389
1390 * A string: only information for function names containing this string
1390 * A string: only information for function names containing this string
1391 is printed.
1391 is printed.
1392
1392
1393 * An integer: only these many lines are printed.
1393 * An integer: only these many lines are printed.
1394
1394
1395 * A float (between 0 and 1): this fraction of the report is printed
1395 * A float (between 0 and 1): this fraction of the report is printed
1396 (for example, use a limit of 0.4 to see the topmost 40% only).
1396 (for example, use a limit of 0.4 to see the topmost 40% only).
1397
1397
1398 You can combine several limits with repeated use of the option. For
1398 You can combine several limits with repeated use of the option. For
1399 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1399 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1400 information about class constructors.
1400 information about class constructors.
1401
1401
1402 -r: return the pstats.Stats object generated by the profiling. This
1402 -r: return the pstats.Stats object generated by the profiling. This
1403 object has all the information about the profile in it, and you can
1403 object has all the information about the profile in it, and you can
1404 later use it for further analysis or in other functions.
1404 later use it for further analysis or in other functions.
1405
1405
1406 -s <key>: sort profile by given key. You can provide more than one key
1406 -s <key>: sort profile by given key. You can provide more than one key
1407 by using the option several times: '-s key1 -s key2 -s key3...'. The
1407 by using the option several times: '-s key1 -s key2 -s key3...'. The
1408 default sorting key is 'time'.
1408 default sorting key is 'time'.
1409
1409
1410 The following is copied verbatim from the profile documentation
1410 The following is copied verbatim from the profile documentation
1411 referenced below:
1411 referenced below:
1412
1412
1413 When more than one key is provided, additional keys are used as
1413 When more than one key is provided, additional keys are used as
1414 secondary criteria when the there is equality in all keys selected
1414 secondary criteria when the there is equality in all keys selected
1415 before them.
1415 before them.
1416
1416
1417 Abbreviations can be used for any key names, as long as the
1417 Abbreviations can be used for any key names, as long as the
1418 abbreviation is unambiguous. The following are the keys currently
1418 abbreviation is unambiguous. The following are the keys currently
1419 defined:
1419 defined:
1420
1420
1421 Valid Arg Meaning
1421 Valid Arg Meaning
1422 "calls" call count
1422 "calls" call count
1423 "cumulative" cumulative time
1423 "cumulative" cumulative time
1424 "file" file name
1424 "file" file name
1425 "module" file name
1425 "module" file name
1426 "pcalls" primitive call count
1426 "pcalls" primitive call count
1427 "line" line number
1427 "line" line number
1428 "name" function name
1428 "name" function name
1429 "nfl" name/file/line
1429 "nfl" name/file/line
1430 "stdname" standard name
1430 "stdname" standard name
1431 "time" internal time
1431 "time" internal time
1432
1432
1433 Note that all sorts on statistics are in descending order (placing
1433 Note that all sorts on statistics are in descending order (placing
1434 most time consuming items first), where as name, file, and line number
1434 most time consuming items first), where as name, file, and line number
1435 searches are in ascending order (i.e., alphabetical). The subtle
1435 searches are in ascending order (i.e., alphabetical). The subtle
1436 distinction between "nfl" and "stdname" is that the standard name is a
1436 distinction between "nfl" and "stdname" is that the standard name is a
1437 sort of the name as printed, which means that the embedded line
1437 sort of the name as printed, which means that the embedded line
1438 numbers get compared in an odd way. For example, lines 3, 20, and 40
1438 numbers get compared in an odd way. For example, lines 3, 20, and 40
1439 would (if the file names were the same) appear in the string order
1439 would (if the file names were the same) appear in the string order
1440 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1440 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1441 line numbers. In fact, sort_stats("nfl") is the same as
1441 line numbers. In fact, sort_stats("nfl") is the same as
1442 sort_stats("name", "file", "line").
1442 sort_stats("name", "file", "line").
1443
1443
1444 -T <filename>: save profile results as shown on screen to a text
1444 -T <filename>: save profile results as shown on screen to a text
1445 file. The profile is still shown on screen.
1445 file. The profile is still shown on screen.
1446
1446
1447 -D <filename>: save (via dump_stats) profile statistics to given
1447 -D <filename>: save (via dump_stats) profile statistics to given
1448 filename. This data is in a format understood by the pstats module, and
1448 filename. This data is in a format understood by the pstats module, and
1449 is generated by a call to the dump_stats() method of profile
1449 is generated by a call to the dump_stats() method of profile
1450 objects. The profile is still shown on screen.
1450 objects. The profile is still shown on screen.
1451
1451
1452 -q: suppress output to the pager. Best used with -T and/or -D above.
1452 -q: suppress output to the pager. Best used with -T and/or -D above.
1453
1453
1454 If you want to run complete programs under the profiler's control, use
1454 If you want to run complete programs under the profiler's control, use
1455 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1455 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1456 contains profiler specific options as described here.
1456 contains profiler specific options as described here.
1457
1457
1458 You can read the complete documentation for the profile module with::
1458 You can read the complete documentation for the profile module with::
1459
1459
1460 In [1]: import profile; profile.help()
1460 In [1]: import profile; profile.help()
1461 """
1461 """
1462
1462
1463 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1463 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1464
1464
1465 if user_mode: # regular user call
1465 if user_mode: # regular user call
1466 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
1466 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
1467 list_all=1, posix=False)
1467 list_all=1, posix=False)
1468 namespace = self.shell.user_ns
1468 namespace = self.shell.user_ns
1469 else: # called to run a program by %run -p
1469 else: # called to run a program by %run -p
1470 try:
1470 try:
1471 filename = get_py_filename(arg_lst[0])
1471 filename = get_py_filename(arg_lst[0])
1472 except IOError as e:
1472 except IOError as e:
1473 try:
1473 try:
1474 msg = str(e)
1474 msg = str(e)
1475 except UnicodeError:
1475 except UnicodeError:
1476 msg = e.message
1476 msg = e.message
1477 error(msg)
1477 error(msg)
1478 return
1478 return
1479
1479
1480 arg_str = 'execfile(filename,prog_ns)'
1480 arg_str = 'execfile(filename,prog_ns)'
1481 namespace = {
1481 namespace = {
1482 'execfile': self.shell.safe_execfile,
1482 'execfile': self.shell.safe_execfile,
1483 'prog_ns': prog_ns,
1483 'prog_ns': prog_ns,
1484 'filename': filename
1484 'filename': filename
1485 }
1485 }
1486
1486
1487 opts.merge(opts_def)
1487 opts.merge(opts_def)
1488
1488
1489 prof = profile.Profile()
1489 prof = profile.Profile()
1490 try:
1490 try:
1491 prof = prof.runctx(arg_str,namespace,namespace)
1491 prof = prof.runctx(arg_str,namespace,namespace)
1492 sys_exit = ''
1492 sys_exit = ''
1493 except SystemExit:
1493 except SystemExit:
1494 sys_exit = """*** SystemExit exception caught in code being profiled."""
1494 sys_exit = """*** SystemExit exception caught in code being profiled."""
1495
1495
1496 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1496 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1497
1497
1498 lims = opts.l
1498 lims = opts.l
1499 if lims:
1499 if lims:
1500 lims = [] # rebuild lims with ints/floats/strings
1500 lims = [] # rebuild lims with ints/floats/strings
1501 for lim in opts.l:
1501 for lim in opts.l:
1502 try:
1502 try:
1503 lims.append(int(lim))
1503 lims.append(int(lim))
1504 except ValueError:
1504 except ValueError:
1505 try:
1505 try:
1506 lims.append(float(lim))
1506 lims.append(float(lim))
1507 except ValueError:
1507 except ValueError:
1508 lims.append(lim)
1508 lims.append(lim)
1509
1509
1510 # Trap output.
1510 # Trap output.
1511 stdout_trap = StringIO()
1511 stdout_trap = StringIO()
1512
1512
1513 if hasattr(stats,'stream'):
1513 if hasattr(stats,'stream'):
1514 # In newer versions of python, the stats object has a 'stream'
1514 # In newer versions of python, the stats object has a 'stream'
1515 # attribute to write into.
1515 # attribute to write into.
1516 stats.stream = stdout_trap
1516 stats.stream = stdout_trap
1517 stats.print_stats(*lims)
1517 stats.print_stats(*lims)
1518 else:
1518 else:
1519 # For older versions, we manually redirect stdout during printing
1519 # For older versions, we manually redirect stdout during printing
1520 sys_stdout = sys.stdout
1520 sys_stdout = sys.stdout
1521 try:
1521 try:
1522 sys.stdout = stdout_trap
1522 sys.stdout = stdout_trap
1523 stats.print_stats(*lims)
1523 stats.print_stats(*lims)
1524 finally:
1524 finally:
1525 sys.stdout = sys_stdout
1525 sys.stdout = sys_stdout
1526
1526
1527 output = stdout_trap.getvalue()
1527 output = stdout_trap.getvalue()
1528 output = output.rstrip()
1528 output = output.rstrip()
1529
1529
1530 if 'q' not in opts:
1530 if 'q' not in opts:
1531 page.page(output)
1531 page.page(output)
1532 print sys_exit,
1532 print sys_exit,
1533
1533
1534 dump_file = opts.D[0]
1534 dump_file = opts.D[0]
1535 text_file = opts.T[0]
1535 text_file = opts.T[0]
1536 if dump_file:
1536 if dump_file:
1537 dump_file = unquote_filename(dump_file)
1537 dump_file = unquote_filename(dump_file)
1538 prof.dump_stats(dump_file)
1538 prof.dump_stats(dump_file)
1539 print '\n*** Profile stats marshalled to file',\
1539 print '\n*** Profile stats marshalled to file',\
1540 `dump_file`+'.',sys_exit
1540 `dump_file`+'.',sys_exit
1541 if text_file:
1541 if text_file:
1542 text_file = unquote_filename(text_file)
1542 text_file = unquote_filename(text_file)
1543 pfile = open(text_file,'w')
1543 pfile = open(text_file,'w')
1544 pfile.write(output)
1544 pfile.write(output)
1545 pfile.close()
1545 pfile.close()
1546 print '\n*** Profile printout saved to text file',\
1546 print '\n*** Profile printout saved to text file',\
1547 `text_file`+'.',sys_exit
1547 `text_file`+'.',sys_exit
1548
1548
1549 if opts.has_key('r'):
1549 if opts.has_key('r'):
1550 return stats
1550 return stats
1551 else:
1551 else:
1552 return None
1552 return None
1553
1553
1554 @skip_doctest
1554 @skip_doctest
1555 def magic_run(self, parameter_s ='', runner=None,
1555 def magic_run(self, parameter_s ='', runner=None,
1556 file_finder=get_py_filename):
1556 file_finder=get_py_filename):
1557 """Run the named file inside IPython as a program.
1557 """Run the named file inside IPython as a program.
1558
1558
1559 Usage:\\
1559 Usage:\\
1560 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1560 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1561
1561
1562 Parameters after the filename are passed as command-line arguments to
1562 Parameters after the filename are passed as command-line arguments to
1563 the program (put in sys.argv). Then, control returns to IPython's
1563 the program (put in sys.argv). Then, control returns to IPython's
1564 prompt.
1564 prompt.
1565
1565
1566 This is similar to running at a system prompt:\\
1566 This is similar to running at a system prompt:\\
1567 $ python file args\\
1567 $ python file args\\
1568 but with the advantage of giving you IPython's tracebacks, and of
1568 but with the advantage of giving you IPython's tracebacks, and of
1569 loading all variables into your interactive namespace for further use
1569 loading all variables into your interactive namespace for further use
1570 (unless -p is used, see below).
1570 (unless -p is used, see below).
1571
1571
1572 The file is executed in a namespace initially consisting only of
1572 The file is executed in a namespace initially consisting only of
1573 __name__=='__main__' and sys.argv constructed as indicated. It thus
1573 __name__=='__main__' and sys.argv constructed as indicated. It thus
1574 sees its environment as if it were being run as a stand-alone program
1574 sees its environment as if it were being run as a stand-alone program
1575 (except for sharing global objects such as previously imported
1575 (except for sharing global objects such as previously imported
1576 modules). But after execution, the IPython interactive namespace gets
1576 modules). But after execution, the IPython interactive namespace gets
1577 updated with all variables defined in the program (except for __name__
1577 updated with all variables defined in the program (except for __name__
1578 and sys.argv). This allows for very convenient loading of code for
1578 and sys.argv). This allows for very convenient loading of code for
1579 interactive work, while giving each program a 'clean sheet' to run in.
1579 interactive work, while giving each program a 'clean sheet' to run in.
1580
1580
1581 Options:
1581 Options:
1582
1582
1583 -n: __name__ is NOT set to '__main__', but to the running file's name
1583 -n: __name__ is NOT set to '__main__', but to the running file's name
1584 without extension (as python does under import). This allows running
1584 without extension (as python does under import). This allows running
1585 scripts and reloading the definitions in them without calling code
1585 scripts and reloading the definitions in them without calling code
1586 protected by an ' if __name__ == "__main__" ' clause.
1586 protected by an ' if __name__ == "__main__" ' clause.
1587
1587
1588 -i: run the file in IPython's namespace instead of an empty one. This
1588 -i: run the file in IPython's namespace instead of an empty one. This
1589 is useful if you are experimenting with code written in a text editor
1589 is useful if you are experimenting with code written in a text editor
1590 which depends on variables defined interactively.
1590 which depends on variables defined interactively.
1591
1591
1592 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1592 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1593 being run. This is particularly useful if IPython is being used to
1593 being run. This is particularly useful if IPython is being used to
1594 run unittests, which always exit with a sys.exit() call. In such
1594 run unittests, which always exit with a sys.exit() call. In such
1595 cases you are interested in the output of the test results, not in
1595 cases you are interested in the output of the test results, not in
1596 seeing a traceback of the unittest module.
1596 seeing a traceback of the unittest module.
1597
1597
1598 -t: print timing information at the end of the run. IPython will give
1598 -t: print timing information at the end of the run. IPython will give
1599 you an estimated CPU time consumption for your script, which under
1599 you an estimated CPU time consumption for your script, which under
1600 Unix uses the resource module to avoid the wraparound problems of
1600 Unix uses the resource module to avoid the wraparound problems of
1601 time.clock(). Under Unix, an estimate of time spent on system tasks
1601 time.clock(). Under Unix, an estimate of time spent on system tasks
1602 is also given (for Windows platforms this is reported as 0.0).
1602 is also given (for Windows platforms this is reported as 0.0).
1603
1603
1604 If -t is given, an additional -N<N> option can be given, where <N>
1604 If -t is given, an additional -N<N> option can be given, where <N>
1605 must be an integer indicating how many times you want the script to
1605 must be an integer indicating how many times you want the script to
1606 run. The final timing report will include total and per run results.
1606 run. The final timing report will include total and per run results.
1607
1607
1608 For example (testing the script uniq_stable.py)::
1608 For example (testing the script uniq_stable.py)::
1609
1609
1610 In [1]: run -t uniq_stable
1610 In [1]: run -t uniq_stable
1611
1611
1612 IPython CPU timings (estimated):\\
1612 IPython CPU timings (estimated):\\
1613 User : 0.19597 s.\\
1613 User : 0.19597 s.\\
1614 System: 0.0 s.\\
1614 System: 0.0 s.\\
1615
1615
1616 In [2]: run -t -N5 uniq_stable
1616 In [2]: run -t -N5 uniq_stable
1617
1617
1618 IPython CPU timings (estimated):\\
1618 IPython CPU timings (estimated):\\
1619 Total runs performed: 5\\
1619 Total runs performed: 5\\
1620 Times : Total Per run\\
1620 Times : Total Per run\\
1621 User : 0.910862 s, 0.1821724 s.\\
1621 User : 0.910862 s, 0.1821724 s.\\
1622 System: 0.0 s, 0.0 s.
1622 System: 0.0 s, 0.0 s.
1623
1623
1624 -d: run your program under the control of pdb, the Python debugger.
1624 -d: run your program under the control of pdb, the Python debugger.
1625 This allows you to execute your program step by step, watch variables,
1625 This allows you to execute your program step by step, watch variables,
1626 etc. Internally, what IPython does is similar to calling:
1626 etc. Internally, what IPython does is similar to calling:
1627
1627
1628 pdb.run('execfile("YOURFILENAME")')
1628 pdb.run('execfile("YOURFILENAME")')
1629
1629
1630 with a breakpoint set on line 1 of your file. You can change the line
1630 with a breakpoint set on line 1 of your file. You can change the line
1631 number for this automatic breakpoint to be <N> by using the -bN option
1631 number for this automatic breakpoint to be <N> by using the -bN option
1632 (where N must be an integer). For example::
1632 (where N must be an integer). For example::
1633
1633
1634 %run -d -b40 myscript
1634 %run -d -b40 myscript
1635
1635
1636 will set the first breakpoint at line 40 in myscript.py. Note that
1636 will set the first breakpoint at line 40 in myscript.py. Note that
1637 the first breakpoint must be set on a line which actually does
1637 the first breakpoint must be set on a line which actually does
1638 something (not a comment or docstring) for it to stop execution.
1638 something (not a comment or docstring) for it to stop execution.
1639
1639
1640 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1640 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1641 first enter 'c' (without quotes) to start execution up to the first
1641 first enter 'c' (without quotes) to start execution up to the first
1642 breakpoint.
1642 breakpoint.
1643
1643
1644 Entering 'help' gives information about the use of the debugger. You
1644 Entering 'help' gives information about the use of the debugger. You
1645 can easily see pdb's full documentation with "import pdb;pdb.help()"
1645 can easily see pdb's full documentation with "import pdb;pdb.help()"
1646 at a prompt.
1646 at a prompt.
1647
1647
1648 -p: run program under the control of the Python profiler module (which
1648 -p: run program under the control of the Python profiler module (which
1649 prints a detailed report of execution times, function calls, etc).
1649 prints a detailed report of execution times, function calls, etc).
1650
1650
1651 You can pass other options after -p which affect the behavior of the
1651 You can pass other options after -p which affect the behavior of the
1652 profiler itself. See the docs for %prun for details.
1652 profiler itself. See the docs for %prun for details.
1653
1653
1654 In this mode, the program's variables do NOT propagate back to the
1654 In this mode, the program's variables do NOT propagate back to the
1655 IPython interactive namespace (because they remain in the namespace
1655 IPython interactive namespace (because they remain in the namespace
1656 where the profiler executes them).
1656 where the profiler executes them).
1657
1657
1658 Internally this triggers a call to %prun, see its documentation for
1658 Internally this triggers a call to %prun, see its documentation for
1659 details on the options available specifically for profiling.
1659 details on the options available specifically for profiling.
1660
1660
1661 There is one special usage for which the text above doesn't apply:
1661 There is one special usage for which the text above doesn't apply:
1662 if the filename ends with .ipy, the file is run as ipython script,
1662 if the filename ends with .ipy, the file is run as ipython script,
1663 just as if the commands were written on IPython prompt.
1663 just as if the commands were written on IPython prompt.
1664
1664
1665 -m: specify module name to load instead of script path. Similar to
1665 -m: specify module name to load instead of script path. Similar to
1666 the -m option for the python interpreter. Use this option last if you
1666 the -m option for the python interpreter. Use this option last if you
1667 want to combine with other %run options. Unlike the python interpreter
1667 want to combine with other %run options. Unlike the python interpreter
1668 only source modules are allowed no .pyc or .pyo files.
1668 only source modules are allowed no .pyc or .pyo files.
1669 For example::
1669 For example::
1670
1670
1671 %run -m example
1671 %run -m example
1672
1672
1673 will run the example module.
1673 will run the example module.
1674
1674
1675 """
1675 """
1676
1676
1677 # get arguments and set sys.argv for program to be run.
1677 # get arguments and set sys.argv for program to be run.
1678 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
1678 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
1679 mode='list', list_all=1)
1679 mode='list', list_all=1)
1680 if "m" in opts:
1680 if "m" in opts:
1681 modulename = opts["m"][0]
1681 modulename = opts["m"][0]
1682 modpath = find_mod(modulename)
1682 modpath = find_mod(modulename)
1683 if modpath is None:
1683 if modpath is None:
1684 warn('%r is not a valid modulename on sys.path'%modulename)
1684 warn('%r is not a valid modulename on sys.path'%modulename)
1685 return
1685 return
1686 arg_lst = [modpath] + arg_lst
1686 arg_lst = [modpath] + arg_lst
1687 try:
1687 try:
1688 filename = file_finder(arg_lst[0])
1688 filename = file_finder(arg_lst[0])
1689 except IndexError:
1689 except IndexError:
1690 warn('you must provide at least a filename.')
1690 warn('you must provide at least a filename.')
1691 print '\n%run:\n', oinspect.getdoc(self.magic_run)
1691 print '\n%run:\n', oinspect.getdoc(self.magic_run)
1692 return
1692 return
1693 except IOError as e:
1693 except IOError as e:
1694 try:
1694 try:
1695 msg = str(e)
1695 msg = str(e)
1696 except UnicodeError:
1696 except UnicodeError:
1697 msg = e.message
1697 msg = e.message
1698 error(msg)
1698 error(msg)
1699 return
1699 return
1700
1700
1701 if filename.lower().endswith('.ipy'):
1701 if filename.lower().endswith('.ipy'):
1702 self.shell.safe_execfile_ipy(filename)
1702 self.shell.safe_execfile_ipy(filename)
1703 return
1703 return
1704
1704
1705 # Control the response to exit() calls made by the script being run
1705 # Control the response to exit() calls made by the script being run
1706 exit_ignore = 'e' in opts
1706 exit_ignore = 'e' in opts
1707
1707
1708 # Make sure that the running script gets a proper sys.argv as if it
1708 # Make sure that the running script gets a proper sys.argv as if it
1709 # were run from a system shell.
1709 # were run from a system shell.
1710 save_argv = sys.argv # save it for later restoring
1710 save_argv = sys.argv # save it for later restoring
1711
1711
1712 # simulate shell expansion on arguments, at least tilde expansion
1712 # simulate shell expansion on arguments, at least tilde expansion
1713 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
1713 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
1714
1714
1715 sys.argv = [filename] + args # put in the proper filename
1715 sys.argv = [filename] + args # put in the proper filename
1716 # protect sys.argv from potential unicode strings on Python 2:
1716 # protect sys.argv from potential unicode strings on Python 2:
1717 if not py3compat.PY3:
1717 if not py3compat.PY3:
1718 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
1718 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
1719
1719
1720 if 'i' in opts:
1720 if 'i' in opts:
1721 # Run in user's interactive namespace
1721 # Run in user's interactive namespace
1722 prog_ns = self.shell.user_ns
1722 prog_ns = self.shell.user_ns
1723 __name__save = self.shell.user_ns['__name__']
1723 __name__save = self.shell.user_ns['__name__']
1724 prog_ns['__name__'] = '__main__'
1724 prog_ns['__name__'] = '__main__'
1725 main_mod = self.shell.new_main_mod(prog_ns)
1725 main_mod = self.shell.new_main_mod(prog_ns)
1726 else:
1726 else:
1727 # Run in a fresh, empty namespace
1727 # Run in a fresh, empty namespace
1728 if 'n' in opts:
1728 if 'n' in opts:
1729 name = os.path.splitext(os.path.basename(filename))[0]
1729 name = os.path.splitext(os.path.basename(filename))[0]
1730 else:
1730 else:
1731 name = '__main__'
1731 name = '__main__'
1732
1732
1733 main_mod = self.shell.new_main_mod()
1733 main_mod = self.shell.new_main_mod()
1734 prog_ns = main_mod.__dict__
1734 prog_ns = main_mod.__dict__
1735 prog_ns['__name__'] = name
1735 prog_ns['__name__'] = name
1736
1736
1737 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1737 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1738 # set the __file__ global in the script's namespace
1738 # set the __file__ global in the script's namespace
1739 prog_ns['__file__'] = filename
1739 prog_ns['__file__'] = filename
1740
1740
1741 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1741 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1742 # that, if we overwrite __main__, we replace it at the end
1742 # that, if we overwrite __main__, we replace it at the end
1743 main_mod_name = prog_ns['__name__']
1743 main_mod_name = prog_ns['__name__']
1744
1744
1745 if main_mod_name == '__main__':
1745 if main_mod_name == '__main__':
1746 restore_main = sys.modules['__main__']
1746 restore_main = sys.modules['__main__']
1747 else:
1747 else:
1748 restore_main = False
1748 restore_main = False
1749
1749
1750 # This needs to be undone at the end to prevent holding references to
1750 # This needs to be undone at the end to prevent holding references to
1751 # every single object ever created.
1751 # every single object ever created.
1752 sys.modules[main_mod_name] = main_mod
1752 sys.modules[main_mod_name] = main_mod
1753
1753
1754 try:
1754 try:
1755 stats = None
1755 stats = None
1756 with self.shell.readline_no_record:
1756 with self.shell.readline_no_record:
1757 if 'p' in opts:
1757 if 'p' in opts:
1758 stats = self.magic_prun('', 0, opts, arg_lst, prog_ns)
1758 stats = self.magic_prun('', 0, opts, arg_lst, prog_ns)
1759 else:
1759 else:
1760 if 'd' in opts:
1760 if 'd' in opts:
1761 deb = debugger.Pdb(self.shell.colors)
1761 deb = debugger.Pdb(self.shell.colors)
1762 # reset Breakpoint state, which is moronically kept
1762 # reset Breakpoint state, which is moronically kept
1763 # in a class
1763 # in a class
1764 bdb.Breakpoint.next = 1
1764 bdb.Breakpoint.next = 1
1765 bdb.Breakpoint.bplist = {}
1765 bdb.Breakpoint.bplist = {}
1766 bdb.Breakpoint.bpbynumber = [None]
1766 bdb.Breakpoint.bpbynumber = [None]
1767 # Set an initial breakpoint to stop execution
1767 # Set an initial breakpoint to stop execution
1768 maxtries = 10
1768 maxtries = 10
1769 bp = int(opts.get('b', [1])[0])
1769 bp = int(opts.get('b', [1])[0])
1770 checkline = deb.checkline(filename, bp)
1770 checkline = deb.checkline(filename, bp)
1771 if not checkline:
1771 if not checkline:
1772 for bp in range(bp + 1, bp + maxtries + 1):
1772 for bp in range(bp + 1, bp + maxtries + 1):
1773 if deb.checkline(filename, bp):
1773 if deb.checkline(filename, bp):
1774 break
1774 break
1775 else:
1775 else:
1776 msg = ("\nI failed to find a valid line to set "
1776 msg = ("\nI failed to find a valid line to set "
1777 "a breakpoint\n"
1777 "a breakpoint\n"
1778 "after trying up to line: %s.\n"
1778 "after trying up to line: %s.\n"
1779 "Please set a valid breakpoint manually "
1779 "Please set a valid breakpoint manually "
1780 "with the -b option." % bp)
1780 "with the -b option." % bp)
1781 error(msg)
1781 error(msg)
1782 return
1782 return
1783 # if we find a good linenumber, set the breakpoint
1783 # if we find a good linenumber, set the breakpoint
1784 deb.do_break('%s:%s' % (filename, bp))
1784 deb.do_break('%s:%s' % (filename, bp))
1785 # Start file run
1785 # Start file run
1786 print "NOTE: Enter 'c' at the",
1786 print "NOTE: Enter 'c' at the",
1787 print "%s prompt to start your script." % deb.prompt
1787 print "%s prompt to start your script." % deb.prompt
1788 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
1788 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
1789 try:
1789 try:
1790 deb.run('execfile("%s", prog_ns)' % filename, ns)
1790 deb.run('execfile("%s", prog_ns)' % filename, ns)
1791
1791
1792 except:
1792 except:
1793 etype, value, tb = sys.exc_info()
1793 etype, value, tb = sys.exc_info()
1794 # Skip three frames in the traceback: the %run one,
1794 # Skip three frames in the traceback: the %run one,
1795 # one inside bdb.py, and the command-line typed by the
1795 # one inside bdb.py, and the command-line typed by the
1796 # user (run by exec in pdb itself).
1796 # user (run by exec in pdb itself).
1797 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
1797 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
1798 else:
1798 else:
1799 if runner is None:
1799 if runner is None:
1800 runner = self.default_runner
1800 runner = self.default_runner
1801 if runner is None:
1801 if runner is None:
1802 runner = self.shell.safe_execfile
1802 runner = self.shell.safe_execfile
1803 if 't' in opts:
1803 if 't' in opts:
1804 # timed execution
1804 # timed execution
1805 try:
1805 try:
1806 nruns = int(opts['N'][0])
1806 nruns = int(opts['N'][0])
1807 if nruns < 1:
1807 if nruns < 1:
1808 error('Number of runs must be >=1')
1808 error('Number of runs must be >=1')
1809 return
1809 return
1810 except (KeyError):
1810 except (KeyError):
1811 nruns = 1
1811 nruns = 1
1812 twall0 = time.time()
1812 twall0 = time.time()
1813 if nruns == 1:
1813 if nruns == 1:
1814 t0 = clock2()
1814 t0 = clock2()
1815 runner(filename, prog_ns, prog_ns,
1815 runner(filename, prog_ns, prog_ns,
1816 exit_ignore=exit_ignore)
1816 exit_ignore=exit_ignore)
1817 t1 = clock2()
1817 t1 = clock2()
1818 t_usr = t1[0] - t0[0]
1818 t_usr = t1[0] - t0[0]
1819 t_sys = t1[1] - t0[1]
1819 t_sys = t1[1] - t0[1]
1820 print "\nIPython CPU timings (estimated):"
1820 print "\nIPython CPU timings (estimated):"
1821 print " User : %10.2f s." % t_usr
1821 print " User : %10.2f s." % t_usr
1822 print " System : %10.2f s." % t_sys
1822 print " System : %10.2f s." % t_sys
1823 else:
1823 else:
1824 runs = range(nruns)
1824 runs = range(nruns)
1825 t0 = clock2()
1825 t0 = clock2()
1826 for nr in runs:
1826 for nr in runs:
1827 runner(filename, prog_ns, prog_ns,
1827 runner(filename, prog_ns, prog_ns,
1828 exit_ignore=exit_ignore)
1828 exit_ignore=exit_ignore)
1829 t1 = clock2()
1829 t1 = clock2()
1830 t_usr = t1[0] - t0[0]
1830 t_usr = t1[0] - t0[0]
1831 t_sys = t1[1] - t0[1]
1831 t_sys = t1[1] - t0[1]
1832 print "\nIPython CPU timings (estimated):"
1832 print "\nIPython CPU timings (estimated):"
1833 print "Total runs performed:", nruns
1833 print "Total runs performed:", nruns
1834 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
1834 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
1835 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
1835 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
1836 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
1836 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
1837 twall1 = time.time()
1837 twall1 = time.time()
1838 print "Wall time: %10.2f s." % (twall1 - twall0)
1838 print "Wall time: %10.2f s." % (twall1 - twall0)
1839
1839
1840 else:
1840 else:
1841 # regular execution
1841 # regular execution
1842 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
1842 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
1843
1843
1844 if 'i' in opts:
1844 if 'i' in opts:
1845 self.shell.user_ns['__name__'] = __name__save
1845 self.shell.user_ns['__name__'] = __name__save
1846 else:
1846 else:
1847 # The shell MUST hold a reference to prog_ns so after %run
1847 # The shell MUST hold a reference to prog_ns so after %run
1848 # exits, the python deletion mechanism doesn't zero it out
1848 # exits, the python deletion mechanism doesn't zero it out
1849 # (leaving dangling references).
1849 # (leaving dangling references).
1850 self.shell.cache_main_mod(prog_ns, filename)
1850 self.shell.cache_main_mod(prog_ns, filename)
1851 # update IPython interactive namespace
1851 # update IPython interactive namespace
1852
1852
1853 # Some forms of read errors on the file may mean the
1853 # Some forms of read errors on the file may mean the
1854 # __name__ key was never set; using pop we don't have to
1854 # __name__ key was never set; using pop we don't have to
1855 # worry about a possible KeyError.
1855 # worry about a possible KeyError.
1856 prog_ns.pop('__name__', None)
1856 prog_ns.pop('__name__', None)
1857
1857
1858 self.shell.user_ns.update(prog_ns)
1858 self.shell.user_ns.update(prog_ns)
1859 finally:
1859 finally:
1860 # It's a bit of a mystery why, but __builtins__ can change from
1860 # It's a bit of a mystery why, but __builtins__ can change from
1861 # being a module to becoming a dict missing some key data after
1861 # being a module to becoming a dict missing some key data after
1862 # %run. As best I can see, this is NOT something IPython is doing
1862 # %run. As best I can see, this is NOT something IPython is doing
1863 # at all, and similar problems have been reported before:
1863 # at all, and similar problems have been reported before:
1864 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1864 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1865 # Since this seems to be done by the interpreter itself, the best
1865 # Since this seems to be done by the interpreter itself, the best
1866 # we can do is to at least restore __builtins__ for the user on
1866 # we can do is to at least restore __builtins__ for the user on
1867 # exit.
1867 # exit.
1868 self.shell.user_ns['__builtins__'] = builtin_mod
1868 self.shell.user_ns['__builtins__'] = builtin_mod
1869
1869
1870 # Ensure key global structures are restored
1870 # Ensure key global structures are restored
1871 sys.argv = save_argv
1871 sys.argv = save_argv
1872 if restore_main:
1872 if restore_main:
1873 sys.modules['__main__'] = restore_main
1873 sys.modules['__main__'] = restore_main
1874 else:
1874 else:
1875 # Remove from sys.modules the reference to main_mod we'd
1875 # Remove from sys.modules the reference to main_mod we'd
1876 # added. Otherwise it will trap references to objects
1876 # added. Otherwise it will trap references to objects
1877 # contained therein.
1877 # contained therein.
1878 del sys.modules[main_mod_name]
1878 del sys.modules[main_mod_name]
1879
1879
1880 return stats
1880 return stats
1881
1881
1882 @skip_doctest
1882 @skip_doctest
1883 def magic_timeit(self, parameter_s =''):
1883 def magic_timeit(self, parameter_s =''):
1884 """Time execution of a Python statement or expression
1884 """Time execution of a Python statement or expression
1885
1885
1886 Usage:\\
1886 Usage:\\
1887 %timeit [-n<N> -r<R> [-t|-c]] statement
1887 %timeit [-n<N> -r<R> [-t|-c]] statement
1888
1888
1889 Time execution of a Python statement or expression using the timeit
1889 Time execution of a Python statement or expression using the timeit
1890 module.
1890 module.
1891
1891
1892 Options:
1892 Options:
1893 -n<N>: execute the given statement <N> times in a loop. If this value
1893 -n<N>: execute the given statement <N> times in a loop. If this value
1894 is not given, a fitting value is chosen.
1894 is not given, a fitting value is chosen.
1895
1895
1896 -r<R>: repeat the loop iteration <R> times and take the best result.
1896 -r<R>: repeat the loop iteration <R> times and take the best result.
1897 Default: 3
1897 Default: 3
1898
1898
1899 -t: use time.time to measure the time, which is the default on Unix.
1899 -t: use time.time to measure the time, which is the default on Unix.
1900 This function measures wall time.
1900 This function measures wall time.
1901
1901
1902 -c: use time.clock to measure the time, which is the default on
1902 -c: use time.clock to measure the time, which is the default on
1903 Windows and measures wall time. On Unix, resource.getrusage is used
1903 Windows and measures wall time. On Unix, resource.getrusage is used
1904 instead and returns the CPU user time.
1904 instead and returns the CPU user time.
1905
1905
1906 -p<P>: use a precision of <P> digits to display the timing result.
1906 -p<P>: use a precision of <P> digits to display the timing result.
1907 Default: 3
1907 Default: 3
1908
1908
1909
1909
1910 Examples
1910 Examples
1911 --------
1911 --------
1912 ::
1912 ::
1913
1913
1914 In [1]: %timeit pass
1914 In [1]: %timeit pass
1915 10000000 loops, best of 3: 53.3 ns per loop
1915 10000000 loops, best of 3: 53.3 ns per loop
1916
1916
1917 In [2]: u = None
1917 In [2]: u = None
1918
1918
1919 In [3]: %timeit u is None
1919 In [3]: %timeit u is None
1920 10000000 loops, best of 3: 184 ns per loop
1920 10000000 loops, best of 3: 184 ns per loop
1921
1921
1922 In [4]: %timeit -r 4 u == None
1922 In [4]: %timeit -r 4 u == None
1923 1000000 loops, best of 4: 242 ns per loop
1923 1000000 loops, best of 4: 242 ns per loop
1924
1924
1925 In [5]: import time
1925 In [5]: import time
1926
1926
1927 In [6]: %timeit -n1 time.sleep(2)
1927 In [6]: %timeit -n1 time.sleep(2)
1928 1 loops, best of 3: 2 s per loop
1928 1 loops, best of 3: 2 s per loop
1929
1929
1930
1930
1931 The times reported by %timeit will be slightly higher than those
1931 The times reported by %timeit will be slightly higher than those
1932 reported by the timeit.py script when variables are accessed. This is
1932 reported by the timeit.py script when variables are accessed. This is
1933 due to the fact that %timeit executes the statement in the namespace
1933 due to the fact that %timeit executes the statement in the namespace
1934 of the shell, compared with timeit.py, which uses a single setup
1934 of the shell, compared with timeit.py, which uses a single setup
1935 statement to import function or create variables. Generally, the bias
1935 statement to import function or create variables. Generally, the bias
1936 does not matter as long as results from timeit.py are not mixed with
1936 does not matter as long as results from timeit.py are not mixed with
1937 those from %timeit."""
1937 those from %timeit."""
1938
1938
1939 import timeit
1939 import timeit
1940 import math
1940 import math
1941
1941
1942 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1942 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1943 # certain terminals. Until we figure out a robust way of
1943 # certain terminals. Until we figure out a robust way of
1944 # auto-detecting if the terminal can deal with it, use plain 'us' for
1944 # auto-detecting if the terminal can deal with it, use plain 'us' for
1945 # microseconds. I am really NOT happy about disabling the proper
1945 # microseconds. I am really NOT happy about disabling the proper
1946 # 'micro' prefix, but crashing is worse... If anyone knows what the
1946 # 'micro' prefix, but crashing is worse... If anyone knows what the
1947 # right solution for this is, I'm all ears...
1947 # right solution for this is, I'm all ears...
1948 #
1948 #
1949 # Note: using
1949 # Note: using
1950 #
1950 #
1951 # s = u'\xb5'
1951 # s = u'\xb5'
1952 # s.encode(sys.getdefaultencoding())
1952 # s.encode(sys.getdefaultencoding())
1953 #
1953 #
1954 # is not sufficient, as I've seen terminals where that fails but
1954 # is not sufficient, as I've seen terminals where that fails but
1955 # print s
1955 # print s
1956 #
1956 #
1957 # succeeds
1957 # succeeds
1958 #
1958 #
1959 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1959 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1960
1960
1961 #units = [u"s", u"ms",u'\xb5',"ns"]
1961 #units = [u"s", u"ms",u'\xb5',"ns"]
1962 units = [u"s", u"ms",u'us',"ns"]
1962 units = [u"s", u"ms",u'us',"ns"]
1963
1963
1964 scaling = [1, 1e3, 1e6, 1e9]
1964 scaling = [1, 1e3, 1e6, 1e9]
1965
1965
1966 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1966 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1967 posix=False, strict=False)
1967 posix=False, strict=False)
1968 if stmt == "":
1968 if stmt == "":
1969 return
1969 return
1970 timefunc = timeit.default_timer
1970 timefunc = timeit.default_timer
1971 number = int(getattr(opts, "n", 0))
1971 number = int(getattr(opts, "n", 0))
1972 repeat = int(getattr(opts, "r", timeit.default_repeat))
1972 repeat = int(getattr(opts, "r", timeit.default_repeat))
1973 precision = int(getattr(opts, "p", 3))
1973 precision = int(getattr(opts, "p", 3))
1974 if hasattr(opts, "t"):
1974 if hasattr(opts, "t"):
1975 timefunc = time.time
1975 timefunc = time.time
1976 if hasattr(opts, "c"):
1976 if hasattr(opts, "c"):
1977 timefunc = clock
1977 timefunc = clock
1978
1978
1979 timer = timeit.Timer(timer=timefunc)
1979 timer = timeit.Timer(timer=timefunc)
1980 # this code has tight coupling to the inner workings of timeit.Timer,
1980 # this code has tight coupling to the inner workings of timeit.Timer,
1981 # but is there a better way to achieve that the code stmt has access
1981 # but is there a better way to achieve that the code stmt has access
1982 # to the shell namespace?
1982 # to the shell namespace?
1983
1983
1984 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1984 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1985 'setup': "pass"}
1985 'setup': "pass"}
1986 # Track compilation time so it can be reported if too long
1986 # Track compilation time so it can be reported if too long
1987 # Minimum time above which compilation time will be reported
1987 # Minimum time above which compilation time will be reported
1988 tc_min = 0.1
1988 tc_min = 0.1
1989
1989
1990 t0 = clock()
1990 t0 = clock()
1991 code = compile(src, "<magic-timeit>", "exec")
1991 code = compile(src, "<magic-timeit>", "exec")
1992 tc = clock()-t0
1992 tc = clock()-t0
1993
1993
1994 ns = {}
1994 ns = {}
1995 exec code in self.shell.user_ns, ns
1995 exec code in self.shell.user_ns, ns
1996 timer.inner = ns["inner"]
1996 timer.inner = ns["inner"]
1997
1997
1998 if number == 0:
1998 if number == 0:
1999 # determine number so that 0.2 <= total time < 2.0
1999 # determine number so that 0.2 <= total time < 2.0
2000 number = 1
2000 number = 1
2001 for i in range(1, 10):
2001 for i in range(1, 10):
2002 if timer.timeit(number) >= 0.2:
2002 if timer.timeit(number) >= 0.2:
2003 break
2003 break
2004 number *= 10
2004 number *= 10
2005
2005
2006 best = min(timer.repeat(repeat, number)) / number
2006 best = min(timer.repeat(repeat, number)) / number
2007
2007
2008 if best > 0.0 and best < 1000.0:
2008 if best > 0.0 and best < 1000.0:
2009 order = min(-int(math.floor(math.log10(best)) // 3), 3)
2009 order = min(-int(math.floor(math.log10(best)) // 3), 3)
2010 elif best >= 1000.0:
2010 elif best >= 1000.0:
2011 order = 0
2011 order = 0
2012 else:
2012 else:
2013 order = 3
2013 order = 3
2014 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
2014 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
2015 precision,
2015 precision,
2016 best * scaling[order],
2016 best * scaling[order],
2017 units[order])
2017 units[order])
2018 if tc > tc_min:
2018 if tc > tc_min:
2019 print "Compiler time: %.2f s" % tc
2019 print "Compiler time: %.2f s" % tc
2020
2020
2021 @skip_doctest
2021 @skip_doctest
2022 @needs_local_scope
2022 @needs_local_scope
2023 def magic_time(self,parameter_s, user_locals):
2023 def magic_time(self,parameter_s, user_locals):
2024 """Time execution of a Python statement or expression.
2024 """Time execution of a Python statement or expression.
2025
2025
2026 The CPU and wall clock times are printed, and the value of the
2026 The CPU and wall clock times are printed, and the value of the
2027 expression (if any) is returned. Note that under Win32, system time
2027 expression (if any) is returned. Note that under Win32, system time
2028 is always reported as 0, since it can not be measured.
2028 is always reported as 0, since it can not be measured.
2029
2029
2030 This function provides very basic timing functionality. In Python
2030 This function provides very basic timing functionality. In Python
2031 2.3, the timeit module offers more control and sophistication, so this
2031 2.3, the timeit module offers more control and sophistication, so this
2032 could be rewritten to use it (patches welcome).
2032 could be rewritten to use it (patches welcome).
2033
2033
2034 Examples
2034 Examples
2035 --------
2035 --------
2036 ::
2036 ::
2037
2037
2038 In [1]: time 2**128
2038 In [1]: time 2**128
2039 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2039 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2040 Wall time: 0.00
2040 Wall time: 0.00
2041 Out[1]: 340282366920938463463374607431768211456L
2041 Out[1]: 340282366920938463463374607431768211456L
2042
2042
2043 In [2]: n = 1000000
2043 In [2]: n = 1000000
2044
2044
2045 In [3]: time sum(range(n))
2045 In [3]: time sum(range(n))
2046 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
2046 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
2047 Wall time: 1.37
2047 Wall time: 1.37
2048 Out[3]: 499999500000L
2048 Out[3]: 499999500000L
2049
2049
2050 In [4]: time print 'hello world'
2050 In [4]: time print 'hello world'
2051 hello world
2051 hello world
2052 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2052 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2053 Wall time: 0.00
2053 Wall time: 0.00
2054
2054
2055 Note that the time needed by Python to compile the given expression
2055 Note that the time needed by Python to compile the given expression
2056 will be reported if it is more than 0.1s. In this example, the
2056 will be reported if it is more than 0.1s. In this example, the
2057 actual exponentiation is done by Python at compilation time, so while
2057 actual exponentiation is done by Python at compilation time, so while
2058 the expression can take a noticeable amount of time to compute, that
2058 the expression can take a noticeable amount of time to compute, that
2059 time is purely due to the compilation:
2059 time is purely due to the compilation:
2060
2060
2061 In [5]: time 3**9999;
2061 In [5]: time 3**9999;
2062 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2062 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2063 Wall time: 0.00 s
2063 Wall time: 0.00 s
2064
2064
2065 In [6]: time 3**999999;
2065 In [6]: time 3**999999;
2066 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2066 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2067 Wall time: 0.00 s
2067 Wall time: 0.00 s
2068 Compiler : 0.78 s
2068 Compiler : 0.78 s
2069 """
2069 """
2070
2070
2071 # fail immediately if the given expression can't be compiled
2071 # fail immediately if the given expression can't be compiled
2072
2072
2073 expr = self.shell.prefilter(parameter_s,False)
2073 expr = self.shell.prefilter(parameter_s,False)
2074
2074
2075 # Minimum time above which compilation time will be reported
2075 # Minimum time above which compilation time will be reported
2076 tc_min = 0.1
2076 tc_min = 0.1
2077
2077
2078 try:
2078 try:
2079 mode = 'eval'
2079 mode = 'eval'
2080 t0 = clock()
2080 t0 = clock()
2081 code = compile(expr,'<timed eval>',mode)
2081 code = compile(expr,'<timed eval>',mode)
2082 tc = clock()-t0
2082 tc = clock()-t0
2083 except SyntaxError:
2083 except SyntaxError:
2084 mode = 'exec'
2084 mode = 'exec'
2085 t0 = clock()
2085 t0 = clock()
2086 code = compile(expr,'<timed exec>',mode)
2086 code = compile(expr,'<timed exec>',mode)
2087 tc = clock()-t0
2087 tc = clock()-t0
2088 # skew measurement as little as possible
2088 # skew measurement as little as possible
2089 glob = self.shell.user_ns
2089 glob = self.shell.user_ns
2090 wtime = time.time
2090 wtime = time.time
2091 # time execution
2091 # time execution
2092 wall_st = wtime()
2092 wall_st = wtime()
2093 if mode=='eval':
2093 if mode=='eval':
2094 st = clock2()
2094 st = clock2()
2095 out = eval(code, glob, user_locals)
2095 out = eval(code, glob, user_locals)
2096 end = clock2()
2096 end = clock2()
2097 else:
2097 else:
2098 st = clock2()
2098 st = clock2()
2099 exec code in glob, user_locals
2099 exec code in glob, user_locals
2100 end = clock2()
2100 end = clock2()
2101 out = None
2101 out = None
2102 wall_end = wtime()
2102 wall_end = wtime()
2103 # Compute actual times and report
2103 # Compute actual times and report
2104 wall_time = wall_end-wall_st
2104 wall_time = wall_end-wall_st
2105 cpu_user = end[0]-st[0]
2105 cpu_user = end[0]-st[0]
2106 cpu_sys = end[1]-st[1]
2106 cpu_sys = end[1]-st[1]
2107 cpu_tot = cpu_user+cpu_sys
2107 cpu_tot = cpu_user+cpu_sys
2108 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2108 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2109 (cpu_user,cpu_sys,cpu_tot)
2109 (cpu_user,cpu_sys,cpu_tot)
2110 print "Wall time: %.2f s" % wall_time
2110 print "Wall time: %.2f s" % wall_time
2111 if tc > tc_min:
2111 if tc > tc_min:
2112 print "Compiler : %.2f s" % tc
2112 print "Compiler : %.2f s" % tc
2113 return out
2113 return out
2114
2114
2115 @skip_doctest
2115 @skip_doctest
2116 def magic_macro(self,parameter_s = ''):
2116 def magic_macro(self,parameter_s = ''):
2117 """Define a macro for future re-execution. It accepts ranges of history,
2117 """Define a macro for future re-execution. It accepts ranges of history,
2118 filenames or string objects.
2118 filenames or string objects.
2119
2119
2120 Usage:\\
2120 Usage:\\
2121 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2121 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2122
2122
2123 Options:
2123 Options:
2124
2124
2125 -r: use 'raw' input. By default, the 'processed' history is used,
2125 -r: use 'raw' input. By default, the 'processed' history is used,
2126 so that magics are loaded in their transformed version to valid
2126 so that magics are loaded in their transformed version to valid
2127 Python. If this option is given, the raw input as typed as the
2127 Python. If this option is given, the raw input as typed as the
2128 command line is used instead.
2128 command line is used instead.
2129
2129
2130 This will define a global variable called `name` which is a string
2130 This will define a global variable called `name` which is a string
2131 made of joining the slices and lines you specify (n1,n2,... numbers
2131 made of joining the slices and lines you specify (n1,n2,... numbers
2132 above) from your input history into a single string. This variable
2132 above) from your input history into a single string. This variable
2133 acts like an automatic function which re-executes those lines as if
2133 acts like an automatic function which re-executes those lines as if
2134 you had typed them. You just type 'name' at the prompt and the code
2134 you had typed them. You just type 'name' at the prompt and the code
2135 executes.
2135 executes.
2136
2136
2137 The syntax for indicating input ranges is described in %history.
2137 The syntax for indicating input ranges is described in %history.
2138
2138
2139 Note: as a 'hidden' feature, you can also use traditional python slice
2139 Note: as a 'hidden' feature, you can also use traditional python slice
2140 notation, where N:M means numbers N through M-1.
2140 notation, where N:M means numbers N through M-1.
2141
2141
2142 For example, if your history contains (%hist prints it)::
2142 For example, if your history contains (%hist prints it)::
2143
2143
2144 44: x=1
2144 44: x=1
2145 45: y=3
2145 45: y=3
2146 46: z=x+y
2146 46: z=x+y
2147 47: print x
2147 47: print x
2148 48: a=5
2148 48: a=5
2149 49: print 'x',x,'y',y
2149 49: print 'x',x,'y',y
2150
2150
2151 you can create a macro with lines 44 through 47 (included) and line 49
2151 you can create a macro with lines 44 through 47 (included) and line 49
2152 called my_macro with::
2152 called my_macro with::
2153
2153
2154 In [55]: %macro my_macro 44-47 49
2154 In [55]: %macro my_macro 44-47 49
2155
2155
2156 Now, typing `my_macro` (without quotes) will re-execute all this code
2156 Now, typing `my_macro` (without quotes) will re-execute all this code
2157 in one pass.
2157 in one pass.
2158
2158
2159 You don't need to give the line-numbers in order, and any given line
2159 You don't need to give the line-numbers in order, and any given line
2160 number can appear multiple times. You can assemble macros with any
2160 number can appear multiple times. You can assemble macros with any
2161 lines from your input history in any order.
2161 lines from your input history in any order.
2162
2162
2163 The macro is a simple object which holds its value in an attribute,
2163 The macro is a simple object which holds its value in an attribute,
2164 but IPython's display system checks for macros and executes them as
2164 but IPython's display system checks for macros and executes them as
2165 code instead of printing them when you type their name.
2165 code instead of printing them when you type their name.
2166
2166
2167 You can view a macro's contents by explicitly printing it with::
2167 You can view a macro's contents by explicitly printing it with::
2168
2168
2169 print macro_name
2169 print macro_name
2170
2170
2171 """
2171 """
2172 opts,args = self.parse_options(parameter_s,'r',mode='list')
2172 opts,args = self.parse_options(parameter_s,'r',mode='list')
2173 if not args: # List existing macros
2173 if not args: # List existing macros
2174 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2174 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2175 isinstance(v, Macro))
2175 isinstance(v, Macro))
2176 if len(args) == 1:
2176 if len(args) == 1:
2177 raise UsageError(
2177 raise UsageError(
2178 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2178 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2179 name, codefrom = args[0], " ".join(args[1:])
2179 name, codefrom = args[0], " ".join(args[1:])
2180
2180
2181 #print 'rng',ranges # dbg
2181 #print 'rng',ranges # dbg
2182 try:
2182 try:
2183 lines = self.shell.find_user_code(codefrom, 'r' in opts)
2183 lines = self.shell.find_user_code(codefrom, 'r' in opts)
2184 except (ValueError, TypeError) as e:
2184 except (ValueError, TypeError) as e:
2185 print e.args[0]
2185 print e.args[0]
2186 return
2186 return
2187 macro = Macro(lines)
2187 macro = Macro(lines)
2188 self.shell.define_macro(name, macro)
2188 self.shell.define_macro(name, macro)
2189 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2189 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2190 print '=== Macro contents: ==='
2190 print '=== Macro contents: ==='
2191 print macro,
2191 print macro,
2192
2192
2193 def magic_save(self,parameter_s = ''):
2193 def magic_save(self,parameter_s = ''):
2194 """Save a set of lines or a macro to a given filename.
2194 """Save a set of lines or a macro to a given filename.
2195
2195
2196 Usage:\\
2196 Usage:\\
2197 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2197 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2198
2198
2199 Options:
2199 Options:
2200
2200
2201 -r: use 'raw' input. By default, the 'processed' history is used,
2201 -r: use 'raw' input. By default, the 'processed' history is used,
2202 so that magics are loaded in their transformed version to valid
2202 so that magics are loaded in their transformed version to valid
2203 Python. If this option is given, the raw input as typed as the
2203 Python. If this option is given, the raw input as typed as the
2204 command line is used instead.
2204 command line is used instead.
2205
2205
2206 This function uses the same syntax as %history for input ranges,
2206 This function uses the same syntax as %history for input ranges,
2207 then saves the lines to the filename you specify.
2207 then saves the lines to the filename you specify.
2208
2208
2209 It adds a '.py' extension to the file if you don't do so yourself, and
2209 It adds a '.py' extension to the file if you don't do so yourself, and
2210 it asks for confirmation before overwriting existing files."""
2210 it asks for confirmation before overwriting existing files."""
2211
2211
2212 opts,args = self.parse_options(parameter_s,'r',mode='list')
2212 opts,args = self.parse_options(parameter_s,'r',mode='list')
2213 fname, codefrom = unquote_filename(args[0]), " ".join(args[1:])
2213 fname, codefrom = unquote_filename(args[0]), " ".join(args[1:])
2214 if not fname.endswith('.py'):
2214 if not fname.endswith('.py'):
2215 fname += '.py'
2215 fname += '.py'
2216 if os.path.isfile(fname):
2216 if os.path.isfile(fname):
2217 overwrite = self.shell.ask_yes_no('File `%s` exists. Overwrite (y/[N])? ' % fname, default='n')
2217 overwrite = self.shell.ask_yes_no('File `%s` exists. Overwrite (y/[N])? ' % fname, default='n')
2218 if not overwrite :
2218 if not overwrite :
2219 print 'Operation cancelled.'
2219 print 'Operation cancelled.'
2220 return
2220 return
2221 try:
2221 try:
2222 cmds = self.shell.find_user_code(codefrom, 'r' in opts)
2222 cmds = self.shell.find_user_code(codefrom, 'r' in opts)
2223 except (TypeError, ValueError) as e:
2223 except (TypeError, ValueError) as e:
2224 print e.args[0]
2224 print e.args[0]
2225 return
2225 return
2226 with io.open(fname,'w', encoding="utf-8") as f:
2226 with io.open(fname,'w', encoding="utf-8") as f:
2227 f.write(u"# coding: utf-8\n")
2227 f.write(u"# coding: utf-8\n")
2228 f.write(py3compat.cast_unicode(cmds))
2228 f.write(py3compat.cast_unicode(cmds))
2229 print 'The following commands were written to file `%s`:' % fname
2229 print 'The following commands were written to file `%s`:' % fname
2230 print cmds
2230 print cmds
2231
2231
2232 def magic_pastebin(self, parameter_s = ''):
2232 def magic_pastebin(self, parameter_s = ''):
2233 """Upload code to Github's Gist paste bin, returning the URL.
2233 """Upload code to Github's Gist paste bin, returning the URL.
2234
2234
2235 Usage:\\
2235 Usage:\\
2236 %pastebin [-d "Custom description"] 1-7
2236 %pastebin [-d "Custom description"] 1-7
2237
2237
2238 The argument can be an input history range, a filename, or the name of a
2238 The argument can be an input history range, a filename, or the name of a
2239 string or macro.
2239 string or macro.
2240
2240
2241 Options:
2241 Options:
2242
2242
2243 -d: Pass a custom description for the gist. The default will say
2243 -d: Pass a custom description for the gist. The default will say
2244 "Pasted from IPython".
2244 "Pasted from IPython".
2245 """
2245 """
2246 opts, args = self.parse_options(parameter_s, 'd:')
2246 opts, args = self.parse_options(parameter_s, 'd:')
2247
2247
2248 try:
2248 try:
2249 code = self.shell.find_user_code(args)
2249 code = self.shell.find_user_code(args)
2250 except (ValueError, TypeError) as e:
2250 except (ValueError, TypeError) as e:
2251 print e.args[0]
2251 print e.args[0]
2252 return
2252 return
2253
2253
2254 post_data = json.dumps({
2254 post_data = json.dumps({
2255 "description": opts.get('d', "Pasted from IPython"),
2255 "description": opts.get('d', "Pasted from IPython"),
2256 "public": True,
2256 "public": True,
2257 "files": {
2257 "files": {
2258 "file1.py": {
2258 "file1.py": {
2259 "content": code
2259 "content": code
2260 }
2260 }
2261 }
2261 }
2262 }).encode('utf-8')
2262 }).encode('utf-8')
2263
2263
2264 response = urlopen("https://api.github.com/gists", post_data)
2264 response = urlopen("https://api.github.com/gists", post_data)
2265 response_data = json.loads(response.read().decode('utf-8'))
2265 response_data = json.loads(response.read().decode('utf-8'))
2266 return response_data['html_url']
2266 return response_data['html_url']
2267
2267
2268 def magic_loadpy(self, arg_s):
2268 def magic_loadpy(self, arg_s):
2269 """Alias of `%load`
2269 """Alias of `%load`
2270
2270
2271 `%loadpy` has gained some flexibility and droped the requirement of a `.py`
2271 `%loadpy` has gained some flexibility and droped the requirement of a `.py`
2272 extension. So it has been renamed simply into %load. You can look at
2272 extension. So it has been renamed simply into %load. You can look at
2273 `%load`'s docstring for more info.
2273 `%load`'s docstring for more info.
2274 """
2274 """
2275 self.magic_load(arg_s)
2275 self.magic_load(arg_s)
2276
2276
2277 def magic_load(self, arg_s):
2277 def magic_load(self, arg_s):
2278 """Load code into the current frontend.
2278 """Load code into the current frontend.
2279
2279
2280 Usage:\\
2280 Usage:\\
2281 %load [options] source
2281 %load [options] source
2282
2282
2283 where source can be a filename, URL, input history range or macro
2283 where source can be a filename, URL, input history range or macro
2284
2284
2285 Options:
2285 Options:
2286 --------
2286 --------
2287 -y : Don't ask confirmation for loading source above 200 000 characters.
2287 -y : Don't ask confirmation for loading source above 200 000 characters.
2288
2288
2289 This magic command can either take a local filename, a URL, an history
2289 This magic command can either take a local filename, a URL, an history
2290 range (see %history) or a macro as argument, it will prompt for
2290 range (see %history) or a macro as argument, it will prompt for
2291 confirmation before loading source with more than 200 000 characters, unless
2291 confirmation before loading source with more than 200 000 characters, unless
2292 -y flag is passed or if the frontend does not support raw_input::
2292 -y flag is passed or if the frontend does not support raw_input::
2293
2293
2294 %load myscript.py
2294 %load myscript.py
2295 %load 7-27
2295 %load 7-27
2296 %load myMacro
2296 %load myMacro
2297 %load http://www.example.com/myscript.py
2297 %load http://www.example.com/myscript.py
2298 """
2298 """
2299 opts,args = self.parse_options(arg_s,'y')
2299 opts,args = self.parse_options(arg_s,'y')
2300
2300
2301 contents = self.shell.find_user_code(args)
2301 contents = self.shell.find_user_code(args)
2302 l = len(contents)
2302 l = len(contents)
2303
2303
2304 # 200 000 is ~ 2500 full 80 caracter lines
2304 # 200 000 is ~ 2500 full 80 caracter lines
2305 # so in average, more than 5000 lines
2305 # so in average, more than 5000 lines
2306 if l > 200000 and 'y' not in opts:
2306 if l > 200000 and 'y' not in opts:
2307 try:
2307 try:
2308 ans = self.shell.ask_yes_no(("The text you're trying to load seems pretty big"\
2308 ans = self.shell.ask_yes_no(("The text you're trying to load seems pretty big"\
2309 " (%d characters). Continue (y/[N]) ?" % l), default='n' )
2309 " (%d characters). Continue (y/[N]) ?" % l), default='n' )
2310 except StdinNotImplementedError:
2310 except StdinNotImplementedError:
2311 #asume yes if raw input not implemented
2311 #asume yes if raw input not implemented
2312 ans = True
2312 ans = True
2313
2313
2314 if ans is False :
2314 if ans is False :
2315 print 'Operation cancelled.'
2315 print 'Operation cancelled.'
2316 return
2316 return
2317
2317
2318 self.set_next_input(contents)
2318 self.set_next_input(contents)
2319
2319
2320 def _find_edit_target(self, args, opts, last_call):
2320 def _find_edit_target(self, args, opts, last_call):
2321 """Utility method used by magic_edit to find what to edit."""
2321 """Utility method used by magic_edit to find what to edit."""
2322
2322
2323 def make_filename(arg):
2323 def make_filename(arg):
2324 "Make a filename from the given args"
2324 "Make a filename from the given args"
2325 arg = unquote_filename(arg)
2325 arg = unquote_filename(arg)
2326 try:
2326 try:
2327 filename = get_py_filename(arg)
2327 filename = get_py_filename(arg)
2328 except IOError:
2328 except IOError:
2329 # If it ends with .py but doesn't already exist, assume we want
2329 # If it ends with .py but doesn't already exist, assume we want
2330 # a new file.
2330 # a new file.
2331 if arg.endswith('.py'):
2331 if arg.endswith('.py'):
2332 filename = arg
2332 filename = arg
2333 else:
2333 else:
2334 filename = None
2334 filename = None
2335 return filename
2335 return filename
2336
2336
2337 # Set a few locals from the options for convenience:
2337 # Set a few locals from the options for convenience:
2338 opts_prev = 'p' in opts
2338 opts_prev = 'p' in opts
2339 opts_raw = 'r' in opts
2339 opts_raw = 'r' in opts
2340
2340
2341 # custom exceptions
2341 # custom exceptions
2342 class DataIsObject(Exception): pass
2342 class DataIsObject(Exception): pass
2343
2343
2344 # Default line number value
2344 # Default line number value
2345 lineno = opts.get('n',None)
2345 lineno = opts.get('n',None)
2346
2346
2347 if opts_prev:
2347 if opts_prev:
2348 args = '_%s' % last_call[0]
2348 args = '_%s' % last_call[0]
2349 if not self.shell.user_ns.has_key(args):
2349 if not self.shell.user_ns.has_key(args):
2350 args = last_call[1]
2350 args = last_call[1]
2351
2351
2352 # use last_call to remember the state of the previous call, but don't
2352 # use last_call to remember the state of the previous call, but don't
2353 # let it be clobbered by successive '-p' calls.
2353 # let it be clobbered by successive '-p' calls.
2354 try:
2354 try:
2355 last_call[0] = self.shell.displayhook.prompt_count
2355 last_call[0] = self.shell.displayhook.prompt_count
2356 if not opts_prev:
2356 if not opts_prev:
2357 last_call[1] = args
2357 last_call[1] = args
2358 except:
2358 except:
2359 pass
2359 pass
2360
2360
2361 # by default this is done with temp files, except when the given
2361 # by default this is done with temp files, except when the given
2362 # arg is a filename
2362 # arg is a filename
2363 use_temp = True
2363 use_temp = True
2364
2364
2365 data = ''
2365 data = ''
2366
2366
2367 # First, see if the arguments should be a filename.
2367 # First, see if the arguments should be a filename.
2368 filename = make_filename(args)
2368 filename = make_filename(args)
2369 if filename:
2369 if filename:
2370 use_temp = False
2370 use_temp = False
2371 elif args:
2371 elif args:
2372 # Mode where user specifies ranges of lines, like in %macro.
2372 # Mode where user specifies ranges of lines, like in %macro.
2373 data = self.extract_input_lines(args, opts_raw)
2373 data = self.extract_input_lines(args, opts_raw)
2374 if not data:
2374 if not data:
2375 try:
2375 try:
2376 # Load the parameter given as a variable. If not a string,
2376 # Load the parameter given as a variable. If not a string,
2377 # process it as an object instead (below)
2377 # process it as an object instead (below)
2378
2378
2379 #print '*** args',args,'type',type(args) # dbg
2379 #print '*** args',args,'type',type(args) # dbg
2380 data = eval(args, self.shell.user_ns)
2380 data = eval(args, self.shell.user_ns)
2381 if not isinstance(data, basestring):
2381 if not isinstance(data, basestring):
2382 raise DataIsObject
2382 raise DataIsObject
2383
2383
2384 except (NameError,SyntaxError):
2384 except (NameError,SyntaxError):
2385 # given argument is not a variable, try as a filename
2385 # given argument is not a variable, try as a filename
2386 filename = make_filename(args)
2386 filename = make_filename(args)
2387 if filename is None:
2387 if filename is None:
2388 warn("Argument given (%s) can't be found as a variable "
2388 warn("Argument given (%s) can't be found as a variable "
2389 "or as a filename." % args)
2389 "or as a filename." % args)
2390 return
2390 return
2391 use_temp = False
2391 use_temp = False
2392
2392
2393 except DataIsObject:
2393 except DataIsObject:
2394 # macros have a special edit function
2394 # macros have a special edit function
2395 if isinstance(data, Macro):
2395 if isinstance(data, Macro):
2396 raise MacroToEdit(data)
2396 raise MacroToEdit(data)
2397
2397
2398 # For objects, try to edit the file where they are defined
2398 # For objects, try to edit the file where they are defined
2399 try:
2399 try:
2400 filename = inspect.getabsfile(data)
2400 filename = inspect.getabsfile(data)
2401 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2401 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2402 # class created by %edit? Try to find source
2402 # class created by %edit? Try to find source
2403 # by looking for method definitions instead, the
2403 # by looking for method definitions instead, the
2404 # __module__ in those classes is FakeModule.
2404 # __module__ in those classes is FakeModule.
2405 attrs = [getattr(data, aname) for aname in dir(data)]
2405 attrs = [getattr(data, aname) for aname in dir(data)]
2406 for attr in attrs:
2406 for attr in attrs:
2407 if not inspect.ismethod(attr):
2407 if not inspect.ismethod(attr):
2408 continue
2408 continue
2409 filename = inspect.getabsfile(attr)
2409 filename = inspect.getabsfile(attr)
2410 if filename and 'fakemodule' not in filename.lower():
2410 if filename and 'fakemodule' not in filename.lower():
2411 # change the attribute to be the edit target instead
2411 # change the attribute to be the edit target instead
2412 data = attr
2412 data = attr
2413 break
2413 break
2414
2414
2415 datafile = 1
2415 datafile = 1
2416 except TypeError:
2416 except TypeError:
2417 filename = make_filename(args)
2417 filename = make_filename(args)
2418 datafile = 1
2418 datafile = 1
2419 warn('Could not find file where `%s` is defined.\n'
2419 warn('Could not find file where `%s` is defined.\n'
2420 'Opening a file named `%s`' % (args,filename))
2420 'Opening a file named `%s`' % (args,filename))
2421 # Now, make sure we can actually read the source (if it was in
2421 # Now, make sure we can actually read the source (if it was in
2422 # a temp file it's gone by now).
2422 # a temp file it's gone by now).
2423 if datafile:
2423 if datafile:
2424 try:
2424 try:
2425 if lineno is None:
2425 if lineno is None:
2426 lineno = inspect.getsourcelines(data)[1]
2426 lineno = inspect.getsourcelines(data)[1]
2427 except IOError:
2427 except IOError:
2428 filename = make_filename(args)
2428 filename = make_filename(args)
2429 if filename is None:
2429 if filename is None:
2430 warn('The file `%s` where `%s` was defined cannot '
2430 warn('The file `%s` where `%s` was defined cannot '
2431 'be read.' % (filename,data))
2431 'be read.' % (filename,data))
2432 return
2432 return
2433 use_temp = False
2433 use_temp = False
2434
2434
2435 if use_temp:
2435 if use_temp:
2436 filename = self.shell.mktempfile(data)
2436 filename = self.shell.mktempfile(data)
2437 print 'IPython will make a temporary file named:',filename
2437 print 'IPython will make a temporary file named:',filename
2438
2438
2439 return filename, lineno, use_temp
2439 return filename, lineno, use_temp
2440
2440
2441 def _edit_macro(self,mname,macro):
2441 def _edit_macro(self,mname,macro):
2442 """open an editor with the macro data in a file"""
2442 """open an editor with the macro data in a file"""
2443 filename = self.shell.mktempfile(macro.value)
2443 filename = self.shell.mktempfile(macro.value)
2444 self.shell.hooks.editor(filename)
2444 self.shell.hooks.editor(filename)
2445
2445
2446 # and make a new macro object, to replace the old one
2446 # and make a new macro object, to replace the old one
2447 mfile = open(filename)
2447 mfile = open(filename)
2448 mvalue = mfile.read()
2448 mvalue = mfile.read()
2449 mfile.close()
2449 mfile.close()
2450 self.shell.user_ns[mname] = Macro(mvalue)
2450 self.shell.user_ns[mname] = Macro(mvalue)
2451
2451
2452 def magic_ed(self,parameter_s=''):
2452 def magic_ed(self,parameter_s=''):
2453 """Alias to %edit."""
2453 """Alias to %edit."""
2454 return self.magic_edit(parameter_s)
2454 return self.magic_edit(parameter_s)
2455
2455
2456 @skip_doctest
2456 @skip_doctest
2457 def magic_edit(self,parameter_s='',last_call=['','']):
2457 def magic_edit(self,parameter_s='',last_call=['','']):
2458 """Bring up an editor and execute the resulting code.
2458 """Bring up an editor and execute the resulting code.
2459
2459
2460 Usage:
2460 Usage:
2461 %edit [options] [args]
2461 %edit [options] [args]
2462
2462
2463 %edit runs IPython's editor hook. The default version of this hook is
2463 %edit runs IPython's editor hook. The default version of this hook is
2464 set to call the editor specified by your $EDITOR environment variable.
2464 set to call the editor specified by your $EDITOR environment variable.
2465 If this isn't found, it will default to vi under Linux/Unix and to
2465 If this isn't found, it will default to vi under Linux/Unix and to
2466 notepad under Windows. See the end of this docstring for how to change
2466 notepad under Windows. See the end of this docstring for how to change
2467 the editor hook.
2467 the editor hook.
2468
2468
2469 You can also set the value of this editor via the
2469 You can also set the value of this editor via the
2470 ``TerminalInteractiveShell.editor`` option in your configuration file.
2470 ``TerminalInteractiveShell.editor`` option in your configuration file.
2471 This is useful if you wish to use a different editor from your typical
2471 This is useful if you wish to use a different editor from your typical
2472 default with IPython (and for Windows users who typically don't set
2472 default with IPython (and for Windows users who typically don't set
2473 environment variables).
2473 environment variables).
2474
2474
2475 This command allows you to conveniently edit multi-line code right in
2475 This command allows you to conveniently edit multi-line code right in
2476 your IPython session.
2476 your IPython session.
2477
2477
2478 If called without arguments, %edit opens up an empty editor with a
2478 If called without arguments, %edit opens up an empty editor with a
2479 temporary file and will execute the contents of this file when you
2479 temporary file and will execute the contents of this file when you
2480 close it (don't forget to save it!).
2480 close it (don't forget to save it!).
2481
2481
2482
2482
2483 Options:
2483 Options:
2484
2484
2485 -n <number>: open the editor at a specified line number. By default,
2485 -n <number>: open the editor at a specified line number. By default,
2486 the IPython editor hook uses the unix syntax 'editor +N filename', but
2486 the IPython editor hook uses the unix syntax 'editor +N filename', but
2487 you can configure this by providing your own modified hook if your
2487 you can configure this by providing your own modified hook if your
2488 favorite editor supports line-number specifications with a different
2488 favorite editor supports line-number specifications with a different
2489 syntax.
2489 syntax.
2490
2490
2491 -p: this will call the editor with the same data as the previous time
2491 -p: this will call the editor with the same data as the previous time
2492 it was used, regardless of how long ago (in your current session) it
2492 it was used, regardless of how long ago (in your current session) it
2493 was.
2493 was.
2494
2494
2495 -r: use 'raw' input. This option only applies to input taken from the
2495 -r: use 'raw' input. This option only applies to input taken from the
2496 user's history. By default, the 'processed' history is used, so that
2496 user's history. By default, the 'processed' history is used, so that
2497 magics are loaded in their transformed version to valid Python. If
2497 magics are loaded in their transformed version to valid Python. If
2498 this option is given, the raw input as typed as the command line is
2498 this option is given, the raw input as typed as the command line is
2499 used instead. When you exit the editor, it will be executed by
2499 used instead. When you exit the editor, it will be executed by
2500 IPython's own processor.
2500 IPython's own processor.
2501
2501
2502 -x: do not execute the edited code immediately upon exit. This is
2502 -x: do not execute the edited code immediately upon exit. This is
2503 mainly useful if you are editing programs which need to be called with
2503 mainly useful if you are editing programs which need to be called with
2504 command line arguments, which you can then do using %run.
2504 command line arguments, which you can then do using %run.
2505
2505
2506
2506
2507 Arguments:
2507 Arguments:
2508
2508
2509 If arguments are given, the following possibilities exist:
2509 If arguments are given, the following possibilities exist:
2510
2510
2511 - If the argument is a filename, IPython will load that into the
2511 - If the argument is a filename, IPython will load that into the
2512 editor. It will execute its contents with execfile() when you exit,
2512 editor. It will execute its contents with execfile() when you exit,
2513 loading any code in the file into your interactive namespace.
2513 loading any code in the file into your interactive namespace.
2514
2514
2515 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
2515 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
2516 The syntax is the same as in the %history magic.
2516 The syntax is the same as in the %history magic.
2517
2517
2518 - If the argument is a string variable, its contents are loaded
2518 - If the argument is a string variable, its contents are loaded
2519 into the editor. You can thus edit any string which contains
2519 into the editor. You can thus edit any string which contains
2520 python code (including the result of previous edits).
2520 python code (including the result of previous edits).
2521
2521
2522 - If the argument is the name of an object (other than a string),
2522 - If the argument is the name of an object (other than a string),
2523 IPython will try to locate the file where it was defined and open the
2523 IPython will try to locate the file where it was defined and open the
2524 editor at the point where it is defined. You can use `%edit function`
2524 editor at the point where it is defined. You can use `%edit function`
2525 to load an editor exactly at the point where 'function' is defined,
2525 to load an editor exactly at the point where 'function' is defined,
2526 edit it and have the file be executed automatically.
2526 edit it and have the file be executed automatically.
2527
2527
2528 - If the object is a macro (see %macro for details), this opens up your
2528 - If the object is a macro (see %macro for details), this opens up your
2529 specified editor with a temporary file containing the macro's data.
2529 specified editor with a temporary file containing the macro's data.
2530 Upon exit, the macro is reloaded with the contents of the file.
2530 Upon exit, the macro is reloaded with the contents of the file.
2531
2531
2532 Note: opening at an exact line is only supported under Unix, and some
2532 Note: opening at an exact line is only supported under Unix, and some
2533 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2533 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2534 '+NUMBER' parameter necessary for this feature. Good editors like
2534 '+NUMBER' parameter necessary for this feature. Good editors like
2535 (X)Emacs, vi, jed, pico and joe all do.
2535 (X)Emacs, vi, jed, pico and joe all do.
2536
2536
2537 After executing your code, %edit will return as output the code you
2537 After executing your code, %edit will return as output the code you
2538 typed in the editor (except when it was an existing file). This way
2538 typed in the editor (except when it was an existing file). This way
2539 you can reload the code in further invocations of %edit as a variable,
2539 you can reload the code in further invocations of %edit as a variable,
2540 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2540 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2541 the output.
2541 the output.
2542
2542
2543 Note that %edit is also available through the alias %ed.
2543 Note that %edit is also available through the alias %ed.
2544
2544
2545 This is an example of creating a simple function inside the editor and
2545 This is an example of creating a simple function inside the editor and
2546 then modifying it. First, start up the editor::
2546 then modifying it. First, start up the editor::
2547
2547
2548 In [1]: ed
2548 In [1]: ed
2549 Editing... done. Executing edited code...
2549 Editing... done. Executing edited code...
2550 Out[1]: 'def foo():\\n print "foo() was defined in an editing
2550 Out[1]: 'def foo():\\n print "foo() was defined in an editing
2551 session"\\n'
2551 session"\\n'
2552
2552
2553 We can then call the function foo()::
2553 We can then call the function foo()::
2554
2554
2555 In [2]: foo()
2555 In [2]: foo()
2556 foo() was defined in an editing session
2556 foo() was defined in an editing session
2557
2557
2558 Now we edit foo. IPython automatically loads the editor with the
2558 Now we edit foo. IPython automatically loads the editor with the
2559 (temporary) file where foo() was previously defined::
2559 (temporary) file where foo() was previously defined::
2560
2560
2561 In [3]: ed foo
2561 In [3]: ed foo
2562 Editing... done. Executing edited code...
2562 Editing... done. Executing edited code...
2563
2563
2564 And if we call foo() again we get the modified version::
2564 And if we call foo() again we get the modified version::
2565
2565
2566 In [4]: foo()
2566 In [4]: foo()
2567 foo() has now been changed!
2567 foo() has now been changed!
2568
2568
2569 Here is an example of how to edit a code snippet successive
2569 Here is an example of how to edit a code snippet successive
2570 times. First we call the editor::
2570 times. First we call the editor::
2571
2571
2572 In [5]: ed
2572 In [5]: ed
2573 Editing... done. Executing edited code...
2573 Editing... done. Executing edited code...
2574 hello
2574 hello
2575 Out[5]: "print 'hello'\\n"
2575 Out[5]: "print 'hello'\\n"
2576
2576
2577 Now we call it again with the previous output (stored in _)::
2577 Now we call it again with the previous output (stored in _)::
2578
2578
2579 In [6]: ed _
2579 In [6]: ed _
2580 Editing... done. Executing edited code...
2580 Editing... done. Executing edited code...
2581 hello world
2581 hello world
2582 Out[6]: "print 'hello world'\\n"
2582 Out[6]: "print 'hello world'\\n"
2583
2583
2584 Now we call it with the output #8 (stored in _8, also as Out[8])::
2584 Now we call it with the output #8 (stored in _8, also as Out[8])::
2585
2585
2586 In [7]: ed _8
2586 In [7]: ed _8
2587 Editing... done. Executing edited code...
2587 Editing... done. Executing edited code...
2588 hello again
2588 hello again
2589 Out[7]: "print 'hello again'\\n"
2589 Out[7]: "print 'hello again'\\n"
2590
2590
2591
2591
2592 Changing the default editor hook:
2592 Changing the default editor hook:
2593
2593
2594 If you wish to write your own editor hook, you can put it in a
2594 If you wish to write your own editor hook, you can put it in a
2595 configuration file which you load at startup time. The default hook
2595 configuration file which you load at startup time. The default hook
2596 is defined in the IPython.core.hooks module, and you can use that as a
2596 is defined in the IPython.core.hooks module, and you can use that as a
2597 starting example for further modifications. That file also has
2597 starting example for further modifications. That file also has
2598 general instructions on how to set a new hook for use once you've
2598 general instructions on how to set a new hook for use once you've
2599 defined it."""
2599 defined it."""
2600 opts,args = self.parse_options(parameter_s,'prxn:')
2600 opts,args = self.parse_options(parameter_s,'prxn:')
2601
2601
2602 try:
2602 try:
2603 filename, lineno, is_temp = self._find_edit_target(args, opts, last_call)
2603 filename, lineno, is_temp = self._find_edit_target(args, opts, last_call)
2604 except MacroToEdit as e:
2604 except MacroToEdit as e:
2605 self._edit_macro(args, e.args[0])
2605 self._edit_macro(args, e.args[0])
2606 return
2606 return
2607
2607
2608 # do actual editing here
2608 # do actual editing here
2609 print 'Editing...',
2609 print 'Editing...',
2610 sys.stdout.flush()
2610 sys.stdout.flush()
2611 try:
2611 try:
2612 # Quote filenames that may have spaces in them
2612 # Quote filenames that may have spaces in them
2613 if ' ' in filename:
2613 if ' ' in filename:
2614 filename = "'%s'" % filename
2614 filename = "'%s'" % filename
2615 self.shell.hooks.editor(filename,lineno)
2615 self.shell.hooks.editor(filename,lineno)
2616 except TryNext:
2616 except TryNext:
2617 warn('Could not open editor')
2617 warn('Could not open editor')
2618 return
2618 return
2619
2619
2620 # XXX TODO: should this be generalized for all string vars?
2620 # XXX TODO: should this be generalized for all string vars?
2621 # For now, this is special-cased to blocks created by cpaste
2621 # For now, this is special-cased to blocks created by cpaste
2622 if args.strip() == 'pasted_block':
2622 if args.strip() == 'pasted_block':
2623 self.shell.user_ns['pasted_block'] = file_read(filename)
2623 self.shell.user_ns['pasted_block'] = file_read(filename)
2624
2624
2625 if 'x' in opts: # -x prevents actual execution
2625 if 'x' in opts: # -x prevents actual execution
2626 print
2626 print
2627 else:
2627 else:
2628 print 'done. Executing edited code...'
2628 print 'done. Executing edited code...'
2629 if 'r' in opts: # Untranslated IPython code
2629 if 'r' in opts: # Untranslated IPython code
2630 self.shell.run_cell(file_read(filename),
2630 self.shell.run_cell(file_read(filename),
2631 store_history=False)
2631 store_history=False)
2632 else:
2632 else:
2633 self.shell.safe_execfile(filename,self.shell.user_ns,
2633 self.shell.safe_execfile(filename, self.shell.user_ns,
2634 self.shell.user_ns)
2634 self.shell.user_ns)
2635
2635
2636 if is_temp:
2636 if is_temp:
2637 try:
2637 try:
2638 return open(filename).read()
2638 return open(filename).read()
2639 except IOError,msg:
2639 except IOError,msg:
2640 if msg.filename == filename:
2640 if msg.filename == filename:
2641 warn('File not found. Did you forget to save?')
2641 warn('File not found. Did you forget to save?')
2642 return
2642 return
2643 else:
2643 else:
2644 self.shell.showtraceback()
2644 self.shell.showtraceback()
2645
2645
2646 def magic_xmode(self,parameter_s = ''):
2646 def magic_xmode(self,parameter_s = ''):
2647 """Switch modes for the exception handlers.
2647 """Switch modes for the exception handlers.
2648
2648
2649 Valid modes: Plain, Context and Verbose.
2649 Valid modes: Plain, Context and Verbose.
2650
2650
2651 If called without arguments, acts as a toggle."""
2651 If called without arguments, acts as a toggle."""
2652
2652
2653 def xmode_switch_err(name):
2653 def xmode_switch_err(name):
2654 warn('Error changing %s exception modes.\n%s' %
2654 warn('Error changing %s exception modes.\n%s' %
2655 (name,sys.exc_info()[1]))
2655 (name,sys.exc_info()[1]))
2656
2656
2657 shell = self.shell
2657 shell = self.shell
2658 new_mode = parameter_s.strip().capitalize()
2658 new_mode = parameter_s.strip().capitalize()
2659 try:
2659 try:
2660 shell.InteractiveTB.set_mode(mode=new_mode)
2660 shell.InteractiveTB.set_mode(mode=new_mode)
2661 print 'Exception reporting mode:',shell.InteractiveTB.mode
2661 print 'Exception reporting mode:',shell.InteractiveTB.mode
2662 except:
2662 except:
2663 xmode_switch_err('user')
2663 xmode_switch_err('user')
2664
2664
2665 def magic_colors(self,parameter_s = ''):
2665 def magic_colors(self,parameter_s = ''):
2666 """Switch color scheme for prompts, info system and exception handlers.
2666 """Switch color scheme for prompts, info system and exception handlers.
2667
2667
2668 Currently implemented schemes: NoColor, Linux, LightBG.
2668 Currently implemented schemes: NoColor, Linux, LightBG.
2669
2669
2670 Color scheme names are not case-sensitive.
2670 Color scheme names are not case-sensitive.
2671
2671
2672 Examples
2672 Examples
2673 --------
2673 --------
2674 To get a plain black and white terminal::
2674 To get a plain black and white terminal::
2675
2675
2676 %colors nocolor
2676 %colors nocolor
2677 """
2677 """
2678
2678
2679 def color_switch_err(name):
2679 def color_switch_err(name):
2680 warn('Error changing %s color schemes.\n%s' %
2680 warn('Error changing %s color schemes.\n%s' %
2681 (name,sys.exc_info()[1]))
2681 (name,sys.exc_info()[1]))
2682
2682
2683
2683
2684 new_scheme = parameter_s.strip()
2684 new_scheme = parameter_s.strip()
2685 if not new_scheme:
2685 if not new_scheme:
2686 raise UsageError(
2686 raise UsageError(
2687 "%colors: you must specify a color scheme. See '%colors?'")
2687 "%colors: you must specify a color scheme. See '%colors?'")
2688 return
2688 return
2689 # local shortcut
2689 # local shortcut
2690 shell = self.shell
2690 shell = self.shell
2691
2691
2692 import IPython.utils.rlineimpl as readline
2692 import IPython.utils.rlineimpl as readline
2693
2693
2694 if not shell.colors_force and \
2694 if not shell.colors_force and \
2695 not readline.have_readline and sys.platform == "win32":
2695 not readline.have_readline and sys.platform == "win32":
2696 msg = """\
2696 msg = """\
2697 Proper color support under MS Windows requires the pyreadline library.
2697 Proper color support under MS Windows requires the pyreadline library.
2698 You can find it at:
2698 You can find it at:
2699 http://ipython.org/pyreadline.html
2699 http://ipython.org/pyreadline.html
2700 Gary's readline needs the ctypes module, from:
2700 Gary's readline needs the ctypes module, from:
2701 http://starship.python.net/crew/theller/ctypes
2701 http://starship.python.net/crew/theller/ctypes
2702 (Note that ctypes is already part of Python versions 2.5 and newer).
2702 (Note that ctypes is already part of Python versions 2.5 and newer).
2703
2703
2704 Defaulting color scheme to 'NoColor'"""
2704 Defaulting color scheme to 'NoColor'"""
2705 new_scheme = 'NoColor'
2705 new_scheme = 'NoColor'
2706 warn(msg)
2706 warn(msg)
2707
2707
2708 # readline option is 0
2708 # readline option is 0
2709 if not shell.colors_force and not shell.has_readline:
2709 if not shell.colors_force and not shell.has_readline:
2710 new_scheme = 'NoColor'
2710 new_scheme = 'NoColor'
2711
2711
2712 # Set prompt colors
2712 # Set prompt colors
2713 try:
2713 try:
2714 shell.prompt_manager.color_scheme = new_scheme
2714 shell.prompt_manager.color_scheme = new_scheme
2715 except:
2715 except:
2716 color_switch_err('prompt')
2716 color_switch_err('prompt')
2717 else:
2717 else:
2718 shell.colors = \
2718 shell.colors = \
2719 shell.prompt_manager.color_scheme_table.active_scheme_name
2719 shell.prompt_manager.color_scheme_table.active_scheme_name
2720 # Set exception colors
2720 # Set exception colors
2721 try:
2721 try:
2722 shell.InteractiveTB.set_colors(scheme = new_scheme)
2722 shell.InteractiveTB.set_colors(scheme = new_scheme)
2723 shell.SyntaxTB.set_colors(scheme = new_scheme)
2723 shell.SyntaxTB.set_colors(scheme = new_scheme)
2724 except:
2724 except:
2725 color_switch_err('exception')
2725 color_switch_err('exception')
2726
2726
2727 # Set info (for 'object?') colors
2727 # Set info (for 'object?') colors
2728 if shell.color_info:
2728 if shell.color_info:
2729 try:
2729 try:
2730 shell.inspector.set_active_scheme(new_scheme)
2730 shell.inspector.set_active_scheme(new_scheme)
2731 except:
2731 except:
2732 color_switch_err('object inspector')
2732 color_switch_err('object inspector')
2733 else:
2733 else:
2734 shell.inspector.set_active_scheme('NoColor')
2734 shell.inspector.set_active_scheme('NoColor')
2735
2735
2736 def magic_pprint(self, parameter_s=''):
2736 def magic_pprint(self, parameter_s=''):
2737 """Toggle pretty printing on/off."""
2737 """Toggle pretty printing on/off."""
2738 ptformatter = self.shell.display_formatter.formatters['text/plain']
2738 ptformatter = self.shell.display_formatter.formatters['text/plain']
2739 ptformatter.pprint = bool(1 - ptformatter.pprint)
2739 ptformatter.pprint = bool(1 - ptformatter.pprint)
2740 print 'Pretty printing has been turned', \
2740 print 'Pretty printing has been turned', \
2741 ['OFF','ON'][ptformatter.pprint]
2741 ['OFF','ON'][ptformatter.pprint]
2742
2742
2743 #......................................................................
2743 #......................................................................
2744 # Functions to implement unix shell-type things
2744 # Functions to implement unix shell-type things
2745
2745
2746 @skip_doctest
2746 @skip_doctest
2747 def magic_alias(self, parameter_s = ''):
2747 def magic_alias(self, parameter_s = ''):
2748 """Define an alias for a system command.
2748 """Define an alias for a system command.
2749
2749
2750 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2750 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2751
2751
2752 Then, typing 'alias_name params' will execute the system command 'cmd
2752 Then, typing 'alias_name params' will execute the system command 'cmd
2753 params' (from your underlying operating system).
2753 params' (from your underlying operating system).
2754
2754
2755 Aliases have lower precedence than magic functions and Python normal
2755 Aliases have lower precedence than magic functions and Python normal
2756 variables, so if 'foo' is both a Python variable and an alias, the
2756 variables, so if 'foo' is both a Python variable and an alias, the
2757 alias can not be executed until 'del foo' removes the Python variable.
2757 alias can not be executed until 'del foo' removes the Python variable.
2758
2758
2759 You can use the %l specifier in an alias definition to represent the
2759 You can use the %l specifier in an alias definition to represent the
2760 whole line when the alias is called. For example::
2760 whole line when the alias is called. For example::
2761
2761
2762 In [2]: alias bracket echo "Input in brackets: <%l>"
2762 In [2]: alias bracket echo "Input in brackets: <%l>"
2763 In [3]: bracket hello world
2763 In [3]: bracket hello world
2764 Input in brackets: <hello world>
2764 Input in brackets: <hello world>
2765
2765
2766 You can also define aliases with parameters using %s specifiers (one
2766 You can also define aliases with parameters using %s specifiers (one
2767 per parameter)::
2767 per parameter)::
2768
2768
2769 In [1]: alias parts echo first %s second %s
2769 In [1]: alias parts echo first %s second %s
2770 In [2]: %parts A B
2770 In [2]: %parts A B
2771 first A second B
2771 first A second B
2772 In [3]: %parts A
2772 In [3]: %parts A
2773 Incorrect number of arguments: 2 expected.
2773 Incorrect number of arguments: 2 expected.
2774 parts is an alias to: 'echo first %s second %s'
2774 parts is an alias to: 'echo first %s second %s'
2775
2775
2776 Note that %l and %s are mutually exclusive. You can only use one or
2776 Note that %l and %s are mutually exclusive. You can only use one or
2777 the other in your aliases.
2777 the other in your aliases.
2778
2778
2779 Aliases expand Python variables just like system calls using ! or !!
2779 Aliases expand Python variables just like system calls using ! or !!
2780 do: all expressions prefixed with '$' get expanded. For details of
2780 do: all expressions prefixed with '$' get expanded. For details of
2781 the semantic rules, see PEP-215:
2781 the semantic rules, see PEP-215:
2782 http://www.python.org/peps/pep-0215.html. This is the library used by
2782 http://www.python.org/peps/pep-0215.html. This is the library used by
2783 IPython for variable expansion. If you want to access a true shell
2783 IPython for variable expansion. If you want to access a true shell
2784 variable, an extra $ is necessary to prevent its expansion by
2784 variable, an extra $ is necessary to prevent its expansion by
2785 IPython::
2785 IPython::
2786
2786
2787 In [6]: alias show echo
2787 In [6]: alias show echo
2788 In [7]: PATH='A Python string'
2788 In [7]: PATH='A Python string'
2789 In [8]: show $PATH
2789 In [8]: show $PATH
2790 A Python string
2790 A Python string
2791 In [9]: show $$PATH
2791 In [9]: show $$PATH
2792 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2792 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2793
2793
2794 You can use the alias facility to acess all of $PATH. See the %rehash
2794 You can use the alias facility to acess all of $PATH. See the %rehash
2795 and %rehashx functions, which automatically create aliases for the
2795 and %rehashx functions, which automatically create aliases for the
2796 contents of your $PATH.
2796 contents of your $PATH.
2797
2797
2798 If called with no parameters, %alias prints the current alias table."""
2798 If called with no parameters, %alias prints the current alias table."""
2799
2799
2800 par = parameter_s.strip()
2800 par = parameter_s.strip()
2801 if not par:
2801 if not par:
2802 stored = self.shell.db.get('stored_aliases', {} )
2802 stored = self.shell.db.get('stored_aliases', {} )
2803 aliases = sorted(self.shell.alias_manager.aliases)
2803 aliases = sorted(self.shell.alias_manager.aliases)
2804 # for k, v in stored:
2804 # for k, v in stored:
2805 # atab.append(k, v[0])
2805 # atab.append(k, v[0])
2806
2806
2807 print "Total number of aliases:", len(aliases)
2807 print "Total number of aliases:", len(aliases)
2808 sys.stdout.flush()
2808 sys.stdout.flush()
2809 return aliases
2809 return aliases
2810
2810
2811 # Now try to define a new one
2811 # Now try to define a new one
2812 try:
2812 try:
2813 alias,cmd = par.split(None, 1)
2813 alias,cmd = par.split(None, 1)
2814 except:
2814 except:
2815 print oinspect.getdoc(self.magic_alias)
2815 print oinspect.getdoc(self.magic_alias)
2816 else:
2816 else:
2817 self.shell.alias_manager.soft_define_alias(alias, cmd)
2817 self.shell.alias_manager.soft_define_alias(alias, cmd)
2818 # end magic_alias
2818 # end magic_alias
2819
2819
2820 def magic_unalias(self, parameter_s = ''):
2820 def magic_unalias(self, parameter_s = ''):
2821 """Remove an alias"""
2821 """Remove an alias"""
2822
2822
2823 aname = parameter_s.strip()
2823 aname = parameter_s.strip()
2824 self.shell.alias_manager.undefine_alias(aname)
2824 self.shell.alias_manager.undefine_alias(aname)
2825 stored = self.shell.db.get('stored_aliases', {} )
2825 stored = self.shell.db.get('stored_aliases', {} )
2826 if aname in stored:
2826 if aname in stored:
2827 print "Removing %stored alias",aname
2827 print "Removing %stored alias",aname
2828 del stored[aname]
2828 del stored[aname]
2829 self.shell.db['stored_aliases'] = stored
2829 self.shell.db['stored_aliases'] = stored
2830
2830
2831 def magic_rehashx(self, parameter_s = ''):
2831 def magic_rehashx(self, parameter_s = ''):
2832 """Update the alias table with all executable files in $PATH.
2832 """Update the alias table with all executable files in $PATH.
2833
2833
2834 This version explicitly checks that every entry in $PATH is a file
2834 This version explicitly checks that every entry in $PATH is a file
2835 with execute access (os.X_OK), so it is much slower than %rehash.
2835 with execute access (os.X_OK), so it is much slower than %rehash.
2836
2836
2837 Under Windows, it checks executability as a match against a
2837 Under Windows, it checks executability as a match against a
2838 '|'-separated string of extensions, stored in the IPython config
2838 '|'-separated string of extensions, stored in the IPython config
2839 variable win_exec_ext. This defaults to 'exe|com|bat'.
2839 variable win_exec_ext. This defaults to 'exe|com|bat'.
2840
2840
2841 This function also resets the root module cache of module completer,
2841 This function also resets the root module cache of module completer,
2842 used on slow filesystems.
2842 used on slow filesystems.
2843 """
2843 """
2844 from IPython.core.alias import InvalidAliasError
2844 from IPython.core.alias import InvalidAliasError
2845
2845
2846 # for the benefit of module completer in ipy_completers.py
2846 # for the benefit of module completer in ipy_completers.py
2847 del self.shell.db['rootmodules']
2847 del self.shell.db['rootmodules']
2848
2848
2849 path = [os.path.abspath(os.path.expanduser(p)) for p in
2849 path = [os.path.abspath(os.path.expanduser(p)) for p in
2850 os.environ.get('PATH','').split(os.pathsep)]
2850 os.environ.get('PATH','').split(os.pathsep)]
2851 path = filter(os.path.isdir,path)
2851 path = filter(os.path.isdir,path)
2852
2852
2853 syscmdlist = []
2853 syscmdlist = []
2854 # Now define isexec in a cross platform manner.
2854 # Now define isexec in a cross platform manner.
2855 if os.name == 'posix':
2855 if os.name == 'posix':
2856 isexec = lambda fname:os.path.isfile(fname) and \
2856 isexec = lambda fname:os.path.isfile(fname) and \
2857 os.access(fname,os.X_OK)
2857 os.access(fname,os.X_OK)
2858 else:
2858 else:
2859 try:
2859 try:
2860 winext = os.environ['pathext'].replace(';','|').replace('.','')
2860 winext = os.environ['pathext'].replace(';','|').replace('.','')
2861 except KeyError:
2861 except KeyError:
2862 winext = 'exe|com|bat|py'
2862 winext = 'exe|com|bat|py'
2863 if 'py' not in winext:
2863 if 'py' not in winext:
2864 winext += '|py'
2864 winext += '|py'
2865 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2865 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2866 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2866 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2867 savedir = os.getcwdu()
2867 savedir = os.getcwdu()
2868
2868
2869 # Now walk the paths looking for executables to alias.
2869 # Now walk the paths looking for executables to alias.
2870 try:
2870 try:
2871 # write the whole loop for posix/Windows so we don't have an if in
2871 # write the whole loop for posix/Windows so we don't have an if in
2872 # the innermost part
2872 # the innermost part
2873 if os.name == 'posix':
2873 if os.name == 'posix':
2874 for pdir in path:
2874 for pdir in path:
2875 os.chdir(pdir)
2875 os.chdir(pdir)
2876 for ff in os.listdir(pdir):
2876 for ff in os.listdir(pdir):
2877 if isexec(ff):
2877 if isexec(ff):
2878 try:
2878 try:
2879 # Removes dots from the name since ipython
2879 # Removes dots from the name since ipython
2880 # will assume names with dots to be python.
2880 # will assume names with dots to be python.
2881 self.shell.alias_manager.define_alias(
2881 self.shell.alias_manager.define_alias(
2882 ff.replace('.',''), ff)
2882 ff.replace('.',''), ff)
2883 except InvalidAliasError:
2883 except InvalidAliasError:
2884 pass
2884 pass
2885 else:
2885 else:
2886 syscmdlist.append(ff)
2886 syscmdlist.append(ff)
2887 else:
2887 else:
2888 no_alias = self.shell.alias_manager.no_alias
2888 no_alias = self.shell.alias_manager.no_alias
2889 for pdir in path:
2889 for pdir in path:
2890 os.chdir(pdir)
2890 os.chdir(pdir)
2891 for ff in os.listdir(pdir):
2891 for ff in os.listdir(pdir):
2892 base, ext = os.path.splitext(ff)
2892 base, ext = os.path.splitext(ff)
2893 if isexec(ff) and base.lower() not in no_alias:
2893 if isexec(ff) and base.lower() not in no_alias:
2894 if ext.lower() == '.exe':
2894 if ext.lower() == '.exe':
2895 ff = base
2895 ff = base
2896 try:
2896 try:
2897 # Removes dots from the name since ipython
2897 # Removes dots from the name since ipython
2898 # will assume names with dots to be python.
2898 # will assume names with dots to be python.
2899 self.shell.alias_manager.define_alias(
2899 self.shell.alias_manager.define_alias(
2900 base.lower().replace('.',''), ff)
2900 base.lower().replace('.',''), ff)
2901 except InvalidAliasError:
2901 except InvalidAliasError:
2902 pass
2902 pass
2903 syscmdlist.append(ff)
2903 syscmdlist.append(ff)
2904 self.shell.db['syscmdlist'] = syscmdlist
2904 self.shell.db['syscmdlist'] = syscmdlist
2905 finally:
2905 finally:
2906 os.chdir(savedir)
2906 os.chdir(savedir)
2907
2907
2908 @skip_doctest
2908 @skip_doctest
2909 def magic_pwd(self, parameter_s = ''):
2909 def magic_pwd(self, parameter_s = ''):
2910 """Return the current working directory path.
2910 """Return the current working directory path.
2911
2911
2912 Examples
2912 Examples
2913 --------
2913 --------
2914 ::
2914 ::
2915
2915
2916 In [9]: pwd
2916 In [9]: pwd
2917 Out[9]: '/home/tsuser/sprint/ipython'
2917 Out[9]: '/home/tsuser/sprint/ipython'
2918 """
2918 """
2919 return os.getcwdu()
2919 return os.getcwdu()
2920
2920
2921 @skip_doctest
2921 @skip_doctest
2922 def magic_cd(self, parameter_s=''):
2922 def magic_cd(self, parameter_s=''):
2923 """Change the current working directory.
2923 """Change the current working directory.
2924
2924
2925 This command automatically maintains an internal list of directories
2925 This command automatically maintains an internal list of directories
2926 you visit during your IPython session, in the variable _dh. The
2926 you visit during your IPython session, in the variable _dh. The
2927 command %dhist shows this history nicely formatted. You can also
2927 command %dhist shows this history nicely formatted. You can also
2928 do 'cd -<tab>' to see directory history conveniently.
2928 do 'cd -<tab>' to see directory history conveniently.
2929
2929
2930 Usage:
2930 Usage:
2931
2931
2932 cd 'dir': changes to directory 'dir'.
2932 cd 'dir': changes to directory 'dir'.
2933
2933
2934 cd -: changes to the last visited directory.
2934 cd -: changes to the last visited directory.
2935
2935
2936 cd -<n>: changes to the n-th directory in the directory history.
2936 cd -<n>: changes to the n-th directory in the directory history.
2937
2937
2938 cd --foo: change to directory that matches 'foo' in history
2938 cd --foo: change to directory that matches 'foo' in history
2939
2939
2940 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2940 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2941 (note: cd <bookmark_name> is enough if there is no
2941 (note: cd <bookmark_name> is enough if there is no
2942 directory <bookmark_name>, but a bookmark with the name exists.)
2942 directory <bookmark_name>, but a bookmark with the name exists.)
2943 'cd -b <tab>' allows you to tab-complete bookmark names.
2943 'cd -b <tab>' allows you to tab-complete bookmark names.
2944
2944
2945 Options:
2945 Options:
2946
2946
2947 -q: quiet. Do not print the working directory after the cd command is
2947 -q: quiet. Do not print the working directory after the cd command is
2948 executed. By default IPython's cd command does print this directory,
2948 executed. By default IPython's cd command does print this directory,
2949 since the default prompts do not display path information.
2949 since the default prompts do not display path information.
2950
2950
2951 Note that !cd doesn't work for this purpose because the shell where
2951 Note that !cd doesn't work for this purpose because the shell where
2952 !command runs is immediately discarded after executing 'command'.
2952 !command runs is immediately discarded after executing 'command'.
2953
2953
2954 Examples
2954 Examples
2955 --------
2955 --------
2956 ::
2956 ::
2957
2957
2958 In [10]: cd parent/child
2958 In [10]: cd parent/child
2959 /home/tsuser/parent/child
2959 /home/tsuser/parent/child
2960 """
2960 """
2961
2961
2962 parameter_s = parameter_s.strip()
2962 parameter_s = parameter_s.strip()
2963 #bkms = self.shell.persist.get("bookmarks",{})
2963 #bkms = self.shell.persist.get("bookmarks",{})
2964
2964
2965 oldcwd = os.getcwdu()
2965 oldcwd = os.getcwdu()
2966 numcd = re.match(r'(-)(\d+)$',parameter_s)
2966 numcd = re.match(r'(-)(\d+)$',parameter_s)
2967 # jump in directory history by number
2967 # jump in directory history by number
2968 if numcd:
2968 if numcd:
2969 nn = int(numcd.group(2))
2969 nn = int(numcd.group(2))
2970 try:
2970 try:
2971 ps = self.shell.user_ns['_dh'][nn]
2971 ps = self.shell.user_ns['_dh'][nn]
2972 except IndexError:
2972 except IndexError:
2973 print 'The requested directory does not exist in history.'
2973 print 'The requested directory does not exist in history.'
2974 return
2974 return
2975 else:
2975 else:
2976 opts = {}
2976 opts = {}
2977 elif parameter_s.startswith('--'):
2977 elif parameter_s.startswith('--'):
2978 ps = None
2978 ps = None
2979 fallback = None
2979 fallback = None
2980 pat = parameter_s[2:]
2980 pat = parameter_s[2:]
2981 dh = self.shell.user_ns['_dh']
2981 dh = self.shell.user_ns['_dh']
2982 # first search only by basename (last component)
2982 # first search only by basename (last component)
2983 for ent in reversed(dh):
2983 for ent in reversed(dh):
2984 if pat in os.path.basename(ent) and os.path.isdir(ent):
2984 if pat in os.path.basename(ent) and os.path.isdir(ent):
2985 ps = ent
2985 ps = ent
2986 break
2986 break
2987
2987
2988 if fallback is None and pat in ent and os.path.isdir(ent):
2988 if fallback is None and pat in ent and os.path.isdir(ent):
2989 fallback = ent
2989 fallback = ent
2990
2990
2991 # if we have no last part match, pick the first full path match
2991 # if we have no last part match, pick the first full path match
2992 if ps is None:
2992 if ps is None:
2993 ps = fallback
2993 ps = fallback
2994
2994
2995 if ps is None:
2995 if ps is None:
2996 print "No matching entry in directory history"
2996 print "No matching entry in directory history"
2997 return
2997 return
2998 else:
2998 else:
2999 opts = {}
2999 opts = {}
3000
3000
3001
3001
3002 else:
3002 else:
3003 #turn all non-space-escaping backslashes to slashes,
3003 #turn all non-space-escaping backslashes to slashes,
3004 # for c:\windows\directory\names\
3004 # for c:\windows\directory\names\
3005 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
3005 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
3006 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
3006 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
3007 # jump to previous
3007 # jump to previous
3008 if ps == '-':
3008 if ps == '-':
3009 try:
3009 try:
3010 ps = self.shell.user_ns['_dh'][-2]
3010 ps = self.shell.user_ns['_dh'][-2]
3011 except IndexError:
3011 except IndexError:
3012 raise UsageError('%cd -: No previous directory to change to.')
3012 raise UsageError('%cd -: No previous directory to change to.')
3013 # jump to bookmark if needed
3013 # jump to bookmark if needed
3014 else:
3014 else:
3015 if not os.path.isdir(ps) or opts.has_key('b'):
3015 if not os.path.isdir(ps) or opts.has_key('b'):
3016 bkms = self.shell.db.get('bookmarks', {})
3016 bkms = self.shell.db.get('bookmarks', {})
3017
3017
3018 if bkms.has_key(ps):
3018 if bkms.has_key(ps):
3019 target = bkms[ps]
3019 target = bkms[ps]
3020 print '(bookmark:%s) -> %s' % (ps,target)
3020 print '(bookmark:%s) -> %s' % (ps,target)
3021 ps = target
3021 ps = target
3022 else:
3022 else:
3023 if opts.has_key('b'):
3023 if opts.has_key('b'):
3024 raise UsageError("Bookmark '%s' not found. "
3024 raise UsageError("Bookmark '%s' not found. "
3025 "Use '%%bookmark -l' to see your bookmarks." % ps)
3025 "Use '%%bookmark -l' to see your bookmarks." % ps)
3026
3026
3027 # strip extra quotes on Windows, because os.chdir doesn't like them
3027 # strip extra quotes on Windows, because os.chdir doesn't like them
3028 ps = unquote_filename(ps)
3028 ps = unquote_filename(ps)
3029 # at this point ps should point to the target dir
3029 # at this point ps should point to the target dir
3030 if ps:
3030 if ps:
3031 try:
3031 try:
3032 os.chdir(os.path.expanduser(ps))
3032 os.chdir(os.path.expanduser(ps))
3033 if hasattr(self.shell, 'term_title') and self.shell.term_title:
3033 if hasattr(self.shell, 'term_title') and self.shell.term_title:
3034 set_term_title('IPython: ' + abbrev_cwd())
3034 set_term_title('IPython: ' + abbrev_cwd())
3035 except OSError:
3035 except OSError:
3036 print sys.exc_info()[1]
3036 print sys.exc_info()[1]
3037 else:
3037 else:
3038 cwd = os.getcwdu()
3038 cwd = os.getcwdu()
3039 dhist = self.shell.user_ns['_dh']
3039 dhist = self.shell.user_ns['_dh']
3040 if oldcwd != cwd:
3040 if oldcwd != cwd:
3041 dhist.append(cwd)
3041 dhist.append(cwd)
3042 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
3042 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
3043
3043
3044 else:
3044 else:
3045 os.chdir(self.shell.home_dir)
3045 os.chdir(self.shell.home_dir)
3046 if hasattr(self.shell, 'term_title') and self.shell.term_title:
3046 if hasattr(self.shell, 'term_title') and self.shell.term_title:
3047 set_term_title('IPython: ' + '~')
3047 set_term_title('IPython: ' + '~')
3048 cwd = os.getcwdu()
3048 cwd = os.getcwdu()
3049 dhist = self.shell.user_ns['_dh']
3049 dhist = self.shell.user_ns['_dh']
3050
3050
3051 if oldcwd != cwd:
3051 if oldcwd != cwd:
3052 dhist.append(cwd)
3052 dhist.append(cwd)
3053 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
3053 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
3054 if not 'q' in opts and self.shell.user_ns['_dh']:
3054 if not 'q' in opts and self.shell.user_ns['_dh']:
3055 print self.shell.user_ns['_dh'][-1]
3055 print self.shell.user_ns['_dh'][-1]
3056
3056
3057
3057
3058 def magic_env(self, parameter_s=''):
3058 def magic_env(self, parameter_s=''):
3059 """List environment variables."""
3059 """List environment variables."""
3060
3060
3061 return dict(os.environ)
3061 return dict(os.environ)
3062
3062
3063 def magic_pushd(self, parameter_s=''):
3063 def magic_pushd(self, parameter_s=''):
3064 """Place the current dir on stack and change directory.
3064 """Place the current dir on stack and change directory.
3065
3065
3066 Usage:\\
3066 Usage:\\
3067 %pushd ['dirname']
3067 %pushd ['dirname']
3068 """
3068 """
3069
3069
3070 dir_s = self.shell.dir_stack
3070 dir_s = self.shell.dir_stack
3071 tgt = os.path.expanduser(unquote_filename(parameter_s))
3071 tgt = os.path.expanduser(unquote_filename(parameter_s))
3072 cwd = os.getcwdu().replace(self.home_dir,'~')
3072 cwd = os.getcwdu().replace(self.home_dir,'~')
3073 if tgt:
3073 if tgt:
3074 self.magic_cd(parameter_s)
3074 self.magic_cd(parameter_s)
3075 dir_s.insert(0,cwd)
3075 dir_s.insert(0,cwd)
3076 return self.magic_dirs()
3076 return self.magic_dirs()
3077
3077
3078 def magic_popd(self, parameter_s=''):
3078 def magic_popd(self, parameter_s=''):
3079 """Change to directory popped off the top of the stack.
3079 """Change to directory popped off the top of the stack.
3080 """
3080 """
3081 if not self.shell.dir_stack:
3081 if not self.shell.dir_stack:
3082 raise UsageError("%popd on empty stack")
3082 raise UsageError("%popd on empty stack")
3083 top = self.shell.dir_stack.pop(0)
3083 top = self.shell.dir_stack.pop(0)
3084 self.magic_cd(top)
3084 self.magic_cd(top)
3085 print "popd ->",top
3085 print "popd ->",top
3086
3086
3087 def magic_dirs(self, parameter_s=''):
3087 def magic_dirs(self, parameter_s=''):
3088 """Return the current directory stack."""
3088 """Return the current directory stack."""
3089
3089
3090 return self.shell.dir_stack
3090 return self.shell.dir_stack
3091
3091
3092 def magic_dhist(self, parameter_s=''):
3092 def magic_dhist(self, parameter_s=''):
3093 """Print your history of visited directories.
3093 """Print your history of visited directories.
3094
3094
3095 %dhist -> print full history\\
3095 %dhist -> print full history\\
3096 %dhist n -> print last n entries only\\
3096 %dhist n -> print last n entries only\\
3097 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
3097 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
3098
3098
3099 This history is automatically maintained by the %cd command, and
3099 This history is automatically maintained by the %cd command, and
3100 always available as the global list variable _dh. You can use %cd -<n>
3100 always available as the global list variable _dh. You can use %cd -<n>
3101 to go to directory number <n>.
3101 to go to directory number <n>.
3102
3102
3103 Note that most of time, you should view directory history by entering
3103 Note that most of time, you should view directory history by entering
3104 cd -<TAB>.
3104 cd -<TAB>.
3105
3105
3106 """
3106 """
3107
3107
3108 dh = self.shell.user_ns['_dh']
3108 dh = self.shell.user_ns['_dh']
3109 if parameter_s:
3109 if parameter_s:
3110 try:
3110 try:
3111 args = map(int,parameter_s.split())
3111 args = map(int,parameter_s.split())
3112 except:
3112 except:
3113 self.arg_err(Magic.magic_dhist)
3113 self.arg_err(Magic.magic_dhist)
3114 return
3114 return
3115 if len(args) == 1:
3115 if len(args) == 1:
3116 ini,fin = max(len(dh)-(args[0]),0),len(dh)
3116 ini,fin = max(len(dh)-(args[0]),0),len(dh)
3117 elif len(args) == 2:
3117 elif len(args) == 2:
3118 ini,fin = args
3118 ini,fin = args
3119 else:
3119 else:
3120 self.arg_err(Magic.magic_dhist)
3120 self.arg_err(Magic.magic_dhist)
3121 return
3121 return
3122 else:
3122 else:
3123 ini,fin = 0,len(dh)
3123 ini,fin = 0,len(dh)
3124 nlprint(dh,
3124 nlprint(dh,
3125 header = 'Directory history (kept in _dh)',
3125 header = 'Directory history (kept in _dh)',
3126 start=ini,stop=fin)
3126 start=ini,stop=fin)
3127
3127
3128 @skip_doctest
3128 @skip_doctest
3129 def magic_sc(self, parameter_s=''):
3129 def magic_sc(self, parameter_s=''):
3130 """Shell capture - execute a shell command and capture its output.
3130 """Shell capture - execute a shell command and capture its output.
3131
3131
3132 DEPRECATED. Suboptimal, retained for backwards compatibility.
3132 DEPRECATED. Suboptimal, retained for backwards compatibility.
3133
3133
3134 You should use the form 'var = !command' instead. Example:
3134 You should use the form 'var = !command' instead. Example:
3135
3135
3136 "%sc -l myfiles = ls ~" should now be written as
3136 "%sc -l myfiles = ls ~" should now be written as
3137
3137
3138 "myfiles = !ls ~"
3138 "myfiles = !ls ~"
3139
3139
3140 myfiles.s, myfiles.l and myfiles.n still apply as documented
3140 myfiles.s, myfiles.l and myfiles.n still apply as documented
3141 below.
3141 below.
3142
3142
3143 --
3143 --
3144 %sc [options] varname=command
3144 %sc [options] varname=command
3145
3145
3146 IPython will run the given command using commands.getoutput(), and
3146 IPython will run the given command using commands.getoutput(), and
3147 will then update the user's interactive namespace with a variable
3147 will then update the user's interactive namespace with a variable
3148 called varname, containing the value of the call. Your command can
3148 called varname, containing the value of the call. Your command can
3149 contain shell wildcards, pipes, etc.
3149 contain shell wildcards, pipes, etc.
3150
3150
3151 The '=' sign in the syntax is mandatory, and the variable name you
3151 The '=' sign in the syntax is mandatory, and the variable name you
3152 supply must follow Python's standard conventions for valid names.
3152 supply must follow Python's standard conventions for valid names.
3153
3153
3154 (A special format without variable name exists for internal use)
3154 (A special format without variable name exists for internal use)
3155
3155
3156 Options:
3156 Options:
3157
3157
3158 -l: list output. Split the output on newlines into a list before
3158 -l: list output. Split the output on newlines into a list before
3159 assigning it to the given variable. By default the output is stored
3159 assigning it to the given variable. By default the output is stored
3160 as a single string.
3160 as a single string.
3161
3161
3162 -v: verbose. Print the contents of the variable.
3162 -v: verbose. Print the contents of the variable.
3163
3163
3164 In most cases you should not need to split as a list, because the
3164 In most cases you should not need to split as a list, because the
3165 returned value is a special type of string which can automatically
3165 returned value is a special type of string which can automatically
3166 provide its contents either as a list (split on newlines) or as a
3166 provide its contents either as a list (split on newlines) or as a
3167 space-separated string. These are convenient, respectively, either
3167 space-separated string. These are convenient, respectively, either
3168 for sequential processing or to be passed to a shell command.
3168 for sequential processing or to be passed to a shell command.
3169
3169
3170 For example::
3170 For example::
3171
3171
3172 # Capture into variable a
3172 # Capture into variable a
3173 In [1]: sc a=ls *py
3173 In [1]: sc a=ls *py
3174
3174
3175 # a is a string with embedded newlines
3175 # a is a string with embedded newlines
3176 In [2]: a
3176 In [2]: a
3177 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3177 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3178
3178
3179 # which can be seen as a list:
3179 # which can be seen as a list:
3180 In [3]: a.l
3180 In [3]: a.l
3181 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3181 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3182
3182
3183 # or as a whitespace-separated string:
3183 # or as a whitespace-separated string:
3184 In [4]: a.s
3184 In [4]: a.s
3185 Out[4]: 'setup.py win32_manual_post_install.py'
3185 Out[4]: 'setup.py win32_manual_post_install.py'
3186
3186
3187 # a.s is useful to pass as a single command line:
3187 # a.s is useful to pass as a single command line:
3188 In [5]: !wc -l $a.s
3188 In [5]: !wc -l $a.s
3189 146 setup.py
3189 146 setup.py
3190 130 win32_manual_post_install.py
3190 130 win32_manual_post_install.py
3191 276 total
3191 276 total
3192
3192
3193 # while the list form is useful to loop over:
3193 # while the list form is useful to loop over:
3194 In [6]: for f in a.l:
3194 In [6]: for f in a.l:
3195 ...: !wc -l $f
3195 ...: !wc -l $f
3196 ...:
3196 ...:
3197 146 setup.py
3197 146 setup.py
3198 130 win32_manual_post_install.py
3198 130 win32_manual_post_install.py
3199
3199
3200 Similarly, the lists returned by the -l option are also special, in
3200 Similarly, the lists returned by the -l option are also special, in
3201 the sense that you can equally invoke the .s attribute on them to
3201 the sense that you can equally invoke the .s attribute on them to
3202 automatically get a whitespace-separated string from their contents::
3202 automatically get a whitespace-separated string from their contents::
3203
3203
3204 In [7]: sc -l b=ls *py
3204 In [7]: sc -l b=ls *py
3205
3205
3206 In [8]: b
3206 In [8]: b
3207 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3207 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3208
3208
3209 In [9]: b.s
3209 In [9]: b.s
3210 Out[9]: 'setup.py win32_manual_post_install.py'
3210 Out[9]: 'setup.py win32_manual_post_install.py'
3211
3211
3212 In summary, both the lists and strings used for output capture have
3212 In summary, both the lists and strings used for output capture have
3213 the following special attributes::
3213 the following special attributes::
3214
3214
3215 .l (or .list) : value as list.
3215 .l (or .list) : value as list.
3216 .n (or .nlstr): value as newline-separated string.
3216 .n (or .nlstr): value as newline-separated string.
3217 .s (or .spstr): value as space-separated string.
3217 .s (or .spstr): value as space-separated string.
3218 """
3218 """
3219
3219
3220 opts,args = self.parse_options(parameter_s,'lv')
3220 opts,args = self.parse_options(parameter_s,'lv')
3221 # Try to get a variable name and command to run
3221 # Try to get a variable name and command to run
3222 try:
3222 try:
3223 # the variable name must be obtained from the parse_options
3223 # the variable name must be obtained from the parse_options
3224 # output, which uses shlex.split to strip options out.
3224 # output, which uses shlex.split to strip options out.
3225 var,_ = args.split('=',1)
3225 var,_ = args.split('=',1)
3226 var = var.strip()
3226 var = var.strip()
3227 # But the command has to be extracted from the original input
3227 # But the command has to be extracted from the original input
3228 # parameter_s, not on what parse_options returns, to avoid the
3228 # parameter_s, not on what parse_options returns, to avoid the
3229 # quote stripping which shlex.split performs on it.
3229 # quote stripping which shlex.split performs on it.
3230 _,cmd = parameter_s.split('=',1)
3230 _,cmd = parameter_s.split('=',1)
3231 except ValueError:
3231 except ValueError:
3232 var,cmd = '',''
3232 var,cmd = '',''
3233 # If all looks ok, proceed
3233 # If all looks ok, proceed
3234 split = 'l' in opts
3234 split = 'l' in opts
3235 out = self.shell.getoutput(cmd, split=split)
3235 out = self.shell.getoutput(cmd, split=split)
3236 if opts.has_key('v'):
3236 if opts.has_key('v'):
3237 print '%s ==\n%s' % (var,pformat(out))
3237 print '%s ==\n%s' % (var,pformat(out))
3238 if var:
3238 if var:
3239 self.shell.user_ns.update({var:out})
3239 self.shell.user_ns.update({var:out})
3240 else:
3240 else:
3241 return out
3241 return out
3242
3242
3243 def magic_sx(self, parameter_s=''):
3243 def magic_sx(self, parameter_s=''):
3244 """Shell execute - run a shell command and capture its output.
3244 """Shell execute - run a shell command and capture its output.
3245
3245
3246 %sx command
3246 %sx command
3247
3247
3248 IPython will run the given command using commands.getoutput(), and
3248 IPython will run the given command using commands.getoutput(), and
3249 return the result formatted as a list (split on '\\n'). Since the
3249 return the result formatted as a list (split on '\\n'). Since the
3250 output is _returned_, it will be stored in ipython's regular output
3250 output is _returned_, it will be stored in ipython's regular output
3251 cache Out[N] and in the '_N' automatic variables.
3251 cache Out[N] and in the '_N' automatic variables.
3252
3252
3253 Notes:
3253 Notes:
3254
3254
3255 1) If an input line begins with '!!', then %sx is automatically
3255 1) If an input line begins with '!!', then %sx is automatically
3256 invoked. That is, while::
3256 invoked. That is, while::
3257
3257
3258 !ls
3258 !ls
3259
3259
3260 causes ipython to simply issue system('ls'), typing::
3260 causes ipython to simply issue system('ls'), typing::
3261
3261
3262 !!ls
3262 !!ls
3263
3263
3264 is a shorthand equivalent to::
3264 is a shorthand equivalent to::
3265
3265
3266 %sx ls
3266 %sx ls
3267
3267
3268 2) %sx differs from %sc in that %sx automatically splits into a list,
3268 2) %sx differs from %sc in that %sx automatically splits into a list,
3269 like '%sc -l'. The reason for this is to make it as easy as possible
3269 like '%sc -l'. The reason for this is to make it as easy as possible
3270 to process line-oriented shell output via further python commands.
3270 to process line-oriented shell output via further python commands.
3271 %sc is meant to provide much finer control, but requires more
3271 %sc is meant to provide much finer control, but requires more
3272 typing.
3272 typing.
3273
3273
3274 3) Just like %sc -l, this is a list with special attributes:
3274 3) Just like %sc -l, this is a list with special attributes:
3275 ::
3275 ::
3276
3276
3277 .l (or .list) : value as list.
3277 .l (or .list) : value as list.
3278 .n (or .nlstr): value as newline-separated string.
3278 .n (or .nlstr): value as newline-separated string.
3279 .s (or .spstr): value as whitespace-separated string.
3279 .s (or .spstr): value as whitespace-separated string.
3280
3280
3281 This is very useful when trying to use such lists as arguments to
3281 This is very useful when trying to use such lists as arguments to
3282 system commands."""
3282 system commands."""
3283
3283
3284 if parameter_s:
3284 if parameter_s:
3285 return self.shell.getoutput(parameter_s)
3285 return self.shell.getoutput(parameter_s)
3286
3286
3287
3287
3288 def magic_bookmark(self, parameter_s=''):
3288 def magic_bookmark(self, parameter_s=''):
3289 """Manage IPython's bookmark system.
3289 """Manage IPython's bookmark system.
3290
3290
3291 %bookmark <name> - set bookmark to current dir
3291 %bookmark <name> - set bookmark to current dir
3292 %bookmark <name> <dir> - set bookmark to <dir>
3292 %bookmark <name> <dir> - set bookmark to <dir>
3293 %bookmark -l - list all bookmarks
3293 %bookmark -l - list all bookmarks
3294 %bookmark -d <name> - remove bookmark
3294 %bookmark -d <name> - remove bookmark
3295 %bookmark -r - remove all bookmarks
3295 %bookmark -r - remove all bookmarks
3296
3296
3297 You can later on access a bookmarked folder with::
3297 You can later on access a bookmarked folder with::
3298
3298
3299 %cd -b <name>
3299 %cd -b <name>
3300
3300
3301 or simply '%cd <name>' if there is no directory called <name> AND
3301 or simply '%cd <name>' if there is no directory called <name> AND
3302 there is such a bookmark defined.
3302 there is such a bookmark defined.
3303
3303
3304 Your bookmarks persist through IPython sessions, but they are
3304 Your bookmarks persist through IPython sessions, but they are
3305 associated with each profile."""
3305 associated with each profile."""
3306
3306
3307 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3307 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3308 if len(args) > 2:
3308 if len(args) > 2:
3309 raise UsageError("%bookmark: too many arguments")
3309 raise UsageError("%bookmark: too many arguments")
3310
3310
3311 bkms = self.shell.db.get('bookmarks',{})
3311 bkms = self.shell.db.get('bookmarks',{})
3312
3312
3313 if opts.has_key('d'):
3313 if opts.has_key('d'):
3314 try:
3314 try:
3315 todel = args[0]
3315 todel = args[0]
3316 except IndexError:
3316 except IndexError:
3317 raise UsageError(
3317 raise UsageError(
3318 "%bookmark -d: must provide a bookmark to delete")
3318 "%bookmark -d: must provide a bookmark to delete")
3319 else:
3319 else:
3320 try:
3320 try:
3321 del bkms[todel]
3321 del bkms[todel]
3322 except KeyError:
3322 except KeyError:
3323 raise UsageError(
3323 raise UsageError(
3324 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3324 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3325
3325
3326 elif opts.has_key('r'):
3326 elif opts.has_key('r'):
3327 bkms = {}
3327 bkms = {}
3328 elif opts.has_key('l'):
3328 elif opts.has_key('l'):
3329 bks = bkms.keys()
3329 bks = bkms.keys()
3330 bks.sort()
3330 bks.sort()
3331 if bks:
3331 if bks:
3332 size = max(map(len,bks))
3332 size = max(map(len,bks))
3333 else:
3333 else:
3334 size = 0
3334 size = 0
3335 fmt = '%-'+str(size)+'s -> %s'
3335 fmt = '%-'+str(size)+'s -> %s'
3336 print 'Current bookmarks:'
3336 print 'Current bookmarks:'
3337 for bk in bks:
3337 for bk in bks:
3338 print fmt % (bk,bkms[bk])
3338 print fmt % (bk,bkms[bk])
3339 else:
3339 else:
3340 if not args:
3340 if not args:
3341 raise UsageError("%bookmark: You must specify the bookmark name")
3341 raise UsageError("%bookmark: You must specify the bookmark name")
3342 elif len(args)==1:
3342 elif len(args)==1:
3343 bkms[args[0]] = os.getcwdu()
3343 bkms[args[0]] = os.getcwdu()
3344 elif len(args)==2:
3344 elif len(args)==2:
3345 bkms[args[0]] = args[1]
3345 bkms[args[0]] = args[1]
3346 self.shell.db['bookmarks'] = bkms
3346 self.shell.db['bookmarks'] = bkms
3347
3347
3348
3348
3349 def magic_pycat(self, parameter_s=''):
3349 def magic_pycat(self, parameter_s=''):
3350 """Show a syntax-highlighted file through a pager.
3350 """Show a syntax-highlighted file through a pager.
3351
3351
3352 This magic is similar to the cat utility, but it will assume the file
3352 This magic is similar to the cat utility, but it will assume the file
3353 to be Python source and will show it with syntax highlighting.
3353 to be Python source and will show it with syntax highlighting.
3354
3354
3355 This magic command can either take a local filename, an url,
3355 This magic command can either take a local filename, an url,
3356 an history range (see %history) or a macro as argument ::
3356 an history range (see %history) or a macro as argument ::
3357
3357
3358 %pycat myscript.py
3358 %pycat myscript.py
3359 %pycat 7-27
3359 %pycat 7-27
3360 %pycat myMacro
3360 %pycat myMacro
3361 %pycat http://www.example.com/myscript.py
3361 %pycat http://www.example.com/myscript.py
3362 """
3362 """
3363
3363
3364 try :
3364 try :
3365 cont = self.shell.find_user_code(parameter_s)
3365 cont = self.shell.find_user_code(parameter_s)
3366 except ValueError, IOError:
3366 except ValueError, IOError:
3367 print "Error: no such file, variable, URL, history range or macro"
3367 print "Error: no such file, variable, URL, history range or macro"
3368 return
3368 return
3369
3369
3370 page.page(self.shell.pycolorize(cont))
3370 page.page(self.shell.pycolorize(cont))
3371
3371
3372 def magic_quickref(self,arg):
3372 def magic_quickref(self,arg):
3373 """ Show a quick reference sheet """
3373 """ Show a quick reference sheet """
3374 import IPython.core.usage
3374 import IPython.core.usage
3375 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3375 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3376
3376
3377 page.page(qr)
3377 page.page(qr)
3378
3378
3379 def magic_doctest_mode(self,parameter_s=''):
3379 def magic_doctest_mode(self,parameter_s=''):
3380 """Toggle doctest mode on and off.
3380 """Toggle doctest mode on and off.
3381
3381
3382 This mode is intended to make IPython behave as much as possible like a
3382 This mode is intended to make IPython behave as much as possible like a
3383 plain Python shell, from the perspective of how its prompts, exceptions
3383 plain Python shell, from the perspective of how its prompts, exceptions
3384 and output look. This makes it easy to copy and paste parts of a
3384 and output look. This makes it easy to copy and paste parts of a
3385 session into doctests. It does so by:
3385 session into doctests. It does so by:
3386
3386
3387 - Changing the prompts to the classic ``>>>`` ones.
3387 - Changing the prompts to the classic ``>>>`` ones.
3388 - Changing the exception reporting mode to 'Plain'.
3388 - Changing the exception reporting mode to 'Plain'.
3389 - Disabling pretty-printing of output.
3389 - Disabling pretty-printing of output.
3390
3390
3391 Note that IPython also supports the pasting of code snippets that have
3391 Note that IPython also supports the pasting of code snippets that have
3392 leading '>>>' and '...' prompts in them. This means that you can paste
3392 leading '>>>' and '...' prompts in them. This means that you can paste
3393 doctests from files or docstrings (even if they have leading
3393 doctests from files or docstrings (even if they have leading
3394 whitespace), and the code will execute correctly. You can then use
3394 whitespace), and the code will execute correctly. You can then use
3395 '%history -t' to see the translated history; this will give you the
3395 '%history -t' to see the translated history; this will give you the
3396 input after removal of all the leading prompts and whitespace, which
3396 input after removal of all the leading prompts and whitespace, which
3397 can be pasted back into an editor.
3397 can be pasted back into an editor.
3398
3398
3399 With these features, you can switch into this mode easily whenever you
3399 With these features, you can switch into this mode easily whenever you
3400 need to do testing and changes to doctests, without having to leave
3400 need to do testing and changes to doctests, without having to leave
3401 your existing IPython session.
3401 your existing IPython session.
3402 """
3402 """
3403
3403
3404 from IPython.utils.ipstruct import Struct
3404 from IPython.utils.ipstruct import Struct
3405
3405
3406 # Shorthands
3406 # Shorthands
3407 shell = self.shell
3407 shell = self.shell
3408 pm = shell.prompt_manager
3408 pm = shell.prompt_manager
3409 meta = shell.meta
3409 meta = shell.meta
3410 disp_formatter = self.shell.display_formatter
3410 disp_formatter = self.shell.display_formatter
3411 ptformatter = disp_formatter.formatters['text/plain']
3411 ptformatter = disp_formatter.formatters['text/plain']
3412 # dstore is a data store kept in the instance metadata bag to track any
3412 # dstore is a data store kept in the instance metadata bag to track any
3413 # changes we make, so we can undo them later.
3413 # changes we make, so we can undo them later.
3414 dstore = meta.setdefault('doctest_mode',Struct())
3414 dstore = meta.setdefault('doctest_mode',Struct())
3415 save_dstore = dstore.setdefault
3415 save_dstore = dstore.setdefault
3416
3416
3417 # save a few values we'll need to recover later
3417 # save a few values we'll need to recover later
3418 mode = save_dstore('mode',False)
3418 mode = save_dstore('mode',False)
3419 save_dstore('rc_pprint',ptformatter.pprint)
3419 save_dstore('rc_pprint',ptformatter.pprint)
3420 save_dstore('xmode',shell.InteractiveTB.mode)
3420 save_dstore('xmode',shell.InteractiveTB.mode)
3421 save_dstore('rc_separate_out',shell.separate_out)
3421 save_dstore('rc_separate_out',shell.separate_out)
3422 save_dstore('rc_separate_out2',shell.separate_out2)
3422 save_dstore('rc_separate_out2',shell.separate_out2)
3423 save_dstore('rc_prompts_pad_left',pm.justify)
3423 save_dstore('rc_prompts_pad_left',pm.justify)
3424 save_dstore('rc_separate_in',shell.separate_in)
3424 save_dstore('rc_separate_in',shell.separate_in)
3425 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3425 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3426 save_dstore('prompt_templates',(pm.in_template, pm.in2_template, pm.out_template))
3426 save_dstore('prompt_templates',(pm.in_template, pm.in2_template, pm.out_template))
3427
3427
3428 if mode == False:
3428 if mode == False:
3429 # turn on
3429 # turn on
3430 pm.in_template = '>>> '
3430 pm.in_template = '>>> '
3431 pm.in2_template = '... '
3431 pm.in2_template = '... '
3432 pm.out_template = ''
3432 pm.out_template = ''
3433
3433
3434 # Prompt separators like plain python
3434 # Prompt separators like plain python
3435 shell.separate_in = ''
3435 shell.separate_in = ''
3436 shell.separate_out = ''
3436 shell.separate_out = ''
3437 shell.separate_out2 = ''
3437 shell.separate_out2 = ''
3438
3438
3439 pm.justify = False
3439 pm.justify = False
3440
3440
3441 ptformatter.pprint = False
3441 ptformatter.pprint = False
3442 disp_formatter.plain_text_only = True
3442 disp_formatter.plain_text_only = True
3443
3443
3444 shell.magic_xmode('Plain')
3444 shell.magic_xmode('Plain')
3445 else:
3445 else:
3446 # turn off
3446 # turn off
3447 pm.in_template, pm.in2_template, pm.out_template = dstore.prompt_templates
3447 pm.in_template, pm.in2_template, pm.out_template = dstore.prompt_templates
3448
3448
3449 shell.separate_in = dstore.rc_separate_in
3449 shell.separate_in = dstore.rc_separate_in
3450
3450
3451 shell.separate_out = dstore.rc_separate_out
3451 shell.separate_out = dstore.rc_separate_out
3452 shell.separate_out2 = dstore.rc_separate_out2
3452 shell.separate_out2 = dstore.rc_separate_out2
3453
3453
3454 pm.justify = dstore.rc_prompts_pad_left
3454 pm.justify = dstore.rc_prompts_pad_left
3455
3455
3456 ptformatter.pprint = dstore.rc_pprint
3456 ptformatter.pprint = dstore.rc_pprint
3457 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3457 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3458
3458
3459 shell.magic_xmode(dstore.xmode)
3459 shell.magic_xmode(dstore.xmode)
3460
3460
3461 # Store new mode and inform
3461 # Store new mode and inform
3462 dstore.mode = bool(1-int(mode))
3462 dstore.mode = bool(1-int(mode))
3463 mode_label = ['OFF','ON'][dstore.mode]
3463 mode_label = ['OFF','ON'][dstore.mode]
3464 print 'Doctest mode is:', mode_label
3464 print 'Doctest mode is:', mode_label
3465
3465
3466 def magic_gui(self, parameter_s=''):
3466 def magic_gui(self, parameter_s=''):
3467 """Enable or disable IPython GUI event loop integration.
3467 """Enable or disable IPython GUI event loop integration.
3468
3468
3469 %gui [GUINAME]
3469 %gui [GUINAME]
3470
3470
3471 This magic replaces IPython's threaded shells that were activated
3471 This magic replaces IPython's threaded shells that were activated
3472 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3472 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3473 can now be enabled at runtime and keyboard
3473 can now be enabled at runtime and keyboard
3474 interrupts should work without any problems. The following toolkits
3474 interrupts should work without any problems. The following toolkits
3475 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
3475 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
3476
3476
3477 %gui wx # enable wxPython event loop integration
3477 %gui wx # enable wxPython event loop integration
3478 %gui qt4|qt # enable PyQt4 event loop integration
3478 %gui qt4|qt # enable PyQt4 event loop integration
3479 %gui gtk # enable PyGTK event loop integration
3479 %gui gtk # enable PyGTK event loop integration
3480 %gui gtk3 # enable Gtk3 event loop integration
3480 %gui gtk3 # enable Gtk3 event loop integration
3481 %gui tk # enable Tk event loop integration
3481 %gui tk # enable Tk event loop integration
3482 %gui OSX # enable Cocoa event loop integration
3482 %gui OSX # enable Cocoa event loop integration
3483 # (requires %matplotlib 1.1)
3483 # (requires %matplotlib 1.1)
3484 %gui # disable all event loop integration
3484 %gui # disable all event loop integration
3485
3485
3486 WARNING: after any of these has been called you can simply create
3486 WARNING: after any of these has been called you can simply create
3487 an application object, but DO NOT start the event loop yourself, as
3487 an application object, but DO NOT start the event loop yourself, as
3488 we have already handled that.
3488 we have already handled that.
3489 """
3489 """
3490 opts, arg = self.parse_options(parameter_s, '')
3490 opts, arg = self.parse_options(parameter_s, '')
3491 if arg=='': arg = None
3491 if arg=='': arg = None
3492 try:
3492 try:
3493 return self.enable_gui(arg)
3493 return self.enable_gui(arg)
3494 except Exception as e:
3494 except Exception as e:
3495 # print simple error message, rather than traceback if we can't
3495 # print simple error message, rather than traceback if we can't
3496 # hook up the GUI
3496 # hook up the GUI
3497 error(str(e))
3497 error(str(e))
3498
3498
3499 def magic_install_ext(self, parameter_s):
3499 def magic_install_ext(self, parameter_s):
3500 """Download and install an extension from a URL, e.g.::
3500 """Download and install an extension from a URL, e.g.::
3501
3501
3502 %install_ext https://bitbucket.org/birkenfeld/ipython-physics/raw/d1310a2ab15d/physics.py
3502 %install_ext https://bitbucket.org/birkenfeld/ipython-physics/raw/d1310a2ab15d/physics.py
3503
3503
3504 The URL should point to an importable Python module - either a .py file
3504 The URL should point to an importable Python module - either a .py file
3505 or a .zip file.
3505 or a .zip file.
3506
3506
3507 Parameters:
3507 Parameters:
3508
3508
3509 -n filename : Specify a name for the file, rather than taking it from
3509 -n filename : Specify a name for the file, rather than taking it from
3510 the URL.
3510 the URL.
3511 """
3511 """
3512 opts, args = self.parse_options(parameter_s, 'n:')
3512 opts, args = self.parse_options(parameter_s, 'n:')
3513 try:
3513 try:
3514 filename = self.extension_manager.install_extension(args, opts.get('n'))
3514 filename = self.extension_manager.install_extension(args, opts.get('n'))
3515 except ValueError as e:
3515 except ValueError as e:
3516 print e
3516 print e
3517 return
3517 return
3518
3518
3519 filename = os.path.basename(filename)
3519 filename = os.path.basename(filename)
3520 print "Installed %s. To use it, type:" % filename
3520 print "Installed %s. To use it, type:" % filename
3521 print " %%load_ext %s" % os.path.splitext(filename)[0]
3521 print " %%load_ext %s" % os.path.splitext(filename)[0]
3522
3522
3523
3523
3524 def magic_load_ext(self, module_str):
3524 def magic_load_ext(self, module_str):
3525 """Load an IPython extension by its module name."""
3525 """Load an IPython extension by its module name."""
3526 return self.extension_manager.load_extension(module_str)
3526 return self.extension_manager.load_extension(module_str)
3527
3527
3528 def magic_unload_ext(self, module_str):
3528 def magic_unload_ext(self, module_str):
3529 """Unload an IPython extension by its module name."""
3529 """Unload an IPython extension by its module name."""
3530 self.extension_manager.unload_extension(module_str)
3530 self.extension_manager.unload_extension(module_str)
3531
3531
3532 def magic_reload_ext(self, module_str):
3532 def magic_reload_ext(self, module_str):
3533 """Reload an IPython extension by its module name."""
3533 """Reload an IPython extension by its module name."""
3534 self.extension_manager.reload_extension(module_str)
3534 self.extension_manager.reload_extension(module_str)
3535
3535
3536 def magic_install_profiles(self, s):
3536 def magic_install_profiles(self, s):
3537 """%install_profiles has been deprecated."""
3537 """%install_profiles has been deprecated."""
3538 print '\n'.join([
3538 print '\n'.join([
3539 "%install_profiles has been deprecated.",
3539 "%install_profiles has been deprecated.",
3540 "Use `ipython profile list` to view available profiles.",
3540 "Use `ipython profile list` to view available profiles.",
3541 "Requesting a profile with `ipython profile create <name>`",
3541 "Requesting a profile with `ipython profile create <name>`",
3542 "or `ipython --profile=<name>` will start with the bundled",
3542 "or `ipython --profile=<name>` will start with the bundled",
3543 "profile of that name if it exists."
3543 "profile of that name if it exists."
3544 ])
3544 ])
3545
3545
3546 def magic_install_default_config(self, s):
3546 def magic_install_default_config(self, s):
3547 """%install_default_config has been deprecated."""
3547 """%install_default_config has been deprecated."""
3548 print '\n'.join([
3548 print '\n'.join([
3549 "%install_default_config has been deprecated.",
3549 "%install_default_config has been deprecated.",
3550 "Use `ipython profile create <name>` to initialize a profile",
3550 "Use `ipython profile create <name>` to initialize a profile",
3551 "with the default config files.",
3551 "with the default config files.",
3552 "Add `--reset` to overwrite already existing config files with defaults."
3552 "Add `--reset` to overwrite already existing config files with defaults."
3553 ])
3553 ])
3554
3554
3555 @skip_doctest
3555 @skip_doctest
3556 def magic_pylab(self, s):
3556 def magic_pylab(self, s):
3557 """Load numpy and matplotlib to work interactively.
3557 """Load numpy and matplotlib to work interactively.
3558
3558
3559 %pylab [GUINAME]
3559 %pylab [GUINAME]
3560
3560
3561 This function lets you activate pylab (matplotlib, numpy and
3561 This function lets you activate pylab (matplotlib, numpy and
3562 interactive support) at any point during an IPython session.
3562 interactive support) at any point during an IPython session.
3563
3563
3564 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3564 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3565 pylab and mlab, as well as all names from numpy and pylab.
3565 pylab and mlab, as well as all names from numpy and pylab.
3566
3566
3567 If you are using the inline matplotlib backend for embedded figures,
3567 If you are using the inline matplotlib backend for embedded figures,
3568 you can adjust its behavior via the %config magic::
3568 you can adjust its behavior via the %config magic::
3569
3569
3570 # enable SVG figures, necessary for SVG+XHTML export in the qtconsole
3570 # enable SVG figures, necessary for SVG+XHTML export in the qtconsole
3571 In [1]: %config InlineBackend.figure_format = 'svg'
3571 In [1]: %config InlineBackend.figure_format = 'svg'
3572
3572
3573 # change the behavior of closing all figures at the end of each
3573 # change the behavior of closing all figures at the end of each
3574 # execution (cell), or allowing reuse of active figures across
3574 # execution (cell), or allowing reuse of active figures across
3575 # cells:
3575 # cells:
3576 In [2]: %config InlineBackend.close_figures = False
3576 In [2]: %config InlineBackend.close_figures = False
3577
3577
3578 Parameters
3578 Parameters
3579 ----------
3579 ----------
3580 guiname : optional
3580 guiname : optional
3581 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk',
3581 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk',
3582 'osx' or 'tk'). If given, the corresponding Matplotlib backend is
3582 'osx' or 'tk'). If given, the corresponding Matplotlib backend is
3583 used, otherwise matplotlib's default (which you can override in your
3583 used, otherwise matplotlib's default (which you can override in your
3584 matplotlib config file) is used.
3584 matplotlib config file) is used.
3585
3585
3586 Examples
3586 Examples
3587 --------
3587 --------
3588 In this case, where the MPL default is TkAgg::
3588 In this case, where the MPL default is TkAgg::
3589
3589
3590 In [2]: %pylab
3590 In [2]: %pylab
3591
3591
3592 Welcome to pylab, a matplotlib-based Python environment.
3592 Welcome to pylab, a matplotlib-based Python environment.
3593 Backend in use: TkAgg
3593 Backend in use: TkAgg
3594 For more information, type 'help(pylab)'.
3594 For more information, type 'help(pylab)'.
3595
3595
3596 But you can explicitly request a different backend::
3596 But you can explicitly request a different backend::
3597
3597
3598 In [3]: %pylab qt
3598 In [3]: %pylab qt
3599
3599
3600 Welcome to pylab, a matplotlib-based Python environment.
3600 Welcome to pylab, a matplotlib-based Python environment.
3601 Backend in use: Qt4Agg
3601 Backend in use: Qt4Agg
3602 For more information, type 'help(pylab)'.
3602 For more information, type 'help(pylab)'.
3603 """
3603 """
3604
3604
3605 if Application.initialized():
3605 if Application.initialized():
3606 app = Application.instance()
3606 app = Application.instance()
3607 try:
3607 try:
3608 import_all_status = app.pylab_import_all
3608 import_all_status = app.pylab_import_all
3609 except AttributeError:
3609 except AttributeError:
3610 import_all_status = True
3610 import_all_status = True
3611 else:
3611 else:
3612 import_all_status = True
3612 import_all_status = True
3613
3613
3614 self.shell.enable_pylab(s, import_all=import_all_status)
3614 self.shell.enable_pylab(s, import_all=import_all_status)
3615
3615
3616 def magic_tb(self, s):
3616 def magic_tb(self, s):
3617 """Print the last traceback with the currently active exception mode.
3617 """Print the last traceback with the currently active exception mode.
3618
3618
3619 See %xmode for changing exception reporting modes."""
3619 See %xmode for changing exception reporting modes."""
3620 self.shell.showtraceback()
3620 self.shell.showtraceback()
3621
3621
3622 @skip_doctest
3622 @skip_doctest
3623 def magic_precision(self, s=''):
3623 def magic_precision(self, s=''):
3624 """Set floating point precision for pretty printing.
3624 """Set floating point precision for pretty printing.
3625
3625
3626 Can set either integer precision or a format string.
3626 Can set either integer precision or a format string.
3627
3627
3628 If numpy has been imported and precision is an int,
3628 If numpy has been imported and precision is an int,
3629 numpy display precision will also be set, via ``numpy.set_printoptions``.
3629 numpy display precision will also be set, via ``numpy.set_printoptions``.
3630
3630
3631 If no argument is given, defaults will be restored.
3631 If no argument is given, defaults will be restored.
3632
3632
3633 Examples
3633 Examples
3634 --------
3634 --------
3635 ::
3635 ::
3636
3636
3637 In [1]: from math import pi
3637 In [1]: from math import pi
3638
3638
3639 In [2]: %precision 3
3639 In [2]: %precision 3
3640 Out[2]: u'%.3f'
3640 Out[2]: u'%.3f'
3641
3641
3642 In [3]: pi
3642 In [3]: pi
3643 Out[3]: 3.142
3643 Out[3]: 3.142
3644
3644
3645 In [4]: %precision %i
3645 In [4]: %precision %i
3646 Out[4]: u'%i'
3646 Out[4]: u'%i'
3647
3647
3648 In [5]: pi
3648 In [5]: pi
3649 Out[5]: 3
3649 Out[5]: 3
3650
3650
3651 In [6]: %precision %e
3651 In [6]: %precision %e
3652 Out[6]: u'%e'
3652 Out[6]: u'%e'
3653
3653
3654 In [7]: pi**10
3654 In [7]: pi**10
3655 Out[7]: 9.364805e+04
3655 Out[7]: 9.364805e+04
3656
3656
3657 In [8]: %precision
3657 In [8]: %precision
3658 Out[8]: u'%r'
3658 Out[8]: u'%r'
3659
3659
3660 In [9]: pi**10
3660 In [9]: pi**10
3661 Out[9]: 93648.047476082982
3661 Out[9]: 93648.047476082982
3662
3662
3663 """
3663 """
3664
3664
3665 ptformatter = self.shell.display_formatter.formatters['text/plain']
3665 ptformatter = self.shell.display_formatter.formatters['text/plain']
3666 ptformatter.float_precision = s
3666 ptformatter.float_precision = s
3667 return ptformatter.float_format
3667 return ptformatter.float_format
3668
3668
3669
3669
3670 @magic_arguments.magic_arguments()
3670 @magic_arguments.magic_arguments()
3671 @magic_arguments.argument(
3671 @magic_arguments.argument(
3672 '-e', '--export', action='store_true', default=False,
3672 '-e', '--export', action='store_true', default=False,
3673 help='Export IPython history as a notebook. The filename argument '
3673 help='Export IPython history as a notebook. The filename argument '
3674 'is used to specify the notebook name and format. For example '
3674 'is used to specify the notebook name and format. For example '
3675 'a filename of notebook.ipynb will result in a notebook name '
3675 'a filename of notebook.ipynb will result in a notebook name '
3676 'of "notebook" and a format of "xml". Likewise using a ".json" '
3676 'of "notebook" and a format of "xml". Likewise using a ".json" '
3677 'or ".py" file extension will write the notebook in the json '
3677 'or ".py" file extension will write the notebook in the json '
3678 'or py formats.'
3678 'or py formats.'
3679 )
3679 )
3680 @magic_arguments.argument(
3680 @magic_arguments.argument(
3681 '-f', '--format',
3681 '-f', '--format',
3682 help='Convert an existing IPython notebook to a new format. This option '
3682 help='Convert an existing IPython notebook to a new format. This option '
3683 'specifies the new format and can have the values: xml, json, py. '
3683 'specifies the new format and can have the values: xml, json, py. '
3684 'The target filename is chosen automatically based on the new '
3684 'The target filename is chosen automatically based on the new '
3685 'format. The filename argument gives the name of the source file.'
3685 'format. The filename argument gives the name of the source file.'
3686 )
3686 )
3687 @magic_arguments.argument(
3687 @magic_arguments.argument(
3688 'filename', type=unicode,
3688 'filename', type=unicode,
3689 help='Notebook name or filename'
3689 help='Notebook name or filename'
3690 )
3690 )
3691 def magic_notebook(self, s):
3691 def magic_notebook(self, s):
3692 """Export and convert IPython notebooks.
3692 """Export and convert IPython notebooks.
3693
3693
3694 This function can export the current IPython history to a notebook file
3694 This function can export the current IPython history to a notebook file
3695 or can convert an existing notebook file into a different format. For
3695 or can convert an existing notebook file into a different format. For
3696 example, to export the history to "foo.ipynb" do "%notebook -e foo.ipynb".
3696 example, to export the history to "foo.ipynb" do "%notebook -e foo.ipynb".
3697 To export the history to "foo.py" do "%notebook -e foo.py". To convert
3697 To export the history to "foo.py" do "%notebook -e foo.py". To convert
3698 "foo.ipynb" to "foo.json" do "%notebook -f json foo.ipynb". Possible
3698 "foo.ipynb" to "foo.json" do "%notebook -f json foo.ipynb". Possible
3699 formats include (json/ipynb, py).
3699 formats include (json/ipynb, py).
3700 """
3700 """
3701 args = magic_arguments.parse_argstring(self.magic_notebook, s)
3701 args = magic_arguments.parse_argstring(self.magic_notebook, s)
3702
3702
3703 from IPython.nbformat import current
3703 from IPython.nbformat import current
3704 args.filename = unquote_filename(args.filename)
3704 args.filename = unquote_filename(args.filename)
3705 if args.export:
3705 if args.export:
3706 fname, name, format = current.parse_filename(args.filename)
3706 fname, name, format = current.parse_filename(args.filename)
3707 cells = []
3707 cells = []
3708 hist = list(self.history_manager.get_range())
3708 hist = list(self.history_manager.get_range())
3709 for session, prompt_number, input in hist[:-1]:
3709 for session, prompt_number, input in hist[:-1]:
3710 cells.append(current.new_code_cell(prompt_number=prompt_number, input=input))
3710 cells.append(current.new_code_cell(prompt_number=prompt_number, input=input))
3711 worksheet = current.new_worksheet(cells=cells)
3711 worksheet = current.new_worksheet(cells=cells)
3712 nb = current.new_notebook(name=name,worksheets=[worksheet])
3712 nb = current.new_notebook(name=name,worksheets=[worksheet])
3713 with io.open(fname, 'w', encoding='utf-8') as f:
3713 with io.open(fname, 'w', encoding='utf-8') as f:
3714 current.write(nb, f, format);
3714 current.write(nb, f, format);
3715 elif args.format is not None:
3715 elif args.format is not None:
3716 old_fname, old_name, old_format = current.parse_filename(args.filename)
3716 old_fname, old_name, old_format = current.parse_filename(args.filename)
3717 new_format = args.format
3717 new_format = args.format
3718 if new_format == u'xml':
3718 if new_format == u'xml':
3719 raise ValueError('Notebooks cannot be written as xml.')
3719 raise ValueError('Notebooks cannot be written as xml.')
3720 elif new_format == u'ipynb' or new_format == u'json':
3720 elif new_format == u'ipynb' or new_format == u'json':
3721 new_fname = old_name + u'.ipynb'
3721 new_fname = old_name + u'.ipynb'
3722 new_format = u'json'
3722 new_format = u'json'
3723 elif new_format == u'py':
3723 elif new_format == u'py':
3724 new_fname = old_name + u'.py'
3724 new_fname = old_name + u'.py'
3725 else:
3725 else:
3726 raise ValueError('Invalid notebook format: %s' % new_format)
3726 raise ValueError('Invalid notebook format: %s' % new_format)
3727 with io.open(old_fname, 'r', encoding='utf-8') as f:
3727 with io.open(old_fname, 'r', encoding='utf-8') as f:
3728 nb = current.read(f, old_format)
3728 nb = current.read(f, old_format)
3729 with io.open(new_fname, 'w', encoding='utf-8') as f:
3729 with io.open(new_fname, 'w', encoding='utf-8') as f:
3730 current.write(nb, f, new_format)
3730 current.write(nb, f, new_format)
3731
3731
3732 def magic_config(self, s):
3732 def magic_config(self, s):
3733 """configure IPython
3733 """configure IPython
3734
3734
3735 %config Class[.trait=value]
3735 %config Class[.trait=value]
3736
3736
3737 This magic exposes most of the IPython config system. Any
3737 This magic exposes most of the IPython config system. Any
3738 Configurable class should be able to be configured with the simple
3738 Configurable class should be able to be configured with the simple
3739 line::
3739 line::
3740
3740
3741 %config Class.trait=value
3741 %config Class.trait=value
3742
3742
3743 Where `value` will be resolved in the user's namespace, if it is an
3743 Where `value` will be resolved in the user's namespace, if it is an
3744 expression or variable name.
3744 expression or variable name.
3745
3745
3746 Examples
3746 Examples
3747 --------
3747 --------
3748
3748
3749 To see what classes are available for config, pass no arguments::
3749 To see what classes are available for config, pass no arguments::
3750
3750
3751 In [1]: %config
3751 In [1]: %config
3752 Available objects for config:
3752 Available objects for config:
3753 TerminalInteractiveShell
3753 TerminalInteractiveShell
3754 HistoryManager
3754 HistoryManager
3755 PrefilterManager
3755 PrefilterManager
3756 AliasManager
3756 AliasManager
3757 IPCompleter
3757 IPCompleter
3758 PromptManager
3758 PromptManager
3759 DisplayFormatter
3759 DisplayFormatter
3760
3760
3761 To view what is configurable on a given class, just pass the class
3761 To view what is configurable on a given class, just pass the class
3762 name::
3762 name::
3763
3763
3764 In [2]: %config IPCompleter
3764 In [2]: %config IPCompleter
3765 IPCompleter options
3765 IPCompleter options
3766 -----------------
3766 -----------------
3767 IPCompleter.omit__names=<Enum>
3767 IPCompleter.omit__names=<Enum>
3768 Current: 2
3768 Current: 2
3769 Choices: (0, 1, 2)
3769 Choices: (0, 1, 2)
3770 Instruct the completer to omit private method names
3770 Instruct the completer to omit private method names
3771 Specifically, when completing on ``object.<tab>``.
3771 Specifically, when completing on ``object.<tab>``.
3772 When 2 [default]: all names that start with '_' will be excluded.
3772 When 2 [default]: all names that start with '_' will be excluded.
3773 When 1: all 'magic' names (``__foo__``) will be excluded.
3773 When 1: all 'magic' names (``__foo__``) will be excluded.
3774 When 0: nothing will be excluded.
3774 When 0: nothing will be excluded.
3775 IPCompleter.merge_completions=<CBool>
3775 IPCompleter.merge_completions=<CBool>
3776 Current: True
3776 Current: True
3777 Whether to merge completion results into a single list
3777 Whether to merge completion results into a single list
3778 If False, only the completion results from the first non-empty completer
3778 If False, only the completion results from the first non-empty completer
3779 will be returned.
3779 will be returned.
3780 IPCompleter.limit_to__all__=<CBool>
3780 IPCompleter.limit_to__all__=<CBool>
3781 Current: False
3781 Current: False
3782 Instruct the completer to use __all__ for the completion
3782 Instruct the completer to use __all__ for the completion
3783 Specifically, when completing on ``object.<tab>``.
3783 Specifically, when completing on ``object.<tab>``.
3784 When True: only those names in obj.__all__ will be included.
3784 When True: only those names in obj.__all__ will be included.
3785 When False [default]: the __all__ attribute is ignored
3785 When False [default]: the __all__ attribute is ignored
3786 IPCompleter.greedy=<CBool>
3786 IPCompleter.greedy=<CBool>
3787 Current: False
3787 Current: False
3788 Activate greedy completion
3788 Activate greedy completion
3789 This will enable completion on elements of lists, results of function calls,
3789 This will enable completion on elements of lists, results of function calls,
3790 etc., but can be unsafe because the code is actually evaluated on TAB.
3790 etc., but can be unsafe because the code is actually evaluated on TAB.
3791
3791
3792 but the real use is in setting values::
3792 but the real use is in setting values::
3793
3793
3794 In [3]: %config IPCompleter.greedy = True
3794 In [3]: %config IPCompleter.greedy = True
3795
3795
3796 and these values are read from the user_ns if they are variables::
3796 and these values are read from the user_ns if they are variables::
3797
3797
3798 In [4]: feeling_greedy=False
3798 In [4]: feeling_greedy=False
3799
3799
3800 In [5]: %config IPCompleter.greedy = feeling_greedy
3800 In [5]: %config IPCompleter.greedy = feeling_greedy
3801
3801
3802 """
3802 """
3803 from IPython.config.loader import Config
3803 from IPython.config.loader import Config
3804 # some IPython objects are Configurable, but do not yet have
3804 # some IPython objects are Configurable, but do not yet have
3805 # any configurable traits. Exclude them from the effects of
3805 # any configurable traits. Exclude them from the effects of
3806 # this magic, as their presence is just noise:
3806 # this magic, as their presence is just noise:
3807 configurables = [ c for c in self.configurables if c.__class__.class_traits(config=True) ]
3807 configurables = [ c for c in self.shell.configurables
3808 if c.__class__.class_traits(config=True) ]
3808 classnames = [ c.__class__.__name__ for c in configurables ]
3809 classnames = [ c.__class__.__name__ for c in configurables ]
3809
3810
3810 line = s.strip()
3811 line = s.strip()
3811 if not line:
3812 if not line:
3812 # print available configurable names
3813 # print available configurable names
3813 print "Available objects for config:"
3814 print "Available objects for config:"
3814 for name in classnames:
3815 for name in classnames:
3815 print " ", name
3816 print " ", name
3816 return
3817 return
3817 elif line in classnames:
3818 elif line in classnames:
3818 # `%config TerminalInteractiveShell` will print trait info for
3819 # `%config TerminalInteractiveShell` will print trait info for
3819 # TerminalInteractiveShell
3820 # TerminalInteractiveShell
3820 c = configurables[classnames.index(line)]
3821 c = configurables[classnames.index(line)]
3821 cls = c.__class__
3822 cls = c.__class__
3822 help = cls.class_get_help(c)
3823 help = cls.class_get_help(c)
3823 # strip leading '--' from cl-args:
3824 # strip leading '--' from cl-args:
3824 help = re.sub(re.compile(r'^--', re.MULTILINE), '', help)
3825 help = re.sub(re.compile(r'^--', re.MULTILINE), '', help)
3825 print help
3826 print help
3826 return
3827 return
3827 elif '=' not in line:
3828 elif '=' not in line:
3828 raise UsageError("Invalid config statement: %r, should be Class.trait = value" % line)
3829 raise UsageError("Invalid config statement: %r, should be Class.trait = value" % line)
3829
3830
3830
3831
3831 # otherwise, assume we are setting configurables.
3832 # otherwise, assume we are setting configurables.
3832 # leave quotes on args when splitting, because we want
3833 # leave quotes on args when splitting, because we want
3833 # unquoted args to eval in user_ns
3834 # unquoted args to eval in user_ns
3834 cfg = Config()
3835 cfg = Config()
3835 exec "cfg."+line in locals(), self.user_ns
3836 exec "cfg."+line in locals(), self.shell.user_ns
3836
3837
3837 for configurable in configurables:
3838 for configurable in configurables:
3838 try:
3839 try:
3839 configurable.update_config(cfg)
3840 configurable.update_config(cfg)
3840 except Exception as e:
3841 except Exception as e:
3841 error(e)
3842 error(e)
3842
3843
3843 # end Magic
3844 # end Magic
@@ -1,957 +1,957 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """
2 """
3 Prefiltering components.
3 Prefiltering components.
4
4
5 Prefilters transform user input before it is exec'd by Python. These
5 Prefilters transform user input before it is exec'd by Python. These
6 transforms are used to implement additional syntax such as !ls and %magic.
6 transforms are used to implement additional syntax such as !ls and %magic.
7
7
8 Authors:
8 Authors:
9
9
10 * Brian Granger
10 * Brian Granger
11 * Fernando Perez
11 * Fernando Perez
12 * Dan Milstein
12 * Dan Milstein
13 * Ville Vainio
13 * Ville Vainio
14 """
14 """
15
15
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17 # Copyright (C) 2008-2011 The IPython Development Team
17 # Copyright (C) 2008-2011 The IPython Development Team
18 #
18 #
19 # Distributed under the terms of the BSD License. The full license is in
19 # Distributed under the terms of the BSD License. The full license is in
20 # the file COPYING, distributed as part of this software.
20 # the file COPYING, distributed as part of this software.
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22
22
23 #-----------------------------------------------------------------------------
23 #-----------------------------------------------------------------------------
24 # Imports
24 # Imports
25 #-----------------------------------------------------------------------------
25 #-----------------------------------------------------------------------------
26
26
27 import __builtin__
27 import __builtin__
28 import codeop
28 import codeop
29 import re
29 import re
30
30
31 from IPython.core.alias import AliasManager
31 from IPython.core.alias import AliasManager
32 from IPython.core.autocall import IPyAutocall
32 from IPython.core.autocall import IPyAutocall
33 from IPython.config.configurable import Configurable
33 from IPython.config.configurable import Configurable
34 from IPython.core.macro import Macro
34 from IPython.core.macro import Macro
35 from IPython.core.splitinput import split_user_input, LineInfo
35 from IPython.core.splitinput import split_user_input, LineInfo
36 from IPython.core import page
36 from IPython.core import page
37
37
38 from IPython.utils.traitlets import (
38 from IPython.utils.traitlets import (
39 List, Integer, Any, Unicode, CBool, Bool, Instance, CRegExp
39 List, Integer, Any, Unicode, CBool, Bool, Instance, CRegExp
40 )
40 )
41 from IPython.utils.autoattr import auto_attr
41 from IPython.utils.autoattr import auto_attr
42
42
43 #-----------------------------------------------------------------------------
43 #-----------------------------------------------------------------------------
44 # Global utilities, errors and constants
44 # Global utilities, errors and constants
45 #-----------------------------------------------------------------------------
45 #-----------------------------------------------------------------------------
46
46
47 # Warning, these cannot be changed unless various regular expressions
47 # Warning, these cannot be changed unless various regular expressions
48 # are updated in a number of places. Not great, but at least we told you.
48 # are updated in a number of places. Not great, but at least we told you.
49 ESC_SHELL = '!'
49 ESC_SHELL = '!'
50 ESC_SH_CAP = '!!'
50 ESC_SH_CAP = '!!'
51 ESC_HELP = '?'
51 ESC_HELP = '?'
52 ESC_MAGIC = '%'
52 ESC_MAGIC = '%'
53 ESC_QUOTE = ','
53 ESC_QUOTE = ','
54 ESC_QUOTE2 = ';'
54 ESC_QUOTE2 = ';'
55 ESC_PAREN = '/'
55 ESC_PAREN = '/'
56
56
57
57
58 class PrefilterError(Exception):
58 class PrefilterError(Exception):
59 pass
59 pass
60
60
61
61
62 # RegExp to identify potential function names
62 # RegExp to identify potential function names
63 re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
63 re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
64
64
65 # RegExp to exclude strings with this start from autocalling. In
65 # RegExp to exclude strings with this start from autocalling. In
66 # particular, all binary operators should be excluded, so that if foo is
66 # particular, all binary operators should be excluded, so that if foo is
67 # callable, foo OP bar doesn't become foo(OP bar), which is invalid. The
67 # callable, foo OP bar doesn't become foo(OP bar), which is invalid. The
68 # characters '!=()' don't need to be checked for, as the checkPythonChars
68 # characters '!=()' don't need to be checked for, as the checkPythonChars
69 # routine explicitely does so, to catch direct calls and rebindings of
69 # routine explicitely does so, to catch direct calls and rebindings of
70 # existing names.
70 # existing names.
71
71
72 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
72 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
73 # it affects the rest of the group in square brackets.
73 # it affects the rest of the group in square brackets.
74 re_exclude_auto = re.compile(r'^[,&^\|\*/\+-]'
74 re_exclude_auto = re.compile(r'^[,&^\|\*/\+-]'
75 r'|^is |^not |^in |^and |^or ')
75 r'|^is |^not |^in |^and |^or ')
76
76
77 # try to catch also methods for stuff in lists/tuples/dicts: off
77 # try to catch also methods for stuff in lists/tuples/dicts: off
78 # (experimental). For this to work, the line_split regexp would need
78 # (experimental). For this to work, the line_split regexp would need
79 # to be modified so it wouldn't break things at '['. That line is
79 # to be modified so it wouldn't break things at '['. That line is
80 # nasty enough that I shouldn't change it until I can test it _well_.
80 # nasty enough that I shouldn't change it until I can test it _well_.
81 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
81 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
82
82
83
83
84 # Handler Check Utilities
84 # Handler Check Utilities
85 def is_shadowed(identifier, ip):
85 def is_shadowed(identifier, ip):
86 """Is the given identifier defined in one of the namespaces which shadow
86 """Is the given identifier defined in one of the namespaces which shadow
87 the alias and magic namespaces? Note that an identifier is different
87 the alias and magic namespaces? Note that an identifier is different
88 than ifun, because it can not contain a '.' character."""
88 than ifun, because it can not contain a '.' character."""
89 # This is much safer than calling ofind, which can change state
89 # This is much safer than calling ofind, which can change state
90 return (identifier in ip.user_ns \
90 return (identifier in ip.user_ns \
91 or identifier in ip.user_global_ns \
91 or identifier in ip.user_global_ns \
92 or identifier in ip.ns_table['builtin'])
92 or identifier in ip.ns_table['builtin'])
93
93
94
94
95 #-----------------------------------------------------------------------------
95 #-----------------------------------------------------------------------------
96 # Main Prefilter manager
96 # Main Prefilter manager
97 #-----------------------------------------------------------------------------
97 #-----------------------------------------------------------------------------
98
98
99
99
100 class PrefilterManager(Configurable):
100 class PrefilterManager(Configurable):
101 """Main prefilter component.
101 """Main prefilter component.
102
102
103 The IPython prefilter is run on all user input before it is run. The
103 The IPython prefilter is run on all user input before it is run. The
104 prefilter consumes lines of input and produces transformed lines of
104 prefilter consumes lines of input and produces transformed lines of
105 input.
105 input.
106
106
107 The iplementation consists of two phases:
107 The iplementation consists of two phases:
108
108
109 1. Transformers
109 1. Transformers
110 2. Checkers and handlers
110 2. Checkers and handlers
111
111
112 Over time, we plan on deprecating the checkers and handlers and doing
112 Over time, we plan on deprecating the checkers and handlers and doing
113 everything in the transformers.
113 everything in the transformers.
114
114
115 The transformers are instances of :class:`PrefilterTransformer` and have
115 The transformers are instances of :class:`PrefilterTransformer` and have
116 a single method :meth:`transform` that takes a line and returns a
116 a single method :meth:`transform` that takes a line and returns a
117 transformed line. The transformation can be accomplished using any
117 transformed line. The transformation can be accomplished using any
118 tool, but our current ones use regular expressions for speed. We also
118 tool, but our current ones use regular expressions for speed. We also
119 ship :mod:`pyparsing` in :mod:`IPython.external` for use in transformers.
119 ship :mod:`pyparsing` in :mod:`IPython.external` for use in transformers.
120
120
121 After all the transformers have been run, the line is fed to the checkers,
121 After all the transformers have been run, the line is fed to the checkers,
122 which are instances of :class:`PrefilterChecker`. The line is passed to
122 which are instances of :class:`PrefilterChecker`. The line is passed to
123 the :meth:`check` method, which either returns `None` or a
123 the :meth:`check` method, which either returns `None` or a
124 :class:`PrefilterHandler` instance. If `None` is returned, the other
124 :class:`PrefilterHandler` instance. If `None` is returned, the other
125 checkers are tried. If an :class:`PrefilterHandler` instance is returned,
125 checkers are tried. If an :class:`PrefilterHandler` instance is returned,
126 the line is passed to the :meth:`handle` method of the returned
126 the line is passed to the :meth:`handle` method of the returned
127 handler and no further checkers are tried.
127 handler and no further checkers are tried.
128
128
129 Both transformers and checkers have a `priority` attribute, that determines
129 Both transformers and checkers have a `priority` attribute, that determines
130 the order in which they are called. Smaller priorities are tried first.
130 the order in which they are called. Smaller priorities are tried first.
131
131
132 Both transformers and checkers also have `enabled` attribute, which is
132 Both transformers and checkers also have `enabled` attribute, which is
133 a boolean that determines if the instance is used.
133 a boolean that determines if the instance is used.
134
134
135 Users or developers can change the priority or enabled attribute of
135 Users or developers can change the priority or enabled attribute of
136 transformers or checkers, but they must call the :meth:`sort_checkers`
136 transformers or checkers, but they must call the :meth:`sort_checkers`
137 or :meth:`sort_transformers` method after changing the priority.
137 or :meth:`sort_transformers` method after changing the priority.
138 """
138 """
139
139
140 multi_line_specials = CBool(True, config=True)
140 multi_line_specials = CBool(True, config=True)
141 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
141 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
142
142
143 def __init__(self, shell=None, config=None):
143 def __init__(self, shell=None, config=None):
144 super(PrefilterManager, self).__init__(shell=shell, config=config)
144 super(PrefilterManager, self).__init__(shell=shell, config=config)
145 self.shell = shell
145 self.shell = shell
146 self.init_transformers()
146 self.init_transformers()
147 self.init_handlers()
147 self.init_handlers()
148 self.init_checkers()
148 self.init_checkers()
149
149
150 #-------------------------------------------------------------------------
150 #-------------------------------------------------------------------------
151 # API for managing transformers
151 # API for managing transformers
152 #-------------------------------------------------------------------------
152 #-------------------------------------------------------------------------
153
153
154 def init_transformers(self):
154 def init_transformers(self):
155 """Create the default transformers."""
155 """Create the default transformers."""
156 self._transformers = []
156 self._transformers = []
157 for transformer_cls in _default_transformers:
157 for transformer_cls in _default_transformers:
158 transformer_cls(
158 transformer_cls(
159 shell=self.shell, prefilter_manager=self, config=self.config
159 shell=self.shell, prefilter_manager=self, config=self.config
160 )
160 )
161
161
162 def sort_transformers(self):
162 def sort_transformers(self):
163 """Sort the transformers by priority.
163 """Sort the transformers by priority.
164
164
165 This must be called after the priority of a transformer is changed.
165 This must be called after the priority of a transformer is changed.
166 The :meth:`register_transformer` method calls this automatically.
166 The :meth:`register_transformer` method calls this automatically.
167 """
167 """
168 self._transformers.sort(key=lambda x: x.priority)
168 self._transformers.sort(key=lambda x: x.priority)
169
169
170 @property
170 @property
171 def transformers(self):
171 def transformers(self):
172 """Return a list of checkers, sorted by priority."""
172 """Return a list of checkers, sorted by priority."""
173 return self._transformers
173 return self._transformers
174
174
175 def register_transformer(self, transformer):
175 def register_transformer(self, transformer):
176 """Register a transformer instance."""
176 """Register a transformer instance."""
177 if transformer not in self._transformers:
177 if transformer not in self._transformers:
178 self._transformers.append(transformer)
178 self._transformers.append(transformer)
179 self.sort_transformers()
179 self.sort_transformers()
180
180
181 def unregister_transformer(self, transformer):
181 def unregister_transformer(self, transformer):
182 """Unregister a transformer instance."""
182 """Unregister a transformer instance."""
183 if transformer in self._transformers:
183 if transformer in self._transformers:
184 self._transformers.remove(transformer)
184 self._transformers.remove(transformer)
185
185
186 #-------------------------------------------------------------------------
186 #-------------------------------------------------------------------------
187 # API for managing checkers
187 # API for managing checkers
188 #-------------------------------------------------------------------------
188 #-------------------------------------------------------------------------
189
189
190 def init_checkers(self):
190 def init_checkers(self):
191 """Create the default checkers."""
191 """Create the default checkers."""
192 self._checkers = []
192 self._checkers = []
193 for checker in _default_checkers:
193 for checker in _default_checkers:
194 checker(
194 checker(
195 shell=self.shell, prefilter_manager=self, config=self.config
195 shell=self.shell, prefilter_manager=self, config=self.config
196 )
196 )
197
197
198 def sort_checkers(self):
198 def sort_checkers(self):
199 """Sort the checkers by priority.
199 """Sort the checkers by priority.
200
200
201 This must be called after the priority of a checker is changed.
201 This must be called after the priority of a checker is changed.
202 The :meth:`register_checker` method calls this automatically.
202 The :meth:`register_checker` method calls this automatically.
203 """
203 """
204 self._checkers.sort(key=lambda x: x.priority)
204 self._checkers.sort(key=lambda x: x.priority)
205
205
206 @property
206 @property
207 def checkers(self):
207 def checkers(self):
208 """Return a list of checkers, sorted by priority."""
208 """Return a list of checkers, sorted by priority."""
209 return self._checkers
209 return self._checkers
210
210
211 def register_checker(self, checker):
211 def register_checker(self, checker):
212 """Register a checker instance."""
212 """Register a checker instance."""
213 if checker not in self._checkers:
213 if checker not in self._checkers:
214 self._checkers.append(checker)
214 self._checkers.append(checker)
215 self.sort_checkers()
215 self.sort_checkers()
216
216
217 def unregister_checker(self, checker):
217 def unregister_checker(self, checker):
218 """Unregister a checker instance."""
218 """Unregister a checker instance."""
219 if checker in self._checkers:
219 if checker in self._checkers:
220 self._checkers.remove(checker)
220 self._checkers.remove(checker)
221
221
222 #-------------------------------------------------------------------------
222 #-------------------------------------------------------------------------
223 # API for managing checkers
223 # API for managing checkers
224 #-------------------------------------------------------------------------
224 #-------------------------------------------------------------------------
225
225
226 def init_handlers(self):
226 def init_handlers(self):
227 """Create the default handlers."""
227 """Create the default handlers."""
228 self._handlers = {}
228 self._handlers = {}
229 self._esc_handlers = {}
229 self._esc_handlers = {}
230 for handler in _default_handlers:
230 for handler in _default_handlers:
231 handler(
231 handler(
232 shell=self.shell, prefilter_manager=self, config=self.config
232 shell=self.shell, prefilter_manager=self, config=self.config
233 )
233 )
234
234
235 @property
235 @property
236 def handlers(self):
236 def handlers(self):
237 """Return a dict of all the handlers."""
237 """Return a dict of all the handlers."""
238 return self._handlers
238 return self._handlers
239
239
240 def register_handler(self, name, handler, esc_strings):
240 def register_handler(self, name, handler, esc_strings):
241 """Register a handler instance by name with esc_strings."""
241 """Register a handler instance by name with esc_strings."""
242 self._handlers[name] = handler
242 self._handlers[name] = handler
243 for esc_str in esc_strings:
243 for esc_str in esc_strings:
244 self._esc_handlers[esc_str] = handler
244 self._esc_handlers[esc_str] = handler
245
245
246 def unregister_handler(self, name, handler, esc_strings):
246 def unregister_handler(self, name, handler, esc_strings):
247 """Unregister a handler instance by name with esc_strings."""
247 """Unregister a handler instance by name with esc_strings."""
248 try:
248 try:
249 del self._handlers[name]
249 del self._handlers[name]
250 except KeyError:
250 except KeyError:
251 pass
251 pass
252 for esc_str in esc_strings:
252 for esc_str in esc_strings:
253 h = self._esc_handlers.get(esc_str)
253 h = self._esc_handlers.get(esc_str)
254 if h is handler:
254 if h is handler:
255 del self._esc_handlers[esc_str]
255 del self._esc_handlers[esc_str]
256
256
257 def get_handler_by_name(self, name):
257 def get_handler_by_name(self, name):
258 """Get a handler by its name."""
258 """Get a handler by its name."""
259 return self._handlers.get(name)
259 return self._handlers.get(name)
260
260
261 def get_handler_by_esc(self, esc_str):
261 def get_handler_by_esc(self, esc_str):
262 """Get a handler by its escape string."""
262 """Get a handler by its escape string."""
263 return self._esc_handlers.get(esc_str)
263 return self._esc_handlers.get(esc_str)
264
264
265 #-------------------------------------------------------------------------
265 #-------------------------------------------------------------------------
266 # Main prefiltering API
266 # Main prefiltering API
267 #-------------------------------------------------------------------------
267 #-------------------------------------------------------------------------
268
268
269 def prefilter_line_info(self, line_info):
269 def prefilter_line_info(self, line_info):
270 """Prefilter a line that has been converted to a LineInfo object.
270 """Prefilter a line that has been converted to a LineInfo object.
271
271
272 This implements the checker/handler part of the prefilter pipe.
272 This implements the checker/handler part of the prefilter pipe.
273 """
273 """
274 # print "prefilter_line_info: ", line_info
274 # print "prefilter_line_info: ", line_info
275 handler = self.find_handler(line_info)
275 handler = self.find_handler(line_info)
276 return handler.handle(line_info)
276 return handler.handle(line_info)
277
277
278 def find_handler(self, line_info):
278 def find_handler(self, line_info):
279 """Find a handler for the line_info by trying checkers."""
279 """Find a handler for the line_info by trying checkers."""
280 for checker in self.checkers:
280 for checker in self.checkers:
281 if checker.enabled:
281 if checker.enabled:
282 handler = checker.check(line_info)
282 handler = checker.check(line_info)
283 if handler:
283 if handler:
284 return handler
284 return handler
285 return self.get_handler_by_name('normal')
285 return self.get_handler_by_name('normal')
286
286
287 def transform_line(self, line, continue_prompt):
287 def transform_line(self, line, continue_prompt):
288 """Calls the enabled transformers in order of increasing priority."""
288 """Calls the enabled transformers in order of increasing priority."""
289 for transformer in self.transformers:
289 for transformer in self.transformers:
290 if transformer.enabled:
290 if transformer.enabled:
291 line = transformer.transform(line, continue_prompt)
291 line = transformer.transform(line, continue_prompt)
292 return line
292 return line
293
293
294 def prefilter_line(self, line, continue_prompt=False):
294 def prefilter_line(self, line, continue_prompt=False):
295 """Prefilter a single input line as text.
295 """Prefilter a single input line as text.
296
296
297 This method prefilters a single line of text by calling the
297 This method prefilters a single line of text by calling the
298 transformers and then the checkers/handlers.
298 transformers and then the checkers/handlers.
299 """
299 """
300
300
301 # print "prefilter_line: ", line, continue_prompt
301 # print "prefilter_line: ", line, continue_prompt
302 # All handlers *must* return a value, even if it's blank ('').
302 # All handlers *must* return a value, even if it's blank ('').
303
303
304 # save the line away in case we crash, so the post-mortem handler can
304 # save the line away in case we crash, so the post-mortem handler can
305 # record it
305 # record it
306 self.shell._last_input_line = line
306 self.shell._last_input_line = line
307
307
308 if not line:
308 if not line:
309 # Return immediately on purely empty lines, so that if the user
309 # Return immediately on purely empty lines, so that if the user
310 # previously typed some whitespace that started a continuation
310 # previously typed some whitespace that started a continuation
311 # prompt, he can break out of that loop with just an empty line.
311 # prompt, he can break out of that loop with just an empty line.
312 # This is how the default python prompt works.
312 # This is how the default python prompt works.
313 return ''
313 return ''
314
314
315 # At this point, we invoke our transformers.
315 # At this point, we invoke our transformers.
316 if not continue_prompt or (continue_prompt and self.multi_line_specials):
316 if not continue_prompt or (continue_prompt and self.multi_line_specials):
317 line = self.transform_line(line, continue_prompt)
317 line = self.transform_line(line, continue_prompt)
318
318
319 # Now we compute line_info for the checkers and handlers
319 # Now we compute line_info for the checkers and handlers
320 line_info = LineInfo(line, continue_prompt)
320 line_info = LineInfo(line, continue_prompt)
321
321
322 # the input history needs to track even empty lines
322 # the input history needs to track even empty lines
323 stripped = line.strip()
323 stripped = line.strip()
324
324
325 normal_handler = self.get_handler_by_name('normal')
325 normal_handler = self.get_handler_by_name('normal')
326 if not stripped:
326 if not stripped:
327 if not continue_prompt:
327 if not continue_prompt:
328 self.shell.displayhook.prompt_count -= 1
328 self.shell.displayhook.prompt_count -= 1
329
329
330 return normal_handler.handle(line_info)
330 return normal_handler.handle(line_info)
331
331
332 # special handlers are only allowed for single line statements
332 # special handlers are only allowed for single line statements
333 if continue_prompt and not self.multi_line_specials:
333 if continue_prompt and not self.multi_line_specials:
334 return normal_handler.handle(line_info)
334 return normal_handler.handle(line_info)
335
335
336 prefiltered = self.prefilter_line_info(line_info)
336 prefiltered = self.prefilter_line_info(line_info)
337 # print "prefiltered line: %r" % prefiltered
337 # print "prefiltered line: %r" % prefiltered
338 return prefiltered
338 return prefiltered
339
339
340 def prefilter_lines(self, lines, continue_prompt=False):
340 def prefilter_lines(self, lines, continue_prompt=False):
341 """Prefilter multiple input lines of text.
341 """Prefilter multiple input lines of text.
342
342
343 This is the main entry point for prefiltering multiple lines of
343 This is the main entry point for prefiltering multiple lines of
344 input. This simply calls :meth:`prefilter_line` for each line of
344 input. This simply calls :meth:`prefilter_line` for each line of
345 input.
345 input.
346
346
347 This covers cases where there are multiple lines in the user entry,
347 This covers cases where there are multiple lines in the user entry,
348 which is the case when the user goes back to a multiline history
348 which is the case when the user goes back to a multiline history
349 entry and presses enter.
349 entry and presses enter.
350 """
350 """
351 llines = lines.rstrip('\n').split('\n')
351 llines = lines.rstrip('\n').split('\n')
352 # We can get multiple lines in one shot, where multiline input 'blends'
352 # We can get multiple lines in one shot, where multiline input 'blends'
353 # into one line, in cases like recalling from the readline history
353 # into one line, in cases like recalling from the readline history
354 # buffer. We need to make sure that in such cases, we correctly
354 # buffer. We need to make sure that in such cases, we correctly
355 # communicate downstream which line is first and which are continuation
355 # communicate downstream which line is first and which are continuation
356 # ones.
356 # ones.
357 if len(llines) > 1:
357 if len(llines) > 1:
358 out = '\n'.join([self.prefilter_line(line, lnum>0)
358 out = '\n'.join([self.prefilter_line(line, lnum>0)
359 for lnum, line in enumerate(llines) ])
359 for lnum, line in enumerate(llines) ])
360 else:
360 else:
361 out = self.prefilter_line(llines[0], continue_prompt)
361 out = self.prefilter_line(llines[0], continue_prompt)
362
362
363 return out
363 return out
364
364
365 #-----------------------------------------------------------------------------
365 #-----------------------------------------------------------------------------
366 # Prefilter transformers
366 # Prefilter transformers
367 #-----------------------------------------------------------------------------
367 #-----------------------------------------------------------------------------
368
368
369
369
370 class PrefilterTransformer(Configurable):
370 class PrefilterTransformer(Configurable):
371 """Transform a line of user input."""
371 """Transform a line of user input."""
372
372
373 priority = Integer(100, config=True)
373 priority = Integer(100, config=True)
374 # Transformers don't currently use shell or prefilter_manager, but as we
374 # Transformers don't currently use shell or prefilter_manager, but as we
375 # move away from checkers and handlers, they will need them.
375 # move away from checkers and handlers, they will need them.
376 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
376 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
377 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
377 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
378 enabled = Bool(True, config=True)
378 enabled = Bool(True, config=True)
379
379
380 def __init__(self, shell=None, prefilter_manager=None, config=None):
380 def __init__(self, shell=None, prefilter_manager=None, config=None):
381 super(PrefilterTransformer, self).__init__(
381 super(PrefilterTransformer, self).__init__(
382 shell=shell, prefilter_manager=prefilter_manager, config=config
382 shell=shell, prefilter_manager=prefilter_manager, config=config
383 )
383 )
384 self.prefilter_manager.register_transformer(self)
384 self.prefilter_manager.register_transformer(self)
385
385
386 def transform(self, line, continue_prompt):
386 def transform(self, line, continue_prompt):
387 """Transform a line, returning the new one."""
387 """Transform a line, returning the new one."""
388 return None
388 return None
389
389
390 def __repr__(self):
390 def __repr__(self):
391 return "<%s(priority=%r, enabled=%r)>" % (
391 return "<%s(priority=%r, enabled=%r)>" % (
392 self.__class__.__name__, self.priority, self.enabled)
392 self.__class__.__name__, self.priority, self.enabled)
393
393
394
394
395 _assign_system_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
395 _assign_system_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
396 r'\s*=\s*!(?P<cmd>.*)')
396 r'\s*=\s*!(?P<cmd>.*)')
397
397
398
398
399 class AssignSystemTransformer(PrefilterTransformer):
399 class AssignSystemTransformer(PrefilterTransformer):
400 """Handle the `files = !ls` syntax."""
400 """Handle the `files = !ls` syntax."""
401
401
402 priority = Integer(100, config=True)
402 priority = Integer(100, config=True)
403
403
404 def transform(self, line, continue_prompt):
404 def transform(self, line, continue_prompt):
405 m = _assign_system_re.match(line)
405 m = _assign_system_re.match(line)
406 if m is not None:
406 if m is not None:
407 cmd = m.group('cmd')
407 cmd = m.group('cmd')
408 lhs = m.group('lhs')
408 lhs = m.group('lhs')
409 expr = "sc =%s" % cmd
409 expr = "sc =%s" % cmd
410 new_line = '%s = get_ipython().magic(%r)' % (lhs, expr)
410 new_line = '%s = get_ipython().magic(%r)' % (lhs, expr)
411 return new_line
411 return new_line
412 return line
412 return line
413
413
414
414
415 _assign_magic_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
415 _assign_magic_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
416 r'\s*=\s*%(?P<cmd>.*)')
416 r'\s*=\s*%(?P<cmd>.*)')
417
417
418 class AssignMagicTransformer(PrefilterTransformer):
418 class AssignMagicTransformer(PrefilterTransformer):
419 """Handle the `a = %who` syntax."""
419 """Handle the `a = %who` syntax."""
420
420
421 priority = Integer(200, config=True)
421 priority = Integer(200, config=True)
422
422
423 def transform(self, line, continue_prompt):
423 def transform(self, line, continue_prompt):
424 m = _assign_magic_re.match(line)
424 m = _assign_magic_re.match(line)
425 if m is not None:
425 if m is not None:
426 cmd = m.group('cmd')
426 cmd = m.group('cmd')
427 lhs = m.group('lhs')
427 lhs = m.group('lhs')
428 new_line = '%s = get_ipython().magic(%r)' % (lhs, cmd)
428 new_line = '%s = get_ipython().magic(%r)' % (lhs, cmd)
429 return new_line
429 return new_line
430 return line
430 return line
431
431
432
432
433 _classic_prompt_re = re.compile(r'(^[ \t]*>>> |^[ \t]*\.\.\. )')
433 _classic_prompt_re = re.compile(r'(^[ \t]*>>> |^[ \t]*\.\.\. )')
434
434
435 class PyPromptTransformer(PrefilterTransformer):
435 class PyPromptTransformer(PrefilterTransformer):
436 """Handle inputs that start with '>>> ' syntax."""
436 """Handle inputs that start with '>>> ' syntax."""
437
437
438 priority = Integer(50, config=True)
438 priority = Integer(50, config=True)
439
439
440 def transform(self, line, continue_prompt):
440 def transform(self, line, continue_prompt):
441
441
442 if not line or line.isspace() or line.strip() == '...':
442 if not line or line.isspace() or line.strip() == '...':
443 # This allows us to recognize multiple input prompts separated by
443 # This allows us to recognize multiple input prompts separated by
444 # blank lines and pasted in a single chunk, very common when
444 # blank lines and pasted in a single chunk, very common when
445 # pasting doctests or long tutorial passages.
445 # pasting doctests or long tutorial passages.
446 return ''
446 return ''
447 m = _classic_prompt_re.match(line)
447 m = _classic_prompt_re.match(line)
448 if m:
448 if m:
449 return line[len(m.group(0)):]
449 return line[len(m.group(0)):]
450 else:
450 else:
451 return line
451 return line
452
452
453
453
454 _ipy_prompt_re = re.compile(r'(^[ \t]*In \[\d+\]: |^[ \t]*\ \ \ \.\.\.+: )')
454 _ipy_prompt_re = re.compile(r'(^[ \t]*In \[\d+\]: |^[ \t]*\ \ \ \.\.\.+: )')
455
455
456 class IPyPromptTransformer(PrefilterTransformer):
456 class IPyPromptTransformer(PrefilterTransformer):
457 """Handle inputs that start classic IPython prompt syntax."""
457 """Handle inputs that start classic IPython prompt syntax."""
458
458
459 priority = Integer(50, config=True)
459 priority = Integer(50, config=True)
460
460
461 def transform(self, line, continue_prompt):
461 def transform(self, line, continue_prompt):
462
462
463 if not line or line.isspace() or line.strip() == '...':
463 if not line or line.isspace() or line.strip() == '...':
464 # This allows us to recognize multiple input prompts separated by
464 # This allows us to recognize multiple input prompts separated by
465 # blank lines and pasted in a single chunk, very common when
465 # blank lines and pasted in a single chunk, very common when
466 # pasting doctests or long tutorial passages.
466 # pasting doctests or long tutorial passages.
467 return ''
467 return ''
468 m = _ipy_prompt_re.match(line)
468 m = _ipy_prompt_re.match(line)
469 if m:
469 if m:
470 return line[len(m.group(0)):]
470 return line[len(m.group(0)):]
471 else:
471 else:
472 return line
472 return line
473
473
474 #-----------------------------------------------------------------------------
474 #-----------------------------------------------------------------------------
475 # Prefilter checkers
475 # Prefilter checkers
476 #-----------------------------------------------------------------------------
476 #-----------------------------------------------------------------------------
477
477
478
478
479 class PrefilterChecker(Configurable):
479 class PrefilterChecker(Configurable):
480 """Inspect an input line and return a handler for that line."""
480 """Inspect an input line and return a handler for that line."""
481
481
482 priority = Integer(100, config=True)
482 priority = Integer(100, config=True)
483 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
483 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
484 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
484 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
485 enabled = Bool(True, config=True)
485 enabled = Bool(True, config=True)
486
486
487 def __init__(self, shell=None, prefilter_manager=None, config=None):
487 def __init__(self, shell=None, prefilter_manager=None, config=None):
488 super(PrefilterChecker, self).__init__(
488 super(PrefilterChecker, self).__init__(
489 shell=shell, prefilter_manager=prefilter_manager, config=config
489 shell=shell, prefilter_manager=prefilter_manager, config=config
490 )
490 )
491 self.prefilter_manager.register_checker(self)
491 self.prefilter_manager.register_checker(self)
492
492
493 def check(self, line_info):
493 def check(self, line_info):
494 """Inspect line_info and return a handler instance or None."""
494 """Inspect line_info and return a handler instance or None."""
495 return None
495 return None
496
496
497 def __repr__(self):
497 def __repr__(self):
498 return "<%s(priority=%r, enabled=%r)>" % (
498 return "<%s(priority=%r, enabled=%r)>" % (
499 self.__class__.__name__, self.priority, self.enabled)
499 self.__class__.__name__, self.priority, self.enabled)
500
500
501
501
502 class EmacsChecker(PrefilterChecker):
502 class EmacsChecker(PrefilterChecker):
503
503
504 priority = Integer(100, config=True)
504 priority = Integer(100, config=True)
505 enabled = Bool(False, config=True)
505 enabled = Bool(False, config=True)
506
506
507 def check(self, line_info):
507 def check(self, line_info):
508 "Emacs ipython-mode tags certain input lines."
508 "Emacs ipython-mode tags certain input lines."
509 if line_info.line.endswith('# PYTHON-MODE'):
509 if line_info.line.endswith('# PYTHON-MODE'):
510 return self.prefilter_manager.get_handler_by_name('emacs')
510 return self.prefilter_manager.get_handler_by_name('emacs')
511 else:
511 else:
512 return None
512 return None
513
513
514
514
515 class ShellEscapeChecker(PrefilterChecker):
515 class ShellEscapeChecker(PrefilterChecker):
516
516
517 priority = Integer(200, config=True)
517 priority = Integer(200, config=True)
518
518
519 def check(self, line_info):
519 def check(self, line_info):
520 if line_info.line.lstrip().startswith(ESC_SHELL):
520 if line_info.line.lstrip().startswith(ESC_SHELL):
521 return self.prefilter_manager.get_handler_by_name('shell')
521 return self.prefilter_manager.get_handler_by_name('shell')
522
522
523
523
524 class MacroChecker(PrefilterChecker):
524 class MacroChecker(PrefilterChecker):
525
525
526 priority = Integer(250, config=True)
526 priority = Integer(250, config=True)
527
527
528 def check(self, line_info):
528 def check(self, line_info):
529 obj = self.shell.user_ns.get(line_info.ifun)
529 obj = self.shell.user_ns.get(line_info.ifun)
530 if isinstance(obj, Macro):
530 if isinstance(obj, Macro):
531 return self.prefilter_manager.get_handler_by_name('macro')
531 return self.prefilter_manager.get_handler_by_name('macro')
532 else:
532 else:
533 return None
533 return None
534
534
535
535
536 class IPyAutocallChecker(PrefilterChecker):
536 class IPyAutocallChecker(PrefilterChecker):
537
537
538 priority = Integer(300, config=True)
538 priority = Integer(300, config=True)
539
539
540 def check(self, line_info):
540 def check(self, line_info):
541 "Instances of IPyAutocall in user_ns get autocalled immediately"
541 "Instances of IPyAutocall in user_ns get autocalled immediately"
542 obj = self.shell.user_ns.get(line_info.ifun, None)
542 obj = self.shell.user_ns.get(line_info.ifun, None)
543 if isinstance(obj, IPyAutocall):
543 if isinstance(obj, IPyAutocall):
544 obj.set_ip(self.shell)
544 obj.set_ip(self.shell)
545 return self.prefilter_manager.get_handler_by_name('auto')
545 return self.prefilter_manager.get_handler_by_name('auto')
546 else:
546 else:
547 return None
547 return None
548
548
549
549
550 class MultiLineMagicChecker(PrefilterChecker):
550 class MultiLineMagicChecker(PrefilterChecker):
551
551
552 priority = Integer(400, config=True)
552 priority = Integer(400, config=True)
553
553
554 def check(self, line_info):
554 def check(self, line_info):
555 "Allow ! and !! in multi-line statements if multi_line_specials is on"
555 "Allow ! and !! in multi-line statements if multi_line_specials is on"
556 # Note that this one of the only places we check the first character of
556 # Note that this one of the only places we check the first character of
557 # ifun and *not* the pre_char. Also note that the below test matches
557 # ifun and *not* the pre_char. Also note that the below test matches
558 # both ! and !!.
558 # both ! and !!.
559 if line_info.continue_prompt \
559 if line_info.continue_prompt \
560 and self.prefilter_manager.multi_line_specials:
560 and self.prefilter_manager.multi_line_specials:
561 if line_info.esc == ESC_MAGIC:
561 if line_info.esc == ESC_MAGIC:
562 return self.prefilter_manager.get_handler_by_name('magic')
562 return self.prefilter_manager.get_handler_by_name('magic')
563 else:
563 else:
564 return None
564 return None
565
565
566
566
567 class EscCharsChecker(PrefilterChecker):
567 class EscCharsChecker(PrefilterChecker):
568
568
569 priority = Integer(500, config=True)
569 priority = Integer(500, config=True)
570
570
571 def check(self, line_info):
571 def check(self, line_info):
572 """Check for escape character and return either a handler to handle it,
572 """Check for escape character and return either a handler to handle it,
573 or None if there is no escape char."""
573 or None if there is no escape char."""
574 if line_info.line[-1] == ESC_HELP \
574 if line_info.line[-1] == ESC_HELP \
575 and line_info.esc != ESC_SHELL \
575 and line_info.esc != ESC_SHELL \
576 and line_info.esc != ESC_SH_CAP:
576 and line_info.esc != ESC_SH_CAP:
577 # the ? can be at the end, but *not* for either kind of shell escape,
577 # the ? can be at the end, but *not* for either kind of shell escape,
578 # because a ? can be a vaild final char in a shell cmd
578 # because a ? can be a vaild final char in a shell cmd
579 return self.prefilter_manager.get_handler_by_name('help')
579 return self.prefilter_manager.get_handler_by_name('help')
580 else:
580 else:
581 if line_info.pre:
581 if line_info.pre:
582 return None
582 return None
583 # This returns None like it should if no handler exists
583 # This returns None like it should if no handler exists
584 return self.prefilter_manager.get_handler_by_esc(line_info.esc)
584 return self.prefilter_manager.get_handler_by_esc(line_info.esc)
585
585
586
586
587 class AssignmentChecker(PrefilterChecker):
587 class AssignmentChecker(PrefilterChecker):
588
588
589 priority = Integer(600, config=True)
589 priority = Integer(600, config=True)
590
590
591 def check(self, line_info):
591 def check(self, line_info):
592 """Check to see if user is assigning to a var for the first time, in
592 """Check to see if user is assigning to a var for the first time, in
593 which case we want to avoid any sort of automagic / autocall games.
593 which case we want to avoid any sort of automagic / autocall games.
594
594
595 This allows users to assign to either alias or magic names true python
595 This allows users to assign to either alias or magic names true python
596 variables (the magic/alias systems always take second seat to true
596 variables (the magic/alias systems always take second seat to true
597 python code). E.g. ls='hi', or ls,that=1,2"""
597 python code). E.g. ls='hi', or ls,that=1,2"""
598 if line_info.the_rest:
598 if line_info.the_rest:
599 if line_info.the_rest[0] in '=,':
599 if line_info.the_rest[0] in '=,':
600 return self.prefilter_manager.get_handler_by_name('normal')
600 return self.prefilter_manager.get_handler_by_name('normal')
601 else:
601 else:
602 return None
602 return None
603
603
604
604
605 class AutoMagicChecker(PrefilterChecker):
605 class AutoMagicChecker(PrefilterChecker):
606
606
607 priority = Integer(700, config=True)
607 priority = Integer(700, config=True)
608
608
609 def check(self, line_info):
609 def check(self, line_info):
610 """If the ifun is magic, and automagic is on, run it. Note: normal,
610 """If the ifun is magic, and automagic is on, run it. Note: normal,
611 non-auto magic would already have been triggered via '%' in
611 non-auto magic would already have been triggered via '%' in
612 check_esc_chars. This just checks for automagic. Also, before
612 check_esc_chars. This just checks for automagic. Also, before
613 triggering the magic handler, make sure that there is nothing in the
613 triggering the magic handler, make sure that there is nothing in the
614 user namespace which could shadow it."""
614 user namespace which could shadow it."""
615 if not self.shell.automagic or not self.shell.find_magic(line_info.ifun):
615 if not self.shell.automagic or not self.shell.find_magic(line_info.ifun):
616 return None
616 return None
617
617
618 # We have a likely magic method. Make sure we should actually call it.
618 # We have a likely magic method. Make sure we should actually call it.
619 if line_info.continue_prompt and not self.prefilter_manager.multi_line_specials:
619 if line_info.continue_prompt and not self.prefilter_manager.multi_line_specials:
620 return None
620 return None
621
621
622 head = line_info.ifun.split('.',1)[0]
622 head = line_info.ifun.split('.',1)[0]
623 if is_shadowed(head, self.shell):
623 if is_shadowed(head, self.shell):
624 return None
624 return None
625
625
626 return self.prefilter_manager.get_handler_by_name('magic')
626 return self.prefilter_manager.get_handler_by_name('magic')
627
627
628
628
629 class AliasChecker(PrefilterChecker):
629 class AliasChecker(PrefilterChecker):
630
630
631 priority = Integer(800, config=True)
631 priority = Integer(800, config=True)
632
632
633 def check(self, line_info):
633 def check(self, line_info):
634 "Check if the initital identifier on the line is an alias."
634 "Check if the initital identifier on the line is an alias."
635 # Note: aliases can not contain '.'
635 # Note: aliases can not contain '.'
636 head = line_info.ifun.split('.',1)[0]
636 head = line_info.ifun.split('.',1)[0]
637 if line_info.ifun not in self.shell.alias_manager \
637 if line_info.ifun not in self.shell.alias_manager \
638 or head not in self.shell.alias_manager \
638 or head not in self.shell.alias_manager \
639 or is_shadowed(head, self.shell):
639 or is_shadowed(head, self.shell):
640 return None
640 return None
641
641
642 return self.prefilter_manager.get_handler_by_name('alias')
642 return self.prefilter_manager.get_handler_by_name('alias')
643
643
644
644
645 class PythonOpsChecker(PrefilterChecker):
645 class PythonOpsChecker(PrefilterChecker):
646
646
647 priority = Integer(900, config=True)
647 priority = Integer(900, config=True)
648
648
649 def check(self, line_info):
649 def check(self, line_info):
650 """If the 'rest' of the line begins with a function call or pretty much
650 """If the 'rest' of the line begins with a function call or pretty much
651 any python operator, we should simply execute the line (regardless of
651 any python operator, we should simply execute the line (regardless of
652 whether or not there's a possible autocall expansion). This avoids
652 whether or not there's a possible autocall expansion). This avoids
653 spurious (and very confusing) geattr() accesses."""
653 spurious (and very confusing) geattr() accesses."""
654 if line_info.the_rest and line_info.the_rest[0] in '!=()<>,+*/%^&|':
654 if line_info.the_rest and line_info.the_rest[0] in '!=()<>,+*/%^&|':
655 return self.prefilter_manager.get_handler_by_name('normal')
655 return self.prefilter_manager.get_handler_by_name('normal')
656 else:
656 else:
657 return None
657 return None
658
658
659
659
660 class AutocallChecker(PrefilterChecker):
660 class AutocallChecker(PrefilterChecker):
661
661
662 priority = Integer(1000, config=True)
662 priority = Integer(1000, config=True)
663
663
664 function_name_regexp = CRegExp(re_fun_name, config=True,
664 function_name_regexp = CRegExp(re_fun_name, config=True,
665 help="RegExp to identify potential function names.")
665 help="RegExp to identify potential function names.")
666 exclude_regexp = CRegExp(re_exclude_auto, config=True,
666 exclude_regexp = CRegExp(re_exclude_auto, config=True,
667 help="RegExp to exclude strings with this start from autocalling.")
667 help="RegExp to exclude strings with this start from autocalling.")
668
668
669 def check(self, line_info):
669 def check(self, line_info):
670 "Check if the initial word/function is callable and autocall is on."
670 "Check if the initial word/function is callable and autocall is on."
671 if not self.shell.autocall:
671 if not self.shell.autocall:
672 return None
672 return None
673
673
674 oinfo = line_info.ofind(self.shell) # This can mutate state via getattr
674 oinfo = line_info.ofind(self.shell) # This can mutate state via getattr
675 if not oinfo['found']:
675 if not oinfo['found']:
676 return None
676 return None
677
677
678 if callable(oinfo['obj']) \
678 if callable(oinfo['obj']) \
679 and (not self.exclude_regexp.match(line_info.the_rest)) \
679 and (not self.exclude_regexp.match(line_info.the_rest)) \
680 and self.function_name_regexp.match(line_info.ifun):
680 and self.function_name_regexp.match(line_info.ifun):
681 return self.prefilter_manager.get_handler_by_name('auto')
681 return self.prefilter_manager.get_handler_by_name('auto')
682 else:
682 else:
683 return None
683 return None
684
684
685
685
686 #-----------------------------------------------------------------------------
686 #-----------------------------------------------------------------------------
687 # Prefilter handlers
687 # Prefilter handlers
688 #-----------------------------------------------------------------------------
688 #-----------------------------------------------------------------------------
689
689
690
690
691 class PrefilterHandler(Configurable):
691 class PrefilterHandler(Configurable):
692
692
693 handler_name = Unicode('normal')
693 handler_name = Unicode('normal')
694 esc_strings = List([])
694 esc_strings = List([])
695 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
695 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
696 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
696 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
697
697
698 def __init__(self, shell=None, prefilter_manager=None, config=None):
698 def __init__(self, shell=None, prefilter_manager=None, config=None):
699 super(PrefilterHandler, self).__init__(
699 super(PrefilterHandler, self).__init__(
700 shell=shell, prefilter_manager=prefilter_manager, config=config
700 shell=shell, prefilter_manager=prefilter_manager, config=config
701 )
701 )
702 self.prefilter_manager.register_handler(
702 self.prefilter_manager.register_handler(
703 self.handler_name,
703 self.handler_name,
704 self,
704 self,
705 self.esc_strings
705 self.esc_strings
706 )
706 )
707
707
708 def handle(self, line_info):
708 def handle(self, line_info):
709 # print "normal: ", line_info
709 # print "normal: ", line_info
710 """Handle normal input lines. Use as a template for handlers."""
710 """Handle normal input lines. Use as a template for handlers."""
711
711
712 # With autoindent on, we need some way to exit the input loop, and I
712 # With autoindent on, we need some way to exit the input loop, and I
713 # don't want to force the user to have to backspace all the way to
713 # don't want to force the user to have to backspace all the way to
714 # clear the line. The rule will be in this case, that either two
714 # clear the line. The rule will be in this case, that either two
715 # lines of pure whitespace in a row, or a line of pure whitespace but
715 # lines of pure whitespace in a row, or a line of pure whitespace but
716 # of a size different to the indent level, will exit the input loop.
716 # of a size different to the indent level, will exit the input loop.
717 line = line_info.line
717 line = line_info.line
718 continue_prompt = line_info.continue_prompt
718 continue_prompt = line_info.continue_prompt
719
719
720 if (continue_prompt and
720 if (continue_prompt and
721 self.shell.autoindent and
721 self.shell.autoindent and
722 line.isspace() and
722 line.isspace() and
723 0 < abs(len(line) - self.shell.indent_current_nsp) <= 2):
723 0 < abs(len(line) - self.shell.indent_current_nsp) <= 2):
724 line = ''
724 line = ''
725
725
726 return line
726 return line
727
727
728 def __str__(self):
728 def __str__(self):
729 return "<%s(name=%s)>" % (self.__class__.__name__, self.handler_name)
729 return "<%s(name=%s)>" % (self.__class__.__name__, self.handler_name)
730
730
731
731
732 class AliasHandler(PrefilterHandler):
732 class AliasHandler(PrefilterHandler):
733
733
734 handler_name = Unicode('alias')
734 handler_name = Unicode('alias')
735
735
736 def handle(self, line_info):
736 def handle(self, line_info):
737 """Handle alias input lines. """
737 """Handle alias input lines. """
738 transformed = self.shell.alias_manager.expand_aliases(line_info.ifun,line_info.the_rest)
738 transformed = self.shell.alias_manager.expand_aliases(line_info.ifun,line_info.the_rest)
739 # pre is needed, because it carries the leading whitespace. Otherwise
739 # pre is needed, because it carries the leading whitespace. Otherwise
740 # aliases won't work in indented sections.
740 # aliases won't work in indented sections.
741 line_out = '%sget_ipython().system(%r)' % (line_info.pre_whitespace, transformed)
741 line_out = '%sget_ipython().system(%r)' % (line_info.pre_whitespace, transformed)
742
742
743 return line_out
743 return line_out
744
744
745
745
746 class ShellEscapeHandler(PrefilterHandler):
746 class ShellEscapeHandler(PrefilterHandler):
747
747
748 handler_name = Unicode('shell')
748 handler_name = Unicode('shell')
749 esc_strings = List([ESC_SHELL, ESC_SH_CAP])
749 esc_strings = List([ESC_SHELL, ESC_SH_CAP])
750
750
751 def handle(self, line_info):
751 def handle(self, line_info):
752 """Execute the line in a shell, empty return value"""
752 """Execute the line in a shell, empty return value"""
753 magic_handler = self.prefilter_manager.get_handler_by_name('magic')
753 magic_handler = self.prefilter_manager.get_handler_by_name('magic')
754
754
755 line = line_info.line
755 line = line_info.line
756 if line.lstrip().startswith(ESC_SH_CAP):
756 if line.lstrip().startswith(ESC_SH_CAP):
757 # rewrite LineInfo's line, ifun and the_rest to properly hold the
757 # rewrite LineInfo's line, ifun and the_rest to properly hold the
758 # call to %sx and the actual command to be executed, so
758 # call to %sx and the actual command to be executed, so
759 # handle_magic can work correctly. Note that this works even if
759 # handle_magic can work correctly. Note that this works even if
760 # the line is indented, so it handles multi_line_specials
760 # the line is indented, so it handles multi_line_specials
761 # properly.
761 # properly.
762 new_rest = line.lstrip()[2:]
762 new_rest = line.lstrip()[2:]
763 line_info.line = '%ssx %s' % (ESC_MAGIC, new_rest)
763 line_info.line = '%ssx %s' % (ESC_MAGIC, new_rest)
764 line_info.ifun = 'sx'
764 line_info.ifun = 'sx'
765 line_info.the_rest = new_rest
765 line_info.the_rest = new_rest
766 return magic_handler.handle(line_info)
766 return magic_handler.handle(line_info)
767 else:
767 else:
768 cmd = line.lstrip().lstrip(ESC_SHELL)
768 cmd = line.lstrip().lstrip(ESC_SHELL)
769 line_out = '%sget_ipython().system(%r)' % (line_info.pre_whitespace, cmd)
769 line_out = '%sget_ipython().system(%r)' % (line_info.pre_whitespace, cmd)
770 return line_out
770 return line_out
771
771
772
772
773 class MacroHandler(PrefilterHandler):
773 class MacroHandler(PrefilterHandler):
774 handler_name = Unicode("macro")
774 handler_name = Unicode("macro")
775
775
776 def handle(self, line_info):
776 def handle(self, line_info):
777 obj = self.shell.user_ns.get(line_info.ifun)
777 obj = self.shell.user_ns.get(line_info.ifun)
778 pre_space = line_info.pre_whitespace
778 pre_space = line_info.pre_whitespace
779 line_sep = "\n" + pre_space
779 line_sep = "\n" + pre_space
780 return pre_space + line_sep.join(obj.value.splitlines())
780 return pre_space + line_sep.join(obj.value.splitlines())
781
781
782
782
783 class MagicHandler(PrefilterHandler):
783 class MagicHandler(PrefilterHandler):
784
784
785 handler_name = Unicode('magic')
785 handler_name = Unicode('magic')
786 esc_strings = List([ESC_MAGIC])
786 esc_strings = List([ESC_MAGIC])
787
787
788 def handle(self, line_info):
788 def handle(self, line_info):
789 """Execute magic functions."""
789 """Execute magic functions."""
790 ifun = line_info.ifun
790 ifun = line_info.ifun
791 the_rest = line_info.the_rest
791 the_rest = line_info.the_rest
792 cmd = '%sget_ipython().magic(%r)' % (line_info.pre_whitespace,
792 cmd = '%sget_ipython().magic(%r)' % (line_info.pre_whitespace,
793 (ifun + " " + the_rest))
793 (ifun + " " + the_rest))
794 return cmd
794 return cmd
795
795
796
796
797 class AutoHandler(PrefilterHandler):
797 class AutoHandler(PrefilterHandler):
798
798
799 handler_name = Unicode('auto')
799 handler_name = Unicode('auto')
800 esc_strings = List([ESC_PAREN, ESC_QUOTE, ESC_QUOTE2])
800 esc_strings = List([ESC_PAREN, ESC_QUOTE, ESC_QUOTE2])
801
801
802 def handle(self, line_info):
802 def handle(self, line_info):
803 """Handle lines which can be auto-executed, quoting if requested."""
803 """Handle lines which can be auto-executed, quoting if requested."""
804 line = line_info.line
804 line = line_info.line
805 ifun = line_info.ifun
805 ifun = line_info.ifun
806 the_rest = line_info.the_rest
806 the_rest = line_info.the_rest
807 pre = line_info.pre
807 pre = line_info.pre
808 esc = line_info.esc
808 esc = line_info.esc
809 continue_prompt = line_info.continue_prompt
809 continue_prompt = line_info.continue_prompt
810 obj = line_info.ofind(self)['obj']
810 obj = line_info.ofind(self.shell)['obj']
811 #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun,the_rest) # dbg
811 #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun,the_rest) # dbg
812
812
813 # This should only be active for single-line input!
813 # This should only be active for single-line input!
814 if continue_prompt:
814 if continue_prompt:
815 return line
815 return line
816
816
817 force_auto = isinstance(obj, IPyAutocall)
817 force_auto = isinstance(obj, IPyAutocall)
818
818
819 # User objects sometimes raise exceptions on attribute access other
819 # User objects sometimes raise exceptions on attribute access other
820 # than AttributeError (we've seen it in the past), so it's safest to be
820 # than AttributeError (we've seen it in the past), so it's safest to be
821 # ultra-conservative here and catch all.
821 # ultra-conservative here and catch all.
822 try:
822 try:
823 auto_rewrite = obj.rewrite
823 auto_rewrite = obj.rewrite
824 except Exception:
824 except Exception:
825 auto_rewrite = True
825 auto_rewrite = True
826
826
827 if esc == ESC_QUOTE:
827 if esc == ESC_QUOTE:
828 # Auto-quote splitting on whitespace
828 # Auto-quote splitting on whitespace
829 newcmd = '%s("%s")' % (ifun,'", "'.join(the_rest.split()) )
829 newcmd = '%s("%s")' % (ifun,'", "'.join(the_rest.split()) )
830 elif esc == ESC_QUOTE2:
830 elif esc == ESC_QUOTE2:
831 # Auto-quote whole string
831 # Auto-quote whole string
832 newcmd = '%s("%s")' % (ifun,the_rest)
832 newcmd = '%s("%s")' % (ifun,the_rest)
833 elif esc == ESC_PAREN:
833 elif esc == ESC_PAREN:
834 newcmd = '%s(%s)' % (ifun,",".join(the_rest.split()))
834 newcmd = '%s(%s)' % (ifun,",".join(the_rest.split()))
835 else:
835 else:
836 # Auto-paren.
836 # Auto-paren.
837 if force_auto:
837 if force_auto:
838 # Don't rewrite if it is already a call.
838 # Don't rewrite if it is already a call.
839 do_rewrite = not the_rest.startswith('(')
839 do_rewrite = not the_rest.startswith('(')
840 else:
840 else:
841 if not the_rest:
841 if not the_rest:
842 # We only apply it to argument-less calls if the autocall
842 # We only apply it to argument-less calls if the autocall
843 # parameter is set to 2.
843 # parameter is set to 2.
844 do_rewrite = (self.shell.autocall >= 2)
844 do_rewrite = (self.shell.autocall >= 2)
845 elif the_rest.startswith('[') and hasattr(obj, '__getitem__'):
845 elif the_rest.startswith('[') and hasattr(obj, '__getitem__'):
846 # Don't autocall in this case: item access for an object
846 # Don't autocall in this case: item access for an object
847 # which is BOTH callable and implements __getitem__.
847 # which is BOTH callable and implements __getitem__.
848 do_rewrite = False
848 do_rewrite = False
849 else:
849 else:
850 do_rewrite = True
850 do_rewrite = True
851
851
852 # Figure out the rewritten command
852 # Figure out the rewritten command
853 if do_rewrite:
853 if do_rewrite:
854 if the_rest.endswith(';'):
854 if the_rest.endswith(';'):
855 newcmd = '%s(%s);' % (ifun.rstrip(),the_rest[:-1])
855 newcmd = '%s(%s);' % (ifun.rstrip(),the_rest[:-1])
856 else:
856 else:
857 newcmd = '%s(%s)' % (ifun.rstrip(), the_rest)
857 newcmd = '%s(%s)' % (ifun.rstrip(), the_rest)
858 else:
858 else:
859 normal_handler = self.prefilter_manager.get_handler_by_name('normal')
859 normal_handler = self.prefilter_manager.get_handler_by_name('normal')
860 return normal_handler.handle(line_info)
860 return normal_handler.handle(line_info)
861
861
862 # Display the rewritten call
862 # Display the rewritten call
863 if auto_rewrite:
863 if auto_rewrite:
864 self.shell.auto_rewrite_input(newcmd)
864 self.shell.auto_rewrite_input(newcmd)
865
865
866 return newcmd
866 return newcmd
867
867
868
868
869 class HelpHandler(PrefilterHandler):
869 class HelpHandler(PrefilterHandler):
870
870
871 handler_name = Unicode('help')
871 handler_name = Unicode('help')
872 esc_strings = List([ESC_HELP])
872 esc_strings = List([ESC_HELP])
873
873
874 def handle(self, line_info):
874 def handle(self, line_info):
875 """Try to get some help for the object.
875 """Try to get some help for the object.
876
876
877 obj? or ?obj -> basic information.
877 obj? or ?obj -> basic information.
878 obj?? or ??obj -> more details.
878 obj?? or ??obj -> more details.
879 """
879 """
880 normal_handler = self.prefilter_manager.get_handler_by_name('normal')
880 normal_handler = self.prefilter_manager.get_handler_by_name('normal')
881 line = line_info.line
881 line = line_info.line
882 # We need to make sure that we don't process lines which would be
882 # We need to make sure that we don't process lines which would be
883 # otherwise valid python, such as "x=1 # what?"
883 # otherwise valid python, such as "x=1 # what?"
884 try:
884 try:
885 codeop.compile_command(line)
885 codeop.compile_command(line)
886 except SyntaxError:
886 except SyntaxError:
887 # We should only handle as help stuff which is NOT valid syntax
887 # We should only handle as help stuff which is NOT valid syntax
888 if line[0]==ESC_HELP:
888 if line[0]==ESC_HELP:
889 line = line[1:]
889 line = line[1:]
890 elif line[-1]==ESC_HELP:
890 elif line[-1]==ESC_HELP:
891 line = line[:-1]
891 line = line[:-1]
892 if line:
892 if line:
893 #print 'line:<%r>' % line # dbg
893 #print 'line:<%r>' % line # dbg
894 self.shell.magic('pinfo %s' % line_info.ifun)
894 self.shell.magic('pinfo %s' % line_info.ifun)
895 else:
895 else:
896 self.shell.show_usage()
896 self.shell.show_usage()
897 return '' # Empty string is needed here!
897 return '' # Empty string is needed here!
898 except:
898 except:
899 raise
899 raise
900 # Pass any other exceptions through to the normal handler
900 # Pass any other exceptions through to the normal handler
901 return normal_handler.handle(line_info)
901 return normal_handler.handle(line_info)
902 else:
902 else:
903 # If the code compiles ok, we should handle it normally
903 # If the code compiles ok, we should handle it normally
904 return normal_handler.handle(line_info)
904 return normal_handler.handle(line_info)
905
905
906
906
907 class EmacsHandler(PrefilterHandler):
907 class EmacsHandler(PrefilterHandler):
908
908
909 handler_name = Unicode('emacs')
909 handler_name = Unicode('emacs')
910 esc_strings = List([])
910 esc_strings = List([])
911
911
912 def handle(self, line_info):
912 def handle(self, line_info):
913 """Handle input lines marked by python-mode."""
913 """Handle input lines marked by python-mode."""
914
914
915 # Currently, nothing is done. Later more functionality can be added
915 # Currently, nothing is done. Later more functionality can be added
916 # here if needed.
916 # here if needed.
917
917
918 # The input cache shouldn't be updated
918 # The input cache shouldn't be updated
919 return line_info.line
919 return line_info.line
920
920
921
921
922 #-----------------------------------------------------------------------------
922 #-----------------------------------------------------------------------------
923 # Defaults
923 # Defaults
924 #-----------------------------------------------------------------------------
924 #-----------------------------------------------------------------------------
925
925
926
926
927 _default_transformers = [
927 _default_transformers = [
928 AssignSystemTransformer,
928 AssignSystemTransformer,
929 AssignMagicTransformer,
929 AssignMagicTransformer,
930 PyPromptTransformer,
930 PyPromptTransformer,
931 IPyPromptTransformer,
931 IPyPromptTransformer,
932 ]
932 ]
933
933
934 _default_checkers = [
934 _default_checkers = [
935 EmacsChecker,
935 EmacsChecker,
936 ShellEscapeChecker,
936 ShellEscapeChecker,
937 MacroChecker,
937 MacroChecker,
938 IPyAutocallChecker,
938 IPyAutocallChecker,
939 MultiLineMagicChecker,
939 MultiLineMagicChecker,
940 EscCharsChecker,
940 EscCharsChecker,
941 AssignmentChecker,
941 AssignmentChecker,
942 AutoMagicChecker,
942 AutoMagicChecker,
943 AliasChecker,
943 AliasChecker,
944 PythonOpsChecker,
944 PythonOpsChecker,
945 AutocallChecker
945 AutocallChecker
946 ]
946 ]
947
947
948 _default_handlers = [
948 _default_handlers = [
949 PrefilterHandler,
949 PrefilterHandler,
950 AliasHandler,
950 AliasHandler,
951 ShellEscapeHandler,
951 ShellEscapeHandler,
952 MacroHandler,
952 MacroHandler,
953 MagicHandler,
953 MagicHandler,
954 AutoHandler,
954 AutoHandler,
955 HelpHandler,
955 HelpHandler,
956 EmacsHandler
956 EmacsHandler
957 ]
957 ]
@@ -1,140 +1,142 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """
2 """
3 Simple utility for splitting user input. This is used by both inputsplitter and
3 Simple utility for splitting user input. This is used by both inputsplitter and
4 prefilter.
4 prefilter.
5
5
6 Authors:
6 Authors:
7
7
8 * Brian Granger
8 * Brian Granger
9 * Fernando Perez
9 * Fernando Perez
10 """
10 """
11
11
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 # Copyright (C) 2008-2011 The IPython Development Team
13 # Copyright (C) 2008-2011 The IPython Development Team
14 #
14 #
15 # Distributed under the terms of the BSD License. The full license is in
15 # Distributed under the terms of the BSD License. The full license is in
16 # the file COPYING, distributed as part of this software.
16 # the file COPYING, distributed as part of this software.
17 #-----------------------------------------------------------------------------
17 #-----------------------------------------------------------------------------
18
18
19 #-----------------------------------------------------------------------------
19 #-----------------------------------------------------------------------------
20 # Imports
20 # Imports
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22
22
23 import re
23 import re
24 import sys
24 import sys
25
25
26 from IPython.utils import py3compat
26 from IPython.utils import py3compat
27 from IPython.utils.encoding import get_stream_enc
27 from IPython.utils.encoding import get_stream_enc
28
28
29 #-----------------------------------------------------------------------------
29 #-----------------------------------------------------------------------------
30 # Main function
30 # Main function
31 #-----------------------------------------------------------------------------
31 #-----------------------------------------------------------------------------
32
32
33 # RegExp for splitting line contents into pre-char//first word-method//rest.
33 # RegExp for splitting line contents into pre-char//first word-method//rest.
34 # For clarity, each group in on one line.
34 # For clarity, each group in on one line.
35
35
36 # WARNING: update the regexp if the escapes in interactiveshell are changed, as
36 # WARNING: update the regexp if the escapes in interactiveshell are changed, as
37 # they are hardwired in.
37 # they are hardwired in.
38
38
39 # Although it's not solely driven by the regex, note that:
39 # Although it's not solely driven by the regex, note that:
40 # ,;/% only trigger if they are the first character on the line
40 # ,;/% only trigger if they are the first character on the line
41 # ! and !! trigger if they are first char(s) *or* follow an indent
41 # ! and !! trigger if they are first char(s) *or* follow an indent
42 # ? triggers as first or last char.
42 # ? triggers as first or last char.
43
43
44 line_split = re.compile("""
44 line_split = re.compile("""
45 ^(\s*) # any leading space
45 ^(\s*) # any leading space
46 ([,;/%]|!!?|\?\??)? # escape character or characters
46 ([,;/%]|!!?|\?\??)? # escape character or characters
47 \s*(%?[\w\.\*]*) # function/method, possibly with leading %
47 \s*(%?[\w\.\*]*) # function/method, possibly with leading %
48 # to correctly treat things like '?%magic'
48 # to correctly treat things like '?%magic'
49 (.*?$|$) # rest of line
49 (.*?$|$) # rest of line
50 """, re.VERBOSE)
50 """, re.VERBOSE)
51
51
52
52 def split_user_input(line, pattern=None):
53 def split_user_input(line, pattern=None):
53 """Split user input into initial whitespace, escape character, function part
54 """Split user input into initial whitespace, escape character, function part
54 and the rest.
55 and the rest.
55 """
56 """
56 # We need to ensure that the rest of this routine deals only with unicode
57 # We need to ensure that the rest of this routine deals only with unicode
57 encoding = get_stream_enc(sys.stdin, 'utf-8')
58 encoding = get_stream_enc(sys.stdin, 'utf-8')
58 line = py3compat.cast_unicode(line, encoding)
59 line = py3compat.cast_unicode(line, encoding)
59
60
60 if pattern is None:
61 if pattern is None:
61 pattern = line_split
62 pattern = line_split
62 match = pattern.match(line)
63 match = pattern.match(line)
63 if not match:
64 if not match:
64 # print "match failed for line '%s'" % line
65 # print "match failed for line '%s'" % line
65 try:
66 try:
66 ifun, the_rest = line.split(None,1)
67 ifun, the_rest = line.split(None,1)
67 except ValueError:
68 except ValueError:
68 # print "split failed for line '%s'" % line
69 # print "split failed for line '%s'" % line
69 ifun, the_rest = line, u''
70 ifun, the_rest = line, u''
70 pre = re.match('^(\s*)(.*)',line).groups()[0]
71 pre = re.match('^(\s*)(.*)',line).groups()[0]
71 esc = ""
72 esc = ""
72 else:
73 else:
73 pre, esc, ifun, the_rest = match.groups()
74 pre, esc, ifun, the_rest = match.groups()
74
75
75 #print 'line:<%s>' % line # dbg
76 #print 'line:<%s>' % line # dbg
76 #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun.strip(),the_rest) # dbg
77 #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun.strip(),the_rest) # dbg
77 return pre, esc or '', ifun.strip(), the_rest.lstrip()
78 return pre, esc or '', ifun.strip(), the_rest.lstrip()
78
79
80
79 class LineInfo(object):
81 class LineInfo(object):
80 """A single line of input and associated info.
82 """A single line of input and associated info.
81
83
82 Includes the following as properties:
84 Includes the following as properties:
83
85
84 line
86 line
85 The original, raw line
87 The original, raw line
86
88
87 continue_prompt
89 continue_prompt
88 Is this line a continuation in a sequence of multiline input?
90 Is this line a continuation in a sequence of multiline input?
89
91
90 pre
92 pre
91 Any leading whitespace.
93 Any leading whitespace.
92
94
93 esc
95 esc
94 The escape character(s) in pre or the empty string if there isn't one.
96 The escape character(s) in pre or the empty string if there isn't one.
95 Note that '!!' and '??' are possible values for esc. Otherwise it will
97 Note that '!!' and '??' are possible values for esc. Otherwise it will
96 always be a single character.
98 always be a single character.
97
99
98 ifun
100 ifun
99 The 'function part', which is basically the maximal initial sequence
101 The 'function part', which is basically the maximal initial sequence
100 of valid python identifiers and the '.' character. This is what is
102 of valid python identifiers and the '.' character. This is what is
101 checked for alias and magic transformations, used for auto-calling,
103 checked for alias and magic transformations, used for auto-calling,
102 etc. In contrast to Python identifiers, it may start with "%" and contain
104 etc. In contrast to Python identifiers, it may start with "%" and contain
103 "*".
105 "*".
104
106
105 the_rest
107 the_rest
106 Everything else on the line.
108 Everything else on the line.
107 """
109 """
108 def __init__(self, line, continue_prompt=False):
110 def __init__(self, line, continue_prompt=False):
109 self.line = line
111 self.line = line
110 self.continue_prompt = continue_prompt
112 self.continue_prompt = continue_prompt
111 self.pre, self.esc, self.ifun, self.the_rest = split_user_input(line)
113 self.pre, self.esc, self.ifun, self.the_rest = split_user_input(line)
112
114
113 self.pre_char = self.pre.strip()
115 self.pre_char = self.pre.strip()
114 if self.pre_char:
116 if self.pre_char:
115 self.pre_whitespace = '' # No whitespace allowd before esc chars
117 self.pre_whitespace = '' # No whitespace allowd before esc chars
116 else:
118 else:
117 self.pre_whitespace = self.pre
119 self.pre_whitespace = self.pre
118
120
119 self._oinfo = None
121 self._oinfo = None
120
122
121 def ofind(self, ip):
123 def ofind(self, ip):
122 """Do a full, attribute-walking lookup of the ifun in the various
124 """Do a full, attribute-walking lookup of the ifun in the various
123 namespaces for the given IPython InteractiveShell instance.
125 namespaces for the given IPython InteractiveShell instance.
124
126
125 Return a dict with keys: found,obj,ospace,ismagic
127 Return a dict with keys: {found, obj, ospace, ismagic}
126
128
127 Note: can cause state changes because of calling getattr, but should
129 Note: can cause state changes because of calling getattr, but should
128 only be run if autocall is on and if the line hasn't matched any
130 only be run if autocall is on and if the line hasn't matched any
129 other, less dangerous handlers.
131 other, less dangerous handlers.
130
132
131 Does cache the results of the call, so can be called multiple times
133 Does cache the results of the call, so can be called multiple times
132 without worrying about *further* damaging state.
134 without worrying about *further* damaging state.
133 """
135 """
134 if not self._oinfo:
136 if not self._oinfo:
135 # ip.shell._ofind is actually on the Magic class!
137 # ip.shell._ofind is actually on the Magic class!
136 self._oinfo = ip._ofind(self.ifun)
138 self._oinfo = ip._ofind(self.ifun)
137 return self._oinfo
139 return self._oinfo
138
140
139 def __str__(self):
141 def __str__(self):
140 return "LineInfo [%s|%s|%s|%s]" %(self.pre, self.esc, self.ifun, self.the_rest)
142 return "LineInfo [%s|%s|%s|%s]" %(self.pre, self.esc, self.ifun, self.the_rest)
General Comments 0
You need to be logged in to leave comments. Login now