##// END OF EJS Templates
Fix Python 3 handling of urllib...
Sean Vig -
Show More
@@ -1,676 +1,679 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Top-level display functions for displaying object in different formats.
2 """Top-level display functions for displaying object in different formats.
3
3
4 Authors:
4 Authors:
5
5
6 * Brian Granger
6 * Brian Granger
7 """
7 """
8
8
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10 # Copyright (C) 2013 The IPython Development Team
10 # Copyright (C) 2013 The IPython Development Team
11 #
11 #
12 # Distributed under the terms of the BSD License. The full license is in
12 # Distributed under the terms of the BSD License. The full license is in
13 # the file COPYING, distributed as part of this software.
13 # the file COPYING, distributed as part of this software.
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15
15
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17 # Imports
17 # Imports
18 #-----------------------------------------------------------------------------
18 #-----------------------------------------------------------------------------
19
19
20 from __future__ import print_function
20 from __future__ import print_function
21
21
22 import os
22 import os
23 import struct
23 import struct
24
24
25 from IPython.utils.py3compat import (string_types, cast_bytes_py2, cast_unicode,
25 from IPython.utils.py3compat import (string_types, cast_bytes_py2, cast_unicode,
26 unicode_type)
26 unicode_type)
27
27
28 from .displaypub import publish_display_data
28 from .displaypub import publish_display_data
29
29
30 #-----------------------------------------------------------------------------
30 #-----------------------------------------------------------------------------
31 # utility functions
31 # utility functions
32 #-----------------------------------------------------------------------------
32 #-----------------------------------------------------------------------------
33
33
34 def _safe_exists(path):
34 def _safe_exists(path):
35 """Check path, but don't let exceptions raise"""
35 """Check path, but don't let exceptions raise"""
36 try:
36 try:
37 return os.path.exists(path)
37 return os.path.exists(path)
38 except Exception:
38 except Exception:
39 return False
39 return False
40
40
41 def _merge(d1, d2):
41 def _merge(d1, d2):
42 """Like update, but merges sub-dicts instead of clobbering at the top level.
42 """Like update, but merges sub-dicts instead of clobbering at the top level.
43
43
44 Updates d1 in-place
44 Updates d1 in-place
45 """
45 """
46
46
47 if not isinstance(d2, dict) or not isinstance(d1, dict):
47 if not isinstance(d2, dict) or not isinstance(d1, dict):
48 return d2
48 return d2
49 for key, value in d2.items():
49 for key, value in d2.items():
50 d1[key] = _merge(d1.get(key), value)
50 d1[key] = _merge(d1.get(key), value)
51 return d1
51 return d1
52
52
53 def _display_mimetype(mimetype, objs, raw=False, metadata=None):
53 def _display_mimetype(mimetype, objs, raw=False, metadata=None):
54 """internal implementation of all display_foo methods
54 """internal implementation of all display_foo methods
55
55
56 Parameters
56 Parameters
57 ----------
57 ----------
58 mimetype : str
58 mimetype : str
59 The mimetype to be published (e.g. 'image/png')
59 The mimetype to be published (e.g. 'image/png')
60 objs : tuple of objects
60 objs : tuple of objects
61 The Python objects to display, or if raw=True raw text data to
61 The Python objects to display, or if raw=True raw text data to
62 display.
62 display.
63 raw : bool
63 raw : bool
64 Are the data objects raw data or Python objects that need to be
64 Are the data objects raw data or Python objects that need to be
65 formatted before display? [default: False]
65 formatted before display? [default: False]
66 metadata : dict (optional)
66 metadata : dict (optional)
67 Metadata to be associated with the specific mimetype output.
67 Metadata to be associated with the specific mimetype output.
68 """
68 """
69 if metadata:
69 if metadata:
70 metadata = {mimetype: metadata}
70 metadata = {mimetype: metadata}
71 if raw:
71 if raw:
72 # turn list of pngdata into list of { 'image/png': pngdata }
72 # turn list of pngdata into list of { 'image/png': pngdata }
73 objs = [ {mimetype: obj} for obj in objs ]
73 objs = [ {mimetype: obj} for obj in objs ]
74 display(*objs, raw=raw, metadata=metadata, include=[mimetype])
74 display(*objs, raw=raw, metadata=metadata, include=[mimetype])
75
75
76 #-----------------------------------------------------------------------------
76 #-----------------------------------------------------------------------------
77 # Main functions
77 # Main functions
78 #-----------------------------------------------------------------------------
78 #-----------------------------------------------------------------------------
79
79
80 def display(*objs, **kwargs):
80 def display(*objs, **kwargs):
81 """Display a Python object in all frontends.
81 """Display a Python object in all frontends.
82
82
83 By default all representations will be computed and sent to the frontends.
83 By default all representations will be computed and sent to the frontends.
84 Frontends can decide which representation is used and how.
84 Frontends can decide which representation is used and how.
85
85
86 Parameters
86 Parameters
87 ----------
87 ----------
88 objs : tuple of objects
88 objs : tuple of objects
89 The Python objects to display.
89 The Python objects to display.
90 raw : bool, optional
90 raw : bool, optional
91 Are the objects to be displayed already mimetype-keyed dicts of raw display data,
91 Are the objects to be displayed already mimetype-keyed dicts of raw display data,
92 or Python objects that need to be formatted before display? [default: False]
92 or Python objects that need to be formatted before display? [default: False]
93 include : list or tuple, optional
93 include : list or tuple, optional
94 A list of format type strings (MIME types) to include in the
94 A list of format type strings (MIME types) to include in the
95 format data dict. If this is set *only* the format types included
95 format data dict. If this is set *only* the format types included
96 in this list will be computed.
96 in this list will be computed.
97 exclude : list or tuple, optional
97 exclude : list or tuple, optional
98 A list of format type strings (MIME types) to exclude in the format
98 A list of format type strings (MIME types) to exclude in the format
99 data dict. If this is set all format types will be computed,
99 data dict. If this is set all format types will be computed,
100 except for those included in this argument.
100 except for those included in this argument.
101 metadata : dict, optional
101 metadata : dict, optional
102 A dictionary of metadata to associate with the output.
102 A dictionary of metadata to associate with the output.
103 mime-type keys in this dictionary will be associated with the individual
103 mime-type keys in this dictionary will be associated with the individual
104 representation formats, if they exist.
104 representation formats, if they exist.
105 """
105 """
106 raw = kwargs.get('raw', False)
106 raw = kwargs.get('raw', False)
107 include = kwargs.get('include')
107 include = kwargs.get('include')
108 exclude = kwargs.get('exclude')
108 exclude = kwargs.get('exclude')
109 metadata = kwargs.get('metadata')
109 metadata = kwargs.get('metadata')
110
110
111 from IPython.core.interactiveshell import InteractiveShell
111 from IPython.core.interactiveshell import InteractiveShell
112
112
113 if raw:
113 if raw:
114 for obj in objs:
114 for obj in objs:
115 publish_display_data('display', obj, metadata)
115 publish_display_data('display', obj, metadata)
116 else:
116 else:
117 format = InteractiveShell.instance().display_formatter.format
117 format = InteractiveShell.instance().display_formatter.format
118 for obj in objs:
118 for obj in objs:
119 format_dict, md_dict = format(obj, include=include, exclude=exclude)
119 format_dict, md_dict = format(obj, include=include, exclude=exclude)
120 if metadata:
120 if metadata:
121 # kwarg-specified metadata gets precedence
121 # kwarg-specified metadata gets precedence
122 _merge(md_dict, metadata)
122 _merge(md_dict, metadata)
123 publish_display_data('display', format_dict, md_dict)
123 publish_display_data('display', format_dict, md_dict)
124
124
125
125
126 def display_pretty(*objs, **kwargs):
126 def display_pretty(*objs, **kwargs):
127 """Display the pretty (default) representation of an object.
127 """Display the pretty (default) representation of an object.
128
128
129 Parameters
129 Parameters
130 ----------
130 ----------
131 objs : tuple of objects
131 objs : tuple of objects
132 The Python objects to display, or if raw=True raw text data to
132 The Python objects to display, or if raw=True raw text data to
133 display.
133 display.
134 raw : bool
134 raw : bool
135 Are the data objects raw data or Python objects that need to be
135 Are the data objects raw data or Python objects that need to be
136 formatted before display? [default: False]
136 formatted before display? [default: False]
137 metadata : dict (optional)
137 metadata : dict (optional)
138 Metadata to be associated with the specific mimetype output.
138 Metadata to be associated with the specific mimetype output.
139 """
139 """
140 _display_mimetype('text/plain', objs, **kwargs)
140 _display_mimetype('text/plain', objs, **kwargs)
141
141
142
142
143 def display_html(*objs, **kwargs):
143 def display_html(*objs, **kwargs):
144 """Display the HTML representation of an object.
144 """Display the HTML representation of an object.
145
145
146 Parameters
146 Parameters
147 ----------
147 ----------
148 objs : tuple of objects
148 objs : tuple of objects
149 The Python objects to display, or if raw=True raw HTML data to
149 The Python objects to display, or if raw=True raw HTML data to
150 display.
150 display.
151 raw : bool
151 raw : bool
152 Are the data objects raw data or Python objects that need to be
152 Are the data objects raw data or Python objects that need to be
153 formatted before display? [default: False]
153 formatted before display? [default: False]
154 metadata : dict (optional)
154 metadata : dict (optional)
155 Metadata to be associated with the specific mimetype output.
155 Metadata to be associated with the specific mimetype output.
156 """
156 """
157 _display_mimetype('text/html', objs, **kwargs)
157 _display_mimetype('text/html', objs, **kwargs)
158
158
159
159
160 def display_svg(*objs, **kwargs):
160 def display_svg(*objs, **kwargs):
161 """Display the SVG representation of an object.
161 """Display the SVG representation of an object.
162
162
163 Parameters
163 Parameters
164 ----------
164 ----------
165 objs : tuple of objects
165 objs : tuple of objects
166 The Python objects to display, or if raw=True raw svg data to
166 The Python objects to display, or if raw=True raw svg data to
167 display.
167 display.
168 raw : bool
168 raw : bool
169 Are the data objects raw data or Python objects that need to be
169 Are the data objects raw data or Python objects that need to be
170 formatted before display? [default: False]
170 formatted before display? [default: False]
171 metadata : dict (optional)
171 metadata : dict (optional)
172 Metadata to be associated with the specific mimetype output.
172 Metadata to be associated with the specific mimetype output.
173 """
173 """
174 _display_mimetype('image/svg+xml', objs, **kwargs)
174 _display_mimetype('image/svg+xml', objs, **kwargs)
175
175
176
176
177 def display_png(*objs, **kwargs):
177 def display_png(*objs, **kwargs):
178 """Display the PNG representation of an object.
178 """Display the PNG representation of an object.
179
179
180 Parameters
180 Parameters
181 ----------
181 ----------
182 objs : tuple of objects
182 objs : tuple of objects
183 The Python objects to display, or if raw=True raw png data to
183 The Python objects to display, or if raw=True raw png data to
184 display.
184 display.
185 raw : bool
185 raw : bool
186 Are the data objects raw data or Python objects that need to be
186 Are the data objects raw data or Python objects that need to be
187 formatted before display? [default: False]
187 formatted before display? [default: False]
188 metadata : dict (optional)
188 metadata : dict (optional)
189 Metadata to be associated with the specific mimetype output.
189 Metadata to be associated with the specific mimetype output.
190 """
190 """
191 _display_mimetype('image/png', objs, **kwargs)
191 _display_mimetype('image/png', objs, **kwargs)
192
192
193
193
194 def display_jpeg(*objs, **kwargs):
194 def display_jpeg(*objs, **kwargs):
195 """Display the JPEG representation of an object.
195 """Display the JPEG representation of an object.
196
196
197 Parameters
197 Parameters
198 ----------
198 ----------
199 objs : tuple of objects
199 objs : tuple of objects
200 The Python objects to display, or if raw=True raw JPEG data to
200 The Python objects to display, or if raw=True raw JPEG data to
201 display.
201 display.
202 raw : bool
202 raw : bool
203 Are the data objects raw data or Python objects that need to be
203 Are the data objects raw data or Python objects that need to be
204 formatted before display? [default: False]
204 formatted before display? [default: False]
205 metadata : dict (optional)
205 metadata : dict (optional)
206 Metadata to be associated with the specific mimetype output.
206 Metadata to be associated with the specific mimetype output.
207 """
207 """
208 _display_mimetype('image/jpeg', objs, **kwargs)
208 _display_mimetype('image/jpeg', objs, **kwargs)
209
209
210
210
211 def display_latex(*objs, **kwargs):
211 def display_latex(*objs, **kwargs):
212 """Display the LaTeX representation of an object.
212 """Display the LaTeX representation of an object.
213
213
214 Parameters
214 Parameters
215 ----------
215 ----------
216 objs : tuple of objects
216 objs : tuple of objects
217 The Python objects to display, or if raw=True raw latex data to
217 The Python objects to display, or if raw=True raw latex data to
218 display.
218 display.
219 raw : bool
219 raw : bool
220 Are the data objects raw data or Python objects that need to be
220 Are the data objects raw data or Python objects that need to be
221 formatted before display? [default: False]
221 formatted before display? [default: False]
222 metadata : dict (optional)
222 metadata : dict (optional)
223 Metadata to be associated with the specific mimetype output.
223 Metadata to be associated with the specific mimetype output.
224 """
224 """
225 _display_mimetype('text/latex', objs, **kwargs)
225 _display_mimetype('text/latex', objs, **kwargs)
226
226
227
227
228 def display_json(*objs, **kwargs):
228 def display_json(*objs, **kwargs):
229 """Display the JSON representation of an object.
229 """Display the JSON representation of an object.
230
230
231 Note that not many frontends support displaying JSON.
231 Note that not many frontends support displaying JSON.
232
232
233 Parameters
233 Parameters
234 ----------
234 ----------
235 objs : tuple of objects
235 objs : tuple of objects
236 The Python objects to display, or if raw=True raw json data to
236 The Python objects to display, or if raw=True raw json data to
237 display.
237 display.
238 raw : bool
238 raw : bool
239 Are the data objects raw data or Python objects that need to be
239 Are the data objects raw data or Python objects that need to be
240 formatted before display? [default: False]
240 formatted before display? [default: False]
241 metadata : dict (optional)
241 metadata : dict (optional)
242 Metadata to be associated with the specific mimetype output.
242 Metadata to be associated with the specific mimetype output.
243 """
243 """
244 _display_mimetype('application/json', objs, **kwargs)
244 _display_mimetype('application/json', objs, **kwargs)
245
245
246
246
247 def display_javascript(*objs, **kwargs):
247 def display_javascript(*objs, **kwargs):
248 """Display the Javascript representation of an object.
248 """Display the Javascript representation of an object.
249
249
250 Parameters
250 Parameters
251 ----------
251 ----------
252 objs : tuple of objects
252 objs : tuple of objects
253 The Python objects to display, or if raw=True raw javascript data to
253 The Python objects to display, or if raw=True raw javascript data to
254 display.
254 display.
255 raw : bool
255 raw : bool
256 Are the data objects raw data or Python objects that need to be
256 Are the data objects raw data or Python objects that need to be
257 formatted before display? [default: False]
257 formatted before display? [default: False]
258 metadata : dict (optional)
258 metadata : dict (optional)
259 Metadata to be associated with the specific mimetype output.
259 Metadata to be associated with the specific mimetype output.
260 """
260 """
261 _display_mimetype('application/javascript', objs, **kwargs)
261 _display_mimetype('application/javascript', objs, **kwargs)
262
262
263 #-----------------------------------------------------------------------------
263 #-----------------------------------------------------------------------------
264 # Smart classes
264 # Smart classes
265 #-----------------------------------------------------------------------------
265 #-----------------------------------------------------------------------------
266
266
267
267
268 class DisplayObject(object):
268 class DisplayObject(object):
269 """An object that wraps data to be displayed."""
269 """An object that wraps data to be displayed."""
270
270
271 _read_flags = 'r'
271 _read_flags = 'r'
272
272
273 def __init__(self, data=None, url=None, filename=None):
273 def __init__(self, data=None, url=None, filename=None):
274 """Create a display object given raw data.
274 """Create a display object given raw data.
275
275
276 When this object is returned by an expression or passed to the
276 When this object is returned by an expression or passed to the
277 display function, it will result in the data being displayed
277 display function, it will result in the data being displayed
278 in the frontend. The MIME type of the data should match the
278 in the frontend. The MIME type of the data should match the
279 subclasses used, so the Png subclass should be used for 'image/png'
279 subclasses used, so the Png subclass should be used for 'image/png'
280 data. If the data is a URL, the data will first be downloaded
280 data. If the data is a URL, the data will first be downloaded
281 and then displayed. If
281 and then displayed. If
282
282
283 Parameters
283 Parameters
284 ----------
284 ----------
285 data : unicode, str or bytes
285 data : unicode, str or bytes
286 The raw data or a URL or file to load the data from
286 The raw data or a URL or file to load the data from
287 url : unicode
287 url : unicode
288 A URL to download the data from.
288 A URL to download the data from.
289 filename : unicode
289 filename : unicode
290 Path to a local file to load the data from.
290 Path to a local file to load the data from.
291 """
291 """
292 if data is not None and isinstance(data, string_types):
292 if data is not None and isinstance(data, string_types):
293 if data.startswith('http') and url is None:
293 if data.startswith('http') and url is None:
294 url = data
294 url = data
295 filename = None
295 filename = None
296 data = None
296 data = None
297 elif _safe_exists(data) and filename is None:
297 elif _safe_exists(data) and filename is None:
298 url = None
298 url = None
299 filename = data
299 filename = data
300 data = None
300 data = None
301
301
302 self.data = data
302 self.data = data
303 self.url = url
303 self.url = url
304 self.filename = None if filename is None else unicode_type(filename)
304 self.filename = None if filename is None else unicode_type(filename)
305
305
306 self.reload()
306 self.reload()
307
307
308 def reload(self):
308 def reload(self):
309 """Reload the raw data from file or URL."""
309 """Reload the raw data from file or URL."""
310 if self.filename is not None:
310 if self.filename is not None:
311 with open(self.filename, self._read_flags) as f:
311 with open(self.filename, self._read_flags) as f:
312 self.data = f.read()
312 self.data = f.read()
313 elif self.url is not None:
313 elif self.url is not None:
314 try:
314 try:
315 import urllib2
315 try:
316 response = urllib2.urlopen(self.url)
316 from urllib.request import urlopen # Py3
317 except ImportError:
318 from urllib2 import urlopen
319 response = urlopen(self.url)
317 self.data = response.read()
320 self.data = response.read()
318 # extract encoding from header, if there is one:
321 # extract encoding from header, if there is one:
319 encoding = None
322 encoding = None
320 for sub in response.headers['content-type'].split(';'):
323 for sub in response.headers['content-type'].split(';'):
321 sub = sub.strip()
324 sub = sub.strip()
322 if sub.startswith('charset'):
325 if sub.startswith('charset'):
323 encoding = sub.split('=')[-1].strip()
326 encoding = sub.split('=')[-1].strip()
324 break
327 break
325 # decode data, if an encoding was specified
328 # decode data, if an encoding was specified
326 if encoding:
329 if encoding:
327 self.data = self.data.decode(encoding, 'replace')
330 self.data = self.data.decode(encoding, 'replace')
328 except:
331 except:
329 self.data = None
332 self.data = None
330
333
331 class Pretty(DisplayObject):
334 class Pretty(DisplayObject):
332
335
333 def _repr_pretty_(self):
336 def _repr_pretty_(self):
334 return self.data
337 return self.data
335
338
336
339
337 class HTML(DisplayObject):
340 class HTML(DisplayObject):
338
341
339 def _repr_html_(self):
342 def _repr_html_(self):
340 return self.data
343 return self.data
341
344
342 def __html__(self):
345 def __html__(self):
343 """
346 """
344 This method exists to inform other HTML-using modules (e.g. Markupsafe,
347 This method exists to inform other HTML-using modules (e.g. Markupsafe,
345 htmltag, etc) that this object is HTML and does not need things like
348 htmltag, etc) that this object is HTML and does not need things like
346 special characters (<>&) escaped.
349 special characters (<>&) escaped.
347 """
350 """
348 return self._repr_html_()
351 return self._repr_html_()
349
352
350
353
351 class Math(DisplayObject):
354 class Math(DisplayObject):
352
355
353 def _repr_latex_(self):
356 def _repr_latex_(self):
354 s = self.data.strip('$')
357 s = self.data.strip('$')
355 return "$$%s$$" % s
358 return "$$%s$$" % s
356
359
357
360
358 class Latex(DisplayObject):
361 class Latex(DisplayObject):
359
362
360 def _repr_latex_(self):
363 def _repr_latex_(self):
361 return self.data
364 return self.data
362
365
363
366
364 class SVG(DisplayObject):
367 class SVG(DisplayObject):
365
368
366 # wrap data in a property, which extracts the <svg> tag, discarding
369 # wrap data in a property, which extracts the <svg> tag, discarding
367 # document headers
370 # document headers
368 _data = None
371 _data = None
369
372
370 @property
373 @property
371 def data(self):
374 def data(self):
372 return self._data
375 return self._data
373
376
374 @data.setter
377 @data.setter
375 def data(self, svg):
378 def data(self, svg):
376 if svg is None:
379 if svg is None:
377 self._data = None
380 self._data = None
378 return
381 return
379 # parse into dom object
382 # parse into dom object
380 from xml.dom import minidom
383 from xml.dom import minidom
381 svg = cast_bytes_py2(svg)
384 svg = cast_bytes_py2(svg)
382 x = minidom.parseString(svg)
385 x = minidom.parseString(svg)
383 # get svg tag (should be 1)
386 # get svg tag (should be 1)
384 found_svg = x.getElementsByTagName('svg')
387 found_svg = x.getElementsByTagName('svg')
385 if found_svg:
388 if found_svg:
386 svg = found_svg[0].toxml()
389 svg = found_svg[0].toxml()
387 else:
390 else:
388 # fallback on the input, trust the user
391 # fallback on the input, trust the user
389 # but this is probably an error.
392 # but this is probably an error.
390 pass
393 pass
391 svg = cast_unicode(svg)
394 svg = cast_unicode(svg)
392 self._data = svg
395 self._data = svg
393
396
394 def _repr_svg_(self):
397 def _repr_svg_(self):
395 return self.data
398 return self.data
396
399
397
400
398 class JSON(DisplayObject):
401 class JSON(DisplayObject):
399
402
400 def _repr_json_(self):
403 def _repr_json_(self):
401 return self.data
404 return self.data
402
405
403 css_t = """$("head").append($("<link/>").attr({
406 css_t = """$("head").append($("<link/>").attr({
404 rel: "stylesheet",
407 rel: "stylesheet",
405 type: "text/css",
408 type: "text/css",
406 href: "%s"
409 href: "%s"
407 }));
410 }));
408 """
411 """
409
412
410 lib_t1 = """$.getScript("%s", function () {
413 lib_t1 = """$.getScript("%s", function () {
411 """
414 """
412 lib_t2 = """});
415 lib_t2 = """});
413 """
416 """
414
417
415 class Javascript(DisplayObject):
418 class Javascript(DisplayObject):
416
419
417 def __init__(self, data=None, url=None, filename=None, lib=None, css=None):
420 def __init__(self, data=None, url=None, filename=None, lib=None, css=None):
418 """Create a Javascript display object given raw data.
421 """Create a Javascript display object given raw data.
419
422
420 When this object is returned by an expression or passed to the
423 When this object is returned by an expression or passed to the
421 display function, it will result in the data being displayed
424 display function, it will result in the data being displayed
422 in the frontend. If the data is a URL, the data will first be
425 in the frontend. If the data is a URL, the data will first be
423 downloaded and then displayed.
426 downloaded and then displayed.
424
427
425 In the Notebook, the containing element will be available as `element`,
428 In the Notebook, the containing element will be available as `element`,
426 and jQuery will be available. The output area starts hidden, so if
429 and jQuery will be available. The output area starts hidden, so if
427 the js appends content to `element` that should be visible, then
430 the js appends content to `element` that should be visible, then
428 it must call `container.show()` to unhide the area.
431 it must call `container.show()` to unhide the area.
429
432
430 Parameters
433 Parameters
431 ----------
434 ----------
432 data : unicode, str or bytes
435 data : unicode, str or bytes
433 The Javascript source code or a URL to download it from.
436 The Javascript source code or a URL to download it from.
434 url : unicode
437 url : unicode
435 A URL to download the data from.
438 A URL to download the data from.
436 filename : unicode
439 filename : unicode
437 Path to a local file to load the data from.
440 Path to a local file to load the data from.
438 lib : list or str
441 lib : list or str
439 A sequence of Javascript library URLs to load asynchronously before
442 A sequence of Javascript library URLs to load asynchronously before
440 running the source code. The full URLs of the libraries should
443 running the source code. The full URLs of the libraries should
441 be given. A single Javascript library URL can also be given as a
444 be given. A single Javascript library URL can also be given as a
442 string.
445 string.
443 css: : list or str
446 css: : list or str
444 A sequence of css files to load before running the source code.
447 A sequence of css files to load before running the source code.
445 The full URLs of the css files should be given. A single css URL
448 The full URLs of the css files should be given. A single css URL
446 can also be given as a string.
449 can also be given as a string.
447 """
450 """
448 if isinstance(lib, string_types):
451 if isinstance(lib, string_types):
449 lib = [lib]
452 lib = [lib]
450 elif lib is None:
453 elif lib is None:
451 lib = []
454 lib = []
452 if isinstance(css, string_types):
455 if isinstance(css, string_types):
453 css = [css]
456 css = [css]
454 elif css is None:
457 elif css is None:
455 css = []
458 css = []
456 if not isinstance(lib, (list,tuple)):
459 if not isinstance(lib, (list,tuple)):
457 raise TypeError('expected sequence, got: %r' % lib)
460 raise TypeError('expected sequence, got: %r' % lib)
458 if not isinstance(css, (list,tuple)):
461 if not isinstance(css, (list,tuple)):
459 raise TypeError('expected sequence, got: %r' % css)
462 raise TypeError('expected sequence, got: %r' % css)
460 self.lib = lib
463 self.lib = lib
461 self.css = css
464 self.css = css
462 super(Javascript, self).__init__(data=data, url=url, filename=filename)
465 super(Javascript, self).__init__(data=data, url=url, filename=filename)
463
466
464 def _repr_javascript_(self):
467 def _repr_javascript_(self):
465 r = ''
468 r = ''
466 for c in self.css:
469 for c in self.css:
467 r += css_t % c
470 r += css_t % c
468 for l in self.lib:
471 for l in self.lib:
469 r += lib_t1 % l
472 r += lib_t1 % l
470 r += self.data
473 r += self.data
471 r += lib_t2*len(self.lib)
474 r += lib_t2*len(self.lib)
472 return r
475 return r
473
476
474 # constants for identifying png/jpeg data
477 # constants for identifying png/jpeg data
475 _PNG = b'\x89PNG\r\n\x1a\n'
478 _PNG = b'\x89PNG\r\n\x1a\n'
476 _JPEG = b'\xff\xd8'
479 _JPEG = b'\xff\xd8'
477
480
478 def _pngxy(data):
481 def _pngxy(data):
479 """read the (width, height) from a PNG header"""
482 """read the (width, height) from a PNG header"""
480 ihdr = data.index(b'IHDR')
483 ihdr = data.index(b'IHDR')
481 # next 8 bytes are width/height
484 # next 8 bytes are width/height
482 w4h4 = data[ihdr+4:ihdr+12]
485 w4h4 = data[ihdr+4:ihdr+12]
483 return struct.unpack('>ii', w4h4)
486 return struct.unpack('>ii', w4h4)
484
487
485 def _jpegxy(data):
488 def _jpegxy(data):
486 """read the (width, height) from a JPEG header"""
489 """read the (width, height) from a JPEG header"""
487 # adapted from http://www.64lines.com/jpeg-width-height
490 # adapted from http://www.64lines.com/jpeg-width-height
488
491
489 idx = 4
492 idx = 4
490 while True:
493 while True:
491 block_size = struct.unpack('>H', data[idx:idx+2])[0]
494 block_size = struct.unpack('>H', data[idx:idx+2])[0]
492 idx = idx + block_size
495 idx = idx + block_size
493 if data[idx:idx+2] == b'\xFF\xC0':
496 if data[idx:idx+2] == b'\xFF\xC0':
494 # found Start of Frame
497 # found Start of Frame
495 iSOF = idx
498 iSOF = idx
496 break
499 break
497 else:
500 else:
498 # read another block
501 # read another block
499 idx += 2
502 idx += 2
500
503
501 h, w = struct.unpack('>HH', data[iSOF+5:iSOF+9])
504 h, w = struct.unpack('>HH', data[iSOF+5:iSOF+9])
502 return w, h
505 return w, h
503
506
504 class Image(DisplayObject):
507 class Image(DisplayObject):
505
508
506 _read_flags = 'rb'
509 _read_flags = 'rb'
507 _FMT_JPEG = u'jpeg'
510 _FMT_JPEG = u'jpeg'
508 _FMT_PNG = u'png'
511 _FMT_PNG = u'png'
509 _ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG]
512 _ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG]
510
513
511 def __init__(self, data=None, url=None, filename=None, format=u'png', embed=None, width=None, height=None, retina=False):
514 def __init__(self, data=None, url=None, filename=None, format=u'png', embed=None, width=None, height=None, retina=False):
512 """Create a PNG/JPEG image object given raw data.
515 """Create a PNG/JPEG image object given raw data.
513
516
514 When this object is returned by an input cell or passed to the
517 When this object is returned by an input cell or passed to the
515 display function, it will result in the image being displayed
518 display function, it will result in the image being displayed
516 in the frontend.
519 in the frontend.
517
520
518 Parameters
521 Parameters
519 ----------
522 ----------
520 data : unicode, str or bytes
523 data : unicode, str or bytes
521 The raw image data or a URL or filename to load the data from.
524 The raw image data or a URL or filename to load the data from.
522 This always results in embedded image data.
525 This always results in embedded image data.
523 url : unicode
526 url : unicode
524 A URL to download the data from. If you specify `url=`,
527 A URL to download the data from. If you specify `url=`,
525 the image data will not be embedded unless you also specify `embed=True`.
528 the image data will not be embedded unless you also specify `embed=True`.
526 filename : unicode
529 filename : unicode
527 Path to a local file to load the data from.
530 Path to a local file to load the data from.
528 Images from a file are always embedded.
531 Images from a file are always embedded.
529 format : unicode
532 format : unicode
530 The format of the image data (png/jpeg/jpg). If a filename or URL is given
533 The format of the image data (png/jpeg/jpg). If a filename or URL is given
531 for format will be inferred from the filename extension.
534 for format will be inferred from the filename extension.
532 embed : bool
535 embed : bool
533 Should the image data be embedded using a data URI (True) or be
536 Should the image data be embedded using a data URI (True) or be
534 loaded using an <img> tag. Set this to True if you want the image
537 loaded using an <img> tag. Set this to True if you want the image
535 to be viewable later with no internet connection in the notebook.
538 to be viewable later with no internet connection in the notebook.
536
539
537 Default is `True`, unless the keyword argument `url` is set, then
540 Default is `True`, unless the keyword argument `url` is set, then
538 default value is `False`.
541 default value is `False`.
539
542
540 Note that QtConsole is not able to display images if `embed` is set to `False`
543 Note that QtConsole is not able to display images if `embed` is set to `False`
541 width : int
544 width : int
542 Width to which to constrain the image in html
545 Width to which to constrain the image in html
543 height : int
546 height : int
544 Height to which to constrain the image in html
547 Height to which to constrain the image in html
545 retina : bool
548 retina : bool
546 Automatically set the width and height to half of the measured
549 Automatically set the width and height to half of the measured
547 width and height.
550 width and height.
548 This only works for embedded images because it reads the width/height
551 This only works for embedded images because it reads the width/height
549 from image data.
552 from image data.
550 For non-embedded images, you can just set the desired display width
553 For non-embedded images, you can just set the desired display width
551 and height directly.
554 and height directly.
552
555
553 Examples
556 Examples
554 --------
557 --------
555 # embedded image data, works in qtconsole and notebook
558 # embedded image data, works in qtconsole and notebook
556 # when passed positionally, the first arg can be any of raw image data,
559 # when passed positionally, the first arg can be any of raw image data,
557 # a URL, or a filename from which to load image data.
560 # a URL, or a filename from which to load image data.
558 # The result is always embedding image data for inline images.
561 # The result is always embedding image data for inline images.
559 Image('http://www.google.fr/images/srpr/logo3w.png')
562 Image('http://www.google.fr/images/srpr/logo3w.png')
560 Image('/path/to/image.jpg')
563 Image('/path/to/image.jpg')
561 Image(b'RAW_PNG_DATA...')
564 Image(b'RAW_PNG_DATA...')
562
565
563 # Specifying Image(url=...) does not embed the image data,
566 # Specifying Image(url=...) does not embed the image data,
564 # it only generates `<img>` tag with a link to the source.
567 # it only generates `<img>` tag with a link to the source.
565 # This will not work in the qtconsole or offline.
568 # This will not work in the qtconsole or offline.
566 Image(url='http://www.google.fr/images/srpr/logo3w.png')
569 Image(url='http://www.google.fr/images/srpr/logo3w.png')
567
570
568 """
571 """
569 if filename is not None:
572 if filename is not None:
570 ext = self._find_ext(filename)
573 ext = self._find_ext(filename)
571 elif url is not None:
574 elif url is not None:
572 ext = self._find_ext(url)
575 ext = self._find_ext(url)
573 elif data is None:
576 elif data is None:
574 raise ValueError("No image data found. Expecting filename, url, or data.")
577 raise ValueError("No image data found. Expecting filename, url, or data.")
575 elif isinstance(data, string_types) and (
578 elif isinstance(data, string_types) and (
576 data.startswith('http') or _safe_exists(data)
579 data.startswith('http') or _safe_exists(data)
577 ):
580 ):
578 ext = self._find_ext(data)
581 ext = self._find_ext(data)
579 else:
582 else:
580 ext = None
583 ext = None
581
584
582 if ext is not None:
585 if ext is not None:
583 format = ext.lower()
586 format = ext.lower()
584 if ext == u'jpg' or ext == u'jpeg':
587 if ext == u'jpg' or ext == u'jpeg':
585 format = self._FMT_JPEG
588 format = self._FMT_JPEG
586 if ext == u'png':
589 if ext == u'png':
587 format = self._FMT_PNG
590 format = self._FMT_PNG
588 elif isinstance(data, bytes) and format == 'png':
591 elif isinstance(data, bytes) and format == 'png':
589 # infer image type from image data header,
592 # infer image type from image data header,
590 # only if format might not have been specified.
593 # only if format might not have been specified.
591 if data[:2] == _JPEG:
594 if data[:2] == _JPEG:
592 format = 'jpeg'
595 format = 'jpeg'
593
596
594 self.format = unicode_type(format).lower()
597 self.format = unicode_type(format).lower()
595 self.embed = embed if embed is not None else (url is None)
598 self.embed = embed if embed is not None else (url is None)
596
599
597 if self.embed and self.format not in self._ACCEPTABLE_EMBEDDINGS:
600 if self.embed and self.format not in self._ACCEPTABLE_EMBEDDINGS:
598 raise ValueError("Cannot embed the '%s' image format" % (self.format))
601 raise ValueError("Cannot embed the '%s' image format" % (self.format))
599 self.width = width
602 self.width = width
600 self.height = height
603 self.height = height
601 self.retina = retina
604 self.retina = retina
602 super(Image, self).__init__(data=data, url=url, filename=filename)
605 super(Image, self).__init__(data=data, url=url, filename=filename)
603
606
604 if retina:
607 if retina:
605 self._retina_shape()
608 self._retina_shape()
606
609
607 def _retina_shape(self):
610 def _retina_shape(self):
608 """load pixel-doubled width and height from image data"""
611 """load pixel-doubled width and height from image data"""
609 if not self.embed:
612 if not self.embed:
610 return
613 return
611 if self.format == 'png':
614 if self.format == 'png':
612 w, h = _pngxy(self.data)
615 w, h = _pngxy(self.data)
613 elif self.format == 'jpeg':
616 elif self.format == 'jpeg':
614 w, h = _jpegxy(self.data)
617 w, h = _jpegxy(self.data)
615 else:
618 else:
616 # retina only supports png
619 # retina only supports png
617 return
620 return
618 self.width = w // 2
621 self.width = w // 2
619 self.height = h // 2
622 self.height = h // 2
620
623
621 def reload(self):
624 def reload(self):
622 """Reload the raw data from file or URL."""
625 """Reload the raw data from file or URL."""
623 if self.embed:
626 if self.embed:
624 super(Image,self).reload()
627 super(Image,self).reload()
625 if self.retina:
628 if self.retina:
626 self._retina_shape()
629 self._retina_shape()
627
630
628 def _repr_html_(self):
631 def _repr_html_(self):
629 if not self.embed:
632 if not self.embed:
630 width = height = ''
633 width = height = ''
631 if self.width:
634 if self.width:
632 width = ' width="%d"' % self.width
635 width = ' width="%d"' % self.width
633 if self.height:
636 if self.height:
634 height = ' height="%d"' % self.height
637 height = ' height="%d"' % self.height
635 return u'<img src="%s"%s%s/>' % (self.url, width, height)
638 return u'<img src="%s"%s%s/>' % (self.url, width, height)
636
639
637 def _data_and_metadata(self):
640 def _data_and_metadata(self):
638 """shortcut for returning metadata with shape information, if defined"""
641 """shortcut for returning metadata with shape information, if defined"""
639 md = {}
642 md = {}
640 if self.width:
643 if self.width:
641 md['width'] = self.width
644 md['width'] = self.width
642 if self.height:
645 if self.height:
643 md['height'] = self.height
646 md['height'] = self.height
644 if md:
647 if md:
645 return self.data, md
648 return self.data, md
646 else:
649 else:
647 return self.data
650 return self.data
648
651
649 def _repr_png_(self):
652 def _repr_png_(self):
650 if self.embed and self.format == u'png':
653 if self.embed and self.format == u'png':
651 return self._data_and_metadata()
654 return self._data_and_metadata()
652
655
653 def _repr_jpeg_(self):
656 def _repr_jpeg_(self):
654 if self.embed and (self.format == u'jpeg' or self.format == u'jpg'):
657 if self.embed and (self.format == u'jpeg' or self.format == u'jpg'):
655 return self._data_and_metadata()
658 return self._data_and_metadata()
656
659
657 def _find_ext(self, s):
660 def _find_ext(self, s):
658 return unicode_type(s.split('.')[-1].lower())
661 return unicode_type(s.split('.')[-1].lower())
659
662
660
663
661 def clear_output(wait=False):
664 def clear_output(wait=False):
662 """Clear the output of the current cell receiving output.
665 """Clear the output of the current cell receiving output.
663
666
664 Parameters
667 Parameters
665 ----------
668 ----------
666 wait : bool [default: false]
669 wait : bool [default: false]
667 Wait to clear the output until new output is available to replace it."""
670 Wait to clear the output until new output is available to replace it."""
668 from IPython.core.interactiveshell import InteractiveShell
671 from IPython.core.interactiveshell import InteractiveShell
669 if InteractiveShell.initialized():
672 if InteractiveShell.initialized():
670 InteractiveShell.instance().display_pub.clear_output(wait)
673 InteractiveShell.instance().display_pub.clear_output(wait)
671 else:
674 else:
672 from IPython.utils import io
675 from IPython.utils import io
673 print('\033[2K\r', file=io.stdout, end='')
676 print('\033[2K\r', file=io.stdout, end='')
674 io.stdout.flush()
677 io.stdout.flush()
675 print('\033[2K\r', file=io.stderr, end='')
678 print('\033[2K\r', file=io.stderr, end='')
676 io.stderr.flush()
679 io.stderr.flush()
@@ -1,187 +1,189 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """A class for managing IPython extensions.
2 """A class for managing IPython extensions.
3
3
4 Authors:
4 Authors:
5
5
6 * Brian Granger
6 * Brian Granger
7 """
7 """
8
8
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10 # Copyright (C) 2010-2011 The IPython Development Team
10 # Copyright (C) 2010-2011 The IPython Development Team
11 #
11 #
12 # Distributed under the terms of the BSD License. The full license is in
12 # Distributed under the terms of the BSD License. The full license is in
13 # the file COPYING, distributed as part of this software.
13 # the file COPYING, distributed as part of this software.
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15
15
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17 # Imports
17 # Imports
18 #-----------------------------------------------------------------------------
18 #-----------------------------------------------------------------------------
19
19
20 import os
20 import os
21 from shutil import copyfile
21 from shutil import copyfile
22 import sys
22 import sys
23
23
24 from IPython.config.configurable import Configurable
24 from IPython.config.configurable import Configurable
25 from IPython.utils.traitlets import Instance
25 from IPython.utils.traitlets import Instance
26 from IPython.utils.py3compat import PY3
26 from IPython.utils.py3compat import PY3
27 if PY3:
27 if PY3:
28 from imp import reload
28 from imp import reload
29
29
30 #-----------------------------------------------------------------------------
30 #-----------------------------------------------------------------------------
31 # Main class
31 # Main class
32 #-----------------------------------------------------------------------------
32 #-----------------------------------------------------------------------------
33
33
34 class ExtensionManager(Configurable):
34 class ExtensionManager(Configurable):
35 """A class to manage IPython extensions.
35 """A class to manage IPython extensions.
36
36
37 An IPython extension is an importable Python module that has
37 An IPython extension is an importable Python module that has
38 a function with the signature::
38 a function with the signature::
39
39
40 def load_ipython_extension(ipython):
40 def load_ipython_extension(ipython):
41 # Do things with ipython
41 # Do things with ipython
42
42
43 This function is called after your extension is imported and the
43 This function is called after your extension is imported and the
44 currently active :class:`InteractiveShell` instance is passed as
44 currently active :class:`InteractiveShell` instance is passed as
45 the only argument. You can do anything you want with IPython at
45 the only argument. You can do anything you want with IPython at
46 that point, including defining new magic and aliases, adding new
46 that point, including defining new magic and aliases, adding new
47 components, etc.
47 components, etc.
48
48
49 You can also optionally define an :func:`unload_ipython_extension(ipython)`
49 You can also optionally define an :func:`unload_ipython_extension(ipython)`
50 function, which will be called if the user unloads or reloads the extension.
50 function, which will be called if the user unloads or reloads the extension.
51 The extension manager will only call :func:`load_ipython_extension` again
51 The extension manager will only call :func:`load_ipython_extension` again
52 if the extension is reloaded.
52 if the extension is reloaded.
53
53
54 You can put your extension modules anywhere you want, as long as
54 You can put your extension modules anywhere you want, as long as
55 they can be imported by Python's standard import mechanism. However,
55 they can be imported by Python's standard import mechanism. However,
56 to make it easy to write extensions, you can also put your extensions
56 to make it easy to write extensions, you can also put your extensions
57 in ``os.path.join(self.ipython_dir, 'extensions')``. This directory
57 in ``os.path.join(self.ipython_dir, 'extensions')``. This directory
58 is added to ``sys.path`` automatically.
58 is added to ``sys.path`` automatically.
59 """
59 """
60
60
61 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
61 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
62
62
63 def __init__(self, shell=None, **kwargs):
63 def __init__(self, shell=None, **kwargs):
64 super(ExtensionManager, self).__init__(shell=shell, **kwargs)
64 super(ExtensionManager, self).__init__(shell=shell, **kwargs)
65 self.shell.on_trait_change(
65 self.shell.on_trait_change(
66 self._on_ipython_dir_changed, 'ipython_dir'
66 self._on_ipython_dir_changed, 'ipython_dir'
67 )
67 )
68 self.loaded = set()
68 self.loaded = set()
69
69
70 def __del__(self):
70 def __del__(self):
71 self.shell.on_trait_change(
71 self.shell.on_trait_change(
72 self._on_ipython_dir_changed, 'ipython_dir', remove=True
72 self._on_ipython_dir_changed, 'ipython_dir', remove=True
73 )
73 )
74
74
75 @property
75 @property
76 def ipython_extension_dir(self):
76 def ipython_extension_dir(self):
77 return os.path.join(self.shell.ipython_dir, u'extensions')
77 return os.path.join(self.shell.ipython_dir, u'extensions')
78
78
79 def _on_ipython_dir_changed(self):
79 def _on_ipython_dir_changed(self):
80 if not os.path.isdir(self.ipython_extension_dir):
80 if not os.path.isdir(self.ipython_extension_dir):
81 os.makedirs(self.ipython_extension_dir, mode = 0o777)
81 os.makedirs(self.ipython_extension_dir, mode = 0o777)
82
82
83 def load_extension(self, module_str):
83 def load_extension(self, module_str):
84 """Load an IPython extension by its module name.
84 """Load an IPython extension by its module name.
85
85
86 Returns the string "already loaded" if the extension is already loaded,
86 Returns the string "already loaded" if the extension is already loaded,
87 "no load function" if the module doesn't have a load_ipython_extension
87 "no load function" if the module doesn't have a load_ipython_extension
88 function, or None if it succeeded.
88 function, or None if it succeeded.
89 """
89 """
90 if module_str in self.loaded:
90 if module_str in self.loaded:
91 return "already loaded"
91 return "already loaded"
92
92
93 from IPython.utils.syspathcontext import prepended_to_syspath
93 from IPython.utils.syspathcontext import prepended_to_syspath
94
94
95 with self.shell.builtin_trap:
95 with self.shell.builtin_trap:
96 if module_str not in sys.modules:
96 if module_str not in sys.modules:
97 with prepended_to_syspath(self.ipython_extension_dir):
97 with prepended_to_syspath(self.ipython_extension_dir):
98 __import__(module_str)
98 __import__(module_str)
99 mod = sys.modules[module_str]
99 mod = sys.modules[module_str]
100 if self._call_load_ipython_extension(mod):
100 if self._call_load_ipython_extension(mod):
101 self.loaded.add(module_str)
101 self.loaded.add(module_str)
102 else:
102 else:
103 return "no load function"
103 return "no load function"
104
104
105 def unload_extension(self, module_str):
105 def unload_extension(self, module_str):
106 """Unload an IPython extension by its module name.
106 """Unload an IPython extension by its module name.
107
107
108 This function looks up the extension's name in ``sys.modules`` and
108 This function looks up the extension's name in ``sys.modules`` and
109 simply calls ``mod.unload_ipython_extension(self)``.
109 simply calls ``mod.unload_ipython_extension(self)``.
110
110
111 Returns the string "no unload function" if the extension doesn't define
111 Returns the string "no unload function" if the extension doesn't define
112 a function to unload itself, "not loaded" if the extension isn't loaded,
112 a function to unload itself, "not loaded" if the extension isn't loaded,
113 otherwise None.
113 otherwise None.
114 """
114 """
115 if module_str not in self.loaded:
115 if module_str not in self.loaded:
116 return "not loaded"
116 return "not loaded"
117
117
118 if module_str in sys.modules:
118 if module_str in sys.modules:
119 mod = sys.modules[module_str]
119 mod = sys.modules[module_str]
120 if self._call_unload_ipython_extension(mod):
120 if self._call_unload_ipython_extension(mod):
121 self.loaded.discard(module_str)
121 self.loaded.discard(module_str)
122 else:
122 else:
123 return "no unload function"
123 return "no unload function"
124
124
125 def reload_extension(self, module_str):
125 def reload_extension(self, module_str):
126 """Reload an IPython extension by calling reload.
126 """Reload an IPython extension by calling reload.
127
127
128 If the module has not been loaded before,
128 If the module has not been loaded before,
129 :meth:`InteractiveShell.load_extension` is called. Otherwise
129 :meth:`InteractiveShell.load_extension` is called. Otherwise
130 :func:`reload` is called and then the :func:`load_ipython_extension`
130 :func:`reload` is called and then the :func:`load_ipython_extension`
131 function of the module, if it exists is called.
131 function of the module, if it exists is called.
132 """
132 """
133 from IPython.utils.syspathcontext import prepended_to_syspath
133 from IPython.utils.syspathcontext import prepended_to_syspath
134
134
135 if (module_str in self.loaded) and (module_str in sys.modules):
135 if (module_str in self.loaded) and (module_str in sys.modules):
136 self.unload_extension(module_str)
136 self.unload_extension(module_str)
137 mod = sys.modules[module_str]
137 mod = sys.modules[module_str]
138 with prepended_to_syspath(self.ipython_extension_dir):
138 with prepended_to_syspath(self.ipython_extension_dir):
139 reload(mod)
139 reload(mod)
140 if self._call_load_ipython_extension(mod):
140 if self._call_load_ipython_extension(mod):
141 self.loaded.add(module_str)
141 self.loaded.add(module_str)
142 else:
142 else:
143 self.load_extension(module_str)
143 self.load_extension(module_str)
144
144
145 def _call_load_ipython_extension(self, mod):
145 def _call_load_ipython_extension(self, mod):
146 if hasattr(mod, 'load_ipython_extension'):
146 if hasattr(mod, 'load_ipython_extension'):
147 mod.load_ipython_extension(self.shell)
147 mod.load_ipython_extension(self.shell)
148 return True
148 return True
149
149
150 def _call_unload_ipython_extension(self, mod):
150 def _call_unload_ipython_extension(self, mod):
151 if hasattr(mod, 'unload_ipython_extension'):
151 if hasattr(mod, 'unload_ipython_extension'):
152 mod.unload_ipython_extension(self.shell)
152 mod.unload_ipython_extension(self.shell)
153 return True
153 return True
154
154
155 def install_extension(self, url, filename=None):
155 def install_extension(self, url, filename=None):
156 """Download and install an IPython extension.
156 """Download and install an IPython extension.
157
157
158 If filename is given, the file will be so named (inside the extension
158 If filename is given, the file will be so named (inside the extension
159 directory). Otherwise, the name from the URL will be used. The file must
159 directory). Otherwise, the name from the URL will be used. The file must
160 have a .py or .zip extension; otherwise, a ValueError will be raised.
160 have a .py or .zip extension; otherwise, a ValueError will be raised.
161
161
162 Returns the full path to the installed file.
162 Returns the full path to the installed file.
163 """
163 """
164 # Ensure the extension directory exists
164 # Ensure the extension directory exists
165 if not os.path.isdir(self.ipython_extension_dir):
165 if not os.path.isdir(self.ipython_extension_dir):
166 os.makedirs(self.ipython_extension_dir, mode = 0o777)
166 os.makedirs(self.ipython_extension_dir, mode = 0o777)
167
167
168 if os.path.isfile(url):
168 if os.path.isfile(url):
169 src_filename = os.path.basename(url)
169 src_filename = os.path.basename(url)
170 copy = copyfile
170 copy = copyfile
171 else:
171 else:
172 from urllib import urlretrieve # Deferred imports
172 # Deferred imports
173 try:
173 try:
174 from urllib.parse import urlparse # Py3
174 from urllib.parse import urlparse # Py3
175 from urllib.request import urlretrieve
175 except ImportError:
176 except ImportError:
176 from urlparse import urlparse
177 from urlparse import urlparse
178 from urllib import urlretrieve
177 src_filename = urlparse(url).path.split('/')[-1]
179 src_filename = urlparse(url).path.split('/')[-1]
178 copy = urlretrieve
180 copy = urlretrieve
179
181
180 if filename is None:
182 if filename is None:
181 filename = src_filename
183 filename = src_filename
182 if os.path.splitext(filename)[1] not in ('.py', '.zip'):
184 if os.path.splitext(filename)[1] not in ('.py', '.zip'):
183 raise ValueError("The file must have a .py or .zip extension", filename)
185 raise ValueError("The file must have a .py or .zip extension", filename)
184
186
185 filename = os.path.join(self.ipython_extension_dir, filename)
187 filename = os.path.join(self.ipython_extension_dir, filename)
186 copy(url, filename)
188 copy(url, filename)
187 return filename
189 return filename
@@ -1,3166 +1,3170 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Main IPython class."""
2 """Main IPython class."""
3
3
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 # Copyright (C) 2008-2011 The IPython Development Team
7 # Copyright (C) 2008-2011 The IPython Development Team
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import absolute_import
17 from __future__ import absolute_import
18 from __future__ import print_function
18 from __future__ import print_function
19
19
20 import __future__
20 import __future__
21 import abc
21 import abc
22 import ast
22 import ast
23 import atexit
23 import atexit
24 import functools
24 import functools
25 import os
25 import os
26 import re
26 import re
27 import runpy
27 import runpy
28 import sys
28 import sys
29 import tempfile
29 import tempfile
30 import types
30 import types
31 import subprocess
31 import subprocess
32 from io import open as io_open
32 from io import open as io_open
33
33
34 from IPython.config.configurable import SingletonConfigurable
34 from IPython.config.configurable import SingletonConfigurable
35 from IPython.core import debugger, oinspect
35 from IPython.core import debugger, oinspect
36 from IPython.core import magic
36 from IPython.core import magic
37 from IPython.core import page
37 from IPython.core import page
38 from IPython.core import prefilter
38 from IPython.core import prefilter
39 from IPython.core import shadowns
39 from IPython.core import shadowns
40 from IPython.core import ultratb
40 from IPython.core import ultratb
41 from IPython.core.alias import AliasManager, AliasError
41 from IPython.core.alias import AliasManager, AliasError
42 from IPython.core.autocall import ExitAutocall
42 from IPython.core.autocall import ExitAutocall
43 from IPython.core.builtin_trap import BuiltinTrap
43 from IPython.core.builtin_trap import BuiltinTrap
44 from IPython.core.compilerop import CachingCompiler, check_linecache_ipython
44 from IPython.core.compilerop import CachingCompiler, check_linecache_ipython
45 from IPython.core.display_trap import DisplayTrap
45 from IPython.core.display_trap import DisplayTrap
46 from IPython.core.displayhook import DisplayHook
46 from IPython.core.displayhook import DisplayHook
47 from IPython.core.displaypub import DisplayPublisher
47 from IPython.core.displaypub import DisplayPublisher
48 from IPython.core.error import UsageError
48 from IPython.core.error import UsageError
49 from IPython.core.extensions import ExtensionManager
49 from IPython.core.extensions import ExtensionManager
50 from IPython.core.formatters import DisplayFormatter
50 from IPython.core.formatters import DisplayFormatter
51 from IPython.core.history import HistoryManager
51 from IPython.core.history import HistoryManager
52 from IPython.core.inputsplitter import IPythonInputSplitter, ESC_MAGIC, ESC_MAGIC2
52 from IPython.core.inputsplitter import IPythonInputSplitter, ESC_MAGIC, ESC_MAGIC2
53 from IPython.core.logger import Logger
53 from IPython.core.logger import Logger
54 from IPython.core.macro import Macro
54 from IPython.core.macro import Macro
55 from IPython.core.payload import PayloadManager
55 from IPython.core.payload import PayloadManager
56 from IPython.core.prefilter import PrefilterManager
56 from IPython.core.prefilter import PrefilterManager
57 from IPython.core.profiledir import ProfileDir
57 from IPython.core.profiledir import ProfileDir
58 from IPython.core.prompts import PromptManager
58 from IPython.core.prompts import PromptManager
59 from IPython.lib.latextools import LaTeXTool
59 from IPython.lib.latextools import LaTeXTool
60 from IPython.testing.skipdoctest import skip_doctest
60 from IPython.testing.skipdoctest import skip_doctest
61 from IPython.utils import PyColorize
61 from IPython.utils import PyColorize
62 from IPython.utils import io
62 from IPython.utils import io
63 from IPython.utils import py3compat
63 from IPython.utils import py3compat
64 from IPython.utils import openpy
64 from IPython.utils import openpy
65 from IPython.utils.decorators import undoc
65 from IPython.utils.decorators import undoc
66 from IPython.utils.io import ask_yes_no
66 from IPython.utils.io import ask_yes_no
67 from IPython.utils.ipstruct import Struct
67 from IPython.utils.ipstruct import Struct
68 from IPython.utils.path import get_home_dir, get_ipython_dir, get_py_filename, unquote_filename
68 from IPython.utils.path import get_home_dir, get_ipython_dir, get_py_filename, unquote_filename
69 from IPython.utils.pickleshare import PickleShareDB
69 from IPython.utils.pickleshare import PickleShareDB
70 from IPython.utils.process import system, getoutput
70 from IPython.utils.process import system, getoutput
71 from IPython.utils.py3compat import (builtin_mod, unicode_type, string_types,
71 from IPython.utils.py3compat import (builtin_mod, unicode_type, string_types,
72 with_metaclass, iteritems)
72 with_metaclass, iteritems)
73 from IPython.utils.strdispatch import StrDispatch
73 from IPython.utils.strdispatch import StrDispatch
74 from IPython.utils.syspathcontext import prepended_to_syspath
74 from IPython.utils.syspathcontext import prepended_to_syspath
75 from IPython.utils.text import (format_screen, LSString, SList,
75 from IPython.utils.text import (format_screen, LSString, SList,
76 DollarFormatter)
76 DollarFormatter)
77 from IPython.utils.traitlets import (Integer, CBool, CaselessStrEnum, Enum,
77 from IPython.utils.traitlets import (Integer, CBool, CaselessStrEnum, Enum,
78 List, Unicode, Instance, Type)
78 List, Unicode, Instance, Type)
79 from IPython.utils.warn import warn, error
79 from IPython.utils.warn import warn, error
80 import IPython.core.hooks
80 import IPython.core.hooks
81
81
82 #-----------------------------------------------------------------------------
82 #-----------------------------------------------------------------------------
83 # Globals
83 # Globals
84 #-----------------------------------------------------------------------------
84 #-----------------------------------------------------------------------------
85
85
86 # compiled regexps for autoindent management
86 # compiled regexps for autoindent management
87 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
87 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
88
88
89 #-----------------------------------------------------------------------------
89 #-----------------------------------------------------------------------------
90 # Utilities
90 # Utilities
91 #-----------------------------------------------------------------------------
91 #-----------------------------------------------------------------------------
92
92
93 @undoc
93 @undoc
94 def softspace(file, newvalue):
94 def softspace(file, newvalue):
95 """Copied from code.py, to remove the dependency"""
95 """Copied from code.py, to remove the dependency"""
96
96
97 oldvalue = 0
97 oldvalue = 0
98 try:
98 try:
99 oldvalue = file.softspace
99 oldvalue = file.softspace
100 except AttributeError:
100 except AttributeError:
101 pass
101 pass
102 try:
102 try:
103 file.softspace = newvalue
103 file.softspace = newvalue
104 except (AttributeError, TypeError):
104 except (AttributeError, TypeError):
105 # "attribute-less object" or "read-only attributes"
105 # "attribute-less object" or "read-only attributes"
106 pass
106 pass
107 return oldvalue
107 return oldvalue
108
108
109 @undoc
109 @undoc
110 def no_op(*a, **kw): pass
110 def no_op(*a, **kw): pass
111
111
112 @undoc
112 @undoc
113 class NoOpContext(object):
113 class NoOpContext(object):
114 def __enter__(self): pass
114 def __enter__(self): pass
115 def __exit__(self, type, value, traceback): pass
115 def __exit__(self, type, value, traceback): pass
116 no_op_context = NoOpContext()
116 no_op_context = NoOpContext()
117
117
118 class SpaceInInput(Exception): pass
118 class SpaceInInput(Exception): pass
119
119
120 @undoc
120 @undoc
121 class Bunch: pass
121 class Bunch: pass
122
122
123
123
124 def get_default_colors():
124 def get_default_colors():
125 if sys.platform=='darwin':
125 if sys.platform=='darwin':
126 return "LightBG"
126 return "LightBG"
127 elif os.name=='nt':
127 elif os.name=='nt':
128 return 'Linux'
128 return 'Linux'
129 else:
129 else:
130 return 'Linux'
130 return 'Linux'
131
131
132
132
133 class SeparateUnicode(Unicode):
133 class SeparateUnicode(Unicode):
134 """A Unicode subclass to validate separate_in, separate_out, etc.
134 """A Unicode subclass to validate separate_in, separate_out, etc.
135
135
136 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
136 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
137 """
137 """
138
138
139 def validate(self, obj, value):
139 def validate(self, obj, value):
140 if value == '0': value = ''
140 if value == '0': value = ''
141 value = value.replace('\\n','\n')
141 value = value.replace('\\n','\n')
142 return super(SeparateUnicode, self).validate(obj, value)
142 return super(SeparateUnicode, self).validate(obj, value)
143
143
144
144
145 class ReadlineNoRecord(object):
145 class ReadlineNoRecord(object):
146 """Context manager to execute some code, then reload readline history
146 """Context manager to execute some code, then reload readline history
147 so that interactive input to the code doesn't appear when pressing up."""
147 so that interactive input to the code doesn't appear when pressing up."""
148 def __init__(self, shell):
148 def __init__(self, shell):
149 self.shell = shell
149 self.shell = shell
150 self._nested_level = 0
150 self._nested_level = 0
151
151
152 def __enter__(self):
152 def __enter__(self):
153 if self._nested_level == 0:
153 if self._nested_level == 0:
154 try:
154 try:
155 self.orig_length = self.current_length()
155 self.orig_length = self.current_length()
156 self.readline_tail = self.get_readline_tail()
156 self.readline_tail = self.get_readline_tail()
157 except (AttributeError, IndexError): # Can fail with pyreadline
157 except (AttributeError, IndexError): # Can fail with pyreadline
158 self.orig_length, self.readline_tail = 999999, []
158 self.orig_length, self.readline_tail = 999999, []
159 self._nested_level += 1
159 self._nested_level += 1
160
160
161 def __exit__(self, type, value, traceback):
161 def __exit__(self, type, value, traceback):
162 self._nested_level -= 1
162 self._nested_level -= 1
163 if self._nested_level == 0:
163 if self._nested_level == 0:
164 # Try clipping the end if it's got longer
164 # Try clipping the end if it's got longer
165 try:
165 try:
166 e = self.current_length() - self.orig_length
166 e = self.current_length() - self.orig_length
167 if e > 0:
167 if e > 0:
168 for _ in range(e):
168 for _ in range(e):
169 self.shell.readline.remove_history_item(self.orig_length)
169 self.shell.readline.remove_history_item(self.orig_length)
170
170
171 # If it still doesn't match, just reload readline history.
171 # If it still doesn't match, just reload readline history.
172 if self.current_length() != self.orig_length \
172 if self.current_length() != self.orig_length \
173 or self.get_readline_tail() != self.readline_tail:
173 or self.get_readline_tail() != self.readline_tail:
174 self.shell.refill_readline_hist()
174 self.shell.refill_readline_hist()
175 except (AttributeError, IndexError):
175 except (AttributeError, IndexError):
176 pass
176 pass
177 # Returning False will cause exceptions to propagate
177 # Returning False will cause exceptions to propagate
178 return False
178 return False
179
179
180 def current_length(self):
180 def current_length(self):
181 return self.shell.readline.get_current_history_length()
181 return self.shell.readline.get_current_history_length()
182
182
183 def get_readline_tail(self, n=10):
183 def get_readline_tail(self, n=10):
184 """Get the last n items in readline history."""
184 """Get the last n items in readline history."""
185 end = self.shell.readline.get_current_history_length() + 1
185 end = self.shell.readline.get_current_history_length() + 1
186 start = max(end-n, 1)
186 start = max(end-n, 1)
187 ghi = self.shell.readline.get_history_item
187 ghi = self.shell.readline.get_history_item
188 return [ghi(x) for x in range(start, end)]
188 return [ghi(x) for x in range(start, end)]
189
189
190
190
191 @undoc
191 @undoc
192 class DummyMod(object):
192 class DummyMod(object):
193 """A dummy module used for IPython's interactive module when
193 """A dummy module used for IPython's interactive module when
194 a namespace must be assigned to the module's __dict__."""
194 a namespace must be assigned to the module's __dict__."""
195 pass
195 pass
196
196
197 #-----------------------------------------------------------------------------
197 #-----------------------------------------------------------------------------
198 # Main IPython class
198 # Main IPython class
199 #-----------------------------------------------------------------------------
199 #-----------------------------------------------------------------------------
200
200
201 class InteractiveShell(SingletonConfigurable):
201 class InteractiveShell(SingletonConfigurable):
202 """An enhanced, interactive shell for Python."""
202 """An enhanced, interactive shell for Python."""
203
203
204 _instance = None
204 _instance = None
205
205
206 ast_transformers = List([], config=True, help=
206 ast_transformers = List([], config=True, help=
207 """
207 """
208 A list of ast.NodeTransformer subclass instances, which will be applied
208 A list of ast.NodeTransformer subclass instances, which will be applied
209 to user input before code is run.
209 to user input before code is run.
210 """
210 """
211 )
211 )
212
212
213 autocall = Enum((0,1,2), default_value=0, config=True, help=
213 autocall = Enum((0,1,2), default_value=0, config=True, help=
214 """
214 """
215 Make IPython automatically call any callable object even if you didn't
215 Make IPython automatically call any callable object even if you didn't
216 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
216 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
217 automatically. The value can be '0' to disable the feature, '1' for
217 automatically. The value can be '0' to disable the feature, '1' for
218 'smart' autocall, where it is not applied if there are no more
218 'smart' autocall, where it is not applied if there are no more
219 arguments on the line, and '2' for 'full' autocall, where all callable
219 arguments on the line, and '2' for 'full' autocall, where all callable
220 objects are automatically called (even if no arguments are present).
220 objects are automatically called (even if no arguments are present).
221 """
221 """
222 )
222 )
223 # TODO: remove all autoindent logic and put into frontends.
223 # TODO: remove all autoindent logic and put into frontends.
224 # We can't do this yet because even runlines uses the autoindent.
224 # We can't do this yet because even runlines uses the autoindent.
225 autoindent = CBool(True, config=True, help=
225 autoindent = CBool(True, config=True, help=
226 """
226 """
227 Autoindent IPython code entered interactively.
227 Autoindent IPython code entered interactively.
228 """
228 """
229 )
229 )
230 automagic = CBool(True, config=True, help=
230 automagic = CBool(True, config=True, help=
231 """
231 """
232 Enable magic commands to be called without the leading %.
232 Enable magic commands to be called without the leading %.
233 """
233 """
234 )
234 )
235 cache_size = Integer(1000, config=True, help=
235 cache_size = Integer(1000, config=True, help=
236 """
236 """
237 Set the size of the output cache. The default is 1000, you can
237 Set the size of the output cache. The default is 1000, you can
238 change it permanently in your config file. Setting it to 0 completely
238 change it permanently in your config file. Setting it to 0 completely
239 disables the caching system, and the minimum value accepted is 20 (if
239 disables the caching system, and the minimum value accepted is 20 (if
240 you provide a value less than 20, it is reset to 0 and a warning is
240 you provide a value less than 20, it is reset to 0 and a warning is
241 issued). This limit is defined because otherwise you'll spend more
241 issued). This limit is defined because otherwise you'll spend more
242 time re-flushing a too small cache than working
242 time re-flushing a too small cache than working
243 """
243 """
244 )
244 )
245 color_info = CBool(True, config=True, help=
245 color_info = CBool(True, config=True, help=
246 """
246 """
247 Use colors for displaying information about objects. Because this
247 Use colors for displaying information about objects. Because this
248 information is passed through a pager (like 'less'), and some pagers
248 information is passed through a pager (like 'less'), and some pagers
249 get confused with color codes, this capability can be turned off.
249 get confused with color codes, this capability can be turned off.
250 """
250 """
251 )
251 )
252 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
252 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
253 default_value=get_default_colors(), config=True,
253 default_value=get_default_colors(), config=True,
254 help="Set the color scheme (NoColor, Linux, or LightBG)."
254 help="Set the color scheme (NoColor, Linux, or LightBG)."
255 )
255 )
256 colors_force = CBool(False, help=
256 colors_force = CBool(False, help=
257 """
257 """
258 Force use of ANSI color codes, regardless of OS and readline
258 Force use of ANSI color codes, regardless of OS and readline
259 availability.
259 availability.
260 """
260 """
261 # FIXME: This is essentially a hack to allow ZMQShell to show colors
261 # FIXME: This is essentially a hack to allow ZMQShell to show colors
262 # without readline on Win32. When the ZMQ formatting system is
262 # without readline on Win32. When the ZMQ formatting system is
263 # refactored, this should be removed.
263 # refactored, this should be removed.
264 )
264 )
265 debug = CBool(False, config=True)
265 debug = CBool(False, config=True)
266 deep_reload = CBool(False, config=True, help=
266 deep_reload = CBool(False, config=True, help=
267 """
267 """
268 Enable deep (recursive) reloading by default. IPython can use the
268 Enable deep (recursive) reloading by default. IPython can use the
269 deep_reload module which reloads changes in modules recursively (it
269 deep_reload module which reloads changes in modules recursively (it
270 replaces the reload() function, so you don't need to change anything to
270 replaces the reload() function, so you don't need to change anything to
271 use it). deep_reload() forces a full reload of modules whose code may
271 use it). deep_reload() forces a full reload of modules whose code may
272 have changed, which the default reload() function does not. When
272 have changed, which the default reload() function does not. When
273 deep_reload is off, IPython will use the normal reload(), but
273 deep_reload is off, IPython will use the normal reload(), but
274 deep_reload will still be available as dreload().
274 deep_reload will still be available as dreload().
275 """
275 """
276 )
276 )
277 disable_failing_post_execute = CBool(False, config=True,
277 disable_failing_post_execute = CBool(False, config=True,
278 help="Don't call post-execute functions that have failed in the past."
278 help="Don't call post-execute functions that have failed in the past."
279 )
279 )
280 display_formatter = Instance(DisplayFormatter)
280 display_formatter = Instance(DisplayFormatter)
281 displayhook_class = Type(DisplayHook)
281 displayhook_class = Type(DisplayHook)
282 display_pub_class = Type(DisplayPublisher)
282 display_pub_class = Type(DisplayPublisher)
283 data_pub_class = None
283 data_pub_class = None
284
284
285 exit_now = CBool(False)
285 exit_now = CBool(False)
286 exiter = Instance(ExitAutocall)
286 exiter = Instance(ExitAutocall)
287 def _exiter_default(self):
287 def _exiter_default(self):
288 return ExitAutocall(self)
288 return ExitAutocall(self)
289 # Monotonically increasing execution counter
289 # Monotonically increasing execution counter
290 execution_count = Integer(1)
290 execution_count = Integer(1)
291 filename = Unicode("<ipython console>")
291 filename = Unicode("<ipython console>")
292 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
292 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
293
293
294 # Input splitter, to transform input line by line and detect when a block
294 # Input splitter, to transform input line by line and detect when a block
295 # is ready to be executed.
295 # is ready to be executed.
296 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
296 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
297 (), {'line_input_checker': True})
297 (), {'line_input_checker': True})
298
298
299 # This InputSplitter instance is used to transform completed cells before
299 # This InputSplitter instance is used to transform completed cells before
300 # running them. It allows cell magics to contain blank lines.
300 # running them. It allows cell magics to contain blank lines.
301 input_transformer_manager = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
301 input_transformer_manager = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
302 (), {'line_input_checker': False})
302 (), {'line_input_checker': False})
303
303
304 logstart = CBool(False, config=True, help=
304 logstart = CBool(False, config=True, help=
305 """
305 """
306 Start logging to the default log file.
306 Start logging to the default log file.
307 """
307 """
308 )
308 )
309 logfile = Unicode('', config=True, help=
309 logfile = Unicode('', config=True, help=
310 """
310 """
311 The name of the logfile to use.
311 The name of the logfile to use.
312 """
312 """
313 )
313 )
314 logappend = Unicode('', config=True, help=
314 logappend = Unicode('', config=True, help=
315 """
315 """
316 Start logging to the given file in append mode.
316 Start logging to the given file in append mode.
317 """
317 """
318 )
318 )
319 object_info_string_level = Enum((0,1,2), default_value=0,
319 object_info_string_level = Enum((0,1,2), default_value=0,
320 config=True)
320 config=True)
321 pdb = CBool(False, config=True, help=
321 pdb = CBool(False, config=True, help=
322 """
322 """
323 Automatically call the pdb debugger after every exception.
323 Automatically call the pdb debugger after every exception.
324 """
324 """
325 )
325 )
326 multiline_history = CBool(sys.platform != 'win32', config=True,
326 multiline_history = CBool(sys.platform != 'win32', config=True,
327 help="Save multi-line entries as one entry in readline history"
327 help="Save multi-line entries as one entry in readline history"
328 )
328 )
329
329
330 # deprecated prompt traits:
330 # deprecated prompt traits:
331
331
332 prompt_in1 = Unicode('In [\\#]: ', config=True,
332 prompt_in1 = Unicode('In [\\#]: ', config=True,
333 help="Deprecated, use PromptManager.in_template")
333 help="Deprecated, use PromptManager.in_template")
334 prompt_in2 = Unicode(' .\\D.: ', config=True,
334 prompt_in2 = Unicode(' .\\D.: ', config=True,
335 help="Deprecated, use PromptManager.in2_template")
335 help="Deprecated, use PromptManager.in2_template")
336 prompt_out = Unicode('Out[\\#]: ', config=True,
336 prompt_out = Unicode('Out[\\#]: ', config=True,
337 help="Deprecated, use PromptManager.out_template")
337 help="Deprecated, use PromptManager.out_template")
338 prompts_pad_left = CBool(True, config=True,
338 prompts_pad_left = CBool(True, config=True,
339 help="Deprecated, use PromptManager.justify")
339 help="Deprecated, use PromptManager.justify")
340
340
341 def _prompt_trait_changed(self, name, old, new):
341 def _prompt_trait_changed(self, name, old, new):
342 table = {
342 table = {
343 'prompt_in1' : 'in_template',
343 'prompt_in1' : 'in_template',
344 'prompt_in2' : 'in2_template',
344 'prompt_in2' : 'in2_template',
345 'prompt_out' : 'out_template',
345 'prompt_out' : 'out_template',
346 'prompts_pad_left' : 'justify',
346 'prompts_pad_left' : 'justify',
347 }
347 }
348 warn("InteractiveShell.{name} is deprecated, use PromptManager.{newname}".format(
348 warn("InteractiveShell.{name} is deprecated, use PromptManager.{newname}".format(
349 name=name, newname=table[name])
349 name=name, newname=table[name])
350 )
350 )
351 # protect against weird cases where self.config may not exist:
351 # protect against weird cases where self.config may not exist:
352 if self.config is not None:
352 if self.config is not None:
353 # propagate to corresponding PromptManager trait
353 # propagate to corresponding PromptManager trait
354 setattr(self.config.PromptManager, table[name], new)
354 setattr(self.config.PromptManager, table[name], new)
355
355
356 _prompt_in1_changed = _prompt_trait_changed
356 _prompt_in1_changed = _prompt_trait_changed
357 _prompt_in2_changed = _prompt_trait_changed
357 _prompt_in2_changed = _prompt_trait_changed
358 _prompt_out_changed = _prompt_trait_changed
358 _prompt_out_changed = _prompt_trait_changed
359 _prompt_pad_left_changed = _prompt_trait_changed
359 _prompt_pad_left_changed = _prompt_trait_changed
360
360
361 show_rewritten_input = CBool(True, config=True,
361 show_rewritten_input = CBool(True, config=True,
362 help="Show rewritten input, e.g. for autocall."
362 help="Show rewritten input, e.g. for autocall."
363 )
363 )
364
364
365 quiet = CBool(False, config=True)
365 quiet = CBool(False, config=True)
366
366
367 history_length = Integer(10000, config=True)
367 history_length = Integer(10000, config=True)
368
368
369 # The readline stuff will eventually be moved to the terminal subclass
369 # The readline stuff will eventually be moved to the terminal subclass
370 # but for now, we can't do that as readline is welded in everywhere.
370 # but for now, we can't do that as readline is welded in everywhere.
371 readline_use = CBool(True, config=True)
371 readline_use = CBool(True, config=True)
372 readline_remove_delims = Unicode('-/~', config=True)
372 readline_remove_delims = Unicode('-/~', config=True)
373 readline_delims = Unicode() # set by init_readline()
373 readline_delims = Unicode() # set by init_readline()
374 # don't use \M- bindings by default, because they
374 # don't use \M- bindings by default, because they
375 # conflict with 8-bit encodings. See gh-58,gh-88
375 # conflict with 8-bit encodings. See gh-58,gh-88
376 readline_parse_and_bind = List([
376 readline_parse_and_bind = List([
377 'tab: complete',
377 'tab: complete',
378 '"\C-l": clear-screen',
378 '"\C-l": clear-screen',
379 'set show-all-if-ambiguous on',
379 'set show-all-if-ambiguous on',
380 '"\C-o": tab-insert',
380 '"\C-o": tab-insert',
381 '"\C-r": reverse-search-history',
381 '"\C-r": reverse-search-history',
382 '"\C-s": forward-search-history',
382 '"\C-s": forward-search-history',
383 '"\C-p": history-search-backward',
383 '"\C-p": history-search-backward',
384 '"\C-n": history-search-forward',
384 '"\C-n": history-search-forward',
385 '"\e[A": history-search-backward',
385 '"\e[A": history-search-backward',
386 '"\e[B": history-search-forward',
386 '"\e[B": history-search-forward',
387 '"\C-k": kill-line',
387 '"\C-k": kill-line',
388 '"\C-u": unix-line-discard',
388 '"\C-u": unix-line-discard',
389 ], allow_none=False, config=True)
389 ], allow_none=False, config=True)
390
390
391 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none'],
391 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none'],
392 default_value='last_expr', config=True,
392 default_value='last_expr', config=True,
393 help="""
393 help="""
394 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
394 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
395 run interactively (displaying output from expressions).""")
395 run interactively (displaying output from expressions).""")
396
396
397 # TODO: this part of prompt management should be moved to the frontends.
397 # TODO: this part of prompt management should be moved to the frontends.
398 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
398 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
399 separate_in = SeparateUnicode('\n', config=True)
399 separate_in = SeparateUnicode('\n', config=True)
400 separate_out = SeparateUnicode('', config=True)
400 separate_out = SeparateUnicode('', config=True)
401 separate_out2 = SeparateUnicode('', config=True)
401 separate_out2 = SeparateUnicode('', config=True)
402 wildcards_case_sensitive = CBool(True, config=True)
402 wildcards_case_sensitive = CBool(True, config=True)
403 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
403 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
404 default_value='Context', config=True)
404 default_value='Context', config=True)
405
405
406 # Subcomponents of InteractiveShell
406 # Subcomponents of InteractiveShell
407 alias_manager = Instance('IPython.core.alias.AliasManager')
407 alias_manager = Instance('IPython.core.alias.AliasManager')
408 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
408 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
409 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
409 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
410 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
410 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
411 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
411 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
412 payload_manager = Instance('IPython.core.payload.PayloadManager')
412 payload_manager = Instance('IPython.core.payload.PayloadManager')
413 history_manager = Instance('IPython.core.history.HistoryManager')
413 history_manager = Instance('IPython.core.history.HistoryManager')
414 magics_manager = Instance('IPython.core.magic.MagicsManager')
414 magics_manager = Instance('IPython.core.magic.MagicsManager')
415
415
416 profile_dir = Instance('IPython.core.application.ProfileDir')
416 profile_dir = Instance('IPython.core.application.ProfileDir')
417 @property
417 @property
418 def profile(self):
418 def profile(self):
419 if self.profile_dir is not None:
419 if self.profile_dir is not None:
420 name = os.path.basename(self.profile_dir.location)
420 name = os.path.basename(self.profile_dir.location)
421 return name.replace('profile_','')
421 return name.replace('profile_','')
422
422
423
423
424 # Private interface
424 # Private interface
425 _post_execute = Instance(dict)
425 _post_execute = Instance(dict)
426
426
427 # Tracks any GUI loop loaded for pylab
427 # Tracks any GUI loop loaded for pylab
428 pylab_gui_select = None
428 pylab_gui_select = None
429
429
430 def __init__(self, ipython_dir=None, profile_dir=None,
430 def __init__(self, ipython_dir=None, profile_dir=None,
431 user_module=None, user_ns=None,
431 user_module=None, user_ns=None,
432 custom_exceptions=((), None), **kwargs):
432 custom_exceptions=((), None), **kwargs):
433
433
434 # This is where traits with a config_key argument are updated
434 # This is where traits with a config_key argument are updated
435 # from the values on config.
435 # from the values on config.
436 super(InteractiveShell, self).__init__(**kwargs)
436 super(InteractiveShell, self).__init__(**kwargs)
437 self.configurables = [self]
437 self.configurables = [self]
438
438
439 # These are relatively independent and stateless
439 # These are relatively independent and stateless
440 self.init_ipython_dir(ipython_dir)
440 self.init_ipython_dir(ipython_dir)
441 self.init_profile_dir(profile_dir)
441 self.init_profile_dir(profile_dir)
442 self.init_instance_attrs()
442 self.init_instance_attrs()
443 self.init_environment()
443 self.init_environment()
444
444
445 # Check if we're in a virtualenv, and set up sys.path.
445 # Check if we're in a virtualenv, and set up sys.path.
446 self.init_virtualenv()
446 self.init_virtualenv()
447
447
448 # Create namespaces (user_ns, user_global_ns, etc.)
448 # Create namespaces (user_ns, user_global_ns, etc.)
449 self.init_create_namespaces(user_module, user_ns)
449 self.init_create_namespaces(user_module, user_ns)
450 # This has to be done after init_create_namespaces because it uses
450 # This has to be done after init_create_namespaces because it uses
451 # something in self.user_ns, but before init_sys_modules, which
451 # something in self.user_ns, but before init_sys_modules, which
452 # is the first thing to modify sys.
452 # is the first thing to modify sys.
453 # TODO: When we override sys.stdout and sys.stderr before this class
453 # TODO: When we override sys.stdout and sys.stderr before this class
454 # is created, we are saving the overridden ones here. Not sure if this
454 # is created, we are saving the overridden ones here. Not sure if this
455 # is what we want to do.
455 # is what we want to do.
456 self.save_sys_module_state()
456 self.save_sys_module_state()
457 self.init_sys_modules()
457 self.init_sys_modules()
458
458
459 # While we're trying to have each part of the code directly access what
459 # While we're trying to have each part of the code directly access what
460 # it needs without keeping redundant references to objects, we have too
460 # it needs without keeping redundant references to objects, we have too
461 # much legacy code that expects ip.db to exist.
461 # much legacy code that expects ip.db to exist.
462 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
462 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
463
463
464 self.init_history()
464 self.init_history()
465 self.init_encoding()
465 self.init_encoding()
466 self.init_prefilter()
466 self.init_prefilter()
467
467
468 self.init_syntax_highlighting()
468 self.init_syntax_highlighting()
469 self.init_hooks()
469 self.init_hooks()
470 self.init_pushd_popd_magic()
470 self.init_pushd_popd_magic()
471 # self.init_traceback_handlers use to be here, but we moved it below
471 # self.init_traceback_handlers use to be here, but we moved it below
472 # because it and init_io have to come after init_readline.
472 # because it and init_io have to come after init_readline.
473 self.init_user_ns()
473 self.init_user_ns()
474 self.init_logger()
474 self.init_logger()
475 self.init_builtins()
475 self.init_builtins()
476
476
477 # The following was in post_config_initialization
477 # The following was in post_config_initialization
478 self.init_inspector()
478 self.init_inspector()
479 # init_readline() must come before init_io(), because init_io uses
479 # init_readline() must come before init_io(), because init_io uses
480 # readline related things.
480 # readline related things.
481 self.init_readline()
481 self.init_readline()
482 # We save this here in case user code replaces raw_input, but it needs
482 # We save this here in case user code replaces raw_input, but it needs
483 # to be after init_readline(), because PyPy's readline works by replacing
483 # to be after init_readline(), because PyPy's readline works by replacing
484 # raw_input.
484 # raw_input.
485 if py3compat.PY3:
485 if py3compat.PY3:
486 self.raw_input_original = input
486 self.raw_input_original = input
487 else:
487 else:
488 self.raw_input_original = raw_input
488 self.raw_input_original = raw_input
489 # init_completer must come after init_readline, because it needs to
489 # init_completer must come after init_readline, because it needs to
490 # know whether readline is present or not system-wide to configure the
490 # know whether readline is present or not system-wide to configure the
491 # completers, since the completion machinery can now operate
491 # completers, since the completion machinery can now operate
492 # independently of readline (e.g. over the network)
492 # independently of readline (e.g. over the network)
493 self.init_completer()
493 self.init_completer()
494 # TODO: init_io() needs to happen before init_traceback handlers
494 # TODO: init_io() needs to happen before init_traceback handlers
495 # because the traceback handlers hardcode the stdout/stderr streams.
495 # because the traceback handlers hardcode the stdout/stderr streams.
496 # This logic in in debugger.Pdb and should eventually be changed.
496 # This logic in in debugger.Pdb and should eventually be changed.
497 self.init_io()
497 self.init_io()
498 self.init_traceback_handlers(custom_exceptions)
498 self.init_traceback_handlers(custom_exceptions)
499 self.init_prompts()
499 self.init_prompts()
500 self.init_display_formatter()
500 self.init_display_formatter()
501 self.init_display_pub()
501 self.init_display_pub()
502 self.init_data_pub()
502 self.init_data_pub()
503 self.init_displayhook()
503 self.init_displayhook()
504 self.init_latextool()
504 self.init_latextool()
505 self.init_magics()
505 self.init_magics()
506 self.init_alias()
506 self.init_alias()
507 self.init_logstart()
507 self.init_logstart()
508 self.init_pdb()
508 self.init_pdb()
509 self.init_extension_manager()
509 self.init_extension_manager()
510 self.init_payload()
510 self.init_payload()
511 self.init_comms()
511 self.init_comms()
512 self.hooks.late_startup_hook()
512 self.hooks.late_startup_hook()
513 atexit.register(self.atexit_operations)
513 atexit.register(self.atexit_operations)
514
514
515 def get_ipython(self):
515 def get_ipython(self):
516 """Return the currently running IPython instance."""
516 """Return the currently running IPython instance."""
517 return self
517 return self
518
518
519 #-------------------------------------------------------------------------
519 #-------------------------------------------------------------------------
520 # Trait changed handlers
520 # Trait changed handlers
521 #-------------------------------------------------------------------------
521 #-------------------------------------------------------------------------
522
522
523 def _ipython_dir_changed(self, name, new):
523 def _ipython_dir_changed(self, name, new):
524 if not os.path.isdir(new):
524 if not os.path.isdir(new):
525 os.makedirs(new, mode = 0o777)
525 os.makedirs(new, mode = 0o777)
526
526
527 def set_autoindent(self,value=None):
527 def set_autoindent(self,value=None):
528 """Set the autoindent flag, checking for readline support.
528 """Set the autoindent flag, checking for readline support.
529
529
530 If called with no arguments, it acts as a toggle."""
530 If called with no arguments, it acts as a toggle."""
531
531
532 if value != 0 and not self.has_readline:
532 if value != 0 and not self.has_readline:
533 if os.name == 'posix':
533 if os.name == 'posix':
534 warn("The auto-indent feature requires the readline library")
534 warn("The auto-indent feature requires the readline library")
535 self.autoindent = 0
535 self.autoindent = 0
536 return
536 return
537 if value is None:
537 if value is None:
538 self.autoindent = not self.autoindent
538 self.autoindent = not self.autoindent
539 else:
539 else:
540 self.autoindent = value
540 self.autoindent = value
541
541
542 #-------------------------------------------------------------------------
542 #-------------------------------------------------------------------------
543 # init_* methods called by __init__
543 # init_* methods called by __init__
544 #-------------------------------------------------------------------------
544 #-------------------------------------------------------------------------
545
545
546 def init_ipython_dir(self, ipython_dir):
546 def init_ipython_dir(self, ipython_dir):
547 if ipython_dir is not None:
547 if ipython_dir is not None:
548 self.ipython_dir = ipython_dir
548 self.ipython_dir = ipython_dir
549 return
549 return
550
550
551 self.ipython_dir = get_ipython_dir()
551 self.ipython_dir = get_ipython_dir()
552
552
553 def init_profile_dir(self, profile_dir):
553 def init_profile_dir(self, profile_dir):
554 if profile_dir is not None:
554 if profile_dir is not None:
555 self.profile_dir = profile_dir
555 self.profile_dir = profile_dir
556 return
556 return
557 self.profile_dir =\
557 self.profile_dir =\
558 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
558 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
559
559
560 def init_instance_attrs(self):
560 def init_instance_attrs(self):
561 self.more = False
561 self.more = False
562
562
563 # command compiler
563 # command compiler
564 self.compile = CachingCompiler()
564 self.compile = CachingCompiler()
565
565
566 # Make an empty namespace, which extension writers can rely on both
566 # Make an empty namespace, which extension writers can rely on both
567 # existing and NEVER being used by ipython itself. This gives them a
567 # existing and NEVER being used by ipython itself. This gives them a
568 # convenient location for storing additional information and state
568 # convenient location for storing additional information and state
569 # their extensions may require, without fear of collisions with other
569 # their extensions may require, without fear of collisions with other
570 # ipython names that may develop later.
570 # ipython names that may develop later.
571 self.meta = Struct()
571 self.meta = Struct()
572
572
573 # Temporary files used for various purposes. Deleted at exit.
573 # Temporary files used for various purposes. Deleted at exit.
574 self.tempfiles = []
574 self.tempfiles = []
575
575
576 # Keep track of readline usage (later set by init_readline)
576 # Keep track of readline usage (later set by init_readline)
577 self.has_readline = False
577 self.has_readline = False
578
578
579 # keep track of where we started running (mainly for crash post-mortem)
579 # keep track of where we started running (mainly for crash post-mortem)
580 # This is not being used anywhere currently.
580 # This is not being used anywhere currently.
581 self.starting_dir = py3compat.getcwd()
581 self.starting_dir = py3compat.getcwd()
582
582
583 # Indentation management
583 # Indentation management
584 self.indent_current_nsp = 0
584 self.indent_current_nsp = 0
585
585
586 # Dict to track post-execution functions that have been registered
586 # Dict to track post-execution functions that have been registered
587 self._post_execute = {}
587 self._post_execute = {}
588
588
589 def init_environment(self):
589 def init_environment(self):
590 """Any changes we need to make to the user's environment."""
590 """Any changes we need to make to the user's environment."""
591 pass
591 pass
592
592
593 def init_encoding(self):
593 def init_encoding(self):
594 # Get system encoding at startup time. Certain terminals (like Emacs
594 # Get system encoding at startup time. Certain terminals (like Emacs
595 # under Win32 have it set to None, and we need to have a known valid
595 # under Win32 have it set to None, and we need to have a known valid
596 # encoding to use in the raw_input() method
596 # encoding to use in the raw_input() method
597 try:
597 try:
598 self.stdin_encoding = sys.stdin.encoding or 'ascii'
598 self.stdin_encoding = sys.stdin.encoding or 'ascii'
599 except AttributeError:
599 except AttributeError:
600 self.stdin_encoding = 'ascii'
600 self.stdin_encoding = 'ascii'
601
601
602 def init_syntax_highlighting(self):
602 def init_syntax_highlighting(self):
603 # Python source parser/formatter for syntax highlighting
603 # Python source parser/formatter for syntax highlighting
604 pyformat = PyColorize.Parser().format
604 pyformat = PyColorize.Parser().format
605 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
605 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
606
606
607 def init_pushd_popd_magic(self):
607 def init_pushd_popd_magic(self):
608 # for pushd/popd management
608 # for pushd/popd management
609 self.home_dir = get_home_dir()
609 self.home_dir = get_home_dir()
610
610
611 self.dir_stack = []
611 self.dir_stack = []
612
612
613 def init_logger(self):
613 def init_logger(self):
614 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
614 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
615 logmode='rotate')
615 logmode='rotate')
616
616
617 def init_logstart(self):
617 def init_logstart(self):
618 """Initialize logging in case it was requested at the command line.
618 """Initialize logging in case it was requested at the command line.
619 """
619 """
620 if self.logappend:
620 if self.logappend:
621 self.magic('logstart %s append' % self.logappend)
621 self.magic('logstart %s append' % self.logappend)
622 elif self.logfile:
622 elif self.logfile:
623 self.magic('logstart %s' % self.logfile)
623 self.magic('logstart %s' % self.logfile)
624 elif self.logstart:
624 elif self.logstart:
625 self.magic('logstart')
625 self.magic('logstart')
626
626
627 def init_builtins(self):
627 def init_builtins(self):
628 # A single, static flag that we set to True. Its presence indicates
628 # A single, static flag that we set to True. Its presence indicates
629 # that an IPython shell has been created, and we make no attempts at
629 # that an IPython shell has been created, and we make no attempts at
630 # removing on exit or representing the existence of more than one
630 # removing on exit or representing the existence of more than one
631 # IPython at a time.
631 # IPython at a time.
632 builtin_mod.__dict__['__IPYTHON__'] = True
632 builtin_mod.__dict__['__IPYTHON__'] = True
633
633
634 # In 0.11 we introduced '__IPYTHON__active' as an integer we'd try to
634 # In 0.11 we introduced '__IPYTHON__active' as an integer we'd try to
635 # manage on enter/exit, but with all our shells it's virtually
635 # manage on enter/exit, but with all our shells it's virtually
636 # impossible to get all the cases right. We're leaving the name in for
636 # impossible to get all the cases right. We're leaving the name in for
637 # those who adapted their codes to check for this flag, but will
637 # those who adapted their codes to check for this flag, but will
638 # eventually remove it after a few more releases.
638 # eventually remove it after a few more releases.
639 builtin_mod.__dict__['__IPYTHON__active'] = \
639 builtin_mod.__dict__['__IPYTHON__active'] = \
640 'Deprecated, check for __IPYTHON__'
640 'Deprecated, check for __IPYTHON__'
641
641
642 self.builtin_trap = BuiltinTrap(shell=self)
642 self.builtin_trap = BuiltinTrap(shell=self)
643
643
644 def init_inspector(self):
644 def init_inspector(self):
645 # Object inspector
645 # Object inspector
646 self.inspector = oinspect.Inspector(oinspect.InspectColors,
646 self.inspector = oinspect.Inspector(oinspect.InspectColors,
647 PyColorize.ANSICodeColors,
647 PyColorize.ANSICodeColors,
648 'NoColor',
648 'NoColor',
649 self.object_info_string_level)
649 self.object_info_string_level)
650
650
651 def init_io(self):
651 def init_io(self):
652 # This will just use sys.stdout and sys.stderr. If you want to
652 # This will just use sys.stdout and sys.stderr. If you want to
653 # override sys.stdout and sys.stderr themselves, you need to do that
653 # override sys.stdout and sys.stderr themselves, you need to do that
654 # *before* instantiating this class, because io holds onto
654 # *before* instantiating this class, because io holds onto
655 # references to the underlying streams.
655 # references to the underlying streams.
656 if (sys.platform == 'win32' or sys.platform == 'cli') and self.has_readline:
656 if (sys.platform == 'win32' or sys.platform == 'cli') and self.has_readline:
657 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
657 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
658 else:
658 else:
659 io.stdout = io.IOStream(sys.stdout)
659 io.stdout = io.IOStream(sys.stdout)
660 io.stderr = io.IOStream(sys.stderr)
660 io.stderr = io.IOStream(sys.stderr)
661
661
662 def init_prompts(self):
662 def init_prompts(self):
663 self.prompt_manager = PromptManager(shell=self, parent=self)
663 self.prompt_manager = PromptManager(shell=self, parent=self)
664 self.configurables.append(self.prompt_manager)
664 self.configurables.append(self.prompt_manager)
665 # Set system prompts, so that scripts can decide if they are running
665 # Set system prompts, so that scripts can decide if they are running
666 # interactively.
666 # interactively.
667 sys.ps1 = 'In : '
667 sys.ps1 = 'In : '
668 sys.ps2 = '...: '
668 sys.ps2 = '...: '
669 sys.ps3 = 'Out: '
669 sys.ps3 = 'Out: '
670
670
671 def init_display_formatter(self):
671 def init_display_formatter(self):
672 self.display_formatter = DisplayFormatter(parent=self)
672 self.display_formatter = DisplayFormatter(parent=self)
673 self.configurables.append(self.display_formatter)
673 self.configurables.append(self.display_formatter)
674
674
675 def init_display_pub(self):
675 def init_display_pub(self):
676 self.display_pub = self.display_pub_class(parent=self)
676 self.display_pub = self.display_pub_class(parent=self)
677 self.configurables.append(self.display_pub)
677 self.configurables.append(self.display_pub)
678
678
679 def init_data_pub(self):
679 def init_data_pub(self):
680 if not self.data_pub_class:
680 if not self.data_pub_class:
681 self.data_pub = None
681 self.data_pub = None
682 return
682 return
683 self.data_pub = self.data_pub_class(parent=self)
683 self.data_pub = self.data_pub_class(parent=self)
684 self.configurables.append(self.data_pub)
684 self.configurables.append(self.data_pub)
685
685
686 def init_displayhook(self):
686 def init_displayhook(self):
687 # Initialize displayhook, set in/out prompts and printing system
687 # Initialize displayhook, set in/out prompts and printing system
688 self.displayhook = self.displayhook_class(
688 self.displayhook = self.displayhook_class(
689 parent=self,
689 parent=self,
690 shell=self,
690 shell=self,
691 cache_size=self.cache_size,
691 cache_size=self.cache_size,
692 )
692 )
693 self.configurables.append(self.displayhook)
693 self.configurables.append(self.displayhook)
694 # This is a context manager that installs/revmoes the displayhook at
694 # This is a context manager that installs/revmoes the displayhook at
695 # the appropriate time.
695 # the appropriate time.
696 self.display_trap = DisplayTrap(hook=self.displayhook)
696 self.display_trap = DisplayTrap(hook=self.displayhook)
697
697
698 def init_latextool(self):
698 def init_latextool(self):
699 """Configure LaTeXTool."""
699 """Configure LaTeXTool."""
700 cfg = LaTeXTool.instance(parent=self)
700 cfg = LaTeXTool.instance(parent=self)
701 if cfg not in self.configurables:
701 if cfg not in self.configurables:
702 self.configurables.append(cfg)
702 self.configurables.append(cfg)
703
703
704 def init_virtualenv(self):
704 def init_virtualenv(self):
705 """Add a virtualenv to sys.path so the user can import modules from it.
705 """Add a virtualenv to sys.path so the user can import modules from it.
706 This isn't perfect: it doesn't use the Python interpreter with which the
706 This isn't perfect: it doesn't use the Python interpreter with which the
707 virtualenv was built, and it ignores the --no-site-packages option. A
707 virtualenv was built, and it ignores the --no-site-packages option. A
708 warning will appear suggesting the user installs IPython in the
708 warning will appear suggesting the user installs IPython in the
709 virtualenv, but for many cases, it probably works well enough.
709 virtualenv, but for many cases, it probably works well enough.
710
710
711 Adapted from code snippets online.
711 Adapted from code snippets online.
712
712
713 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
713 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
714 """
714 """
715 if 'VIRTUAL_ENV' not in os.environ:
715 if 'VIRTUAL_ENV' not in os.environ:
716 # Not in a virtualenv
716 # Not in a virtualenv
717 return
717 return
718
718
719 if os.path.realpath(sys.executable).startswith(
719 if os.path.realpath(sys.executable).startswith(
720 os.path.realpath(os.environ['VIRTUAL_ENV'])
720 os.path.realpath(os.environ['VIRTUAL_ENV'])
721 ):
721 ):
722 # Running properly in the virtualenv, don't need to do anything
722 # Running properly in the virtualenv, don't need to do anything
723 return
723 return
724
724
725 warn("Attempting to work in a virtualenv. If you encounter problems, please "
725 warn("Attempting to work in a virtualenv. If you encounter problems, please "
726 "install IPython inside the virtualenv.")
726 "install IPython inside the virtualenv.")
727 if sys.platform == "win32":
727 if sys.platform == "win32":
728 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
728 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
729 else:
729 else:
730 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
730 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
731 'python%d.%d' % sys.version_info[:2], 'site-packages')
731 'python%d.%d' % sys.version_info[:2], 'site-packages')
732
732
733 import site
733 import site
734 sys.path.insert(0, virtual_env)
734 sys.path.insert(0, virtual_env)
735 site.addsitedir(virtual_env)
735 site.addsitedir(virtual_env)
736
736
737 #-------------------------------------------------------------------------
737 #-------------------------------------------------------------------------
738 # Things related to injections into the sys module
738 # Things related to injections into the sys module
739 #-------------------------------------------------------------------------
739 #-------------------------------------------------------------------------
740
740
741 def save_sys_module_state(self):
741 def save_sys_module_state(self):
742 """Save the state of hooks in the sys module.
742 """Save the state of hooks in the sys module.
743
743
744 This has to be called after self.user_module is created.
744 This has to be called after self.user_module is created.
745 """
745 """
746 self._orig_sys_module_state = {}
746 self._orig_sys_module_state = {}
747 self._orig_sys_module_state['stdin'] = sys.stdin
747 self._orig_sys_module_state['stdin'] = sys.stdin
748 self._orig_sys_module_state['stdout'] = sys.stdout
748 self._orig_sys_module_state['stdout'] = sys.stdout
749 self._orig_sys_module_state['stderr'] = sys.stderr
749 self._orig_sys_module_state['stderr'] = sys.stderr
750 self._orig_sys_module_state['excepthook'] = sys.excepthook
750 self._orig_sys_module_state['excepthook'] = sys.excepthook
751 self._orig_sys_modules_main_name = self.user_module.__name__
751 self._orig_sys_modules_main_name = self.user_module.__name__
752 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
752 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
753
753
754 def restore_sys_module_state(self):
754 def restore_sys_module_state(self):
755 """Restore the state of the sys module."""
755 """Restore the state of the sys module."""
756 try:
756 try:
757 for k, v in iteritems(self._orig_sys_module_state):
757 for k, v in iteritems(self._orig_sys_module_state):
758 setattr(sys, k, v)
758 setattr(sys, k, v)
759 except AttributeError:
759 except AttributeError:
760 pass
760 pass
761 # Reset what what done in self.init_sys_modules
761 # Reset what what done in self.init_sys_modules
762 if self._orig_sys_modules_main_mod is not None:
762 if self._orig_sys_modules_main_mod is not None:
763 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
763 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
764
764
765 #-------------------------------------------------------------------------
765 #-------------------------------------------------------------------------
766 # Things related to hooks
766 # Things related to hooks
767 #-------------------------------------------------------------------------
767 #-------------------------------------------------------------------------
768
768
769 def init_hooks(self):
769 def init_hooks(self):
770 # hooks holds pointers used for user-side customizations
770 # hooks holds pointers used for user-side customizations
771 self.hooks = Struct()
771 self.hooks = Struct()
772
772
773 self.strdispatchers = {}
773 self.strdispatchers = {}
774
774
775 # Set all default hooks, defined in the IPython.hooks module.
775 # Set all default hooks, defined in the IPython.hooks module.
776 hooks = IPython.core.hooks
776 hooks = IPython.core.hooks
777 for hook_name in hooks.__all__:
777 for hook_name in hooks.__all__:
778 # default hooks have priority 100, i.e. low; user hooks should have
778 # default hooks have priority 100, i.e. low; user hooks should have
779 # 0-100 priority
779 # 0-100 priority
780 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
780 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
781
781
782 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
782 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
783 """set_hook(name,hook) -> sets an internal IPython hook.
783 """set_hook(name,hook) -> sets an internal IPython hook.
784
784
785 IPython exposes some of its internal API as user-modifiable hooks. By
785 IPython exposes some of its internal API as user-modifiable hooks. By
786 adding your function to one of these hooks, you can modify IPython's
786 adding your function to one of these hooks, you can modify IPython's
787 behavior to call at runtime your own routines."""
787 behavior to call at runtime your own routines."""
788
788
789 # At some point in the future, this should validate the hook before it
789 # At some point in the future, this should validate the hook before it
790 # accepts it. Probably at least check that the hook takes the number
790 # accepts it. Probably at least check that the hook takes the number
791 # of args it's supposed to.
791 # of args it's supposed to.
792
792
793 f = types.MethodType(hook,self)
793 f = types.MethodType(hook,self)
794
794
795 # check if the hook is for strdispatcher first
795 # check if the hook is for strdispatcher first
796 if str_key is not None:
796 if str_key is not None:
797 sdp = self.strdispatchers.get(name, StrDispatch())
797 sdp = self.strdispatchers.get(name, StrDispatch())
798 sdp.add_s(str_key, f, priority )
798 sdp.add_s(str_key, f, priority )
799 self.strdispatchers[name] = sdp
799 self.strdispatchers[name] = sdp
800 return
800 return
801 if re_key is not None:
801 if re_key is not None:
802 sdp = self.strdispatchers.get(name, StrDispatch())
802 sdp = self.strdispatchers.get(name, StrDispatch())
803 sdp.add_re(re.compile(re_key), f, priority )
803 sdp.add_re(re.compile(re_key), f, priority )
804 self.strdispatchers[name] = sdp
804 self.strdispatchers[name] = sdp
805 return
805 return
806
806
807 dp = getattr(self.hooks, name, None)
807 dp = getattr(self.hooks, name, None)
808 if name not in IPython.core.hooks.__all__:
808 if name not in IPython.core.hooks.__all__:
809 print("Warning! Hook '%s' is not one of %s" % \
809 print("Warning! Hook '%s' is not one of %s" % \
810 (name, IPython.core.hooks.__all__ ))
810 (name, IPython.core.hooks.__all__ ))
811 if not dp:
811 if not dp:
812 dp = IPython.core.hooks.CommandChainDispatcher()
812 dp = IPython.core.hooks.CommandChainDispatcher()
813
813
814 try:
814 try:
815 dp.add(f,priority)
815 dp.add(f,priority)
816 except AttributeError:
816 except AttributeError:
817 # it was not commandchain, plain old func - replace
817 # it was not commandchain, plain old func - replace
818 dp = f
818 dp = f
819
819
820 setattr(self.hooks,name, dp)
820 setattr(self.hooks,name, dp)
821
821
822 def register_post_execute(self, func):
822 def register_post_execute(self, func):
823 """Register a function for calling after code execution.
823 """Register a function for calling after code execution.
824 """
824 """
825 if not callable(func):
825 if not callable(func):
826 raise ValueError('argument %s must be callable' % func)
826 raise ValueError('argument %s must be callable' % func)
827 self._post_execute[func] = True
827 self._post_execute[func] = True
828
828
829 #-------------------------------------------------------------------------
829 #-------------------------------------------------------------------------
830 # Things related to the "main" module
830 # Things related to the "main" module
831 #-------------------------------------------------------------------------
831 #-------------------------------------------------------------------------
832
832
833 def new_main_mod(self, filename, modname):
833 def new_main_mod(self, filename, modname):
834 """Return a new 'main' module object for user code execution.
834 """Return a new 'main' module object for user code execution.
835
835
836 ``filename`` should be the path of the script which will be run in the
836 ``filename`` should be the path of the script which will be run in the
837 module. Requests with the same filename will get the same module, with
837 module. Requests with the same filename will get the same module, with
838 its namespace cleared.
838 its namespace cleared.
839
839
840 ``modname`` should be the module name - normally either '__main__' or
840 ``modname`` should be the module name - normally either '__main__' or
841 the basename of the file without the extension.
841 the basename of the file without the extension.
842
842
843 When scripts are executed via %run, we must keep a reference to their
843 When scripts are executed via %run, we must keep a reference to their
844 __main__ module around so that Python doesn't
844 __main__ module around so that Python doesn't
845 clear it, rendering references to module globals useless.
845 clear it, rendering references to module globals useless.
846
846
847 This method keeps said reference in a private dict, keyed by the
847 This method keeps said reference in a private dict, keyed by the
848 absolute path of the script. This way, for multiple executions of the
848 absolute path of the script. This way, for multiple executions of the
849 same script we only keep one copy of the namespace (the last one),
849 same script we only keep one copy of the namespace (the last one),
850 thus preventing memory leaks from old references while allowing the
850 thus preventing memory leaks from old references while allowing the
851 objects from the last execution to be accessible.
851 objects from the last execution to be accessible.
852 """
852 """
853 filename = os.path.abspath(filename)
853 filename = os.path.abspath(filename)
854 try:
854 try:
855 main_mod = self._main_mod_cache[filename]
855 main_mod = self._main_mod_cache[filename]
856 except KeyError:
856 except KeyError:
857 main_mod = self._main_mod_cache[filename] = types.ModuleType(modname,
857 main_mod = self._main_mod_cache[filename] = types.ModuleType(modname,
858 doc="Module created for script run in IPython")
858 doc="Module created for script run in IPython")
859 else:
859 else:
860 main_mod.__dict__.clear()
860 main_mod.__dict__.clear()
861 main_mod.__name__ = modname
861 main_mod.__name__ = modname
862
862
863 main_mod.__file__ = filename
863 main_mod.__file__ = filename
864 # It seems pydoc (and perhaps others) needs any module instance to
864 # It seems pydoc (and perhaps others) needs any module instance to
865 # implement a __nonzero__ method
865 # implement a __nonzero__ method
866 main_mod.__nonzero__ = lambda : True
866 main_mod.__nonzero__ = lambda : True
867
867
868 return main_mod
868 return main_mod
869
869
870 def clear_main_mod_cache(self):
870 def clear_main_mod_cache(self):
871 """Clear the cache of main modules.
871 """Clear the cache of main modules.
872
872
873 Mainly for use by utilities like %reset.
873 Mainly for use by utilities like %reset.
874
874
875 Examples
875 Examples
876 --------
876 --------
877
877
878 In [15]: import IPython
878 In [15]: import IPython
879
879
880 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
880 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
881
881
882 In [17]: len(_ip._main_mod_cache) > 0
882 In [17]: len(_ip._main_mod_cache) > 0
883 Out[17]: True
883 Out[17]: True
884
884
885 In [18]: _ip.clear_main_mod_cache()
885 In [18]: _ip.clear_main_mod_cache()
886
886
887 In [19]: len(_ip._main_mod_cache) == 0
887 In [19]: len(_ip._main_mod_cache) == 0
888 Out[19]: True
888 Out[19]: True
889 """
889 """
890 self._main_mod_cache.clear()
890 self._main_mod_cache.clear()
891
891
892 #-------------------------------------------------------------------------
892 #-------------------------------------------------------------------------
893 # Things related to debugging
893 # Things related to debugging
894 #-------------------------------------------------------------------------
894 #-------------------------------------------------------------------------
895
895
896 def init_pdb(self):
896 def init_pdb(self):
897 # Set calling of pdb on exceptions
897 # Set calling of pdb on exceptions
898 # self.call_pdb is a property
898 # self.call_pdb is a property
899 self.call_pdb = self.pdb
899 self.call_pdb = self.pdb
900
900
901 def _get_call_pdb(self):
901 def _get_call_pdb(self):
902 return self._call_pdb
902 return self._call_pdb
903
903
904 def _set_call_pdb(self,val):
904 def _set_call_pdb(self,val):
905
905
906 if val not in (0,1,False,True):
906 if val not in (0,1,False,True):
907 raise ValueError('new call_pdb value must be boolean')
907 raise ValueError('new call_pdb value must be boolean')
908
908
909 # store value in instance
909 # store value in instance
910 self._call_pdb = val
910 self._call_pdb = val
911
911
912 # notify the actual exception handlers
912 # notify the actual exception handlers
913 self.InteractiveTB.call_pdb = val
913 self.InteractiveTB.call_pdb = val
914
914
915 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
915 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
916 'Control auto-activation of pdb at exceptions')
916 'Control auto-activation of pdb at exceptions')
917
917
918 def debugger(self,force=False):
918 def debugger(self,force=False):
919 """Call the pydb/pdb debugger.
919 """Call the pydb/pdb debugger.
920
920
921 Keywords:
921 Keywords:
922
922
923 - force(False): by default, this routine checks the instance call_pdb
923 - force(False): by default, this routine checks the instance call_pdb
924 flag and does not actually invoke the debugger if the flag is false.
924 flag and does not actually invoke the debugger if the flag is false.
925 The 'force' option forces the debugger to activate even if the flag
925 The 'force' option forces the debugger to activate even if the flag
926 is false.
926 is false.
927 """
927 """
928
928
929 if not (force or self.call_pdb):
929 if not (force or self.call_pdb):
930 return
930 return
931
931
932 if not hasattr(sys,'last_traceback'):
932 if not hasattr(sys,'last_traceback'):
933 error('No traceback has been produced, nothing to debug.')
933 error('No traceback has been produced, nothing to debug.')
934 return
934 return
935
935
936 # use pydb if available
936 # use pydb if available
937 if debugger.has_pydb:
937 if debugger.has_pydb:
938 from pydb import pm
938 from pydb import pm
939 else:
939 else:
940 # fallback to our internal debugger
940 # fallback to our internal debugger
941 pm = lambda : self.InteractiveTB.debugger(force=True)
941 pm = lambda : self.InteractiveTB.debugger(force=True)
942
942
943 with self.readline_no_record:
943 with self.readline_no_record:
944 pm()
944 pm()
945
945
946 #-------------------------------------------------------------------------
946 #-------------------------------------------------------------------------
947 # Things related to IPython's various namespaces
947 # Things related to IPython's various namespaces
948 #-------------------------------------------------------------------------
948 #-------------------------------------------------------------------------
949 default_user_namespaces = True
949 default_user_namespaces = True
950
950
951 def init_create_namespaces(self, user_module=None, user_ns=None):
951 def init_create_namespaces(self, user_module=None, user_ns=None):
952 # Create the namespace where the user will operate. user_ns is
952 # Create the namespace where the user will operate. user_ns is
953 # normally the only one used, and it is passed to the exec calls as
953 # normally the only one used, and it is passed to the exec calls as
954 # the locals argument. But we do carry a user_global_ns namespace
954 # the locals argument. But we do carry a user_global_ns namespace
955 # given as the exec 'globals' argument, This is useful in embedding
955 # given as the exec 'globals' argument, This is useful in embedding
956 # situations where the ipython shell opens in a context where the
956 # situations where the ipython shell opens in a context where the
957 # distinction between locals and globals is meaningful. For
957 # distinction between locals and globals is meaningful. For
958 # non-embedded contexts, it is just the same object as the user_ns dict.
958 # non-embedded contexts, it is just the same object as the user_ns dict.
959
959
960 # FIXME. For some strange reason, __builtins__ is showing up at user
960 # FIXME. For some strange reason, __builtins__ is showing up at user
961 # level as a dict instead of a module. This is a manual fix, but I
961 # level as a dict instead of a module. This is a manual fix, but I
962 # should really track down where the problem is coming from. Alex
962 # should really track down where the problem is coming from. Alex
963 # Schmolck reported this problem first.
963 # Schmolck reported this problem first.
964
964
965 # A useful post by Alex Martelli on this topic:
965 # A useful post by Alex Martelli on this topic:
966 # Re: inconsistent value from __builtins__
966 # Re: inconsistent value from __builtins__
967 # Von: Alex Martelli <aleaxit@yahoo.com>
967 # Von: Alex Martelli <aleaxit@yahoo.com>
968 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
968 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
969 # Gruppen: comp.lang.python
969 # Gruppen: comp.lang.python
970
970
971 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
971 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
972 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
972 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
973 # > <type 'dict'>
973 # > <type 'dict'>
974 # > >>> print type(__builtins__)
974 # > >>> print type(__builtins__)
975 # > <type 'module'>
975 # > <type 'module'>
976 # > Is this difference in return value intentional?
976 # > Is this difference in return value intentional?
977
977
978 # Well, it's documented that '__builtins__' can be either a dictionary
978 # Well, it's documented that '__builtins__' can be either a dictionary
979 # or a module, and it's been that way for a long time. Whether it's
979 # or a module, and it's been that way for a long time. Whether it's
980 # intentional (or sensible), I don't know. In any case, the idea is
980 # intentional (or sensible), I don't know. In any case, the idea is
981 # that if you need to access the built-in namespace directly, you
981 # that if you need to access the built-in namespace directly, you
982 # should start with "import __builtin__" (note, no 's') which will
982 # should start with "import __builtin__" (note, no 's') which will
983 # definitely give you a module. Yeah, it's somewhat confusing:-(.
983 # definitely give you a module. Yeah, it's somewhat confusing:-(.
984
984
985 # These routines return a properly built module and dict as needed by
985 # These routines return a properly built module and dict as needed by
986 # the rest of the code, and can also be used by extension writers to
986 # the rest of the code, and can also be used by extension writers to
987 # generate properly initialized namespaces.
987 # generate properly initialized namespaces.
988 if (user_ns is not None) or (user_module is not None):
988 if (user_ns is not None) or (user_module is not None):
989 self.default_user_namespaces = False
989 self.default_user_namespaces = False
990 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
990 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
991
991
992 # A record of hidden variables we have added to the user namespace, so
992 # A record of hidden variables we have added to the user namespace, so
993 # we can list later only variables defined in actual interactive use.
993 # we can list later only variables defined in actual interactive use.
994 self.user_ns_hidden = {}
994 self.user_ns_hidden = {}
995
995
996 # Now that FakeModule produces a real module, we've run into a nasty
996 # Now that FakeModule produces a real module, we've run into a nasty
997 # problem: after script execution (via %run), the module where the user
997 # problem: after script execution (via %run), the module where the user
998 # code ran is deleted. Now that this object is a true module (needed
998 # code ran is deleted. Now that this object is a true module (needed
999 # so docetst and other tools work correctly), the Python module
999 # so docetst and other tools work correctly), the Python module
1000 # teardown mechanism runs over it, and sets to None every variable
1000 # teardown mechanism runs over it, and sets to None every variable
1001 # present in that module. Top-level references to objects from the
1001 # present in that module. Top-level references to objects from the
1002 # script survive, because the user_ns is updated with them. However,
1002 # script survive, because the user_ns is updated with them. However,
1003 # calling functions defined in the script that use other things from
1003 # calling functions defined in the script that use other things from
1004 # the script will fail, because the function's closure had references
1004 # the script will fail, because the function's closure had references
1005 # to the original objects, which are now all None. So we must protect
1005 # to the original objects, which are now all None. So we must protect
1006 # these modules from deletion by keeping a cache.
1006 # these modules from deletion by keeping a cache.
1007 #
1007 #
1008 # To avoid keeping stale modules around (we only need the one from the
1008 # To avoid keeping stale modules around (we only need the one from the
1009 # last run), we use a dict keyed with the full path to the script, so
1009 # last run), we use a dict keyed with the full path to the script, so
1010 # only the last version of the module is held in the cache. Note,
1010 # only the last version of the module is held in the cache. Note,
1011 # however, that we must cache the module *namespace contents* (their
1011 # however, that we must cache the module *namespace contents* (their
1012 # __dict__). Because if we try to cache the actual modules, old ones
1012 # __dict__). Because if we try to cache the actual modules, old ones
1013 # (uncached) could be destroyed while still holding references (such as
1013 # (uncached) could be destroyed while still holding references (such as
1014 # those held by GUI objects that tend to be long-lived)>
1014 # those held by GUI objects that tend to be long-lived)>
1015 #
1015 #
1016 # The %reset command will flush this cache. See the cache_main_mod()
1016 # The %reset command will flush this cache. See the cache_main_mod()
1017 # and clear_main_mod_cache() methods for details on use.
1017 # and clear_main_mod_cache() methods for details on use.
1018
1018
1019 # This is the cache used for 'main' namespaces
1019 # This is the cache used for 'main' namespaces
1020 self._main_mod_cache = {}
1020 self._main_mod_cache = {}
1021
1021
1022 # A table holding all the namespaces IPython deals with, so that
1022 # A table holding all the namespaces IPython deals with, so that
1023 # introspection facilities can search easily.
1023 # introspection facilities can search easily.
1024 self.ns_table = {'user_global':self.user_module.__dict__,
1024 self.ns_table = {'user_global':self.user_module.__dict__,
1025 'user_local':self.user_ns,
1025 'user_local':self.user_ns,
1026 'builtin':builtin_mod.__dict__
1026 'builtin':builtin_mod.__dict__
1027 }
1027 }
1028
1028
1029 @property
1029 @property
1030 def user_global_ns(self):
1030 def user_global_ns(self):
1031 return self.user_module.__dict__
1031 return self.user_module.__dict__
1032
1032
1033 def prepare_user_module(self, user_module=None, user_ns=None):
1033 def prepare_user_module(self, user_module=None, user_ns=None):
1034 """Prepare the module and namespace in which user code will be run.
1034 """Prepare the module and namespace in which user code will be run.
1035
1035
1036 When IPython is started normally, both parameters are None: a new module
1036 When IPython is started normally, both parameters are None: a new module
1037 is created automatically, and its __dict__ used as the namespace.
1037 is created automatically, and its __dict__ used as the namespace.
1038
1038
1039 If only user_module is provided, its __dict__ is used as the namespace.
1039 If only user_module is provided, its __dict__ is used as the namespace.
1040 If only user_ns is provided, a dummy module is created, and user_ns
1040 If only user_ns is provided, a dummy module is created, and user_ns
1041 becomes the global namespace. If both are provided (as they may be
1041 becomes the global namespace. If both are provided (as they may be
1042 when embedding), user_ns is the local namespace, and user_module
1042 when embedding), user_ns is the local namespace, and user_module
1043 provides the global namespace.
1043 provides the global namespace.
1044
1044
1045 Parameters
1045 Parameters
1046 ----------
1046 ----------
1047 user_module : module, optional
1047 user_module : module, optional
1048 The current user module in which IPython is being run. If None,
1048 The current user module in which IPython is being run. If None,
1049 a clean module will be created.
1049 a clean module will be created.
1050 user_ns : dict, optional
1050 user_ns : dict, optional
1051 A namespace in which to run interactive commands.
1051 A namespace in which to run interactive commands.
1052
1052
1053 Returns
1053 Returns
1054 -------
1054 -------
1055 A tuple of user_module and user_ns, each properly initialised.
1055 A tuple of user_module and user_ns, each properly initialised.
1056 """
1056 """
1057 if user_module is None and user_ns is not None:
1057 if user_module is None and user_ns is not None:
1058 user_ns.setdefault("__name__", "__main__")
1058 user_ns.setdefault("__name__", "__main__")
1059 user_module = DummyMod()
1059 user_module = DummyMod()
1060 user_module.__dict__ = user_ns
1060 user_module.__dict__ = user_ns
1061
1061
1062 if user_module is None:
1062 if user_module is None:
1063 user_module = types.ModuleType("__main__",
1063 user_module = types.ModuleType("__main__",
1064 doc="Automatically created module for IPython interactive environment")
1064 doc="Automatically created module for IPython interactive environment")
1065
1065
1066 # We must ensure that __builtin__ (without the final 's') is always
1066 # We must ensure that __builtin__ (without the final 's') is always
1067 # available and pointing to the __builtin__ *module*. For more details:
1067 # available and pointing to the __builtin__ *module*. For more details:
1068 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1068 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1069 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1069 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1070 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1070 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1071
1071
1072 if user_ns is None:
1072 if user_ns is None:
1073 user_ns = user_module.__dict__
1073 user_ns = user_module.__dict__
1074
1074
1075 return user_module, user_ns
1075 return user_module, user_ns
1076
1076
1077 def init_sys_modules(self):
1077 def init_sys_modules(self):
1078 # We need to insert into sys.modules something that looks like a
1078 # We need to insert into sys.modules something that looks like a
1079 # module but which accesses the IPython namespace, for shelve and
1079 # module but which accesses the IPython namespace, for shelve and
1080 # pickle to work interactively. Normally they rely on getting
1080 # pickle to work interactively. Normally they rely on getting
1081 # everything out of __main__, but for embedding purposes each IPython
1081 # everything out of __main__, but for embedding purposes each IPython
1082 # instance has its own private namespace, so we can't go shoving
1082 # instance has its own private namespace, so we can't go shoving
1083 # everything into __main__.
1083 # everything into __main__.
1084
1084
1085 # note, however, that we should only do this for non-embedded
1085 # note, however, that we should only do this for non-embedded
1086 # ipythons, which really mimic the __main__.__dict__ with their own
1086 # ipythons, which really mimic the __main__.__dict__ with their own
1087 # namespace. Embedded instances, on the other hand, should not do
1087 # namespace. Embedded instances, on the other hand, should not do
1088 # this because they need to manage the user local/global namespaces
1088 # this because they need to manage the user local/global namespaces
1089 # only, but they live within a 'normal' __main__ (meaning, they
1089 # only, but they live within a 'normal' __main__ (meaning, they
1090 # shouldn't overtake the execution environment of the script they're
1090 # shouldn't overtake the execution environment of the script they're
1091 # embedded in).
1091 # embedded in).
1092
1092
1093 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1093 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1094 main_name = self.user_module.__name__
1094 main_name = self.user_module.__name__
1095 sys.modules[main_name] = self.user_module
1095 sys.modules[main_name] = self.user_module
1096
1096
1097 def init_user_ns(self):
1097 def init_user_ns(self):
1098 """Initialize all user-visible namespaces to their minimum defaults.
1098 """Initialize all user-visible namespaces to their minimum defaults.
1099
1099
1100 Certain history lists are also initialized here, as they effectively
1100 Certain history lists are also initialized here, as they effectively
1101 act as user namespaces.
1101 act as user namespaces.
1102
1102
1103 Notes
1103 Notes
1104 -----
1104 -----
1105 All data structures here are only filled in, they are NOT reset by this
1105 All data structures here are only filled in, they are NOT reset by this
1106 method. If they were not empty before, data will simply be added to
1106 method. If they were not empty before, data will simply be added to
1107 therm.
1107 therm.
1108 """
1108 """
1109 # This function works in two parts: first we put a few things in
1109 # This function works in two parts: first we put a few things in
1110 # user_ns, and we sync that contents into user_ns_hidden so that these
1110 # user_ns, and we sync that contents into user_ns_hidden so that these
1111 # initial variables aren't shown by %who. After the sync, we add the
1111 # initial variables aren't shown by %who. After the sync, we add the
1112 # rest of what we *do* want the user to see with %who even on a new
1112 # rest of what we *do* want the user to see with %who even on a new
1113 # session (probably nothing, so theye really only see their own stuff)
1113 # session (probably nothing, so theye really only see their own stuff)
1114
1114
1115 # The user dict must *always* have a __builtin__ reference to the
1115 # The user dict must *always* have a __builtin__ reference to the
1116 # Python standard __builtin__ namespace, which must be imported.
1116 # Python standard __builtin__ namespace, which must be imported.
1117 # This is so that certain operations in prompt evaluation can be
1117 # This is so that certain operations in prompt evaluation can be
1118 # reliably executed with builtins. Note that we can NOT use
1118 # reliably executed with builtins. Note that we can NOT use
1119 # __builtins__ (note the 's'), because that can either be a dict or a
1119 # __builtins__ (note the 's'), because that can either be a dict or a
1120 # module, and can even mutate at runtime, depending on the context
1120 # module, and can even mutate at runtime, depending on the context
1121 # (Python makes no guarantees on it). In contrast, __builtin__ is
1121 # (Python makes no guarantees on it). In contrast, __builtin__ is
1122 # always a module object, though it must be explicitly imported.
1122 # always a module object, though it must be explicitly imported.
1123
1123
1124 # For more details:
1124 # For more details:
1125 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1125 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1126 ns = dict()
1126 ns = dict()
1127
1127
1128 # Put 'help' in the user namespace
1128 # Put 'help' in the user namespace
1129 try:
1129 try:
1130 from site import _Helper
1130 from site import _Helper
1131 ns['help'] = _Helper()
1131 ns['help'] = _Helper()
1132 except ImportError:
1132 except ImportError:
1133 warn('help() not available - check site.py')
1133 warn('help() not available - check site.py')
1134
1134
1135 # make global variables for user access to the histories
1135 # make global variables for user access to the histories
1136 ns['_ih'] = self.history_manager.input_hist_parsed
1136 ns['_ih'] = self.history_manager.input_hist_parsed
1137 ns['_oh'] = self.history_manager.output_hist
1137 ns['_oh'] = self.history_manager.output_hist
1138 ns['_dh'] = self.history_manager.dir_hist
1138 ns['_dh'] = self.history_manager.dir_hist
1139
1139
1140 ns['_sh'] = shadowns
1140 ns['_sh'] = shadowns
1141
1141
1142 # user aliases to input and output histories. These shouldn't show up
1142 # user aliases to input and output histories. These shouldn't show up
1143 # in %who, as they can have very large reprs.
1143 # in %who, as they can have very large reprs.
1144 ns['In'] = self.history_manager.input_hist_parsed
1144 ns['In'] = self.history_manager.input_hist_parsed
1145 ns['Out'] = self.history_manager.output_hist
1145 ns['Out'] = self.history_manager.output_hist
1146
1146
1147 # Store myself as the public api!!!
1147 # Store myself as the public api!!!
1148 ns['get_ipython'] = self.get_ipython
1148 ns['get_ipython'] = self.get_ipython
1149
1149
1150 ns['exit'] = self.exiter
1150 ns['exit'] = self.exiter
1151 ns['quit'] = self.exiter
1151 ns['quit'] = self.exiter
1152
1152
1153 # Sync what we've added so far to user_ns_hidden so these aren't seen
1153 # Sync what we've added so far to user_ns_hidden so these aren't seen
1154 # by %who
1154 # by %who
1155 self.user_ns_hidden.update(ns)
1155 self.user_ns_hidden.update(ns)
1156
1156
1157 # Anything put into ns now would show up in %who. Think twice before
1157 # Anything put into ns now would show up in %who. Think twice before
1158 # putting anything here, as we really want %who to show the user their
1158 # putting anything here, as we really want %who to show the user their
1159 # stuff, not our variables.
1159 # stuff, not our variables.
1160
1160
1161 # Finally, update the real user's namespace
1161 # Finally, update the real user's namespace
1162 self.user_ns.update(ns)
1162 self.user_ns.update(ns)
1163
1163
1164 @property
1164 @property
1165 def all_ns_refs(self):
1165 def all_ns_refs(self):
1166 """Get a list of references to all the namespace dictionaries in which
1166 """Get a list of references to all the namespace dictionaries in which
1167 IPython might store a user-created object.
1167 IPython might store a user-created object.
1168
1168
1169 Note that this does not include the displayhook, which also caches
1169 Note that this does not include the displayhook, which also caches
1170 objects from the output."""
1170 objects from the output."""
1171 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1171 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1172 [m.__dict__ for m in self._main_mod_cache.values()]
1172 [m.__dict__ for m in self._main_mod_cache.values()]
1173
1173
1174 def reset(self, new_session=True):
1174 def reset(self, new_session=True):
1175 """Clear all internal namespaces, and attempt to release references to
1175 """Clear all internal namespaces, and attempt to release references to
1176 user objects.
1176 user objects.
1177
1177
1178 If new_session is True, a new history session will be opened.
1178 If new_session is True, a new history session will be opened.
1179 """
1179 """
1180 # Clear histories
1180 # Clear histories
1181 self.history_manager.reset(new_session)
1181 self.history_manager.reset(new_session)
1182 # Reset counter used to index all histories
1182 # Reset counter used to index all histories
1183 if new_session:
1183 if new_session:
1184 self.execution_count = 1
1184 self.execution_count = 1
1185
1185
1186 # Flush cached output items
1186 # Flush cached output items
1187 if self.displayhook.do_full_cache:
1187 if self.displayhook.do_full_cache:
1188 self.displayhook.flush()
1188 self.displayhook.flush()
1189
1189
1190 # The main execution namespaces must be cleared very carefully,
1190 # The main execution namespaces must be cleared very carefully,
1191 # skipping the deletion of the builtin-related keys, because doing so
1191 # skipping the deletion of the builtin-related keys, because doing so
1192 # would cause errors in many object's __del__ methods.
1192 # would cause errors in many object's __del__ methods.
1193 if self.user_ns is not self.user_global_ns:
1193 if self.user_ns is not self.user_global_ns:
1194 self.user_ns.clear()
1194 self.user_ns.clear()
1195 ns = self.user_global_ns
1195 ns = self.user_global_ns
1196 drop_keys = set(ns.keys())
1196 drop_keys = set(ns.keys())
1197 drop_keys.discard('__builtin__')
1197 drop_keys.discard('__builtin__')
1198 drop_keys.discard('__builtins__')
1198 drop_keys.discard('__builtins__')
1199 drop_keys.discard('__name__')
1199 drop_keys.discard('__name__')
1200 for k in drop_keys:
1200 for k in drop_keys:
1201 del ns[k]
1201 del ns[k]
1202
1202
1203 self.user_ns_hidden.clear()
1203 self.user_ns_hidden.clear()
1204
1204
1205 # Restore the user namespaces to minimal usability
1205 # Restore the user namespaces to minimal usability
1206 self.init_user_ns()
1206 self.init_user_ns()
1207
1207
1208 # Restore the default and user aliases
1208 # Restore the default and user aliases
1209 self.alias_manager.clear_aliases()
1209 self.alias_manager.clear_aliases()
1210 self.alias_manager.init_aliases()
1210 self.alias_manager.init_aliases()
1211
1211
1212 # Flush the private list of module references kept for script
1212 # Flush the private list of module references kept for script
1213 # execution protection
1213 # execution protection
1214 self.clear_main_mod_cache()
1214 self.clear_main_mod_cache()
1215
1215
1216 def del_var(self, varname, by_name=False):
1216 def del_var(self, varname, by_name=False):
1217 """Delete a variable from the various namespaces, so that, as
1217 """Delete a variable from the various namespaces, so that, as
1218 far as possible, we're not keeping any hidden references to it.
1218 far as possible, we're not keeping any hidden references to it.
1219
1219
1220 Parameters
1220 Parameters
1221 ----------
1221 ----------
1222 varname : str
1222 varname : str
1223 The name of the variable to delete.
1223 The name of the variable to delete.
1224 by_name : bool
1224 by_name : bool
1225 If True, delete variables with the given name in each
1225 If True, delete variables with the given name in each
1226 namespace. If False (default), find the variable in the user
1226 namespace. If False (default), find the variable in the user
1227 namespace, and delete references to it.
1227 namespace, and delete references to it.
1228 """
1228 """
1229 if varname in ('__builtin__', '__builtins__'):
1229 if varname in ('__builtin__', '__builtins__'):
1230 raise ValueError("Refusing to delete %s" % varname)
1230 raise ValueError("Refusing to delete %s" % varname)
1231
1231
1232 ns_refs = self.all_ns_refs
1232 ns_refs = self.all_ns_refs
1233
1233
1234 if by_name: # Delete by name
1234 if by_name: # Delete by name
1235 for ns in ns_refs:
1235 for ns in ns_refs:
1236 try:
1236 try:
1237 del ns[varname]
1237 del ns[varname]
1238 except KeyError:
1238 except KeyError:
1239 pass
1239 pass
1240 else: # Delete by object
1240 else: # Delete by object
1241 try:
1241 try:
1242 obj = self.user_ns[varname]
1242 obj = self.user_ns[varname]
1243 except KeyError:
1243 except KeyError:
1244 raise NameError("name '%s' is not defined" % varname)
1244 raise NameError("name '%s' is not defined" % varname)
1245 # Also check in output history
1245 # Also check in output history
1246 ns_refs.append(self.history_manager.output_hist)
1246 ns_refs.append(self.history_manager.output_hist)
1247 for ns in ns_refs:
1247 for ns in ns_refs:
1248 to_delete = [n for n, o in iteritems(ns) if o is obj]
1248 to_delete = [n for n, o in iteritems(ns) if o is obj]
1249 for name in to_delete:
1249 for name in to_delete:
1250 del ns[name]
1250 del ns[name]
1251
1251
1252 # displayhook keeps extra references, but not in a dictionary
1252 # displayhook keeps extra references, but not in a dictionary
1253 for name in ('_', '__', '___'):
1253 for name in ('_', '__', '___'):
1254 if getattr(self.displayhook, name) is obj:
1254 if getattr(self.displayhook, name) is obj:
1255 setattr(self.displayhook, name, None)
1255 setattr(self.displayhook, name, None)
1256
1256
1257 def reset_selective(self, regex=None):
1257 def reset_selective(self, regex=None):
1258 """Clear selective variables from internal namespaces based on a
1258 """Clear selective variables from internal namespaces based on a
1259 specified regular expression.
1259 specified regular expression.
1260
1260
1261 Parameters
1261 Parameters
1262 ----------
1262 ----------
1263 regex : string or compiled pattern, optional
1263 regex : string or compiled pattern, optional
1264 A regular expression pattern that will be used in searching
1264 A regular expression pattern that will be used in searching
1265 variable names in the users namespaces.
1265 variable names in the users namespaces.
1266 """
1266 """
1267 if regex is not None:
1267 if regex is not None:
1268 try:
1268 try:
1269 m = re.compile(regex)
1269 m = re.compile(regex)
1270 except TypeError:
1270 except TypeError:
1271 raise TypeError('regex must be a string or compiled pattern')
1271 raise TypeError('regex must be a string or compiled pattern')
1272 # Search for keys in each namespace that match the given regex
1272 # Search for keys in each namespace that match the given regex
1273 # If a match is found, delete the key/value pair.
1273 # If a match is found, delete the key/value pair.
1274 for ns in self.all_ns_refs:
1274 for ns in self.all_ns_refs:
1275 for var in ns:
1275 for var in ns:
1276 if m.search(var):
1276 if m.search(var):
1277 del ns[var]
1277 del ns[var]
1278
1278
1279 def push(self, variables, interactive=True):
1279 def push(self, variables, interactive=True):
1280 """Inject a group of variables into the IPython user namespace.
1280 """Inject a group of variables into the IPython user namespace.
1281
1281
1282 Parameters
1282 Parameters
1283 ----------
1283 ----------
1284 variables : dict, str or list/tuple of str
1284 variables : dict, str or list/tuple of str
1285 The variables to inject into the user's namespace. If a dict, a
1285 The variables to inject into the user's namespace. If a dict, a
1286 simple update is done. If a str, the string is assumed to have
1286 simple update is done. If a str, the string is assumed to have
1287 variable names separated by spaces. A list/tuple of str can also
1287 variable names separated by spaces. A list/tuple of str can also
1288 be used to give the variable names. If just the variable names are
1288 be used to give the variable names. If just the variable names are
1289 give (list/tuple/str) then the variable values looked up in the
1289 give (list/tuple/str) then the variable values looked up in the
1290 callers frame.
1290 callers frame.
1291 interactive : bool
1291 interactive : bool
1292 If True (default), the variables will be listed with the ``who``
1292 If True (default), the variables will be listed with the ``who``
1293 magic.
1293 magic.
1294 """
1294 """
1295 vdict = None
1295 vdict = None
1296
1296
1297 # We need a dict of name/value pairs to do namespace updates.
1297 # We need a dict of name/value pairs to do namespace updates.
1298 if isinstance(variables, dict):
1298 if isinstance(variables, dict):
1299 vdict = variables
1299 vdict = variables
1300 elif isinstance(variables, string_types+(list, tuple)):
1300 elif isinstance(variables, string_types+(list, tuple)):
1301 if isinstance(variables, string_types):
1301 if isinstance(variables, string_types):
1302 vlist = variables.split()
1302 vlist = variables.split()
1303 else:
1303 else:
1304 vlist = variables
1304 vlist = variables
1305 vdict = {}
1305 vdict = {}
1306 cf = sys._getframe(1)
1306 cf = sys._getframe(1)
1307 for name in vlist:
1307 for name in vlist:
1308 try:
1308 try:
1309 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1309 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1310 except:
1310 except:
1311 print('Could not get variable %s from %s' %
1311 print('Could not get variable %s from %s' %
1312 (name,cf.f_code.co_name))
1312 (name,cf.f_code.co_name))
1313 else:
1313 else:
1314 raise ValueError('variables must be a dict/str/list/tuple')
1314 raise ValueError('variables must be a dict/str/list/tuple')
1315
1315
1316 # Propagate variables to user namespace
1316 # Propagate variables to user namespace
1317 self.user_ns.update(vdict)
1317 self.user_ns.update(vdict)
1318
1318
1319 # And configure interactive visibility
1319 # And configure interactive visibility
1320 user_ns_hidden = self.user_ns_hidden
1320 user_ns_hidden = self.user_ns_hidden
1321 if interactive:
1321 if interactive:
1322 for name in vdict:
1322 for name in vdict:
1323 user_ns_hidden.pop(name, None)
1323 user_ns_hidden.pop(name, None)
1324 else:
1324 else:
1325 user_ns_hidden.update(vdict)
1325 user_ns_hidden.update(vdict)
1326
1326
1327 def drop_by_id(self, variables):
1327 def drop_by_id(self, variables):
1328 """Remove a dict of variables from the user namespace, if they are the
1328 """Remove a dict of variables from the user namespace, if they are the
1329 same as the values in the dictionary.
1329 same as the values in the dictionary.
1330
1330
1331 This is intended for use by extensions: variables that they've added can
1331 This is intended for use by extensions: variables that they've added can
1332 be taken back out if they are unloaded, without removing any that the
1332 be taken back out if they are unloaded, without removing any that the
1333 user has overwritten.
1333 user has overwritten.
1334
1334
1335 Parameters
1335 Parameters
1336 ----------
1336 ----------
1337 variables : dict
1337 variables : dict
1338 A dictionary mapping object names (as strings) to the objects.
1338 A dictionary mapping object names (as strings) to the objects.
1339 """
1339 """
1340 for name, obj in iteritems(variables):
1340 for name, obj in iteritems(variables):
1341 if name in self.user_ns and self.user_ns[name] is obj:
1341 if name in self.user_ns and self.user_ns[name] is obj:
1342 del self.user_ns[name]
1342 del self.user_ns[name]
1343 self.user_ns_hidden.pop(name, None)
1343 self.user_ns_hidden.pop(name, None)
1344
1344
1345 #-------------------------------------------------------------------------
1345 #-------------------------------------------------------------------------
1346 # Things related to object introspection
1346 # Things related to object introspection
1347 #-------------------------------------------------------------------------
1347 #-------------------------------------------------------------------------
1348
1348
1349 def _ofind(self, oname, namespaces=None):
1349 def _ofind(self, oname, namespaces=None):
1350 """Find an object in the available namespaces.
1350 """Find an object in the available namespaces.
1351
1351
1352 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1352 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1353
1353
1354 Has special code to detect magic functions.
1354 Has special code to detect magic functions.
1355 """
1355 """
1356 oname = oname.strip()
1356 oname = oname.strip()
1357 #print '1- oname: <%r>' % oname # dbg
1357 #print '1- oname: <%r>' % oname # dbg
1358 if not oname.startswith(ESC_MAGIC) and \
1358 if not oname.startswith(ESC_MAGIC) and \
1359 not oname.startswith(ESC_MAGIC2) and \
1359 not oname.startswith(ESC_MAGIC2) and \
1360 not py3compat.isidentifier(oname, dotted=True):
1360 not py3compat.isidentifier(oname, dotted=True):
1361 return dict(found=False)
1361 return dict(found=False)
1362
1362
1363 alias_ns = None
1363 alias_ns = None
1364 if namespaces is None:
1364 if namespaces is None:
1365 # Namespaces to search in:
1365 # Namespaces to search in:
1366 # Put them in a list. The order is important so that we
1366 # Put them in a list. The order is important so that we
1367 # find things in the same order that Python finds them.
1367 # find things in the same order that Python finds them.
1368 namespaces = [ ('Interactive', self.user_ns),
1368 namespaces = [ ('Interactive', self.user_ns),
1369 ('Interactive (global)', self.user_global_ns),
1369 ('Interactive (global)', self.user_global_ns),
1370 ('Python builtin', builtin_mod.__dict__),
1370 ('Python builtin', builtin_mod.__dict__),
1371 ]
1371 ]
1372
1372
1373 # initialize results to 'null'
1373 # initialize results to 'null'
1374 found = False; obj = None; ospace = None; ds = None;
1374 found = False; obj = None; ospace = None; ds = None;
1375 ismagic = False; isalias = False; parent = None
1375 ismagic = False; isalias = False; parent = None
1376
1376
1377 # We need to special-case 'print', which as of python2.6 registers as a
1377 # We need to special-case 'print', which as of python2.6 registers as a
1378 # function but should only be treated as one if print_function was
1378 # function but should only be treated as one if print_function was
1379 # loaded with a future import. In this case, just bail.
1379 # loaded with a future import. In this case, just bail.
1380 if (oname == 'print' and not py3compat.PY3 and not \
1380 if (oname == 'print' and not py3compat.PY3 and not \
1381 (self.compile.compiler_flags & __future__.CO_FUTURE_PRINT_FUNCTION)):
1381 (self.compile.compiler_flags & __future__.CO_FUTURE_PRINT_FUNCTION)):
1382 return {'found':found, 'obj':obj, 'namespace':ospace,
1382 return {'found':found, 'obj':obj, 'namespace':ospace,
1383 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1383 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1384
1384
1385 # Look for the given name by splitting it in parts. If the head is
1385 # Look for the given name by splitting it in parts. If the head is
1386 # found, then we look for all the remaining parts as members, and only
1386 # found, then we look for all the remaining parts as members, and only
1387 # declare success if we can find them all.
1387 # declare success if we can find them all.
1388 oname_parts = oname.split('.')
1388 oname_parts = oname.split('.')
1389 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1389 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1390 for nsname,ns in namespaces:
1390 for nsname,ns in namespaces:
1391 try:
1391 try:
1392 obj = ns[oname_head]
1392 obj = ns[oname_head]
1393 except KeyError:
1393 except KeyError:
1394 continue
1394 continue
1395 else:
1395 else:
1396 #print 'oname_rest:', oname_rest # dbg
1396 #print 'oname_rest:', oname_rest # dbg
1397 for part in oname_rest:
1397 for part in oname_rest:
1398 try:
1398 try:
1399 parent = obj
1399 parent = obj
1400 obj = getattr(obj,part)
1400 obj = getattr(obj,part)
1401 except:
1401 except:
1402 # Blanket except b/c some badly implemented objects
1402 # Blanket except b/c some badly implemented objects
1403 # allow __getattr__ to raise exceptions other than
1403 # allow __getattr__ to raise exceptions other than
1404 # AttributeError, which then crashes IPython.
1404 # AttributeError, which then crashes IPython.
1405 break
1405 break
1406 else:
1406 else:
1407 # If we finish the for loop (no break), we got all members
1407 # If we finish the for loop (no break), we got all members
1408 found = True
1408 found = True
1409 ospace = nsname
1409 ospace = nsname
1410 break # namespace loop
1410 break # namespace loop
1411
1411
1412 # Try to see if it's magic
1412 # Try to see if it's magic
1413 if not found:
1413 if not found:
1414 obj = None
1414 obj = None
1415 if oname.startswith(ESC_MAGIC2):
1415 if oname.startswith(ESC_MAGIC2):
1416 oname = oname.lstrip(ESC_MAGIC2)
1416 oname = oname.lstrip(ESC_MAGIC2)
1417 obj = self.find_cell_magic(oname)
1417 obj = self.find_cell_magic(oname)
1418 elif oname.startswith(ESC_MAGIC):
1418 elif oname.startswith(ESC_MAGIC):
1419 oname = oname.lstrip(ESC_MAGIC)
1419 oname = oname.lstrip(ESC_MAGIC)
1420 obj = self.find_line_magic(oname)
1420 obj = self.find_line_magic(oname)
1421 else:
1421 else:
1422 # search without prefix, so run? will find %run?
1422 # search without prefix, so run? will find %run?
1423 obj = self.find_line_magic(oname)
1423 obj = self.find_line_magic(oname)
1424 if obj is None:
1424 if obj is None:
1425 obj = self.find_cell_magic(oname)
1425 obj = self.find_cell_magic(oname)
1426 if obj is not None:
1426 if obj is not None:
1427 found = True
1427 found = True
1428 ospace = 'IPython internal'
1428 ospace = 'IPython internal'
1429 ismagic = True
1429 ismagic = True
1430
1430
1431 # Last try: special-case some literals like '', [], {}, etc:
1431 # Last try: special-case some literals like '', [], {}, etc:
1432 if not found and oname_head in ["''",'""','[]','{}','()']:
1432 if not found and oname_head in ["''",'""','[]','{}','()']:
1433 obj = eval(oname_head)
1433 obj = eval(oname_head)
1434 found = True
1434 found = True
1435 ospace = 'Interactive'
1435 ospace = 'Interactive'
1436
1436
1437 return {'found':found, 'obj':obj, 'namespace':ospace,
1437 return {'found':found, 'obj':obj, 'namespace':ospace,
1438 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1438 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1439
1439
1440 def _ofind_property(self, oname, info):
1440 def _ofind_property(self, oname, info):
1441 """Second part of object finding, to look for property details."""
1441 """Second part of object finding, to look for property details."""
1442 if info.found:
1442 if info.found:
1443 # Get the docstring of the class property if it exists.
1443 # Get the docstring of the class property if it exists.
1444 path = oname.split('.')
1444 path = oname.split('.')
1445 root = '.'.join(path[:-1])
1445 root = '.'.join(path[:-1])
1446 if info.parent is not None:
1446 if info.parent is not None:
1447 try:
1447 try:
1448 target = getattr(info.parent, '__class__')
1448 target = getattr(info.parent, '__class__')
1449 # The object belongs to a class instance.
1449 # The object belongs to a class instance.
1450 try:
1450 try:
1451 target = getattr(target, path[-1])
1451 target = getattr(target, path[-1])
1452 # The class defines the object.
1452 # The class defines the object.
1453 if isinstance(target, property):
1453 if isinstance(target, property):
1454 oname = root + '.__class__.' + path[-1]
1454 oname = root + '.__class__.' + path[-1]
1455 info = Struct(self._ofind(oname))
1455 info = Struct(self._ofind(oname))
1456 except AttributeError: pass
1456 except AttributeError: pass
1457 except AttributeError: pass
1457 except AttributeError: pass
1458
1458
1459 # We return either the new info or the unmodified input if the object
1459 # We return either the new info or the unmodified input if the object
1460 # hadn't been found
1460 # hadn't been found
1461 return info
1461 return info
1462
1462
1463 def _object_find(self, oname, namespaces=None):
1463 def _object_find(self, oname, namespaces=None):
1464 """Find an object and return a struct with info about it."""
1464 """Find an object and return a struct with info about it."""
1465 inf = Struct(self._ofind(oname, namespaces))
1465 inf = Struct(self._ofind(oname, namespaces))
1466 return Struct(self._ofind_property(oname, inf))
1466 return Struct(self._ofind_property(oname, inf))
1467
1467
1468 def _inspect(self, meth, oname, namespaces=None, **kw):
1468 def _inspect(self, meth, oname, namespaces=None, **kw):
1469 """Generic interface to the inspector system.
1469 """Generic interface to the inspector system.
1470
1470
1471 This function is meant to be called by pdef, pdoc & friends."""
1471 This function is meant to be called by pdef, pdoc & friends."""
1472 info = self._object_find(oname, namespaces)
1472 info = self._object_find(oname, namespaces)
1473 if info.found:
1473 if info.found:
1474 pmethod = getattr(self.inspector, meth)
1474 pmethod = getattr(self.inspector, meth)
1475 formatter = format_screen if info.ismagic else None
1475 formatter = format_screen if info.ismagic else None
1476 if meth == 'pdoc':
1476 if meth == 'pdoc':
1477 pmethod(info.obj, oname, formatter)
1477 pmethod(info.obj, oname, formatter)
1478 elif meth == 'pinfo':
1478 elif meth == 'pinfo':
1479 pmethod(info.obj, oname, formatter, info, **kw)
1479 pmethod(info.obj, oname, formatter, info, **kw)
1480 else:
1480 else:
1481 pmethod(info.obj, oname)
1481 pmethod(info.obj, oname)
1482 else:
1482 else:
1483 print('Object `%s` not found.' % oname)
1483 print('Object `%s` not found.' % oname)
1484 return 'not found' # so callers can take other action
1484 return 'not found' # so callers can take other action
1485
1485
1486 def object_inspect(self, oname, detail_level=0):
1486 def object_inspect(self, oname, detail_level=0):
1487 with self.builtin_trap:
1487 with self.builtin_trap:
1488 info = self._object_find(oname)
1488 info = self._object_find(oname)
1489 if info.found:
1489 if info.found:
1490 return self.inspector.info(info.obj, oname, info=info,
1490 return self.inspector.info(info.obj, oname, info=info,
1491 detail_level=detail_level
1491 detail_level=detail_level
1492 )
1492 )
1493 else:
1493 else:
1494 return oinspect.object_info(name=oname, found=False)
1494 return oinspect.object_info(name=oname, found=False)
1495
1495
1496 #-------------------------------------------------------------------------
1496 #-------------------------------------------------------------------------
1497 # Things related to history management
1497 # Things related to history management
1498 #-------------------------------------------------------------------------
1498 #-------------------------------------------------------------------------
1499
1499
1500 def init_history(self):
1500 def init_history(self):
1501 """Sets up the command history, and starts regular autosaves."""
1501 """Sets up the command history, and starts regular autosaves."""
1502 self.history_manager = HistoryManager(shell=self, parent=self)
1502 self.history_manager = HistoryManager(shell=self, parent=self)
1503 self.configurables.append(self.history_manager)
1503 self.configurables.append(self.history_manager)
1504
1504
1505 #-------------------------------------------------------------------------
1505 #-------------------------------------------------------------------------
1506 # Things related to exception handling and tracebacks (not debugging)
1506 # Things related to exception handling and tracebacks (not debugging)
1507 #-------------------------------------------------------------------------
1507 #-------------------------------------------------------------------------
1508
1508
1509 def init_traceback_handlers(self, custom_exceptions):
1509 def init_traceback_handlers(self, custom_exceptions):
1510 # Syntax error handler.
1510 # Syntax error handler.
1511 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1511 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1512
1512
1513 # The interactive one is initialized with an offset, meaning we always
1513 # The interactive one is initialized with an offset, meaning we always
1514 # want to remove the topmost item in the traceback, which is our own
1514 # want to remove the topmost item in the traceback, which is our own
1515 # internal code. Valid modes: ['Plain','Context','Verbose']
1515 # internal code. Valid modes: ['Plain','Context','Verbose']
1516 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1516 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1517 color_scheme='NoColor',
1517 color_scheme='NoColor',
1518 tb_offset = 1,
1518 tb_offset = 1,
1519 check_cache=check_linecache_ipython)
1519 check_cache=check_linecache_ipython)
1520
1520
1521 # The instance will store a pointer to the system-wide exception hook,
1521 # The instance will store a pointer to the system-wide exception hook,
1522 # so that runtime code (such as magics) can access it. This is because
1522 # so that runtime code (such as magics) can access it. This is because
1523 # during the read-eval loop, it may get temporarily overwritten.
1523 # during the read-eval loop, it may get temporarily overwritten.
1524 self.sys_excepthook = sys.excepthook
1524 self.sys_excepthook = sys.excepthook
1525
1525
1526 # and add any custom exception handlers the user may have specified
1526 # and add any custom exception handlers the user may have specified
1527 self.set_custom_exc(*custom_exceptions)
1527 self.set_custom_exc(*custom_exceptions)
1528
1528
1529 # Set the exception mode
1529 # Set the exception mode
1530 self.InteractiveTB.set_mode(mode=self.xmode)
1530 self.InteractiveTB.set_mode(mode=self.xmode)
1531
1531
1532 def set_custom_exc(self, exc_tuple, handler):
1532 def set_custom_exc(self, exc_tuple, handler):
1533 """set_custom_exc(exc_tuple,handler)
1533 """set_custom_exc(exc_tuple,handler)
1534
1534
1535 Set a custom exception handler, which will be called if any of the
1535 Set a custom exception handler, which will be called if any of the
1536 exceptions in exc_tuple occur in the mainloop (specifically, in the
1536 exceptions in exc_tuple occur in the mainloop (specifically, in the
1537 run_code() method).
1537 run_code() method).
1538
1538
1539 Parameters
1539 Parameters
1540 ----------
1540 ----------
1541
1541
1542 exc_tuple : tuple of exception classes
1542 exc_tuple : tuple of exception classes
1543 A *tuple* of exception classes, for which to call the defined
1543 A *tuple* of exception classes, for which to call the defined
1544 handler. It is very important that you use a tuple, and NOT A
1544 handler. It is very important that you use a tuple, and NOT A
1545 LIST here, because of the way Python's except statement works. If
1545 LIST here, because of the way Python's except statement works. If
1546 you only want to trap a single exception, use a singleton tuple::
1546 you only want to trap a single exception, use a singleton tuple::
1547
1547
1548 exc_tuple == (MyCustomException,)
1548 exc_tuple == (MyCustomException,)
1549
1549
1550 handler : callable
1550 handler : callable
1551 handler must have the following signature::
1551 handler must have the following signature::
1552
1552
1553 def my_handler(self, etype, value, tb, tb_offset=None):
1553 def my_handler(self, etype, value, tb, tb_offset=None):
1554 ...
1554 ...
1555 return structured_traceback
1555 return structured_traceback
1556
1556
1557 Your handler must return a structured traceback (a list of strings),
1557 Your handler must return a structured traceback (a list of strings),
1558 or None.
1558 or None.
1559
1559
1560 This will be made into an instance method (via types.MethodType)
1560 This will be made into an instance method (via types.MethodType)
1561 of IPython itself, and it will be called if any of the exceptions
1561 of IPython itself, and it will be called if any of the exceptions
1562 listed in the exc_tuple are caught. If the handler is None, an
1562 listed in the exc_tuple are caught. If the handler is None, an
1563 internal basic one is used, which just prints basic info.
1563 internal basic one is used, which just prints basic info.
1564
1564
1565 To protect IPython from crashes, if your handler ever raises an
1565 To protect IPython from crashes, if your handler ever raises an
1566 exception or returns an invalid result, it will be immediately
1566 exception or returns an invalid result, it will be immediately
1567 disabled.
1567 disabled.
1568
1568
1569 WARNING: by putting in your own exception handler into IPython's main
1569 WARNING: by putting in your own exception handler into IPython's main
1570 execution loop, you run a very good chance of nasty crashes. This
1570 execution loop, you run a very good chance of nasty crashes. This
1571 facility should only be used if you really know what you are doing."""
1571 facility should only be used if you really know what you are doing."""
1572
1572
1573 assert type(exc_tuple)==type(()) , \
1573 assert type(exc_tuple)==type(()) , \
1574 "The custom exceptions must be given AS A TUPLE."
1574 "The custom exceptions must be given AS A TUPLE."
1575
1575
1576 def dummy_handler(self,etype,value,tb,tb_offset=None):
1576 def dummy_handler(self,etype,value,tb,tb_offset=None):
1577 print('*** Simple custom exception handler ***')
1577 print('*** Simple custom exception handler ***')
1578 print('Exception type :',etype)
1578 print('Exception type :',etype)
1579 print('Exception value:',value)
1579 print('Exception value:',value)
1580 print('Traceback :',tb)
1580 print('Traceback :',tb)
1581 #print 'Source code :','\n'.join(self.buffer)
1581 #print 'Source code :','\n'.join(self.buffer)
1582
1582
1583 def validate_stb(stb):
1583 def validate_stb(stb):
1584 """validate structured traceback return type
1584 """validate structured traceback return type
1585
1585
1586 return type of CustomTB *should* be a list of strings, but allow
1586 return type of CustomTB *should* be a list of strings, but allow
1587 single strings or None, which are harmless.
1587 single strings or None, which are harmless.
1588
1588
1589 This function will *always* return a list of strings,
1589 This function will *always* return a list of strings,
1590 and will raise a TypeError if stb is inappropriate.
1590 and will raise a TypeError if stb is inappropriate.
1591 """
1591 """
1592 msg = "CustomTB must return list of strings, not %r" % stb
1592 msg = "CustomTB must return list of strings, not %r" % stb
1593 if stb is None:
1593 if stb is None:
1594 return []
1594 return []
1595 elif isinstance(stb, string_types):
1595 elif isinstance(stb, string_types):
1596 return [stb]
1596 return [stb]
1597 elif not isinstance(stb, list):
1597 elif not isinstance(stb, list):
1598 raise TypeError(msg)
1598 raise TypeError(msg)
1599 # it's a list
1599 # it's a list
1600 for line in stb:
1600 for line in stb:
1601 # check every element
1601 # check every element
1602 if not isinstance(line, string_types):
1602 if not isinstance(line, string_types):
1603 raise TypeError(msg)
1603 raise TypeError(msg)
1604 return stb
1604 return stb
1605
1605
1606 if handler is None:
1606 if handler is None:
1607 wrapped = dummy_handler
1607 wrapped = dummy_handler
1608 else:
1608 else:
1609 def wrapped(self,etype,value,tb,tb_offset=None):
1609 def wrapped(self,etype,value,tb,tb_offset=None):
1610 """wrap CustomTB handler, to protect IPython from user code
1610 """wrap CustomTB handler, to protect IPython from user code
1611
1611
1612 This makes it harder (but not impossible) for custom exception
1612 This makes it harder (but not impossible) for custom exception
1613 handlers to crash IPython.
1613 handlers to crash IPython.
1614 """
1614 """
1615 try:
1615 try:
1616 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1616 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1617 return validate_stb(stb)
1617 return validate_stb(stb)
1618 except:
1618 except:
1619 # clear custom handler immediately
1619 # clear custom handler immediately
1620 self.set_custom_exc((), None)
1620 self.set_custom_exc((), None)
1621 print("Custom TB Handler failed, unregistering", file=io.stderr)
1621 print("Custom TB Handler failed, unregistering", file=io.stderr)
1622 # show the exception in handler first
1622 # show the exception in handler first
1623 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1623 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1624 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1624 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1625 print("The original exception:", file=io.stdout)
1625 print("The original exception:", file=io.stdout)
1626 stb = self.InteractiveTB.structured_traceback(
1626 stb = self.InteractiveTB.structured_traceback(
1627 (etype,value,tb), tb_offset=tb_offset
1627 (etype,value,tb), tb_offset=tb_offset
1628 )
1628 )
1629 return stb
1629 return stb
1630
1630
1631 self.CustomTB = types.MethodType(wrapped,self)
1631 self.CustomTB = types.MethodType(wrapped,self)
1632 self.custom_exceptions = exc_tuple
1632 self.custom_exceptions = exc_tuple
1633
1633
1634 def excepthook(self, etype, value, tb):
1634 def excepthook(self, etype, value, tb):
1635 """One more defense for GUI apps that call sys.excepthook.
1635 """One more defense for GUI apps that call sys.excepthook.
1636
1636
1637 GUI frameworks like wxPython trap exceptions and call
1637 GUI frameworks like wxPython trap exceptions and call
1638 sys.excepthook themselves. I guess this is a feature that
1638 sys.excepthook themselves. I guess this is a feature that
1639 enables them to keep running after exceptions that would
1639 enables them to keep running after exceptions that would
1640 otherwise kill their mainloop. This is a bother for IPython
1640 otherwise kill their mainloop. This is a bother for IPython
1641 which excepts to catch all of the program exceptions with a try:
1641 which excepts to catch all of the program exceptions with a try:
1642 except: statement.
1642 except: statement.
1643
1643
1644 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1644 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1645 any app directly invokes sys.excepthook, it will look to the user like
1645 any app directly invokes sys.excepthook, it will look to the user like
1646 IPython crashed. In order to work around this, we can disable the
1646 IPython crashed. In order to work around this, we can disable the
1647 CrashHandler and replace it with this excepthook instead, which prints a
1647 CrashHandler and replace it with this excepthook instead, which prints a
1648 regular traceback using our InteractiveTB. In this fashion, apps which
1648 regular traceback using our InteractiveTB. In this fashion, apps which
1649 call sys.excepthook will generate a regular-looking exception from
1649 call sys.excepthook will generate a regular-looking exception from
1650 IPython, and the CrashHandler will only be triggered by real IPython
1650 IPython, and the CrashHandler will only be triggered by real IPython
1651 crashes.
1651 crashes.
1652
1652
1653 This hook should be used sparingly, only in places which are not likely
1653 This hook should be used sparingly, only in places which are not likely
1654 to be true IPython errors.
1654 to be true IPython errors.
1655 """
1655 """
1656 self.showtraceback((etype,value,tb),tb_offset=0)
1656 self.showtraceback((etype,value,tb),tb_offset=0)
1657
1657
1658 def _get_exc_info(self, exc_tuple=None):
1658 def _get_exc_info(self, exc_tuple=None):
1659 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1659 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1660
1660
1661 Ensures sys.last_type,value,traceback hold the exc_info we found,
1661 Ensures sys.last_type,value,traceback hold the exc_info we found,
1662 from whichever source.
1662 from whichever source.
1663
1663
1664 raises ValueError if none of these contain any information
1664 raises ValueError if none of these contain any information
1665 """
1665 """
1666 if exc_tuple is None:
1666 if exc_tuple is None:
1667 etype, value, tb = sys.exc_info()
1667 etype, value, tb = sys.exc_info()
1668 else:
1668 else:
1669 etype, value, tb = exc_tuple
1669 etype, value, tb = exc_tuple
1670
1670
1671 if etype is None:
1671 if etype is None:
1672 if hasattr(sys, 'last_type'):
1672 if hasattr(sys, 'last_type'):
1673 etype, value, tb = sys.last_type, sys.last_value, \
1673 etype, value, tb = sys.last_type, sys.last_value, \
1674 sys.last_traceback
1674 sys.last_traceback
1675
1675
1676 if etype is None:
1676 if etype is None:
1677 raise ValueError("No exception to find")
1677 raise ValueError("No exception to find")
1678
1678
1679 # Now store the exception info in sys.last_type etc.
1679 # Now store the exception info in sys.last_type etc.
1680 # WARNING: these variables are somewhat deprecated and not
1680 # WARNING: these variables are somewhat deprecated and not
1681 # necessarily safe to use in a threaded environment, but tools
1681 # necessarily safe to use in a threaded environment, but tools
1682 # like pdb depend on their existence, so let's set them. If we
1682 # like pdb depend on their existence, so let's set them. If we
1683 # find problems in the field, we'll need to revisit their use.
1683 # find problems in the field, we'll need to revisit their use.
1684 sys.last_type = etype
1684 sys.last_type = etype
1685 sys.last_value = value
1685 sys.last_value = value
1686 sys.last_traceback = tb
1686 sys.last_traceback = tb
1687
1687
1688 return etype, value, tb
1688 return etype, value, tb
1689
1689
1690 def show_usage_error(self, exc):
1690 def show_usage_error(self, exc):
1691 """Show a short message for UsageErrors
1691 """Show a short message for UsageErrors
1692
1692
1693 These are special exceptions that shouldn't show a traceback.
1693 These are special exceptions that shouldn't show a traceback.
1694 """
1694 """
1695 self.write_err("UsageError: %s" % exc)
1695 self.write_err("UsageError: %s" % exc)
1696
1696
1697 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1697 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1698 exception_only=False):
1698 exception_only=False):
1699 """Display the exception that just occurred.
1699 """Display the exception that just occurred.
1700
1700
1701 If nothing is known about the exception, this is the method which
1701 If nothing is known about the exception, this is the method which
1702 should be used throughout the code for presenting user tracebacks,
1702 should be used throughout the code for presenting user tracebacks,
1703 rather than directly invoking the InteractiveTB object.
1703 rather than directly invoking the InteractiveTB object.
1704
1704
1705 A specific showsyntaxerror() also exists, but this method can take
1705 A specific showsyntaxerror() also exists, but this method can take
1706 care of calling it if needed, so unless you are explicitly catching a
1706 care of calling it if needed, so unless you are explicitly catching a
1707 SyntaxError exception, don't try to analyze the stack manually and
1707 SyntaxError exception, don't try to analyze the stack manually and
1708 simply call this method."""
1708 simply call this method."""
1709
1709
1710 try:
1710 try:
1711 try:
1711 try:
1712 etype, value, tb = self._get_exc_info(exc_tuple)
1712 etype, value, tb = self._get_exc_info(exc_tuple)
1713 except ValueError:
1713 except ValueError:
1714 self.write_err('No traceback available to show.\n')
1714 self.write_err('No traceback available to show.\n')
1715 return
1715 return
1716
1716
1717 if issubclass(etype, SyntaxError):
1717 if issubclass(etype, SyntaxError):
1718 # Though this won't be called by syntax errors in the input
1718 # Though this won't be called by syntax errors in the input
1719 # line, there may be SyntaxError cases with imported code.
1719 # line, there may be SyntaxError cases with imported code.
1720 self.showsyntaxerror(filename)
1720 self.showsyntaxerror(filename)
1721 elif etype is UsageError:
1721 elif etype is UsageError:
1722 self.show_usage_error(value)
1722 self.show_usage_error(value)
1723 else:
1723 else:
1724 if exception_only:
1724 if exception_only:
1725 stb = ['An exception has occurred, use %tb to see '
1725 stb = ['An exception has occurred, use %tb to see '
1726 'the full traceback.\n']
1726 'the full traceback.\n']
1727 stb.extend(self.InteractiveTB.get_exception_only(etype,
1727 stb.extend(self.InteractiveTB.get_exception_only(etype,
1728 value))
1728 value))
1729 else:
1729 else:
1730 try:
1730 try:
1731 # Exception classes can customise their traceback - we
1731 # Exception classes can customise their traceback - we
1732 # use this in IPython.parallel for exceptions occurring
1732 # use this in IPython.parallel for exceptions occurring
1733 # in the engines. This should return a list of strings.
1733 # in the engines. This should return a list of strings.
1734 stb = value._render_traceback_()
1734 stb = value._render_traceback_()
1735 except Exception:
1735 except Exception:
1736 stb = self.InteractiveTB.structured_traceback(etype,
1736 stb = self.InteractiveTB.structured_traceback(etype,
1737 value, tb, tb_offset=tb_offset)
1737 value, tb, tb_offset=tb_offset)
1738
1738
1739 self._showtraceback(etype, value, stb)
1739 self._showtraceback(etype, value, stb)
1740 if self.call_pdb:
1740 if self.call_pdb:
1741 # drop into debugger
1741 # drop into debugger
1742 self.debugger(force=True)
1742 self.debugger(force=True)
1743 return
1743 return
1744
1744
1745 # Actually show the traceback
1745 # Actually show the traceback
1746 self._showtraceback(etype, value, stb)
1746 self._showtraceback(etype, value, stb)
1747
1747
1748 except KeyboardInterrupt:
1748 except KeyboardInterrupt:
1749 self.write_err("\nKeyboardInterrupt\n")
1749 self.write_err("\nKeyboardInterrupt\n")
1750
1750
1751 def _showtraceback(self, etype, evalue, stb):
1751 def _showtraceback(self, etype, evalue, stb):
1752 """Actually show a traceback.
1752 """Actually show a traceback.
1753
1753
1754 Subclasses may override this method to put the traceback on a different
1754 Subclasses may override this method to put the traceback on a different
1755 place, like a side channel.
1755 place, like a side channel.
1756 """
1756 """
1757 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1757 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1758
1758
1759 def showsyntaxerror(self, filename=None):
1759 def showsyntaxerror(self, filename=None):
1760 """Display the syntax error that just occurred.
1760 """Display the syntax error that just occurred.
1761
1761
1762 This doesn't display a stack trace because there isn't one.
1762 This doesn't display a stack trace because there isn't one.
1763
1763
1764 If a filename is given, it is stuffed in the exception instead
1764 If a filename is given, it is stuffed in the exception instead
1765 of what was there before (because Python's parser always uses
1765 of what was there before (because Python's parser always uses
1766 "<string>" when reading from a string).
1766 "<string>" when reading from a string).
1767 """
1767 """
1768 etype, value, last_traceback = self._get_exc_info()
1768 etype, value, last_traceback = self._get_exc_info()
1769
1769
1770 if filename and issubclass(etype, SyntaxError):
1770 if filename and issubclass(etype, SyntaxError):
1771 try:
1771 try:
1772 value.filename = filename
1772 value.filename = filename
1773 except:
1773 except:
1774 # Not the format we expect; leave it alone
1774 # Not the format we expect; leave it alone
1775 pass
1775 pass
1776
1776
1777 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1777 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1778 self._showtraceback(etype, value, stb)
1778 self._showtraceback(etype, value, stb)
1779
1779
1780 # This is overridden in TerminalInteractiveShell to show a message about
1780 # This is overridden in TerminalInteractiveShell to show a message about
1781 # the %paste magic.
1781 # the %paste magic.
1782 def showindentationerror(self):
1782 def showindentationerror(self):
1783 """Called by run_cell when there's an IndentationError in code entered
1783 """Called by run_cell when there's an IndentationError in code entered
1784 at the prompt.
1784 at the prompt.
1785
1785
1786 This is overridden in TerminalInteractiveShell to show a message about
1786 This is overridden in TerminalInteractiveShell to show a message about
1787 the %paste magic."""
1787 the %paste magic."""
1788 self.showsyntaxerror()
1788 self.showsyntaxerror()
1789
1789
1790 #-------------------------------------------------------------------------
1790 #-------------------------------------------------------------------------
1791 # Things related to readline
1791 # Things related to readline
1792 #-------------------------------------------------------------------------
1792 #-------------------------------------------------------------------------
1793
1793
1794 def init_readline(self):
1794 def init_readline(self):
1795 """Command history completion/saving/reloading."""
1795 """Command history completion/saving/reloading."""
1796
1796
1797 if self.readline_use:
1797 if self.readline_use:
1798 import IPython.utils.rlineimpl as readline
1798 import IPython.utils.rlineimpl as readline
1799
1799
1800 self.rl_next_input = None
1800 self.rl_next_input = None
1801 self.rl_do_indent = False
1801 self.rl_do_indent = False
1802
1802
1803 if not self.readline_use or not readline.have_readline:
1803 if not self.readline_use or not readline.have_readline:
1804 self.has_readline = False
1804 self.has_readline = False
1805 self.readline = None
1805 self.readline = None
1806 # Set a number of methods that depend on readline to be no-op
1806 # Set a number of methods that depend on readline to be no-op
1807 self.readline_no_record = no_op_context
1807 self.readline_no_record = no_op_context
1808 self.set_readline_completer = no_op
1808 self.set_readline_completer = no_op
1809 self.set_custom_completer = no_op
1809 self.set_custom_completer = no_op
1810 if self.readline_use:
1810 if self.readline_use:
1811 warn('Readline services not available or not loaded.')
1811 warn('Readline services not available or not loaded.')
1812 else:
1812 else:
1813 self.has_readline = True
1813 self.has_readline = True
1814 self.readline = readline
1814 self.readline = readline
1815 sys.modules['readline'] = readline
1815 sys.modules['readline'] = readline
1816
1816
1817 # Platform-specific configuration
1817 # Platform-specific configuration
1818 if os.name == 'nt':
1818 if os.name == 'nt':
1819 # FIXME - check with Frederick to see if we can harmonize
1819 # FIXME - check with Frederick to see if we can harmonize
1820 # naming conventions with pyreadline to avoid this
1820 # naming conventions with pyreadline to avoid this
1821 # platform-dependent check
1821 # platform-dependent check
1822 self.readline_startup_hook = readline.set_pre_input_hook
1822 self.readline_startup_hook = readline.set_pre_input_hook
1823 else:
1823 else:
1824 self.readline_startup_hook = readline.set_startup_hook
1824 self.readline_startup_hook = readline.set_startup_hook
1825
1825
1826 # Load user's initrc file (readline config)
1826 # Load user's initrc file (readline config)
1827 # Or if libedit is used, load editrc.
1827 # Or if libedit is used, load editrc.
1828 inputrc_name = os.environ.get('INPUTRC')
1828 inputrc_name = os.environ.get('INPUTRC')
1829 if inputrc_name is None:
1829 if inputrc_name is None:
1830 inputrc_name = '.inputrc'
1830 inputrc_name = '.inputrc'
1831 if readline.uses_libedit:
1831 if readline.uses_libedit:
1832 inputrc_name = '.editrc'
1832 inputrc_name = '.editrc'
1833 inputrc_name = os.path.join(self.home_dir, inputrc_name)
1833 inputrc_name = os.path.join(self.home_dir, inputrc_name)
1834 if os.path.isfile(inputrc_name):
1834 if os.path.isfile(inputrc_name):
1835 try:
1835 try:
1836 readline.read_init_file(inputrc_name)
1836 readline.read_init_file(inputrc_name)
1837 except:
1837 except:
1838 warn('Problems reading readline initialization file <%s>'
1838 warn('Problems reading readline initialization file <%s>'
1839 % inputrc_name)
1839 % inputrc_name)
1840
1840
1841 # Configure readline according to user's prefs
1841 # Configure readline according to user's prefs
1842 # This is only done if GNU readline is being used. If libedit
1842 # This is only done if GNU readline is being used. If libedit
1843 # is being used (as on Leopard) the readline config is
1843 # is being used (as on Leopard) the readline config is
1844 # not run as the syntax for libedit is different.
1844 # not run as the syntax for libedit is different.
1845 if not readline.uses_libedit:
1845 if not readline.uses_libedit:
1846 for rlcommand in self.readline_parse_and_bind:
1846 for rlcommand in self.readline_parse_and_bind:
1847 #print "loading rl:",rlcommand # dbg
1847 #print "loading rl:",rlcommand # dbg
1848 readline.parse_and_bind(rlcommand)
1848 readline.parse_and_bind(rlcommand)
1849
1849
1850 # Remove some chars from the delimiters list. If we encounter
1850 # Remove some chars from the delimiters list. If we encounter
1851 # unicode chars, discard them.
1851 # unicode chars, discard them.
1852 delims = readline.get_completer_delims()
1852 delims = readline.get_completer_delims()
1853 if not py3compat.PY3:
1853 if not py3compat.PY3:
1854 delims = delims.encode("ascii", "ignore")
1854 delims = delims.encode("ascii", "ignore")
1855 for d in self.readline_remove_delims:
1855 for d in self.readline_remove_delims:
1856 delims = delims.replace(d, "")
1856 delims = delims.replace(d, "")
1857 delims = delims.replace(ESC_MAGIC, '')
1857 delims = delims.replace(ESC_MAGIC, '')
1858 readline.set_completer_delims(delims)
1858 readline.set_completer_delims(delims)
1859 # Store these so we can restore them if something like rpy2 modifies
1859 # Store these so we can restore them if something like rpy2 modifies
1860 # them.
1860 # them.
1861 self.readline_delims = delims
1861 self.readline_delims = delims
1862 # otherwise we end up with a monster history after a while:
1862 # otherwise we end up with a monster history after a while:
1863 readline.set_history_length(self.history_length)
1863 readline.set_history_length(self.history_length)
1864
1864
1865 self.refill_readline_hist()
1865 self.refill_readline_hist()
1866 self.readline_no_record = ReadlineNoRecord(self)
1866 self.readline_no_record = ReadlineNoRecord(self)
1867
1867
1868 # Configure auto-indent for all platforms
1868 # Configure auto-indent for all platforms
1869 self.set_autoindent(self.autoindent)
1869 self.set_autoindent(self.autoindent)
1870
1870
1871 def refill_readline_hist(self):
1871 def refill_readline_hist(self):
1872 # Load the last 1000 lines from history
1872 # Load the last 1000 lines from history
1873 self.readline.clear_history()
1873 self.readline.clear_history()
1874 stdin_encoding = sys.stdin.encoding or "utf-8"
1874 stdin_encoding = sys.stdin.encoding or "utf-8"
1875 last_cell = u""
1875 last_cell = u""
1876 for _, _, cell in self.history_manager.get_tail(1000,
1876 for _, _, cell in self.history_manager.get_tail(1000,
1877 include_latest=True):
1877 include_latest=True):
1878 # Ignore blank lines and consecutive duplicates
1878 # Ignore blank lines and consecutive duplicates
1879 cell = cell.rstrip()
1879 cell = cell.rstrip()
1880 if cell and (cell != last_cell):
1880 if cell and (cell != last_cell):
1881 try:
1881 try:
1882 if self.multiline_history:
1882 if self.multiline_history:
1883 self.readline.add_history(py3compat.unicode_to_str(cell,
1883 self.readline.add_history(py3compat.unicode_to_str(cell,
1884 stdin_encoding))
1884 stdin_encoding))
1885 else:
1885 else:
1886 for line in cell.splitlines():
1886 for line in cell.splitlines():
1887 self.readline.add_history(py3compat.unicode_to_str(line,
1887 self.readline.add_history(py3compat.unicode_to_str(line,
1888 stdin_encoding))
1888 stdin_encoding))
1889 last_cell = cell
1889 last_cell = cell
1890
1890
1891 except TypeError:
1891 except TypeError:
1892 # The history DB can get corrupted so it returns strings
1892 # The history DB can get corrupted so it returns strings
1893 # containing null bytes, which readline objects to.
1893 # containing null bytes, which readline objects to.
1894 continue
1894 continue
1895
1895
1896 @skip_doctest
1896 @skip_doctest
1897 def set_next_input(self, s):
1897 def set_next_input(self, s):
1898 """ Sets the 'default' input string for the next command line.
1898 """ Sets the 'default' input string for the next command line.
1899
1899
1900 Requires readline.
1900 Requires readline.
1901
1901
1902 Example::
1902 Example::
1903
1903
1904 In [1]: _ip.set_next_input("Hello Word")
1904 In [1]: _ip.set_next_input("Hello Word")
1905 In [2]: Hello Word_ # cursor is here
1905 In [2]: Hello Word_ # cursor is here
1906 """
1906 """
1907 self.rl_next_input = py3compat.cast_bytes_py2(s)
1907 self.rl_next_input = py3compat.cast_bytes_py2(s)
1908
1908
1909 # Maybe move this to the terminal subclass?
1909 # Maybe move this to the terminal subclass?
1910 def pre_readline(self):
1910 def pre_readline(self):
1911 """readline hook to be used at the start of each line.
1911 """readline hook to be used at the start of each line.
1912
1912
1913 Currently it handles auto-indent only."""
1913 Currently it handles auto-indent only."""
1914
1914
1915 if self.rl_do_indent:
1915 if self.rl_do_indent:
1916 self.readline.insert_text(self._indent_current_str())
1916 self.readline.insert_text(self._indent_current_str())
1917 if self.rl_next_input is not None:
1917 if self.rl_next_input is not None:
1918 self.readline.insert_text(self.rl_next_input)
1918 self.readline.insert_text(self.rl_next_input)
1919 self.rl_next_input = None
1919 self.rl_next_input = None
1920
1920
1921 def _indent_current_str(self):
1921 def _indent_current_str(self):
1922 """return the current level of indentation as a string"""
1922 """return the current level of indentation as a string"""
1923 return self.input_splitter.indent_spaces * ' '
1923 return self.input_splitter.indent_spaces * ' '
1924
1924
1925 #-------------------------------------------------------------------------
1925 #-------------------------------------------------------------------------
1926 # Things related to text completion
1926 # Things related to text completion
1927 #-------------------------------------------------------------------------
1927 #-------------------------------------------------------------------------
1928
1928
1929 def init_completer(self):
1929 def init_completer(self):
1930 """Initialize the completion machinery.
1930 """Initialize the completion machinery.
1931
1931
1932 This creates completion machinery that can be used by client code,
1932 This creates completion machinery that can be used by client code,
1933 either interactively in-process (typically triggered by the readline
1933 either interactively in-process (typically triggered by the readline
1934 library), programatically (such as in test suites) or out-of-prcess
1934 library), programatically (such as in test suites) or out-of-prcess
1935 (typically over the network by remote frontends).
1935 (typically over the network by remote frontends).
1936 """
1936 """
1937 from IPython.core.completer import IPCompleter
1937 from IPython.core.completer import IPCompleter
1938 from IPython.core.completerlib import (module_completer,
1938 from IPython.core.completerlib import (module_completer,
1939 magic_run_completer, cd_completer, reset_completer)
1939 magic_run_completer, cd_completer, reset_completer)
1940
1940
1941 self.Completer = IPCompleter(shell=self,
1941 self.Completer = IPCompleter(shell=self,
1942 namespace=self.user_ns,
1942 namespace=self.user_ns,
1943 global_namespace=self.user_global_ns,
1943 global_namespace=self.user_global_ns,
1944 use_readline=self.has_readline,
1944 use_readline=self.has_readline,
1945 parent=self,
1945 parent=self,
1946 )
1946 )
1947 self.configurables.append(self.Completer)
1947 self.configurables.append(self.Completer)
1948
1948
1949 # Add custom completers to the basic ones built into IPCompleter
1949 # Add custom completers to the basic ones built into IPCompleter
1950 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1950 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1951 self.strdispatchers['complete_command'] = sdisp
1951 self.strdispatchers['complete_command'] = sdisp
1952 self.Completer.custom_completers = sdisp
1952 self.Completer.custom_completers = sdisp
1953
1953
1954 self.set_hook('complete_command', module_completer, str_key = 'import')
1954 self.set_hook('complete_command', module_completer, str_key = 'import')
1955 self.set_hook('complete_command', module_completer, str_key = 'from')
1955 self.set_hook('complete_command', module_completer, str_key = 'from')
1956 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1956 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1957 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1957 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1958 self.set_hook('complete_command', reset_completer, str_key = '%reset')
1958 self.set_hook('complete_command', reset_completer, str_key = '%reset')
1959
1959
1960 # Only configure readline if we truly are using readline. IPython can
1960 # Only configure readline if we truly are using readline. IPython can
1961 # do tab-completion over the network, in GUIs, etc, where readline
1961 # do tab-completion over the network, in GUIs, etc, where readline
1962 # itself may be absent
1962 # itself may be absent
1963 if self.has_readline:
1963 if self.has_readline:
1964 self.set_readline_completer()
1964 self.set_readline_completer()
1965
1965
1966 def complete(self, text, line=None, cursor_pos=None):
1966 def complete(self, text, line=None, cursor_pos=None):
1967 """Return the completed text and a list of completions.
1967 """Return the completed text and a list of completions.
1968
1968
1969 Parameters
1969 Parameters
1970 ----------
1970 ----------
1971
1971
1972 text : string
1972 text : string
1973 A string of text to be completed on. It can be given as empty and
1973 A string of text to be completed on. It can be given as empty and
1974 instead a line/position pair are given. In this case, the
1974 instead a line/position pair are given. In this case, the
1975 completer itself will split the line like readline does.
1975 completer itself will split the line like readline does.
1976
1976
1977 line : string, optional
1977 line : string, optional
1978 The complete line that text is part of.
1978 The complete line that text is part of.
1979
1979
1980 cursor_pos : int, optional
1980 cursor_pos : int, optional
1981 The position of the cursor on the input line.
1981 The position of the cursor on the input line.
1982
1982
1983 Returns
1983 Returns
1984 -------
1984 -------
1985 text : string
1985 text : string
1986 The actual text that was completed.
1986 The actual text that was completed.
1987
1987
1988 matches : list
1988 matches : list
1989 A sorted list with all possible completions.
1989 A sorted list with all possible completions.
1990
1990
1991 The optional arguments allow the completion to take more context into
1991 The optional arguments allow the completion to take more context into
1992 account, and are part of the low-level completion API.
1992 account, and are part of the low-level completion API.
1993
1993
1994 This is a wrapper around the completion mechanism, similar to what
1994 This is a wrapper around the completion mechanism, similar to what
1995 readline does at the command line when the TAB key is hit. By
1995 readline does at the command line when the TAB key is hit. By
1996 exposing it as a method, it can be used by other non-readline
1996 exposing it as a method, it can be used by other non-readline
1997 environments (such as GUIs) for text completion.
1997 environments (such as GUIs) for text completion.
1998
1998
1999 Simple usage example:
1999 Simple usage example:
2000
2000
2001 In [1]: x = 'hello'
2001 In [1]: x = 'hello'
2002
2002
2003 In [2]: _ip.complete('x.l')
2003 In [2]: _ip.complete('x.l')
2004 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2004 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2005 """
2005 """
2006
2006
2007 # Inject names into __builtin__ so we can complete on the added names.
2007 # Inject names into __builtin__ so we can complete on the added names.
2008 with self.builtin_trap:
2008 with self.builtin_trap:
2009 return self.Completer.complete(text, line, cursor_pos)
2009 return self.Completer.complete(text, line, cursor_pos)
2010
2010
2011 def set_custom_completer(self, completer, pos=0):
2011 def set_custom_completer(self, completer, pos=0):
2012 """Adds a new custom completer function.
2012 """Adds a new custom completer function.
2013
2013
2014 The position argument (defaults to 0) is the index in the completers
2014 The position argument (defaults to 0) is the index in the completers
2015 list where you want the completer to be inserted."""
2015 list where you want the completer to be inserted."""
2016
2016
2017 newcomp = types.MethodType(completer,self.Completer)
2017 newcomp = types.MethodType(completer,self.Completer)
2018 self.Completer.matchers.insert(pos,newcomp)
2018 self.Completer.matchers.insert(pos,newcomp)
2019
2019
2020 def set_readline_completer(self):
2020 def set_readline_completer(self):
2021 """Reset readline's completer to be our own."""
2021 """Reset readline's completer to be our own."""
2022 self.readline.set_completer(self.Completer.rlcomplete)
2022 self.readline.set_completer(self.Completer.rlcomplete)
2023
2023
2024 def set_completer_frame(self, frame=None):
2024 def set_completer_frame(self, frame=None):
2025 """Set the frame of the completer."""
2025 """Set the frame of the completer."""
2026 if frame:
2026 if frame:
2027 self.Completer.namespace = frame.f_locals
2027 self.Completer.namespace = frame.f_locals
2028 self.Completer.global_namespace = frame.f_globals
2028 self.Completer.global_namespace = frame.f_globals
2029 else:
2029 else:
2030 self.Completer.namespace = self.user_ns
2030 self.Completer.namespace = self.user_ns
2031 self.Completer.global_namespace = self.user_global_ns
2031 self.Completer.global_namespace = self.user_global_ns
2032
2032
2033 #-------------------------------------------------------------------------
2033 #-------------------------------------------------------------------------
2034 # Things related to magics
2034 # Things related to magics
2035 #-------------------------------------------------------------------------
2035 #-------------------------------------------------------------------------
2036
2036
2037 def init_magics(self):
2037 def init_magics(self):
2038 from IPython.core import magics as m
2038 from IPython.core import magics as m
2039 self.magics_manager = magic.MagicsManager(shell=self,
2039 self.magics_manager = magic.MagicsManager(shell=self,
2040 parent=self,
2040 parent=self,
2041 user_magics=m.UserMagics(self))
2041 user_magics=m.UserMagics(self))
2042 self.configurables.append(self.magics_manager)
2042 self.configurables.append(self.magics_manager)
2043
2043
2044 # Expose as public API from the magics manager
2044 # Expose as public API from the magics manager
2045 self.register_magics = self.magics_manager.register
2045 self.register_magics = self.magics_manager.register
2046 self.define_magic = self.magics_manager.define_magic
2046 self.define_magic = self.magics_manager.define_magic
2047
2047
2048 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2048 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2049 m.ConfigMagics, m.DeprecatedMagics, m.DisplayMagics, m.ExecutionMagics,
2049 m.ConfigMagics, m.DeprecatedMagics, m.DisplayMagics, m.ExecutionMagics,
2050 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2050 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2051 m.NamespaceMagics, m.OSMagics, m.PylabMagics, m.ScriptMagics,
2051 m.NamespaceMagics, m.OSMagics, m.PylabMagics, m.ScriptMagics,
2052 )
2052 )
2053
2053
2054 # Register Magic Aliases
2054 # Register Magic Aliases
2055 mman = self.magics_manager
2055 mman = self.magics_manager
2056 # FIXME: magic aliases should be defined by the Magics classes
2056 # FIXME: magic aliases should be defined by the Magics classes
2057 # or in MagicsManager, not here
2057 # or in MagicsManager, not here
2058 mman.register_alias('ed', 'edit')
2058 mman.register_alias('ed', 'edit')
2059 mman.register_alias('hist', 'history')
2059 mman.register_alias('hist', 'history')
2060 mman.register_alias('rep', 'recall')
2060 mman.register_alias('rep', 'recall')
2061 mman.register_alias('SVG', 'svg', 'cell')
2061 mman.register_alias('SVG', 'svg', 'cell')
2062 mman.register_alias('HTML', 'html', 'cell')
2062 mman.register_alias('HTML', 'html', 'cell')
2063 mman.register_alias('file', 'writefile', 'cell')
2063 mman.register_alias('file', 'writefile', 'cell')
2064
2064
2065 # FIXME: Move the color initialization to the DisplayHook, which
2065 # FIXME: Move the color initialization to the DisplayHook, which
2066 # should be split into a prompt manager and displayhook. We probably
2066 # should be split into a prompt manager and displayhook. We probably
2067 # even need a centralize colors management object.
2067 # even need a centralize colors management object.
2068 self.magic('colors %s' % self.colors)
2068 self.magic('colors %s' % self.colors)
2069
2069
2070 # Defined here so that it's included in the documentation
2070 # Defined here so that it's included in the documentation
2071 @functools.wraps(magic.MagicsManager.register_function)
2071 @functools.wraps(magic.MagicsManager.register_function)
2072 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2072 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2073 self.magics_manager.register_function(func,
2073 self.magics_manager.register_function(func,
2074 magic_kind=magic_kind, magic_name=magic_name)
2074 magic_kind=magic_kind, magic_name=magic_name)
2075
2075
2076 def run_line_magic(self, magic_name, line):
2076 def run_line_magic(self, magic_name, line):
2077 """Execute the given line magic.
2077 """Execute the given line magic.
2078
2078
2079 Parameters
2079 Parameters
2080 ----------
2080 ----------
2081 magic_name : str
2081 magic_name : str
2082 Name of the desired magic function, without '%' prefix.
2082 Name of the desired magic function, without '%' prefix.
2083
2083
2084 line : str
2084 line : str
2085 The rest of the input line as a single string.
2085 The rest of the input line as a single string.
2086 """
2086 """
2087 fn = self.find_line_magic(magic_name)
2087 fn = self.find_line_magic(magic_name)
2088 if fn is None:
2088 if fn is None:
2089 cm = self.find_cell_magic(magic_name)
2089 cm = self.find_cell_magic(magic_name)
2090 etpl = "Line magic function `%%%s` not found%s."
2090 etpl = "Line magic function `%%%s` not found%s."
2091 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2091 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2092 'did you mean that instead?)' % magic_name )
2092 'did you mean that instead?)' % magic_name )
2093 error(etpl % (magic_name, extra))
2093 error(etpl % (magic_name, extra))
2094 else:
2094 else:
2095 # Note: this is the distance in the stack to the user's frame.
2095 # Note: this is the distance in the stack to the user's frame.
2096 # This will need to be updated if the internal calling logic gets
2096 # This will need to be updated if the internal calling logic gets
2097 # refactored, or else we'll be expanding the wrong variables.
2097 # refactored, or else we'll be expanding the wrong variables.
2098 stack_depth = 2
2098 stack_depth = 2
2099 magic_arg_s = self.var_expand(line, stack_depth)
2099 magic_arg_s = self.var_expand(line, stack_depth)
2100 # Put magic args in a list so we can call with f(*a) syntax
2100 # Put magic args in a list so we can call with f(*a) syntax
2101 args = [magic_arg_s]
2101 args = [magic_arg_s]
2102 kwargs = {}
2102 kwargs = {}
2103 # Grab local namespace if we need it:
2103 # Grab local namespace if we need it:
2104 if getattr(fn, "needs_local_scope", False):
2104 if getattr(fn, "needs_local_scope", False):
2105 kwargs['local_ns'] = sys._getframe(stack_depth).f_locals
2105 kwargs['local_ns'] = sys._getframe(stack_depth).f_locals
2106 with self.builtin_trap:
2106 with self.builtin_trap:
2107 result = fn(*args,**kwargs)
2107 result = fn(*args,**kwargs)
2108 return result
2108 return result
2109
2109
2110 def run_cell_magic(self, magic_name, line, cell):
2110 def run_cell_magic(self, magic_name, line, cell):
2111 """Execute the given cell magic.
2111 """Execute the given cell magic.
2112
2112
2113 Parameters
2113 Parameters
2114 ----------
2114 ----------
2115 magic_name : str
2115 magic_name : str
2116 Name of the desired magic function, without '%' prefix.
2116 Name of the desired magic function, without '%' prefix.
2117
2117
2118 line : str
2118 line : str
2119 The rest of the first input line as a single string.
2119 The rest of the first input line as a single string.
2120
2120
2121 cell : str
2121 cell : str
2122 The body of the cell as a (possibly multiline) string.
2122 The body of the cell as a (possibly multiline) string.
2123 """
2123 """
2124 fn = self.find_cell_magic(magic_name)
2124 fn = self.find_cell_magic(magic_name)
2125 if fn is None:
2125 if fn is None:
2126 lm = self.find_line_magic(magic_name)
2126 lm = self.find_line_magic(magic_name)
2127 etpl = "Cell magic `%%{0}` not found{1}."
2127 etpl = "Cell magic `%%{0}` not found{1}."
2128 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2128 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2129 'did you mean that instead?)'.format(magic_name))
2129 'did you mean that instead?)'.format(magic_name))
2130 error(etpl.format(magic_name, extra))
2130 error(etpl.format(magic_name, extra))
2131 elif cell == '':
2131 elif cell == '':
2132 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2132 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2133 if self.find_line_magic(magic_name) is not None:
2133 if self.find_line_magic(magic_name) is not None:
2134 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2134 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2135 raise UsageError(message)
2135 raise UsageError(message)
2136 else:
2136 else:
2137 # Note: this is the distance in the stack to the user's frame.
2137 # Note: this is the distance in the stack to the user's frame.
2138 # This will need to be updated if the internal calling logic gets
2138 # This will need to be updated if the internal calling logic gets
2139 # refactored, or else we'll be expanding the wrong variables.
2139 # refactored, or else we'll be expanding the wrong variables.
2140 stack_depth = 2
2140 stack_depth = 2
2141 magic_arg_s = self.var_expand(line, stack_depth)
2141 magic_arg_s = self.var_expand(line, stack_depth)
2142 with self.builtin_trap:
2142 with self.builtin_trap:
2143 result = fn(magic_arg_s, cell)
2143 result = fn(magic_arg_s, cell)
2144 return result
2144 return result
2145
2145
2146 def find_line_magic(self, magic_name):
2146 def find_line_magic(self, magic_name):
2147 """Find and return a line magic by name.
2147 """Find and return a line magic by name.
2148
2148
2149 Returns None if the magic isn't found."""
2149 Returns None if the magic isn't found."""
2150 return self.magics_manager.magics['line'].get(magic_name)
2150 return self.magics_manager.magics['line'].get(magic_name)
2151
2151
2152 def find_cell_magic(self, magic_name):
2152 def find_cell_magic(self, magic_name):
2153 """Find and return a cell magic by name.
2153 """Find and return a cell magic by name.
2154
2154
2155 Returns None if the magic isn't found."""
2155 Returns None if the magic isn't found."""
2156 return self.magics_manager.magics['cell'].get(magic_name)
2156 return self.magics_manager.magics['cell'].get(magic_name)
2157
2157
2158 def find_magic(self, magic_name, magic_kind='line'):
2158 def find_magic(self, magic_name, magic_kind='line'):
2159 """Find and return a magic of the given type by name.
2159 """Find and return a magic of the given type by name.
2160
2160
2161 Returns None if the magic isn't found."""
2161 Returns None if the magic isn't found."""
2162 return self.magics_manager.magics[magic_kind].get(magic_name)
2162 return self.magics_manager.magics[magic_kind].get(magic_name)
2163
2163
2164 def magic(self, arg_s):
2164 def magic(self, arg_s):
2165 """DEPRECATED. Use run_line_magic() instead.
2165 """DEPRECATED. Use run_line_magic() instead.
2166
2166
2167 Call a magic function by name.
2167 Call a magic function by name.
2168
2168
2169 Input: a string containing the name of the magic function to call and
2169 Input: a string containing the name of the magic function to call and
2170 any additional arguments to be passed to the magic.
2170 any additional arguments to be passed to the magic.
2171
2171
2172 magic('name -opt foo bar') is equivalent to typing at the ipython
2172 magic('name -opt foo bar') is equivalent to typing at the ipython
2173 prompt:
2173 prompt:
2174
2174
2175 In[1]: %name -opt foo bar
2175 In[1]: %name -opt foo bar
2176
2176
2177 To call a magic without arguments, simply use magic('name').
2177 To call a magic without arguments, simply use magic('name').
2178
2178
2179 This provides a proper Python function to call IPython's magics in any
2179 This provides a proper Python function to call IPython's magics in any
2180 valid Python code you can type at the interpreter, including loops and
2180 valid Python code you can type at the interpreter, including loops and
2181 compound statements.
2181 compound statements.
2182 """
2182 """
2183 # TODO: should we issue a loud deprecation warning here?
2183 # TODO: should we issue a loud deprecation warning here?
2184 magic_name, _, magic_arg_s = arg_s.partition(' ')
2184 magic_name, _, magic_arg_s = arg_s.partition(' ')
2185 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2185 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2186 return self.run_line_magic(magic_name, magic_arg_s)
2186 return self.run_line_magic(magic_name, magic_arg_s)
2187
2187
2188 #-------------------------------------------------------------------------
2188 #-------------------------------------------------------------------------
2189 # Things related to macros
2189 # Things related to macros
2190 #-------------------------------------------------------------------------
2190 #-------------------------------------------------------------------------
2191
2191
2192 def define_macro(self, name, themacro):
2192 def define_macro(self, name, themacro):
2193 """Define a new macro
2193 """Define a new macro
2194
2194
2195 Parameters
2195 Parameters
2196 ----------
2196 ----------
2197 name : str
2197 name : str
2198 The name of the macro.
2198 The name of the macro.
2199 themacro : str or Macro
2199 themacro : str or Macro
2200 The action to do upon invoking the macro. If a string, a new
2200 The action to do upon invoking the macro. If a string, a new
2201 Macro object is created by passing the string to it.
2201 Macro object is created by passing the string to it.
2202 """
2202 """
2203
2203
2204 from IPython.core import macro
2204 from IPython.core import macro
2205
2205
2206 if isinstance(themacro, string_types):
2206 if isinstance(themacro, string_types):
2207 themacro = macro.Macro(themacro)
2207 themacro = macro.Macro(themacro)
2208 if not isinstance(themacro, macro.Macro):
2208 if not isinstance(themacro, macro.Macro):
2209 raise ValueError('A macro must be a string or a Macro instance.')
2209 raise ValueError('A macro must be a string or a Macro instance.')
2210 self.user_ns[name] = themacro
2210 self.user_ns[name] = themacro
2211
2211
2212 #-------------------------------------------------------------------------
2212 #-------------------------------------------------------------------------
2213 # Things related to the running of system commands
2213 # Things related to the running of system commands
2214 #-------------------------------------------------------------------------
2214 #-------------------------------------------------------------------------
2215
2215
2216 def system_piped(self, cmd):
2216 def system_piped(self, cmd):
2217 """Call the given cmd in a subprocess, piping stdout/err
2217 """Call the given cmd in a subprocess, piping stdout/err
2218
2218
2219 Parameters
2219 Parameters
2220 ----------
2220 ----------
2221 cmd : str
2221 cmd : str
2222 Command to execute (can not end in '&', as background processes are
2222 Command to execute (can not end in '&', as background processes are
2223 not supported. Should not be a command that expects input
2223 not supported. Should not be a command that expects input
2224 other than simple text.
2224 other than simple text.
2225 """
2225 """
2226 if cmd.rstrip().endswith('&'):
2226 if cmd.rstrip().endswith('&'):
2227 # this is *far* from a rigorous test
2227 # this is *far* from a rigorous test
2228 # We do not support backgrounding processes because we either use
2228 # We do not support backgrounding processes because we either use
2229 # pexpect or pipes to read from. Users can always just call
2229 # pexpect or pipes to read from. Users can always just call
2230 # os.system() or use ip.system=ip.system_raw
2230 # os.system() or use ip.system=ip.system_raw
2231 # if they really want a background process.
2231 # if they really want a background process.
2232 raise OSError("Background processes not supported.")
2232 raise OSError("Background processes not supported.")
2233
2233
2234 # we explicitly do NOT return the subprocess status code, because
2234 # we explicitly do NOT return the subprocess status code, because
2235 # a non-None value would trigger :func:`sys.displayhook` calls.
2235 # a non-None value would trigger :func:`sys.displayhook` calls.
2236 # Instead, we store the exit_code in user_ns.
2236 # Instead, we store the exit_code in user_ns.
2237 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2237 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2238
2238
2239 def system_raw(self, cmd):
2239 def system_raw(self, cmd):
2240 """Call the given cmd in a subprocess using os.system on Windows or
2240 """Call the given cmd in a subprocess using os.system on Windows or
2241 subprocess.call using the system shell on other platforms.
2241 subprocess.call using the system shell on other platforms.
2242
2242
2243 Parameters
2243 Parameters
2244 ----------
2244 ----------
2245 cmd : str
2245 cmd : str
2246 Command to execute.
2246 Command to execute.
2247 """
2247 """
2248 cmd = self.var_expand(cmd, depth=1)
2248 cmd = self.var_expand(cmd, depth=1)
2249 # protect os.system from UNC paths on Windows, which it can't handle:
2249 # protect os.system from UNC paths on Windows, which it can't handle:
2250 if sys.platform == 'win32':
2250 if sys.platform == 'win32':
2251 from IPython.utils._process_win32 import AvoidUNCPath
2251 from IPython.utils._process_win32 import AvoidUNCPath
2252 with AvoidUNCPath() as path:
2252 with AvoidUNCPath() as path:
2253 if path is not None:
2253 if path is not None:
2254 cmd = '"pushd %s &&"%s' % (path, cmd)
2254 cmd = '"pushd %s &&"%s' % (path, cmd)
2255 cmd = py3compat.unicode_to_str(cmd)
2255 cmd = py3compat.unicode_to_str(cmd)
2256 ec = os.system(cmd)
2256 ec = os.system(cmd)
2257 else:
2257 else:
2258 cmd = py3compat.unicode_to_str(cmd)
2258 cmd = py3compat.unicode_to_str(cmd)
2259 # Call the cmd using the OS shell, instead of the default /bin/sh, if set.
2259 # Call the cmd using the OS shell, instead of the default /bin/sh, if set.
2260 ec = subprocess.call(cmd, shell=True, executable=os.environ.get('SHELL', None))
2260 ec = subprocess.call(cmd, shell=True, executable=os.environ.get('SHELL', None))
2261 # exit code is positive for program failure, or negative for
2261 # exit code is positive for program failure, or negative for
2262 # terminating signal number.
2262 # terminating signal number.
2263
2263
2264 # We explicitly do NOT return the subprocess status code, because
2264 # We explicitly do NOT return the subprocess status code, because
2265 # a non-None value would trigger :func:`sys.displayhook` calls.
2265 # a non-None value would trigger :func:`sys.displayhook` calls.
2266 # Instead, we store the exit_code in user_ns.
2266 # Instead, we store the exit_code in user_ns.
2267 self.user_ns['_exit_code'] = ec
2267 self.user_ns['_exit_code'] = ec
2268
2268
2269 # use piped system by default, because it is better behaved
2269 # use piped system by default, because it is better behaved
2270 system = system_piped
2270 system = system_piped
2271
2271
2272 def getoutput(self, cmd, split=True, depth=0):
2272 def getoutput(self, cmd, split=True, depth=0):
2273 """Get output (possibly including stderr) from a subprocess.
2273 """Get output (possibly including stderr) from a subprocess.
2274
2274
2275 Parameters
2275 Parameters
2276 ----------
2276 ----------
2277 cmd : str
2277 cmd : str
2278 Command to execute (can not end in '&', as background processes are
2278 Command to execute (can not end in '&', as background processes are
2279 not supported.
2279 not supported.
2280 split : bool, optional
2280 split : bool, optional
2281 If True, split the output into an IPython SList. Otherwise, an
2281 If True, split the output into an IPython SList. Otherwise, an
2282 IPython LSString is returned. These are objects similar to normal
2282 IPython LSString is returned. These are objects similar to normal
2283 lists and strings, with a few convenience attributes for easier
2283 lists and strings, with a few convenience attributes for easier
2284 manipulation of line-based output. You can use '?' on them for
2284 manipulation of line-based output. You can use '?' on them for
2285 details.
2285 details.
2286 depth : int, optional
2286 depth : int, optional
2287 How many frames above the caller are the local variables which should
2287 How many frames above the caller are the local variables which should
2288 be expanded in the command string? The default (0) assumes that the
2288 be expanded in the command string? The default (0) assumes that the
2289 expansion variables are in the stack frame calling this function.
2289 expansion variables are in the stack frame calling this function.
2290 """
2290 """
2291 if cmd.rstrip().endswith('&'):
2291 if cmd.rstrip().endswith('&'):
2292 # this is *far* from a rigorous test
2292 # this is *far* from a rigorous test
2293 raise OSError("Background processes not supported.")
2293 raise OSError("Background processes not supported.")
2294 out = getoutput(self.var_expand(cmd, depth=depth+1))
2294 out = getoutput(self.var_expand(cmd, depth=depth+1))
2295 if split:
2295 if split:
2296 out = SList(out.splitlines())
2296 out = SList(out.splitlines())
2297 else:
2297 else:
2298 out = LSString(out)
2298 out = LSString(out)
2299 return out
2299 return out
2300
2300
2301 #-------------------------------------------------------------------------
2301 #-------------------------------------------------------------------------
2302 # Things related to aliases
2302 # Things related to aliases
2303 #-------------------------------------------------------------------------
2303 #-------------------------------------------------------------------------
2304
2304
2305 def init_alias(self):
2305 def init_alias(self):
2306 self.alias_manager = AliasManager(shell=self, parent=self)
2306 self.alias_manager = AliasManager(shell=self, parent=self)
2307 self.configurables.append(self.alias_manager)
2307 self.configurables.append(self.alias_manager)
2308
2308
2309 #-------------------------------------------------------------------------
2309 #-------------------------------------------------------------------------
2310 # Things related to extensions
2310 # Things related to extensions
2311 #-------------------------------------------------------------------------
2311 #-------------------------------------------------------------------------
2312
2312
2313 def init_extension_manager(self):
2313 def init_extension_manager(self):
2314 self.extension_manager = ExtensionManager(shell=self, parent=self)
2314 self.extension_manager = ExtensionManager(shell=self, parent=self)
2315 self.configurables.append(self.extension_manager)
2315 self.configurables.append(self.extension_manager)
2316
2316
2317 #-------------------------------------------------------------------------
2317 #-------------------------------------------------------------------------
2318 # Things related to payloads
2318 # Things related to payloads
2319 #-------------------------------------------------------------------------
2319 #-------------------------------------------------------------------------
2320
2320
2321 def init_payload(self):
2321 def init_payload(self):
2322 self.payload_manager = PayloadManager(parent=self)
2322 self.payload_manager = PayloadManager(parent=self)
2323 self.configurables.append(self.payload_manager)
2323 self.configurables.append(self.payload_manager)
2324
2324
2325 #-------------------------------------------------------------------------
2325 #-------------------------------------------------------------------------
2326 # Things related to widgets
2326 # Things related to widgets
2327 #-------------------------------------------------------------------------
2327 #-------------------------------------------------------------------------
2328
2328
2329 def init_comms(self):
2329 def init_comms(self):
2330 # not implemented in the base class
2330 # not implemented in the base class
2331 pass
2331 pass
2332
2332
2333 #-------------------------------------------------------------------------
2333 #-------------------------------------------------------------------------
2334 # Things related to the prefilter
2334 # Things related to the prefilter
2335 #-------------------------------------------------------------------------
2335 #-------------------------------------------------------------------------
2336
2336
2337 def init_prefilter(self):
2337 def init_prefilter(self):
2338 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2338 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2339 self.configurables.append(self.prefilter_manager)
2339 self.configurables.append(self.prefilter_manager)
2340 # Ultimately this will be refactored in the new interpreter code, but
2340 # Ultimately this will be refactored in the new interpreter code, but
2341 # for now, we should expose the main prefilter method (there's legacy
2341 # for now, we should expose the main prefilter method (there's legacy
2342 # code out there that may rely on this).
2342 # code out there that may rely on this).
2343 self.prefilter = self.prefilter_manager.prefilter_lines
2343 self.prefilter = self.prefilter_manager.prefilter_lines
2344
2344
2345 def auto_rewrite_input(self, cmd):
2345 def auto_rewrite_input(self, cmd):
2346 """Print to the screen the rewritten form of the user's command.
2346 """Print to the screen the rewritten form of the user's command.
2347
2347
2348 This shows visual feedback by rewriting input lines that cause
2348 This shows visual feedback by rewriting input lines that cause
2349 automatic calling to kick in, like::
2349 automatic calling to kick in, like::
2350
2350
2351 /f x
2351 /f x
2352
2352
2353 into::
2353 into::
2354
2354
2355 ------> f(x)
2355 ------> f(x)
2356
2356
2357 after the user's input prompt. This helps the user understand that the
2357 after the user's input prompt. This helps the user understand that the
2358 input line was transformed automatically by IPython.
2358 input line was transformed automatically by IPython.
2359 """
2359 """
2360 if not self.show_rewritten_input:
2360 if not self.show_rewritten_input:
2361 return
2361 return
2362
2362
2363 rw = self.prompt_manager.render('rewrite') + cmd
2363 rw = self.prompt_manager.render('rewrite') + cmd
2364
2364
2365 try:
2365 try:
2366 # plain ascii works better w/ pyreadline, on some machines, so
2366 # plain ascii works better w/ pyreadline, on some machines, so
2367 # we use it and only print uncolored rewrite if we have unicode
2367 # we use it and only print uncolored rewrite if we have unicode
2368 rw = str(rw)
2368 rw = str(rw)
2369 print(rw, file=io.stdout)
2369 print(rw, file=io.stdout)
2370 except UnicodeEncodeError:
2370 except UnicodeEncodeError:
2371 print("------> " + cmd)
2371 print("------> " + cmd)
2372
2372
2373 #-------------------------------------------------------------------------
2373 #-------------------------------------------------------------------------
2374 # Things related to extracting values/expressions from kernel and user_ns
2374 # Things related to extracting values/expressions from kernel and user_ns
2375 #-------------------------------------------------------------------------
2375 #-------------------------------------------------------------------------
2376
2376
2377 def _user_obj_error(self):
2377 def _user_obj_error(self):
2378 """return simple exception dict
2378 """return simple exception dict
2379
2379
2380 for use in user_variables / expressions
2380 for use in user_variables / expressions
2381 """
2381 """
2382
2382
2383 etype, evalue, tb = self._get_exc_info()
2383 etype, evalue, tb = self._get_exc_info()
2384 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2384 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2385
2385
2386 exc_info = {
2386 exc_info = {
2387 u'status' : 'error',
2387 u'status' : 'error',
2388 u'traceback' : stb,
2388 u'traceback' : stb,
2389 u'ename' : unicode_type(etype.__name__),
2389 u'ename' : unicode_type(etype.__name__),
2390 u'evalue' : py3compat.safe_unicode(evalue),
2390 u'evalue' : py3compat.safe_unicode(evalue),
2391 }
2391 }
2392
2392
2393 return exc_info
2393 return exc_info
2394
2394
2395 def _format_user_obj(self, obj):
2395 def _format_user_obj(self, obj):
2396 """format a user object to display dict
2396 """format a user object to display dict
2397
2397
2398 for use in user_expressions / variables
2398 for use in user_expressions / variables
2399 """
2399 """
2400
2400
2401 data, md = self.display_formatter.format(obj)
2401 data, md = self.display_formatter.format(obj)
2402 value = {
2402 value = {
2403 'status' : 'ok',
2403 'status' : 'ok',
2404 'data' : data,
2404 'data' : data,
2405 'metadata' : md,
2405 'metadata' : md,
2406 }
2406 }
2407 return value
2407 return value
2408
2408
2409 def user_variables(self, names):
2409 def user_variables(self, names):
2410 """Get a list of variable names from the user's namespace.
2410 """Get a list of variable names from the user's namespace.
2411
2411
2412 Parameters
2412 Parameters
2413 ----------
2413 ----------
2414 names : list of strings
2414 names : list of strings
2415 A list of names of variables to be read from the user namespace.
2415 A list of names of variables to be read from the user namespace.
2416
2416
2417 Returns
2417 Returns
2418 -------
2418 -------
2419 A dict, keyed by the input names and with the rich mime-type repr(s) of each value.
2419 A dict, keyed by the input names and with the rich mime-type repr(s) of each value.
2420 Each element will be a sub-dict of the same form as a display_data message.
2420 Each element will be a sub-dict of the same form as a display_data message.
2421 """
2421 """
2422 out = {}
2422 out = {}
2423 user_ns = self.user_ns
2423 user_ns = self.user_ns
2424
2424
2425 for varname in names:
2425 for varname in names:
2426 try:
2426 try:
2427 value = self._format_user_obj(user_ns[varname])
2427 value = self._format_user_obj(user_ns[varname])
2428 except:
2428 except:
2429 value = self._user_obj_error()
2429 value = self._user_obj_error()
2430 out[varname] = value
2430 out[varname] = value
2431 return out
2431 return out
2432
2432
2433 def user_expressions(self, expressions):
2433 def user_expressions(self, expressions):
2434 """Evaluate a dict of expressions in the user's namespace.
2434 """Evaluate a dict of expressions in the user's namespace.
2435
2435
2436 Parameters
2436 Parameters
2437 ----------
2437 ----------
2438 expressions : dict
2438 expressions : dict
2439 A dict with string keys and string values. The expression values
2439 A dict with string keys and string values. The expression values
2440 should be valid Python expressions, each of which will be evaluated
2440 should be valid Python expressions, each of which will be evaluated
2441 in the user namespace.
2441 in the user namespace.
2442
2442
2443 Returns
2443 Returns
2444 -------
2444 -------
2445 A dict, keyed like the input expressions dict, with the rich mime-typed
2445 A dict, keyed like the input expressions dict, with the rich mime-typed
2446 display_data of each value.
2446 display_data of each value.
2447 """
2447 """
2448 out = {}
2448 out = {}
2449 user_ns = self.user_ns
2449 user_ns = self.user_ns
2450 global_ns = self.user_global_ns
2450 global_ns = self.user_global_ns
2451
2451
2452 for key, expr in iteritems(expressions):
2452 for key, expr in iteritems(expressions):
2453 try:
2453 try:
2454 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2454 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2455 except:
2455 except:
2456 value = self._user_obj_error()
2456 value = self._user_obj_error()
2457 out[key] = value
2457 out[key] = value
2458 return out
2458 return out
2459
2459
2460 #-------------------------------------------------------------------------
2460 #-------------------------------------------------------------------------
2461 # Things related to the running of code
2461 # Things related to the running of code
2462 #-------------------------------------------------------------------------
2462 #-------------------------------------------------------------------------
2463
2463
2464 def ex(self, cmd):
2464 def ex(self, cmd):
2465 """Execute a normal python statement in user namespace."""
2465 """Execute a normal python statement in user namespace."""
2466 with self.builtin_trap:
2466 with self.builtin_trap:
2467 exec(cmd, self.user_global_ns, self.user_ns)
2467 exec(cmd, self.user_global_ns, self.user_ns)
2468
2468
2469 def ev(self, expr):
2469 def ev(self, expr):
2470 """Evaluate python expression expr in user namespace.
2470 """Evaluate python expression expr in user namespace.
2471
2471
2472 Returns the result of evaluation
2472 Returns the result of evaluation
2473 """
2473 """
2474 with self.builtin_trap:
2474 with self.builtin_trap:
2475 return eval(expr, self.user_global_ns, self.user_ns)
2475 return eval(expr, self.user_global_ns, self.user_ns)
2476
2476
2477 def safe_execfile(self, fname, *where, **kw):
2477 def safe_execfile(self, fname, *where, **kw):
2478 """A safe version of the builtin execfile().
2478 """A safe version of the builtin execfile().
2479
2479
2480 This version will never throw an exception, but instead print
2480 This version will never throw an exception, but instead print
2481 helpful error messages to the screen. This only works on pure
2481 helpful error messages to the screen. This only works on pure
2482 Python files with the .py extension.
2482 Python files with the .py extension.
2483
2483
2484 Parameters
2484 Parameters
2485 ----------
2485 ----------
2486 fname : string
2486 fname : string
2487 The name of the file to be executed.
2487 The name of the file to be executed.
2488 where : tuple
2488 where : tuple
2489 One or two namespaces, passed to execfile() as (globals,locals).
2489 One or two namespaces, passed to execfile() as (globals,locals).
2490 If only one is given, it is passed as both.
2490 If only one is given, it is passed as both.
2491 exit_ignore : bool (False)
2491 exit_ignore : bool (False)
2492 If True, then silence SystemExit for non-zero status (it is always
2492 If True, then silence SystemExit for non-zero status (it is always
2493 silenced for zero status, as it is so common).
2493 silenced for zero status, as it is so common).
2494 raise_exceptions : bool (False)
2494 raise_exceptions : bool (False)
2495 If True raise exceptions everywhere. Meant for testing.
2495 If True raise exceptions everywhere. Meant for testing.
2496
2496
2497 """
2497 """
2498 kw.setdefault('exit_ignore', False)
2498 kw.setdefault('exit_ignore', False)
2499 kw.setdefault('raise_exceptions', False)
2499 kw.setdefault('raise_exceptions', False)
2500
2500
2501 fname = os.path.abspath(os.path.expanduser(fname))
2501 fname = os.path.abspath(os.path.expanduser(fname))
2502
2502
2503 # Make sure we can open the file
2503 # Make sure we can open the file
2504 try:
2504 try:
2505 with open(fname) as thefile:
2505 with open(fname) as thefile:
2506 pass
2506 pass
2507 except:
2507 except:
2508 warn('Could not open file <%s> for safe execution.' % fname)
2508 warn('Could not open file <%s> for safe execution.' % fname)
2509 return
2509 return
2510
2510
2511 # Find things also in current directory. This is needed to mimic the
2511 # Find things also in current directory. This is needed to mimic the
2512 # behavior of running a script from the system command line, where
2512 # behavior of running a script from the system command line, where
2513 # Python inserts the script's directory into sys.path
2513 # Python inserts the script's directory into sys.path
2514 dname = os.path.dirname(fname)
2514 dname = os.path.dirname(fname)
2515
2515
2516 with prepended_to_syspath(dname):
2516 with prepended_to_syspath(dname):
2517 try:
2517 try:
2518 py3compat.execfile(fname,*where)
2518 py3compat.execfile(fname,*where)
2519 except SystemExit as status:
2519 except SystemExit as status:
2520 # If the call was made with 0 or None exit status (sys.exit(0)
2520 # If the call was made with 0 or None exit status (sys.exit(0)
2521 # or sys.exit() ), don't bother showing a traceback, as both of
2521 # or sys.exit() ), don't bother showing a traceback, as both of
2522 # these are considered normal by the OS:
2522 # these are considered normal by the OS:
2523 # > python -c'import sys;sys.exit(0)'; echo $?
2523 # > python -c'import sys;sys.exit(0)'; echo $?
2524 # 0
2524 # 0
2525 # > python -c'import sys;sys.exit()'; echo $?
2525 # > python -c'import sys;sys.exit()'; echo $?
2526 # 0
2526 # 0
2527 # For other exit status, we show the exception unless
2527 # For other exit status, we show the exception unless
2528 # explicitly silenced, but only in short form.
2528 # explicitly silenced, but only in short form.
2529 if kw['raise_exceptions']:
2529 if kw['raise_exceptions']:
2530 raise
2530 raise
2531 if status.code and not kw['exit_ignore']:
2531 if status.code and not kw['exit_ignore']:
2532 self.showtraceback(exception_only=True)
2532 self.showtraceback(exception_only=True)
2533 except:
2533 except:
2534 if kw['raise_exceptions']:
2534 if kw['raise_exceptions']:
2535 raise
2535 raise
2536 self.showtraceback()
2536 self.showtraceback()
2537
2537
2538 def safe_execfile_ipy(self, fname):
2538 def safe_execfile_ipy(self, fname):
2539 """Like safe_execfile, but for .ipy files with IPython syntax.
2539 """Like safe_execfile, but for .ipy files with IPython syntax.
2540
2540
2541 Parameters
2541 Parameters
2542 ----------
2542 ----------
2543 fname : str
2543 fname : str
2544 The name of the file to execute. The filename must have a
2544 The name of the file to execute. The filename must have a
2545 .ipy extension.
2545 .ipy extension.
2546 """
2546 """
2547 fname = os.path.abspath(os.path.expanduser(fname))
2547 fname = os.path.abspath(os.path.expanduser(fname))
2548
2548
2549 # Make sure we can open the file
2549 # Make sure we can open the file
2550 try:
2550 try:
2551 with open(fname) as thefile:
2551 with open(fname) as thefile:
2552 pass
2552 pass
2553 except:
2553 except:
2554 warn('Could not open file <%s> for safe execution.' % fname)
2554 warn('Could not open file <%s> for safe execution.' % fname)
2555 return
2555 return
2556
2556
2557 # Find things also in current directory. This is needed to mimic the
2557 # Find things also in current directory. This is needed to mimic the
2558 # behavior of running a script from the system command line, where
2558 # behavior of running a script from the system command line, where
2559 # Python inserts the script's directory into sys.path
2559 # Python inserts the script's directory into sys.path
2560 dname = os.path.dirname(fname)
2560 dname = os.path.dirname(fname)
2561
2561
2562 with prepended_to_syspath(dname):
2562 with prepended_to_syspath(dname):
2563 try:
2563 try:
2564 with open(fname) as thefile:
2564 with open(fname) as thefile:
2565 # self.run_cell currently captures all exceptions
2565 # self.run_cell currently captures all exceptions
2566 # raised in user code. It would be nice if there were
2566 # raised in user code. It would be nice if there were
2567 # versions of runlines, execfile that did raise, so
2567 # versions of runlines, execfile that did raise, so
2568 # we could catch the errors.
2568 # we could catch the errors.
2569 self.run_cell(thefile.read(), store_history=False, shell_futures=False)
2569 self.run_cell(thefile.read(), store_history=False, shell_futures=False)
2570 except:
2570 except:
2571 self.showtraceback()
2571 self.showtraceback()
2572 warn('Unknown failure executing file: <%s>' % fname)
2572 warn('Unknown failure executing file: <%s>' % fname)
2573
2573
2574 def safe_run_module(self, mod_name, where):
2574 def safe_run_module(self, mod_name, where):
2575 """A safe version of runpy.run_module().
2575 """A safe version of runpy.run_module().
2576
2576
2577 This version will never throw an exception, but instead print
2577 This version will never throw an exception, but instead print
2578 helpful error messages to the screen.
2578 helpful error messages to the screen.
2579
2579
2580 `SystemExit` exceptions with status code 0 or None are ignored.
2580 `SystemExit` exceptions with status code 0 or None are ignored.
2581
2581
2582 Parameters
2582 Parameters
2583 ----------
2583 ----------
2584 mod_name : string
2584 mod_name : string
2585 The name of the module to be executed.
2585 The name of the module to be executed.
2586 where : dict
2586 where : dict
2587 The globals namespace.
2587 The globals namespace.
2588 """
2588 """
2589 try:
2589 try:
2590 try:
2590 try:
2591 where.update(
2591 where.update(
2592 runpy.run_module(str(mod_name), run_name="__main__",
2592 runpy.run_module(str(mod_name), run_name="__main__",
2593 alter_sys=True)
2593 alter_sys=True)
2594 )
2594 )
2595 except SystemExit as status:
2595 except SystemExit as status:
2596 if status.code:
2596 if status.code:
2597 raise
2597 raise
2598 except:
2598 except:
2599 self.showtraceback()
2599 self.showtraceback()
2600 warn('Unknown failure executing module: <%s>' % mod_name)
2600 warn('Unknown failure executing module: <%s>' % mod_name)
2601
2601
2602 def _run_cached_cell_magic(self, magic_name, line):
2602 def _run_cached_cell_magic(self, magic_name, line):
2603 """Special method to call a cell magic with the data stored in self.
2603 """Special method to call a cell magic with the data stored in self.
2604 """
2604 """
2605 cell = self._current_cell_magic_body
2605 cell = self._current_cell_magic_body
2606 self._current_cell_magic_body = None
2606 self._current_cell_magic_body = None
2607 return self.run_cell_magic(magic_name, line, cell)
2607 return self.run_cell_magic(magic_name, line, cell)
2608
2608
2609 def run_cell(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2609 def run_cell(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2610 """Run a complete IPython cell.
2610 """Run a complete IPython cell.
2611
2611
2612 Parameters
2612 Parameters
2613 ----------
2613 ----------
2614 raw_cell : str
2614 raw_cell : str
2615 The code (including IPython code such as %magic functions) to run.
2615 The code (including IPython code such as %magic functions) to run.
2616 store_history : bool
2616 store_history : bool
2617 If True, the raw and translated cell will be stored in IPython's
2617 If True, the raw and translated cell will be stored in IPython's
2618 history. For user code calling back into IPython's machinery, this
2618 history. For user code calling back into IPython's machinery, this
2619 should be set to False.
2619 should be set to False.
2620 silent : bool
2620 silent : bool
2621 If True, avoid side-effects, such as implicit displayhooks and
2621 If True, avoid side-effects, such as implicit displayhooks and
2622 and logging. silent=True forces store_history=False.
2622 and logging. silent=True forces store_history=False.
2623 shell_futures : bool
2623 shell_futures : bool
2624 If True, the code will share future statements with the interactive
2624 If True, the code will share future statements with the interactive
2625 shell. It will both be affected by previous __future__ imports, and
2625 shell. It will both be affected by previous __future__ imports, and
2626 any __future__ imports in the code will affect the shell. If False,
2626 any __future__ imports in the code will affect the shell. If False,
2627 __future__ imports are not shared in either direction.
2627 __future__ imports are not shared in either direction.
2628 """
2628 """
2629 if (not raw_cell) or raw_cell.isspace():
2629 if (not raw_cell) or raw_cell.isspace():
2630 return
2630 return
2631
2631
2632 if silent:
2632 if silent:
2633 store_history = False
2633 store_history = False
2634
2634
2635 self.input_transformer_manager.push(raw_cell)
2635 self.input_transformer_manager.push(raw_cell)
2636 cell = self.input_transformer_manager.source_reset()
2636 cell = self.input_transformer_manager.source_reset()
2637
2637
2638 # Our own compiler remembers the __future__ environment. If we want to
2638 # Our own compiler remembers the __future__ environment. If we want to
2639 # run code with a separate __future__ environment, use the default
2639 # run code with a separate __future__ environment, use the default
2640 # compiler
2640 # compiler
2641 compiler = self.compile if shell_futures else CachingCompiler()
2641 compiler = self.compile if shell_futures else CachingCompiler()
2642
2642
2643 with self.builtin_trap:
2643 with self.builtin_trap:
2644 prefilter_failed = False
2644 prefilter_failed = False
2645 if len(cell.splitlines()) == 1:
2645 if len(cell.splitlines()) == 1:
2646 try:
2646 try:
2647 # use prefilter_lines to handle trailing newlines
2647 # use prefilter_lines to handle trailing newlines
2648 # restore trailing newline for ast.parse
2648 # restore trailing newline for ast.parse
2649 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2649 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2650 except AliasError as e:
2650 except AliasError as e:
2651 error(e)
2651 error(e)
2652 prefilter_failed = True
2652 prefilter_failed = True
2653 except Exception:
2653 except Exception:
2654 # don't allow prefilter errors to crash IPython
2654 # don't allow prefilter errors to crash IPython
2655 self.showtraceback()
2655 self.showtraceback()
2656 prefilter_failed = True
2656 prefilter_failed = True
2657
2657
2658 # Store raw and processed history
2658 # Store raw and processed history
2659 if store_history:
2659 if store_history:
2660 self.history_manager.store_inputs(self.execution_count,
2660 self.history_manager.store_inputs(self.execution_count,
2661 cell, raw_cell)
2661 cell, raw_cell)
2662 if not silent:
2662 if not silent:
2663 self.logger.log(cell, raw_cell)
2663 self.logger.log(cell, raw_cell)
2664
2664
2665 if not prefilter_failed:
2665 if not prefilter_failed:
2666 # don't run if prefilter failed
2666 # don't run if prefilter failed
2667 cell_name = self.compile.cache(cell, self.execution_count)
2667 cell_name = self.compile.cache(cell, self.execution_count)
2668
2668
2669 with self.display_trap:
2669 with self.display_trap:
2670 try:
2670 try:
2671 code_ast = compiler.ast_parse(cell, filename=cell_name)
2671 code_ast = compiler.ast_parse(cell, filename=cell_name)
2672 except IndentationError:
2672 except IndentationError:
2673 self.showindentationerror()
2673 self.showindentationerror()
2674 if store_history:
2674 if store_history:
2675 self.execution_count += 1
2675 self.execution_count += 1
2676 return None
2676 return None
2677 except (OverflowError, SyntaxError, ValueError, TypeError,
2677 except (OverflowError, SyntaxError, ValueError, TypeError,
2678 MemoryError):
2678 MemoryError):
2679 self.showsyntaxerror()
2679 self.showsyntaxerror()
2680 if store_history:
2680 if store_history:
2681 self.execution_count += 1
2681 self.execution_count += 1
2682 return None
2682 return None
2683
2683
2684 code_ast = self.transform_ast(code_ast)
2684 code_ast = self.transform_ast(code_ast)
2685
2685
2686 interactivity = "none" if silent else self.ast_node_interactivity
2686 interactivity = "none" if silent else self.ast_node_interactivity
2687 self.run_ast_nodes(code_ast.body, cell_name,
2687 self.run_ast_nodes(code_ast.body, cell_name,
2688 interactivity=interactivity, compiler=compiler)
2688 interactivity=interactivity, compiler=compiler)
2689
2689
2690 # Execute any registered post-execution functions.
2690 # Execute any registered post-execution functions.
2691 # unless we are silent
2691 # unless we are silent
2692 post_exec = [] if silent else iteritems(self._post_execute)
2692 post_exec = [] if silent else iteritems(self._post_execute)
2693
2693
2694 for func, status in post_exec:
2694 for func, status in post_exec:
2695 if self.disable_failing_post_execute and not status:
2695 if self.disable_failing_post_execute and not status:
2696 continue
2696 continue
2697 try:
2697 try:
2698 func()
2698 func()
2699 except KeyboardInterrupt:
2699 except KeyboardInterrupt:
2700 print("\nKeyboardInterrupt", file=io.stderr)
2700 print("\nKeyboardInterrupt", file=io.stderr)
2701 except Exception:
2701 except Exception:
2702 # register as failing:
2702 # register as failing:
2703 self._post_execute[func] = False
2703 self._post_execute[func] = False
2704 self.showtraceback()
2704 self.showtraceback()
2705 print('\n'.join([
2705 print('\n'.join([
2706 "post-execution function %r produced an error." % func,
2706 "post-execution function %r produced an error." % func,
2707 "If this problem persists, you can disable failing post-exec functions with:",
2707 "If this problem persists, you can disable failing post-exec functions with:",
2708 "",
2708 "",
2709 " get_ipython().disable_failing_post_execute = True"
2709 " get_ipython().disable_failing_post_execute = True"
2710 ]), file=io.stderr)
2710 ]), file=io.stderr)
2711
2711
2712 if store_history:
2712 if store_history:
2713 # Write output to the database. Does nothing unless
2713 # Write output to the database. Does nothing unless
2714 # history output logging is enabled.
2714 # history output logging is enabled.
2715 self.history_manager.store_output(self.execution_count)
2715 self.history_manager.store_output(self.execution_count)
2716 # Each cell is a *single* input, regardless of how many lines it has
2716 # Each cell is a *single* input, regardless of how many lines it has
2717 self.execution_count += 1
2717 self.execution_count += 1
2718
2718
2719 def transform_ast(self, node):
2719 def transform_ast(self, node):
2720 """Apply the AST transformations from self.ast_transformers
2720 """Apply the AST transformations from self.ast_transformers
2721
2721
2722 Parameters
2722 Parameters
2723 ----------
2723 ----------
2724 node : ast.Node
2724 node : ast.Node
2725 The root node to be transformed. Typically called with the ast.Module
2725 The root node to be transformed. Typically called with the ast.Module
2726 produced by parsing user input.
2726 produced by parsing user input.
2727
2727
2728 Returns
2728 Returns
2729 -------
2729 -------
2730 An ast.Node corresponding to the node it was called with. Note that it
2730 An ast.Node corresponding to the node it was called with. Note that it
2731 may also modify the passed object, so don't rely on references to the
2731 may also modify the passed object, so don't rely on references to the
2732 original AST.
2732 original AST.
2733 """
2733 """
2734 for transformer in self.ast_transformers:
2734 for transformer in self.ast_transformers:
2735 try:
2735 try:
2736 node = transformer.visit(node)
2736 node = transformer.visit(node)
2737 except Exception:
2737 except Exception:
2738 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
2738 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
2739 self.ast_transformers.remove(transformer)
2739 self.ast_transformers.remove(transformer)
2740
2740
2741 if self.ast_transformers:
2741 if self.ast_transformers:
2742 ast.fix_missing_locations(node)
2742 ast.fix_missing_locations(node)
2743 return node
2743 return node
2744
2744
2745
2745
2746 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr',
2746 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr',
2747 compiler=compile):
2747 compiler=compile):
2748 """Run a sequence of AST nodes. The execution mode depends on the
2748 """Run a sequence of AST nodes. The execution mode depends on the
2749 interactivity parameter.
2749 interactivity parameter.
2750
2750
2751 Parameters
2751 Parameters
2752 ----------
2752 ----------
2753 nodelist : list
2753 nodelist : list
2754 A sequence of AST nodes to run.
2754 A sequence of AST nodes to run.
2755 cell_name : str
2755 cell_name : str
2756 Will be passed to the compiler as the filename of the cell. Typically
2756 Will be passed to the compiler as the filename of the cell. Typically
2757 the value returned by ip.compile.cache(cell).
2757 the value returned by ip.compile.cache(cell).
2758 interactivity : str
2758 interactivity : str
2759 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2759 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2760 run interactively (displaying output from expressions). 'last_expr'
2760 run interactively (displaying output from expressions). 'last_expr'
2761 will run the last node interactively only if it is an expression (i.e.
2761 will run the last node interactively only if it is an expression (i.e.
2762 expressions in loops or other blocks are not displayed. Other values
2762 expressions in loops or other blocks are not displayed. Other values
2763 for this parameter will raise a ValueError.
2763 for this parameter will raise a ValueError.
2764 compiler : callable
2764 compiler : callable
2765 A function with the same interface as the built-in compile(), to turn
2765 A function with the same interface as the built-in compile(), to turn
2766 the AST nodes into code objects. Default is the built-in compile().
2766 the AST nodes into code objects. Default is the built-in compile().
2767 """
2767 """
2768 if not nodelist:
2768 if not nodelist:
2769 return
2769 return
2770
2770
2771 if interactivity == 'last_expr':
2771 if interactivity == 'last_expr':
2772 if isinstance(nodelist[-1], ast.Expr):
2772 if isinstance(nodelist[-1], ast.Expr):
2773 interactivity = "last"
2773 interactivity = "last"
2774 else:
2774 else:
2775 interactivity = "none"
2775 interactivity = "none"
2776
2776
2777 if interactivity == 'none':
2777 if interactivity == 'none':
2778 to_run_exec, to_run_interactive = nodelist, []
2778 to_run_exec, to_run_interactive = nodelist, []
2779 elif interactivity == 'last':
2779 elif interactivity == 'last':
2780 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2780 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2781 elif interactivity == 'all':
2781 elif interactivity == 'all':
2782 to_run_exec, to_run_interactive = [], nodelist
2782 to_run_exec, to_run_interactive = [], nodelist
2783 else:
2783 else:
2784 raise ValueError("Interactivity was %r" % interactivity)
2784 raise ValueError("Interactivity was %r" % interactivity)
2785
2785
2786 exec_count = self.execution_count
2786 exec_count = self.execution_count
2787
2787
2788 try:
2788 try:
2789 for i, node in enumerate(to_run_exec):
2789 for i, node in enumerate(to_run_exec):
2790 mod = ast.Module([node])
2790 mod = ast.Module([node])
2791 code = compiler(mod, cell_name, "exec")
2791 code = compiler(mod, cell_name, "exec")
2792 if self.run_code(code):
2792 if self.run_code(code):
2793 return True
2793 return True
2794
2794
2795 for i, node in enumerate(to_run_interactive):
2795 for i, node in enumerate(to_run_interactive):
2796 mod = ast.Interactive([node])
2796 mod = ast.Interactive([node])
2797 code = compiler(mod, cell_name, "single")
2797 code = compiler(mod, cell_name, "single")
2798 if self.run_code(code):
2798 if self.run_code(code):
2799 return True
2799 return True
2800
2800
2801 # Flush softspace
2801 # Flush softspace
2802 if softspace(sys.stdout, 0):
2802 if softspace(sys.stdout, 0):
2803 print()
2803 print()
2804
2804
2805 except:
2805 except:
2806 # It's possible to have exceptions raised here, typically by
2806 # It's possible to have exceptions raised here, typically by
2807 # compilation of odd code (such as a naked 'return' outside a
2807 # compilation of odd code (such as a naked 'return' outside a
2808 # function) that did parse but isn't valid. Typically the exception
2808 # function) that did parse but isn't valid. Typically the exception
2809 # is a SyntaxError, but it's safest just to catch anything and show
2809 # is a SyntaxError, but it's safest just to catch anything and show
2810 # the user a traceback.
2810 # the user a traceback.
2811
2811
2812 # We do only one try/except outside the loop to minimize the impact
2812 # We do only one try/except outside the loop to minimize the impact
2813 # on runtime, and also because if any node in the node list is
2813 # on runtime, and also because if any node in the node list is
2814 # broken, we should stop execution completely.
2814 # broken, we should stop execution completely.
2815 self.showtraceback()
2815 self.showtraceback()
2816
2816
2817 return False
2817 return False
2818
2818
2819 def run_code(self, code_obj):
2819 def run_code(self, code_obj):
2820 """Execute a code object.
2820 """Execute a code object.
2821
2821
2822 When an exception occurs, self.showtraceback() is called to display a
2822 When an exception occurs, self.showtraceback() is called to display a
2823 traceback.
2823 traceback.
2824
2824
2825 Parameters
2825 Parameters
2826 ----------
2826 ----------
2827 code_obj : code object
2827 code_obj : code object
2828 A compiled code object, to be executed
2828 A compiled code object, to be executed
2829
2829
2830 Returns
2830 Returns
2831 -------
2831 -------
2832 False : successful execution.
2832 False : successful execution.
2833 True : an error occurred.
2833 True : an error occurred.
2834 """
2834 """
2835
2835
2836 # Set our own excepthook in case the user code tries to call it
2836 # Set our own excepthook in case the user code tries to call it
2837 # directly, so that the IPython crash handler doesn't get triggered
2837 # directly, so that the IPython crash handler doesn't get triggered
2838 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2838 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2839
2839
2840 # we save the original sys.excepthook in the instance, in case config
2840 # we save the original sys.excepthook in the instance, in case config
2841 # code (such as magics) needs access to it.
2841 # code (such as magics) needs access to it.
2842 self.sys_excepthook = old_excepthook
2842 self.sys_excepthook = old_excepthook
2843 outflag = 1 # happens in more places, so it's easier as default
2843 outflag = 1 # happens in more places, so it's easier as default
2844 try:
2844 try:
2845 try:
2845 try:
2846 self.hooks.pre_run_code_hook()
2846 self.hooks.pre_run_code_hook()
2847 #rprint('Running code', repr(code_obj)) # dbg
2847 #rprint('Running code', repr(code_obj)) # dbg
2848 exec(code_obj, self.user_global_ns, self.user_ns)
2848 exec(code_obj, self.user_global_ns, self.user_ns)
2849 finally:
2849 finally:
2850 # Reset our crash handler in place
2850 # Reset our crash handler in place
2851 sys.excepthook = old_excepthook
2851 sys.excepthook = old_excepthook
2852 except SystemExit:
2852 except SystemExit:
2853 self.showtraceback(exception_only=True)
2853 self.showtraceback(exception_only=True)
2854 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2854 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2855 except self.custom_exceptions:
2855 except self.custom_exceptions:
2856 etype,value,tb = sys.exc_info()
2856 etype,value,tb = sys.exc_info()
2857 self.CustomTB(etype,value,tb)
2857 self.CustomTB(etype,value,tb)
2858 except:
2858 except:
2859 self.showtraceback()
2859 self.showtraceback()
2860 else:
2860 else:
2861 outflag = 0
2861 outflag = 0
2862 return outflag
2862 return outflag
2863
2863
2864 # For backwards compatibility
2864 # For backwards compatibility
2865 runcode = run_code
2865 runcode = run_code
2866
2866
2867 #-------------------------------------------------------------------------
2867 #-------------------------------------------------------------------------
2868 # Things related to GUI support and pylab
2868 # Things related to GUI support and pylab
2869 #-------------------------------------------------------------------------
2869 #-------------------------------------------------------------------------
2870
2870
2871 def enable_gui(self, gui=None):
2871 def enable_gui(self, gui=None):
2872 raise NotImplementedError('Implement enable_gui in a subclass')
2872 raise NotImplementedError('Implement enable_gui in a subclass')
2873
2873
2874 def enable_matplotlib(self, gui=None):
2874 def enable_matplotlib(self, gui=None):
2875 """Enable interactive matplotlib and inline figure support.
2875 """Enable interactive matplotlib and inline figure support.
2876
2876
2877 This takes the following steps:
2877 This takes the following steps:
2878
2878
2879 1. select the appropriate eventloop and matplotlib backend
2879 1. select the appropriate eventloop and matplotlib backend
2880 2. set up matplotlib for interactive use with that backend
2880 2. set up matplotlib for interactive use with that backend
2881 3. configure formatters for inline figure display
2881 3. configure formatters for inline figure display
2882 4. enable the selected gui eventloop
2882 4. enable the selected gui eventloop
2883
2883
2884 Parameters
2884 Parameters
2885 ----------
2885 ----------
2886 gui : optional, string
2886 gui : optional, string
2887 If given, dictates the choice of matplotlib GUI backend to use
2887 If given, dictates the choice of matplotlib GUI backend to use
2888 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2888 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2889 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2889 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2890 matplotlib (as dictated by the matplotlib build-time options plus the
2890 matplotlib (as dictated by the matplotlib build-time options plus the
2891 user's matplotlibrc configuration file). Note that not all backends
2891 user's matplotlibrc configuration file). Note that not all backends
2892 make sense in all contexts, for example a terminal ipython can't
2892 make sense in all contexts, for example a terminal ipython can't
2893 display figures inline.
2893 display figures inline.
2894 """
2894 """
2895 from IPython.core import pylabtools as pt
2895 from IPython.core import pylabtools as pt
2896 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
2896 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
2897
2897
2898 if gui != 'inline':
2898 if gui != 'inline':
2899 # If we have our first gui selection, store it
2899 # If we have our first gui selection, store it
2900 if self.pylab_gui_select is None:
2900 if self.pylab_gui_select is None:
2901 self.pylab_gui_select = gui
2901 self.pylab_gui_select = gui
2902 # Otherwise if they are different
2902 # Otherwise if they are different
2903 elif gui != self.pylab_gui_select:
2903 elif gui != self.pylab_gui_select:
2904 print ('Warning: Cannot change to a different GUI toolkit: %s.'
2904 print ('Warning: Cannot change to a different GUI toolkit: %s.'
2905 ' Using %s instead.' % (gui, self.pylab_gui_select))
2905 ' Using %s instead.' % (gui, self.pylab_gui_select))
2906 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
2906 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
2907
2907
2908 pt.activate_matplotlib(backend)
2908 pt.activate_matplotlib(backend)
2909 pt.configure_inline_support(self, backend)
2909 pt.configure_inline_support(self, backend)
2910
2910
2911 # Now we must activate the gui pylab wants to use, and fix %run to take
2911 # Now we must activate the gui pylab wants to use, and fix %run to take
2912 # plot updates into account
2912 # plot updates into account
2913 self.enable_gui(gui)
2913 self.enable_gui(gui)
2914 self.magics_manager.registry['ExecutionMagics'].default_runner = \
2914 self.magics_manager.registry['ExecutionMagics'].default_runner = \
2915 pt.mpl_runner(self.safe_execfile)
2915 pt.mpl_runner(self.safe_execfile)
2916
2916
2917 return gui, backend
2917 return gui, backend
2918
2918
2919 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
2919 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
2920 """Activate pylab support at runtime.
2920 """Activate pylab support at runtime.
2921
2921
2922 This turns on support for matplotlib, preloads into the interactive
2922 This turns on support for matplotlib, preloads into the interactive
2923 namespace all of numpy and pylab, and configures IPython to correctly
2923 namespace all of numpy and pylab, and configures IPython to correctly
2924 interact with the GUI event loop. The GUI backend to be used can be
2924 interact with the GUI event loop. The GUI backend to be used can be
2925 optionally selected with the optional ``gui`` argument.
2925 optionally selected with the optional ``gui`` argument.
2926
2926
2927 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
2927 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
2928
2928
2929 Parameters
2929 Parameters
2930 ----------
2930 ----------
2931 gui : optional, string
2931 gui : optional, string
2932 If given, dictates the choice of matplotlib GUI backend to use
2932 If given, dictates the choice of matplotlib GUI backend to use
2933 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2933 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2934 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2934 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2935 matplotlib (as dictated by the matplotlib build-time options plus the
2935 matplotlib (as dictated by the matplotlib build-time options plus the
2936 user's matplotlibrc configuration file). Note that not all backends
2936 user's matplotlibrc configuration file). Note that not all backends
2937 make sense in all contexts, for example a terminal ipython can't
2937 make sense in all contexts, for example a terminal ipython can't
2938 display figures inline.
2938 display figures inline.
2939 import_all : optional, bool, default: True
2939 import_all : optional, bool, default: True
2940 Whether to do `from numpy import *` and `from pylab import *`
2940 Whether to do `from numpy import *` and `from pylab import *`
2941 in addition to module imports.
2941 in addition to module imports.
2942 welcome_message : deprecated
2942 welcome_message : deprecated
2943 This argument is ignored, no welcome message will be displayed.
2943 This argument is ignored, no welcome message will be displayed.
2944 """
2944 """
2945 from IPython.core.pylabtools import import_pylab
2945 from IPython.core.pylabtools import import_pylab
2946
2946
2947 gui, backend = self.enable_matplotlib(gui)
2947 gui, backend = self.enable_matplotlib(gui)
2948
2948
2949 # We want to prevent the loading of pylab to pollute the user's
2949 # We want to prevent the loading of pylab to pollute the user's
2950 # namespace as shown by the %who* magics, so we execute the activation
2950 # namespace as shown by the %who* magics, so we execute the activation
2951 # code in an empty namespace, and we update *both* user_ns and
2951 # code in an empty namespace, and we update *both* user_ns and
2952 # user_ns_hidden with this information.
2952 # user_ns_hidden with this information.
2953 ns = {}
2953 ns = {}
2954 import_pylab(ns, import_all)
2954 import_pylab(ns, import_all)
2955 # warn about clobbered names
2955 # warn about clobbered names
2956 ignored = set(["__builtins__"])
2956 ignored = set(["__builtins__"])
2957 both = set(ns).intersection(self.user_ns).difference(ignored)
2957 both = set(ns).intersection(self.user_ns).difference(ignored)
2958 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
2958 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
2959 self.user_ns.update(ns)
2959 self.user_ns.update(ns)
2960 self.user_ns_hidden.update(ns)
2960 self.user_ns_hidden.update(ns)
2961 return gui, backend, clobbered
2961 return gui, backend, clobbered
2962
2962
2963 #-------------------------------------------------------------------------
2963 #-------------------------------------------------------------------------
2964 # Utilities
2964 # Utilities
2965 #-------------------------------------------------------------------------
2965 #-------------------------------------------------------------------------
2966
2966
2967 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
2967 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
2968 """Expand python variables in a string.
2968 """Expand python variables in a string.
2969
2969
2970 The depth argument indicates how many frames above the caller should
2970 The depth argument indicates how many frames above the caller should
2971 be walked to look for the local namespace where to expand variables.
2971 be walked to look for the local namespace where to expand variables.
2972
2972
2973 The global namespace for expansion is always the user's interactive
2973 The global namespace for expansion is always the user's interactive
2974 namespace.
2974 namespace.
2975 """
2975 """
2976 ns = self.user_ns.copy()
2976 ns = self.user_ns.copy()
2977 ns.update(sys._getframe(depth+1).f_locals)
2977 ns.update(sys._getframe(depth+1).f_locals)
2978 try:
2978 try:
2979 # We have to use .vformat() here, because 'self' is a valid and common
2979 # We have to use .vformat() here, because 'self' is a valid and common
2980 # name, and expanding **ns for .format() would make it collide with
2980 # name, and expanding **ns for .format() would make it collide with
2981 # the 'self' argument of the method.
2981 # the 'self' argument of the method.
2982 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
2982 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
2983 except Exception:
2983 except Exception:
2984 # if formatter couldn't format, just let it go untransformed
2984 # if formatter couldn't format, just let it go untransformed
2985 pass
2985 pass
2986 return cmd
2986 return cmd
2987
2987
2988 def mktempfile(self, data=None, prefix='ipython_edit_'):
2988 def mktempfile(self, data=None, prefix='ipython_edit_'):
2989 """Make a new tempfile and return its filename.
2989 """Make a new tempfile and return its filename.
2990
2990
2991 This makes a call to tempfile.mktemp, but it registers the created
2991 This makes a call to tempfile.mktemp, but it registers the created
2992 filename internally so ipython cleans it up at exit time.
2992 filename internally so ipython cleans it up at exit time.
2993
2993
2994 Optional inputs:
2994 Optional inputs:
2995
2995
2996 - data(None): if data is given, it gets written out to the temp file
2996 - data(None): if data is given, it gets written out to the temp file
2997 immediately, and the file is closed again."""
2997 immediately, and the file is closed again."""
2998
2998
2999 filename = tempfile.mktemp('.py', prefix)
2999 filename = tempfile.mktemp('.py', prefix)
3000 self.tempfiles.append(filename)
3000 self.tempfiles.append(filename)
3001
3001
3002 if data:
3002 if data:
3003 tmp_file = open(filename,'w')
3003 tmp_file = open(filename,'w')
3004 tmp_file.write(data)
3004 tmp_file.write(data)
3005 tmp_file.close()
3005 tmp_file.close()
3006 return filename
3006 return filename
3007
3007
3008 # TODO: This should be removed when Term is refactored.
3008 # TODO: This should be removed when Term is refactored.
3009 def write(self,data):
3009 def write(self,data):
3010 """Write a string to the default output"""
3010 """Write a string to the default output"""
3011 io.stdout.write(data)
3011 io.stdout.write(data)
3012
3012
3013 # TODO: This should be removed when Term is refactored.
3013 # TODO: This should be removed when Term is refactored.
3014 def write_err(self,data):
3014 def write_err(self,data):
3015 """Write a string to the default error output"""
3015 """Write a string to the default error output"""
3016 io.stderr.write(data)
3016 io.stderr.write(data)
3017
3017
3018 def ask_yes_no(self, prompt, default=None):
3018 def ask_yes_no(self, prompt, default=None):
3019 if self.quiet:
3019 if self.quiet:
3020 return True
3020 return True
3021 return ask_yes_no(prompt,default)
3021 return ask_yes_no(prompt,default)
3022
3022
3023 def show_usage(self):
3023 def show_usage(self):
3024 """Show a usage message"""
3024 """Show a usage message"""
3025 page.page(IPython.core.usage.interactive_usage)
3025 page.page(IPython.core.usage.interactive_usage)
3026
3026
3027 def extract_input_lines(self, range_str, raw=False):
3027 def extract_input_lines(self, range_str, raw=False):
3028 """Return as a string a set of input history slices.
3028 """Return as a string a set of input history slices.
3029
3029
3030 Parameters
3030 Parameters
3031 ----------
3031 ----------
3032 range_str : string
3032 range_str : string
3033 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3033 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3034 since this function is for use by magic functions which get their
3034 since this function is for use by magic functions which get their
3035 arguments as strings. The number before the / is the session
3035 arguments as strings. The number before the / is the session
3036 number: ~n goes n back from the current session.
3036 number: ~n goes n back from the current session.
3037
3037
3038 Optional Parameters:
3038 Optional Parameters:
3039 - raw(False): by default, the processed input is used. If this is
3039 - raw(False): by default, the processed input is used. If this is
3040 true, the raw input history is used instead.
3040 true, the raw input history is used instead.
3041
3041
3042 Note that slices can be called with two notations:
3042 Note that slices can be called with two notations:
3043
3043
3044 N:M -> standard python form, means including items N...(M-1).
3044 N:M -> standard python form, means including items N...(M-1).
3045
3045
3046 N-M -> include items N..M (closed endpoint).
3046 N-M -> include items N..M (closed endpoint).
3047 """
3047 """
3048 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3048 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3049 return "\n".join(x for _, _, x in lines)
3049 return "\n".join(x for _, _, x in lines)
3050
3050
3051 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True):
3051 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True):
3052 """Get a code string from history, file, url, or a string or macro.
3052 """Get a code string from history, file, url, or a string or macro.
3053
3053
3054 This is mainly used by magic functions.
3054 This is mainly used by magic functions.
3055
3055
3056 Parameters
3056 Parameters
3057 ----------
3057 ----------
3058
3058
3059 target : str
3059 target : str
3060
3060
3061 A string specifying code to retrieve. This will be tried respectively
3061 A string specifying code to retrieve. This will be tried respectively
3062 as: ranges of input history (see %history for syntax), url,
3062 as: ranges of input history (see %history for syntax), url,
3063 correspnding .py file, filename, or an expression evaluating to a
3063 correspnding .py file, filename, or an expression evaluating to a
3064 string or Macro in the user namespace.
3064 string or Macro in the user namespace.
3065
3065
3066 raw : bool
3066 raw : bool
3067 If true (default), retrieve raw history. Has no effect on the other
3067 If true (default), retrieve raw history. Has no effect on the other
3068 retrieval mechanisms.
3068 retrieval mechanisms.
3069
3069
3070 py_only : bool (default False)
3070 py_only : bool (default False)
3071 Only try to fetch python code, do not try alternative methods to decode file
3071 Only try to fetch python code, do not try alternative methods to decode file
3072 if unicode fails.
3072 if unicode fails.
3073
3073
3074 Returns
3074 Returns
3075 -------
3075 -------
3076 A string of code.
3076 A string of code.
3077
3077
3078 ValueError is raised if nothing is found, and TypeError if it evaluates
3078 ValueError is raised if nothing is found, and TypeError if it evaluates
3079 to an object of another type. In each case, .args[0] is a printable
3079 to an object of another type. In each case, .args[0] is a printable
3080 message.
3080 message.
3081 """
3081 """
3082 code = self.extract_input_lines(target, raw=raw) # Grab history
3082 code = self.extract_input_lines(target, raw=raw) # Grab history
3083 if code:
3083 if code:
3084 return code
3084 return code
3085 utarget = unquote_filename(target)
3085 utarget = unquote_filename(target)
3086 try:
3086 try:
3087 if utarget.startswith(('http://', 'https://')):
3087 if utarget.startswith(('http://', 'https://')):
3088 return openpy.read_py_url(utarget, skip_encoding_cookie=skip_encoding_cookie)
3088 return openpy.read_py_url(utarget, skip_encoding_cookie=skip_encoding_cookie)
3089 except UnicodeDecodeError:
3089 except UnicodeDecodeError:
3090 if not py_only :
3090 if not py_only :
3091 from urllib import urlopen # Deferred import
3091 # Deferred import
3092 try:
3093 from urllib.request import urlopen # Py3
3094 except ImportError:
3095 from urllib import urlopen
3092 response = urlopen(target)
3096 response = urlopen(target)
3093 return response.read().decode('latin1')
3097 return response.read().decode('latin1')
3094 raise ValueError(("'%s' seem to be unreadable.") % utarget)
3098 raise ValueError(("'%s' seem to be unreadable.") % utarget)
3095
3099
3096 potential_target = [target]
3100 potential_target = [target]
3097 try :
3101 try :
3098 potential_target.insert(0,get_py_filename(target))
3102 potential_target.insert(0,get_py_filename(target))
3099 except IOError:
3103 except IOError:
3100 pass
3104 pass
3101
3105
3102 for tgt in potential_target :
3106 for tgt in potential_target :
3103 if os.path.isfile(tgt): # Read file
3107 if os.path.isfile(tgt): # Read file
3104 try :
3108 try :
3105 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3109 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3106 except UnicodeDecodeError :
3110 except UnicodeDecodeError :
3107 if not py_only :
3111 if not py_only :
3108 with io_open(tgt,'r', encoding='latin1') as f :
3112 with io_open(tgt,'r', encoding='latin1') as f :
3109 return f.read()
3113 return f.read()
3110 raise ValueError(("'%s' seem to be unreadable.") % target)
3114 raise ValueError(("'%s' seem to be unreadable.") % target)
3111 elif os.path.isdir(os.path.expanduser(tgt)):
3115 elif os.path.isdir(os.path.expanduser(tgt)):
3112 raise ValueError("'%s' is a directory, not a regular file." % target)
3116 raise ValueError("'%s' is a directory, not a regular file." % target)
3113
3117
3114 try: # User namespace
3118 try: # User namespace
3115 codeobj = eval(target, self.user_ns)
3119 codeobj = eval(target, self.user_ns)
3116 except Exception:
3120 except Exception:
3117 raise ValueError(("'%s' was not found in history, as a file, url, "
3121 raise ValueError(("'%s' was not found in history, as a file, url, "
3118 "nor in the user namespace.") % target)
3122 "nor in the user namespace.") % target)
3119 if isinstance(codeobj, string_types):
3123 if isinstance(codeobj, string_types):
3120 return codeobj
3124 return codeobj
3121 elif isinstance(codeobj, Macro):
3125 elif isinstance(codeobj, Macro):
3122 return codeobj.value
3126 return codeobj.value
3123
3127
3124 raise TypeError("%s is neither a string nor a macro." % target,
3128 raise TypeError("%s is neither a string nor a macro." % target,
3125 codeobj)
3129 codeobj)
3126
3130
3127 #-------------------------------------------------------------------------
3131 #-------------------------------------------------------------------------
3128 # Things related to IPython exiting
3132 # Things related to IPython exiting
3129 #-------------------------------------------------------------------------
3133 #-------------------------------------------------------------------------
3130 def atexit_operations(self):
3134 def atexit_operations(self):
3131 """This will be executed at the time of exit.
3135 """This will be executed at the time of exit.
3132
3136
3133 Cleanup operations and saving of persistent data that is done
3137 Cleanup operations and saving of persistent data that is done
3134 unconditionally by IPython should be performed here.
3138 unconditionally by IPython should be performed here.
3135
3139
3136 For things that may depend on startup flags or platform specifics (such
3140 For things that may depend on startup flags or platform specifics (such
3137 as having readline or not), register a separate atexit function in the
3141 as having readline or not), register a separate atexit function in the
3138 code that has the appropriate information, rather than trying to
3142 code that has the appropriate information, rather than trying to
3139 clutter
3143 clutter
3140 """
3144 """
3141 # Close the history session (this stores the end time and line count)
3145 # Close the history session (this stores the end time and line count)
3142 # this must be *before* the tempfile cleanup, in case of temporary
3146 # this must be *before* the tempfile cleanup, in case of temporary
3143 # history db
3147 # history db
3144 self.history_manager.end_session()
3148 self.history_manager.end_session()
3145
3149
3146 # Cleanup all tempfiles left around
3150 # Cleanup all tempfiles left around
3147 for tfile in self.tempfiles:
3151 for tfile in self.tempfiles:
3148 try:
3152 try:
3149 os.unlink(tfile)
3153 os.unlink(tfile)
3150 except OSError:
3154 except OSError:
3151 pass
3155 pass
3152
3156
3153 # Clear all user namespaces to release all references cleanly.
3157 # Clear all user namespaces to release all references cleanly.
3154 self.reset(new_session=False)
3158 self.reset(new_session=False)
3155
3159
3156 # Run user hooks
3160 # Run user hooks
3157 self.hooks.shutdown_hook()
3161 self.hooks.shutdown_hook()
3158
3162
3159 def cleanup(self):
3163 def cleanup(self):
3160 self.restore_sys_module_state()
3164 self.restore_sys_module_state()
3161
3165
3162
3166
3163 class InteractiveShellABC(with_metaclass(abc.ABCMeta, object)):
3167 class InteractiveShellABC(with_metaclass(abc.ABCMeta, object)):
3164 """An abstract base class for InteractiveShell."""
3168 """An abstract base class for InteractiveShell."""
3165
3169
3166 InteractiveShellABC.register(InteractiveShell)
3170 InteractiveShellABC.register(InteractiveShell)
@@ -1,692 +1,696 b''
1 """Implementation of code management magic functions.
1 """Implementation of code management magic functions.
2 """
2 """
3 from __future__ import print_function
3 from __future__ import print_function
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (c) 2012 The IPython Development Team.
5 # Copyright (c) 2012 The IPython Development Team.
6 #
6 #
7 # Distributed under the terms of the Modified BSD License.
7 # Distributed under the terms of the Modified BSD License.
8 #
8 #
9 # The full license is in the file COPYING.txt, distributed with this software.
9 # The full license is in the file COPYING.txt, distributed with this software.
10 #-----------------------------------------------------------------------------
10 #-----------------------------------------------------------------------------
11
11
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 # Imports
13 # Imports
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15
15
16 # Stdlib
16 # Stdlib
17 import inspect
17 import inspect
18 import io
18 import io
19 import os
19 import os
20 import re
20 import re
21 import sys
21 import sys
22 import ast
22 import ast
23 from itertools import chain
23 from itertools import chain
24
24
25 # Our own packages
25 # Our own packages
26 from IPython.core.error import TryNext, StdinNotImplementedError, UsageError
26 from IPython.core.error import TryNext, StdinNotImplementedError, UsageError
27 from IPython.core.macro import Macro
27 from IPython.core.macro import Macro
28 from IPython.core.magic import Magics, magics_class, line_magic
28 from IPython.core.magic import Magics, magics_class, line_magic
29 from IPython.core.oinspect import find_file, find_source_lines
29 from IPython.core.oinspect import find_file, find_source_lines
30 from IPython.testing.skipdoctest import skip_doctest
30 from IPython.testing.skipdoctest import skip_doctest
31 from IPython.utils import py3compat
31 from IPython.utils import py3compat
32 from IPython.utils.py3compat import string_types
32 from IPython.utils.py3compat import string_types
33 from IPython.utils.contexts import preserve_keys
33 from IPython.utils.contexts import preserve_keys
34 from IPython.utils.path import get_py_filename, unquote_filename
34 from IPython.utils.path import get_py_filename, unquote_filename
35 from IPython.utils.warn import warn, error
35 from IPython.utils.warn import warn, error
36 from IPython.utils.text import get_text_list
36 from IPython.utils.text import get_text_list
37
37
38 #-----------------------------------------------------------------------------
38 #-----------------------------------------------------------------------------
39 # Magic implementation classes
39 # Magic implementation classes
40 #-----------------------------------------------------------------------------
40 #-----------------------------------------------------------------------------
41
41
42 # Used for exception handling in magic_edit
42 # Used for exception handling in magic_edit
43 class MacroToEdit(ValueError): pass
43 class MacroToEdit(ValueError): pass
44
44
45 ipython_input_pat = re.compile(r"<ipython\-input\-(\d+)-[a-z\d]+>$")
45 ipython_input_pat = re.compile(r"<ipython\-input\-(\d+)-[a-z\d]+>$")
46
46
47 # To match, e.g. 8-10 1:5 :10 3-
47 # To match, e.g. 8-10 1:5 :10 3-
48 range_re = re.compile(r"""
48 range_re = re.compile(r"""
49 (?P<start>\d+)?
49 (?P<start>\d+)?
50 ((?P<sep>[\-:])
50 ((?P<sep>[\-:])
51 (?P<end>\d+)?)?
51 (?P<end>\d+)?)?
52 $""", re.VERBOSE)
52 $""", re.VERBOSE)
53
53
54
54
55 def extract_code_ranges(ranges_str):
55 def extract_code_ranges(ranges_str):
56 """Turn a string of range for %%load into 2-tuples of (start, stop)
56 """Turn a string of range for %%load into 2-tuples of (start, stop)
57 ready to use as a slice of the content splitted by lines.
57 ready to use as a slice of the content splitted by lines.
58
58
59 Examples
59 Examples
60 --------
60 --------
61 list(extract_input_ranges("5-10 2"))
61 list(extract_input_ranges("5-10 2"))
62 [(4, 10), (1, 2)]
62 [(4, 10), (1, 2)]
63 """
63 """
64 for range_str in ranges_str.split():
64 for range_str in ranges_str.split():
65 rmatch = range_re.match(range_str)
65 rmatch = range_re.match(range_str)
66 if not rmatch:
66 if not rmatch:
67 continue
67 continue
68 sep = rmatch.group("sep")
68 sep = rmatch.group("sep")
69 start = rmatch.group("start")
69 start = rmatch.group("start")
70 end = rmatch.group("end")
70 end = rmatch.group("end")
71
71
72 if sep == '-':
72 if sep == '-':
73 start = int(start) - 1 if start else None
73 start = int(start) - 1 if start else None
74 end = int(end) if end else None
74 end = int(end) if end else None
75 elif sep == ':':
75 elif sep == ':':
76 start = int(start) - 1 if start else None
76 start = int(start) - 1 if start else None
77 end = int(end) - 1 if end else None
77 end = int(end) - 1 if end else None
78 else:
78 else:
79 end = int(start)
79 end = int(start)
80 start = int(start) - 1
80 start = int(start) - 1
81 yield (start, end)
81 yield (start, end)
82
82
83
83
84 @skip_doctest
84 @skip_doctest
85 def extract_symbols(code, symbols):
85 def extract_symbols(code, symbols):
86 """
86 """
87 Return a tuple (blocks, not_found)
87 Return a tuple (blocks, not_found)
88 where ``blocks`` is a list of code fragments
88 where ``blocks`` is a list of code fragments
89 for each symbol parsed from code, and ``not_found`` are
89 for each symbol parsed from code, and ``not_found`` are
90 symbols not found in the code.
90 symbols not found in the code.
91
91
92 For example::
92 For example::
93
93
94 >>> code = '''a = 10
94 >>> code = '''a = 10
95
95
96 def b(): return 42
96 def b(): return 42
97
97
98 class A: pass'''
98 class A: pass'''
99
99
100 >>> extract_symbols(code, 'A,b,z')
100 >>> extract_symbols(code, 'A,b,z')
101 (["class A: pass", "def b(): return 42"], ['z'])
101 (["class A: pass", "def b(): return 42"], ['z'])
102 """
102 """
103 symbols = symbols.split(',')
103 symbols = symbols.split(',')
104
104
105 # this will raise SyntaxError if code isn't valid Python
105 # this will raise SyntaxError if code isn't valid Python
106 py_code = ast.parse(code)
106 py_code = ast.parse(code)
107
107
108 marks = [(getattr(s, 'name', None), s.lineno) for s in py_code.body]
108 marks = [(getattr(s, 'name', None), s.lineno) for s in py_code.body]
109 code = code.split('\n')
109 code = code.split('\n')
110
110
111 symbols_lines = {}
111 symbols_lines = {}
112
112
113 # we already know the start_lineno of each symbol (marks).
113 # we already know the start_lineno of each symbol (marks).
114 # To find each end_lineno, we traverse in reverse order until each
114 # To find each end_lineno, we traverse in reverse order until each
115 # non-blank line
115 # non-blank line
116 end = len(code)
116 end = len(code)
117 for name, start in reversed(marks):
117 for name, start in reversed(marks):
118 while not code[end - 1].strip():
118 while not code[end - 1].strip():
119 end -= 1
119 end -= 1
120 if name:
120 if name:
121 symbols_lines[name] = (start - 1, end)
121 symbols_lines[name] = (start - 1, end)
122 end = start - 1
122 end = start - 1
123
123
124 # Now symbols_lines is a map
124 # Now symbols_lines is a map
125 # {'symbol_name': (start_lineno, end_lineno), ...}
125 # {'symbol_name': (start_lineno, end_lineno), ...}
126
126
127 # fill a list with chunks of codes for each requested symbol
127 # fill a list with chunks of codes for each requested symbol
128 blocks = []
128 blocks = []
129 not_found = []
129 not_found = []
130 for symbol in symbols:
130 for symbol in symbols:
131 if symbol in symbols_lines:
131 if symbol in symbols_lines:
132 start, end = symbols_lines[symbol]
132 start, end = symbols_lines[symbol]
133 blocks.append('\n'.join(code[start:end]) + '\n')
133 blocks.append('\n'.join(code[start:end]) + '\n')
134 else:
134 else:
135 not_found.append(symbol)
135 not_found.append(symbol)
136
136
137 return blocks, not_found
137 return blocks, not_found
138
138
139
139
140 class InteractivelyDefined(Exception):
140 class InteractivelyDefined(Exception):
141 """Exception for interactively defined variable in magic_edit"""
141 """Exception for interactively defined variable in magic_edit"""
142 def __init__(self, index):
142 def __init__(self, index):
143 self.index = index
143 self.index = index
144
144
145
145
146 @magics_class
146 @magics_class
147 class CodeMagics(Magics):
147 class CodeMagics(Magics):
148 """Magics related to code management (loading, saving, editing, ...)."""
148 """Magics related to code management (loading, saving, editing, ...)."""
149
149
150 @line_magic
150 @line_magic
151 def save(self, parameter_s=''):
151 def save(self, parameter_s=''):
152 """Save a set of lines or a macro to a given filename.
152 """Save a set of lines or a macro to a given filename.
153
153
154 Usage:\\
154 Usage:\\
155 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
155 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
156
156
157 Options:
157 Options:
158
158
159 -r: use 'raw' input. By default, the 'processed' history is used,
159 -r: use 'raw' input. By default, the 'processed' history is used,
160 so that magics are loaded in their transformed version to valid
160 so that magics are loaded in their transformed version to valid
161 Python. If this option is given, the raw input as typed as the
161 Python. If this option is given, the raw input as typed as the
162 command line is used instead.
162 command line is used instead.
163
163
164 -f: force overwrite. If file exists, %save will prompt for overwrite
164 -f: force overwrite. If file exists, %save will prompt for overwrite
165 unless -f is given.
165 unless -f is given.
166
166
167 -a: append to the file instead of overwriting it.
167 -a: append to the file instead of overwriting it.
168
168
169 This function uses the same syntax as %history for input ranges,
169 This function uses the same syntax as %history for input ranges,
170 then saves the lines to the filename you specify.
170 then saves the lines to the filename you specify.
171
171
172 It adds a '.py' extension to the file if you don't do so yourself, and
172 It adds a '.py' extension to the file if you don't do so yourself, and
173 it asks for confirmation before overwriting existing files.
173 it asks for confirmation before overwriting existing files.
174
174
175 If `-r` option is used, the default extension is `.ipy`.
175 If `-r` option is used, the default extension is `.ipy`.
176 """
176 """
177
177
178 opts,args = self.parse_options(parameter_s,'fra',mode='list')
178 opts,args = self.parse_options(parameter_s,'fra',mode='list')
179 if not args:
179 if not args:
180 raise UsageError('Missing filename.')
180 raise UsageError('Missing filename.')
181 raw = 'r' in opts
181 raw = 'r' in opts
182 force = 'f' in opts
182 force = 'f' in opts
183 append = 'a' in opts
183 append = 'a' in opts
184 mode = 'a' if append else 'w'
184 mode = 'a' if append else 'w'
185 ext = u'.ipy' if raw else u'.py'
185 ext = u'.ipy' if raw else u'.py'
186 fname, codefrom = unquote_filename(args[0]), " ".join(args[1:])
186 fname, codefrom = unquote_filename(args[0]), " ".join(args[1:])
187 if not fname.endswith((u'.py',u'.ipy')):
187 if not fname.endswith((u'.py',u'.ipy')):
188 fname += ext
188 fname += ext
189 file_exists = os.path.isfile(fname)
189 file_exists = os.path.isfile(fname)
190 if file_exists and not force and not append:
190 if file_exists and not force and not append:
191 try:
191 try:
192 overwrite = self.shell.ask_yes_no('File `%s` exists. Overwrite (y/[N])? ' % fname, default='n')
192 overwrite = self.shell.ask_yes_no('File `%s` exists. Overwrite (y/[N])? ' % fname, default='n')
193 except StdinNotImplementedError:
193 except StdinNotImplementedError:
194 print("File `%s` exists. Use `%%save -f %s` to force overwrite" % (fname, parameter_s))
194 print("File `%s` exists. Use `%%save -f %s` to force overwrite" % (fname, parameter_s))
195 return
195 return
196 if not overwrite :
196 if not overwrite :
197 print('Operation cancelled.')
197 print('Operation cancelled.')
198 return
198 return
199 try:
199 try:
200 cmds = self.shell.find_user_code(codefrom,raw)
200 cmds = self.shell.find_user_code(codefrom,raw)
201 except (TypeError, ValueError) as e:
201 except (TypeError, ValueError) as e:
202 print(e.args[0])
202 print(e.args[0])
203 return
203 return
204 out = py3compat.cast_unicode(cmds)
204 out = py3compat.cast_unicode(cmds)
205 with io.open(fname, mode, encoding="utf-8") as f:
205 with io.open(fname, mode, encoding="utf-8") as f:
206 if not file_exists or not append:
206 if not file_exists or not append:
207 f.write(u"# coding: utf-8\n")
207 f.write(u"# coding: utf-8\n")
208 f.write(out)
208 f.write(out)
209 # make sure we end on a newline
209 # make sure we end on a newline
210 if not out.endswith(u'\n'):
210 if not out.endswith(u'\n'):
211 f.write(u'\n')
211 f.write(u'\n')
212 print('The following commands were written to file `%s`:' % fname)
212 print('The following commands were written to file `%s`:' % fname)
213 print(cmds)
213 print(cmds)
214
214
215 @line_magic
215 @line_magic
216 def pastebin(self, parameter_s=''):
216 def pastebin(self, parameter_s=''):
217 """Upload code to Github's Gist paste bin, returning the URL.
217 """Upload code to Github's Gist paste bin, returning the URL.
218
218
219 Usage:\\
219 Usage:\\
220 %pastebin [-d "Custom description"] 1-7
220 %pastebin [-d "Custom description"] 1-7
221
221
222 The argument can be an input history range, a filename, or the name of a
222 The argument can be an input history range, a filename, or the name of a
223 string or macro.
223 string or macro.
224
224
225 Options:
225 Options:
226
226
227 -d: Pass a custom description for the gist. The default will say
227 -d: Pass a custom description for the gist. The default will say
228 "Pasted from IPython".
228 "Pasted from IPython".
229 """
229 """
230 opts, args = self.parse_options(parameter_s, 'd:')
230 opts, args = self.parse_options(parameter_s, 'd:')
231
231
232 try:
232 try:
233 code = self.shell.find_user_code(args)
233 code = self.shell.find_user_code(args)
234 except (ValueError, TypeError) as e:
234 except (ValueError, TypeError) as e:
235 print(e.args[0])
235 print(e.args[0])
236 return
236 return
237
237
238 from urllib2 import urlopen # Deferred import
238 # Deferred import
239 try:
240 from urllib.request import urlopen # Py 3
241 except ImportError:
242 from urllib2 import urlopen
239 import json
243 import json
240 post_data = json.dumps({
244 post_data = json.dumps({
241 "description": opts.get('d', "Pasted from IPython"),
245 "description": opts.get('d', "Pasted from IPython"),
242 "public": True,
246 "public": True,
243 "files": {
247 "files": {
244 "file1.py": {
248 "file1.py": {
245 "content": code
249 "content": code
246 }
250 }
247 }
251 }
248 }).encode('utf-8')
252 }).encode('utf-8')
249
253
250 response = urlopen("https://api.github.com/gists", post_data)
254 response = urlopen("https://api.github.com/gists", post_data)
251 response_data = json.loads(response.read().decode('utf-8'))
255 response_data = json.loads(response.read().decode('utf-8'))
252 return response_data['html_url']
256 return response_data['html_url']
253
257
254 @line_magic
258 @line_magic
255 def loadpy(self, arg_s):
259 def loadpy(self, arg_s):
256 """Alias of `%load`
260 """Alias of `%load`
257
261
258 `%loadpy` has gained some flexibility and dropped the requirement of a `.py`
262 `%loadpy` has gained some flexibility and dropped the requirement of a `.py`
259 extension. So it has been renamed simply into %load. You can look at
263 extension. So it has been renamed simply into %load. You can look at
260 `%load`'s docstring for more info.
264 `%load`'s docstring for more info.
261 """
265 """
262 self.load(arg_s)
266 self.load(arg_s)
263
267
264 @line_magic
268 @line_magic
265 def load(self, arg_s):
269 def load(self, arg_s):
266 """Load code into the current frontend.
270 """Load code into the current frontend.
267
271
268 Usage:\\
272 Usage:\\
269 %load [options] source
273 %load [options] source
270
274
271 where source can be a filename, URL, input history range or macro
275 where source can be a filename, URL, input history range or macro
272
276
273 Options:
277 Options:
274 --------
278 --------
275 -r <lines>: Specify lines or ranges of lines to load from the source.
279 -r <lines>: Specify lines or ranges of lines to load from the source.
276 Ranges could be specified as x-y (x..y) or in python-style x:y
280 Ranges could be specified as x-y (x..y) or in python-style x:y
277 (x..(y-1)). Both limits x and y can be left blank (meaning the
281 (x..(y-1)). Both limits x and y can be left blank (meaning the
278 beginning and end of the file, respectively).
282 beginning and end of the file, respectively).
279
283
280 -s <symbols>: Specify function or classes to load from python source.
284 -s <symbols>: Specify function or classes to load from python source.
281
285
282 -y : Don't ask confirmation for loading source above 200 000 characters.
286 -y : Don't ask confirmation for loading source above 200 000 characters.
283
287
284 This magic command can either take a local filename, a URL, an history
288 This magic command can either take a local filename, a URL, an history
285 range (see %history) or a macro as argument, it will prompt for
289 range (see %history) or a macro as argument, it will prompt for
286 confirmation before loading source with more than 200 000 characters, unless
290 confirmation before loading source with more than 200 000 characters, unless
287 -y flag is passed or if the frontend does not support raw_input::
291 -y flag is passed or if the frontend does not support raw_input::
288
292
289 %load myscript.py
293 %load myscript.py
290 %load 7-27
294 %load 7-27
291 %load myMacro
295 %load myMacro
292 %load http://www.example.com/myscript.py
296 %load http://www.example.com/myscript.py
293 %load -r 5-10 myscript.py
297 %load -r 5-10 myscript.py
294 %load -r 10-20,30,40: foo.py
298 %load -r 10-20,30,40: foo.py
295 %load -s MyClass,wonder_function myscript.py
299 %load -s MyClass,wonder_function myscript.py
296 """
300 """
297 opts,args = self.parse_options(arg_s,'ys:r:')
301 opts,args = self.parse_options(arg_s,'ys:r:')
298
302
299 if not args:
303 if not args:
300 raise UsageError('Missing filename, URL, input history range, '
304 raise UsageError('Missing filename, URL, input history range, '
301 'or macro.')
305 'or macro.')
302
306
303 contents = self.shell.find_user_code(args)
307 contents = self.shell.find_user_code(args)
304
308
305 if 's' in opts:
309 if 's' in opts:
306 try:
310 try:
307 blocks, not_found = extract_symbols(contents, opts['s'])
311 blocks, not_found = extract_symbols(contents, opts['s'])
308 except SyntaxError:
312 except SyntaxError:
309 # non python code
313 # non python code
310 error("Unable to parse the input as valid Python code")
314 error("Unable to parse the input as valid Python code")
311 return
315 return
312
316
313 if len(not_found) == 1:
317 if len(not_found) == 1:
314 warn('The symbol `%s` was not found' % not_found[0])
318 warn('The symbol `%s` was not found' % not_found[0])
315 elif len(not_found) > 1:
319 elif len(not_found) > 1:
316 warn('The symbols %s were not found' % get_text_list(not_found,
320 warn('The symbols %s were not found' % get_text_list(not_found,
317 wrap_item_with='`')
321 wrap_item_with='`')
318 )
322 )
319
323
320 contents = '\n'.join(blocks)
324 contents = '\n'.join(blocks)
321
325
322 if 'r' in opts:
326 if 'r' in opts:
323 ranges = opts['r'].replace(',', ' ')
327 ranges = opts['r'].replace(',', ' ')
324 lines = contents.split('\n')
328 lines = contents.split('\n')
325 slices = extract_code_ranges(ranges)
329 slices = extract_code_ranges(ranges)
326 contents = [lines[slice(*slc)] for slc in slices]
330 contents = [lines[slice(*slc)] for slc in slices]
327 contents = '\n'.join(chain.from_iterable(contents))
331 contents = '\n'.join(chain.from_iterable(contents))
328
332
329 l = len(contents)
333 l = len(contents)
330
334
331 # 200 000 is ~ 2500 full 80 caracter lines
335 # 200 000 is ~ 2500 full 80 caracter lines
332 # so in average, more than 5000 lines
336 # so in average, more than 5000 lines
333 if l > 200000 and 'y' not in opts:
337 if l > 200000 and 'y' not in opts:
334 try:
338 try:
335 ans = self.shell.ask_yes_no(("The text you're trying to load seems pretty big"\
339 ans = self.shell.ask_yes_no(("The text you're trying to load seems pretty big"\
336 " (%d characters). Continue (y/[N]) ?" % l), default='n' )
340 " (%d characters). Continue (y/[N]) ?" % l), default='n' )
337 except StdinNotImplementedError:
341 except StdinNotImplementedError:
338 #asume yes if raw input not implemented
342 #asume yes if raw input not implemented
339 ans = True
343 ans = True
340
344
341 if ans is False :
345 if ans is False :
342 print('Operation cancelled.')
346 print('Operation cancelled.')
343 return
347 return
344
348
345 self.shell.set_next_input(contents)
349 self.shell.set_next_input(contents)
346
350
347 @staticmethod
351 @staticmethod
348 def _find_edit_target(shell, args, opts, last_call):
352 def _find_edit_target(shell, args, opts, last_call):
349 """Utility method used by magic_edit to find what to edit."""
353 """Utility method used by magic_edit to find what to edit."""
350
354
351 def make_filename(arg):
355 def make_filename(arg):
352 "Make a filename from the given args"
356 "Make a filename from the given args"
353 arg = unquote_filename(arg)
357 arg = unquote_filename(arg)
354 try:
358 try:
355 filename = get_py_filename(arg)
359 filename = get_py_filename(arg)
356 except IOError:
360 except IOError:
357 # If it ends with .py but doesn't already exist, assume we want
361 # If it ends with .py but doesn't already exist, assume we want
358 # a new file.
362 # a new file.
359 if arg.endswith('.py'):
363 if arg.endswith('.py'):
360 filename = arg
364 filename = arg
361 else:
365 else:
362 filename = None
366 filename = None
363 return filename
367 return filename
364
368
365 # Set a few locals from the options for convenience:
369 # Set a few locals from the options for convenience:
366 opts_prev = 'p' in opts
370 opts_prev = 'p' in opts
367 opts_raw = 'r' in opts
371 opts_raw = 'r' in opts
368
372
369 # custom exceptions
373 # custom exceptions
370 class DataIsObject(Exception): pass
374 class DataIsObject(Exception): pass
371
375
372 # Default line number value
376 # Default line number value
373 lineno = opts.get('n',None)
377 lineno = opts.get('n',None)
374
378
375 if opts_prev:
379 if opts_prev:
376 args = '_%s' % last_call[0]
380 args = '_%s' % last_call[0]
377 if args not in shell.user_ns:
381 if args not in shell.user_ns:
378 args = last_call[1]
382 args = last_call[1]
379
383
380 # by default this is done with temp files, except when the given
384 # by default this is done with temp files, except when the given
381 # arg is a filename
385 # arg is a filename
382 use_temp = True
386 use_temp = True
383
387
384 data = ''
388 data = ''
385
389
386 # First, see if the arguments should be a filename.
390 # First, see if the arguments should be a filename.
387 filename = make_filename(args)
391 filename = make_filename(args)
388 if filename:
392 if filename:
389 use_temp = False
393 use_temp = False
390 elif args:
394 elif args:
391 # Mode where user specifies ranges of lines, like in %macro.
395 # Mode where user specifies ranges of lines, like in %macro.
392 data = shell.extract_input_lines(args, opts_raw)
396 data = shell.extract_input_lines(args, opts_raw)
393 if not data:
397 if not data:
394 try:
398 try:
395 # Load the parameter given as a variable. If not a string,
399 # Load the parameter given as a variable. If not a string,
396 # process it as an object instead (below)
400 # process it as an object instead (below)
397
401
398 #print '*** args',args,'type',type(args) # dbg
402 #print '*** args',args,'type',type(args) # dbg
399 data = eval(args, shell.user_ns)
403 data = eval(args, shell.user_ns)
400 if not isinstance(data, string_types):
404 if not isinstance(data, string_types):
401 raise DataIsObject
405 raise DataIsObject
402
406
403 except (NameError,SyntaxError):
407 except (NameError,SyntaxError):
404 # given argument is not a variable, try as a filename
408 # given argument is not a variable, try as a filename
405 filename = make_filename(args)
409 filename = make_filename(args)
406 if filename is None:
410 if filename is None:
407 warn("Argument given (%s) can't be found as a variable "
411 warn("Argument given (%s) can't be found as a variable "
408 "or as a filename." % args)
412 "or as a filename." % args)
409 return (None, None, None)
413 return (None, None, None)
410 use_temp = False
414 use_temp = False
411
415
412 except DataIsObject:
416 except DataIsObject:
413 # macros have a special edit function
417 # macros have a special edit function
414 if isinstance(data, Macro):
418 if isinstance(data, Macro):
415 raise MacroToEdit(data)
419 raise MacroToEdit(data)
416
420
417 # For objects, try to edit the file where they are defined
421 # For objects, try to edit the file where they are defined
418 filename = find_file(data)
422 filename = find_file(data)
419 if filename:
423 if filename:
420 if 'fakemodule' in filename.lower() and \
424 if 'fakemodule' in filename.lower() and \
421 inspect.isclass(data):
425 inspect.isclass(data):
422 # class created by %edit? Try to find source
426 # class created by %edit? Try to find source
423 # by looking for method definitions instead, the
427 # by looking for method definitions instead, the
424 # __module__ in those classes is FakeModule.
428 # __module__ in those classes is FakeModule.
425 attrs = [getattr(data, aname) for aname in dir(data)]
429 attrs = [getattr(data, aname) for aname in dir(data)]
426 for attr in attrs:
430 for attr in attrs:
427 if not inspect.ismethod(attr):
431 if not inspect.ismethod(attr):
428 continue
432 continue
429 filename = find_file(attr)
433 filename = find_file(attr)
430 if filename and \
434 if filename and \
431 'fakemodule' not in filename.lower():
435 'fakemodule' not in filename.lower():
432 # change the attribute to be the edit
436 # change the attribute to be the edit
433 # target instead
437 # target instead
434 data = attr
438 data = attr
435 break
439 break
436
440
437 m = ipython_input_pat.match(os.path.basename(filename))
441 m = ipython_input_pat.match(os.path.basename(filename))
438 if m:
442 if m:
439 raise InteractivelyDefined(int(m.groups()[0]))
443 raise InteractivelyDefined(int(m.groups()[0]))
440
444
441 datafile = 1
445 datafile = 1
442 if filename is None:
446 if filename is None:
443 filename = make_filename(args)
447 filename = make_filename(args)
444 datafile = 1
448 datafile = 1
445 if filename is not None:
449 if filename is not None:
446 # only warn about this if we get a real name
450 # only warn about this if we get a real name
447 warn('Could not find file where `%s` is defined.\n'
451 warn('Could not find file where `%s` is defined.\n'
448 'Opening a file named `%s`' % (args, filename))
452 'Opening a file named `%s`' % (args, filename))
449 # Now, make sure we can actually read the source (if it was
453 # Now, make sure we can actually read the source (if it was
450 # in a temp file it's gone by now).
454 # in a temp file it's gone by now).
451 if datafile:
455 if datafile:
452 if lineno is None:
456 if lineno is None:
453 lineno = find_source_lines(data)
457 lineno = find_source_lines(data)
454 if lineno is None:
458 if lineno is None:
455 filename = make_filename(args)
459 filename = make_filename(args)
456 if filename is None:
460 if filename is None:
457 warn('The file where `%s` was defined '
461 warn('The file where `%s` was defined '
458 'cannot be read or found.' % data)
462 'cannot be read or found.' % data)
459 return (None, None, None)
463 return (None, None, None)
460 use_temp = False
464 use_temp = False
461
465
462 if use_temp:
466 if use_temp:
463 filename = shell.mktempfile(data)
467 filename = shell.mktempfile(data)
464 print('IPython will make a temporary file named:',filename)
468 print('IPython will make a temporary file named:',filename)
465
469
466 # use last_call to remember the state of the previous call, but don't
470 # use last_call to remember the state of the previous call, but don't
467 # let it be clobbered by successive '-p' calls.
471 # let it be clobbered by successive '-p' calls.
468 try:
472 try:
469 last_call[0] = shell.displayhook.prompt_count
473 last_call[0] = shell.displayhook.prompt_count
470 if not opts_prev:
474 if not opts_prev:
471 last_call[1] = args
475 last_call[1] = args
472 except:
476 except:
473 pass
477 pass
474
478
475
479
476 return filename, lineno, use_temp
480 return filename, lineno, use_temp
477
481
478 def _edit_macro(self,mname,macro):
482 def _edit_macro(self,mname,macro):
479 """open an editor with the macro data in a file"""
483 """open an editor with the macro data in a file"""
480 filename = self.shell.mktempfile(macro.value)
484 filename = self.shell.mktempfile(macro.value)
481 self.shell.hooks.editor(filename)
485 self.shell.hooks.editor(filename)
482
486
483 # and make a new macro object, to replace the old one
487 # and make a new macro object, to replace the old one
484 with open(filename) as mfile:
488 with open(filename) as mfile:
485 mvalue = mfile.read()
489 mvalue = mfile.read()
486 self.shell.user_ns[mname] = Macro(mvalue)
490 self.shell.user_ns[mname] = Macro(mvalue)
487
491
488 @skip_doctest
492 @skip_doctest
489 @line_magic
493 @line_magic
490 def edit(self, parameter_s='',last_call=['','']):
494 def edit(self, parameter_s='',last_call=['','']):
491 """Bring up an editor and execute the resulting code.
495 """Bring up an editor and execute the resulting code.
492
496
493 Usage:
497 Usage:
494 %edit [options] [args]
498 %edit [options] [args]
495
499
496 %edit runs IPython's editor hook. The default version of this hook is
500 %edit runs IPython's editor hook. The default version of this hook is
497 set to call the editor specified by your $EDITOR environment variable.
501 set to call the editor specified by your $EDITOR environment variable.
498 If this isn't found, it will default to vi under Linux/Unix and to
502 If this isn't found, it will default to vi under Linux/Unix and to
499 notepad under Windows. See the end of this docstring for how to change
503 notepad under Windows. See the end of this docstring for how to change
500 the editor hook.
504 the editor hook.
501
505
502 You can also set the value of this editor via the
506 You can also set the value of this editor via the
503 ``TerminalInteractiveShell.editor`` option in your configuration file.
507 ``TerminalInteractiveShell.editor`` option in your configuration file.
504 This is useful if you wish to use a different editor from your typical
508 This is useful if you wish to use a different editor from your typical
505 default with IPython (and for Windows users who typically don't set
509 default with IPython (and for Windows users who typically don't set
506 environment variables).
510 environment variables).
507
511
508 This command allows you to conveniently edit multi-line code right in
512 This command allows you to conveniently edit multi-line code right in
509 your IPython session.
513 your IPython session.
510
514
511 If called without arguments, %edit opens up an empty editor with a
515 If called without arguments, %edit opens up an empty editor with a
512 temporary file and will execute the contents of this file when you
516 temporary file and will execute the contents of this file when you
513 close it (don't forget to save it!).
517 close it (don't forget to save it!).
514
518
515
519
516 Options:
520 Options:
517
521
518 -n <number>: open the editor at a specified line number. By default,
522 -n <number>: open the editor at a specified line number. By default,
519 the IPython editor hook uses the unix syntax 'editor +N filename', but
523 the IPython editor hook uses the unix syntax 'editor +N filename', but
520 you can configure this by providing your own modified hook if your
524 you can configure this by providing your own modified hook if your
521 favorite editor supports line-number specifications with a different
525 favorite editor supports line-number specifications with a different
522 syntax.
526 syntax.
523
527
524 -p: this will call the editor with the same data as the previous time
528 -p: this will call the editor with the same data as the previous time
525 it was used, regardless of how long ago (in your current session) it
529 it was used, regardless of how long ago (in your current session) it
526 was.
530 was.
527
531
528 -r: use 'raw' input. This option only applies to input taken from the
532 -r: use 'raw' input. This option only applies to input taken from the
529 user's history. By default, the 'processed' history is used, so that
533 user's history. By default, the 'processed' history is used, so that
530 magics are loaded in their transformed version to valid Python. If
534 magics are loaded in their transformed version to valid Python. If
531 this option is given, the raw input as typed as the command line is
535 this option is given, the raw input as typed as the command line is
532 used instead. When you exit the editor, it will be executed by
536 used instead. When you exit the editor, it will be executed by
533 IPython's own processor.
537 IPython's own processor.
534
538
535 -x: do not execute the edited code immediately upon exit. This is
539 -x: do not execute the edited code immediately upon exit. This is
536 mainly useful if you are editing programs which need to be called with
540 mainly useful if you are editing programs which need to be called with
537 command line arguments, which you can then do using %run.
541 command line arguments, which you can then do using %run.
538
542
539
543
540 Arguments:
544 Arguments:
541
545
542 If arguments are given, the following possibilities exist:
546 If arguments are given, the following possibilities exist:
543
547
544 - If the argument is a filename, IPython will load that into the
548 - If the argument is a filename, IPython will load that into the
545 editor. It will execute its contents with execfile() when you exit,
549 editor. It will execute its contents with execfile() when you exit,
546 loading any code in the file into your interactive namespace.
550 loading any code in the file into your interactive namespace.
547
551
548 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
552 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
549 The syntax is the same as in the %history magic.
553 The syntax is the same as in the %history magic.
550
554
551 - If the argument is a string variable, its contents are loaded
555 - If the argument is a string variable, its contents are loaded
552 into the editor. You can thus edit any string which contains
556 into the editor. You can thus edit any string which contains
553 python code (including the result of previous edits).
557 python code (including the result of previous edits).
554
558
555 - If the argument is the name of an object (other than a string),
559 - If the argument is the name of an object (other than a string),
556 IPython will try to locate the file where it was defined and open the
560 IPython will try to locate the file where it was defined and open the
557 editor at the point where it is defined. You can use `%edit function`
561 editor at the point where it is defined. You can use `%edit function`
558 to load an editor exactly at the point where 'function' is defined,
562 to load an editor exactly at the point where 'function' is defined,
559 edit it and have the file be executed automatically.
563 edit it and have the file be executed automatically.
560
564
561 - If the object is a macro (see %macro for details), this opens up your
565 - If the object is a macro (see %macro for details), this opens up your
562 specified editor with a temporary file containing the macro's data.
566 specified editor with a temporary file containing the macro's data.
563 Upon exit, the macro is reloaded with the contents of the file.
567 Upon exit, the macro is reloaded with the contents of the file.
564
568
565 Note: opening at an exact line is only supported under Unix, and some
569 Note: opening at an exact line is only supported under Unix, and some
566 editors (like kedit and gedit up to Gnome 2.8) do not understand the
570 editors (like kedit and gedit up to Gnome 2.8) do not understand the
567 '+NUMBER' parameter necessary for this feature. Good editors like
571 '+NUMBER' parameter necessary for this feature. Good editors like
568 (X)Emacs, vi, jed, pico and joe all do.
572 (X)Emacs, vi, jed, pico and joe all do.
569
573
570 After executing your code, %edit will return as output the code you
574 After executing your code, %edit will return as output the code you
571 typed in the editor (except when it was an existing file). This way
575 typed in the editor (except when it was an existing file). This way
572 you can reload the code in further invocations of %edit as a variable,
576 you can reload the code in further invocations of %edit as a variable,
573 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
577 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
574 the output.
578 the output.
575
579
576 Note that %edit is also available through the alias %ed.
580 Note that %edit is also available through the alias %ed.
577
581
578 This is an example of creating a simple function inside the editor and
582 This is an example of creating a simple function inside the editor and
579 then modifying it. First, start up the editor::
583 then modifying it. First, start up the editor::
580
584
581 In [1]: edit
585 In [1]: edit
582 Editing... done. Executing edited code...
586 Editing... done. Executing edited code...
583 Out[1]: 'def foo():\\n print "foo() was defined in an editing
587 Out[1]: 'def foo():\\n print "foo() was defined in an editing
584 session"\\n'
588 session"\\n'
585
589
586 We can then call the function foo()::
590 We can then call the function foo()::
587
591
588 In [2]: foo()
592 In [2]: foo()
589 foo() was defined in an editing session
593 foo() was defined in an editing session
590
594
591 Now we edit foo. IPython automatically loads the editor with the
595 Now we edit foo. IPython automatically loads the editor with the
592 (temporary) file where foo() was previously defined::
596 (temporary) file where foo() was previously defined::
593
597
594 In [3]: edit foo
598 In [3]: edit foo
595 Editing... done. Executing edited code...
599 Editing... done. Executing edited code...
596
600
597 And if we call foo() again we get the modified version::
601 And if we call foo() again we get the modified version::
598
602
599 In [4]: foo()
603 In [4]: foo()
600 foo() has now been changed!
604 foo() has now been changed!
601
605
602 Here is an example of how to edit a code snippet successive
606 Here is an example of how to edit a code snippet successive
603 times. First we call the editor::
607 times. First we call the editor::
604
608
605 In [5]: edit
609 In [5]: edit
606 Editing... done. Executing edited code...
610 Editing... done. Executing edited code...
607 hello
611 hello
608 Out[5]: "print 'hello'\\n"
612 Out[5]: "print 'hello'\\n"
609
613
610 Now we call it again with the previous output (stored in _)::
614 Now we call it again with the previous output (stored in _)::
611
615
612 In [6]: edit _
616 In [6]: edit _
613 Editing... done. Executing edited code...
617 Editing... done. Executing edited code...
614 hello world
618 hello world
615 Out[6]: "print 'hello world'\\n"
619 Out[6]: "print 'hello world'\\n"
616
620
617 Now we call it with the output #8 (stored in _8, also as Out[8])::
621 Now we call it with the output #8 (stored in _8, also as Out[8])::
618
622
619 In [7]: edit _8
623 In [7]: edit _8
620 Editing... done. Executing edited code...
624 Editing... done. Executing edited code...
621 hello again
625 hello again
622 Out[7]: "print 'hello again'\\n"
626 Out[7]: "print 'hello again'\\n"
623
627
624
628
625 Changing the default editor hook:
629 Changing the default editor hook:
626
630
627 If you wish to write your own editor hook, you can put it in a
631 If you wish to write your own editor hook, you can put it in a
628 configuration file which you load at startup time. The default hook
632 configuration file which you load at startup time. The default hook
629 is defined in the IPython.core.hooks module, and you can use that as a
633 is defined in the IPython.core.hooks module, and you can use that as a
630 starting example for further modifications. That file also has
634 starting example for further modifications. That file also has
631 general instructions on how to set a new hook for use once you've
635 general instructions on how to set a new hook for use once you've
632 defined it."""
636 defined it."""
633 opts,args = self.parse_options(parameter_s,'prxn:')
637 opts,args = self.parse_options(parameter_s,'prxn:')
634
638
635 try:
639 try:
636 filename, lineno, is_temp = self._find_edit_target(self.shell,
640 filename, lineno, is_temp = self._find_edit_target(self.shell,
637 args, opts, last_call)
641 args, opts, last_call)
638 except MacroToEdit as e:
642 except MacroToEdit as e:
639 self._edit_macro(args, e.args[0])
643 self._edit_macro(args, e.args[0])
640 return
644 return
641 except InteractivelyDefined as e:
645 except InteractivelyDefined as e:
642 print("Editing In[%i]" % e.index)
646 print("Editing In[%i]" % e.index)
643 args = str(e.index)
647 args = str(e.index)
644 filename, lineno, is_temp = self._find_edit_target(self.shell,
648 filename, lineno, is_temp = self._find_edit_target(self.shell,
645 args, opts, last_call)
649 args, opts, last_call)
646 if filename is None:
650 if filename is None:
647 # nothing was found, warnings have already been issued,
651 # nothing was found, warnings have already been issued,
648 # just give up.
652 # just give up.
649 return
653 return
650
654
651 # do actual editing here
655 # do actual editing here
652 print('Editing...', end=' ')
656 print('Editing...', end=' ')
653 sys.stdout.flush()
657 sys.stdout.flush()
654 try:
658 try:
655 # Quote filenames that may have spaces in them
659 # Quote filenames that may have spaces in them
656 if ' ' in filename:
660 if ' ' in filename:
657 filename = "'%s'" % filename
661 filename = "'%s'" % filename
658 self.shell.hooks.editor(filename,lineno)
662 self.shell.hooks.editor(filename,lineno)
659 except TryNext:
663 except TryNext:
660 warn('Could not open editor')
664 warn('Could not open editor')
661 return
665 return
662
666
663 # XXX TODO: should this be generalized for all string vars?
667 # XXX TODO: should this be generalized for all string vars?
664 # For now, this is special-cased to blocks created by cpaste
668 # For now, this is special-cased to blocks created by cpaste
665 if args.strip() == 'pasted_block':
669 if args.strip() == 'pasted_block':
666 with open(filename, 'r') as f:
670 with open(filename, 'r') as f:
667 self.shell.user_ns['pasted_block'] = f.read()
671 self.shell.user_ns['pasted_block'] = f.read()
668
672
669 if 'x' in opts: # -x prevents actual execution
673 if 'x' in opts: # -x prevents actual execution
670 print()
674 print()
671 else:
675 else:
672 print('done. Executing edited code...')
676 print('done. Executing edited code...')
673 with preserve_keys(self.shell.user_ns, '__file__'):
677 with preserve_keys(self.shell.user_ns, '__file__'):
674 if not is_temp:
678 if not is_temp:
675 self.shell.user_ns['__file__'] = filename
679 self.shell.user_ns['__file__'] = filename
676 if 'r' in opts: # Untranslated IPython code
680 if 'r' in opts: # Untranslated IPython code
677 with open(filename, 'r') as f:
681 with open(filename, 'r') as f:
678 source = f.read()
682 source = f.read()
679 self.shell.run_cell(source, store_history=False)
683 self.shell.run_cell(source, store_history=False)
680 else:
684 else:
681 self.shell.safe_execfile(filename, self.shell.user_ns,
685 self.shell.safe_execfile(filename, self.shell.user_ns,
682 self.shell.user_ns)
686 self.shell.user_ns)
683
687
684 if is_temp:
688 if is_temp:
685 try:
689 try:
686 return open(filename).read()
690 return open(filename).read()
687 except IOError as msg:
691 except IOError as msg:
688 if msg.filename == filename:
692 if msg.filename == filename:
689 warn('File not found. Did you forget to save?')
693 warn('File not found. Did you forget to save?')
690 return
694 return
691 else:
695 else:
692 self.shell.showtraceback()
696 self.shell.showtraceback()
@@ -1,234 +1,238 b''
1 #!/usr/bin/python
1 #!/usr/bin/python
2 """Utility function for installing MathJax javascript library into
2 """Utility function for installing MathJax javascript library into
3 your IPython nbextensions directory, for offline use.
3 your IPython nbextensions directory, for offline use.
4
4
5 Authors:
5 Authors:
6
6
7 * Min RK
7 * Min RK
8 * Mark Sienkiewicz
8 * Mark Sienkiewicz
9 * Matthias Bussonnier
9 * Matthias Bussonnier
10
10
11 To download and install MathJax:
11 To download and install MathJax:
12
12
13 From Python:
13 From Python:
14
14
15 >>> from IPython.external.mathjax import install_mathjax
15 >>> from IPython.external.mathjax import install_mathjax
16 >>> install_mathjax()
16 >>> install_mathjax()
17
17
18 From the command line:
18 From the command line:
19
19
20 $ python -m IPython.external.mathjax
20 $ python -m IPython.external.mathjax
21
21
22 To a specific location:
22 To a specific location:
23
23
24 $ python -m IPython.external.mathjax -i /usr/share/
24 $ python -m IPython.external.mathjax -i /usr/share/
25
25
26 will install mathjax to /usr/share/mathjax
26 will install mathjax to /usr/share/mathjax
27
27
28 To install MathJax from a file you have already downloaded:
28 To install MathJax from a file you have already downloaded:
29
29
30 $ python -m IPython.external.mathjax mathjax-xxx.tar.gz
30 $ python -m IPython.external.mathjax mathjax-xxx.tar.gz
31 $ python -m IPython.external.mathjax mathjax-xxx.zip
31 $ python -m IPython.external.mathjax mathjax-xxx.zip
32
32
33 It will not install MathJax if it is already there. Use -r to
33 It will not install MathJax if it is already there. Use -r to
34 replace the existing copy of MathJax.
34 replace the existing copy of MathJax.
35
35
36 To find the directory where IPython would like MathJax installed:
36 To find the directory where IPython would like MathJax installed:
37
37
38 $ python -m IPython.external.mathjax -d
38 $ python -m IPython.external.mathjax -d
39
39
40 """
40 """
41 from __future__ import print_function
41 from __future__ import print_function
42
42
43
43
44 #-----------------------------------------------------------------------------
44 #-----------------------------------------------------------------------------
45 # Copyright (C) 2011 The IPython Development Team
45 # Copyright (C) 2011 The IPython Development Team
46 #
46 #
47 # Distributed under the terms of the BSD License. The full license is in
47 # Distributed under the terms of the BSD License. The full license is in
48 # the file COPYING, distributed as part of this software.
48 # the file COPYING, distributed as part of this software.
49 #-----------------------------------------------------------------------------
49 #-----------------------------------------------------------------------------
50
50
51
51
52 #-----------------------------------------------------------------------------
52 #-----------------------------------------------------------------------------
53 # Imports
53 # Imports
54 #-----------------------------------------------------------------------------
54 #-----------------------------------------------------------------------------
55
55
56 import argparse
56 import argparse
57 import os
57 import os
58 import shutil
58 import shutil
59 import sys
59 import sys
60 import tarfile
60 import tarfile
61 import urllib2
62 import zipfile
61 import zipfile
63
62
64 from IPython.utils.path import get_ipython_dir
63 from IPython.utils.path import get_ipython_dir
65
64
65 try:
66 from urllib.request import urlopen # Py 3
67 except ImportError:
68 from urllib2 import urlopen
69
66 #-----------------------------------------------------------------------------
70 #-----------------------------------------------------------------------------
67 #
71 #
68 #-----------------------------------------------------------------------------
72 #-----------------------------------------------------------------------------
69
73
70 # Where mathjax will be installed
74 # Where mathjax will be installed
71
75
72 nbextensions = os.path.join(get_ipython_dir(), 'nbextensions')
76 nbextensions = os.path.join(get_ipython_dir(), 'nbextensions')
73 default_dest = os.path.join(nbextensions, 'mathjax')
77 default_dest = os.path.join(nbextensions, 'mathjax')
74
78
75 # Test for access to install mathjax
79 # Test for access to install mathjax
76
80
77 def prepare_dest(dest, replace=False):
81 def prepare_dest(dest, replace=False):
78 """prepare the destination folder for mathjax install
82 """prepare the destination folder for mathjax install
79
83
80 Returns False if mathjax appears to already be installed and there is nothing to do,
84 Returns False if mathjax appears to already be installed and there is nothing to do,
81 True otherwise.
85 True otherwise.
82 """
86 """
83
87
84 parent = os.path.abspath(os.path.join(dest, os.path.pardir))
88 parent = os.path.abspath(os.path.join(dest, os.path.pardir))
85 if not os.path.exists(parent):
89 if not os.path.exists(parent):
86 os.makedirs(parent)
90 os.makedirs(parent)
87
91
88 if os.path.exists(dest):
92 if os.path.exists(dest):
89 if replace:
93 if replace:
90 print("removing existing MathJax at %s" % dest)
94 print("removing existing MathJax at %s" % dest)
91 shutil.rmtree(dest)
95 shutil.rmtree(dest)
92 return True
96 return True
93 else:
97 else:
94 mathjax_js = os.path.join(dest, 'MathJax.js')
98 mathjax_js = os.path.join(dest, 'MathJax.js')
95 if not os.path.exists(mathjax_js):
99 if not os.path.exists(mathjax_js):
96 raise IOError("%s exists, but does not contain MathJax.js" % dest)
100 raise IOError("%s exists, but does not contain MathJax.js" % dest)
97 print("%s already exists" % mathjax_js)
101 print("%s already exists" % mathjax_js)
98 return False
102 return False
99 else:
103 else:
100 return True
104 return True
101
105
102
106
103 def extract_tar(fd, dest):
107 def extract_tar(fd, dest):
104 """extract a tarball from filelike `fd` to destination `dest`"""
108 """extract a tarball from filelike `fd` to destination `dest`"""
105 # use 'r|gz' stream mode, because socket file-like objects can't seek:
109 # use 'r|gz' stream mode, because socket file-like objects can't seek:
106 tar = tarfile.open(fileobj=fd, mode='r|gz')
110 tar = tarfile.open(fileobj=fd, mode='r|gz')
107
111
108 # The first entry in the archive is the top-level dir
112 # The first entry in the archive is the top-level dir
109 topdir = tar.firstmember.path
113 topdir = tar.firstmember.path
110
114
111 # extract the archive (contains a single directory) to the destination directory
115 # extract the archive (contains a single directory) to the destination directory
112 parent = os.path.abspath(os.path.join(dest, os.path.pardir))
116 parent = os.path.abspath(os.path.join(dest, os.path.pardir))
113 tar.extractall(parent)
117 tar.extractall(parent)
114
118
115 # it will be mathjax-MathJax-<sha>, rename to just mathjax
119 # it will be mathjax-MathJax-<sha>, rename to just mathjax
116 os.rename(os.path.join(parent, topdir), dest)
120 os.rename(os.path.join(parent, topdir), dest)
117
121
118
122
119 def extract_zip(fd, dest):
123 def extract_zip(fd, dest):
120 """extract a zip file from filelike `fd` to destination `dest`"""
124 """extract a zip file from filelike `fd` to destination `dest`"""
121 z = zipfile.ZipFile(fd, 'r')
125 z = zipfile.ZipFile(fd, 'r')
122
126
123 # The first entry in the archive is the top-level dir
127 # The first entry in the archive is the top-level dir
124 topdir = z.namelist()[0]
128 topdir = z.namelist()[0]
125
129
126 # extract the archive (contains a single directory) to the static/ directory
130 # extract the archive (contains a single directory) to the static/ directory
127 parent = os.path.abspath(os.path.join(dest, os.path.pardir))
131 parent = os.path.abspath(os.path.join(dest, os.path.pardir))
128 z.extractall(parent)
132 z.extractall(parent)
129
133
130 # it will be mathjax-MathJax-<sha>, rename to just mathjax
134 # it will be mathjax-MathJax-<sha>, rename to just mathjax
131 d = os.path.join(parent, topdir)
135 d = os.path.join(parent, topdir)
132 os.rename(os.path.join(parent, topdir), dest)
136 os.rename(os.path.join(parent, topdir), dest)
133
137
134
138
135 def install_mathjax(tag='v2.2', dest=default_dest, replace=False, file=None, extractor=extract_tar):
139 def install_mathjax(tag='v2.2', dest=default_dest, replace=False, file=None, extractor=extract_tar):
136 """Download and/or install MathJax for offline use.
140 """Download and/or install MathJax for offline use.
137
141
138 This will install mathjax to the nbextensions dir in your IPYTHONDIR.
142 This will install mathjax to the nbextensions dir in your IPYTHONDIR.
139
143
140 MathJax is a ~15MB download, and ~150MB installed.
144 MathJax is a ~15MB download, and ~150MB installed.
141
145
142 Parameters
146 Parameters
143 ----------
147 ----------
144
148
145 replace : bool [False]
149 replace : bool [False]
146 Whether to remove and replace an existing install.
150 Whether to remove and replace an existing install.
147 dest : str [IPYTHONDIR/nbextensions/mathjax]
151 dest : str [IPYTHONDIR/nbextensions/mathjax]
148 Where to install mathjax
152 Where to install mathjax
149 tag : str ['v2.2']
153 tag : str ['v2.2']
150 Which tag to download. Default is 'v2.2', the current stable release,
154 Which tag to download. Default is 'v2.2', the current stable release,
151 but alternatives include 'v1.1a' and 'master'.
155 but alternatives include 'v1.1a' and 'master'.
152 file : file like object [ defualt to content of https://github.com/mathjax/MathJax/tarball/#{tag}]
156 file : file like object [ defualt to content of https://github.com/mathjax/MathJax/tarball/#{tag}]
153 File handle from which to untar/unzip/... mathjax
157 File handle from which to untar/unzip/... mathjax
154 extractor : function
158 extractor : function
155 Method to use to untar/unzip/... `file`
159 Method to use to untar/unzip/... `file`
156 """
160 """
157 try:
161 try:
158 anything_to_do = prepare_dest(dest, replace)
162 anything_to_do = prepare_dest(dest, replace)
159 except OSError as e:
163 except OSError as e:
160 print("ERROR %s, require write access to %s" % (e, dest))
164 print("ERROR %s, require write access to %s" % (e, dest))
161 return 1
165 return 1
162 else:
166 else:
163 if not anything_to_do:
167 if not anything_to_do:
164 return 0
168 return 0
165
169
166 if file is None:
170 if file is None:
167 # download mathjax
171 # download mathjax
168 mathjax_url = "https://github.com/mathjax/MathJax/archive/%s.tar.gz" %tag
172 mathjax_url = "https://github.com/mathjax/MathJax/archive/%s.tar.gz" %tag
169 print("Downloading mathjax source from %s" % mathjax_url)
173 print("Downloading mathjax source from %s" % mathjax_url)
170 response = urllib2.urlopen(mathjax_url)
174 response = urlopen(mathjax_url)
171 file = response.fp
175 file = response.fp
172
176
173 print("Extracting to %s" % dest)
177 print("Extracting to %s" % dest)
174 extractor(file, dest)
178 extractor(file, dest)
175 return 0
179 return 0
176
180
177
181
178 def main():
182 def main():
179 parser = argparse.ArgumentParser(
183 parser = argparse.ArgumentParser(
180 description="""Install mathjax from internet or local archive""",
184 description="""Install mathjax from internet or local archive""",
181 )
185 )
182
186
183 parser.add_argument(
187 parser.add_argument(
184 '-i',
188 '-i',
185 '--install-dir',
189 '--install-dir',
186 default=nbextensions,
190 default=nbextensions,
187 help='custom installation directory. Mathjax will be installed in here/mathjax')
191 help='custom installation directory. Mathjax will be installed in here/mathjax')
188
192
189 parser.add_argument(
193 parser.add_argument(
190 '-d',
194 '-d',
191 '--print-dest',
195 '--print-dest',
192 action='store_true',
196 action='store_true',
193 help='print where mathjax would be installed and exit')
197 help='print where mathjax would be installed and exit')
194 parser.add_argument(
198 parser.add_argument(
195 '-r',
199 '-r',
196 '--replace',
200 '--replace',
197 action='store_true',
201 action='store_true',
198 help='Whether to replace current mathjax if it already exists')
202 help='Whether to replace current mathjax if it already exists')
199 parser.add_argument('filename',
203 parser.add_argument('filename',
200 help="the local tar/zip-ball filename containing mathjax",
204 help="the local tar/zip-ball filename containing mathjax",
201 nargs='?',
205 nargs='?',
202 metavar='filename')
206 metavar='filename')
203
207
204 pargs = parser.parse_args()
208 pargs = parser.parse_args()
205
209
206 dest = os.path.join(pargs.install_dir, 'mathjax')
210 dest = os.path.join(pargs.install_dir, 'mathjax')
207
211
208 if pargs.print_dest:
212 if pargs.print_dest:
209 print(dest)
213 print(dest)
210 return
214 return
211
215
212 # remove/replace existing mathjax?
216 # remove/replace existing mathjax?
213 replace = pargs.replace
217 replace = pargs.replace
214
218
215 # do it
219 # do it
216 if pargs.filename:
220 if pargs.filename:
217 fname = pargs.filename
221 fname = pargs.filename
218
222
219 # automatically detect zip/tar - could do something based
223 # automatically detect zip/tar - could do something based
220 # on file content, but really not cost-effective here.
224 # on file content, but really not cost-effective here.
221 if fname.endswith('.zip'):
225 if fname.endswith('.zip'):
222 extractor = extract_zip
226 extractor = extract_zip
223 else :
227 else :
224 extractor = extract_tar
228 extractor = extract_tar
225 # do it
229 # do it
226 return install_mathjax(file=open(fname, "rb"), replace=replace, extractor=extractor, dest=dest)
230 return install_mathjax(file=open(fname, "rb"), replace=replace, extractor=extractor, dest=dest)
227 else:
231 else:
228 return install_mathjax(replace=replace, dest=dest)
232 return install_mathjax(replace=replace, dest=dest)
229
233
230
234
231 if __name__ == '__main__' :
235 if __name__ == '__main__' :
232 sys.exit(main())
236 sys.exit(main())
233
237
234 __all__ = ['install_mathjax', 'main', 'default_dest']
238 __all__ = ['install_mathjax', 'main', 'default_dest']
@@ -1,494 +1,497 b''
1 """Various display related classes.
1 """Various display related classes.
2
2
3 Authors : MinRK, gregcaporaso, dannystaple
3 Authors : MinRK, gregcaporaso, dannystaple
4 """
4 """
5 from os.path import exists, isfile, splitext, abspath, join, isdir
5 from os.path import exists, isfile, splitext, abspath, join, isdir
6 from os import walk, sep
6 from os import walk, sep
7
7
8 from IPython.core.display import DisplayObject
8 from IPython.core.display import DisplayObject
9
9
10
10
11 class Audio(DisplayObject):
11 class Audio(DisplayObject):
12 """Create an audio object.
12 """Create an audio object.
13
13
14 When this object is returned by an input cell or passed to the
14 When this object is returned by an input cell or passed to the
15 display function, it will result in Audio controls being displayed
15 display function, it will result in Audio controls being displayed
16 in the frontend (only works in the notebook).
16 in the frontend (only works in the notebook).
17
17
18 Parameters
18 Parameters
19 ----------
19 ----------
20 data : numpy array, list, unicode, str or bytes
20 data : numpy array, list, unicode, str or bytes
21 Can be a
21 Can be a
22 * Numpy 1d array containing the desired waveform (mono)
22 * Numpy 1d array containing the desired waveform (mono)
23 * List of float or integer representing the waveform (mono)
23 * List of float or integer representing the waveform (mono)
24 * String containing the filename
24 * String containing the filename
25 * Bytestring containing raw PCM data or
25 * Bytestring containing raw PCM data or
26 * URL pointing to a file on the web.
26 * URL pointing to a file on the web.
27
27
28 If the array option is used the waveform will be normalized.
28 If the array option is used the waveform will be normalized.
29
29
30 If a filename or url is used the format support will be browser
30 If a filename or url is used the format support will be browser
31 dependent.
31 dependent.
32 url : unicode
32 url : unicode
33 A URL to download the data from.
33 A URL to download the data from.
34 filename : unicode
34 filename : unicode
35 Path to a local file to load the data from.
35 Path to a local file to load the data from.
36 embed : boolean
36 embed : boolean
37 Should the image data be embedded using a data URI (True) or should
37 Should the image data be embedded using a data URI (True) or should
38 the original source be referenced. Set this to True if you want the
38 the original source be referenced. Set this to True if you want the
39 audio to playable later with no internet connection in the notebook.
39 audio to playable later with no internet connection in the notebook.
40
40
41 Default is `True`, unless the keyword argument `url` is set, then
41 Default is `True`, unless the keyword argument `url` is set, then
42 default value is `False`.
42 default value is `False`.
43 rate : integer
43 rate : integer
44 The sampling rate of the raw data.
44 The sampling rate of the raw data.
45 Only required when data parameter is being used as an array
45 Only required when data parameter is being used as an array
46 autoplay : bool
46 autoplay : bool
47 Set to True if the audio should immediately start playing.
47 Set to True if the audio should immediately start playing.
48 Default is `False`.
48 Default is `False`.
49
49
50 Examples
50 Examples
51 --------
51 --------
52
52
53 # Generate a sound
53 # Generate a sound
54 import numpy as np
54 import numpy as np
55 framerate = 44100
55 framerate = 44100
56 t = np.linspace(0,5,framerate*5)
56 t = np.linspace(0,5,framerate*5)
57 data = np.sin(2*np.pi*220*t) + np.sin(2*np.pi*224*t))
57 data = np.sin(2*np.pi*220*t) + np.sin(2*np.pi*224*t))
58 Audio(data,rate=framerate)
58 Audio(data,rate=framerate)
59
59
60 Audio("http://www.nch.com.au/acm/8k16bitpcm.wav")
60 Audio("http://www.nch.com.au/acm/8k16bitpcm.wav")
61 Audio(url="http://www.w3schools.com/html/horse.ogg")
61 Audio(url="http://www.w3schools.com/html/horse.ogg")
62
62
63 Audio('/path/to/sound.wav')
63 Audio('/path/to/sound.wav')
64 Audio(filename='/path/to/sound.ogg')
64 Audio(filename='/path/to/sound.ogg')
65
65
66 Audio(b'RAW_WAV_DATA..)
66 Audio(b'RAW_WAV_DATA..)
67 Audio(data=b'RAW_WAV_DATA..)
67 Audio(data=b'RAW_WAV_DATA..)
68
68
69 """
69 """
70 _read_flags = 'rb'
70 _read_flags = 'rb'
71
71
72 def __init__(self, data=None, filename=None, url=None, embed=None, rate=None, autoplay=False):
72 def __init__(self, data=None, filename=None, url=None, embed=None, rate=None, autoplay=False):
73 if filename is None and url is None and data is None:
73 if filename is None and url is None and data is None:
74 raise ValueError("No image data found. Expecting filename, url, or data.")
74 raise ValueError("No image data found. Expecting filename, url, or data.")
75 if embed is False and url is None:
75 if embed is False and url is None:
76 raise ValueError("No url found. Expecting url when embed=False")
76 raise ValueError("No url found. Expecting url when embed=False")
77
77
78 if url is not None and embed is not True:
78 if url is not None and embed is not True:
79 self.embed = False
79 self.embed = False
80 else:
80 else:
81 self.embed = True
81 self.embed = True
82 self.autoplay = autoplay
82 self.autoplay = autoplay
83 super(Audio, self).__init__(data=data, url=url, filename=filename)
83 super(Audio, self).__init__(data=data, url=url, filename=filename)
84
84
85 if self.data is not None and not isinstance(self.data, bytes):
85 if self.data is not None and not isinstance(self.data, bytes):
86 self.data = self._make_wav(data,rate)
86 self.data = self._make_wav(data,rate)
87
87
88 def reload(self):
88 def reload(self):
89 """Reload the raw data from file or URL."""
89 """Reload the raw data from file or URL."""
90 import mimetypes
90 import mimetypes
91 if self.embed:
91 if self.embed:
92 super(Audio, self).reload()
92 super(Audio, self).reload()
93
93
94 if self.filename is not None:
94 if self.filename is not None:
95 self.mimetype = mimetypes.guess_type(self.filename)[0]
95 self.mimetype = mimetypes.guess_type(self.filename)[0]
96 elif self.url is not None:
96 elif self.url is not None:
97 self.mimetype = mimetypes.guess_type(self.url)[0]
97 self.mimetype = mimetypes.guess_type(self.url)[0]
98 else:
98 else:
99 self.mimetype = "audio/wav"
99 self.mimetype = "audio/wav"
100
100
101 def _make_wav(self, data, rate):
101 def _make_wav(self, data, rate):
102 """ Transform a numpy array to a PCM bytestring """
102 """ Transform a numpy array to a PCM bytestring """
103 import struct
103 import struct
104 from io import BytesIO
104 from io import BytesIO
105 import wave
105 import wave
106 try:
106 try:
107 import numpy as np
107 import numpy as np
108 data = np.array(data,dtype=float)
108 data = np.array(data,dtype=float)
109 if len(data.shape) > 1:
109 if len(data.shape) > 1:
110 raise ValueError("encoding of stereo PCM signals are unsupported")
110 raise ValueError("encoding of stereo PCM signals are unsupported")
111 scaled = np.int16(data/np.max(np.abs(data))*32767).tolist()
111 scaled = np.int16(data/np.max(np.abs(data))*32767).tolist()
112 except ImportError:
112 except ImportError:
113 maxabsvalue = float(max([abs(x) for x in data]))
113 maxabsvalue = float(max([abs(x) for x in data]))
114 scaled = [int(x/maxabsvalue*32767) for x in data]
114 scaled = [int(x/maxabsvalue*32767) for x in data]
115 fp = BytesIO()
115 fp = BytesIO()
116 waveobj = wave.open(fp,mode='wb')
116 waveobj = wave.open(fp,mode='wb')
117 waveobj.setnchannels(1)
117 waveobj.setnchannels(1)
118 waveobj.setframerate(rate)
118 waveobj.setframerate(rate)
119 waveobj.setsampwidth(2)
119 waveobj.setsampwidth(2)
120 waveobj.setcomptype('NONE','NONE')
120 waveobj.setcomptype('NONE','NONE')
121 waveobj.writeframes(b''.join([struct.pack('<h',x) for x in scaled]))
121 waveobj.writeframes(b''.join([struct.pack('<h',x) for x in scaled]))
122 val = fp.getvalue()
122 val = fp.getvalue()
123 waveobj.close()
123 waveobj.close()
124 return val
124 return val
125
125
126 def _data_and_metadata(self):
126 def _data_and_metadata(self):
127 """shortcut for returning metadata with url information, if defined"""
127 """shortcut for returning metadata with url information, if defined"""
128 md = {}
128 md = {}
129 if self.url:
129 if self.url:
130 md['url'] = self.url
130 md['url'] = self.url
131 if md:
131 if md:
132 return self.data, md
132 return self.data, md
133 else:
133 else:
134 return self.data
134 return self.data
135
135
136 def _repr_html_(self):
136 def _repr_html_(self):
137 src = """
137 src = """
138 <audio controls="controls" {autoplay}>
138 <audio controls="controls" {autoplay}>
139 <source src="{src}" type="{type}" />
139 <source src="{src}" type="{type}" />
140 Your browser does not support the audio element.
140 Your browser does not support the audio element.
141 </audio>
141 </audio>
142 """
142 """
143 return src.format(src=self.src_attr(),type=self.mimetype, autoplay=self.autoplay_attr())
143 return src.format(src=self.src_attr(),type=self.mimetype, autoplay=self.autoplay_attr())
144
144
145 def src_attr(self):
145 def src_attr(self):
146 import base64
146 import base64
147 if self.embed and (self.data is not None):
147 if self.embed and (self.data is not None):
148 data = base64=base64.b64encode(self.data).decode('ascii')
148 data = base64=base64.b64encode(self.data).decode('ascii')
149 return """data:{type};base64,{base64}""".format(type=self.mimetype,
149 return """data:{type};base64,{base64}""".format(type=self.mimetype,
150 base64=data)
150 base64=data)
151 elif self.url is not None:
151 elif self.url is not None:
152 return self.url
152 return self.url
153 else:
153 else:
154 return ""
154 return ""
155
155
156 def autoplay_attr(self):
156 def autoplay_attr(self):
157 if(self.autoplay):
157 if(self.autoplay):
158 return 'autoplay="autoplay"'
158 return 'autoplay="autoplay"'
159 else:
159 else:
160 return ''
160 return ''
161
161
162 class IFrame(object):
162 class IFrame(object):
163 """
163 """
164 Generic class to embed an iframe in an IPython notebook
164 Generic class to embed an iframe in an IPython notebook
165 """
165 """
166
166
167 iframe = """
167 iframe = """
168 <iframe
168 <iframe
169 width="{width}"
169 width="{width}"
170 height={height}"
170 height={height}"
171 src="{src}{params}"
171 src="{src}{params}"
172 frameborder="0"
172 frameborder="0"
173 allowfullscreen
173 allowfullscreen
174 ></iframe>
174 ></iframe>
175 """
175 """
176
176
177 def __init__(self, src, width, height, **kwargs):
177 def __init__(self, src, width, height, **kwargs):
178 self.src = src
178 self.src = src
179 self.width = width
179 self.width = width
180 self.height = height
180 self.height = height
181 self.params = kwargs
181 self.params = kwargs
182
182
183 def _repr_html_(self):
183 def _repr_html_(self):
184 """return the embed iframe"""
184 """return the embed iframe"""
185 if self.params:
185 if self.params:
186 try:
187 from urllib.parse import urlencode # Py 3
188 except ImportError:
186 from urllib import urlencode
189 from urllib import urlencode
187 params = "?" + urlencode(self.params)
190 params = "?" + urlencode(self.params)
188 else:
191 else:
189 params = ""
192 params = ""
190 return self.iframe.format(src=self.src,
193 return self.iframe.format(src=self.src,
191 width=self.width,
194 width=self.width,
192 height=self.height,
195 height=self.height,
193 params=params)
196 params=params)
194
197
195 class YouTubeVideo(IFrame):
198 class YouTubeVideo(IFrame):
196 """Class for embedding a YouTube Video in an IPython session, based on its video id.
199 """Class for embedding a YouTube Video in an IPython session, based on its video id.
197
200
198 e.g. to embed the video on this page:
201 e.g. to embed the video on this page:
199
202
200 http://www.youtube.com/watch?v=foo
203 http://www.youtube.com/watch?v=foo
201
204
202 you would do:
205 you would do:
203
206
204 vid = YouTubeVideo("foo")
207 vid = YouTubeVideo("foo")
205 display(vid)
208 display(vid)
206
209
207 To start from 30 seconds:
210 To start from 30 seconds:
208
211
209 vid = YouTubeVideo("abc", start=30)
212 vid = YouTubeVideo("abc", start=30)
210 display(vid)
213 display(vid)
211
214
212 To calculate seconds from time as hours, minutes, seconds use:
215 To calculate seconds from time as hours, minutes, seconds use:
213 start=int(timedelta(hours=1, minutes=46, seconds=40).total_seconds())
216 start=int(timedelta(hours=1, minutes=46, seconds=40).total_seconds())
214
217
215 Other parameters can be provided as documented at
218 Other parameters can be provided as documented at
216 https://developers.google.com/youtube/player_parameters#parameter-subheader
219 https://developers.google.com/youtube/player_parameters#parameter-subheader
217 """
220 """
218
221
219 def __init__(self, id, width=400, height=300, **kwargs):
222 def __init__(self, id, width=400, height=300, **kwargs):
220 src = "http://www.youtube.com/embed/{0}".format(id)
223 src = "http://www.youtube.com/embed/{0}".format(id)
221 super(YouTubeVideo, self).__init__(src, width, height, **kwargs)
224 super(YouTubeVideo, self).__init__(src, width, height, **kwargs)
222
225
223 class VimeoVideo(IFrame):
226 class VimeoVideo(IFrame):
224 """
227 """
225 Class for embedding a Vimeo video in an IPython session, based on its video id.
228 Class for embedding a Vimeo video in an IPython session, based on its video id.
226 """
229 """
227
230
228 def __init__(self, id, width=400, height=300, **kwargs):
231 def __init__(self, id, width=400, height=300, **kwargs):
229 src="http://player.vimeo.com/video/{0}".format(id)
232 src="http://player.vimeo.com/video/{0}".format(id)
230 super(VimeoVideo, self).__init__(src, width, height, **kwargs)
233 super(VimeoVideo, self).__init__(src, width, height, **kwargs)
231
234
232 class ScribdDocument(IFrame):
235 class ScribdDocument(IFrame):
233 """
236 """
234 Class for embedding a Scribd document in an IPython session
237 Class for embedding a Scribd document in an IPython session
235
238
236 Use the start_page params to specify a starting point in the document
239 Use the start_page params to specify a starting point in the document
237 Use the view_mode params to specify display type one off scroll | slideshow | book
240 Use the view_mode params to specify display type one off scroll | slideshow | book
238
241
239 e.g to Display Wes' foundational paper about PANDAS in book mode from page 3
242 e.g to Display Wes' foundational paper about PANDAS in book mode from page 3
240
243
241 ScribdDocument(71048089, width=800, height=400, start_page=3, view_mode="book")
244 ScribdDocument(71048089, width=800, height=400, start_page=3, view_mode="book")
242 """
245 """
243
246
244 def __init__(self, id, width=400, height=300, **kwargs):
247 def __init__(self, id, width=400, height=300, **kwargs):
245 src="http://www.scribd.com/embeds/{0}/content".format(id)
248 src="http://www.scribd.com/embeds/{0}/content".format(id)
246 super(ScribdDocument, self).__init__(src, width, height, **kwargs)
249 super(ScribdDocument, self).__init__(src, width, height, **kwargs)
247
250
248 class FileLink(object):
251 class FileLink(object):
249 """Class for embedding a local file link in an IPython session, based on path
252 """Class for embedding a local file link in an IPython session, based on path
250
253
251 e.g. to embed a link that was generated in the IPython notebook as my/data.txt
254 e.g. to embed a link that was generated in the IPython notebook as my/data.txt
252
255
253 you would do::
256 you would do::
254
257
255 local_file = FileLink("my/data.txt")
258 local_file = FileLink("my/data.txt")
256 display(local_file)
259 display(local_file)
257
260
258 or in the HTML notebook, just::
261 or in the HTML notebook, just::
259
262
260 FileLink("my/data.txt")
263 FileLink("my/data.txt")
261 """
264 """
262
265
263 html_link_str = "<a href='%s' target='_blank'>%s</a>"
266 html_link_str = "<a href='%s' target='_blank'>%s</a>"
264
267
265 def __init__(self,
268 def __init__(self,
266 path,
269 path,
267 url_prefix='files/',
270 url_prefix='files/',
268 result_html_prefix='',
271 result_html_prefix='',
269 result_html_suffix='<br>'):
272 result_html_suffix='<br>'):
270 """
273 """
271 Parameters
274 Parameters
272 ----------
275 ----------
273 path : str
276 path : str
274 path to the file or directory that should be formatted
277 path to the file or directory that should be formatted
275 directory_prefix : str
278 directory_prefix : str
276 prefix to be prepended to all files to form a working link [default:
279 prefix to be prepended to all files to form a working link [default:
277 'files']
280 'files']
278 result_html_prefix : str
281 result_html_prefix : str
279 text to append to beginning to link [default: none]
282 text to append to beginning to link [default: none]
280 result_html_suffix : str
283 result_html_suffix : str
281 text to append at the end of link [default: '<br>']
284 text to append at the end of link [default: '<br>']
282 """
285 """
283 if isdir(path):
286 if isdir(path):
284 raise ValueError("Cannot display a directory using FileLink. "
287 raise ValueError("Cannot display a directory using FileLink. "
285 "Use FileLinks to display '%s'." % path)
288 "Use FileLinks to display '%s'." % path)
286 self.path = path
289 self.path = path
287 self.url_prefix = url_prefix
290 self.url_prefix = url_prefix
288 self.result_html_prefix = result_html_prefix
291 self.result_html_prefix = result_html_prefix
289 self.result_html_suffix = result_html_suffix
292 self.result_html_suffix = result_html_suffix
290
293
291 def _format_path(self):
294 def _format_path(self):
292 fp = ''.join([self.url_prefix,self.path])
295 fp = ''.join([self.url_prefix,self.path])
293 return ''.join([self.result_html_prefix,
296 return ''.join([self.result_html_prefix,
294 self.html_link_str % (fp, self.path),
297 self.html_link_str % (fp, self.path),
295 self.result_html_suffix])
298 self.result_html_suffix])
296
299
297 def _repr_html_(self):
300 def _repr_html_(self):
298 """return html link to file
301 """return html link to file
299 """
302 """
300 if not exists(self.path):
303 if not exists(self.path):
301 return ("Path (<tt>%s</tt>) doesn't exist. "
304 return ("Path (<tt>%s</tt>) doesn't exist. "
302 "It may still be in the process of "
305 "It may still be in the process of "
303 "being generated, or you may have the "
306 "being generated, or you may have the "
304 "incorrect path." % self.path)
307 "incorrect path." % self.path)
305
308
306 return self._format_path()
309 return self._format_path()
307
310
308 def __repr__(self):
311 def __repr__(self):
309 """return absolute path to file
312 """return absolute path to file
310 """
313 """
311 return abspath(self.path)
314 return abspath(self.path)
312
315
313 class FileLinks(FileLink):
316 class FileLinks(FileLink):
314 """Class for embedding local file links in an IPython session, based on path
317 """Class for embedding local file links in an IPython session, based on path
315
318
316 e.g. to embed links to files that were generated in the IPython notebook under my/data
319 e.g. to embed links to files that were generated in the IPython notebook under my/data
317
320
318 you would do:
321 you would do:
319
322
320 local_files = FileLinks("my/data")
323 local_files = FileLinks("my/data")
321 display(local_files)
324 display(local_files)
322
325
323 or in the HTML notebook, just
326 or in the HTML notebook, just
324
327
325 FileLinks("my/data")
328 FileLinks("my/data")
326
329
327 """
330 """
328 def __init__(self,
331 def __init__(self,
329 path,
332 path,
330 url_prefix='files/',
333 url_prefix='files/',
331 included_suffixes=None,
334 included_suffixes=None,
332 result_html_prefix='',
335 result_html_prefix='',
333 result_html_suffix='<br>',
336 result_html_suffix='<br>',
334 notebook_display_formatter=None,
337 notebook_display_formatter=None,
335 terminal_display_formatter=None):
338 terminal_display_formatter=None):
336 """
339 """
337 included_suffixes : list of filename suffixes to include when
340 included_suffixes : list of filename suffixes to include when
338 formatting output [default: include all files]
341 formatting output [default: include all files]
339
342
340 See the FileLink (baseclass of LocalDirectory) docstring for
343 See the FileLink (baseclass of LocalDirectory) docstring for
341 information on additional parameters.
344 information on additional parameters.
342
345
343 notebook_display_formatter : func used to format links for display
346 notebook_display_formatter : func used to format links for display
344 in the notebook. See discussion of formatter function below.
347 in the notebook. See discussion of formatter function below.
345
348
346 terminal_display_formatter : func used to format links for display
349 terminal_display_formatter : func used to format links for display
347 in the terminal. See discussion of formatter function below.
350 in the terminal. See discussion of formatter function below.
348
351
349
352
350 Passing custom formatter functions
353 Passing custom formatter functions
351 ----------------------------------
354 ----------------------------------
352 Formatter functions must be of the form:
355 Formatter functions must be of the form:
353 f(dirname, fnames, included_suffixes)
356 f(dirname, fnames, included_suffixes)
354 dirname : the name of a directory (a string),
357 dirname : the name of a directory (a string),
355 fnames : a list of the files in that directory
358 fnames : a list of the files in that directory
356 included_suffixes : a list of the file suffixes that should be
359 included_suffixes : a list of the file suffixes that should be
357 included in the output (passing None means
360 included in the output (passing None means
358 to include all suffixes in the output in
361 to include all suffixes in the output in
359 the built-in formatters)
362 the built-in formatters)
360
363
361 returns a list of lines that should will be print in the
364 returns a list of lines that should will be print in the
362 notebook (if passing notebook_display_formatter) or the terminal
365 notebook (if passing notebook_display_formatter) or the terminal
363 (if passing terminal_display_formatter). This function is iterated
366 (if passing terminal_display_formatter). This function is iterated
364 over for each directory in self.path. Default formatters are in
367 over for each directory in self.path. Default formatters are in
365 place, can be passed here to support alternative formatting.
368 place, can be passed here to support alternative formatting.
366
369
367 """
370 """
368 if isfile(path):
371 if isfile(path):
369 raise ValueError("Cannot display a file using FileLinks. "
372 raise ValueError("Cannot display a file using FileLinks. "
370 "Use FileLink to display '%s'." % path)
373 "Use FileLink to display '%s'." % path)
371 self.included_suffixes = included_suffixes
374 self.included_suffixes = included_suffixes
372 # remove trailing slashs for more consistent output formatting
375 # remove trailing slashs for more consistent output formatting
373 path = path.rstrip('/')
376 path = path.rstrip('/')
374
377
375 self.path = path
378 self.path = path
376 self.url_prefix = url_prefix
379 self.url_prefix = url_prefix
377 self.result_html_prefix = result_html_prefix
380 self.result_html_prefix = result_html_prefix
378 self.result_html_suffix = result_html_suffix
381 self.result_html_suffix = result_html_suffix
379
382
380 self.notebook_display_formatter = \
383 self.notebook_display_formatter = \
381 notebook_display_formatter or self._get_notebook_display_formatter()
384 notebook_display_formatter or self._get_notebook_display_formatter()
382 self.terminal_display_formatter = \
385 self.terminal_display_formatter = \
383 terminal_display_formatter or self._get_terminal_display_formatter()
386 terminal_display_formatter or self._get_terminal_display_formatter()
384
387
385 def _get_display_formatter(self,
388 def _get_display_formatter(self,
386 dirname_output_format,
389 dirname_output_format,
387 fname_output_format,
390 fname_output_format,
388 fp_format,
391 fp_format,
389 fp_cleaner=None):
392 fp_cleaner=None):
390 """ generate built-in formatter function
393 """ generate built-in formatter function
391
394
392 this is used to define both the notebook and terminal built-in
395 this is used to define both the notebook and terminal built-in
393 formatters as they only differ by some wrapper text for each entry
396 formatters as they only differ by some wrapper text for each entry
394
397
395 dirname_output_format: string to use for formatting directory
398 dirname_output_format: string to use for formatting directory
396 names, dirname will be substituted for a single "%s" which
399 names, dirname will be substituted for a single "%s" which
397 must appear in this string
400 must appear in this string
398 fname_output_format: string to use for formatting file names,
401 fname_output_format: string to use for formatting file names,
399 if a single "%s" appears in the string, fname will be substituted
402 if a single "%s" appears in the string, fname will be substituted
400 if two "%s" appear in the string, the path to fname will be
403 if two "%s" appear in the string, the path to fname will be
401 substituted for the first and fname will be substituted for the
404 substituted for the first and fname will be substituted for the
402 second
405 second
403 fp_format: string to use for formatting filepaths, must contain
406 fp_format: string to use for formatting filepaths, must contain
404 exactly two "%s" and the dirname will be subsituted for the first
407 exactly two "%s" and the dirname will be subsituted for the first
405 and fname will be substituted for the second
408 and fname will be substituted for the second
406 """
409 """
407 def f(dirname, fnames, included_suffixes=None):
410 def f(dirname, fnames, included_suffixes=None):
408 result = []
411 result = []
409 # begin by figuring out which filenames, if any,
412 # begin by figuring out which filenames, if any,
410 # are going to be displayed
413 # are going to be displayed
411 display_fnames = []
414 display_fnames = []
412 for fname in fnames:
415 for fname in fnames:
413 if (isfile(join(dirname,fname)) and
416 if (isfile(join(dirname,fname)) and
414 (included_suffixes == None or
417 (included_suffixes == None or
415 splitext(fname)[1] in included_suffixes)):
418 splitext(fname)[1] in included_suffixes)):
416 display_fnames.append(fname)
419 display_fnames.append(fname)
417
420
418 if len(display_fnames) == 0:
421 if len(display_fnames) == 0:
419 # if there are no filenames to display, don't print anything
422 # if there are no filenames to display, don't print anything
420 # (not even the directory name)
423 # (not even the directory name)
421 pass
424 pass
422 else:
425 else:
423 # otherwise print the formatted directory name followed by
426 # otherwise print the formatted directory name followed by
424 # the formatted filenames
427 # the formatted filenames
425 dirname_output_line = dirname_output_format % dirname
428 dirname_output_line = dirname_output_format % dirname
426 result.append(dirname_output_line)
429 result.append(dirname_output_line)
427 for fname in display_fnames:
430 for fname in display_fnames:
428 fp = fp_format % (dirname,fname)
431 fp = fp_format % (dirname,fname)
429 if fp_cleaner is not None:
432 if fp_cleaner is not None:
430 fp = fp_cleaner(fp)
433 fp = fp_cleaner(fp)
431 try:
434 try:
432 # output can include both a filepath and a filename...
435 # output can include both a filepath and a filename...
433 fname_output_line = fname_output_format % (fp, fname)
436 fname_output_line = fname_output_format % (fp, fname)
434 except TypeError:
437 except TypeError:
435 # ... or just a single filepath
438 # ... or just a single filepath
436 fname_output_line = fname_output_format % fname
439 fname_output_line = fname_output_format % fname
437 result.append(fname_output_line)
440 result.append(fname_output_line)
438 return result
441 return result
439 return f
442 return f
440
443
441 def _get_notebook_display_formatter(self,
444 def _get_notebook_display_formatter(self,
442 spacer="&nbsp;&nbsp;"):
445 spacer="&nbsp;&nbsp;"):
443 """ generate function to use for notebook formatting
446 """ generate function to use for notebook formatting
444 """
447 """
445 dirname_output_format = \
448 dirname_output_format = \
446 self.result_html_prefix + "%s/" + self.result_html_suffix
449 self.result_html_prefix + "%s/" + self.result_html_suffix
447 fname_output_format = \
450 fname_output_format = \
448 self.result_html_prefix + spacer + self.html_link_str + self.result_html_suffix
451 self.result_html_prefix + spacer + self.html_link_str + self.result_html_suffix
449 fp_format = self.url_prefix + '%s/%s'
452 fp_format = self.url_prefix + '%s/%s'
450 if sep == "\\":
453 if sep == "\\":
451 # Working on a platform where the path separator is "\", so
454 # Working on a platform where the path separator is "\", so
452 # must convert these to "/" for generating a URI
455 # must convert these to "/" for generating a URI
453 def fp_cleaner(fp):
456 def fp_cleaner(fp):
454 # Replace all occurences of backslash ("\") with a forward
457 # Replace all occurences of backslash ("\") with a forward
455 # slash ("/") - this is necessary on windows when a path is
458 # slash ("/") - this is necessary on windows when a path is
456 # provided as input, but we must link to a URI
459 # provided as input, but we must link to a URI
457 return fp.replace('\\','/')
460 return fp.replace('\\','/')
458 else:
461 else:
459 fp_cleaner = None
462 fp_cleaner = None
460
463
461 return self._get_display_formatter(dirname_output_format,
464 return self._get_display_formatter(dirname_output_format,
462 fname_output_format,
465 fname_output_format,
463 fp_format,
466 fp_format,
464 fp_cleaner)
467 fp_cleaner)
465
468
466 def _get_terminal_display_formatter(self,
469 def _get_terminal_display_formatter(self,
467 spacer=" "):
470 spacer=" "):
468 """ generate function to use for terminal formatting
471 """ generate function to use for terminal formatting
469 """
472 """
470 dirname_output_format = "%s/"
473 dirname_output_format = "%s/"
471 fname_output_format = spacer + "%s"
474 fname_output_format = spacer + "%s"
472 fp_format = '%s/%s'
475 fp_format = '%s/%s'
473
476
474 return self._get_display_formatter(dirname_output_format,
477 return self._get_display_formatter(dirname_output_format,
475 fname_output_format,
478 fname_output_format,
476 fp_format)
479 fp_format)
477
480
478 def _format_path(self):
481 def _format_path(self):
479 result_lines = []
482 result_lines = []
480 walked_dir = list(walk(self.path))
483 walked_dir = list(walk(self.path))
481 walked_dir.sort()
484 walked_dir.sort()
482 for dirname, subdirs, fnames in walked_dir:
485 for dirname, subdirs, fnames in walked_dir:
483 result_lines += self.notebook_display_formatter(dirname, fnames, self.included_suffixes)
486 result_lines += self.notebook_display_formatter(dirname, fnames, self.included_suffixes)
484 return '\n'.join(result_lines)
487 return '\n'.join(result_lines)
485
488
486 def __repr__(self):
489 def __repr__(self):
487 """return newline-separated absolute paths
490 """return newline-separated absolute paths
488 """
491 """
489 result_lines = []
492 result_lines = []
490 walked_dir = list(walk(self.path))
493 walked_dir = list(walk(self.path))
491 walked_dir.sort()
494 walked_dir.sort()
492 for dirname, subdirs, fnames in walked_dir:
495 for dirname, subdirs, fnames in walked_dir:
493 result_lines += self.terminal_display_formatter(dirname, fnames, self.included_suffixes)
496 result_lines += self.terminal_display_formatter(dirname, fnames, self.included_suffixes)
494 return '\n'.join(result_lines)
497 return '\n'.join(result_lines)
@@ -1,241 +1,245 b''
1 """
1 """
2 Tools to open .py files as Unicode, using the encoding specified within the file,
2 Tools to open .py files as Unicode, using the encoding specified within the file,
3 as per PEP 263.
3 as per PEP 263.
4
4
5 Much of the code is taken from the tokenize module in Python 3.2.
5 Much of the code is taken from the tokenize module in Python 3.2.
6 """
6 """
7 from __future__ import absolute_import
7 from __future__ import absolute_import
8
8
9 import io
9 import io
10 from io import TextIOWrapper, BytesIO
10 from io import TextIOWrapper, BytesIO
11 import os.path
11 import os.path
12 import re
12 import re
13
13
14 from .py3compat import unicode_type
14 from .py3compat import unicode_type
15
15
16 cookie_re = re.compile(r"coding[:=]\s*([-\w.]+)", re.UNICODE)
16 cookie_re = re.compile(r"coding[:=]\s*([-\w.]+)", re.UNICODE)
17 cookie_comment_re = re.compile(r"^\s*#.*coding[:=]\s*([-\w.]+)", re.UNICODE)
17 cookie_comment_re = re.compile(r"^\s*#.*coding[:=]\s*([-\w.]+)", re.UNICODE)
18
18
19 try:
19 try:
20 # Available in Python 3
20 # Available in Python 3
21 from tokenize import detect_encoding
21 from tokenize import detect_encoding
22 except ImportError:
22 except ImportError:
23 from codecs import lookup, BOM_UTF8
23 from codecs import lookup, BOM_UTF8
24
24
25 # Copied from Python 3.2 tokenize
25 # Copied from Python 3.2 tokenize
26 def _get_normal_name(orig_enc):
26 def _get_normal_name(orig_enc):
27 """Imitates get_normal_name in tokenizer.c."""
27 """Imitates get_normal_name in tokenizer.c."""
28 # Only care about the first 12 characters.
28 # Only care about the first 12 characters.
29 enc = orig_enc[:12].lower().replace("_", "-")
29 enc = orig_enc[:12].lower().replace("_", "-")
30 if enc == "utf-8" or enc.startswith("utf-8-"):
30 if enc == "utf-8" or enc.startswith("utf-8-"):
31 return "utf-8"
31 return "utf-8"
32 if enc in ("latin-1", "iso-8859-1", "iso-latin-1") or \
32 if enc in ("latin-1", "iso-8859-1", "iso-latin-1") or \
33 enc.startswith(("latin-1-", "iso-8859-1-", "iso-latin-1-")):
33 enc.startswith(("latin-1-", "iso-8859-1-", "iso-latin-1-")):
34 return "iso-8859-1"
34 return "iso-8859-1"
35 return orig_enc
35 return orig_enc
36
36
37 # Copied from Python 3.2 tokenize
37 # Copied from Python 3.2 tokenize
38 def detect_encoding(readline):
38 def detect_encoding(readline):
39 """
39 """
40 The detect_encoding() function is used to detect the encoding that should
40 The detect_encoding() function is used to detect the encoding that should
41 be used to decode a Python source file. It requires one argment, readline,
41 be used to decode a Python source file. It requires one argment, readline,
42 in the same way as the tokenize() generator.
42 in the same way as the tokenize() generator.
43
43
44 It will call readline a maximum of twice, and return the encoding used
44 It will call readline a maximum of twice, and return the encoding used
45 (as a string) and a list of any lines (left as bytes) it has read in.
45 (as a string) and a list of any lines (left as bytes) it has read in.
46
46
47 It detects the encoding from the presence of a utf-8 bom or an encoding
47 It detects the encoding from the presence of a utf-8 bom or an encoding
48 cookie as specified in pep-0263. If both a bom and a cookie are present,
48 cookie as specified in pep-0263. If both a bom and a cookie are present,
49 but disagree, a SyntaxError will be raised. If the encoding cookie is an
49 but disagree, a SyntaxError will be raised. If the encoding cookie is an
50 invalid charset, raise a SyntaxError. Note that if a utf-8 bom is found,
50 invalid charset, raise a SyntaxError. Note that if a utf-8 bom is found,
51 'utf-8-sig' is returned.
51 'utf-8-sig' is returned.
52
52
53 If no encoding is specified, then the default of 'utf-8' will be returned.
53 If no encoding is specified, then the default of 'utf-8' will be returned.
54 """
54 """
55 bom_found = False
55 bom_found = False
56 encoding = None
56 encoding = None
57 default = 'utf-8'
57 default = 'utf-8'
58 def read_or_stop():
58 def read_or_stop():
59 try:
59 try:
60 return readline()
60 return readline()
61 except StopIteration:
61 except StopIteration:
62 return b''
62 return b''
63
63
64 def find_cookie(line):
64 def find_cookie(line):
65 try:
65 try:
66 line_string = line.decode('ascii')
66 line_string = line.decode('ascii')
67 except UnicodeDecodeError:
67 except UnicodeDecodeError:
68 return None
68 return None
69
69
70 matches = cookie_re.findall(line_string)
70 matches = cookie_re.findall(line_string)
71 if not matches:
71 if not matches:
72 return None
72 return None
73 encoding = _get_normal_name(matches[0])
73 encoding = _get_normal_name(matches[0])
74 try:
74 try:
75 codec = lookup(encoding)
75 codec = lookup(encoding)
76 except LookupError:
76 except LookupError:
77 # This behaviour mimics the Python interpreter
77 # This behaviour mimics the Python interpreter
78 raise SyntaxError("unknown encoding: " + encoding)
78 raise SyntaxError("unknown encoding: " + encoding)
79
79
80 if bom_found:
80 if bom_found:
81 if codec.name != 'utf-8':
81 if codec.name != 'utf-8':
82 # This behaviour mimics the Python interpreter
82 # This behaviour mimics the Python interpreter
83 raise SyntaxError('encoding problem: utf-8')
83 raise SyntaxError('encoding problem: utf-8')
84 encoding += '-sig'
84 encoding += '-sig'
85 return encoding
85 return encoding
86
86
87 first = read_or_stop()
87 first = read_or_stop()
88 if first.startswith(BOM_UTF8):
88 if first.startswith(BOM_UTF8):
89 bom_found = True
89 bom_found = True
90 first = first[3:]
90 first = first[3:]
91 default = 'utf-8-sig'
91 default = 'utf-8-sig'
92 if not first:
92 if not first:
93 return default, []
93 return default, []
94
94
95 encoding = find_cookie(first)
95 encoding = find_cookie(first)
96 if encoding:
96 if encoding:
97 return encoding, [first]
97 return encoding, [first]
98
98
99 second = read_or_stop()
99 second = read_or_stop()
100 if not second:
100 if not second:
101 return default, [first]
101 return default, [first]
102
102
103 encoding = find_cookie(second)
103 encoding = find_cookie(second)
104 if encoding:
104 if encoding:
105 return encoding, [first, second]
105 return encoding, [first, second]
106
106
107 return default, [first, second]
107 return default, [first, second]
108
108
109 try:
109 try:
110 # Available in Python 3.2 and above.
110 # Available in Python 3.2 and above.
111 from tokenize import open
111 from tokenize import open
112 except ImportError:
112 except ImportError:
113 # Copied from Python 3.2 tokenize
113 # Copied from Python 3.2 tokenize
114 def open(filename):
114 def open(filename):
115 """Open a file in read only mode using the encoding detected by
115 """Open a file in read only mode using the encoding detected by
116 detect_encoding().
116 detect_encoding().
117 """
117 """
118 buffer = io.open(filename, 'rb') # Tweaked to use io.open for Python 2
118 buffer = io.open(filename, 'rb') # Tweaked to use io.open for Python 2
119 encoding, lines = detect_encoding(buffer.readline)
119 encoding, lines = detect_encoding(buffer.readline)
120 buffer.seek(0)
120 buffer.seek(0)
121 text = TextIOWrapper(buffer, encoding, line_buffering=True)
121 text = TextIOWrapper(buffer, encoding, line_buffering=True)
122 text.mode = 'r'
122 text.mode = 'r'
123 return text
123 return text
124
124
125 def source_to_unicode(txt, errors='replace', skip_encoding_cookie=True):
125 def source_to_unicode(txt, errors='replace', skip_encoding_cookie=True):
126 """Converts a bytes string with python source code to unicode.
126 """Converts a bytes string with python source code to unicode.
127
127
128 Unicode strings are passed through unchanged. Byte strings are checked
128 Unicode strings are passed through unchanged. Byte strings are checked
129 for the python source file encoding cookie to determine encoding.
129 for the python source file encoding cookie to determine encoding.
130 txt can be either a bytes buffer or a string containing the source
130 txt can be either a bytes buffer or a string containing the source
131 code.
131 code.
132 """
132 """
133 if isinstance(txt, unicode_type):
133 if isinstance(txt, unicode_type):
134 return txt
134 return txt
135 if isinstance(txt, bytes):
135 if isinstance(txt, bytes):
136 buffer = BytesIO(txt)
136 buffer = BytesIO(txt)
137 else:
137 else:
138 buffer = txt
138 buffer = txt
139 try:
139 try:
140 encoding, _ = detect_encoding(buffer.readline)
140 encoding, _ = detect_encoding(buffer.readline)
141 except SyntaxError:
141 except SyntaxError:
142 encoding = "ascii"
142 encoding = "ascii"
143 buffer.seek(0)
143 buffer.seek(0)
144 text = TextIOWrapper(buffer, encoding, errors=errors, line_buffering=True)
144 text = TextIOWrapper(buffer, encoding, errors=errors, line_buffering=True)
145 text.mode = 'r'
145 text.mode = 'r'
146 if skip_encoding_cookie:
146 if skip_encoding_cookie:
147 return u"".join(strip_encoding_cookie(text))
147 return u"".join(strip_encoding_cookie(text))
148 else:
148 else:
149 return text.read()
149 return text.read()
150
150
151 def strip_encoding_cookie(filelike):
151 def strip_encoding_cookie(filelike):
152 """Generator to pull lines from a text-mode file, skipping the encoding
152 """Generator to pull lines from a text-mode file, skipping the encoding
153 cookie if it is found in the first two lines.
153 cookie if it is found in the first two lines.
154 """
154 """
155 it = iter(filelike)
155 it = iter(filelike)
156 try:
156 try:
157 first = next(it)
157 first = next(it)
158 if not cookie_comment_re.match(first):
158 if not cookie_comment_re.match(first):
159 yield first
159 yield first
160 second = next(it)
160 second = next(it)
161 if not cookie_comment_re.match(second):
161 if not cookie_comment_re.match(second):
162 yield second
162 yield second
163 except StopIteration:
163 except StopIteration:
164 return
164 return
165
165
166 for line in it:
166 for line in it:
167 yield line
167 yield line
168
168
169 def read_py_file(filename, skip_encoding_cookie=True):
169 def read_py_file(filename, skip_encoding_cookie=True):
170 """Read a Python file, using the encoding declared inside the file.
170 """Read a Python file, using the encoding declared inside the file.
171
171
172 Parameters
172 Parameters
173 ----------
173 ----------
174 filename : str
174 filename : str
175 The path to the file to read.
175 The path to the file to read.
176 skip_encoding_cookie : bool
176 skip_encoding_cookie : bool
177 If True (the default), and the encoding declaration is found in the first
177 If True (the default), and the encoding declaration is found in the first
178 two lines, that line will be excluded from the output - compiling a
178 two lines, that line will be excluded from the output - compiling a
179 unicode string with an encoding declaration is a SyntaxError in Python 2.
179 unicode string with an encoding declaration is a SyntaxError in Python 2.
180
180
181 Returns
181 Returns
182 -------
182 -------
183 A unicode string containing the contents of the file.
183 A unicode string containing the contents of the file.
184 """
184 """
185 with open(filename) as f: # the open function defined in this module.
185 with open(filename) as f: # the open function defined in this module.
186 if skip_encoding_cookie:
186 if skip_encoding_cookie:
187 return "".join(strip_encoding_cookie(f))
187 return "".join(strip_encoding_cookie(f))
188 else:
188 else:
189 return f.read()
189 return f.read()
190
190
191 def read_py_url(url, errors='replace', skip_encoding_cookie=True):
191 def read_py_url(url, errors='replace', skip_encoding_cookie=True):
192 """Read a Python file from a URL, using the encoding declared inside the file.
192 """Read a Python file from a URL, using the encoding declared inside the file.
193
193
194 Parameters
194 Parameters
195 ----------
195 ----------
196 url : str
196 url : str
197 The URL from which to fetch the file.
197 The URL from which to fetch the file.
198 errors : str
198 errors : str
199 How to handle decoding errors in the file. Options are the same as for
199 How to handle decoding errors in the file. Options are the same as for
200 bytes.decode(), but here 'replace' is the default.
200 bytes.decode(), but here 'replace' is the default.
201 skip_encoding_cookie : bool
201 skip_encoding_cookie : bool
202 If True (the default), and the encoding declaration is found in the first
202 If True (the default), and the encoding declaration is found in the first
203 two lines, that line will be excluded from the output - compiling a
203 two lines, that line will be excluded from the output - compiling a
204 unicode string with an encoding declaration is a SyntaxError in Python 2.
204 unicode string with an encoding declaration is a SyntaxError in Python 2.
205
205
206 Returns
206 Returns
207 -------
207 -------
208 A unicode string containing the contents of the file.
208 A unicode string containing the contents of the file.
209 """
209 """
210 from urllib import urlopen # Deferred import for faster start
210 # Deferred import for faster start
211 try:
212 from urllib.request import urlopen # Py 3
213 except ImportError:
214 from urllib import urlopen
211 response = urlopen(url)
215 response = urlopen(url)
212 buffer = io.BytesIO(response.read())
216 buffer = io.BytesIO(response.read())
213 return source_to_unicode(buffer, errors, skip_encoding_cookie)
217 return source_to_unicode(buffer, errors, skip_encoding_cookie)
214
218
215 def _list_readline(x):
219 def _list_readline(x):
216 """Given a list, returns a readline() function that returns the next element
220 """Given a list, returns a readline() function that returns the next element
217 with each call.
221 with each call.
218 """
222 """
219 x = iter(x)
223 x = iter(x)
220 def readline():
224 def readline():
221 return next(x)
225 return next(x)
222 return readline
226 return readline
223
227
224 # Code for going between .py files and cached .pyc files ----------------------
228 # Code for going between .py files and cached .pyc files ----------------------
225
229
226 try: # Python 3.2, see PEP 3147
230 try: # Python 3.2, see PEP 3147
227 from imp import source_from_cache, cache_from_source
231 from imp import source_from_cache, cache_from_source
228 except ImportError:
232 except ImportError:
229 # Python <= 3.1: .pyc files go next to .py
233 # Python <= 3.1: .pyc files go next to .py
230 def source_from_cache(path):
234 def source_from_cache(path):
231 basename, ext = os.path.splitext(path)
235 basename, ext = os.path.splitext(path)
232 if ext not in ('.pyc', '.pyo'):
236 if ext not in ('.pyc', '.pyo'):
233 raise ValueError('Not a cached Python file extension', ext)
237 raise ValueError('Not a cached Python file extension', ext)
234 # Should we look for .pyw files?
238 # Should we look for .pyw files?
235 return basename + '.py'
239 return basename + '.py'
236
240
237 def cache_from_source(path, debug_override=None):
241 def cache_from_source(path, debug_override=None):
238 if debug_override is None:
242 if debug_override is None:
239 debug_override = __debug__
243 debug_override = __debug__
240 basename, ext = os.path.splitext(path)
244 basename, ext = os.path.splitext(path)
241 return basename + '.pyc' if debug_override else '.pyo'
245 return basename + '.pyc' if debug_override else '.pyo'
General Comments 0
You need to be logged in to leave comments. Login now