##// END OF EJS Templates
doc new behavior of clients without stdin
Paul Ivanov -
Show More
@@ -1,974 +1,975 b''
1 1 """ History related magics and functionality """
2 2 #-----------------------------------------------------------------------------
3 3 # Copyright (C) 2010-2011 The IPython Development Team.
4 4 #
5 5 # Distributed under the terms of the BSD License.
6 6 #
7 7 # The full license is in the file COPYING.txt, distributed with this software.
8 8 #-----------------------------------------------------------------------------
9 9
10 10 #-----------------------------------------------------------------------------
11 11 # Imports
12 12 #-----------------------------------------------------------------------------
13 13 from __future__ import print_function
14 14
15 15 # Stdlib imports
16 16 import atexit
17 17 import datetime
18 18 import os
19 19 import re
20 20 try:
21 21 import sqlite3
22 22 except ImportError:
23 23 sqlite3 = None
24 24 import threading
25 25
26 26 # Our own packages
27 27 from IPython.core.error import StdinNotImplementedError
28 28 from IPython.config.configurable import Configurable
29 29 from IPython.external.decorator import decorator
30 30 from IPython.testing.skipdoctest import skip_doctest
31 31 from IPython.utils import io
32 32 from IPython.utils.path import locate_profile
33 33 from IPython.utils.traitlets import Bool, Dict, Instance, Integer, List, Unicode
34 34 from IPython.utils.warn import warn
35 35
36 36 #-----------------------------------------------------------------------------
37 37 # Classes and functions
38 38 #-----------------------------------------------------------------------------
39 39
40 40 class DummyDB(object):
41 41 """Dummy DB that will act as a black hole for history.
42 42
43 43 Only used in the absence of sqlite"""
44 44 def execute(*args, **kwargs):
45 45 return []
46 46
47 47 def commit(self, *args, **kwargs):
48 48 pass
49 49
50 50 def __enter__(self, *args, **kwargs):
51 51 pass
52 52
53 53 def __exit__(self, *args, **kwargs):
54 54 pass
55 55
56 56 @decorator
57 57 def needs_sqlite(f,*a,**kw):
58 58 """return an empty list in the absence of sqlite"""
59 59 if sqlite3 is None:
60 60 return []
61 61 else:
62 62 return f(*a,**kw)
63 63
64 64 class HistoryAccessor(Configurable):
65 65 """Access the history database without adding to it.
66 66
67 67 This is intended for use by standalone history tools. IPython shells use
68 68 HistoryManager, below, which is a subclass of this."""
69 69
70 70 # String holding the path to the history file
71 71 hist_file = Unicode(config=True,
72 72 help="""Path to file to use for SQLite history database.
73 73
74 74 By default, IPython will put the history database in the IPython profile
75 75 directory. If you would rather share one history among profiles,
76 76 you ca set this value in each, so that they are consistent.
77 77
78 78 Due to an issue with fcntl, SQLite is known to misbehave on some NFS mounts.
79 79 If you see IPython hanging, try setting this to something on a local disk,
80 80 e.g::
81 81
82 82 ipython --HistoryManager.hist_file=/tmp/ipython_hist.sqlite
83 83
84 84 """)
85 85
86 86
87 87 # The SQLite database
88 88 if sqlite3:
89 89 db = Instance(sqlite3.Connection)
90 90 else:
91 91 db = Instance(DummyDB)
92 92
93 93 def __init__(self, profile='default', hist_file=u'', config=None, **traits):
94 94 """Create a new history accessor.
95 95
96 96 Parameters
97 97 ----------
98 98 profile : str
99 99 The name of the profile from which to open history.
100 100 hist_file : str
101 101 Path to an SQLite history database stored by IPython. If specified,
102 102 hist_file overrides profile.
103 103 config :
104 104 Config object. hist_file can also be set through this.
105 105 """
106 106 # We need a pointer back to the shell for various tasks.
107 107 super(HistoryAccessor, self).__init__(config=config, **traits)
108 108 # defer setting hist_file from kwarg until after init,
109 109 # otherwise the default kwarg value would clobber any value
110 110 # set by config
111 111 if hist_file:
112 112 self.hist_file = hist_file
113 113
114 114 if self.hist_file == u'':
115 115 # No one has set the hist_file, yet.
116 116 self.hist_file = self._get_hist_file_name(profile)
117 117
118 118 if sqlite3 is None:
119 119 warn("IPython History requires SQLite, your history will not be saved\n")
120 120 self.db = DummyDB()
121 121 return
122 122
123 123 try:
124 124 self.init_db()
125 125 except sqlite3.DatabaseError:
126 126 if os.path.isfile(self.hist_file):
127 127 # Try to move the file out of the way
128 128 base,ext = os.path.splitext(self.hist_file)
129 129 newpath = base + '-corrupt' + ext
130 130 os.rename(self.hist_file, newpath)
131 131 print("ERROR! History file wasn't a valid SQLite database.",
132 132 "It was moved to %s" % newpath, "and a new file created.")
133 133 self.init_db()
134 134 else:
135 135 # The hist_file is probably :memory: or something else.
136 136 raise
137 137
138 138 def _get_hist_file_name(self, profile='default'):
139 139 """Find the history file for the given profile name.
140 140
141 141 This is overridden by the HistoryManager subclass, to use the shell's
142 142 active profile.
143 143
144 144 Parameters
145 145 ----------
146 146 profile : str
147 147 The name of a profile which has a history file.
148 148 """
149 149 return os.path.join(locate_profile(profile), 'history.sqlite')
150 150
151 151 def init_db(self):
152 152 """Connect to the database, and create tables if necessary."""
153 153 # use detect_types so that timestamps return datetime objects
154 154 self.db = sqlite3.connect(self.hist_file, detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
155 155 self.db.execute("""CREATE TABLE IF NOT EXISTS sessions (session integer
156 156 primary key autoincrement, start timestamp,
157 157 end timestamp, num_cmds integer, remark text)""")
158 158 self.db.execute("""CREATE TABLE IF NOT EXISTS history
159 159 (session integer, line integer, source text, source_raw text,
160 160 PRIMARY KEY (session, line))""")
161 161 # Output history is optional, but ensure the table's there so it can be
162 162 # enabled later.
163 163 self.db.execute("""CREATE TABLE IF NOT EXISTS output_history
164 164 (session integer, line integer, output text,
165 165 PRIMARY KEY (session, line))""")
166 166 self.db.commit()
167 167
168 168 def writeout_cache(self):
169 169 """Overridden by HistoryManager to dump the cache before certain
170 170 database lookups."""
171 171 pass
172 172
173 173 ## -------------------------------
174 174 ## Methods for retrieving history:
175 175 ## -------------------------------
176 176 def _run_sql(self, sql, params, raw=True, output=False):
177 177 """Prepares and runs an SQL query for the history database.
178 178
179 179 Parameters
180 180 ----------
181 181 sql : str
182 182 Any filtering expressions to go after SELECT ... FROM ...
183 183 params : tuple
184 184 Parameters passed to the SQL query (to replace "?")
185 185 raw, output : bool
186 186 See :meth:`get_range`
187 187
188 188 Returns
189 189 -------
190 190 Tuples as :meth:`get_range`
191 191 """
192 192 toget = 'source_raw' if raw else 'source'
193 193 sqlfrom = "history"
194 194 if output:
195 195 sqlfrom = "history LEFT JOIN output_history USING (session, line)"
196 196 toget = "history.%s, output_history.output" % toget
197 197 cur = self.db.execute("SELECT session, line, %s FROM %s " %\
198 198 (toget, sqlfrom) + sql, params)
199 199 if output: # Regroup into 3-tuples, and parse JSON
200 200 return ((ses, lin, (inp, out)) for ses, lin, inp, out in cur)
201 201 return cur
202 202
203 203 @needs_sqlite
204 204 def get_session_info(self, session=0):
205 205 """get info about a session
206 206
207 207 Parameters
208 208 ----------
209 209
210 210 session : int
211 211 Session number to retrieve. The current session is 0, and negative
212 212 numbers count back from current session, so -1 is previous session.
213 213
214 214 Returns
215 215 -------
216 216
217 217 (session_id [int], start [datetime], end [datetime], num_cmds [int], remark [unicode])
218 218
219 219 Sessions that are running or did not exit cleanly will have `end=None`
220 220 and `num_cmds=None`.
221 221
222 222 """
223 223
224 224 if session <= 0:
225 225 session += self.session_number
226 226
227 227 query = "SELECT * from sessions where session == ?"
228 228 return self.db.execute(query, (session,)).fetchone()
229 229
230 230 def get_tail(self, n=10, raw=True, output=False, include_latest=False):
231 231 """Get the last n lines from the history database.
232 232
233 233 Parameters
234 234 ----------
235 235 n : int
236 236 The number of lines to get
237 237 raw, output : bool
238 238 See :meth:`get_range`
239 239 include_latest : bool
240 240 If False (default), n+1 lines are fetched, and the latest one
241 241 is discarded. This is intended to be used where the function
242 242 is called by a user command, which it should not return.
243 243
244 244 Returns
245 245 -------
246 246 Tuples as :meth:`get_range`
247 247 """
248 248 self.writeout_cache()
249 249 if not include_latest:
250 250 n += 1
251 251 cur = self._run_sql("ORDER BY session DESC, line DESC LIMIT ?",
252 252 (n,), raw=raw, output=output)
253 253 if not include_latest:
254 254 return reversed(list(cur)[1:])
255 255 return reversed(list(cur))
256 256
257 257 def search(self, pattern="*", raw=True, search_raw=True,
258 258 output=False):
259 259 """Search the database using unix glob-style matching (wildcards
260 260 * and ?).
261 261
262 262 Parameters
263 263 ----------
264 264 pattern : str
265 265 The wildcarded pattern to match when searching
266 266 search_raw : bool
267 267 If True, search the raw input, otherwise, the parsed input
268 268 raw, output : bool
269 269 See :meth:`get_range`
270 270
271 271 Returns
272 272 -------
273 273 Tuples as :meth:`get_range`
274 274 """
275 275 tosearch = "source_raw" if search_raw else "source"
276 276 if output:
277 277 tosearch = "history." + tosearch
278 278 self.writeout_cache()
279 279 return self._run_sql("WHERE %s GLOB ?" % tosearch, (pattern,),
280 280 raw=raw, output=output)
281 281
282 282 def get_range(self, session, start=1, stop=None, raw=True,output=False):
283 283 """Retrieve input by session.
284 284
285 285 Parameters
286 286 ----------
287 287 session : int
288 288 Session number to retrieve.
289 289 start : int
290 290 First line to retrieve.
291 291 stop : int
292 292 End of line range (excluded from output itself). If None, retrieve
293 293 to the end of the session.
294 294 raw : bool
295 295 If True, return untranslated input
296 296 output : bool
297 297 If True, attempt to include output. This will be 'real' Python
298 298 objects for the current session, or text reprs from previous
299 299 sessions if db_log_output was enabled at the time. Where no output
300 300 is found, None is used.
301 301
302 302 Returns
303 303 -------
304 304 An iterator over the desired lines. Each line is a 3-tuple, either
305 305 (session, line, input) if output is False, or
306 306 (session, line, (input, output)) if output is True.
307 307 """
308 308 if stop:
309 309 lineclause = "line >= ? AND line < ?"
310 310 params = (session, start, stop)
311 311 else:
312 312 lineclause = "line>=?"
313 313 params = (session, start)
314 314
315 315 return self._run_sql("WHERE session==? AND %s""" % lineclause,
316 316 params, raw=raw, output=output)
317 317
318 318 def get_range_by_str(self, rangestr, raw=True, output=False):
319 319 """Get lines of history from a string of ranges, as used by magic
320 320 commands %hist, %save, %macro, etc.
321 321
322 322 Parameters
323 323 ----------
324 324 rangestr : str
325 325 A string specifying ranges, e.g. "5 ~2/1-4". See
326 326 :func:`magic_history` for full details.
327 327 raw, output : bool
328 328 As :meth:`get_range`
329 329
330 330 Returns
331 331 -------
332 332 Tuples as :meth:`get_range`
333 333 """
334 334 for sess, s, e in extract_hist_ranges(rangestr):
335 335 for line in self.get_range(sess, s, e, raw=raw, output=output):
336 336 yield line
337 337
338 338
339 339 class HistoryManager(HistoryAccessor):
340 340 """A class to organize all history-related functionality in one place.
341 341 """
342 342 # Public interface
343 343
344 344 # An instance of the IPython shell we are attached to
345 345 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
346 346 # Lists to hold processed and raw history. These start with a blank entry
347 347 # so that we can index them starting from 1
348 348 input_hist_parsed = List([""])
349 349 input_hist_raw = List([""])
350 350 # A list of directories visited during session
351 351 dir_hist = List()
352 352 def _dir_hist_default(self):
353 353 try:
354 354 return [os.getcwdu()]
355 355 except OSError:
356 356 return []
357 357
358 358 # A dict of output history, keyed with ints from the shell's
359 359 # execution count.
360 360 output_hist = Dict()
361 361 # The text/plain repr of outputs.
362 362 output_hist_reprs = Dict()
363 363
364 364 # The number of the current session in the history database
365 365 session_number = Integer()
366 366 # Should we log output to the database? (default no)
367 367 db_log_output = Bool(False, config=True)
368 368 # Write to database every x commands (higher values save disk access & power)
369 369 # Values of 1 or less effectively disable caching.
370 370 db_cache_size = Integer(0, config=True)
371 371 # The input and output caches
372 372 db_input_cache = List()
373 373 db_output_cache = List()
374 374
375 375 # History saving in separate thread
376 376 save_thread = Instance('IPython.core.history.HistorySavingThread')
377 377 try: # Event is a function returning an instance of _Event...
378 378 save_flag = Instance(threading._Event)
379 379 except AttributeError: # ...until Python 3.3, when it's a class.
380 380 save_flag = Instance(threading.Event)
381 381
382 382 # Private interface
383 383 # Variables used to store the three last inputs from the user. On each new
384 384 # history update, we populate the user's namespace with these, shifted as
385 385 # necessary.
386 386 _i00 = Unicode(u'')
387 387 _i = Unicode(u'')
388 388 _ii = Unicode(u'')
389 389 _iii = Unicode(u'')
390 390
391 391 # A regex matching all forms of the exit command, so that we don't store
392 392 # them in the history (it's annoying to rewind the first entry and land on
393 393 # an exit call).
394 394 _exit_re = re.compile(r"(exit|quit)(\s*\(.*\))?$")
395 395
396 396 def __init__(self, shell=None, config=None, **traits):
397 397 """Create a new history manager associated with a shell instance.
398 398 """
399 399 # We need a pointer back to the shell for various tasks.
400 400 super(HistoryManager, self).__init__(shell=shell, config=config,
401 401 **traits)
402 402 self.save_flag = threading.Event()
403 403 self.db_input_cache_lock = threading.Lock()
404 404 self.db_output_cache_lock = threading.Lock()
405 405 self.save_thread = HistorySavingThread(self)
406 406 self.save_thread.start()
407 407
408 408 self.new_session()
409 409
410 410 def _get_hist_file_name(self, profile=None):
411 411 """Get default history file name based on the Shell's profile.
412 412
413 413 The profile parameter is ignored, but must exist for compatibility with
414 414 the parent class."""
415 415 profile_dir = self.shell.profile_dir.location
416 416 return os.path.join(profile_dir, 'history.sqlite')
417 417
418 418 @needs_sqlite
419 419 def new_session(self, conn=None):
420 420 """Get a new session number."""
421 421 if conn is None:
422 422 conn = self.db
423 423
424 424 with conn:
425 425 cur = conn.execute("""INSERT INTO sessions VALUES (NULL, ?, NULL,
426 426 NULL, "") """, (datetime.datetime.now(),))
427 427 self.session_number = cur.lastrowid
428 428
429 429 def end_session(self):
430 430 """Close the database session, filling in the end time and line count."""
431 431 self.writeout_cache()
432 432 with self.db:
433 433 self.db.execute("""UPDATE sessions SET end=?, num_cmds=? WHERE
434 434 session==?""", (datetime.datetime.now(),
435 435 len(self.input_hist_parsed)-1, self.session_number))
436 436 self.session_number = 0
437 437
438 438 def name_session(self, name):
439 439 """Give the current session a name in the history database."""
440 440 with self.db:
441 441 self.db.execute("UPDATE sessions SET remark=? WHERE session==?",
442 442 (name, self.session_number))
443 443
444 444 def reset(self, new_session=True):
445 445 """Clear the session history, releasing all object references, and
446 446 optionally open a new session."""
447 447 self.output_hist.clear()
448 448 # The directory history can't be completely empty
449 449 self.dir_hist[:] = [os.getcwdu()]
450 450
451 451 if new_session:
452 452 if self.session_number:
453 453 self.end_session()
454 454 self.input_hist_parsed[:] = [""]
455 455 self.input_hist_raw[:] = [""]
456 456 self.new_session()
457 457
458 458 # ------------------------------
459 459 # Methods for retrieving history
460 460 # ------------------------------
461 461 def _get_range_session(self, start=1, stop=None, raw=True, output=False):
462 462 """Get input and output history from the current session. Called by
463 463 get_range, and takes similar parameters."""
464 464 input_hist = self.input_hist_raw if raw else self.input_hist_parsed
465 465
466 466 n = len(input_hist)
467 467 if start < 0:
468 468 start += n
469 469 if not stop or (stop > n):
470 470 stop = n
471 471 elif stop < 0:
472 472 stop += n
473 473
474 474 for i in range(start, stop):
475 475 if output:
476 476 line = (input_hist[i], self.output_hist_reprs.get(i))
477 477 else:
478 478 line = input_hist[i]
479 479 yield (0, i, line)
480 480
481 481 def get_range(self, session=0, start=1, stop=None, raw=True,output=False):
482 482 """Retrieve input by session.
483 483
484 484 Parameters
485 485 ----------
486 486 session : int
487 487 Session number to retrieve. The current session is 0, and negative
488 488 numbers count back from current session, so -1 is previous session.
489 489 start : int
490 490 First line to retrieve.
491 491 stop : int
492 492 End of line range (excluded from output itself). If None, retrieve
493 493 to the end of the session.
494 494 raw : bool
495 495 If True, return untranslated input
496 496 output : bool
497 497 If True, attempt to include output. This will be 'real' Python
498 498 objects for the current session, or text reprs from previous
499 499 sessions if db_log_output was enabled at the time. Where no output
500 500 is found, None is used.
501 501
502 502 Returns
503 503 -------
504 504 An iterator over the desired lines. Each line is a 3-tuple, either
505 505 (session, line, input) if output is False, or
506 506 (session, line, (input, output)) if output is True.
507 507 """
508 508 if session <= 0:
509 509 session += self.session_number
510 510 if session==self.session_number: # Current session
511 511 return self._get_range_session(start, stop, raw, output)
512 512 return super(HistoryManager, self).get_range(session, start, stop, raw, output)
513 513
514 514 ## ----------------------------
515 515 ## Methods for storing history:
516 516 ## ----------------------------
517 517 def store_inputs(self, line_num, source, source_raw=None):
518 518 """Store source and raw input in history and create input cache
519 519 variables _i*.
520 520
521 521 Parameters
522 522 ----------
523 523 line_num : int
524 524 The prompt number of this input.
525 525
526 526 source : str
527 527 Python input.
528 528
529 529 source_raw : str, optional
530 530 If given, this is the raw input without any IPython transformations
531 531 applied to it. If not given, ``source`` is used.
532 532 """
533 533 if source_raw is None:
534 534 source_raw = source
535 535 source = source.rstrip('\n')
536 536 source_raw = source_raw.rstrip('\n')
537 537
538 538 # do not store exit/quit commands
539 539 if self._exit_re.match(source_raw.strip()):
540 540 return
541 541
542 542 self.input_hist_parsed.append(source)
543 543 self.input_hist_raw.append(source_raw)
544 544
545 545 with self.db_input_cache_lock:
546 546 self.db_input_cache.append((line_num, source, source_raw))
547 547 # Trigger to flush cache and write to DB.
548 548 if len(self.db_input_cache) >= self.db_cache_size:
549 549 self.save_flag.set()
550 550
551 551 # update the auto _i variables
552 552 self._iii = self._ii
553 553 self._ii = self._i
554 554 self._i = self._i00
555 555 self._i00 = source_raw
556 556
557 557 # hackish access to user namespace to create _i1,_i2... dynamically
558 558 new_i = '_i%s' % line_num
559 559 to_main = {'_i': self._i,
560 560 '_ii': self._ii,
561 561 '_iii': self._iii,
562 562 new_i : self._i00 }
563 563
564 564 self.shell.push(to_main, interactive=False)
565 565
566 566 def store_output(self, line_num):
567 567 """If database output logging is enabled, this saves all the
568 568 outputs from the indicated prompt number to the database. It's
569 569 called by run_cell after code has been executed.
570 570
571 571 Parameters
572 572 ----------
573 573 line_num : int
574 574 The line number from which to save outputs
575 575 """
576 576 if (not self.db_log_output) or (line_num not in self.output_hist_reprs):
577 577 return
578 578 output = self.output_hist_reprs[line_num]
579 579
580 580 with self.db_output_cache_lock:
581 581 self.db_output_cache.append((line_num, output))
582 582 if self.db_cache_size <= 1:
583 583 self.save_flag.set()
584 584
585 585 def _writeout_input_cache(self, conn):
586 586 with conn:
587 587 for line in self.db_input_cache:
588 588 conn.execute("INSERT INTO history VALUES (?, ?, ?, ?)",
589 589 (self.session_number,)+line)
590 590
591 591 def _writeout_output_cache(self, conn):
592 592 with conn:
593 593 for line in self.db_output_cache:
594 594 conn.execute("INSERT INTO output_history VALUES (?, ?, ?)",
595 595 (self.session_number,)+line)
596 596
597 597 @needs_sqlite
598 598 def writeout_cache(self, conn=None):
599 599 """Write any entries in the cache to the database."""
600 600 if conn is None:
601 601 conn = self.db
602 602
603 603 with self.db_input_cache_lock:
604 604 try:
605 605 self._writeout_input_cache(conn)
606 606 except sqlite3.IntegrityError:
607 607 self.new_session(conn)
608 608 print("ERROR! Session/line number was not unique in",
609 609 "database. History logging moved to new session",
610 610 self.session_number)
611 611 try: # Try writing to the new session. If this fails, don't recurse
612 612 self._writeout_input_cache(conn)
613 613 except sqlite3.IntegrityError:
614 614 pass
615 615 finally:
616 616 self.db_input_cache = []
617 617
618 618 with self.db_output_cache_lock:
619 619 try:
620 620 self._writeout_output_cache(conn)
621 621 except sqlite3.IntegrityError:
622 622 print("!! Session/line number for output was not unique",
623 623 "in database. Output will not be stored.")
624 624 finally:
625 625 self.db_output_cache = []
626 626
627 627
628 628 class HistorySavingThread(threading.Thread):
629 629 """This thread takes care of writing history to the database, so that
630 630 the UI isn't held up while that happens.
631 631
632 632 It waits for the HistoryManager's save_flag to be set, then writes out
633 633 the history cache. The main thread is responsible for setting the flag when
634 634 the cache size reaches a defined threshold."""
635 635 daemon = True
636 636 stop_now = False
637 637 def __init__(self, history_manager):
638 638 super(HistorySavingThread, self).__init__()
639 639 self.history_manager = history_manager
640 640 atexit.register(self.stop)
641 641
642 642 @needs_sqlite
643 643 def run(self):
644 644 # We need a separate db connection per thread:
645 645 try:
646 646 self.db = sqlite3.connect(self.history_manager.hist_file)
647 647 while True:
648 648 self.history_manager.save_flag.wait()
649 649 if self.stop_now:
650 650 return
651 651 self.history_manager.save_flag.clear()
652 652 self.history_manager.writeout_cache(self.db)
653 653 except Exception as e:
654 654 print(("The history saving thread hit an unexpected error (%s)."
655 655 "History will not be written to the database.") % repr(e))
656 656
657 657 def stop(self):
658 658 """This can be called from the main thread to safely stop this thread.
659 659
660 660 Note that it does not attempt to write out remaining history before
661 661 exiting. That should be done by calling the HistoryManager's
662 662 end_session method."""
663 663 self.stop_now = True
664 664 self.history_manager.save_flag.set()
665 665 self.join()
666 666
667 667
668 668 # To match, e.g. ~5/8-~2/3
669 669 range_re = re.compile(r"""
670 670 ((?P<startsess>~?\d+)/)?
671 671 (?P<start>\d+) # Only the start line num is compulsory
672 672 ((?P<sep>[\-:])
673 673 ((?P<endsess>~?\d+)/)?
674 674 (?P<end>\d+))?
675 675 $""", re.VERBOSE)
676 676
677 677 def extract_hist_ranges(ranges_str):
678 678 """Turn a string of history ranges into 3-tuples of (session, start, stop).
679 679
680 680 Examples
681 681 --------
682 682 list(extract_input_ranges("~8/5-~7/4 2"))
683 683 [(-8, 5, None), (-7, 1, 4), (0, 2, 3)]
684 684 """
685 685 for range_str in ranges_str.split():
686 686 rmatch = range_re.match(range_str)
687 687 if not rmatch:
688 688 continue
689 689 start = int(rmatch.group("start"))
690 690 end = rmatch.group("end")
691 691 end = int(end) if end else start+1 # If no end specified, get (a, a+1)
692 692 if rmatch.group("sep") == "-": # 1-3 == 1:4 --> [1, 2, 3]
693 693 end += 1
694 694 startsess = rmatch.group("startsess") or "0"
695 695 endsess = rmatch.group("endsess") or startsess
696 696 startsess = int(startsess.replace("~","-"))
697 697 endsess = int(endsess.replace("~","-"))
698 698 assert endsess >= startsess
699 699
700 700 if endsess == startsess:
701 701 yield (startsess, start, end)
702 702 continue
703 703 # Multiple sessions in one range:
704 704 yield (startsess, start, None)
705 705 for sess in range(startsess+1, endsess):
706 706 yield (sess, 1, None)
707 707 yield (endsess, 1, end)
708 708
709 709 def _format_lineno(session, line):
710 710 """Helper function to format line numbers properly."""
711 711 if session == 0:
712 712 return str(line)
713 713 return "%s#%s" % (session, line)
714 714
715 715 @skip_doctest
716 716 def magic_history(self, parameter_s = ''):
717 717 """Print input history (_i<n> variables), with most recent last.
718 718
719 719 %history -> print at most 40 inputs (some may be multi-line)\\
720 720 %history n -> print at most n inputs\\
721 721 %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
722 722
723 723 By default, input history is printed without line numbers so it can be
724 724 directly pasted into an editor. Use -n to show them.
725 725
726 726 Ranges of history can be indicated using the syntax:
727 727 4 : Line 4, current session
728 728 4-6 : Lines 4-6, current session
729 729 243/1-5: Lines 1-5, session 243
730 730 ~2/7 : Line 7, session 2 before current
731 731 ~8/1-~6/5 : From the first line of 8 sessions ago, to the fifth line
732 732 of 6 sessions ago.
733 733 Multiple ranges can be entered, separated by spaces
734 734
735 735 The same syntax is used by %macro, %save, %edit, %rerun
736 736
737 737 Options:
738 738
739 739 -n: print line numbers for each input.
740 740 This feature is only available if numbered prompts are in use.
741 741
742 742 -o: also print outputs for each input.
743 743
744 744 -p: print classic '>>>' python prompts before each input. This is useful
745 745 for making documentation, and in conjunction with -o, for producing
746 746 doctest-ready output.
747 747
748 748 -r: (default) print the 'raw' history, i.e. the actual commands you typed.
749 749
750 750 -t: print the 'translated' history, as IPython understands it. IPython
751 751 filters your input and converts it all into valid Python source before
752 752 executing it (things like magics or aliases are turned into function
753 753 calls, for example). With this option, you'll see the native history
754 754 instead of the user-entered version: '%cd /' will be seen as
755 755 'get_ipython().magic("%cd /")' instead of '%cd /'.
756 756
757 757 -g: treat the arg as a pattern to grep for in (full) history.
758 758 This includes the saved history (almost all commands ever written).
759 759 Use '%hist -g' to show full saved history (may be very long).
760 760
761 761 -l: get the last n lines from all sessions. Specify n as a single arg, or
762 762 the default is the last 10 lines.
763 763
764 764 -f FILENAME: instead of printing the output to the screen, redirect it to
765 the given file. The file is always overwritten, though IPython asks for
766 confirmation first if it already exists.
765 the given file. The file is always overwritten, though *when it can*,
766 IPython asks for confirmation first. In particular, running the command
767 "history -f FILENAME" from the IPython Notebook interface will replace
768 FILENAME even if it already exists *without* confirmation.
767 769
768 770 Examples
769 771 --------
770 772 ::
771 773
772 774 In [6]: %hist -n 4 6
773 775 4:a = 12
774 776 5:print a**2
775 777
776 778 """
777 779
778 780 if not self.shell.displayhook.do_full_cache:
779 781 print('This feature is only available if numbered prompts are in use.')
780 782 return
781 783 opts,args = self.parse_options(parameter_s,'noprtglf:',mode='string')
782 784
783 785 # For brevity
784 786 history_manager = self.shell.history_manager
785 787
786 788 def _format_lineno(session, line):
787 789 """Helper function to format line numbers properly."""
788 790 if session in (0, history_manager.session_number):
789 791 return str(line)
790 792 return "%s/%s" % (session, line)
791 793
792 794 # Check if output to specific file was requested.
793 795 try:
794 796 outfname = opts['f']
795 797 except KeyError:
796 798 outfile = io.stdout # default
797 799 # We don't want to close stdout at the end!
798 800 close_at_end = False
799 801 else:
800 802 if os.path.exists(outfname):
801 803 try:
802 804 ans = io.ask_yes_no("File %r exists. Overwrite?" % outfname)
803 805 except StdinNotImplementedError:
804 print("Overwriting file.")
805 806 ans = True
806 807 if not ans:
807 808 print('Aborting.')
808 809 return
809
810 print("Overwriting file.")
810 811 outfile = open(outfname,'w')
811 812 close_at_end = True
812 813
813 814 print_nums = 'n' in opts
814 815 get_output = 'o' in opts
815 816 pyprompts = 'p' in opts
816 817 # Raw history is the default
817 818 raw = not('t' in opts)
818 819
819 820 default_length = 40
820 821 pattern = None
821 822
822 823 if 'g' in opts: # Glob search
823 824 pattern = "*" + args + "*" if args else "*"
824 825 hist = history_manager.search(pattern, raw=raw, output=get_output)
825 826 print_nums = True
826 827 elif 'l' in opts: # Get 'tail'
827 828 try:
828 829 n = int(args)
829 830 except ValueError, IndexError:
830 831 n = 10
831 832 hist = history_manager.get_tail(n, raw=raw, output=get_output)
832 833 else:
833 834 if args: # Get history by ranges
834 835 hist = history_manager.get_range_by_str(args, raw, get_output)
835 836 else: # Just get history for the current session
836 837 hist = history_manager.get_range(raw=raw, output=get_output)
837 838
838 839 # We could be displaying the entire history, so let's not try to pull it
839 840 # into a list in memory. Anything that needs more space will just misalign.
840 841 width = 4
841 842
842 843 for session, lineno, inline in hist:
843 844 # Print user history with tabs expanded to 4 spaces. The GUI clients
844 845 # use hard tabs for easier usability in auto-indented code, but we want
845 846 # to produce PEP-8 compliant history for safe pasting into an editor.
846 847 if get_output:
847 848 inline, output = inline
848 849 inline = inline.expandtabs(4).rstrip()
849 850
850 851 multiline = "\n" in inline
851 852 line_sep = '\n' if multiline else ' '
852 853 if print_nums:
853 854 print('%s:%s' % (_format_lineno(session, lineno).rjust(width),
854 855 line_sep), file=outfile, end='')
855 856 if pyprompts:
856 857 print(">>> ", end="", file=outfile)
857 858 if multiline:
858 859 inline = "\n... ".join(inline.splitlines()) + "\n..."
859 860 print(inline, file=outfile)
860 861 if get_output and output:
861 862 print(output, file=outfile)
862 863
863 864 if close_at_end:
864 865 outfile.close()
865 866
866 867
867 868 def magic_rep(self, arg):
868 869 r"""Repeat a command, or get command to input line for editing.
869 870
870 871 %recall and %rep are equivalent.
871 872
872 873 - %recall (no arguments):
873 874
874 875 Place a string version of last computation result (stored in the special '_'
875 876 variable) to the next input prompt. Allows you to create elaborate command
876 877 lines without using copy-paste::
877 878
878 879 In[1]: l = ["hei", "vaan"]
879 880 In[2]: "".join(l)
880 881 Out[2]: heivaan
881 882 In[3]: %rep
882 883 In[4]: heivaan_ <== cursor blinking
883 884
884 885 %recall 45
885 886
886 887 Place history line 45 on the next input prompt. Use %hist to find
887 888 out the number.
888 889
889 890 %recall 1-4
890 891
891 892 Combine the specified lines into one cell, and place it on the next
892 893 input prompt. See %history for the slice syntax.
893 894
894 895 %recall foo+bar
895 896
896 897 If foo+bar can be evaluated in the user namespace, the result is
897 898 placed at the next input prompt. Otherwise, the history is searched
898 899 for lines which contain that substring, and the most recent one is
899 900 placed at the next input prompt.
900 901 """
901 902 if not arg: # Last output
902 903 self.set_next_input(str(self.shell.user_ns["_"]))
903 904 return
904 905 # Get history range
905 906 histlines = self.history_manager.get_range_by_str(arg)
906 907 cmd = "\n".join(x[2] for x in histlines)
907 908 if cmd:
908 909 self.set_next_input(cmd.rstrip())
909 910 return
910 911
911 912 try: # Variable in user namespace
912 913 cmd = str(eval(arg, self.shell.user_ns))
913 914 except Exception: # Search for term in history
914 915 histlines = self.history_manager.search("*"+arg+"*")
915 916 for h in reversed([x[2] for x in histlines]):
916 917 if 'rep' in h:
917 918 continue
918 919 self.set_next_input(h.rstrip())
919 920 return
920 921 else:
921 922 self.set_next_input(cmd.rstrip())
922 923 print("Couldn't evaluate or find in history:", arg)
923 924
924 925 def magic_rerun(self, parameter_s=''):
925 926 """Re-run previous input
926 927
927 928 By default, you can specify ranges of input history to be repeated
928 929 (as with %history). With no arguments, it will repeat the last line.
929 930
930 931 Options:
931 932
932 933 -l <n> : Repeat the last n lines of input, not including the
933 934 current command.
934 935
935 936 -g foo : Repeat the most recent line which contains foo
936 937 """
937 938 opts, args = self.parse_options(parameter_s, 'l:g:', mode='string')
938 939 if "l" in opts: # Last n lines
939 940 n = int(opts['l'])
940 941 hist = self.history_manager.get_tail(n)
941 942 elif "g" in opts: # Search
942 943 p = "*"+opts['g']+"*"
943 944 hist = list(self.history_manager.search(p))
944 945 for l in reversed(hist):
945 946 if "rerun" not in l[2]:
946 947 hist = [l] # The last match which isn't a %rerun
947 948 break
948 949 else:
949 950 hist = [] # No matches except %rerun
950 951 elif args: # Specify history ranges
951 952 hist = self.history_manager.get_range_by_str(args)
952 953 else: # Last line
953 954 hist = self.history_manager.get_tail(1)
954 955 hist = [x[2] for x in hist]
955 956 if not hist:
956 957 print("No lines in history match specification")
957 958 return
958 959 histlines = "\n".join(hist)
959 960 print("=== Executing: ===")
960 961 print(histlines)
961 962 print("=== Output: ===")
962 963 self.run_cell("\n".join(hist), store_history=False)
963 964
964 965
965 966 def init_ipython(ip):
966 967 ip.define_magic("rep", magic_rep)
967 968 ip.define_magic("recall", magic_rep)
968 969 ip.define_magic("rerun", magic_rerun)
969 970 ip.define_magic("hist",magic_history) # Alternative name
970 971 ip.define_magic("history",magic_history)
971 972
972 973 # XXX - ipy_completers are in quarantine, need to be updated to new apis
973 974 #import ipy_completers
974 975 #ipy_completers.quick_completer('%hist' ,'-g -t -r -n')
@@ -1,3688 +1,3700 b''
1 1 # encoding: utf-8
2 2 """Magic functions for InteractiveShell.
3 3 """
4 4
5 5 #-----------------------------------------------------------------------------
6 6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 7 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
8 8 # Copyright (C) 2008-2011 The IPython Development Team
9 9
10 10 # Distributed under the terms of the BSD License. The full license is in
11 11 # the file COPYING, distributed as part of this software.
12 12 #-----------------------------------------------------------------------------
13 13
14 14 #-----------------------------------------------------------------------------
15 15 # Imports
16 16 #-----------------------------------------------------------------------------
17 17
18 18 import __builtin__ as builtin_mod
19 19 import __future__
20 20 import bdb
21 21 import inspect
22 22 import imp
23 23 import os
24 24 import sys
25 25 import shutil
26 26 import re
27 27 import time
28 28 from StringIO import StringIO
29 29 from getopt import getopt,GetoptError
30 30 from pprint import pformat
31 31 from xmlrpclib import ServerProxy
32 32
33 33 # cProfile was added in Python2.5
34 34 try:
35 35 import cProfile as profile
36 36 import pstats
37 37 except ImportError:
38 38 # profile isn't bundled by default in Debian for license reasons
39 39 try:
40 40 import profile,pstats
41 41 except ImportError:
42 42 profile = pstats = None
43 43
44 44 import IPython
45 45 from IPython.core import debugger, oinspect
46 46 from IPython.core.error import TryNext
47 47 from IPython.core.error import UsageError
48 48 from IPython.core.error import StdinNotImplementedError
49 49 from IPython.core.fakemodule import FakeModule
50 50 from IPython.core.profiledir import ProfileDir
51 51 from IPython.core.macro import Macro
52 52 from IPython.core import magic_arguments, page
53 53 from IPython.core.prefilter import ESC_MAGIC
54 54 from IPython.core.pylabtools import mpl_runner
55 55 from IPython.testing.skipdoctest import skip_doctest
56 56 from IPython.utils import py3compat
57 57 from IPython.utils.io import file_read, nlprint
58 58 from IPython.utils.module_paths import find_mod
59 59 from IPython.utils.path import get_py_filename, unquote_filename
60 60 from IPython.utils.process import arg_split, abbrev_cwd
61 61 from IPython.utils.terminal import set_term_title
62 62 from IPython.utils.text import LSString, SList, format_screen
63 63 from IPython.utils.timing import clock, clock2
64 64 from IPython.utils.warn import warn, error
65 65 from IPython.utils.ipstruct import Struct
66 66 from IPython.config.application import Application
67 67
68 68 #-----------------------------------------------------------------------------
69 69 # Utility functions
70 70 #-----------------------------------------------------------------------------
71 71
72 72 def on_off(tag):
73 73 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
74 74 return ['OFF','ON'][tag]
75 75
76 76 class Bunch: pass
77 77
78 78 def compress_dhist(dh):
79 79 head, tail = dh[:-10], dh[-10:]
80 80
81 81 newhead = []
82 82 done = set()
83 83 for h in head:
84 84 if h in done:
85 85 continue
86 86 newhead.append(h)
87 87 done.add(h)
88 88
89 89 return newhead + tail
90 90
91 91 def needs_local_scope(func):
92 92 """Decorator to mark magic functions which need to local scope to run."""
93 93 func.needs_local_scope = True
94 94 return func
95 95
96 96
97 97 # Used for exception handling in magic_edit
98 98 class MacroToEdit(ValueError): pass
99 99
100 100 # Taken from PEP 263, this is the official encoding regexp.
101 101 _encoding_declaration_re = re.compile(r"^#.*coding[:=]\s*([-\w.]+)")
102 102
103 103 #***************************************************************************
104 104 # Main class implementing Magic functionality
105 105
106 106 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
107 107 # on construction of the main InteractiveShell object. Something odd is going
108 108 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
109 109 # eventually this needs to be clarified.
110 110 # BG: This is because InteractiveShell inherits from this, but is itself a
111 111 # Configurable. This messes up the MRO in some way. The fix is that we need to
112 112 # make Magic a configurable that InteractiveShell does not subclass.
113 113
114 114 class Magic:
115 115 """Magic functions for InteractiveShell.
116 116
117 117 Shell functions which can be reached as %function_name. All magic
118 118 functions should accept a string, which they can parse for their own
119 119 needs. This can make some functions easier to type, eg `%cd ../`
120 120 vs. `%cd("../")`
121 121
122 122 ALL definitions MUST begin with the prefix magic_. The user won't need it
123 123 at the command line, but it is is needed in the definition. """
124 124
125 125 # class globals
126 126 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
127 127 'Automagic is ON, % prefix NOT needed for magic functions.']
128 128
129 129
130 130 configurables = None
131 131 #......................................................................
132 132 # some utility functions
133 133
134 134 def __init__(self,shell):
135 135
136 136 self.options_table = {}
137 137 if profile is None:
138 138 self.magic_prun = self.profile_missing_notice
139 139 self.shell = shell
140 140 if self.configurables is None:
141 141 self.configurables = []
142 142
143 143 # namespace for holding state we may need
144 144 self._magic_state = Bunch()
145 145
146 146 def profile_missing_notice(self, *args, **kwargs):
147 147 error("""\
148 148 The profile module could not be found. It has been removed from the standard
149 149 python packages because of its non-free license. To use profiling, install the
150 150 python-profiler package from non-free.""")
151 151
152 152 def default_option(self,fn,optstr):
153 153 """Make an entry in the options_table for fn, with value optstr"""
154 154
155 155 if fn not in self.lsmagic():
156 156 error("%s is not a magic function" % fn)
157 157 self.options_table[fn] = optstr
158 158
159 159 def lsmagic(self):
160 160 """Return a list of currently available magic functions.
161 161
162 162 Gives a list of the bare names after mangling (['ls','cd', ...], not
163 163 ['magic_ls','magic_cd',...]"""
164 164
165 165 # FIXME. This needs a cleanup, in the way the magics list is built.
166 166
167 167 # magics in class definition
168 168 class_magic = lambda fn: fn.startswith('magic_') and \
169 169 callable(Magic.__dict__[fn])
170 170 # in instance namespace (run-time user additions)
171 171 inst_magic = lambda fn: fn.startswith('magic_') and \
172 172 callable(self.__dict__[fn])
173 173 # and bound magics by user (so they can access self):
174 174 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
175 175 callable(self.__class__.__dict__[fn])
176 176 magics = filter(class_magic,Magic.__dict__.keys()) + \
177 177 filter(inst_magic,self.__dict__.keys()) + \
178 178 filter(inst_bound_magic,self.__class__.__dict__.keys())
179 179 out = []
180 180 for fn in set(magics):
181 181 out.append(fn.replace('magic_','',1))
182 182 out.sort()
183 183 return out
184 184
185 185 def extract_input_lines(self, range_str, raw=False):
186 186 """Return as a string a set of input history slices.
187 187
188 188 Inputs:
189 189
190 190 - range_str: the set of slices is given as a string, like
191 191 "~5/6-~4/2 4:8 9", since this function is for use by magic functions
192 192 which get their arguments as strings. The number before the / is the
193 193 session number: ~n goes n back from the current session.
194 194
195 195 Optional inputs:
196 196
197 197 - raw(False): by default, the processed input is used. If this is
198 198 true, the raw input history is used instead.
199 199
200 200 Note that slices can be called with two notations:
201 201
202 202 N:M -> standard python form, means including items N...(M-1).
203 203
204 204 N-M -> include items N..M (closed endpoint)."""
205 205 lines = self.shell.history_manager.\
206 206 get_range_by_str(range_str, raw=raw)
207 207 return "\n".join(x for _, _, x in lines)
208 208
209 209 def arg_err(self,func):
210 210 """Print docstring if incorrect arguments were passed"""
211 211 print 'Error in arguments:'
212 212 print oinspect.getdoc(func)
213 213
214 214 def format_latex(self,strng):
215 215 """Format a string for latex inclusion."""
216 216
217 217 # Characters that need to be escaped for latex:
218 218 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
219 219 # Magic command names as headers:
220 220 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
221 221 re.MULTILINE)
222 222 # Magic commands
223 223 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
224 224 re.MULTILINE)
225 225 # Paragraph continue
226 226 par_re = re.compile(r'\\$',re.MULTILINE)
227 227
228 228 # The "\n" symbol
229 229 newline_re = re.compile(r'\\n')
230 230
231 231 # Now build the string for output:
232 232 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
233 233 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
234 234 strng)
235 235 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
236 236 strng = par_re.sub(r'\\\\',strng)
237 237 strng = escape_re.sub(r'\\\1',strng)
238 238 strng = newline_re.sub(r'\\textbackslash{}n',strng)
239 239 return strng
240 240
241 241 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
242 242 """Parse options passed to an argument string.
243 243
244 244 The interface is similar to that of getopt(), but it returns back a
245 245 Struct with the options as keys and the stripped argument string still
246 246 as a string.
247 247
248 248 arg_str is quoted as a true sys.argv vector by using shlex.split.
249 249 This allows us to easily expand variables, glob files, quote
250 250 arguments, etc.
251 251
252 252 Options:
253 253 -mode: default 'string'. If given as 'list', the argument string is
254 254 returned as a list (split on whitespace) instead of a string.
255 255
256 256 -list_all: put all option values in lists. Normally only options
257 257 appearing more than once are put in a list.
258 258
259 259 -posix (True): whether to split the input line in POSIX mode or not,
260 260 as per the conventions outlined in the shlex module from the
261 261 standard library."""
262 262
263 263 # inject default options at the beginning of the input line
264 264 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
265 265 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
266 266
267 267 mode = kw.get('mode','string')
268 268 if mode not in ['string','list']:
269 269 raise ValueError,'incorrect mode given: %s' % mode
270 270 # Get options
271 271 list_all = kw.get('list_all',0)
272 272 posix = kw.get('posix', os.name == 'posix')
273 273 strict = kw.get('strict', True)
274 274
275 275 # Check if we have more than one argument to warrant extra processing:
276 276 odict = {} # Dictionary with options
277 277 args = arg_str.split()
278 278 if len(args) >= 1:
279 279 # If the list of inputs only has 0 or 1 thing in it, there's no
280 280 # need to look for options
281 281 argv = arg_split(arg_str, posix, strict)
282 282 # Do regular option processing
283 283 try:
284 284 opts,args = getopt(argv,opt_str,*long_opts)
285 285 except GetoptError,e:
286 286 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
287 287 " ".join(long_opts)))
288 288 for o,a in opts:
289 289 if o.startswith('--'):
290 290 o = o[2:]
291 291 else:
292 292 o = o[1:]
293 293 try:
294 294 odict[o].append(a)
295 295 except AttributeError:
296 296 odict[o] = [odict[o],a]
297 297 except KeyError:
298 298 if list_all:
299 299 odict[o] = [a]
300 300 else:
301 301 odict[o] = a
302 302
303 303 # Prepare opts,args for return
304 304 opts = Struct(odict)
305 305 if mode == 'string':
306 306 args = ' '.join(args)
307 307
308 308 return opts,args
309 309
310 310 #......................................................................
311 311 # And now the actual magic functions
312 312
313 313 # Functions for IPython shell work (vars,funcs, config, etc)
314 314 def magic_lsmagic(self, parameter_s = ''):
315 315 """List currently available magic functions."""
316 316 mesc = ESC_MAGIC
317 317 print 'Available magic functions:\n'+mesc+\
318 318 (' '+mesc).join(self.lsmagic())
319 319 print '\n' + Magic.auto_status[self.shell.automagic]
320 320 return None
321 321
322 322 def magic_magic(self, parameter_s = ''):
323 323 """Print information about the magic function system.
324 324
325 325 Supported formats: -latex, -brief, -rest
326 326 """
327 327
328 328 mode = ''
329 329 try:
330 330 if parameter_s.split()[0] == '-latex':
331 331 mode = 'latex'
332 332 if parameter_s.split()[0] == '-brief':
333 333 mode = 'brief'
334 334 if parameter_s.split()[0] == '-rest':
335 335 mode = 'rest'
336 336 rest_docs = []
337 337 except:
338 338 pass
339 339
340 340 magic_docs = []
341 341 for fname in self.lsmagic():
342 342 mname = 'magic_' + fname
343 343 for space in (Magic,self,self.__class__):
344 344 try:
345 345 fn = space.__dict__[mname]
346 346 except KeyError:
347 347 pass
348 348 else:
349 349 break
350 350 if mode == 'brief':
351 351 # only first line
352 352 if fn.__doc__:
353 353 fndoc = fn.__doc__.split('\n',1)[0]
354 354 else:
355 355 fndoc = 'No documentation'
356 356 else:
357 357 if fn.__doc__:
358 358 fndoc = fn.__doc__.rstrip()
359 359 else:
360 360 fndoc = 'No documentation'
361 361
362 362
363 363 if mode == 'rest':
364 364 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
365 365 fname,fndoc))
366 366
367 367 else:
368 368 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
369 369 fname,fndoc))
370 370
371 371 magic_docs = ''.join(magic_docs)
372 372
373 373 if mode == 'rest':
374 374 return "".join(rest_docs)
375 375
376 376 if mode == 'latex':
377 377 print self.format_latex(magic_docs)
378 378 return
379 379 else:
380 380 magic_docs = format_screen(magic_docs)
381 381 if mode == 'brief':
382 382 return magic_docs
383 383
384 384 outmsg = """
385 385 IPython's 'magic' functions
386 386 ===========================
387 387
388 388 The magic function system provides a series of functions which allow you to
389 389 control the behavior of IPython itself, plus a lot of system-type
390 390 features. All these functions are prefixed with a % character, but parameters
391 391 are given without parentheses or quotes.
392 392
393 393 NOTE: If you have 'automagic' enabled (via the command line option or with the
394 394 %automagic function), you don't need to type in the % explicitly. By default,
395 395 IPython ships with automagic on, so you should only rarely need the % escape.
396 396
397 397 Example: typing '%cd mydir' (without the quotes) changes you working directory
398 398 to 'mydir', if it exists.
399 399
400 400 For a list of the available magic functions, use %lsmagic. For a description
401 401 of any of them, type %magic_name?, e.g. '%cd?'.
402 402
403 403 Currently the magic system has the following functions:\n"""
404 404
405 405 mesc = ESC_MAGIC
406 406 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
407 407 "\n\n%s%s\n\n%s" % (outmsg,
408 408 magic_docs,mesc,mesc,
409 409 (' '+mesc).join(self.lsmagic()),
410 410 Magic.auto_status[self.shell.automagic] ) )
411 411 page.page(outmsg)
412 412
413 413 def magic_automagic(self, parameter_s = ''):
414 414 """Make magic functions callable without having to type the initial %.
415 415
416 416 Without argumentsl toggles on/off (when off, you must call it as
417 417 %automagic, of course). With arguments it sets the value, and you can
418 418 use any of (case insensitive):
419 419
420 420 - on,1,True: to activate
421 421
422 422 - off,0,False: to deactivate.
423 423
424 424 Note that magic functions have lowest priority, so if there's a
425 425 variable whose name collides with that of a magic fn, automagic won't
426 426 work for that function (you get the variable instead). However, if you
427 427 delete the variable (del var), the previously shadowed magic function
428 428 becomes visible to automagic again."""
429 429
430 430 arg = parameter_s.lower()
431 431 if parameter_s in ('on','1','true'):
432 432 self.shell.automagic = True
433 433 elif parameter_s in ('off','0','false'):
434 434 self.shell.automagic = False
435 435 else:
436 436 self.shell.automagic = not self.shell.automagic
437 437 print '\n' + Magic.auto_status[self.shell.automagic]
438 438
439 439 @skip_doctest
440 440 def magic_autocall(self, parameter_s = ''):
441 441 """Make functions callable without having to type parentheses.
442 442
443 443 Usage:
444 444
445 445 %autocall [mode]
446 446
447 447 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
448 448 value is toggled on and off (remembering the previous state).
449 449
450 450 In more detail, these values mean:
451 451
452 452 0 -> fully disabled
453 453
454 454 1 -> active, but do not apply if there are no arguments on the line.
455 455
456 456 In this mode, you get:
457 457
458 458 In [1]: callable
459 459 Out[1]: <built-in function callable>
460 460
461 461 In [2]: callable 'hello'
462 462 ------> callable('hello')
463 463 Out[2]: False
464 464
465 465 2 -> Active always. Even if no arguments are present, the callable
466 466 object is called:
467 467
468 468 In [2]: float
469 469 ------> float()
470 470 Out[2]: 0.0
471 471
472 472 Note that even with autocall off, you can still use '/' at the start of
473 473 a line to treat the first argument on the command line as a function
474 474 and add parentheses to it:
475 475
476 476 In [8]: /str 43
477 477 ------> str(43)
478 478 Out[8]: '43'
479 479
480 480 # all-random (note for auto-testing)
481 481 """
482 482
483 483 if parameter_s:
484 484 arg = int(parameter_s)
485 485 else:
486 486 arg = 'toggle'
487 487
488 488 if not arg in (0,1,2,'toggle'):
489 489 error('Valid modes: (0->Off, 1->Smart, 2->Full')
490 490 return
491 491
492 492 if arg in (0,1,2):
493 493 self.shell.autocall = arg
494 494 else: # toggle
495 495 if self.shell.autocall:
496 496 self._magic_state.autocall_save = self.shell.autocall
497 497 self.shell.autocall = 0
498 498 else:
499 499 try:
500 500 self.shell.autocall = self._magic_state.autocall_save
501 501 except AttributeError:
502 502 self.shell.autocall = self._magic_state.autocall_save = 1
503 503
504 504 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
505 505
506 506
507 507 def magic_page(self, parameter_s=''):
508 508 """Pretty print the object and display it through a pager.
509 509
510 510 %page [options] OBJECT
511 511
512 512 If no object is given, use _ (last output).
513 513
514 514 Options:
515 515
516 516 -r: page str(object), don't pretty-print it."""
517 517
518 518 # After a function contributed by Olivier Aubert, slightly modified.
519 519
520 520 # Process options/args
521 521 opts,args = self.parse_options(parameter_s,'r')
522 522 raw = 'r' in opts
523 523
524 524 oname = args and args or '_'
525 525 info = self._ofind(oname)
526 526 if info['found']:
527 527 txt = (raw and str or pformat)( info['obj'] )
528 528 page.page(txt)
529 529 else:
530 530 print 'Object `%s` not found' % oname
531 531
532 532 def magic_profile(self, parameter_s=''):
533 533 """Print your currently active IPython profile."""
534 534 from IPython.core.application import BaseIPythonApplication
535 535 if BaseIPythonApplication.initialized():
536 536 print BaseIPythonApplication.instance().profile
537 537 else:
538 538 error("profile is an application-level value, but you don't appear to be in an IPython application")
539 539
540 540 def magic_pinfo(self, parameter_s='', namespaces=None):
541 541 """Provide detailed information about an object.
542 542
543 543 '%pinfo object' is just a synonym for object? or ?object."""
544 544
545 545 #print 'pinfo par: <%s>' % parameter_s # dbg
546 546
547 547
548 548 # detail_level: 0 -> obj? , 1 -> obj??
549 549 detail_level = 0
550 550 # We need to detect if we got called as 'pinfo pinfo foo', which can
551 551 # happen if the user types 'pinfo foo?' at the cmd line.
552 552 pinfo,qmark1,oname,qmark2 = \
553 553 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
554 554 if pinfo or qmark1 or qmark2:
555 555 detail_level = 1
556 556 if "*" in oname:
557 557 self.magic_psearch(oname)
558 558 else:
559 559 self.shell._inspect('pinfo', oname, detail_level=detail_level,
560 560 namespaces=namespaces)
561 561
562 562 def magic_pinfo2(self, parameter_s='', namespaces=None):
563 563 """Provide extra detailed information about an object.
564 564
565 565 '%pinfo2 object' is just a synonym for object?? or ??object."""
566 566 self.shell._inspect('pinfo', parameter_s, detail_level=1,
567 567 namespaces=namespaces)
568 568
569 569 @skip_doctest
570 570 def magic_pdef(self, parameter_s='', namespaces=None):
571 571 """Print the definition header for any callable object.
572 572
573 573 If the object is a class, print the constructor information.
574 574
575 575 Examples
576 576 --------
577 577 ::
578 578
579 579 In [3]: %pdef urllib.urlopen
580 580 urllib.urlopen(url, data=None, proxies=None)
581 581 """
582 582 self._inspect('pdef',parameter_s, namespaces)
583 583
584 584 def magic_pdoc(self, parameter_s='', namespaces=None):
585 585 """Print the docstring for an object.
586 586
587 587 If the given object is a class, it will print both the class and the
588 588 constructor docstrings."""
589 589 self._inspect('pdoc',parameter_s, namespaces)
590 590
591 591 def magic_psource(self, parameter_s='', namespaces=None):
592 592 """Print (or run through pager) the source code for an object."""
593 593 self._inspect('psource',parameter_s, namespaces)
594 594
595 595 def magic_pfile(self, parameter_s=''):
596 596 """Print (or run through pager) the file where an object is defined.
597 597
598 598 The file opens at the line where the object definition begins. IPython
599 599 will honor the environment variable PAGER if set, and otherwise will
600 600 do its best to print the file in a convenient form.
601 601
602 602 If the given argument is not an object currently defined, IPython will
603 603 try to interpret it as a filename (automatically adding a .py extension
604 604 if needed). You can thus use %pfile as a syntax highlighting code
605 605 viewer."""
606 606
607 607 # first interpret argument as an object name
608 608 out = self._inspect('pfile',parameter_s)
609 609 # if not, try the input as a filename
610 610 if out == 'not found':
611 611 try:
612 612 filename = get_py_filename(parameter_s)
613 613 except IOError,msg:
614 614 print msg
615 615 return
616 616 page.page(self.shell.inspector.format(file(filename).read()))
617 617
618 618 def magic_psearch(self, parameter_s=''):
619 619 """Search for object in namespaces by wildcard.
620 620
621 621 %psearch [options] PATTERN [OBJECT TYPE]
622 622
623 623 Note: ? can be used as a synonym for %psearch, at the beginning or at
624 624 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
625 625 rest of the command line must be unchanged (options come first), so
626 626 for example the following forms are equivalent
627 627
628 628 %psearch -i a* function
629 629 -i a* function?
630 630 ?-i a* function
631 631
632 632 Arguments:
633 633
634 634 PATTERN
635 635
636 636 where PATTERN is a string containing * as a wildcard similar to its
637 637 use in a shell. The pattern is matched in all namespaces on the
638 638 search path. By default objects starting with a single _ are not
639 639 matched, many IPython generated objects have a single
640 640 underscore. The default is case insensitive matching. Matching is
641 641 also done on the attributes of objects and not only on the objects
642 642 in a module.
643 643
644 644 [OBJECT TYPE]
645 645
646 646 Is the name of a python type from the types module. The name is
647 647 given in lowercase without the ending type, ex. StringType is
648 648 written string. By adding a type here only objects matching the
649 649 given type are matched. Using all here makes the pattern match all
650 650 types (this is the default).
651 651
652 652 Options:
653 653
654 654 -a: makes the pattern match even objects whose names start with a
655 655 single underscore. These names are normally omitted from the
656 656 search.
657 657
658 658 -i/-c: make the pattern case insensitive/sensitive. If neither of
659 659 these options are given, the default is read from your configuration
660 660 file, with the option ``InteractiveShell.wildcards_case_sensitive``.
661 661 If this option is not specified in your configuration file, IPython's
662 662 internal default is to do a case sensitive search.
663 663
664 664 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
665 665 specify can be searched in any of the following namespaces:
666 666 'builtin', 'user', 'user_global','internal', 'alias', where
667 667 'builtin' and 'user' are the search defaults. Note that you should
668 668 not use quotes when specifying namespaces.
669 669
670 670 'Builtin' contains the python module builtin, 'user' contains all
671 671 user data, 'alias' only contain the shell aliases and no python
672 672 objects, 'internal' contains objects used by IPython. The
673 673 'user_global' namespace is only used by embedded IPython instances,
674 674 and it contains module-level globals. You can add namespaces to the
675 675 search with -s or exclude them with -e (these options can be given
676 676 more than once).
677 677
678 678 Examples:
679 679
680 680 %psearch a* -> objects beginning with an a
681 681 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
682 682 %psearch a* function -> all functions beginning with an a
683 683 %psearch re.e* -> objects beginning with an e in module re
684 684 %psearch r*.e* -> objects that start with e in modules starting in r
685 685 %psearch r*.* string -> all strings in modules beginning with r
686 686
687 687 Case sensitive search:
688 688
689 689 %psearch -c a* list all object beginning with lower case a
690 690
691 691 Show objects beginning with a single _:
692 692
693 693 %psearch -a _* list objects beginning with a single underscore"""
694 694 try:
695 695 parameter_s.encode('ascii')
696 696 except UnicodeEncodeError:
697 697 print 'Python identifiers can only contain ascii characters.'
698 698 return
699 699
700 700 # default namespaces to be searched
701 701 def_search = ['user_local', 'user_global', 'builtin']
702 702
703 703 # Process options/args
704 704 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
705 705 opt = opts.get
706 706 shell = self.shell
707 707 psearch = shell.inspector.psearch
708 708
709 709 # select case options
710 710 if opts.has_key('i'):
711 711 ignore_case = True
712 712 elif opts.has_key('c'):
713 713 ignore_case = False
714 714 else:
715 715 ignore_case = not shell.wildcards_case_sensitive
716 716
717 717 # Build list of namespaces to search from user options
718 718 def_search.extend(opt('s',[]))
719 719 ns_exclude = ns_exclude=opt('e',[])
720 720 ns_search = [nm for nm in def_search if nm not in ns_exclude]
721 721
722 722 # Call the actual search
723 723 try:
724 724 psearch(args,shell.ns_table,ns_search,
725 725 show_all=opt('a'),ignore_case=ignore_case)
726 726 except:
727 727 shell.showtraceback()
728 728
729 729 @skip_doctest
730 730 def magic_who_ls(self, parameter_s=''):
731 731 """Return a sorted list of all interactive variables.
732 732
733 733 If arguments are given, only variables of types matching these
734 734 arguments are returned.
735 735
736 736 Examples
737 737 --------
738 738
739 739 Define two variables and list them with who_ls::
740 740
741 741 In [1]: alpha = 123
742 742
743 743 In [2]: beta = 'test'
744 744
745 745 In [3]: %who_ls
746 746 Out[3]: ['alpha', 'beta']
747 747
748 748 In [4]: %who_ls int
749 749 Out[4]: ['alpha']
750 750
751 751 In [5]: %who_ls str
752 752 Out[5]: ['beta']
753 753 """
754 754
755 755 user_ns = self.shell.user_ns
756 756 user_ns_hidden = self.shell.user_ns_hidden
757 757 out = [ i for i in user_ns
758 758 if not i.startswith('_') \
759 759 and not i in user_ns_hidden ]
760 760
761 761 typelist = parameter_s.split()
762 762 if typelist:
763 763 typeset = set(typelist)
764 764 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
765 765
766 766 out.sort()
767 767 return out
768 768
769 769 @skip_doctest
770 770 def magic_who(self, parameter_s=''):
771 771 """Print all interactive variables, with some minimal formatting.
772 772
773 773 If any arguments are given, only variables whose type matches one of
774 774 these are printed. For example:
775 775
776 776 %who function str
777 777
778 778 will only list functions and strings, excluding all other types of
779 779 variables. To find the proper type names, simply use type(var) at a
780 780 command line to see how python prints type names. For example:
781 781
782 782 In [1]: type('hello')\\
783 783 Out[1]: <type 'str'>
784 784
785 785 indicates that the type name for strings is 'str'.
786 786
787 787 %who always excludes executed names loaded through your configuration
788 788 file and things which are internal to IPython.
789 789
790 790 This is deliberate, as typically you may load many modules and the
791 791 purpose of %who is to show you only what you've manually defined.
792 792
793 793 Examples
794 794 --------
795 795
796 796 Define two variables and list them with who::
797 797
798 798 In [1]: alpha = 123
799 799
800 800 In [2]: beta = 'test'
801 801
802 802 In [3]: %who
803 803 alpha beta
804 804
805 805 In [4]: %who int
806 806 alpha
807 807
808 808 In [5]: %who str
809 809 beta
810 810 """
811 811
812 812 varlist = self.magic_who_ls(parameter_s)
813 813 if not varlist:
814 814 if parameter_s:
815 815 print 'No variables match your requested type.'
816 816 else:
817 817 print 'Interactive namespace is empty.'
818 818 return
819 819
820 820 # if we have variables, move on...
821 821 count = 0
822 822 for i in varlist:
823 823 print i+'\t',
824 824 count += 1
825 825 if count > 8:
826 826 count = 0
827 827 print
828 828 print
829 829
830 830 @skip_doctest
831 831 def magic_whos(self, parameter_s=''):
832 832 """Like %who, but gives some extra information about each variable.
833 833
834 834 The same type filtering of %who can be applied here.
835 835
836 836 For all variables, the type is printed. Additionally it prints:
837 837
838 838 - For {},[],(): their length.
839 839
840 840 - For numpy arrays, a summary with shape, number of
841 841 elements, typecode and size in memory.
842 842
843 843 - Everything else: a string representation, snipping their middle if
844 844 too long.
845 845
846 846 Examples
847 847 --------
848 848
849 849 Define two variables and list them with whos::
850 850
851 851 In [1]: alpha = 123
852 852
853 853 In [2]: beta = 'test'
854 854
855 855 In [3]: %whos
856 856 Variable Type Data/Info
857 857 --------------------------------
858 858 alpha int 123
859 859 beta str test
860 860 """
861 861
862 862 varnames = self.magic_who_ls(parameter_s)
863 863 if not varnames:
864 864 if parameter_s:
865 865 print 'No variables match your requested type.'
866 866 else:
867 867 print 'Interactive namespace is empty.'
868 868 return
869 869
870 870 # if we have variables, move on...
871 871
872 872 # for these types, show len() instead of data:
873 873 seq_types = ['dict', 'list', 'tuple']
874 874
875 875 # for numpy arrays, display summary info
876 876 ndarray_type = None
877 877 if 'numpy' in sys.modules:
878 878 try:
879 879 from numpy import ndarray
880 880 except ImportError:
881 881 pass
882 882 else:
883 883 ndarray_type = ndarray.__name__
884 884
885 885 # Find all variable names and types so we can figure out column sizes
886 886 def get_vars(i):
887 887 return self.shell.user_ns[i]
888 888
889 889 # some types are well known and can be shorter
890 890 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
891 891 def type_name(v):
892 892 tn = type(v).__name__
893 893 return abbrevs.get(tn,tn)
894 894
895 895 varlist = map(get_vars,varnames)
896 896
897 897 typelist = []
898 898 for vv in varlist:
899 899 tt = type_name(vv)
900 900
901 901 if tt=='instance':
902 902 typelist.append( abbrevs.get(str(vv.__class__),
903 903 str(vv.__class__)))
904 904 else:
905 905 typelist.append(tt)
906 906
907 907 # column labels and # of spaces as separator
908 908 varlabel = 'Variable'
909 909 typelabel = 'Type'
910 910 datalabel = 'Data/Info'
911 911 colsep = 3
912 912 # variable format strings
913 913 vformat = "{0:<{varwidth}}{1:<{typewidth}}"
914 914 aformat = "%s: %s elems, type `%s`, %s bytes"
915 915 # find the size of the columns to format the output nicely
916 916 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
917 917 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
918 918 # table header
919 919 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
920 920 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
921 921 # and the table itself
922 922 kb = 1024
923 923 Mb = 1048576 # kb**2
924 924 for vname,var,vtype in zip(varnames,varlist,typelist):
925 925 print vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth),
926 926 if vtype in seq_types:
927 927 print "n="+str(len(var))
928 928 elif vtype == ndarray_type:
929 929 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
930 930 if vtype==ndarray_type:
931 931 # numpy
932 932 vsize = var.size
933 933 vbytes = vsize*var.itemsize
934 934 vdtype = var.dtype
935 935 else:
936 936 # Numeric
937 937 vsize = Numeric.size(var)
938 938 vbytes = vsize*var.itemsize()
939 939 vdtype = var.typecode()
940 940
941 941 if vbytes < 100000:
942 942 print aformat % (vshape,vsize,vdtype,vbytes)
943 943 else:
944 944 print aformat % (vshape,vsize,vdtype,vbytes),
945 945 if vbytes < Mb:
946 946 print '(%s kb)' % (vbytes/kb,)
947 947 else:
948 948 print '(%s Mb)' % (vbytes/Mb,)
949 949 else:
950 950 try:
951 951 vstr = str(var)
952 952 except UnicodeEncodeError:
953 953 vstr = unicode(var).encode(sys.getdefaultencoding(),
954 954 'backslashreplace')
955 955 vstr = vstr.replace('\n','\\n')
956 956 if len(vstr) < 50:
957 957 print vstr
958 958 else:
959 959 print vstr[:25] + "<...>" + vstr[-25:]
960 960
961 961 def magic_reset(self, parameter_s=''):
962 962 """Resets the namespace by removing all names defined by the user.
963 963
964 964 Parameters
965 965 ----------
966 966 -f : force reset without asking for confirmation.
967 967
968 968 -s : 'Soft' reset: Only clears your namespace, leaving history intact.
969 969 References to objects may be kept. By default (without this option),
970 970 we do a 'hard' reset, giving you a new session and removing all
971 971 references to objects from the current session.
972 972
973 973 Examples
974 974 --------
975 975 In [6]: a = 1
976 976
977 977 In [7]: a
978 978 Out[7]: 1
979 979
980 980 In [8]: 'a' in _ip.user_ns
981 981 Out[8]: True
982 982
983 983 In [9]: %reset -f
984 984
985 985 In [1]: 'a' in _ip.user_ns
986 986 Out[1]: False
987
988 Notes
989 -----
990 Calling this magic from clients that do not implement standard input,
991 such as the ipython notebook interface, will reset the namespace
992 without confirmation.
987 993 """
988 994 opts, args = self.parse_options(parameter_s,'sf')
989 995 if 'f' in opts:
990 996 ans = True
991 997 else:
992 998 try:
993 999 ans = self.shell.ask_yes_no(
994 1000 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ", default='n')
995 1001 except StdinNotImplementedError:
996 1002 ans = True
997 1003 if not ans:
998 1004 print 'Nothing done.'
999 1005 return
1000 1006
1001 1007 if 's' in opts: # Soft reset
1002 1008 user_ns = self.shell.user_ns
1003 1009 for i in self.magic_who_ls():
1004 1010 del(user_ns[i])
1005 1011
1006 1012 else: # Hard reset
1007 1013 self.shell.reset(new_session = False)
1008 1014
1009 1015
1010 1016
1011 1017 def magic_reset_selective(self, parameter_s=''):
1012 1018 """Resets the namespace by removing names defined by the user.
1013 1019
1014 1020 Input/Output history are left around in case you need them.
1015 1021
1016 1022 %reset_selective [-f] regex
1017 1023
1018 1024 No action is taken if regex is not included
1019 1025
1020 1026 Options
1021 1027 -f : force reset without asking for confirmation.
1022 1028
1023 1029 Examples
1024 1030 --------
1025 1031
1026 1032 We first fully reset the namespace so your output looks identical to
1027 1033 this example for pedagogical reasons; in practice you do not need a
1028 1034 full reset.
1029 1035
1030 1036 In [1]: %reset -f
1031 1037
1032 1038 Now, with a clean namespace we can make a few variables and use
1033 1039 %reset_selective to only delete names that match our regexp:
1034 1040
1035 1041 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1036 1042
1037 1043 In [3]: who_ls
1038 1044 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1039 1045
1040 1046 In [4]: %reset_selective -f b[2-3]m
1041 1047
1042 1048 In [5]: who_ls
1043 1049 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1044 1050
1045 1051 In [6]: %reset_selective -f d
1046 1052
1047 1053 In [7]: who_ls
1048 1054 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1049 1055
1050 1056 In [8]: %reset_selective -f c
1051 1057
1052 1058 In [9]: who_ls
1053 1059 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1054 1060
1055 1061 In [10]: %reset_selective -f b
1056 1062
1057 1063 In [11]: who_ls
1058 1064 Out[11]: ['a']
1065
1066 Notes
1067 -----
1068 Calling this magic from clients that do not implement standard input,
1069 such as the ipython notebook interface, will reset the namespace
1070 without confirmation.
1059 1071 """
1060 1072
1061 1073 opts, regex = self.parse_options(parameter_s,'f')
1062 1074
1063 1075 if opts.has_key('f'):
1064 1076 ans = True
1065 1077 else:
1066 1078 try:
1067 1079 ans = self.shell.ask_yes_no(
1068 1080 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
1069 1081 default='n')
1070 1082 except StdinNotImplementedError:
1071 1083 ans = True
1072 1084 if not ans:
1073 1085 print 'Nothing done.'
1074 1086 return
1075 1087 user_ns = self.shell.user_ns
1076 1088 if not regex:
1077 1089 print 'No regex pattern specified. Nothing done.'
1078 1090 return
1079 1091 else:
1080 1092 try:
1081 1093 m = re.compile(regex)
1082 1094 except TypeError:
1083 1095 raise TypeError('regex must be a string or compiled pattern')
1084 1096 for i in self.magic_who_ls():
1085 1097 if m.search(i):
1086 1098 del(user_ns[i])
1087 1099
1088 1100 def magic_xdel(self, parameter_s=''):
1089 1101 """Delete a variable, trying to clear it from anywhere that
1090 1102 IPython's machinery has references to it. By default, this uses
1091 1103 the identity of the named object in the user namespace to remove
1092 1104 references held under other names. The object is also removed
1093 1105 from the output history.
1094 1106
1095 1107 Options
1096 1108 -n : Delete the specified name from all namespaces, without
1097 1109 checking their identity.
1098 1110 """
1099 1111 opts, varname = self.parse_options(parameter_s,'n')
1100 1112 try:
1101 1113 self.shell.del_var(varname, ('n' in opts))
1102 1114 except (NameError, ValueError) as e:
1103 1115 print type(e).__name__ +": "+ str(e)
1104 1116
1105 1117 def magic_logstart(self,parameter_s=''):
1106 1118 """Start logging anywhere in a session.
1107 1119
1108 1120 %logstart [-o|-r|-t] [log_name [log_mode]]
1109 1121
1110 1122 If no name is given, it defaults to a file named 'ipython_log.py' in your
1111 1123 current directory, in 'rotate' mode (see below).
1112 1124
1113 1125 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1114 1126 history up to that point and then continues logging.
1115 1127
1116 1128 %logstart takes a second optional parameter: logging mode. This can be one
1117 1129 of (note that the modes are given unquoted):\\
1118 1130 append: well, that says it.\\
1119 1131 backup: rename (if exists) to name~ and start name.\\
1120 1132 global: single logfile in your home dir, appended to.\\
1121 1133 over : overwrite existing log.\\
1122 1134 rotate: create rotating logs name.1~, name.2~, etc.
1123 1135
1124 1136 Options:
1125 1137
1126 1138 -o: log also IPython's output. In this mode, all commands which
1127 1139 generate an Out[NN] prompt are recorded to the logfile, right after
1128 1140 their corresponding input line. The output lines are always
1129 1141 prepended with a '#[Out]# ' marker, so that the log remains valid
1130 1142 Python code.
1131 1143
1132 1144 Since this marker is always the same, filtering only the output from
1133 1145 a log is very easy, using for example a simple awk call:
1134 1146
1135 1147 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1136 1148
1137 1149 -r: log 'raw' input. Normally, IPython's logs contain the processed
1138 1150 input, so that user lines are logged in their final form, converted
1139 1151 into valid Python. For example, %Exit is logged as
1140 1152 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1141 1153 exactly as typed, with no transformations applied.
1142 1154
1143 1155 -t: put timestamps before each input line logged (these are put in
1144 1156 comments)."""
1145 1157
1146 1158 opts,par = self.parse_options(parameter_s,'ort')
1147 1159 log_output = 'o' in opts
1148 1160 log_raw_input = 'r' in opts
1149 1161 timestamp = 't' in opts
1150 1162
1151 1163 logger = self.shell.logger
1152 1164
1153 1165 # if no args are given, the defaults set in the logger constructor by
1154 1166 # ipython remain valid
1155 1167 if par:
1156 1168 try:
1157 1169 logfname,logmode = par.split()
1158 1170 except:
1159 1171 logfname = par
1160 1172 logmode = 'backup'
1161 1173 else:
1162 1174 logfname = logger.logfname
1163 1175 logmode = logger.logmode
1164 1176 # put logfname into rc struct as if it had been called on the command
1165 1177 # line, so it ends up saved in the log header Save it in case we need
1166 1178 # to restore it...
1167 1179 old_logfile = self.shell.logfile
1168 1180 if logfname:
1169 1181 logfname = os.path.expanduser(logfname)
1170 1182 self.shell.logfile = logfname
1171 1183
1172 1184 loghead = '# IPython log file\n\n'
1173 1185 try:
1174 1186 started = logger.logstart(logfname,loghead,logmode,
1175 1187 log_output,timestamp,log_raw_input)
1176 1188 except:
1177 1189 self.shell.logfile = old_logfile
1178 1190 warn("Couldn't start log: %s" % sys.exc_info()[1])
1179 1191 else:
1180 1192 # log input history up to this point, optionally interleaving
1181 1193 # output if requested
1182 1194
1183 1195 if timestamp:
1184 1196 # disable timestamping for the previous history, since we've
1185 1197 # lost those already (no time machine here).
1186 1198 logger.timestamp = False
1187 1199
1188 1200 if log_raw_input:
1189 1201 input_hist = self.shell.history_manager.input_hist_raw
1190 1202 else:
1191 1203 input_hist = self.shell.history_manager.input_hist_parsed
1192 1204
1193 1205 if log_output:
1194 1206 log_write = logger.log_write
1195 1207 output_hist = self.shell.history_manager.output_hist
1196 1208 for n in range(1,len(input_hist)-1):
1197 1209 log_write(input_hist[n].rstrip() + '\n')
1198 1210 if n in output_hist:
1199 1211 log_write(repr(output_hist[n]),'output')
1200 1212 else:
1201 1213 logger.log_write('\n'.join(input_hist[1:]))
1202 1214 logger.log_write('\n')
1203 1215 if timestamp:
1204 1216 # re-enable timestamping
1205 1217 logger.timestamp = True
1206 1218
1207 1219 print ('Activating auto-logging. '
1208 1220 'Current session state plus future input saved.')
1209 1221 logger.logstate()
1210 1222
1211 1223 def magic_logstop(self,parameter_s=''):
1212 1224 """Fully stop logging and close log file.
1213 1225
1214 1226 In order to start logging again, a new %logstart call needs to be made,
1215 1227 possibly (though not necessarily) with a new filename, mode and other
1216 1228 options."""
1217 1229 self.logger.logstop()
1218 1230
1219 1231 def magic_logoff(self,parameter_s=''):
1220 1232 """Temporarily stop logging.
1221 1233
1222 1234 You must have previously started logging."""
1223 1235 self.shell.logger.switch_log(0)
1224 1236
1225 1237 def magic_logon(self,parameter_s=''):
1226 1238 """Restart logging.
1227 1239
1228 1240 This function is for restarting logging which you've temporarily
1229 1241 stopped with %logoff. For starting logging for the first time, you
1230 1242 must use the %logstart function, which allows you to specify an
1231 1243 optional log filename."""
1232 1244
1233 1245 self.shell.logger.switch_log(1)
1234 1246
1235 1247 def magic_logstate(self,parameter_s=''):
1236 1248 """Print the status of the logging system."""
1237 1249
1238 1250 self.shell.logger.logstate()
1239 1251
1240 1252 def magic_pdb(self, parameter_s=''):
1241 1253 """Control the automatic calling of the pdb interactive debugger.
1242 1254
1243 1255 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1244 1256 argument it works as a toggle.
1245 1257
1246 1258 When an exception is triggered, IPython can optionally call the
1247 1259 interactive pdb debugger after the traceback printout. %pdb toggles
1248 1260 this feature on and off.
1249 1261
1250 1262 The initial state of this feature is set in your configuration
1251 1263 file (the option is ``InteractiveShell.pdb``).
1252 1264
1253 1265 If you want to just activate the debugger AFTER an exception has fired,
1254 1266 without having to type '%pdb on' and rerunning your code, you can use
1255 1267 the %debug magic."""
1256 1268
1257 1269 par = parameter_s.strip().lower()
1258 1270
1259 1271 if par:
1260 1272 try:
1261 1273 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1262 1274 except KeyError:
1263 1275 print ('Incorrect argument. Use on/1, off/0, '
1264 1276 'or nothing for a toggle.')
1265 1277 return
1266 1278 else:
1267 1279 # toggle
1268 1280 new_pdb = not self.shell.call_pdb
1269 1281
1270 1282 # set on the shell
1271 1283 self.shell.call_pdb = new_pdb
1272 1284 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1273 1285
1274 1286 def magic_debug(self, parameter_s=''):
1275 1287 """Activate the interactive debugger in post-mortem mode.
1276 1288
1277 1289 If an exception has just occurred, this lets you inspect its stack
1278 1290 frames interactively. Note that this will always work only on the last
1279 1291 traceback that occurred, so you must call this quickly after an
1280 1292 exception that you wish to inspect has fired, because if another one
1281 1293 occurs, it clobbers the previous one.
1282 1294
1283 1295 If you want IPython to automatically do this on every exception, see
1284 1296 the %pdb magic for more details.
1285 1297 """
1286 1298 self.shell.debugger(force=True)
1287 1299
1288 1300 @skip_doctest
1289 1301 def magic_prun(self, parameter_s ='',user_mode=1,
1290 1302 opts=None,arg_lst=None,prog_ns=None):
1291 1303
1292 1304 """Run a statement through the python code profiler.
1293 1305
1294 1306 Usage:
1295 1307 %prun [options] statement
1296 1308
1297 1309 The given statement (which doesn't require quote marks) is run via the
1298 1310 python profiler in a manner similar to the profile.run() function.
1299 1311 Namespaces are internally managed to work correctly; profile.run
1300 1312 cannot be used in IPython because it makes certain assumptions about
1301 1313 namespaces which do not hold under IPython.
1302 1314
1303 1315 Options:
1304 1316
1305 1317 -l <limit>: you can place restrictions on what or how much of the
1306 1318 profile gets printed. The limit value can be:
1307 1319
1308 1320 * A string: only information for function names containing this string
1309 1321 is printed.
1310 1322
1311 1323 * An integer: only these many lines are printed.
1312 1324
1313 1325 * A float (between 0 and 1): this fraction of the report is printed
1314 1326 (for example, use a limit of 0.4 to see the topmost 40% only).
1315 1327
1316 1328 You can combine several limits with repeated use of the option. For
1317 1329 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1318 1330 information about class constructors.
1319 1331
1320 1332 -r: return the pstats.Stats object generated by the profiling. This
1321 1333 object has all the information about the profile in it, and you can
1322 1334 later use it for further analysis or in other functions.
1323 1335
1324 1336 -s <key>: sort profile by given key. You can provide more than one key
1325 1337 by using the option several times: '-s key1 -s key2 -s key3...'. The
1326 1338 default sorting key is 'time'.
1327 1339
1328 1340 The following is copied verbatim from the profile documentation
1329 1341 referenced below:
1330 1342
1331 1343 When more than one key is provided, additional keys are used as
1332 1344 secondary criteria when the there is equality in all keys selected
1333 1345 before them.
1334 1346
1335 1347 Abbreviations can be used for any key names, as long as the
1336 1348 abbreviation is unambiguous. The following are the keys currently
1337 1349 defined:
1338 1350
1339 1351 Valid Arg Meaning
1340 1352 "calls" call count
1341 1353 "cumulative" cumulative time
1342 1354 "file" file name
1343 1355 "module" file name
1344 1356 "pcalls" primitive call count
1345 1357 "line" line number
1346 1358 "name" function name
1347 1359 "nfl" name/file/line
1348 1360 "stdname" standard name
1349 1361 "time" internal time
1350 1362
1351 1363 Note that all sorts on statistics are in descending order (placing
1352 1364 most time consuming items first), where as name, file, and line number
1353 1365 searches are in ascending order (i.e., alphabetical). The subtle
1354 1366 distinction between "nfl" and "stdname" is that the standard name is a
1355 1367 sort of the name as printed, which means that the embedded line
1356 1368 numbers get compared in an odd way. For example, lines 3, 20, and 40
1357 1369 would (if the file names were the same) appear in the string order
1358 1370 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1359 1371 line numbers. In fact, sort_stats("nfl") is the same as
1360 1372 sort_stats("name", "file", "line").
1361 1373
1362 1374 -T <filename>: save profile results as shown on screen to a text
1363 1375 file. The profile is still shown on screen.
1364 1376
1365 1377 -D <filename>: save (via dump_stats) profile statistics to given
1366 1378 filename. This data is in a format understood by the pstats module, and
1367 1379 is generated by a call to the dump_stats() method of profile
1368 1380 objects. The profile is still shown on screen.
1369 1381
1370 1382 -q: suppress output to the pager. Best used with -T and/or -D above.
1371 1383
1372 1384 If you want to run complete programs under the profiler's control, use
1373 1385 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1374 1386 contains profiler specific options as described here.
1375 1387
1376 1388 You can read the complete documentation for the profile module with::
1377 1389
1378 1390 In [1]: import profile; profile.help()
1379 1391 """
1380 1392
1381 1393 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1382 1394 # protect user quote marks
1383 1395 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1384 1396
1385 1397 if user_mode: # regular user call
1386 1398 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
1387 1399 list_all=1)
1388 1400 namespace = self.shell.user_ns
1389 1401 else: # called to run a program by %run -p
1390 1402 try:
1391 1403 filename = get_py_filename(arg_lst[0])
1392 1404 except IOError as e:
1393 1405 try:
1394 1406 msg = str(e)
1395 1407 except UnicodeError:
1396 1408 msg = e.message
1397 1409 error(msg)
1398 1410 return
1399 1411
1400 1412 arg_str = 'execfile(filename,prog_ns)'
1401 1413 namespace = {
1402 1414 'execfile': self.shell.safe_execfile,
1403 1415 'prog_ns': prog_ns,
1404 1416 'filename': filename
1405 1417 }
1406 1418
1407 1419 opts.merge(opts_def)
1408 1420
1409 1421 prof = profile.Profile()
1410 1422 try:
1411 1423 prof = prof.runctx(arg_str,namespace,namespace)
1412 1424 sys_exit = ''
1413 1425 except SystemExit:
1414 1426 sys_exit = """*** SystemExit exception caught in code being profiled."""
1415 1427
1416 1428 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1417 1429
1418 1430 lims = opts.l
1419 1431 if lims:
1420 1432 lims = [] # rebuild lims with ints/floats/strings
1421 1433 for lim in opts.l:
1422 1434 try:
1423 1435 lims.append(int(lim))
1424 1436 except ValueError:
1425 1437 try:
1426 1438 lims.append(float(lim))
1427 1439 except ValueError:
1428 1440 lims.append(lim)
1429 1441
1430 1442 # Trap output.
1431 1443 stdout_trap = StringIO()
1432 1444
1433 1445 if hasattr(stats,'stream'):
1434 1446 # In newer versions of python, the stats object has a 'stream'
1435 1447 # attribute to write into.
1436 1448 stats.stream = stdout_trap
1437 1449 stats.print_stats(*lims)
1438 1450 else:
1439 1451 # For older versions, we manually redirect stdout during printing
1440 1452 sys_stdout = sys.stdout
1441 1453 try:
1442 1454 sys.stdout = stdout_trap
1443 1455 stats.print_stats(*lims)
1444 1456 finally:
1445 1457 sys.stdout = sys_stdout
1446 1458
1447 1459 output = stdout_trap.getvalue()
1448 1460 output = output.rstrip()
1449 1461
1450 1462 if 'q' not in opts:
1451 1463 page.page(output)
1452 1464 print sys_exit,
1453 1465
1454 1466 dump_file = opts.D[0]
1455 1467 text_file = opts.T[0]
1456 1468 if dump_file:
1457 1469 dump_file = unquote_filename(dump_file)
1458 1470 prof.dump_stats(dump_file)
1459 1471 print '\n*** Profile stats marshalled to file',\
1460 1472 `dump_file`+'.',sys_exit
1461 1473 if text_file:
1462 1474 text_file = unquote_filename(text_file)
1463 1475 pfile = file(text_file,'w')
1464 1476 pfile.write(output)
1465 1477 pfile.close()
1466 1478 print '\n*** Profile printout saved to text file',\
1467 1479 `text_file`+'.',sys_exit
1468 1480
1469 1481 if opts.has_key('r'):
1470 1482 return stats
1471 1483 else:
1472 1484 return None
1473 1485
1474 1486 @skip_doctest
1475 1487 def magic_run(self, parameter_s ='', runner=None,
1476 1488 file_finder=get_py_filename):
1477 1489 """Run the named file inside IPython as a program.
1478 1490
1479 1491 Usage:\\
1480 1492 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1481 1493
1482 1494 Parameters after the filename are passed as command-line arguments to
1483 1495 the program (put in sys.argv). Then, control returns to IPython's
1484 1496 prompt.
1485 1497
1486 1498 This is similar to running at a system prompt:\\
1487 1499 $ python file args\\
1488 1500 but with the advantage of giving you IPython's tracebacks, and of
1489 1501 loading all variables into your interactive namespace for further use
1490 1502 (unless -p is used, see below).
1491 1503
1492 1504 The file is executed in a namespace initially consisting only of
1493 1505 __name__=='__main__' and sys.argv constructed as indicated. It thus
1494 1506 sees its environment as if it were being run as a stand-alone program
1495 1507 (except for sharing global objects such as previously imported
1496 1508 modules). But after execution, the IPython interactive namespace gets
1497 1509 updated with all variables defined in the program (except for __name__
1498 1510 and sys.argv). This allows for very convenient loading of code for
1499 1511 interactive work, while giving each program a 'clean sheet' to run in.
1500 1512
1501 1513 Options:
1502 1514
1503 1515 -n: __name__ is NOT set to '__main__', but to the running file's name
1504 1516 without extension (as python does under import). This allows running
1505 1517 scripts and reloading the definitions in them without calling code
1506 1518 protected by an ' if __name__ == "__main__" ' clause.
1507 1519
1508 1520 -i: run the file in IPython's namespace instead of an empty one. This
1509 1521 is useful if you are experimenting with code written in a text editor
1510 1522 which depends on variables defined interactively.
1511 1523
1512 1524 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1513 1525 being run. This is particularly useful if IPython is being used to
1514 1526 run unittests, which always exit with a sys.exit() call. In such
1515 1527 cases you are interested in the output of the test results, not in
1516 1528 seeing a traceback of the unittest module.
1517 1529
1518 1530 -t: print timing information at the end of the run. IPython will give
1519 1531 you an estimated CPU time consumption for your script, which under
1520 1532 Unix uses the resource module to avoid the wraparound problems of
1521 1533 time.clock(). Under Unix, an estimate of time spent on system tasks
1522 1534 is also given (for Windows platforms this is reported as 0.0).
1523 1535
1524 1536 If -t is given, an additional -N<N> option can be given, where <N>
1525 1537 must be an integer indicating how many times you want the script to
1526 1538 run. The final timing report will include total and per run results.
1527 1539
1528 1540 For example (testing the script uniq_stable.py):
1529 1541
1530 1542 In [1]: run -t uniq_stable
1531 1543
1532 1544 IPython CPU timings (estimated):\\
1533 1545 User : 0.19597 s.\\
1534 1546 System: 0.0 s.\\
1535 1547
1536 1548 In [2]: run -t -N5 uniq_stable
1537 1549
1538 1550 IPython CPU timings (estimated):\\
1539 1551 Total runs performed: 5\\
1540 1552 Times : Total Per run\\
1541 1553 User : 0.910862 s, 0.1821724 s.\\
1542 1554 System: 0.0 s, 0.0 s.
1543 1555
1544 1556 -d: run your program under the control of pdb, the Python debugger.
1545 1557 This allows you to execute your program step by step, watch variables,
1546 1558 etc. Internally, what IPython does is similar to calling:
1547 1559
1548 1560 pdb.run('execfile("YOURFILENAME")')
1549 1561
1550 1562 with a breakpoint set on line 1 of your file. You can change the line
1551 1563 number for this automatic breakpoint to be <N> by using the -bN option
1552 1564 (where N must be an integer). For example:
1553 1565
1554 1566 %run -d -b40 myscript
1555 1567
1556 1568 will set the first breakpoint at line 40 in myscript.py. Note that
1557 1569 the first breakpoint must be set on a line which actually does
1558 1570 something (not a comment or docstring) for it to stop execution.
1559 1571
1560 1572 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1561 1573 first enter 'c' (without quotes) to start execution up to the first
1562 1574 breakpoint.
1563 1575
1564 1576 Entering 'help' gives information about the use of the debugger. You
1565 1577 can easily see pdb's full documentation with "import pdb;pdb.help()"
1566 1578 at a prompt.
1567 1579
1568 1580 -p: run program under the control of the Python profiler module (which
1569 1581 prints a detailed report of execution times, function calls, etc).
1570 1582
1571 1583 You can pass other options after -p which affect the behavior of the
1572 1584 profiler itself. See the docs for %prun for details.
1573 1585
1574 1586 In this mode, the program's variables do NOT propagate back to the
1575 1587 IPython interactive namespace (because they remain in the namespace
1576 1588 where the profiler executes them).
1577 1589
1578 1590 Internally this triggers a call to %prun, see its documentation for
1579 1591 details on the options available specifically for profiling.
1580 1592
1581 1593 There is one special usage for which the text above doesn't apply:
1582 1594 if the filename ends with .ipy, the file is run as ipython script,
1583 1595 just as if the commands were written on IPython prompt.
1584 1596
1585 1597 -m: specify module name to load instead of script path. Similar to
1586 1598 the -m option for the python interpreter. Use this option last if you
1587 1599 want to combine with other %run options. Unlike the python interpreter
1588 1600 only source modules are allowed no .pyc or .pyo files.
1589 1601 For example:
1590 1602
1591 1603 %run -m example
1592 1604
1593 1605 will run the example module.
1594 1606
1595 1607 """
1596 1608
1597 1609 # get arguments and set sys.argv for program to be run.
1598 1610 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
1599 1611 mode='list', list_all=1)
1600 1612 if "m" in opts:
1601 1613 modulename = opts["m"][0]
1602 1614 modpath = find_mod(modulename)
1603 1615 if modpath is None:
1604 1616 warn('%r is not a valid modulename on sys.path'%modulename)
1605 1617 return
1606 1618 arg_lst = [modpath] + arg_lst
1607 1619 try:
1608 1620 filename = file_finder(arg_lst[0])
1609 1621 except IndexError:
1610 1622 warn('you must provide at least a filename.')
1611 1623 print '\n%run:\n', oinspect.getdoc(self.magic_run)
1612 1624 return
1613 1625 except IOError as e:
1614 1626 try:
1615 1627 msg = str(e)
1616 1628 except UnicodeError:
1617 1629 msg = e.message
1618 1630 error(msg)
1619 1631 return
1620 1632
1621 1633 if filename.lower().endswith('.ipy'):
1622 1634 self.shell.safe_execfile_ipy(filename)
1623 1635 return
1624 1636
1625 1637 # Control the response to exit() calls made by the script being run
1626 1638 exit_ignore = 'e' in opts
1627 1639
1628 1640 # Make sure that the running script gets a proper sys.argv as if it
1629 1641 # were run from a system shell.
1630 1642 save_argv = sys.argv # save it for later restoring
1631 1643
1632 1644 # simulate shell expansion on arguments, at least tilde expansion
1633 1645 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
1634 1646
1635 1647 sys.argv = [filename] + args # put in the proper filename
1636 1648 # protect sys.argv from potential unicode strings on Python 2:
1637 1649 if not py3compat.PY3:
1638 1650 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
1639 1651
1640 1652 if 'i' in opts:
1641 1653 # Run in user's interactive namespace
1642 1654 prog_ns = self.shell.user_ns
1643 1655 __name__save = self.shell.user_ns['__name__']
1644 1656 prog_ns['__name__'] = '__main__'
1645 1657 main_mod = self.shell.new_main_mod(prog_ns)
1646 1658 else:
1647 1659 # Run in a fresh, empty namespace
1648 1660 if 'n' in opts:
1649 1661 name = os.path.splitext(os.path.basename(filename))[0]
1650 1662 else:
1651 1663 name = '__main__'
1652 1664
1653 1665 main_mod = self.shell.new_main_mod()
1654 1666 prog_ns = main_mod.__dict__
1655 1667 prog_ns['__name__'] = name
1656 1668
1657 1669 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1658 1670 # set the __file__ global in the script's namespace
1659 1671 prog_ns['__file__'] = filename
1660 1672
1661 1673 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1662 1674 # that, if we overwrite __main__, we replace it at the end
1663 1675 main_mod_name = prog_ns['__name__']
1664 1676
1665 1677 if main_mod_name == '__main__':
1666 1678 restore_main = sys.modules['__main__']
1667 1679 else:
1668 1680 restore_main = False
1669 1681
1670 1682 # This needs to be undone at the end to prevent holding references to
1671 1683 # every single object ever created.
1672 1684 sys.modules[main_mod_name] = main_mod
1673 1685
1674 1686 try:
1675 1687 stats = None
1676 1688 with self.readline_no_record:
1677 1689 if 'p' in opts:
1678 1690 stats = self.magic_prun('', 0, opts, arg_lst, prog_ns)
1679 1691 else:
1680 1692 if 'd' in opts:
1681 1693 deb = debugger.Pdb(self.shell.colors)
1682 1694 # reset Breakpoint state, which is moronically kept
1683 1695 # in a class
1684 1696 bdb.Breakpoint.next = 1
1685 1697 bdb.Breakpoint.bplist = {}
1686 1698 bdb.Breakpoint.bpbynumber = [None]
1687 1699 # Set an initial breakpoint to stop execution
1688 1700 maxtries = 10
1689 1701 bp = int(opts.get('b', [1])[0])
1690 1702 checkline = deb.checkline(filename, bp)
1691 1703 if not checkline:
1692 1704 for bp in range(bp + 1, bp + maxtries + 1):
1693 1705 if deb.checkline(filename, bp):
1694 1706 break
1695 1707 else:
1696 1708 msg = ("\nI failed to find a valid line to set "
1697 1709 "a breakpoint\n"
1698 1710 "after trying up to line: %s.\n"
1699 1711 "Please set a valid breakpoint manually "
1700 1712 "with the -b option." % bp)
1701 1713 error(msg)
1702 1714 return
1703 1715 # if we find a good linenumber, set the breakpoint
1704 1716 deb.do_break('%s:%s' % (filename, bp))
1705 1717 # Start file run
1706 1718 print "NOTE: Enter 'c' at the",
1707 1719 print "%s prompt to start your script." % deb.prompt
1708 1720 try:
1709 1721 deb.run('execfile("%s")' % filename, prog_ns)
1710 1722
1711 1723 except:
1712 1724 etype, value, tb = sys.exc_info()
1713 1725 # Skip three frames in the traceback: the %run one,
1714 1726 # one inside bdb.py, and the command-line typed by the
1715 1727 # user (run by exec in pdb itself).
1716 1728 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
1717 1729 else:
1718 1730 if runner is None:
1719 1731 runner = self.shell.safe_execfile
1720 1732 if 't' in opts:
1721 1733 # timed execution
1722 1734 try:
1723 1735 nruns = int(opts['N'][0])
1724 1736 if nruns < 1:
1725 1737 error('Number of runs must be >=1')
1726 1738 return
1727 1739 except (KeyError):
1728 1740 nruns = 1
1729 1741 twall0 = time.time()
1730 1742 if nruns == 1:
1731 1743 t0 = clock2()
1732 1744 runner(filename, prog_ns, prog_ns,
1733 1745 exit_ignore=exit_ignore)
1734 1746 t1 = clock2()
1735 1747 t_usr = t1[0] - t0[0]
1736 1748 t_sys = t1[1] - t0[1]
1737 1749 print "\nIPython CPU timings (estimated):"
1738 1750 print " User : %10.2f s." % t_usr
1739 1751 print " System : %10.2f s." % t_sys
1740 1752 else:
1741 1753 runs = range(nruns)
1742 1754 t0 = clock2()
1743 1755 for nr in runs:
1744 1756 runner(filename, prog_ns, prog_ns,
1745 1757 exit_ignore=exit_ignore)
1746 1758 t1 = clock2()
1747 1759 t_usr = t1[0] - t0[0]
1748 1760 t_sys = t1[1] - t0[1]
1749 1761 print "\nIPython CPU timings (estimated):"
1750 1762 print "Total runs performed:", nruns
1751 1763 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
1752 1764 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
1753 1765 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
1754 1766 twall1 = time.time()
1755 1767 print "Wall time: %10.2f s." % (twall1 - twall0)
1756 1768
1757 1769 else:
1758 1770 # regular execution
1759 1771 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
1760 1772
1761 1773 if 'i' in opts:
1762 1774 self.shell.user_ns['__name__'] = __name__save
1763 1775 else:
1764 1776 # The shell MUST hold a reference to prog_ns so after %run
1765 1777 # exits, the python deletion mechanism doesn't zero it out
1766 1778 # (leaving dangling references).
1767 1779 self.shell.cache_main_mod(prog_ns, filename)
1768 1780 # update IPython interactive namespace
1769 1781
1770 1782 # Some forms of read errors on the file may mean the
1771 1783 # __name__ key was never set; using pop we don't have to
1772 1784 # worry about a possible KeyError.
1773 1785 prog_ns.pop('__name__', None)
1774 1786
1775 1787 self.shell.user_ns.update(prog_ns)
1776 1788 finally:
1777 1789 # It's a bit of a mystery why, but __builtins__ can change from
1778 1790 # being a module to becoming a dict missing some key data after
1779 1791 # %run. As best I can see, this is NOT something IPython is doing
1780 1792 # at all, and similar problems have been reported before:
1781 1793 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1782 1794 # Since this seems to be done by the interpreter itself, the best
1783 1795 # we can do is to at least restore __builtins__ for the user on
1784 1796 # exit.
1785 1797 self.shell.user_ns['__builtins__'] = builtin_mod
1786 1798
1787 1799 # Ensure key global structures are restored
1788 1800 sys.argv = save_argv
1789 1801 if restore_main:
1790 1802 sys.modules['__main__'] = restore_main
1791 1803 else:
1792 1804 # Remove from sys.modules the reference to main_mod we'd
1793 1805 # added. Otherwise it will trap references to objects
1794 1806 # contained therein.
1795 1807 del sys.modules[main_mod_name]
1796 1808
1797 1809 return stats
1798 1810
1799 1811 @skip_doctest
1800 1812 def magic_timeit(self, parameter_s =''):
1801 1813 """Time execution of a Python statement or expression
1802 1814
1803 1815 Usage:\\
1804 1816 %timeit [-n<N> -r<R> [-t|-c]] statement
1805 1817
1806 1818 Time execution of a Python statement or expression using the timeit
1807 1819 module.
1808 1820
1809 1821 Options:
1810 1822 -n<N>: execute the given statement <N> times in a loop. If this value
1811 1823 is not given, a fitting value is chosen.
1812 1824
1813 1825 -r<R>: repeat the loop iteration <R> times and take the best result.
1814 1826 Default: 3
1815 1827
1816 1828 -t: use time.time to measure the time, which is the default on Unix.
1817 1829 This function measures wall time.
1818 1830
1819 1831 -c: use time.clock to measure the time, which is the default on
1820 1832 Windows and measures wall time. On Unix, resource.getrusage is used
1821 1833 instead and returns the CPU user time.
1822 1834
1823 1835 -p<P>: use a precision of <P> digits to display the timing result.
1824 1836 Default: 3
1825 1837
1826 1838
1827 1839 Examples:
1828 1840
1829 1841 In [1]: %timeit pass
1830 1842 10000000 loops, best of 3: 53.3 ns per loop
1831 1843
1832 1844 In [2]: u = None
1833 1845
1834 1846 In [3]: %timeit u is None
1835 1847 10000000 loops, best of 3: 184 ns per loop
1836 1848
1837 1849 In [4]: %timeit -r 4 u == None
1838 1850 1000000 loops, best of 4: 242 ns per loop
1839 1851
1840 1852 In [5]: import time
1841 1853
1842 1854 In [6]: %timeit -n1 time.sleep(2)
1843 1855 1 loops, best of 3: 2 s per loop
1844 1856
1845 1857
1846 1858 The times reported by %timeit will be slightly higher than those
1847 1859 reported by the timeit.py script when variables are accessed. This is
1848 1860 due to the fact that %timeit executes the statement in the namespace
1849 1861 of the shell, compared with timeit.py, which uses a single setup
1850 1862 statement to import function or create variables. Generally, the bias
1851 1863 does not matter as long as results from timeit.py are not mixed with
1852 1864 those from %timeit."""
1853 1865
1854 1866 import timeit
1855 1867 import math
1856 1868
1857 1869 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1858 1870 # certain terminals. Until we figure out a robust way of
1859 1871 # auto-detecting if the terminal can deal with it, use plain 'us' for
1860 1872 # microseconds. I am really NOT happy about disabling the proper
1861 1873 # 'micro' prefix, but crashing is worse... If anyone knows what the
1862 1874 # right solution for this is, I'm all ears...
1863 1875 #
1864 1876 # Note: using
1865 1877 #
1866 1878 # s = u'\xb5'
1867 1879 # s.encode(sys.getdefaultencoding())
1868 1880 #
1869 1881 # is not sufficient, as I've seen terminals where that fails but
1870 1882 # print s
1871 1883 #
1872 1884 # succeeds
1873 1885 #
1874 1886 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1875 1887
1876 1888 #units = [u"s", u"ms",u'\xb5',"ns"]
1877 1889 units = [u"s", u"ms",u'us',"ns"]
1878 1890
1879 1891 scaling = [1, 1e3, 1e6, 1e9]
1880 1892
1881 1893 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1882 1894 posix=False, strict=False)
1883 1895 if stmt == "":
1884 1896 return
1885 1897 timefunc = timeit.default_timer
1886 1898 number = int(getattr(opts, "n", 0))
1887 1899 repeat = int(getattr(opts, "r", timeit.default_repeat))
1888 1900 precision = int(getattr(opts, "p", 3))
1889 1901 if hasattr(opts, "t"):
1890 1902 timefunc = time.time
1891 1903 if hasattr(opts, "c"):
1892 1904 timefunc = clock
1893 1905
1894 1906 timer = timeit.Timer(timer=timefunc)
1895 1907 # this code has tight coupling to the inner workings of timeit.Timer,
1896 1908 # but is there a better way to achieve that the code stmt has access
1897 1909 # to the shell namespace?
1898 1910
1899 1911 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1900 1912 'setup': "pass"}
1901 1913 # Track compilation time so it can be reported if too long
1902 1914 # Minimum time above which compilation time will be reported
1903 1915 tc_min = 0.1
1904 1916
1905 1917 t0 = clock()
1906 1918 code = compile(src, "<magic-timeit>", "exec")
1907 1919 tc = clock()-t0
1908 1920
1909 1921 ns = {}
1910 1922 exec code in self.shell.user_ns, ns
1911 1923 timer.inner = ns["inner"]
1912 1924
1913 1925 if number == 0:
1914 1926 # determine number so that 0.2 <= total time < 2.0
1915 1927 number = 1
1916 1928 for i in range(1, 10):
1917 1929 if timer.timeit(number) >= 0.2:
1918 1930 break
1919 1931 number *= 10
1920 1932
1921 1933 best = min(timer.repeat(repeat, number)) / number
1922 1934
1923 1935 if best > 0.0 and best < 1000.0:
1924 1936 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1925 1937 elif best >= 1000.0:
1926 1938 order = 0
1927 1939 else:
1928 1940 order = 3
1929 1941 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1930 1942 precision,
1931 1943 best * scaling[order],
1932 1944 units[order])
1933 1945 if tc > tc_min:
1934 1946 print "Compiler time: %.2f s" % tc
1935 1947
1936 1948 @skip_doctest
1937 1949 @needs_local_scope
1938 1950 def magic_time(self,parameter_s = ''):
1939 1951 """Time execution of a Python statement or expression.
1940 1952
1941 1953 The CPU and wall clock times are printed, and the value of the
1942 1954 expression (if any) is returned. Note that under Win32, system time
1943 1955 is always reported as 0, since it can not be measured.
1944 1956
1945 1957 This function provides very basic timing functionality. In Python
1946 1958 2.3, the timeit module offers more control and sophistication, so this
1947 1959 could be rewritten to use it (patches welcome).
1948 1960
1949 1961 Some examples:
1950 1962
1951 1963 In [1]: time 2**128
1952 1964 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1953 1965 Wall time: 0.00
1954 1966 Out[1]: 340282366920938463463374607431768211456L
1955 1967
1956 1968 In [2]: n = 1000000
1957 1969
1958 1970 In [3]: time sum(range(n))
1959 1971 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1960 1972 Wall time: 1.37
1961 1973 Out[3]: 499999500000L
1962 1974
1963 1975 In [4]: time print 'hello world'
1964 1976 hello world
1965 1977 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1966 1978 Wall time: 0.00
1967 1979
1968 1980 Note that the time needed by Python to compile the given expression
1969 1981 will be reported if it is more than 0.1s. In this example, the
1970 1982 actual exponentiation is done by Python at compilation time, so while
1971 1983 the expression can take a noticeable amount of time to compute, that
1972 1984 time is purely due to the compilation:
1973 1985
1974 1986 In [5]: time 3**9999;
1975 1987 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1976 1988 Wall time: 0.00 s
1977 1989
1978 1990 In [6]: time 3**999999;
1979 1991 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1980 1992 Wall time: 0.00 s
1981 1993 Compiler : 0.78 s
1982 1994 """
1983 1995
1984 1996 # fail immediately if the given expression can't be compiled
1985 1997
1986 1998 expr = self.shell.prefilter(parameter_s,False)
1987 1999
1988 2000 # Minimum time above which compilation time will be reported
1989 2001 tc_min = 0.1
1990 2002
1991 2003 try:
1992 2004 mode = 'eval'
1993 2005 t0 = clock()
1994 2006 code = compile(expr,'<timed eval>',mode)
1995 2007 tc = clock()-t0
1996 2008 except SyntaxError:
1997 2009 mode = 'exec'
1998 2010 t0 = clock()
1999 2011 code = compile(expr,'<timed exec>',mode)
2000 2012 tc = clock()-t0
2001 2013 # skew measurement as little as possible
2002 2014 glob = self.shell.user_ns
2003 2015 locs = self._magic_locals
2004 2016 clk = clock2
2005 2017 wtime = time.time
2006 2018 # time execution
2007 2019 wall_st = wtime()
2008 2020 if mode=='eval':
2009 2021 st = clk()
2010 2022 out = eval(code, glob, locs)
2011 2023 end = clk()
2012 2024 else:
2013 2025 st = clk()
2014 2026 exec code in glob, locs
2015 2027 end = clk()
2016 2028 out = None
2017 2029 wall_end = wtime()
2018 2030 # Compute actual times and report
2019 2031 wall_time = wall_end-wall_st
2020 2032 cpu_user = end[0]-st[0]
2021 2033 cpu_sys = end[1]-st[1]
2022 2034 cpu_tot = cpu_user+cpu_sys
2023 2035 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2024 2036 (cpu_user,cpu_sys,cpu_tot)
2025 2037 print "Wall time: %.2f s" % wall_time
2026 2038 if tc > tc_min:
2027 2039 print "Compiler : %.2f s" % tc
2028 2040 return out
2029 2041
2030 2042 @skip_doctest
2031 2043 def magic_macro(self,parameter_s = ''):
2032 2044 """Define a macro for future re-execution. It accepts ranges of history,
2033 2045 filenames or string objects.
2034 2046
2035 2047 Usage:\\
2036 2048 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2037 2049
2038 2050 Options:
2039 2051
2040 2052 -r: use 'raw' input. By default, the 'processed' history is used,
2041 2053 so that magics are loaded in their transformed version to valid
2042 2054 Python. If this option is given, the raw input as typed as the
2043 2055 command line is used instead.
2044 2056
2045 2057 This will define a global variable called `name` which is a string
2046 2058 made of joining the slices and lines you specify (n1,n2,... numbers
2047 2059 above) from your input history into a single string. This variable
2048 2060 acts like an automatic function which re-executes those lines as if
2049 2061 you had typed them. You just type 'name' at the prompt and the code
2050 2062 executes.
2051 2063
2052 2064 The syntax for indicating input ranges is described in %history.
2053 2065
2054 2066 Note: as a 'hidden' feature, you can also use traditional python slice
2055 2067 notation, where N:M means numbers N through M-1.
2056 2068
2057 2069 For example, if your history contains (%hist prints it):
2058 2070
2059 2071 44: x=1
2060 2072 45: y=3
2061 2073 46: z=x+y
2062 2074 47: print x
2063 2075 48: a=5
2064 2076 49: print 'x',x,'y',y
2065 2077
2066 2078 you can create a macro with lines 44 through 47 (included) and line 49
2067 2079 called my_macro with:
2068 2080
2069 2081 In [55]: %macro my_macro 44-47 49
2070 2082
2071 2083 Now, typing `my_macro` (without quotes) will re-execute all this code
2072 2084 in one pass.
2073 2085
2074 2086 You don't need to give the line-numbers in order, and any given line
2075 2087 number can appear multiple times. You can assemble macros with any
2076 2088 lines from your input history in any order.
2077 2089
2078 2090 The macro is a simple object which holds its value in an attribute,
2079 2091 but IPython's display system checks for macros and executes them as
2080 2092 code instead of printing them when you type their name.
2081 2093
2082 2094 You can view a macro's contents by explicitly printing it with:
2083 2095
2084 2096 'print macro_name'.
2085 2097
2086 2098 """
2087 2099 opts,args = self.parse_options(parameter_s,'r',mode='list')
2088 2100 if not args: # List existing macros
2089 2101 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2090 2102 isinstance(v, Macro))
2091 2103 if len(args) == 1:
2092 2104 raise UsageError(
2093 2105 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2094 2106 name, codefrom = args[0], " ".join(args[1:])
2095 2107
2096 2108 #print 'rng',ranges # dbg
2097 2109 try:
2098 2110 lines = self.shell.find_user_code(codefrom, 'r' in opts)
2099 2111 except (ValueError, TypeError) as e:
2100 2112 print e.args[0]
2101 2113 return
2102 2114 macro = Macro(lines)
2103 2115 self.shell.define_macro(name, macro)
2104 2116 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2105 2117 print '=== Macro contents: ==='
2106 2118 print macro,
2107 2119
2108 2120 def magic_save(self,parameter_s = ''):
2109 2121 """Save a set of lines or a macro to a given filename.
2110 2122
2111 2123 Usage:\\
2112 2124 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2113 2125
2114 2126 Options:
2115 2127
2116 2128 -r: use 'raw' input. By default, the 'processed' history is used,
2117 2129 so that magics are loaded in their transformed version to valid
2118 2130 Python. If this option is given, the raw input as typed as the
2119 2131 command line is used instead.
2120 2132
2121 2133 This function uses the same syntax as %history for input ranges,
2122 2134 then saves the lines to the filename you specify.
2123 2135
2124 2136 It adds a '.py' extension to the file if you don't do so yourself, and
2125 2137 it asks for confirmation before overwriting existing files."""
2126 2138
2127 2139 opts,args = self.parse_options(parameter_s,'r',mode='list')
2128 2140 fname, codefrom = unquote_filename(args[0]), " ".join(args[1:])
2129 2141 if not fname.endswith('.py'):
2130 2142 fname += '.py'
2131 2143 if os.path.isfile(fname):
2132 2144 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2133 2145 if ans.lower() not in ['y','yes']:
2134 2146 print 'Operation cancelled.'
2135 2147 return
2136 2148 try:
2137 2149 cmds = self.shell.find_user_code(codefrom, 'r' in opts)
2138 2150 except (TypeError, ValueError) as e:
2139 2151 print e.args[0]
2140 2152 return
2141 2153 with py3compat.open(fname,'w', encoding="utf-8") as f:
2142 2154 f.write(u"# coding: utf-8\n")
2143 2155 f.write(py3compat.cast_unicode(cmds))
2144 2156 print 'The following commands were written to file `%s`:' % fname
2145 2157 print cmds
2146 2158
2147 2159 def magic_pastebin(self, parameter_s = ''):
2148 2160 """Upload code to the 'Lodge it' paste bin, returning the URL."""
2149 2161 try:
2150 2162 code = self.shell.find_user_code(parameter_s)
2151 2163 except (ValueError, TypeError) as e:
2152 2164 print e.args[0]
2153 2165 return
2154 2166 pbserver = ServerProxy('http://paste.pocoo.org/xmlrpc/')
2155 2167 id = pbserver.pastes.newPaste("python", code)
2156 2168 return "http://paste.pocoo.org/show/" + id
2157 2169
2158 2170 def magic_loadpy(self, arg_s):
2159 2171 """Load a .py python script into the GUI console.
2160 2172
2161 2173 This magic command can either take a local filename or a url::
2162 2174
2163 2175 %loadpy myscript.py
2164 2176 %loadpy http://www.example.com/myscript.py
2165 2177 """
2166 2178 arg_s = unquote_filename(arg_s)
2167 2179 remote_url = arg_s.startswith(('http://', 'https://'))
2168 2180 local_url = not remote_url
2169 2181 if local_url and not arg_s.endswith('.py'):
2170 2182 # Local files must be .py; for remote URLs it's possible that the
2171 2183 # fetch URL doesn't have a .py in it (many servers have an opaque
2172 2184 # URL, such as scipy-central.org).
2173 2185 raise ValueError('%%load only works with .py files: %s' % arg_s)
2174 2186 if remote_url:
2175 2187 import urllib2
2176 2188 fileobj = urllib2.urlopen(arg_s)
2177 2189 # While responses have a .info().getencoding() way of asking for
2178 2190 # their encoding, in *many* cases the return value is bogus. In
2179 2191 # the wild, servers serving utf-8 but declaring latin-1 are
2180 2192 # extremely common, as the old HTTP standards specify latin-1 as
2181 2193 # the default but many modern filesystems use utf-8. So we can NOT
2182 2194 # rely on the headers. Short of building complex encoding-guessing
2183 2195 # logic, going with utf-8 is a simple solution likely to be right
2184 2196 # in most real-world cases.
2185 2197 linesource = fileobj.read().decode('utf-8', 'replace').splitlines()
2186 2198 fileobj.close()
2187 2199 else:
2188 2200 with open(arg_s) as fileobj:
2189 2201 linesource = fileobj.read().splitlines()
2190 2202
2191 2203 # Strip out encoding declarations
2192 2204 lines = [l for l in linesource if not _encoding_declaration_re.match(l)]
2193 2205
2194 2206 self.set_next_input(os.linesep.join(lines))
2195 2207
2196 2208 def _find_edit_target(self, args, opts, last_call):
2197 2209 """Utility method used by magic_edit to find what to edit."""
2198 2210
2199 2211 def make_filename(arg):
2200 2212 "Make a filename from the given args"
2201 2213 arg = unquote_filename(arg)
2202 2214 try:
2203 2215 filename = get_py_filename(arg)
2204 2216 except IOError:
2205 2217 # If it ends with .py but doesn't already exist, assume we want
2206 2218 # a new file.
2207 2219 if arg.endswith('.py'):
2208 2220 filename = arg
2209 2221 else:
2210 2222 filename = None
2211 2223 return filename
2212 2224
2213 2225 # Set a few locals from the options for convenience:
2214 2226 opts_prev = 'p' in opts
2215 2227 opts_raw = 'r' in opts
2216 2228
2217 2229 # custom exceptions
2218 2230 class DataIsObject(Exception): pass
2219 2231
2220 2232 # Default line number value
2221 2233 lineno = opts.get('n',None)
2222 2234
2223 2235 if opts_prev:
2224 2236 args = '_%s' % last_call[0]
2225 2237 if not self.shell.user_ns.has_key(args):
2226 2238 args = last_call[1]
2227 2239
2228 2240 # use last_call to remember the state of the previous call, but don't
2229 2241 # let it be clobbered by successive '-p' calls.
2230 2242 try:
2231 2243 last_call[0] = self.shell.displayhook.prompt_count
2232 2244 if not opts_prev:
2233 2245 last_call[1] = parameter_s
2234 2246 except:
2235 2247 pass
2236 2248
2237 2249 # by default this is done with temp files, except when the given
2238 2250 # arg is a filename
2239 2251 use_temp = True
2240 2252
2241 2253 data = ''
2242 2254
2243 2255 # First, see if the arguments should be a filename.
2244 2256 filename = make_filename(args)
2245 2257 if filename:
2246 2258 use_temp = False
2247 2259 elif args:
2248 2260 # Mode where user specifies ranges of lines, like in %macro.
2249 2261 data = self.extract_input_lines(args, opts_raw)
2250 2262 if not data:
2251 2263 try:
2252 2264 # Load the parameter given as a variable. If not a string,
2253 2265 # process it as an object instead (below)
2254 2266
2255 2267 #print '*** args',args,'type',type(args) # dbg
2256 2268 data = eval(args, self.shell.user_ns)
2257 2269 if not isinstance(data, basestring):
2258 2270 raise DataIsObject
2259 2271
2260 2272 except (NameError,SyntaxError):
2261 2273 # given argument is not a variable, try as a filename
2262 2274 filename = make_filename(args)
2263 2275 if filename is None:
2264 2276 warn("Argument given (%s) can't be found as a variable "
2265 2277 "or as a filename." % args)
2266 2278 return
2267 2279 use_temp = False
2268 2280
2269 2281 except DataIsObject:
2270 2282 # macros have a special edit function
2271 2283 if isinstance(data, Macro):
2272 2284 raise MacroToEdit(data)
2273 2285
2274 2286 # For objects, try to edit the file where they are defined
2275 2287 try:
2276 2288 filename = inspect.getabsfile(data)
2277 2289 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2278 2290 # class created by %edit? Try to find source
2279 2291 # by looking for method definitions instead, the
2280 2292 # __module__ in those classes is FakeModule.
2281 2293 attrs = [getattr(data, aname) for aname in dir(data)]
2282 2294 for attr in attrs:
2283 2295 if not inspect.ismethod(attr):
2284 2296 continue
2285 2297 filename = inspect.getabsfile(attr)
2286 2298 if filename and 'fakemodule' not in filename.lower():
2287 2299 # change the attribute to be the edit target instead
2288 2300 data = attr
2289 2301 break
2290 2302
2291 2303 datafile = 1
2292 2304 except TypeError:
2293 2305 filename = make_filename(args)
2294 2306 datafile = 1
2295 2307 warn('Could not find file where `%s` is defined.\n'
2296 2308 'Opening a file named `%s`' % (args,filename))
2297 2309 # Now, make sure we can actually read the source (if it was in
2298 2310 # a temp file it's gone by now).
2299 2311 if datafile:
2300 2312 try:
2301 2313 if lineno is None:
2302 2314 lineno = inspect.getsourcelines(data)[1]
2303 2315 except IOError:
2304 2316 filename = make_filename(args)
2305 2317 if filename is None:
2306 2318 warn('The file `%s` where `%s` was defined cannot '
2307 2319 'be read.' % (filename,data))
2308 2320 return
2309 2321 use_temp = False
2310 2322
2311 2323 if use_temp:
2312 2324 filename = self.shell.mktempfile(data)
2313 2325 print 'IPython will make a temporary file named:',filename
2314 2326
2315 2327 return filename, lineno, use_temp
2316 2328
2317 2329 def _edit_macro(self,mname,macro):
2318 2330 """open an editor with the macro data in a file"""
2319 2331 filename = self.shell.mktempfile(macro.value)
2320 2332 self.shell.hooks.editor(filename)
2321 2333
2322 2334 # and make a new macro object, to replace the old one
2323 2335 mfile = open(filename)
2324 2336 mvalue = mfile.read()
2325 2337 mfile.close()
2326 2338 self.shell.user_ns[mname] = Macro(mvalue)
2327 2339
2328 2340 def magic_ed(self,parameter_s=''):
2329 2341 """Alias to %edit."""
2330 2342 return self.magic_edit(parameter_s)
2331 2343
2332 2344 @skip_doctest
2333 2345 def magic_edit(self,parameter_s='',last_call=['','']):
2334 2346 """Bring up an editor and execute the resulting code.
2335 2347
2336 2348 Usage:
2337 2349 %edit [options] [args]
2338 2350
2339 2351 %edit runs IPython's editor hook. The default version of this hook is
2340 2352 set to call the editor specified by your $EDITOR environment variable.
2341 2353 If this isn't found, it will default to vi under Linux/Unix and to
2342 2354 notepad under Windows. See the end of this docstring for how to change
2343 2355 the editor hook.
2344 2356
2345 2357 You can also set the value of this editor via the
2346 2358 ``TerminalInteractiveShell.editor`` option in your configuration file.
2347 2359 This is useful if you wish to use a different editor from your typical
2348 2360 default with IPython (and for Windows users who typically don't set
2349 2361 environment variables).
2350 2362
2351 2363 This command allows you to conveniently edit multi-line code right in
2352 2364 your IPython session.
2353 2365
2354 2366 If called without arguments, %edit opens up an empty editor with a
2355 2367 temporary file and will execute the contents of this file when you
2356 2368 close it (don't forget to save it!).
2357 2369
2358 2370
2359 2371 Options:
2360 2372
2361 2373 -n <number>: open the editor at a specified line number. By default,
2362 2374 the IPython editor hook uses the unix syntax 'editor +N filename', but
2363 2375 you can configure this by providing your own modified hook if your
2364 2376 favorite editor supports line-number specifications with a different
2365 2377 syntax.
2366 2378
2367 2379 -p: this will call the editor with the same data as the previous time
2368 2380 it was used, regardless of how long ago (in your current session) it
2369 2381 was.
2370 2382
2371 2383 -r: use 'raw' input. This option only applies to input taken from the
2372 2384 user's history. By default, the 'processed' history is used, so that
2373 2385 magics are loaded in their transformed version to valid Python. If
2374 2386 this option is given, the raw input as typed as the command line is
2375 2387 used instead. When you exit the editor, it will be executed by
2376 2388 IPython's own processor.
2377 2389
2378 2390 -x: do not execute the edited code immediately upon exit. This is
2379 2391 mainly useful if you are editing programs which need to be called with
2380 2392 command line arguments, which you can then do using %run.
2381 2393
2382 2394
2383 2395 Arguments:
2384 2396
2385 2397 If arguments are given, the following possibilities exist:
2386 2398
2387 2399 - If the argument is a filename, IPython will load that into the
2388 2400 editor. It will execute its contents with execfile() when you exit,
2389 2401 loading any code in the file into your interactive namespace.
2390 2402
2391 2403 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
2392 2404 The syntax is the same as in the %history magic.
2393 2405
2394 2406 - If the argument is a string variable, its contents are loaded
2395 2407 into the editor. You can thus edit any string which contains
2396 2408 python code (including the result of previous edits).
2397 2409
2398 2410 - If the argument is the name of an object (other than a string),
2399 2411 IPython will try to locate the file where it was defined and open the
2400 2412 editor at the point where it is defined. You can use `%edit function`
2401 2413 to load an editor exactly at the point where 'function' is defined,
2402 2414 edit it and have the file be executed automatically.
2403 2415
2404 2416 - If the object is a macro (see %macro for details), this opens up your
2405 2417 specified editor with a temporary file containing the macro's data.
2406 2418 Upon exit, the macro is reloaded with the contents of the file.
2407 2419
2408 2420 Note: opening at an exact line is only supported under Unix, and some
2409 2421 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2410 2422 '+NUMBER' parameter necessary for this feature. Good editors like
2411 2423 (X)Emacs, vi, jed, pico and joe all do.
2412 2424
2413 2425 After executing your code, %edit will return as output the code you
2414 2426 typed in the editor (except when it was an existing file). This way
2415 2427 you can reload the code in further invocations of %edit as a variable,
2416 2428 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2417 2429 the output.
2418 2430
2419 2431 Note that %edit is also available through the alias %ed.
2420 2432
2421 2433 This is an example of creating a simple function inside the editor and
2422 2434 then modifying it. First, start up the editor:
2423 2435
2424 2436 In [1]: ed
2425 2437 Editing... done. Executing edited code...
2426 2438 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2427 2439
2428 2440 We can then call the function foo():
2429 2441
2430 2442 In [2]: foo()
2431 2443 foo() was defined in an editing session
2432 2444
2433 2445 Now we edit foo. IPython automatically loads the editor with the
2434 2446 (temporary) file where foo() was previously defined:
2435 2447
2436 2448 In [3]: ed foo
2437 2449 Editing... done. Executing edited code...
2438 2450
2439 2451 And if we call foo() again we get the modified version:
2440 2452
2441 2453 In [4]: foo()
2442 2454 foo() has now been changed!
2443 2455
2444 2456 Here is an example of how to edit a code snippet successive
2445 2457 times. First we call the editor:
2446 2458
2447 2459 In [5]: ed
2448 2460 Editing... done. Executing edited code...
2449 2461 hello
2450 2462 Out[5]: "print 'hello'n"
2451 2463
2452 2464 Now we call it again with the previous output (stored in _):
2453 2465
2454 2466 In [6]: ed _
2455 2467 Editing... done. Executing edited code...
2456 2468 hello world
2457 2469 Out[6]: "print 'hello world'n"
2458 2470
2459 2471 Now we call it with the output #8 (stored in _8, also as Out[8]):
2460 2472
2461 2473 In [7]: ed _8
2462 2474 Editing... done. Executing edited code...
2463 2475 hello again
2464 2476 Out[7]: "print 'hello again'n"
2465 2477
2466 2478
2467 2479 Changing the default editor hook:
2468 2480
2469 2481 If you wish to write your own editor hook, you can put it in a
2470 2482 configuration file which you load at startup time. The default hook
2471 2483 is defined in the IPython.core.hooks module, and you can use that as a
2472 2484 starting example for further modifications. That file also has
2473 2485 general instructions on how to set a new hook for use once you've
2474 2486 defined it."""
2475 2487 opts,args = self.parse_options(parameter_s,'prxn:')
2476 2488
2477 2489 try:
2478 2490 filename, lineno, is_temp = self._find_edit_target(args, opts, last_call)
2479 2491 except MacroToEdit as e:
2480 2492 self._edit_macro(args, e.args[0])
2481 2493 return
2482 2494
2483 2495 # do actual editing here
2484 2496 print 'Editing...',
2485 2497 sys.stdout.flush()
2486 2498 try:
2487 2499 # Quote filenames that may have spaces in them
2488 2500 if ' ' in filename:
2489 2501 filename = "'%s'" % filename
2490 2502 self.shell.hooks.editor(filename,lineno)
2491 2503 except TryNext:
2492 2504 warn('Could not open editor')
2493 2505 return
2494 2506
2495 2507 # XXX TODO: should this be generalized for all string vars?
2496 2508 # For now, this is special-cased to blocks created by cpaste
2497 2509 if args.strip() == 'pasted_block':
2498 2510 self.shell.user_ns['pasted_block'] = file_read(filename)
2499 2511
2500 2512 if 'x' in opts: # -x prevents actual execution
2501 2513 print
2502 2514 else:
2503 2515 print 'done. Executing edited code...'
2504 2516 if 'r' in opts: # Untranslated IPython code
2505 2517 self.shell.run_cell(file_read(filename),
2506 2518 store_history=False)
2507 2519 else:
2508 2520 self.shell.safe_execfile(filename,self.shell.user_ns,
2509 2521 self.shell.user_ns)
2510 2522
2511 2523 if is_temp:
2512 2524 try:
2513 2525 return open(filename).read()
2514 2526 except IOError,msg:
2515 2527 if msg.filename == filename:
2516 2528 warn('File not found. Did you forget to save?')
2517 2529 return
2518 2530 else:
2519 2531 self.shell.showtraceback()
2520 2532
2521 2533 def magic_xmode(self,parameter_s = ''):
2522 2534 """Switch modes for the exception handlers.
2523 2535
2524 2536 Valid modes: Plain, Context and Verbose.
2525 2537
2526 2538 If called without arguments, acts as a toggle."""
2527 2539
2528 2540 def xmode_switch_err(name):
2529 2541 warn('Error changing %s exception modes.\n%s' %
2530 2542 (name,sys.exc_info()[1]))
2531 2543
2532 2544 shell = self.shell
2533 2545 new_mode = parameter_s.strip().capitalize()
2534 2546 try:
2535 2547 shell.InteractiveTB.set_mode(mode=new_mode)
2536 2548 print 'Exception reporting mode:',shell.InteractiveTB.mode
2537 2549 except:
2538 2550 xmode_switch_err('user')
2539 2551
2540 2552 def magic_colors(self,parameter_s = ''):
2541 2553 """Switch color scheme for prompts, info system and exception handlers.
2542 2554
2543 2555 Currently implemented schemes: NoColor, Linux, LightBG.
2544 2556
2545 2557 Color scheme names are not case-sensitive.
2546 2558
2547 2559 Examples
2548 2560 --------
2549 2561 To get a plain black and white terminal::
2550 2562
2551 2563 %colors nocolor
2552 2564 """
2553 2565
2554 2566 def color_switch_err(name):
2555 2567 warn('Error changing %s color schemes.\n%s' %
2556 2568 (name,sys.exc_info()[1]))
2557 2569
2558 2570
2559 2571 new_scheme = parameter_s.strip()
2560 2572 if not new_scheme:
2561 2573 raise UsageError(
2562 2574 "%colors: you must specify a color scheme. See '%colors?'")
2563 2575 return
2564 2576 # local shortcut
2565 2577 shell = self.shell
2566 2578
2567 2579 import IPython.utils.rlineimpl as readline
2568 2580
2569 2581 if not shell.colors_force and \
2570 2582 not readline.have_readline and sys.platform == "win32":
2571 2583 msg = """\
2572 2584 Proper color support under MS Windows requires the pyreadline library.
2573 2585 You can find it at:
2574 2586 http://ipython.org/pyreadline.html
2575 2587 Gary's readline needs the ctypes module, from:
2576 2588 http://starship.python.net/crew/theller/ctypes
2577 2589 (Note that ctypes is already part of Python versions 2.5 and newer).
2578 2590
2579 2591 Defaulting color scheme to 'NoColor'"""
2580 2592 new_scheme = 'NoColor'
2581 2593 warn(msg)
2582 2594
2583 2595 # readline option is 0
2584 2596 if not shell.colors_force and not shell.has_readline:
2585 2597 new_scheme = 'NoColor'
2586 2598
2587 2599 # Set prompt colors
2588 2600 try:
2589 2601 shell.prompt_manager.color_scheme = new_scheme
2590 2602 except:
2591 2603 color_switch_err('prompt')
2592 2604 else:
2593 2605 shell.colors = \
2594 2606 shell.prompt_manager.color_scheme_table.active_scheme_name
2595 2607 # Set exception colors
2596 2608 try:
2597 2609 shell.InteractiveTB.set_colors(scheme = new_scheme)
2598 2610 shell.SyntaxTB.set_colors(scheme = new_scheme)
2599 2611 except:
2600 2612 color_switch_err('exception')
2601 2613
2602 2614 # Set info (for 'object?') colors
2603 2615 if shell.color_info:
2604 2616 try:
2605 2617 shell.inspector.set_active_scheme(new_scheme)
2606 2618 except:
2607 2619 color_switch_err('object inspector')
2608 2620 else:
2609 2621 shell.inspector.set_active_scheme('NoColor')
2610 2622
2611 2623 def magic_pprint(self, parameter_s=''):
2612 2624 """Toggle pretty printing on/off."""
2613 2625 ptformatter = self.shell.display_formatter.formatters['text/plain']
2614 2626 ptformatter.pprint = bool(1 - ptformatter.pprint)
2615 2627 print 'Pretty printing has been turned', \
2616 2628 ['OFF','ON'][ptformatter.pprint]
2617 2629
2618 2630 #......................................................................
2619 2631 # Functions to implement unix shell-type things
2620 2632
2621 2633 @skip_doctest
2622 2634 def magic_alias(self, parameter_s = ''):
2623 2635 """Define an alias for a system command.
2624 2636
2625 2637 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2626 2638
2627 2639 Then, typing 'alias_name params' will execute the system command 'cmd
2628 2640 params' (from your underlying operating system).
2629 2641
2630 2642 Aliases have lower precedence than magic functions and Python normal
2631 2643 variables, so if 'foo' is both a Python variable and an alias, the
2632 2644 alias can not be executed until 'del foo' removes the Python variable.
2633 2645
2634 2646 You can use the %l specifier in an alias definition to represent the
2635 2647 whole line when the alias is called. For example:
2636 2648
2637 2649 In [2]: alias bracket echo "Input in brackets: <%l>"
2638 2650 In [3]: bracket hello world
2639 2651 Input in brackets: <hello world>
2640 2652
2641 2653 You can also define aliases with parameters using %s specifiers (one
2642 2654 per parameter):
2643 2655
2644 2656 In [1]: alias parts echo first %s second %s
2645 2657 In [2]: %parts A B
2646 2658 first A second B
2647 2659 In [3]: %parts A
2648 2660 Incorrect number of arguments: 2 expected.
2649 2661 parts is an alias to: 'echo first %s second %s'
2650 2662
2651 2663 Note that %l and %s are mutually exclusive. You can only use one or
2652 2664 the other in your aliases.
2653 2665
2654 2666 Aliases expand Python variables just like system calls using ! or !!
2655 2667 do: all expressions prefixed with '$' get expanded. For details of
2656 2668 the semantic rules, see PEP-215:
2657 2669 http://www.python.org/peps/pep-0215.html. This is the library used by
2658 2670 IPython for variable expansion. If you want to access a true shell
2659 2671 variable, an extra $ is necessary to prevent its expansion by IPython:
2660 2672
2661 2673 In [6]: alias show echo
2662 2674 In [7]: PATH='A Python string'
2663 2675 In [8]: show $PATH
2664 2676 A Python string
2665 2677 In [9]: show $$PATH
2666 2678 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2667 2679
2668 2680 You can use the alias facility to acess all of $PATH. See the %rehash
2669 2681 and %rehashx functions, which automatically create aliases for the
2670 2682 contents of your $PATH.
2671 2683
2672 2684 If called with no parameters, %alias prints the current alias table."""
2673 2685
2674 2686 par = parameter_s.strip()
2675 2687 if not par:
2676 2688 stored = self.db.get('stored_aliases', {} )
2677 2689 aliases = sorted(self.shell.alias_manager.aliases)
2678 2690 # for k, v in stored:
2679 2691 # atab.append(k, v[0])
2680 2692
2681 2693 print "Total number of aliases:", len(aliases)
2682 2694 sys.stdout.flush()
2683 2695 return aliases
2684 2696
2685 2697 # Now try to define a new one
2686 2698 try:
2687 2699 alias,cmd = par.split(None, 1)
2688 2700 except:
2689 2701 print oinspect.getdoc(self.magic_alias)
2690 2702 else:
2691 2703 self.shell.alias_manager.soft_define_alias(alias, cmd)
2692 2704 # end magic_alias
2693 2705
2694 2706 def magic_unalias(self, parameter_s = ''):
2695 2707 """Remove an alias"""
2696 2708
2697 2709 aname = parameter_s.strip()
2698 2710 self.shell.alias_manager.undefine_alias(aname)
2699 2711 stored = self.db.get('stored_aliases', {} )
2700 2712 if aname in stored:
2701 2713 print "Removing %stored alias",aname
2702 2714 del stored[aname]
2703 2715 self.db['stored_aliases'] = stored
2704 2716
2705 2717 def magic_rehashx(self, parameter_s = ''):
2706 2718 """Update the alias table with all executable files in $PATH.
2707 2719
2708 2720 This version explicitly checks that every entry in $PATH is a file
2709 2721 with execute access (os.X_OK), so it is much slower than %rehash.
2710 2722
2711 2723 Under Windows, it checks executability as a match against a
2712 2724 '|'-separated string of extensions, stored in the IPython config
2713 2725 variable win_exec_ext. This defaults to 'exe|com|bat'.
2714 2726
2715 2727 This function also resets the root module cache of module completer,
2716 2728 used on slow filesystems.
2717 2729 """
2718 2730 from IPython.core.alias import InvalidAliasError
2719 2731
2720 2732 # for the benefit of module completer in ipy_completers.py
2721 2733 del self.shell.db['rootmodules']
2722 2734
2723 2735 path = [os.path.abspath(os.path.expanduser(p)) for p in
2724 2736 os.environ.get('PATH','').split(os.pathsep)]
2725 2737 path = filter(os.path.isdir,path)
2726 2738
2727 2739 syscmdlist = []
2728 2740 # Now define isexec in a cross platform manner.
2729 2741 if os.name == 'posix':
2730 2742 isexec = lambda fname:os.path.isfile(fname) and \
2731 2743 os.access(fname,os.X_OK)
2732 2744 else:
2733 2745 try:
2734 2746 winext = os.environ['pathext'].replace(';','|').replace('.','')
2735 2747 except KeyError:
2736 2748 winext = 'exe|com|bat|py'
2737 2749 if 'py' not in winext:
2738 2750 winext += '|py'
2739 2751 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2740 2752 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2741 2753 savedir = os.getcwdu()
2742 2754
2743 2755 # Now walk the paths looking for executables to alias.
2744 2756 try:
2745 2757 # write the whole loop for posix/Windows so we don't have an if in
2746 2758 # the innermost part
2747 2759 if os.name == 'posix':
2748 2760 for pdir in path:
2749 2761 os.chdir(pdir)
2750 2762 for ff in os.listdir(pdir):
2751 2763 if isexec(ff):
2752 2764 try:
2753 2765 # Removes dots from the name since ipython
2754 2766 # will assume names with dots to be python.
2755 2767 self.shell.alias_manager.define_alias(
2756 2768 ff.replace('.',''), ff)
2757 2769 except InvalidAliasError:
2758 2770 pass
2759 2771 else:
2760 2772 syscmdlist.append(ff)
2761 2773 else:
2762 2774 no_alias = self.shell.alias_manager.no_alias
2763 2775 for pdir in path:
2764 2776 os.chdir(pdir)
2765 2777 for ff in os.listdir(pdir):
2766 2778 base, ext = os.path.splitext(ff)
2767 2779 if isexec(ff) and base.lower() not in no_alias:
2768 2780 if ext.lower() == '.exe':
2769 2781 ff = base
2770 2782 try:
2771 2783 # Removes dots from the name since ipython
2772 2784 # will assume names with dots to be python.
2773 2785 self.shell.alias_manager.define_alias(
2774 2786 base.lower().replace('.',''), ff)
2775 2787 except InvalidAliasError:
2776 2788 pass
2777 2789 syscmdlist.append(ff)
2778 2790 self.shell.db['syscmdlist'] = syscmdlist
2779 2791 finally:
2780 2792 os.chdir(savedir)
2781 2793
2782 2794 @skip_doctest
2783 2795 def magic_pwd(self, parameter_s = ''):
2784 2796 """Return the current working directory path.
2785 2797
2786 2798 Examples
2787 2799 --------
2788 2800 ::
2789 2801
2790 2802 In [9]: pwd
2791 2803 Out[9]: '/home/tsuser/sprint/ipython'
2792 2804 """
2793 2805 return os.getcwdu()
2794 2806
2795 2807 @skip_doctest
2796 2808 def magic_cd(self, parameter_s=''):
2797 2809 """Change the current working directory.
2798 2810
2799 2811 This command automatically maintains an internal list of directories
2800 2812 you visit during your IPython session, in the variable _dh. The
2801 2813 command %dhist shows this history nicely formatted. You can also
2802 2814 do 'cd -<tab>' to see directory history conveniently.
2803 2815
2804 2816 Usage:
2805 2817
2806 2818 cd 'dir': changes to directory 'dir'.
2807 2819
2808 2820 cd -: changes to the last visited directory.
2809 2821
2810 2822 cd -<n>: changes to the n-th directory in the directory history.
2811 2823
2812 2824 cd --foo: change to directory that matches 'foo' in history
2813 2825
2814 2826 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2815 2827 (note: cd <bookmark_name> is enough if there is no
2816 2828 directory <bookmark_name>, but a bookmark with the name exists.)
2817 2829 'cd -b <tab>' allows you to tab-complete bookmark names.
2818 2830
2819 2831 Options:
2820 2832
2821 2833 -q: quiet. Do not print the working directory after the cd command is
2822 2834 executed. By default IPython's cd command does print this directory,
2823 2835 since the default prompts do not display path information.
2824 2836
2825 2837 Note that !cd doesn't work for this purpose because the shell where
2826 2838 !command runs is immediately discarded after executing 'command'.
2827 2839
2828 2840 Examples
2829 2841 --------
2830 2842 ::
2831 2843
2832 2844 In [10]: cd parent/child
2833 2845 /home/tsuser/parent/child
2834 2846 """
2835 2847
2836 2848 parameter_s = parameter_s.strip()
2837 2849 #bkms = self.shell.persist.get("bookmarks",{})
2838 2850
2839 2851 oldcwd = os.getcwdu()
2840 2852 numcd = re.match(r'(-)(\d+)$',parameter_s)
2841 2853 # jump in directory history by number
2842 2854 if numcd:
2843 2855 nn = int(numcd.group(2))
2844 2856 try:
2845 2857 ps = self.shell.user_ns['_dh'][nn]
2846 2858 except IndexError:
2847 2859 print 'The requested directory does not exist in history.'
2848 2860 return
2849 2861 else:
2850 2862 opts = {}
2851 2863 elif parameter_s.startswith('--'):
2852 2864 ps = None
2853 2865 fallback = None
2854 2866 pat = parameter_s[2:]
2855 2867 dh = self.shell.user_ns['_dh']
2856 2868 # first search only by basename (last component)
2857 2869 for ent in reversed(dh):
2858 2870 if pat in os.path.basename(ent) and os.path.isdir(ent):
2859 2871 ps = ent
2860 2872 break
2861 2873
2862 2874 if fallback is None and pat in ent and os.path.isdir(ent):
2863 2875 fallback = ent
2864 2876
2865 2877 # if we have no last part match, pick the first full path match
2866 2878 if ps is None:
2867 2879 ps = fallback
2868 2880
2869 2881 if ps is None:
2870 2882 print "No matching entry in directory history"
2871 2883 return
2872 2884 else:
2873 2885 opts = {}
2874 2886
2875 2887
2876 2888 else:
2877 2889 #turn all non-space-escaping backslashes to slashes,
2878 2890 # for c:\windows\directory\names\
2879 2891 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2880 2892 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2881 2893 # jump to previous
2882 2894 if ps == '-':
2883 2895 try:
2884 2896 ps = self.shell.user_ns['_dh'][-2]
2885 2897 except IndexError:
2886 2898 raise UsageError('%cd -: No previous directory to change to.')
2887 2899 # jump to bookmark if needed
2888 2900 else:
2889 2901 if not os.path.isdir(ps) or opts.has_key('b'):
2890 2902 bkms = self.db.get('bookmarks', {})
2891 2903
2892 2904 if bkms.has_key(ps):
2893 2905 target = bkms[ps]
2894 2906 print '(bookmark:%s) -> %s' % (ps,target)
2895 2907 ps = target
2896 2908 else:
2897 2909 if opts.has_key('b'):
2898 2910 raise UsageError("Bookmark '%s' not found. "
2899 2911 "Use '%%bookmark -l' to see your bookmarks." % ps)
2900 2912
2901 2913 # strip extra quotes on Windows, because os.chdir doesn't like them
2902 2914 ps = unquote_filename(ps)
2903 2915 # at this point ps should point to the target dir
2904 2916 if ps:
2905 2917 try:
2906 2918 os.chdir(os.path.expanduser(ps))
2907 2919 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2908 2920 set_term_title('IPython: ' + abbrev_cwd())
2909 2921 except OSError:
2910 2922 print sys.exc_info()[1]
2911 2923 else:
2912 2924 cwd = os.getcwdu()
2913 2925 dhist = self.shell.user_ns['_dh']
2914 2926 if oldcwd != cwd:
2915 2927 dhist.append(cwd)
2916 2928 self.db['dhist'] = compress_dhist(dhist)[-100:]
2917 2929
2918 2930 else:
2919 2931 os.chdir(self.shell.home_dir)
2920 2932 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2921 2933 set_term_title('IPython: ' + '~')
2922 2934 cwd = os.getcwdu()
2923 2935 dhist = self.shell.user_ns['_dh']
2924 2936
2925 2937 if oldcwd != cwd:
2926 2938 dhist.append(cwd)
2927 2939 self.db['dhist'] = compress_dhist(dhist)[-100:]
2928 2940 if not 'q' in opts and self.shell.user_ns['_dh']:
2929 2941 print self.shell.user_ns['_dh'][-1]
2930 2942
2931 2943
2932 2944 def magic_env(self, parameter_s=''):
2933 2945 """List environment variables."""
2934 2946
2935 2947 return os.environ.data
2936 2948
2937 2949 def magic_pushd(self, parameter_s=''):
2938 2950 """Place the current dir on stack and change directory.
2939 2951
2940 2952 Usage:\\
2941 2953 %pushd ['dirname']
2942 2954 """
2943 2955
2944 2956 dir_s = self.shell.dir_stack
2945 2957 tgt = os.path.expanduser(unquote_filename(parameter_s))
2946 2958 cwd = os.getcwdu().replace(self.home_dir,'~')
2947 2959 if tgt:
2948 2960 self.magic_cd(parameter_s)
2949 2961 dir_s.insert(0,cwd)
2950 2962 return self.magic_dirs()
2951 2963
2952 2964 def magic_popd(self, parameter_s=''):
2953 2965 """Change to directory popped off the top of the stack.
2954 2966 """
2955 2967 if not self.shell.dir_stack:
2956 2968 raise UsageError("%popd on empty stack")
2957 2969 top = self.shell.dir_stack.pop(0)
2958 2970 self.magic_cd(top)
2959 2971 print "popd ->",top
2960 2972
2961 2973 def magic_dirs(self, parameter_s=''):
2962 2974 """Return the current directory stack."""
2963 2975
2964 2976 return self.shell.dir_stack
2965 2977
2966 2978 def magic_dhist(self, parameter_s=''):
2967 2979 """Print your history of visited directories.
2968 2980
2969 2981 %dhist -> print full history\\
2970 2982 %dhist n -> print last n entries only\\
2971 2983 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2972 2984
2973 2985 This history is automatically maintained by the %cd command, and
2974 2986 always available as the global list variable _dh. You can use %cd -<n>
2975 2987 to go to directory number <n>.
2976 2988
2977 2989 Note that most of time, you should view directory history by entering
2978 2990 cd -<TAB>.
2979 2991
2980 2992 """
2981 2993
2982 2994 dh = self.shell.user_ns['_dh']
2983 2995 if parameter_s:
2984 2996 try:
2985 2997 args = map(int,parameter_s.split())
2986 2998 except:
2987 2999 self.arg_err(Magic.magic_dhist)
2988 3000 return
2989 3001 if len(args) == 1:
2990 3002 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2991 3003 elif len(args) == 2:
2992 3004 ini,fin = args
2993 3005 else:
2994 3006 self.arg_err(Magic.magic_dhist)
2995 3007 return
2996 3008 else:
2997 3009 ini,fin = 0,len(dh)
2998 3010 nlprint(dh,
2999 3011 header = 'Directory history (kept in _dh)',
3000 3012 start=ini,stop=fin)
3001 3013
3002 3014 @skip_doctest
3003 3015 def magic_sc(self, parameter_s=''):
3004 3016 """Shell capture - execute a shell command and capture its output.
3005 3017
3006 3018 DEPRECATED. Suboptimal, retained for backwards compatibility.
3007 3019
3008 3020 You should use the form 'var = !command' instead. Example:
3009 3021
3010 3022 "%sc -l myfiles = ls ~" should now be written as
3011 3023
3012 3024 "myfiles = !ls ~"
3013 3025
3014 3026 myfiles.s, myfiles.l and myfiles.n still apply as documented
3015 3027 below.
3016 3028
3017 3029 --
3018 3030 %sc [options] varname=command
3019 3031
3020 3032 IPython will run the given command using commands.getoutput(), and
3021 3033 will then update the user's interactive namespace with a variable
3022 3034 called varname, containing the value of the call. Your command can
3023 3035 contain shell wildcards, pipes, etc.
3024 3036
3025 3037 The '=' sign in the syntax is mandatory, and the variable name you
3026 3038 supply must follow Python's standard conventions for valid names.
3027 3039
3028 3040 (A special format without variable name exists for internal use)
3029 3041
3030 3042 Options:
3031 3043
3032 3044 -l: list output. Split the output on newlines into a list before
3033 3045 assigning it to the given variable. By default the output is stored
3034 3046 as a single string.
3035 3047
3036 3048 -v: verbose. Print the contents of the variable.
3037 3049
3038 3050 In most cases you should not need to split as a list, because the
3039 3051 returned value is a special type of string which can automatically
3040 3052 provide its contents either as a list (split on newlines) or as a
3041 3053 space-separated string. These are convenient, respectively, either
3042 3054 for sequential processing or to be passed to a shell command.
3043 3055
3044 3056 For example:
3045 3057
3046 3058 # all-random
3047 3059
3048 3060 # Capture into variable a
3049 3061 In [1]: sc a=ls *py
3050 3062
3051 3063 # a is a string with embedded newlines
3052 3064 In [2]: a
3053 3065 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3054 3066
3055 3067 # which can be seen as a list:
3056 3068 In [3]: a.l
3057 3069 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3058 3070
3059 3071 # or as a whitespace-separated string:
3060 3072 In [4]: a.s
3061 3073 Out[4]: 'setup.py win32_manual_post_install.py'
3062 3074
3063 3075 # a.s is useful to pass as a single command line:
3064 3076 In [5]: !wc -l $a.s
3065 3077 146 setup.py
3066 3078 130 win32_manual_post_install.py
3067 3079 276 total
3068 3080
3069 3081 # while the list form is useful to loop over:
3070 3082 In [6]: for f in a.l:
3071 3083 ...: !wc -l $f
3072 3084 ...:
3073 3085 146 setup.py
3074 3086 130 win32_manual_post_install.py
3075 3087
3076 3088 Similarly, the lists returned by the -l option are also special, in
3077 3089 the sense that you can equally invoke the .s attribute on them to
3078 3090 automatically get a whitespace-separated string from their contents:
3079 3091
3080 3092 In [7]: sc -l b=ls *py
3081 3093
3082 3094 In [8]: b
3083 3095 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3084 3096
3085 3097 In [9]: b.s
3086 3098 Out[9]: 'setup.py win32_manual_post_install.py'
3087 3099
3088 3100 In summary, both the lists and strings used for output capture have
3089 3101 the following special attributes:
3090 3102
3091 3103 .l (or .list) : value as list.
3092 3104 .n (or .nlstr): value as newline-separated string.
3093 3105 .s (or .spstr): value as space-separated string.
3094 3106 """
3095 3107
3096 3108 opts,args = self.parse_options(parameter_s,'lv')
3097 3109 # Try to get a variable name and command to run
3098 3110 try:
3099 3111 # the variable name must be obtained from the parse_options
3100 3112 # output, which uses shlex.split to strip options out.
3101 3113 var,_ = args.split('=',1)
3102 3114 var = var.strip()
3103 3115 # But the command has to be extracted from the original input
3104 3116 # parameter_s, not on what parse_options returns, to avoid the
3105 3117 # quote stripping which shlex.split performs on it.
3106 3118 _,cmd = parameter_s.split('=',1)
3107 3119 except ValueError:
3108 3120 var,cmd = '',''
3109 3121 # If all looks ok, proceed
3110 3122 split = 'l' in opts
3111 3123 out = self.shell.getoutput(cmd, split=split)
3112 3124 if opts.has_key('v'):
3113 3125 print '%s ==\n%s' % (var,pformat(out))
3114 3126 if var:
3115 3127 self.shell.user_ns.update({var:out})
3116 3128 else:
3117 3129 return out
3118 3130
3119 3131 def magic_sx(self, parameter_s=''):
3120 3132 """Shell execute - run a shell command and capture its output.
3121 3133
3122 3134 %sx command
3123 3135
3124 3136 IPython will run the given command using commands.getoutput(), and
3125 3137 return the result formatted as a list (split on '\\n'). Since the
3126 3138 output is _returned_, it will be stored in ipython's regular output
3127 3139 cache Out[N] and in the '_N' automatic variables.
3128 3140
3129 3141 Notes:
3130 3142
3131 3143 1) If an input line begins with '!!', then %sx is automatically
3132 3144 invoked. That is, while:
3133 3145 !ls
3134 3146 causes ipython to simply issue system('ls'), typing
3135 3147 !!ls
3136 3148 is a shorthand equivalent to:
3137 3149 %sx ls
3138 3150
3139 3151 2) %sx differs from %sc in that %sx automatically splits into a list,
3140 3152 like '%sc -l'. The reason for this is to make it as easy as possible
3141 3153 to process line-oriented shell output via further python commands.
3142 3154 %sc is meant to provide much finer control, but requires more
3143 3155 typing.
3144 3156
3145 3157 3) Just like %sc -l, this is a list with special attributes:
3146 3158
3147 3159 .l (or .list) : value as list.
3148 3160 .n (or .nlstr): value as newline-separated string.
3149 3161 .s (or .spstr): value as whitespace-separated string.
3150 3162
3151 3163 This is very useful when trying to use such lists as arguments to
3152 3164 system commands."""
3153 3165
3154 3166 if parameter_s:
3155 3167 return self.shell.getoutput(parameter_s)
3156 3168
3157 3169
3158 3170 def magic_bookmark(self, parameter_s=''):
3159 3171 """Manage IPython's bookmark system.
3160 3172
3161 3173 %bookmark <name> - set bookmark to current dir
3162 3174 %bookmark <name> <dir> - set bookmark to <dir>
3163 3175 %bookmark -l - list all bookmarks
3164 3176 %bookmark -d <name> - remove bookmark
3165 3177 %bookmark -r - remove all bookmarks
3166 3178
3167 3179 You can later on access a bookmarked folder with:
3168 3180 %cd -b <name>
3169 3181 or simply '%cd <name>' if there is no directory called <name> AND
3170 3182 there is such a bookmark defined.
3171 3183
3172 3184 Your bookmarks persist through IPython sessions, but they are
3173 3185 associated with each profile."""
3174 3186
3175 3187 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3176 3188 if len(args) > 2:
3177 3189 raise UsageError("%bookmark: too many arguments")
3178 3190
3179 3191 bkms = self.db.get('bookmarks',{})
3180 3192
3181 3193 if opts.has_key('d'):
3182 3194 try:
3183 3195 todel = args[0]
3184 3196 except IndexError:
3185 3197 raise UsageError(
3186 3198 "%bookmark -d: must provide a bookmark to delete")
3187 3199 else:
3188 3200 try:
3189 3201 del bkms[todel]
3190 3202 except KeyError:
3191 3203 raise UsageError(
3192 3204 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3193 3205
3194 3206 elif opts.has_key('r'):
3195 3207 bkms = {}
3196 3208 elif opts.has_key('l'):
3197 3209 bks = bkms.keys()
3198 3210 bks.sort()
3199 3211 if bks:
3200 3212 size = max(map(len,bks))
3201 3213 else:
3202 3214 size = 0
3203 3215 fmt = '%-'+str(size)+'s -> %s'
3204 3216 print 'Current bookmarks:'
3205 3217 for bk in bks:
3206 3218 print fmt % (bk,bkms[bk])
3207 3219 else:
3208 3220 if not args:
3209 3221 raise UsageError("%bookmark: You must specify the bookmark name")
3210 3222 elif len(args)==1:
3211 3223 bkms[args[0]] = os.getcwdu()
3212 3224 elif len(args)==2:
3213 3225 bkms[args[0]] = args[1]
3214 3226 self.db['bookmarks'] = bkms
3215 3227
3216 3228 def magic_pycat(self, parameter_s=''):
3217 3229 """Show a syntax-highlighted file through a pager.
3218 3230
3219 3231 This magic is similar to the cat utility, but it will assume the file
3220 3232 to be Python source and will show it with syntax highlighting. """
3221 3233
3222 3234 try:
3223 3235 filename = get_py_filename(parameter_s)
3224 3236 cont = file_read(filename)
3225 3237 except IOError:
3226 3238 try:
3227 3239 cont = eval(parameter_s,self.user_ns)
3228 3240 except NameError:
3229 3241 cont = None
3230 3242 if cont is None:
3231 3243 print "Error: no such file or variable"
3232 3244 return
3233 3245
3234 3246 page.page(self.shell.pycolorize(cont))
3235 3247
3236 3248 def magic_quickref(self,arg):
3237 3249 """ Show a quick reference sheet """
3238 3250 import IPython.core.usage
3239 3251 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3240 3252
3241 3253 page.page(qr)
3242 3254
3243 3255 def magic_doctest_mode(self,parameter_s=''):
3244 3256 """Toggle doctest mode on and off.
3245 3257
3246 3258 This mode is intended to make IPython behave as much as possible like a
3247 3259 plain Python shell, from the perspective of how its prompts, exceptions
3248 3260 and output look. This makes it easy to copy and paste parts of a
3249 3261 session into doctests. It does so by:
3250 3262
3251 3263 - Changing the prompts to the classic ``>>>`` ones.
3252 3264 - Changing the exception reporting mode to 'Plain'.
3253 3265 - Disabling pretty-printing of output.
3254 3266
3255 3267 Note that IPython also supports the pasting of code snippets that have
3256 3268 leading '>>>' and '...' prompts in them. This means that you can paste
3257 3269 doctests from files or docstrings (even if they have leading
3258 3270 whitespace), and the code will execute correctly. You can then use
3259 3271 '%history -t' to see the translated history; this will give you the
3260 3272 input after removal of all the leading prompts and whitespace, which
3261 3273 can be pasted back into an editor.
3262 3274
3263 3275 With these features, you can switch into this mode easily whenever you
3264 3276 need to do testing and changes to doctests, without having to leave
3265 3277 your existing IPython session.
3266 3278 """
3267 3279
3268 3280 from IPython.utils.ipstruct import Struct
3269 3281
3270 3282 # Shorthands
3271 3283 shell = self.shell
3272 3284 pm = shell.prompt_manager
3273 3285 meta = shell.meta
3274 3286 disp_formatter = self.shell.display_formatter
3275 3287 ptformatter = disp_formatter.formatters['text/plain']
3276 3288 # dstore is a data store kept in the instance metadata bag to track any
3277 3289 # changes we make, so we can undo them later.
3278 3290 dstore = meta.setdefault('doctest_mode',Struct())
3279 3291 save_dstore = dstore.setdefault
3280 3292
3281 3293 # save a few values we'll need to recover later
3282 3294 mode = save_dstore('mode',False)
3283 3295 save_dstore('rc_pprint',ptformatter.pprint)
3284 3296 save_dstore('xmode',shell.InteractiveTB.mode)
3285 3297 save_dstore('rc_separate_out',shell.separate_out)
3286 3298 save_dstore('rc_separate_out2',shell.separate_out2)
3287 3299 save_dstore('rc_prompts_pad_left',pm.justify)
3288 3300 save_dstore('rc_separate_in',shell.separate_in)
3289 3301 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3290 3302 save_dstore('prompt_templates',(pm.in_template, pm.in2_template, pm.out_template))
3291 3303
3292 3304 if mode == False:
3293 3305 # turn on
3294 3306 pm.in_template = '>>> '
3295 3307 pm.in2_template = '... '
3296 3308 pm.out_template = ''
3297 3309
3298 3310 # Prompt separators like plain python
3299 3311 shell.separate_in = ''
3300 3312 shell.separate_out = ''
3301 3313 shell.separate_out2 = ''
3302 3314
3303 3315 pm.justify = False
3304 3316
3305 3317 ptformatter.pprint = False
3306 3318 disp_formatter.plain_text_only = True
3307 3319
3308 3320 shell.magic_xmode('Plain')
3309 3321 else:
3310 3322 # turn off
3311 3323 pm.in_template, pm.in2_template, pm.out_template = dstore.prompt_templates
3312 3324
3313 3325 shell.separate_in = dstore.rc_separate_in
3314 3326
3315 3327 shell.separate_out = dstore.rc_separate_out
3316 3328 shell.separate_out2 = dstore.rc_separate_out2
3317 3329
3318 3330 pm.justify = dstore.rc_prompts_pad_left
3319 3331
3320 3332 ptformatter.pprint = dstore.rc_pprint
3321 3333 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3322 3334
3323 3335 shell.magic_xmode(dstore.xmode)
3324 3336
3325 3337 # Store new mode and inform
3326 3338 dstore.mode = bool(1-int(mode))
3327 3339 mode_label = ['OFF','ON'][dstore.mode]
3328 3340 print 'Doctest mode is:', mode_label
3329 3341
3330 3342 def magic_gui(self, parameter_s=''):
3331 3343 """Enable or disable IPython GUI event loop integration.
3332 3344
3333 3345 %gui [GUINAME]
3334 3346
3335 3347 This magic replaces IPython's threaded shells that were activated
3336 3348 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3337 3349 can now be enabled at runtime and keyboard
3338 3350 interrupts should work without any problems. The following toolkits
3339 3351 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
3340 3352
3341 3353 %gui wx # enable wxPython event loop integration
3342 3354 %gui qt4|qt # enable PyQt4 event loop integration
3343 3355 %gui gtk # enable PyGTK event loop integration
3344 3356 %gui tk # enable Tk event loop integration
3345 3357 %gui OSX # enable Cocoa event loop integration
3346 3358 # (requires %matplotlib 1.1)
3347 3359 %gui # disable all event loop integration
3348 3360
3349 3361 WARNING: after any of these has been called you can simply create
3350 3362 an application object, but DO NOT start the event loop yourself, as
3351 3363 we have already handled that.
3352 3364 """
3353 3365 opts, arg = self.parse_options(parameter_s, '')
3354 3366 if arg=='': arg = None
3355 3367 try:
3356 3368 return self.enable_gui(arg)
3357 3369 except Exception as e:
3358 3370 # print simple error message, rather than traceback if we can't
3359 3371 # hook up the GUI
3360 3372 error(str(e))
3361 3373
3362 3374 def magic_load_ext(self, module_str):
3363 3375 """Load an IPython extension by its module name."""
3364 3376 return self.extension_manager.load_extension(module_str)
3365 3377
3366 3378 def magic_unload_ext(self, module_str):
3367 3379 """Unload an IPython extension by its module name."""
3368 3380 self.extension_manager.unload_extension(module_str)
3369 3381
3370 3382 def magic_reload_ext(self, module_str):
3371 3383 """Reload an IPython extension by its module name."""
3372 3384 self.extension_manager.reload_extension(module_str)
3373 3385
3374 3386 def magic_install_profiles(self, s):
3375 3387 """%install_profiles has been deprecated."""
3376 3388 print '\n'.join([
3377 3389 "%install_profiles has been deprecated.",
3378 3390 "Use `ipython profile list` to view available profiles.",
3379 3391 "Requesting a profile with `ipython profile create <name>`",
3380 3392 "or `ipython --profile=<name>` will start with the bundled",
3381 3393 "profile of that name if it exists."
3382 3394 ])
3383 3395
3384 3396 def magic_install_default_config(self, s):
3385 3397 """%install_default_config has been deprecated."""
3386 3398 print '\n'.join([
3387 3399 "%install_default_config has been deprecated.",
3388 3400 "Use `ipython profile create <name>` to initialize a profile",
3389 3401 "with the default config files.",
3390 3402 "Add `--reset` to overwrite already existing config files with defaults."
3391 3403 ])
3392 3404
3393 3405 # Pylab support: simple wrappers that activate pylab, load gui input
3394 3406 # handling and modify slightly %run
3395 3407
3396 3408 @skip_doctest
3397 3409 def _pylab_magic_run(self, parameter_s=''):
3398 3410 Magic.magic_run(self, parameter_s,
3399 3411 runner=mpl_runner(self.shell.safe_execfile))
3400 3412
3401 3413 _pylab_magic_run.__doc__ = magic_run.__doc__
3402 3414
3403 3415 @skip_doctest
3404 3416 def magic_pylab(self, s):
3405 3417 """Load numpy and matplotlib to work interactively.
3406 3418
3407 3419 %pylab [GUINAME]
3408 3420
3409 3421 This function lets you activate pylab (matplotlib, numpy and
3410 3422 interactive support) at any point during an IPython session.
3411 3423
3412 3424 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3413 3425 pylab and mlab, as well as all names from numpy and pylab.
3414 3426
3415 3427 If you are using the inline matplotlib backend for embedded figures,
3416 3428 you can adjust its behavior via the %config magic::
3417 3429
3418 3430 # enable SVG figures, necessary for SVG+XHTML export in the qtconsole
3419 3431 In [1]: %config InlineBackend.figure_format = 'svg'
3420 3432
3421 3433 # change the behavior of closing all figures at the end of each
3422 3434 # execution (cell), or allowing reuse of active figures across
3423 3435 # cells:
3424 3436 In [2]: %config InlineBackend.close_figures = False
3425 3437
3426 3438 Parameters
3427 3439 ----------
3428 3440 guiname : optional
3429 3441 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk',
3430 3442 'osx' or 'tk'). If given, the corresponding Matplotlib backend is
3431 3443 used, otherwise matplotlib's default (which you can override in your
3432 3444 matplotlib config file) is used.
3433 3445
3434 3446 Examples
3435 3447 --------
3436 3448 In this case, where the MPL default is TkAgg::
3437 3449
3438 3450 In [2]: %pylab
3439 3451
3440 3452 Welcome to pylab, a matplotlib-based Python environment.
3441 3453 Backend in use: TkAgg
3442 3454 For more information, type 'help(pylab)'.
3443 3455
3444 3456 But you can explicitly request a different backend::
3445 3457
3446 3458 In [3]: %pylab qt
3447 3459
3448 3460 Welcome to pylab, a matplotlib-based Python environment.
3449 3461 Backend in use: Qt4Agg
3450 3462 For more information, type 'help(pylab)'.
3451 3463 """
3452 3464
3453 3465 if Application.initialized():
3454 3466 app = Application.instance()
3455 3467 try:
3456 3468 import_all_status = app.pylab_import_all
3457 3469 except AttributeError:
3458 3470 import_all_status = True
3459 3471 else:
3460 3472 import_all_status = True
3461 3473
3462 3474 self.shell.enable_pylab(s, import_all=import_all_status)
3463 3475
3464 3476 def magic_tb(self, s):
3465 3477 """Print the last traceback with the currently active exception mode.
3466 3478
3467 3479 See %xmode for changing exception reporting modes."""
3468 3480 self.shell.showtraceback()
3469 3481
3470 3482 @skip_doctest
3471 3483 def magic_precision(self, s=''):
3472 3484 """Set floating point precision for pretty printing.
3473 3485
3474 3486 Can set either integer precision or a format string.
3475 3487
3476 3488 If numpy has been imported and precision is an int,
3477 3489 numpy display precision will also be set, via ``numpy.set_printoptions``.
3478 3490
3479 3491 If no argument is given, defaults will be restored.
3480 3492
3481 3493 Examples
3482 3494 --------
3483 3495 ::
3484 3496
3485 3497 In [1]: from math import pi
3486 3498
3487 3499 In [2]: %precision 3
3488 3500 Out[2]: u'%.3f'
3489 3501
3490 3502 In [3]: pi
3491 3503 Out[3]: 3.142
3492 3504
3493 3505 In [4]: %precision %i
3494 3506 Out[4]: u'%i'
3495 3507
3496 3508 In [5]: pi
3497 3509 Out[5]: 3
3498 3510
3499 3511 In [6]: %precision %e
3500 3512 Out[6]: u'%e'
3501 3513
3502 3514 In [7]: pi**10
3503 3515 Out[7]: 9.364805e+04
3504 3516
3505 3517 In [8]: %precision
3506 3518 Out[8]: u'%r'
3507 3519
3508 3520 In [9]: pi**10
3509 3521 Out[9]: 93648.047476082982
3510 3522
3511 3523 """
3512 3524
3513 3525 ptformatter = self.shell.display_formatter.formatters['text/plain']
3514 3526 ptformatter.float_precision = s
3515 3527 return ptformatter.float_format
3516 3528
3517 3529
3518 3530 @magic_arguments.magic_arguments()
3519 3531 @magic_arguments.argument(
3520 3532 '-e', '--export', action='store_true', default=False,
3521 3533 help='Export IPython history as a notebook. The filename argument '
3522 3534 'is used to specify the notebook name and format. For example '
3523 3535 'a filename of notebook.ipynb will result in a notebook name '
3524 3536 'of "notebook" and a format of "xml". Likewise using a ".json" '
3525 3537 'or ".py" file extension will write the notebook in the json '
3526 3538 'or py formats.'
3527 3539 )
3528 3540 @magic_arguments.argument(
3529 3541 '-f', '--format',
3530 3542 help='Convert an existing IPython notebook to a new format. This option '
3531 3543 'specifies the new format and can have the values: xml, json, py. '
3532 3544 'The target filename is chosen automatically based on the new '
3533 3545 'format. The filename argument gives the name of the source file.'
3534 3546 )
3535 3547 @magic_arguments.argument(
3536 3548 'filename', type=unicode,
3537 3549 help='Notebook name or filename'
3538 3550 )
3539 3551 def magic_notebook(self, s):
3540 3552 """Export and convert IPython notebooks.
3541 3553
3542 3554 This function can export the current IPython history to a notebook file
3543 3555 or can convert an existing notebook file into a different format. For
3544 3556 example, to export the history to "foo.ipynb" do "%notebook -e foo.ipynb".
3545 3557 To export the history to "foo.py" do "%notebook -e foo.py". To convert
3546 3558 "foo.ipynb" to "foo.json" do "%notebook -f json foo.ipynb". Possible
3547 3559 formats include (json/ipynb, py).
3548 3560 """
3549 3561 args = magic_arguments.parse_argstring(self.magic_notebook, s)
3550 3562
3551 3563 from IPython.nbformat import current
3552 3564 args.filename = unquote_filename(args.filename)
3553 3565 if args.export:
3554 3566 fname, name, format = current.parse_filename(args.filename)
3555 3567 cells = []
3556 3568 hist = list(self.history_manager.get_range())
3557 3569 for session, prompt_number, input in hist[:-1]:
3558 3570 cells.append(current.new_code_cell(prompt_number=prompt_number, input=input))
3559 3571 worksheet = current.new_worksheet(cells=cells)
3560 3572 nb = current.new_notebook(name=name,worksheets=[worksheet])
3561 3573 with open(fname, 'w') as f:
3562 3574 current.write(nb, f, format);
3563 3575 elif args.format is not None:
3564 3576 old_fname, old_name, old_format = current.parse_filename(args.filename)
3565 3577 new_format = args.format
3566 3578 if new_format == u'xml':
3567 3579 raise ValueError('Notebooks cannot be written as xml.')
3568 3580 elif new_format == u'ipynb' or new_format == u'json':
3569 3581 new_fname = old_name + u'.ipynb'
3570 3582 new_format = u'json'
3571 3583 elif new_format == u'py':
3572 3584 new_fname = old_name + u'.py'
3573 3585 else:
3574 3586 raise ValueError('Invalid notebook format: %s' % new_format)
3575 3587 with open(old_fname, 'r') as f:
3576 3588 s = f.read()
3577 3589 try:
3578 3590 nb = current.reads(s, old_format)
3579 3591 except:
3580 3592 nb = current.reads(s, u'xml')
3581 3593 with open(new_fname, 'w') as f:
3582 3594 current.write(nb, f, new_format)
3583 3595
3584 3596 def magic_config(self, s):
3585 3597 """configure IPython
3586 3598
3587 3599 %config Class[.trait=value]
3588 3600
3589 3601 This magic exposes most of the IPython config system. Any
3590 3602 Configurable class should be able to be configured with the simple
3591 3603 line::
3592 3604
3593 3605 %config Class.trait=value
3594 3606
3595 3607 Where `value` will be resolved in the user's namespace, if it is an
3596 3608 expression or variable name.
3597 3609
3598 3610 Examples
3599 3611 --------
3600 3612
3601 3613 To see what classes are available for config, pass no arguments::
3602 3614
3603 3615 In [1]: %config
3604 3616 Available objects for config:
3605 3617 TerminalInteractiveShell
3606 3618 HistoryManager
3607 3619 PrefilterManager
3608 3620 AliasManager
3609 3621 IPCompleter
3610 3622 PromptManager
3611 3623 DisplayFormatter
3612 3624
3613 3625 To view what is configurable on a given class, just pass the class name::
3614 3626
3615 3627 In [2]: %config IPCompleter
3616 3628 IPCompleter options
3617 3629 -----------------
3618 3630 IPCompleter.omit__names=<Enum>
3619 3631 Current: 2
3620 3632 Choices: (0, 1, 2)
3621 3633 Instruct the completer to omit private method names
3622 3634 Specifically, when completing on ``object.<tab>``.
3623 3635 When 2 [default]: all names that start with '_' will be excluded.
3624 3636 When 1: all 'magic' names (``__foo__``) will be excluded.
3625 3637 When 0: nothing will be excluded.
3626 3638 IPCompleter.merge_completions=<CBool>
3627 3639 Current: True
3628 3640 Whether to merge completion results into a single list
3629 3641 If False, only the completion results from the first non-empty completer
3630 3642 will be returned.
3631 3643 IPCompleter.greedy=<CBool>
3632 3644 Current: False
3633 3645 Activate greedy completion
3634 3646 This will enable completion on elements of lists, results of function calls,
3635 3647 etc., but can be unsafe because the code is actually evaluated on TAB.
3636 3648
3637 3649 but the real use is in setting values::
3638 3650
3639 3651 In [3]: %config IPCompleter.greedy = True
3640 3652
3641 3653 and these values are read from the user_ns if they are variables::
3642 3654
3643 3655 In [4]: feeling_greedy=False
3644 3656
3645 3657 In [5]: %config IPCompleter.greedy = feeling_greedy
3646 3658
3647 3659 """
3648 3660 from IPython.config.loader import Config
3649 3661 # some IPython objects are Configurable, but do not yet have
3650 3662 # any configurable traits. Exclude them from the effects of
3651 3663 # this magic, as their presence is just noise:
3652 3664 configurables = [ c for c in self.configurables if c.__class__.class_traits(config=True) ]
3653 3665 classnames = [ c.__class__.__name__ for c in configurables ]
3654 3666
3655 3667 line = s.strip()
3656 3668 if not line:
3657 3669 # print available configurable names
3658 3670 print "Available objects for config:"
3659 3671 for name in classnames:
3660 3672 print " ", name
3661 3673 return
3662 3674 elif line in classnames:
3663 3675 # `%config TerminalInteractiveShell` will print trait info for
3664 3676 # TerminalInteractiveShell
3665 3677 c = configurables[classnames.index(line)]
3666 3678 cls = c.__class__
3667 3679 help = cls.class_get_help(c)
3668 3680 # strip leading '--' from cl-args:
3669 3681 help = re.sub(re.compile(r'^--', re.MULTILINE), '', help)
3670 3682 print help
3671 3683 return
3672 3684 elif '=' not in line:
3673 3685 raise UsageError("Invalid config statement: %r, should be Class.trait = value" % line)
3674 3686
3675 3687
3676 3688 # otherwise, assume we are setting configurables.
3677 3689 # leave quotes on args when splitting, because we want
3678 3690 # unquoted args to eval in user_ns
3679 3691 cfg = Config()
3680 3692 exec "cfg."+line in locals(), self.user_ns
3681 3693
3682 3694 for configurable in configurables:
3683 3695 try:
3684 3696 configurable.update_config(cfg)
3685 3697 except Exception as e:
3686 3698 error(e)
3687 3699
3688 3700 # end Magic
General Comments 0
You need to be logged in to leave comments. Login now