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