##// END OF EJS Templates
Merge pull request #12381 from cool-RR/2020-06-09-raise-from
Matthias Bussonnier -
r25830:66921af3 merge
parent child Browse files
Show More
@@ -1,1024 +1,1024
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Display formatters.
2 """Display formatters.
3
3
4 Inheritance diagram:
4 Inheritance diagram:
5
5
6 .. inheritance-diagram:: IPython.core.formatters
6 .. inheritance-diagram:: IPython.core.formatters
7 :parts: 3
7 :parts: 3
8 """
8 """
9
9
10 # Copyright (c) IPython Development Team.
10 # Copyright (c) IPython Development Team.
11 # Distributed under the terms of the Modified BSD License.
11 # Distributed under the terms of the Modified BSD License.
12
12
13 import abc
13 import abc
14 import json
14 import json
15 import sys
15 import sys
16 import traceback
16 import traceback
17 import warnings
17 import warnings
18 from io import StringIO
18 from io import StringIO
19
19
20 from decorator import decorator
20 from decorator import decorator
21
21
22 from traitlets.config.configurable import Configurable
22 from traitlets.config.configurable import Configurable
23 from .getipython import get_ipython
23 from .getipython import get_ipython
24 from ..utils.sentinel import Sentinel
24 from ..utils.sentinel import Sentinel
25 from ..utils.dir2 import get_real_method
25 from ..utils.dir2 import get_real_method
26 from ..lib import pretty
26 from ..lib import pretty
27 from traitlets import (
27 from traitlets import (
28 Bool, Dict, Integer, Unicode, CUnicode, ObjectName, List,
28 Bool, Dict, Integer, Unicode, CUnicode, ObjectName, List,
29 ForwardDeclaredInstance,
29 ForwardDeclaredInstance,
30 default, observe,
30 default, observe,
31 )
31 )
32
32
33
33
34 class DisplayFormatter(Configurable):
34 class DisplayFormatter(Configurable):
35
35
36 active_types = List(Unicode(),
36 active_types = List(Unicode(),
37 help="""List of currently active mime-types to display.
37 help="""List of currently active mime-types to display.
38 You can use this to set a white-list for formats to display.
38 You can use this to set a white-list for formats to display.
39
39
40 Most users will not need to change this value.
40 Most users will not need to change this value.
41 """).tag(config=True)
41 """).tag(config=True)
42
42
43 @default('active_types')
43 @default('active_types')
44 def _active_types_default(self):
44 def _active_types_default(self):
45 return self.format_types
45 return self.format_types
46
46
47 @observe('active_types')
47 @observe('active_types')
48 def _active_types_changed(self, change):
48 def _active_types_changed(self, change):
49 for key, formatter in self.formatters.items():
49 for key, formatter in self.formatters.items():
50 if key in change['new']:
50 if key in change['new']:
51 formatter.enabled = True
51 formatter.enabled = True
52 else:
52 else:
53 formatter.enabled = False
53 formatter.enabled = False
54
54
55 ipython_display_formatter = ForwardDeclaredInstance('FormatterABC')
55 ipython_display_formatter = ForwardDeclaredInstance('FormatterABC')
56 @default('ipython_display_formatter')
56 @default('ipython_display_formatter')
57 def _default_formatter(self):
57 def _default_formatter(self):
58 return IPythonDisplayFormatter(parent=self)
58 return IPythonDisplayFormatter(parent=self)
59
59
60 mimebundle_formatter = ForwardDeclaredInstance('FormatterABC')
60 mimebundle_formatter = ForwardDeclaredInstance('FormatterABC')
61 @default('mimebundle_formatter')
61 @default('mimebundle_formatter')
62 def _default_mime_formatter(self):
62 def _default_mime_formatter(self):
63 return MimeBundleFormatter(parent=self)
63 return MimeBundleFormatter(parent=self)
64
64
65 # A dict of formatter whose keys are format types (MIME types) and whose
65 # A dict of formatter whose keys are format types (MIME types) and whose
66 # values are subclasses of BaseFormatter.
66 # values are subclasses of BaseFormatter.
67 formatters = Dict()
67 formatters = Dict()
68 @default('formatters')
68 @default('formatters')
69 def _formatters_default(self):
69 def _formatters_default(self):
70 """Activate the default formatters."""
70 """Activate the default formatters."""
71 formatter_classes = [
71 formatter_classes = [
72 PlainTextFormatter,
72 PlainTextFormatter,
73 HTMLFormatter,
73 HTMLFormatter,
74 MarkdownFormatter,
74 MarkdownFormatter,
75 SVGFormatter,
75 SVGFormatter,
76 PNGFormatter,
76 PNGFormatter,
77 PDFFormatter,
77 PDFFormatter,
78 JPEGFormatter,
78 JPEGFormatter,
79 LatexFormatter,
79 LatexFormatter,
80 JSONFormatter,
80 JSONFormatter,
81 JavascriptFormatter
81 JavascriptFormatter
82 ]
82 ]
83 d = {}
83 d = {}
84 for cls in formatter_classes:
84 for cls in formatter_classes:
85 f = cls(parent=self)
85 f = cls(parent=self)
86 d[f.format_type] = f
86 d[f.format_type] = f
87 return d
87 return d
88
88
89 def format(self, obj, include=None, exclude=None):
89 def format(self, obj, include=None, exclude=None):
90 """Return a format data dict for an object.
90 """Return a format data dict for an object.
91
91
92 By default all format types will be computed.
92 By default all format types will be computed.
93
93
94 The following MIME types are usually implemented:
94 The following MIME types are usually implemented:
95
95
96 * text/plain
96 * text/plain
97 * text/html
97 * text/html
98 * text/markdown
98 * text/markdown
99 * text/latex
99 * text/latex
100 * application/json
100 * application/json
101 * application/javascript
101 * application/javascript
102 * application/pdf
102 * application/pdf
103 * image/png
103 * image/png
104 * image/jpeg
104 * image/jpeg
105 * image/svg+xml
105 * image/svg+xml
106
106
107 Parameters
107 Parameters
108 ----------
108 ----------
109 obj : object
109 obj : object
110 The Python object whose format data will be computed.
110 The Python object whose format data will be computed.
111 include : list, tuple or set; optional
111 include : list, tuple or set; optional
112 A list of format type strings (MIME types) to include in the
112 A list of format type strings (MIME types) to include in the
113 format data dict. If this is set *only* the format types included
113 format data dict. If this is set *only* the format types included
114 in this list will be computed.
114 in this list will be computed.
115 exclude : list, tuple or set; optional
115 exclude : list, tuple or set; optional
116 A list of format type string (MIME types) to exclude in the format
116 A list of format type string (MIME types) to exclude in the format
117 data dict. If this is set all format types will be computed,
117 data dict. If this is set all format types will be computed,
118 except for those included in this argument.
118 except for those included in this argument.
119 Mimetypes present in exclude will take precedence over the ones in include
119 Mimetypes present in exclude will take precedence over the ones in include
120
120
121 Returns
121 Returns
122 -------
122 -------
123 (format_dict, metadata_dict) : tuple of two dicts
123 (format_dict, metadata_dict) : tuple of two dicts
124
124
125 format_dict is a dictionary of key/value pairs, one of each format that was
125 format_dict is a dictionary of key/value pairs, one of each format that was
126 generated for the object. The keys are the format types, which
126 generated for the object. The keys are the format types, which
127 will usually be MIME type strings and the values and JSON'able
127 will usually be MIME type strings and the values and JSON'able
128 data structure containing the raw data for the representation in
128 data structure containing the raw data for the representation in
129 that format.
129 that format.
130
130
131 metadata_dict is a dictionary of metadata about each mime-type output.
131 metadata_dict is a dictionary of metadata about each mime-type output.
132 Its keys will be a strict subset of the keys in format_dict.
132 Its keys will be a strict subset of the keys in format_dict.
133
133
134 Notes
134 Notes
135 -----
135 -----
136
136
137 If an object implement `_repr_mimebundle_` as well as various
137 If an object implement `_repr_mimebundle_` as well as various
138 `_repr_*_`, the data returned by `_repr_mimebundle_` will take
138 `_repr_*_`, the data returned by `_repr_mimebundle_` will take
139 precedence and the corresponding `_repr_*_` for this mimetype will
139 precedence and the corresponding `_repr_*_` for this mimetype will
140 not be called.
140 not be called.
141
141
142 """
142 """
143 format_dict = {}
143 format_dict = {}
144 md_dict = {}
144 md_dict = {}
145
145
146 if self.ipython_display_formatter(obj):
146 if self.ipython_display_formatter(obj):
147 # object handled itself, don't proceed
147 # object handled itself, don't proceed
148 return {}, {}
148 return {}, {}
149
149
150 format_dict, md_dict = self.mimebundle_formatter(obj, include=include, exclude=exclude)
150 format_dict, md_dict = self.mimebundle_formatter(obj, include=include, exclude=exclude)
151
151
152 if format_dict or md_dict:
152 if format_dict or md_dict:
153 if include:
153 if include:
154 format_dict = {k:v for k,v in format_dict.items() if k in include}
154 format_dict = {k:v for k,v in format_dict.items() if k in include}
155 md_dict = {k:v for k,v in md_dict.items() if k in include}
155 md_dict = {k:v for k,v in md_dict.items() if k in include}
156 if exclude:
156 if exclude:
157 format_dict = {k:v for k,v in format_dict.items() if k not in exclude}
157 format_dict = {k:v for k,v in format_dict.items() if k not in exclude}
158 md_dict = {k:v for k,v in md_dict.items() if k not in exclude}
158 md_dict = {k:v for k,v in md_dict.items() if k not in exclude}
159
159
160 for format_type, formatter in self.formatters.items():
160 for format_type, formatter in self.formatters.items():
161 if format_type in format_dict:
161 if format_type in format_dict:
162 # already got it from mimebundle, maybe don't render again.
162 # already got it from mimebundle, maybe don't render again.
163 # exception: manually registered per-mime renderer
163 # exception: manually registered per-mime renderer
164 # check priority:
164 # check priority:
165 # 1. user-registered per-mime formatter
165 # 1. user-registered per-mime formatter
166 # 2. mime-bundle (user-registered or repr method)
166 # 2. mime-bundle (user-registered or repr method)
167 # 3. default per-mime formatter (e.g. repr method)
167 # 3. default per-mime formatter (e.g. repr method)
168 try:
168 try:
169 formatter.lookup(obj)
169 formatter.lookup(obj)
170 except KeyError:
170 except KeyError:
171 # no special formatter, use mime-bundle-provided value
171 # no special formatter, use mime-bundle-provided value
172 continue
172 continue
173 if include and format_type not in include:
173 if include and format_type not in include:
174 continue
174 continue
175 if exclude and format_type in exclude:
175 if exclude and format_type in exclude:
176 continue
176 continue
177
177
178 md = None
178 md = None
179 try:
179 try:
180 data = formatter(obj)
180 data = formatter(obj)
181 except:
181 except:
182 # FIXME: log the exception
182 # FIXME: log the exception
183 raise
183 raise
184
184
185 # formatters can return raw data or (data, metadata)
185 # formatters can return raw data or (data, metadata)
186 if isinstance(data, tuple) and len(data) == 2:
186 if isinstance(data, tuple) and len(data) == 2:
187 data, md = data
187 data, md = data
188
188
189 if data is not None:
189 if data is not None:
190 format_dict[format_type] = data
190 format_dict[format_type] = data
191 if md is not None:
191 if md is not None:
192 md_dict[format_type] = md
192 md_dict[format_type] = md
193 return format_dict, md_dict
193 return format_dict, md_dict
194
194
195 @property
195 @property
196 def format_types(self):
196 def format_types(self):
197 """Return the format types (MIME types) of the active formatters."""
197 """Return the format types (MIME types) of the active formatters."""
198 return list(self.formatters.keys())
198 return list(self.formatters.keys())
199
199
200
200
201 #-----------------------------------------------------------------------------
201 #-----------------------------------------------------------------------------
202 # Formatters for specific format types (text, html, svg, etc.)
202 # Formatters for specific format types (text, html, svg, etc.)
203 #-----------------------------------------------------------------------------
203 #-----------------------------------------------------------------------------
204
204
205
205
206 def _safe_repr(obj):
206 def _safe_repr(obj):
207 """Try to return a repr of an object
207 """Try to return a repr of an object
208
208
209 always returns a string, at least.
209 always returns a string, at least.
210 """
210 """
211 try:
211 try:
212 return repr(obj)
212 return repr(obj)
213 except Exception as e:
213 except Exception as e:
214 return "un-repr-able object (%r)" % e
214 return "un-repr-able object (%r)" % e
215
215
216
216
217 class FormatterWarning(UserWarning):
217 class FormatterWarning(UserWarning):
218 """Warning class for errors in formatters"""
218 """Warning class for errors in formatters"""
219
219
220 @decorator
220 @decorator
221 def catch_format_error(method, self, *args, **kwargs):
221 def catch_format_error(method, self, *args, **kwargs):
222 """show traceback on failed format call"""
222 """show traceback on failed format call"""
223 try:
223 try:
224 r = method(self, *args, **kwargs)
224 r = method(self, *args, **kwargs)
225 except NotImplementedError:
225 except NotImplementedError:
226 # don't warn on NotImplementedErrors
226 # don't warn on NotImplementedErrors
227 return self._check_return(None, args[0])
227 return self._check_return(None, args[0])
228 except Exception:
228 except Exception:
229 exc_info = sys.exc_info()
229 exc_info = sys.exc_info()
230 ip = get_ipython()
230 ip = get_ipython()
231 if ip is not None:
231 if ip is not None:
232 ip.showtraceback(exc_info)
232 ip.showtraceback(exc_info)
233 else:
233 else:
234 traceback.print_exception(*exc_info)
234 traceback.print_exception(*exc_info)
235 return self._check_return(None, args[0])
235 return self._check_return(None, args[0])
236 return self._check_return(r, args[0])
236 return self._check_return(r, args[0])
237
237
238
238
239 class FormatterABC(metaclass=abc.ABCMeta):
239 class FormatterABC(metaclass=abc.ABCMeta):
240 """ Abstract base class for Formatters.
240 """ Abstract base class for Formatters.
241
241
242 A formatter is a callable class that is responsible for computing the
242 A formatter is a callable class that is responsible for computing the
243 raw format data for a particular format type (MIME type). For example,
243 raw format data for a particular format type (MIME type). For example,
244 an HTML formatter would have a format type of `text/html` and would return
244 an HTML formatter would have a format type of `text/html` and would return
245 the HTML representation of the object when called.
245 the HTML representation of the object when called.
246 """
246 """
247
247
248 # The format type of the data returned, usually a MIME type.
248 # The format type of the data returned, usually a MIME type.
249 format_type = 'text/plain'
249 format_type = 'text/plain'
250
250
251 # Is the formatter enabled...
251 # Is the formatter enabled...
252 enabled = True
252 enabled = True
253
253
254 @abc.abstractmethod
254 @abc.abstractmethod
255 def __call__(self, obj):
255 def __call__(self, obj):
256 """Return a JSON'able representation of the object.
256 """Return a JSON'able representation of the object.
257
257
258 If the object cannot be formatted by this formatter,
258 If the object cannot be formatted by this formatter,
259 warn and return None.
259 warn and return None.
260 """
260 """
261 return repr(obj)
261 return repr(obj)
262
262
263
263
264 def _mod_name_key(typ):
264 def _mod_name_key(typ):
265 """Return a (__module__, __name__) tuple for a type.
265 """Return a (__module__, __name__) tuple for a type.
266
266
267 Used as key in Formatter.deferred_printers.
267 Used as key in Formatter.deferred_printers.
268 """
268 """
269 module = getattr(typ, '__module__', None)
269 module = getattr(typ, '__module__', None)
270 name = getattr(typ, '__name__', None)
270 name = getattr(typ, '__name__', None)
271 return (module, name)
271 return (module, name)
272
272
273
273
274 def _get_type(obj):
274 def _get_type(obj):
275 """Return the type of an instance (old and new-style)"""
275 """Return the type of an instance (old and new-style)"""
276 return getattr(obj, '__class__', None) or type(obj)
276 return getattr(obj, '__class__', None) or type(obj)
277
277
278
278
279 _raise_key_error = Sentinel('_raise_key_error', __name__,
279 _raise_key_error = Sentinel('_raise_key_error', __name__,
280 """
280 """
281 Special value to raise a KeyError
281 Special value to raise a KeyError
282
282
283 Raise KeyError in `BaseFormatter.pop` if passed as the default value to `pop`
283 Raise KeyError in `BaseFormatter.pop` if passed as the default value to `pop`
284 """)
284 """)
285
285
286
286
287 class BaseFormatter(Configurable):
287 class BaseFormatter(Configurable):
288 """A base formatter class that is configurable.
288 """A base formatter class that is configurable.
289
289
290 This formatter should usually be used as the base class of all formatters.
290 This formatter should usually be used as the base class of all formatters.
291 It is a traited :class:`Configurable` class and includes an extensible
291 It is a traited :class:`Configurable` class and includes an extensible
292 API for users to determine how their objects are formatted. The following
292 API for users to determine how their objects are formatted. The following
293 logic is used to find a function to format an given object.
293 logic is used to find a function to format an given object.
294
294
295 1. The object is introspected to see if it has a method with the name
295 1. The object is introspected to see if it has a method with the name
296 :attr:`print_method`. If is does, that object is passed to that method
296 :attr:`print_method`. If is does, that object is passed to that method
297 for formatting.
297 for formatting.
298 2. If no print method is found, three internal dictionaries are consulted
298 2. If no print method is found, three internal dictionaries are consulted
299 to find print method: :attr:`singleton_printers`, :attr:`type_printers`
299 to find print method: :attr:`singleton_printers`, :attr:`type_printers`
300 and :attr:`deferred_printers`.
300 and :attr:`deferred_printers`.
301
301
302 Users should use these dictionaries to register functions that will be
302 Users should use these dictionaries to register functions that will be
303 used to compute the format data for their objects (if those objects don't
303 used to compute the format data for their objects (if those objects don't
304 have the special print methods). The easiest way of using these
304 have the special print methods). The easiest way of using these
305 dictionaries is through the :meth:`for_type` and :meth:`for_type_by_name`
305 dictionaries is through the :meth:`for_type` and :meth:`for_type_by_name`
306 methods.
306 methods.
307
307
308 If no function/callable is found to compute the format data, ``None`` is
308 If no function/callable is found to compute the format data, ``None`` is
309 returned and this format type is not used.
309 returned and this format type is not used.
310 """
310 """
311
311
312 format_type = Unicode('text/plain')
312 format_type = Unicode('text/plain')
313 _return_type = str
313 _return_type = str
314
314
315 enabled = Bool(True).tag(config=True)
315 enabled = Bool(True).tag(config=True)
316
316
317 print_method = ObjectName('__repr__')
317 print_method = ObjectName('__repr__')
318
318
319 # The singleton printers.
319 # The singleton printers.
320 # Maps the IDs of the builtin singleton objects to the format functions.
320 # Maps the IDs of the builtin singleton objects to the format functions.
321 singleton_printers = Dict().tag(config=True)
321 singleton_printers = Dict().tag(config=True)
322
322
323 # The type-specific printers.
323 # The type-specific printers.
324 # Map type objects to the format functions.
324 # Map type objects to the format functions.
325 type_printers = Dict().tag(config=True)
325 type_printers = Dict().tag(config=True)
326
326
327 # The deferred-import type-specific printers.
327 # The deferred-import type-specific printers.
328 # Map (modulename, classname) pairs to the format functions.
328 # Map (modulename, classname) pairs to the format functions.
329 deferred_printers = Dict().tag(config=True)
329 deferred_printers = Dict().tag(config=True)
330
330
331 @catch_format_error
331 @catch_format_error
332 def __call__(self, obj):
332 def __call__(self, obj):
333 """Compute the format for an object."""
333 """Compute the format for an object."""
334 if self.enabled:
334 if self.enabled:
335 # lookup registered printer
335 # lookup registered printer
336 try:
336 try:
337 printer = self.lookup(obj)
337 printer = self.lookup(obj)
338 except KeyError:
338 except KeyError:
339 pass
339 pass
340 else:
340 else:
341 return printer(obj)
341 return printer(obj)
342 # Finally look for special method names
342 # Finally look for special method names
343 method = get_real_method(obj, self.print_method)
343 method = get_real_method(obj, self.print_method)
344 if method is not None:
344 if method is not None:
345 return method()
345 return method()
346 return None
346 return None
347 else:
347 else:
348 return None
348 return None
349
349
350 def __contains__(self, typ):
350 def __contains__(self, typ):
351 """map in to lookup_by_type"""
351 """map in to lookup_by_type"""
352 try:
352 try:
353 self.lookup_by_type(typ)
353 self.lookup_by_type(typ)
354 except KeyError:
354 except KeyError:
355 return False
355 return False
356 else:
356 else:
357 return True
357 return True
358
358
359 def _check_return(self, r, obj):
359 def _check_return(self, r, obj):
360 """Check that a return value is appropriate
360 """Check that a return value is appropriate
361
361
362 Return the value if so, None otherwise, warning if invalid.
362 Return the value if so, None otherwise, warning if invalid.
363 """
363 """
364 if r is None or isinstance(r, self._return_type) or \
364 if r is None or isinstance(r, self._return_type) or \
365 (isinstance(r, tuple) and r and isinstance(r[0], self._return_type)):
365 (isinstance(r, tuple) and r and isinstance(r[0], self._return_type)):
366 return r
366 return r
367 else:
367 else:
368 warnings.warn(
368 warnings.warn(
369 "%s formatter returned invalid type %s (expected %s) for object: %s" % \
369 "%s formatter returned invalid type %s (expected %s) for object: %s" % \
370 (self.format_type, type(r), self._return_type, _safe_repr(obj)),
370 (self.format_type, type(r), self._return_type, _safe_repr(obj)),
371 FormatterWarning
371 FormatterWarning
372 )
372 )
373
373
374 def lookup(self, obj):
374 def lookup(self, obj):
375 """Look up the formatter for a given instance.
375 """Look up the formatter for a given instance.
376
376
377 Parameters
377 Parameters
378 ----------
378 ----------
379 obj : object instance
379 obj : object instance
380
380
381 Returns
381 Returns
382 -------
382 -------
383 f : callable
383 f : callable
384 The registered formatting callable for the type.
384 The registered formatting callable for the type.
385
385
386 Raises
386 Raises
387 ------
387 ------
388 KeyError if the type has not been registered.
388 KeyError if the type has not been registered.
389 """
389 """
390 # look for singleton first
390 # look for singleton first
391 obj_id = id(obj)
391 obj_id = id(obj)
392 if obj_id in self.singleton_printers:
392 if obj_id in self.singleton_printers:
393 return self.singleton_printers[obj_id]
393 return self.singleton_printers[obj_id]
394 # then lookup by type
394 # then lookup by type
395 return self.lookup_by_type(_get_type(obj))
395 return self.lookup_by_type(_get_type(obj))
396
396
397 def lookup_by_type(self, typ):
397 def lookup_by_type(self, typ):
398 """Look up the registered formatter for a type.
398 """Look up the registered formatter for a type.
399
399
400 Parameters
400 Parameters
401 ----------
401 ----------
402 typ : type or '__module__.__name__' string for a type
402 typ : type or '__module__.__name__' string for a type
403
403
404 Returns
404 Returns
405 -------
405 -------
406 f : callable
406 f : callable
407 The registered formatting callable for the type.
407 The registered formatting callable for the type.
408
408
409 Raises
409 Raises
410 ------
410 ------
411 KeyError if the type has not been registered.
411 KeyError if the type has not been registered.
412 """
412 """
413 if isinstance(typ, str):
413 if isinstance(typ, str):
414 typ_key = tuple(typ.rsplit('.',1))
414 typ_key = tuple(typ.rsplit('.',1))
415 if typ_key not in self.deferred_printers:
415 if typ_key not in self.deferred_printers:
416 # We may have it cached in the type map. We will have to
416 # We may have it cached in the type map. We will have to
417 # iterate over all of the types to check.
417 # iterate over all of the types to check.
418 for cls in self.type_printers:
418 for cls in self.type_printers:
419 if _mod_name_key(cls) == typ_key:
419 if _mod_name_key(cls) == typ_key:
420 return self.type_printers[cls]
420 return self.type_printers[cls]
421 else:
421 else:
422 return self.deferred_printers[typ_key]
422 return self.deferred_printers[typ_key]
423 else:
423 else:
424 for cls in pretty._get_mro(typ):
424 for cls in pretty._get_mro(typ):
425 if cls in self.type_printers or self._in_deferred_types(cls):
425 if cls in self.type_printers or self._in_deferred_types(cls):
426 return self.type_printers[cls]
426 return self.type_printers[cls]
427
427
428 # If we have reached here, the lookup failed.
428 # If we have reached here, the lookup failed.
429 raise KeyError("No registered printer for {0!r}".format(typ))
429 raise KeyError("No registered printer for {0!r}".format(typ))
430
430
431 def for_type(self, typ, func=None):
431 def for_type(self, typ, func=None):
432 """Add a format function for a given type.
432 """Add a format function for a given type.
433
433
434 Parameters
434 Parameters
435 -----------
435 -----------
436 typ : type or '__module__.__name__' string for a type
436 typ : type or '__module__.__name__' string for a type
437 The class of the object that will be formatted using `func`.
437 The class of the object that will be formatted using `func`.
438 func : callable
438 func : callable
439 A callable for computing the format data.
439 A callable for computing the format data.
440 `func` will be called with the object to be formatted,
440 `func` will be called with the object to be formatted,
441 and will return the raw data in this formatter's format.
441 and will return the raw data in this formatter's format.
442 Subclasses may use a different call signature for the
442 Subclasses may use a different call signature for the
443 `func` argument.
443 `func` argument.
444
444
445 If `func` is None or not specified, there will be no change,
445 If `func` is None or not specified, there will be no change,
446 only returning the current value.
446 only returning the current value.
447
447
448 Returns
448 Returns
449 -------
449 -------
450 oldfunc : callable
450 oldfunc : callable
451 The currently registered callable.
451 The currently registered callable.
452 If you are registering a new formatter,
452 If you are registering a new formatter,
453 this will be the previous value (to enable restoring later).
453 this will be the previous value (to enable restoring later).
454 """
454 """
455 # if string given, interpret as 'pkg.module.class_name'
455 # if string given, interpret as 'pkg.module.class_name'
456 if isinstance(typ, str):
456 if isinstance(typ, str):
457 type_module, type_name = typ.rsplit('.', 1)
457 type_module, type_name = typ.rsplit('.', 1)
458 return self.for_type_by_name(type_module, type_name, func)
458 return self.for_type_by_name(type_module, type_name, func)
459
459
460 try:
460 try:
461 oldfunc = self.lookup_by_type(typ)
461 oldfunc = self.lookup_by_type(typ)
462 except KeyError:
462 except KeyError:
463 oldfunc = None
463 oldfunc = None
464
464
465 if func is not None:
465 if func is not None:
466 self.type_printers[typ] = func
466 self.type_printers[typ] = func
467
467
468 return oldfunc
468 return oldfunc
469
469
470 def for_type_by_name(self, type_module, type_name, func=None):
470 def for_type_by_name(self, type_module, type_name, func=None):
471 """Add a format function for a type specified by the full dotted
471 """Add a format function for a type specified by the full dotted
472 module and name of the type, rather than the type of the object.
472 module and name of the type, rather than the type of the object.
473
473
474 Parameters
474 Parameters
475 ----------
475 ----------
476 type_module : str
476 type_module : str
477 The full dotted name of the module the type is defined in, like
477 The full dotted name of the module the type is defined in, like
478 ``numpy``.
478 ``numpy``.
479 type_name : str
479 type_name : str
480 The name of the type (the class name), like ``dtype``
480 The name of the type (the class name), like ``dtype``
481 func : callable
481 func : callable
482 A callable for computing the format data.
482 A callable for computing the format data.
483 `func` will be called with the object to be formatted,
483 `func` will be called with the object to be formatted,
484 and will return the raw data in this formatter's format.
484 and will return the raw data in this formatter's format.
485 Subclasses may use a different call signature for the
485 Subclasses may use a different call signature for the
486 `func` argument.
486 `func` argument.
487
487
488 If `func` is None or unspecified, there will be no change,
488 If `func` is None or unspecified, there will be no change,
489 only returning the current value.
489 only returning the current value.
490
490
491 Returns
491 Returns
492 -------
492 -------
493 oldfunc : callable
493 oldfunc : callable
494 The currently registered callable.
494 The currently registered callable.
495 If you are registering a new formatter,
495 If you are registering a new formatter,
496 this will be the previous value (to enable restoring later).
496 this will be the previous value (to enable restoring later).
497 """
497 """
498 key = (type_module, type_name)
498 key = (type_module, type_name)
499
499
500 try:
500 try:
501 oldfunc = self.lookup_by_type("%s.%s" % key)
501 oldfunc = self.lookup_by_type("%s.%s" % key)
502 except KeyError:
502 except KeyError:
503 oldfunc = None
503 oldfunc = None
504
504
505 if func is not None:
505 if func is not None:
506 self.deferred_printers[key] = func
506 self.deferred_printers[key] = func
507 return oldfunc
507 return oldfunc
508
508
509 def pop(self, typ, default=_raise_key_error):
509 def pop(self, typ, default=_raise_key_error):
510 """Pop a formatter for the given type.
510 """Pop a formatter for the given type.
511
511
512 Parameters
512 Parameters
513 ----------
513 ----------
514 typ : type or '__module__.__name__' string for a type
514 typ : type or '__module__.__name__' string for a type
515 default : object
515 default : object
516 value to be returned if no formatter is registered for typ.
516 value to be returned if no formatter is registered for typ.
517
517
518 Returns
518 Returns
519 -------
519 -------
520 obj : object
520 obj : object
521 The last registered object for the type.
521 The last registered object for the type.
522
522
523 Raises
523 Raises
524 ------
524 ------
525 KeyError if the type is not registered and default is not specified.
525 KeyError if the type is not registered and default is not specified.
526 """
526 """
527
527
528 if isinstance(typ, str):
528 if isinstance(typ, str):
529 typ_key = tuple(typ.rsplit('.',1))
529 typ_key = tuple(typ.rsplit('.',1))
530 if typ_key not in self.deferred_printers:
530 if typ_key not in self.deferred_printers:
531 # We may have it cached in the type map. We will have to
531 # We may have it cached in the type map. We will have to
532 # iterate over all of the types to check.
532 # iterate over all of the types to check.
533 for cls in self.type_printers:
533 for cls in self.type_printers:
534 if _mod_name_key(cls) == typ_key:
534 if _mod_name_key(cls) == typ_key:
535 old = self.type_printers.pop(cls)
535 old = self.type_printers.pop(cls)
536 break
536 break
537 else:
537 else:
538 old = default
538 old = default
539 else:
539 else:
540 old = self.deferred_printers.pop(typ_key)
540 old = self.deferred_printers.pop(typ_key)
541 else:
541 else:
542 if typ in self.type_printers:
542 if typ in self.type_printers:
543 old = self.type_printers.pop(typ)
543 old = self.type_printers.pop(typ)
544 else:
544 else:
545 old = self.deferred_printers.pop(_mod_name_key(typ), default)
545 old = self.deferred_printers.pop(_mod_name_key(typ), default)
546 if old is _raise_key_error:
546 if old is _raise_key_error:
547 raise KeyError("No registered value for {0!r}".format(typ))
547 raise KeyError("No registered value for {0!r}".format(typ))
548 return old
548 return old
549
549
550 def _in_deferred_types(self, cls):
550 def _in_deferred_types(self, cls):
551 """
551 """
552 Check if the given class is specified in the deferred type registry.
552 Check if the given class is specified in the deferred type registry.
553
553
554 Successful matches will be moved to the regular type registry for future use.
554 Successful matches will be moved to the regular type registry for future use.
555 """
555 """
556 mod = getattr(cls, '__module__', None)
556 mod = getattr(cls, '__module__', None)
557 name = getattr(cls, '__name__', None)
557 name = getattr(cls, '__name__', None)
558 key = (mod, name)
558 key = (mod, name)
559 if key in self.deferred_printers:
559 if key in self.deferred_printers:
560 # Move the printer over to the regular registry.
560 # Move the printer over to the regular registry.
561 printer = self.deferred_printers.pop(key)
561 printer = self.deferred_printers.pop(key)
562 self.type_printers[cls] = printer
562 self.type_printers[cls] = printer
563 return True
563 return True
564 return False
564 return False
565
565
566
566
567 class PlainTextFormatter(BaseFormatter):
567 class PlainTextFormatter(BaseFormatter):
568 """The default pretty-printer.
568 """The default pretty-printer.
569
569
570 This uses :mod:`IPython.lib.pretty` to compute the format data of
570 This uses :mod:`IPython.lib.pretty` to compute the format data of
571 the object. If the object cannot be pretty printed, :func:`repr` is used.
571 the object. If the object cannot be pretty printed, :func:`repr` is used.
572 See the documentation of :mod:`IPython.lib.pretty` for details on
572 See the documentation of :mod:`IPython.lib.pretty` for details on
573 how to write pretty printers. Here is a simple example::
573 how to write pretty printers. Here is a simple example::
574
574
575 def dtype_pprinter(obj, p, cycle):
575 def dtype_pprinter(obj, p, cycle):
576 if cycle:
576 if cycle:
577 return p.text('dtype(...)')
577 return p.text('dtype(...)')
578 if hasattr(obj, 'fields'):
578 if hasattr(obj, 'fields'):
579 if obj.fields is None:
579 if obj.fields is None:
580 p.text(repr(obj))
580 p.text(repr(obj))
581 else:
581 else:
582 p.begin_group(7, 'dtype([')
582 p.begin_group(7, 'dtype([')
583 for i, field in enumerate(obj.descr):
583 for i, field in enumerate(obj.descr):
584 if i > 0:
584 if i > 0:
585 p.text(',')
585 p.text(',')
586 p.breakable()
586 p.breakable()
587 p.pretty(field)
587 p.pretty(field)
588 p.end_group(7, '])')
588 p.end_group(7, '])')
589 """
589 """
590
590
591 # The format type of data returned.
591 # The format type of data returned.
592 format_type = Unicode('text/plain')
592 format_type = Unicode('text/plain')
593
593
594 # This subclass ignores this attribute as it always need to return
594 # This subclass ignores this attribute as it always need to return
595 # something.
595 # something.
596 enabled = Bool(True).tag(config=False)
596 enabled = Bool(True).tag(config=False)
597
597
598 max_seq_length = Integer(pretty.MAX_SEQ_LENGTH,
598 max_seq_length = Integer(pretty.MAX_SEQ_LENGTH,
599 help="""Truncate large collections (lists, dicts, tuples, sets) to this size.
599 help="""Truncate large collections (lists, dicts, tuples, sets) to this size.
600
600
601 Set to 0 to disable truncation.
601 Set to 0 to disable truncation.
602 """
602 """
603 ).tag(config=True)
603 ).tag(config=True)
604
604
605 # Look for a _repr_pretty_ methods to use for pretty printing.
605 # Look for a _repr_pretty_ methods to use for pretty printing.
606 print_method = ObjectName('_repr_pretty_')
606 print_method = ObjectName('_repr_pretty_')
607
607
608 # Whether to pretty-print or not.
608 # Whether to pretty-print or not.
609 pprint = Bool(True).tag(config=True)
609 pprint = Bool(True).tag(config=True)
610
610
611 # Whether to be verbose or not.
611 # Whether to be verbose or not.
612 verbose = Bool(False).tag(config=True)
612 verbose = Bool(False).tag(config=True)
613
613
614 # The maximum width.
614 # The maximum width.
615 max_width = Integer(79).tag(config=True)
615 max_width = Integer(79).tag(config=True)
616
616
617 # The newline character.
617 # The newline character.
618 newline = Unicode('\n').tag(config=True)
618 newline = Unicode('\n').tag(config=True)
619
619
620 # format-string for pprinting floats
620 # format-string for pprinting floats
621 float_format = Unicode('%r')
621 float_format = Unicode('%r')
622 # setter for float precision, either int or direct format-string
622 # setter for float precision, either int or direct format-string
623 float_precision = CUnicode('').tag(config=True)
623 float_precision = CUnicode('').tag(config=True)
624
624
625 @observe('float_precision')
625 @observe('float_precision')
626 def _float_precision_changed(self, change):
626 def _float_precision_changed(self, change):
627 """float_precision changed, set float_format accordingly.
627 """float_precision changed, set float_format accordingly.
628
628
629 float_precision can be set by int or str.
629 float_precision can be set by int or str.
630 This will set float_format, after interpreting input.
630 This will set float_format, after interpreting input.
631 If numpy has been imported, numpy print precision will also be set.
631 If numpy has been imported, numpy print precision will also be set.
632
632
633 integer `n` sets format to '%.nf', otherwise, format set directly.
633 integer `n` sets format to '%.nf', otherwise, format set directly.
634
634
635 An empty string returns to defaults (repr for float, 8 for numpy).
635 An empty string returns to defaults (repr for float, 8 for numpy).
636
636
637 This parameter can be set via the '%precision' magic.
637 This parameter can be set via the '%precision' magic.
638 """
638 """
639
639
640 new = change['new']
640 new = change['new']
641 if '%' in new:
641 if '%' in new:
642 # got explicit format string
642 # got explicit format string
643 fmt = new
643 fmt = new
644 try:
644 try:
645 fmt%3.14159
645 fmt%3.14159
646 except Exception:
646 except Exception as e:
647 raise ValueError("Precision must be int or format string, not %r"%new)
647 raise ValueError("Precision must be int or format string, not %r"%new) from e
648 elif new:
648 elif new:
649 # otherwise, should be an int
649 # otherwise, should be an int
650 try:
650 try:
651 i = int(new)
651 i = int(new)
652 assert i >= 0
652 assert i >= 0
653 except ValueError:
653 except ValueError as e:
654 raise ValueError("Precision must be int or format string, not %r"%new)
654 raise ValueError("Precision must be int or format string, not %r"%new) from e
655 except AssertionError:
655 except AssertionError as e:
656 raise ValueError("int precision must be non-negative, not %r"%i)
656 raise ValueError("int precision must be non-negative, not %r"%i) from e
657
657
658 fmt = '%%.%if'%i
658 fmt = '%%.%if'%i
659 if 'numpy' in sys.modules:
659 if 'numpy' in sys.modules:
660 # set numpy precision if it has been imported
660 # set numpy precision if it has been imported
661 import numpy
661 import numpy
662 numpy.set_printoptions(precision=i)
662 numpy.set_printoptions(precision=i)
663 else:
663 else:
664 # default back to repr
664 # default back to repr
665 fmt = '%r'
665 fmt = '%r'
666 if 'numpy' in sys.modules:
666 if 'numpy' in sys.modules:
667 import numpy
667 import numpy
668 # numpy default is 8
668 # numpy default is 8
669 numpy.set_printoptions(precision=8)
669 numpy.set_printoptions(precision=8)
670 self.float_format = fmt
670 self.float_format = fmt
671
671
672 # Use the default pretty printers from IPython.lib.pretty.
672 # Use the default pretty printers from IPython.lib.pretty.
673 @default('singleton_printers')
673 @default('singleton_printers')
674 def _singleton_printers_default(self):
674 def _singleton_printers_default(self):
675 return pretty._singleton_pprinters.copy()
675 return pretty._singleton_pprinters.copy()
676
676
677 @default('type_printers')
677 @default('type_printers')
678 def _type_printers_default(self):
678 def _type_printers_default(self):
679 d = pretty._type_pprinters.copy()
679 d = pretty._type_pprinters.copy()
680 d[float] = lambda obj,p,cycle: p.text(self.float_format%obj)
680 d[float] = lambda obj,p,cycle: p.text(self.float_format%obj)
681 return d
681 return d
682
682
683 @default('deferred_printers')
683 @default('deferred_printers')
684 def _deferred_printers_default(self):
684 def _deferred_printers_default(self):
685 return pretty._deferred_type_pprinters.copy()
685 return pretty._deferred_type_pprinters.copy()
686
686
687 #### FormatterABC interface ####
687 #### FormatterABC interface ####
688
688
689 @catch_format_error
689 @catch_format_error
690 def __call__(self, obj):
690 def __call__(self, obj):
691 """Compute the pretty representation of the object."""
691 """Compute the pretty representation of the object."""
692 if not self.pprint:
692 if not self.pprint:
693 return repr(obj)
693 return repr(obj)
694 else:
694 else:
695 stream = StringIO()
695 stream = StringIO()
696 printer = pretty.RepresentationPrinter(stream, self.verbose,
696 printer = pretty.RepresentationPrinter(stream, self.verbose,
697 self.max_width, self.newline,
697 self.max_width, self.newline,
698 max_seq_length=self.max_seq_length,
698 max_seq_length=self.max_seq_length,
699 singleton_pprinters=self.singleton_printers,
699 singleton_pprinters=self.singleton_printers,
700 type_pprinters=self.type_printers,
700 type_pprinters=self.type_printers,
701 deferred_pprinters=self.deferred_printers)
701 deferred_pprinters=self.deferred_printers)
702 printer.pretty(obj)
702 printer.pretty(obj)
703 printer.flush()
703 printer.flush()
704 return stream.getvalue()
704 return stream.getvalue()
705
705
706
706
707 class HTMLFormatter(BaseFormatter):
707 class HTMLFormatter(BaseFormatter):
708 """An HTML formatter.
708 """An HTML formatter.
709
709
710 To define the callables that compute the HTML representation of your
710 To define the callables that compute the HTML representation of your
711 objects, define a :meth:`_repr_html_` method or use the :meth:`for_type`
711 objects, define a :meth:`_repr_html_` method or use the :meth:`for_type`
712 or :meth:`for_type_by_name` methods to register functions that handle
712 or :meth:`for_type_by_name` methods to register functions that handle
713 this.
713 this.
714
714
715 The return value of this formatter should be a valid HTML snippet that
715 The return value of this formatter should be a valid HTML snippet that
716 could be injected into an existing DOM. It should *not* include the
716 could be injected into an existing DOM. It should *not* include the
717 ```<html>`` or ```<body>`` tags.
717 ```<html>`` or ```<body>`` tags.
718 """
718 """
719 format_type = Unicode('text/html')
719 format_type = Unicode('text/html')
720
720
721 print_method = ObjectName('_repr_html_')
721 print_method = ObjectName('_repr_html_')
722
722
723
723
724 class MarkdownFormatter(BaseFormatter):
724 class MarkdownFormatter(BaseFormatter):
725 """A Markdown formatter.
725 """A Markdown formatter.
726
726
727 To define the callables that compute the Markdown representation of your
727 To define the callables that compute the Markdown representation of your
728 objects, define a :meth:`_repr_markdown_` method or use the :meth:`for_type`
728 objects, define a :meth:`_repr_markdown_` method or use the :meth:`for_type`
729 or :meth:`for_type_by_name` methods to register functions that handle
729 or :meth:`for_type_by_name` methods to register functions that handle
730 this.
730 this.
731
731
732 The return value of this formatter should be a valid Markdown.
732 The return value of this formatter should be a valid Markdown.
733 """
733 """
734 format_type = Unicode('text/markdown')
734 format_type = Unicode('text/markdown')
735
735
736 print_method = ObjectName('_repr_markdown_')
736 print_method = ObjectName('_repr_markdown_')
737
737
738 class SVGFormatter(BaseFormatter):
738 class SVGFormatter(BaseFormatter):
739 """An SVG formatter.
739 """An SVG formatter.
740
740
741 To define the callables that compute the SVG representation of your
741 To define the callables that compute the SVG representation of your
742 objects, define a :meth:`_repr_svg_` method or use the :meth:`for_type`
742 objects, define a :meth:`_repr_svg_` method or use the :meth:`for_type`
743 or :meth:`for_type_by_name` methods to register functions that handle
743 or :meth:`for_type_by_name` methods to register functions that handle
744 this.
744 this.
745
745
746 The return value of this formatter should be valid SVG enclosed in
746 The return value of this formatter should be valid SVG enclosed in
747 ```<svg>``` tags, that could be injected into an existing DOM. It should
747 ```<svg>``` tags, that could be injected into an existing DOM. It should
748 *not* include the ```<html>`` or ```<body>`` tags.
748 *not* include the ```<html>`` or ```<body>`` tags.
749 """
749 """
750 format_type = Unicode('image/svg+xml')
750 format_type = Unicode('image/svg+xml')
751
751
752 print_method = ObjectName('_repr_svg_')
752 print_method = ObjectName('_repr_svg_')
753
753
754
754
755 class PNGFormatter(BaseFormatter):
755 class PNGFormatter(BaseFormatter):
756 """A PNG formatter.
756 """A PNG formatter.
757
757
758 To define the callables that compute the PNG representation of your
758 To define the callables that compute the PNG representation of your
759 objects, define a :meth:`_repr_png_` method or use the :meth:`for_type`
759 objects, define a :meth:`_repr_png_` method or use the :meth:`for_type`
760 or :meth:`for_type_by_name` methods to register functions that handle
760 or :meth:`for_type_by_name` methods to register functions that handle
761 this.
761 this.
762
762
763 The return value of this formatter should be raw PNG data, *not*
763 The return value of this formatter should be raw PNG data, *not*
764 base64 encoded.
764 base64 encoded.
765 """
765 """
766 format_type = Unicode('image/png')
766 format_type = Unicode('image/png')
767
767
768 print_method = ObjectName('_repr_png_')
768 print_method = ObjectName('_repr_png_')
769
769
770 _return_type = (bytes, str)
770 _return_type = (bytes, str)
771
771
772
772
773 class JPEGFormatter(BaseFormatter):
773 class JPEGFormatter(BaseFormatter):
774 """A JPEG formatter.
774 """A JPEG formatter.
775
775
776 To define the callables that compute the JPEG representation of your
776 To define the callables that compute the JPEG representation of your
777 objects, define a :meth:`_repr_jpeg_` method or use the :meth:`for_type`
777 objects, define a :meth:`_repr_jpeg_` method or use the :meth:`for_type`
778 or :meth:`for_type_by_name` methods to register functions that handle
778 or :meth:`for_type_by_name` methods to register functions that handle
779 this.
779 this.
780
780
781 The return value of this formatter should be raw JPEG data, *not*
781 The return value of this formatter should be raw JPEG data, *not*
782 base64 encoded.
782 base64 encoded.
783 """
783 """
784 format_type = Unicode('image/jpeg')
784 format_type = Unicode('image/jpeg')
785
785
786 print_method = ObjectName('_repr_jpeg_')
786 print_method = ObjectName('_repr_jpeg_')
787
787
788 _return_type = (bytes, str)
788 _return_type = (bytes, str)
789
789
790
790
791 class LatexFormatter(BaseFormatter):
791 class LatexFormatter(BaseFormatter):
792 """A LaTeX formatter.
792 """A LaTeX formatter.
793
793
794 To define the callables that compute the LaTeX representation of your
794 To define the callables that compute the LaTeX representation of your
795 objects, define a :meth:`_repr_latex_` method or use the :meth:`for_type`
795 objects, define a :meth:`_repr_latex_` method or use the :meth:`for_type`
796 or :meth:`for_type_by_name` methods to register functions that handle
796 or :meth:`for_type_by_name` methods to register functions that handle
797 this.
797 this.
798
798
799 The return value of this formatter should be a valid LaTeX equation,
799 The return value of this formatter should be a valid LaTeX equation,
800 enclosed in either ```$```, ```$$``` or another LaTeX equation
800 enclosed in either ```$```, ```$$``` or another LaTeX equation
801 environment.
801 environment.
802 """
802 """
803 format_type = Unicode('text/latex')
803 format_type = Unicode('text/latex')
804
804
805 print_method = ObjectName('_repr_latex_')
805 print_method = ObjectName('_repr_latex_')
806
806
807
807
808 class JSONFormatter(BaseFormatter):
808 class JSONFormatter(BaseFormatter):
809 """A JSON string formatter.
809 """A JSON string formatter.
810
810
811 To define the callables that compute the JSONable representation of
811 To define the callables that compute the JSONable representation of
812 your objects, define a :meth:`_repr_json_` method or use the :meth:`for_type`
812 your objects, define a :meth:`_repr_json_` method or use the :meth:`for_type`
813 or :meth:`for_type_by_name` methods to register functions that handle
813 or :meth:`for_type_by_name` methods to register functions that handle
814 this.
814 this.
815
815
816 The return value of this formatter should be a JSONable list or dict.
816 The return value of this formatter should be a JSONable list or dict.
817 JSON scalars (None, number, string) are not allowed, only dict or list containers.
817 JSON scalars (None, number, string) are not allowed, only dict or list containers.
818 """
818 """
819 format_type = Unicode('application/json')
819 format_type = Unicode('application/json')
820 _return_type = (list, dict)
820 _return_type = (list, dict)
821
821
822 print_method = ObjectName('_repr_json_')
822 print_method = ObjectName('_repr_json_')
823
823
824 def _check_return(self, r, obj):
824 def _check_return(self, r, obj):
825 """Check that a return value is appropriate
825 """Check that a return value is appropriate
826
826
827 Return the value if so, None otherwise, warning if invalid.
827 Return the value if so, None otherwise, warning if invalid.
828 """
828 """
829 if r is None:
829 if r is None:
830 return
830 return
831 md = None
831 md = None
832 if isinstance(r, tuple):
832 if isinstance(r, tuple):
833 # unpack data, metadata tuple for type checking on first element
833 # unpack data, metadata tuple for type checking on first element
834 r, md = r
834 r, md = r
835
835
836 # handle deprecated JSON-as-string form from IPython < 3
836 # handle deprecated JSON-as-string form from IPython < 3
837 if isinstance(r, str):
837 if isinstance(r, str):
838 warnings.warn("JSON expects JSONable list/dict containers, not JSON strings",
838 warnings.warn("JSON expects JSONable list/dict containers, not JSON strings",
839 FormatterWarning)
839 FormatterWarning)
840 r = json.loads(r)
840 r = json.loads(r)
841
841
842 if md is not None:
842 if md is not None:
843 # put the tuple back together
843 # put the tuple back together
844 r = (r, md)
844 r = (r, md)
845 return super(JSONFormatter, self)._check_return(r, obj)
845 return super(JSONFormatter, self)._check_return(r, obj)
846
846
847
847
848 class JavascriptFormatter(BaseFormatter):
848 class JavascriptFormatter(BaseFormatter):
849 """A Javascript formatter.
849 """A Javascript formatter.
850
850
851 To define the callables that compute the Javascript representation of
851 To define the callables that compute the Javascript representation of
852 your objects, define a :meth:`_repr_javascript_` method or use the
852 your objects, define a :meth:`_repr_javascript_` method or use the
853 :meth:`for_type` or :meth:`for_type_by_name` methods to register functions
853 :meth:`for_type` or :meth:`for_type_by_name` methods to register functions
854 that handle this.
854 that handle this.
855
855
856 The return value of this formatter should be valid Javascript code and
856 The return value of this formatter should be valid Javascript code and
857 should *not* be enclosed in ```<script>``` tags.
857 should *not* be enclosed in ```<script>``` tags.
858 """
858 """
859 format_type = Unicode('application/javascript')
859 format_type = Unicode('application/javascript')
860
860
861 print_method = ObjectName('_repr_javascript_')
861 print_method = ObjectName('_repr_javascript_')
862
862
863
863
864 class PDFFormatter(BaseFormatter):
864 class PDFFormatter(BaseFormatter):
865 """A PDF formatter.
865 """A PDF formatter.
866
866
867 To define the callables that compute the PDF representation of your
867 To define the callables that compute the PDF representation of your
868 objects, define a :meth:`_repr_pdf_` method or use the :meth:`for_type`
868 objects, define a :meth:`_repr_pdf_` method or use the :meth:`for_type`
869 or :meth:`for_type_by_name` methods to register functions that handle
869 or :meth:`for_type_by_name` methods to register functions that handle
870 this.
870 this.
871
871
872 The return value of this formatter should be raw PDF data, *not*
872 The return value of this formatter should be raw PDF data, *not*
873 base64 encoded.
873 base64 encoded.
874 """
874 """
875 format_type = Unicode('application/pdf')
875 format_type = Unicode('application/pdf')
876
876
877 print_method = ObjectName('_repr_pdf_')
877 print_method = ObjectName('_repr_pdf_')
878
878
879 _return_type = (bytes, str)
879 _return_type = (bytes, str)
880
880
881 class IPythonDisplayFormatter(BaseFormatter):
881 class IPythonDisplayFormatter(BaseFormatter):
882 """An escape-hatch Formatter for objects that know how to display themselves.
882 """An escape-hatch Formatter for objects that know how to display themselves.
883
883
884 To define the callables that compute the representation of your
884 To define the callables that compute the representation of your
885 objects, define a :meth:`_ipython_display_` method or use the :meth:`for_type`
885 objects, define a :meth:`_ipython_display_` method or use the :meth:`for_type`
886 or :meth:`for_type_by_name` methods to register functions that handle
886 or :meth:`for_type_by_name` methods to register functions that handle
887 this. Unlike mime-type displays, this method should not return anything,
887 this. Unlike mime-type displays, this method should not return anything,
888 instead calling any appropriate display methods itself.
888 instead calling any appropriate display methods itself.
889
889
890 This display formatter has highest priority.
890 This display formatter has highest priority.
891 If it fires, no other display formatter will be called.
891 If it fires, no other display formatter will be called.
892
892
893 Prior to IPython 6.1, `_ipython_display_` was the only way to display custom mime-types
893 Prior to IPython 6.1, `_ipython_display_` was the only way to display custom mime-types
894 without registering a new Formatter.
894 without registering a new Formatter.
895
895
896 IPython 6.1 introduces `_repr_mimebundle_` for displaying custom mime-types,
896 IPython 6.1 introduces `_repr_mimebundle_` for displaying custom mime-types,
897 so `_ipython_display_` should only be used for objects that require unusual
897 so `_ipython_display_` should only be used for objects that require unusual
898 display patterns, such as multiple display calls.
898 display patterns, such as multiple display calls.
899 """
899 """
900 print_method = ObjectName('_ipython_display_')
900 print_method = ObjectName('_ipython_display_')
901 _return_type = (type(None), bool)
901 _return_type = (type(None), bool)
902
902
903 @catch_format_error
903 @catch_format_error
904 def __call__(self, obj):
904 def __call__(self, obj):
905 """Compute the format for an object."""
905 """Compute the format for an object."""
906 if self.enabled:
906 if self.enabled:
907 # lookup registered printer
907 # lookup registered printer
908 try:
908 try:
909 printer = self.lookup(obj)
909 printer = self.lookup(obj)
910 except KeyError:
910 except KeyError:
911 pass
911 pass
912 else:
912 else:
913 printer(obj)
913 printer(obj)
914 return True
914 return True
915 # Finally look for special method names
915 # Finally look for special method names
916 method = get_real_method(obj, self.print_method)
916 method = get_real_method(obj, self.print_method)
917 if method is not None:
917 if method is not None:
918 method()
918 method()
919 return True
919 return True
920
920
921
921
922 class MimeBundleFormatter(BaseFormatter):
922 class MimeBundleFormatter(BaseFormatter):
923 """A Formatter for arbitrary mime-types.
923 """A Formatter for arbitrary mime-types.
924
924
925 Unlike other `_repr_<mimetype>_` methods,
925 Unlike other `_repr_<mimetype>_` methods,
926 `_repr_mimebundle_` should return mime-bundle data,
926 `_repr_mimebundle_` should return mime-bundle data,
927 either the mime-keyed `data` dictionary or the tuple `(data, metadata)`.
927 either the mime-keyed `data` dictionary or the tuple `(data, metadata)`.
928 Any mime-type is valid.
928 Any mime-type is valid.
929
929
930 To define the callables that compute the mime-bundle representation of your
930 To define the callables that compute the mime-bundle representation of your
931 objects, define a :meth:`_repr_mimebundle_` method or use the :meth:`for_type`
931 objects, define a :meth:`_repr_mimebundle_` method or use the :meth:`for_type`
932 or :meth:`for_type_by_name` methods to register functions that handle
932 or :meth:`for_type_by_name` methods to register functions that handle
933 this.
933 this.
934
934
935 .. versionadded:: 6.1
935 .. versionadded:: 6.1
936 """
936 """
937 print_method = ObjectName('_repr_mimebundle_')
937 print_method = ObjectName('_repr_mimebundle_')
938 _return_type = dict
938 _return_type = dict
939
939
940 def _check_return(self, r, obj):
940 def _check_return(self, r, obj):
941 r = super(MimeBundleFormatter, self)._check_return(r, obj)
941 r = super(MimeBundleFormatter, self)._check_return(r, obj)
942 # always return (data, metadata):
942 # always return (data, metadata):
943 if r is None:
943 if r is None:
944 return {}, {}
944 return {}, {}
945 if not isinstance(r, tuple):
945 if not isinstance(r, tuple):
946 return r, {}
946 return r, {}
947 return r
947 return r
948
948
949 @catch_format_error
949 @catch_format_error
950 def __call__(self, obj, include=None, exclude=None):
950 def __call__(self, obj, include=None, exclude=None):
951 """Compute the format for an object.
951 """Compute the format for an object.
952
952
953 Identical to parent's method but we pass extra parameters to the method.
953 Identical to parent's method but we pass extra parameters to the method.
954
954
955 Unlike other _repr_*_ `_repr_mimebundle_` should allow extra kwargs, in
955 Unlike other _repr_*_ `_repr_mimebundle_` should allow extra kwargs, in
956 particular `include` and `exclude`.
956 particular `include` and `exclude`.
957 """
957 """
958 if self.enabled:
958 if self.enabled:
959 # lookup registered printer
959 # lookup registered printer
960 try:
960 try:
961 printer = self.lookup(obj)
961 printer = self.lookup(obj)
962 except KeyError:
962 except KeyError:
963 pass
963 pass
964 else:
964 else:
965 return printer(obj)
965 return printer(obj)
966 # Finally look for special method names
966 # Finally look for special method names
967 method = get_real_method(obj, self.print_method)
967 method = get_real_method(obj, self.print_method)
968
968
969 if method is not None:
969 if method is not None:
970 return method(include=include, exclude=exclude)
970 return method(include=include, exclude=exclude)
971 return None
971 return None
972 else:
972 else:
973 return None
973 return None
974
974
975
975
976 FormatterABC.register(BaseFormatter)
976 FormatterABC.register(BaseFormatter)
977 FormatterABC.register(PlainTextFormatter)
977 FormatterABC.register(PlainTextFormatter)
978 FormatterABC.register(HTMLFormatter)
978 FormatterABC.register(HTMLFormatter)
979 FormatterABC.register(MarkdownFormatter)
979 FormatterABC.register(MarkdownFormatter)
980 FormatterABC.register(SVGFormatter)
980 FormatterABC.register(SVGFormatter)
981 FormatterABC.register(PNGFormatter)
981 FormatterABC.register(PNGFormatter)
982 FormatterABC.register(PDFFormatter)
982 FormatterABC.register(PDFFormatter)
983 FormatterABC.register(JPEGFormatter)
983 FormatterABC.register(JPEGFormatter)
984 FormatterABC.register(LatexFormatter)
984 FormatterABC.register(LatexFormatter)
985 FormatterABC.register(JSONFormatter)
985 FormatterABC.register(JSONFormatter)
986 FormatterABC.register(JavascriptFormatter)
986 FormatterABC.register(JavascriptFormatter)
987 FormatterABC.register(IPythonDisplayFormatter)
987 FormatterABC.register(IPythonDisplayFormatter)
988 FormatterABC.register(MimeBundleFormatter)
988 FormatterABC.register(MimeBundleFormatter)
989
989
990
990
991 def format_display_data(obj, include=None, exclude=None):
991 def format_display_data(obj, include=None, exclude=None):
992 """Return a format data dict for an object.
992 """Return a format data dict for an object.
993
993
994 By default all format types will be computed.
994 By default all format types will be computed.
995
995
996 Parameters
996 Parameters
997 ----------
997 ----------
998 obj : object
998 obj : object
999 The Python object whose format data will be computed.
999 The Python object whose format data will be computed.
1000
1000
1001 Returns
1001 Returns
1002 -------
1002 -------
1003 format_dict : dict
1003 format_dict : dict
1004 A dictionary of key/value pairs, one or each format that was
1004 A dictionary of key/value pairs, one or each format that was
1005 generated for the object. The keys are the format types, which
1005 generated for the object. The keys are the format types, which
1006 will usually be MIME type strings and the values and JSON'able
1006 will usually be MIME type strings and the values and JSON'able
1007 data structure containing the raw data for the representation in
1007 data structure containing the raw data for the representation in
1008 that format.
1008 that format.
1009 include : list or tuple, optional
1009 include : list or tuple, optional
1010 A list of format type strings (MIME types) to include in the
1010 A list of format type strings (MIME types) to include in the
1011 format data dict. If this is set *only* the format types included
1011 format data dict. If this is set *only* the format types included
1012 in this list will be computed.
1012 in this list will be computed.
1013 exclude : list or tuple, optional
1013 exclude : list or tuple, optional
1014 A list of format type string (MIME types) to exclude in the format
1014 A list of format type string (MIME types) to exclude in the format
1015 data dict. If this is set all format types will be computed,
1015 data dict. If this is set all format types will be computed,
1016 except for those included in this argument.
1016 except for those included in this argument.
1017 """
1017 """
1018 from .interactiveshell import InteractiveShell
1018 from .interactiveshell import InteractiveShell
1019
1019
1020 return InteractiveShell.instance().display_formatter.format(
1020 return InteractiveShell.instance().display_formatter.format(
1021 obj,
1021 obj,
1022 include,
1022 include,
1023 exclude
1023 exclude
1024 )
1024 )
@@ -1,3713 +1,3713
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 import abc
14 import abc
15 import ast
15 import ast
16 import atexit
16 import atexit
17 import builtins as builtin_mod
17 import builtins as builtin_mod
18 import functools
18 import functools
19 import inspect
19 import inspect
20 import os
20 import os
21 import re
21 import re
22 import runpy
22 import runpy
23 import sys
23 import sys
24 import tempfile
24 import tempfile
25 import traceback
25 import traceback
26 import types
26 import types
27 import subprocess
27 import subprocess
28 import warnings
28 import warnings
29 from io import open as io_open
29 from io import open as io_open
30
30
31 from pickleshare import PickleShareDB
31 from pickleshare import PickleShareDB
32
32
33 from traitlets.config.configurable import SingletonConfigurable
33 from traitlets.config.configurable import SingletonConfigurable
34 from traitlets.utils.importstring import import_item
34 from traitlets.utils.importstring import import_item
35 from IPython.core import oinspect
35 from IPython.core import 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 ultratb
39 from IPython.core import ultratb
40 from IPython.core.alias import Alias, AliasManager
40 from IPython.core.alias import Alias, AliasManager
41 from IPython.core.autocall import ExitAutocall
41 from IPython.core.autocall import ExitAutocall
42 from IPython.core.builtin_trap import BuiltinTrap
42 from IPython.core.builtin_trap import BuiltinTrap
43 from IPython.core.events import EventManager, available_events
43 from IPython.core.events import EventManager, available_events
44 from IPython.core.compilerop import CachingCompiler, check_linecache_ipython
44 from IPython.core.compilerop import CachingCompiler, check_linecache_ipython
45 from IPython.core.debugger import Pdb
45 from IPython.core.debugger import Pdb
46 from IPython.core.display_trap import DisplayTrap
46 from IPython.core.display_trap import DisplayTrap
47 from IPython.core.displayhook import DisplayHook
47 from IPython.core.displayhook import DisplayHook
48 from IPython.core.displaypub import DisplayPublisher
48 from IPython.core.displaypub import DisplayPublisher
49 from IPython.core.error import InputRejected, UsageError
49 from IPython.core.error import InputRejected, UsageError
50 from IPython.core.extensions import ExtensionManager
50 from IPython.core.extensions import ExtensionManager
51 from IPython.core.formatters import DisplayFormatter
51 from IPython.core.formatters import DisplayFormatter
52 from IPython.core.history import HistoryManager
52 from IPython.core.history import HistoryManager
53 from IPython.core.inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
53 from IPython.core.inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
54 from IPython.core.logger import Logger
54 from IPython.core.logger import Logger
55 from IPython.core.macro import Macro
55 from IPython.core.macro import Macro
56 from IPython.core.payload import PayloadManager
56 from IPython.core.payload import PayloadManager
57 from IPython.core.prefilter import PrefilterManager
57 from IPython.core.prefilter import PrefilterManager
58 from IPython.core.profiledir import ProfileDir
58 from IPython.core.profiledir import ProfileDir
59 from IPython.core.usage import default_banner
59 from IPython.core.usage import default_banner
60 from IPython.display import display
60 from IPython.display import display
61 from IPython.testing.skipdoctest import skip_doctest
61 from IPython.testing.skipdoctest import skip_doctest
62 from IPython.utils import PyColorize
62 from IPython.utils import PyColorize
63 from IPython.utils import io
63 from IPython.utils import io
64 from IPython.utils import py3compat
64 from IPython.utils import py3compat
65 from IPython.utils import openpy
65 from IPython.utils import openpy
66 from IPython.utils.decorators import undoc
66 from IPython.utils.decorators import undoc
67 from IPython.utils.io import ask_yes_no
67 from IPython.utils.io import ask_yes_no
68 from IPython.utils.ipstruct import Struct
68 from IPython.utils.ipstruct import Struct
69 from IPython.paths import get_ipython_dir
69 from IPython.paths import get_ipython_dir
70 from IPython.utils.path import get_home_dir, get_py_filename, ensure_dir_exists
70 from IPython.utils.path import get_home_dir, get_py_filename, ensure_dir_exists
71 from IPython.utils.process import system, getoutput
71 from IPython.utils.process import system, getoutput
72 from IPython.utils.strdispatch import StrDispatch
72 from IPython.utils.strdispatch import StrDispatch
73 from IPython.utils.syspathcontext import prepended_to_syspath
73 from IPython.utils.syspathcontext import prepended_to_syspath
74 from IPython.utils.text import format_screen, LSString, SList, DollarFormatter
74 from IPython.utils.text import format_screen, LSString, SList, DollarFormatter
75 from IPython.utils.tempdir import TemporaryDirectory
75 from IPython.utils.tempdir import TemporaryDirectory
76 from traitlets import (
76 from traitlets import (
77 Integer, Bool, CaselessStrEnum, Enum, List, Dict, Unicode, Instance, Type,
77 Integer, Bool, CaselessStrEnum, Enum, List, Dict, Unicode, Instance, Type,
78 observe, default, validate, Any
78 observe, default, validate, Any
79 )
79 )
80 from warnings import warn
80 from warnings import warn
81 from logging import error
81 from logging import error
82 import IPython.core.hooks
82 import IPython.core.hooks
83
83
84 from typing import List as ListType, Tuple
84 from typing import List as ListType, Tuple
85 from ast import AST
85 from ast import AST
86
86
87 # NoOpContext is deprecated, but ipykernel imports it from here.
87 # NoOpContext is deprecated, but ipykernel imports it from here.
88 # See https://github.com/ipython/ipykernel/issues/157
88 # See https://github.com/ipython/ipykernel/issues/157
89 # (2016, let's try to remove than in IPython 8.0)
89 # (2016, let's try to remove than in IPython 8.0)
90 from IPython.utils.contexts import NoOpContext
90 from IPython.utils.contexts import NoOpContext
91
91
92 try:
92 try:
93 import docrepr.sphinxify as sphx
93 import docrepr.sphinxify as sphx
94
94
95 def sphinxify(doc):
95 def sphinxify(doc):
96 with TemporaryDirectory() as dirname:
96 with TemporaryDirectory() as dirname:
97 return {
97 return {
98 'text/html': sphx.sphinxify(doc, dirname),
98 'text/html': sphx.sphinxify(doc, dirname),
99 'text/plain': doc
99 'text/plain': doc
100 }
100 }
101 except ImportError:
101 except ImportError:
102 sphinxify = None
102 sphinxify = None
103
103
104
104
105 class ProvisionalWarning(DeprecationWarning):
105 class ProvisionalWarning(DeprecationWarning):
106 """
106 """
107 Warning class for unstable features
107 Warning class for unstable features
108 """
108 """
109 pass
109 pass
110
110
111 if sys.version_info > (3,8):
111 if sys.version_info > (3,8):
112 from ast import Module
112 from ast import Module
113 else :
113 else :
114 # mock the new API, ignore second argument
114 # mock the new API, ignore second argument
115 # see https://github.com/ipython/ipython/issues/11590
115 # see https://github.com/ipython/ipython/issues/11590
116 from ast import Module as OriginalModule
116 from ast import Module as OriginalModule
117 Module = lambda nodelist, type_ignores: OriginalModule(nodelist)
117 Module = lambda nodelist, type_ignores: OriginalModule(nodelist)
118
118
119 if sys.version_info > (3,6):
119 if sys.version_info > (3,6):
120 _assign_nodes = (ast.AugAssign, ast.AnnAssign, ast.Assign)
120 _assign_nodes = (ast.AugAssign, ast.AnnAssign, ast.Assign)
121 _single_targets_nodes = (ast.AugAssign, ast.AnnAssign)
121 _single_targets_nodes = (ast.AugAssign, ast.AnnAssign)
122 else:
122 else:
123 _assign_nodes = (ast.AugAssign, ast.Assign )
123 _assign_nodes = (ast.AugAssign, ast.Assign )
124 _single_targets_nodes = (ast.AugAssign, )
124 _single_targets_nodes = (ast.AugAssign, )
125
125
126 #-----------------------------------------------------------------------------
126 #-----------------------------------------------------------------------------
127 # Await Helpers
127 # Await Helpers
128 #-----------------------------------------------------------------------------
128 #-----------------------------------------------------------------------------
129
129
130 def removed_co_newlocals(function:types.FunctionType) -> types.FunctionType:
130 def removed_co_newlocals(function:types.FunctionType) -> types.FunctionType:
131 """Return a function that do not create a new local scope.
131 """Return a function that do not create a new local scope.
132
132
133 Given a function, create a clone of this function where the co_newlocal flag
133 Given a function, create a clone of this function where the co_newlocal flag
134 has been removed, making this function code actually run in the sourounding
134 has been removed, making this function code actually run in the sourounding
135 scope.
135 scope.
136
136
137 We need this in order to run asynchronous code in user level namespace.
137 We need this in order to run asynchronous code in user level namespace.
138 """
138 """
139 from types import CodeType, FunctionType
139 from types import CodeType, FunctionType
140 CO_NEWLOCALS = 0x0002
140 CO_NEWLOCALS = 0x0002
141 code = function.__code__
141 code = function.__code__
142 new_co_flags = code.co_flags & ~CO_NEWLOCALS
142 new_co_flags = code.co_flags & ~CO_NEWLOCALS
143 if sys.version_info > (3, 8, 0, 'alpha', 3):
143 if sys.version_info > (3, 8, 0, 'alpha', 3):
144 new_code = code.replace(co_flags=new_co_flags)
144 new_code = code.replace(co_flags=new_co_flags)
145 else:
145 else:
146 new_code = CodeType(
146 new_code = CodeType(
147 code.co_argcount,
147 code.co_argcount,
148 code.co_kwonlyargcount,
148 code.co_kwonlyargcount,
149 code.co_nlocals,
149 code.co_nlocals,
150 code.co_stacksize,
150 code.co_stacksize,
151 new_co_flags,
151 new_co_flags,
152 code.co_code,
152 code.co_code,
153 code.co_consts,
153 code.co_consts,
154 code.co_names,
154 code.co_names,
155 code.co_varnames,
155 code.co_varnames,
156 code.co_filename,
156 code.co_filename,
157 code.co_name,
157 code.co_name,
158 code.co_firstlineno,
158 code.co_firstlineno,
159 code.co_lnotab,
159 code.co_lnotab,
160 code.co_freevars,
160 code.co_freevars,
161 code.co_cellvars
161 code.co_cellvars
162 )
162 )
163 return FunctionType(new_code, globals(), function.__name__, function.__defaults__)
163 return FunctionType(new_code, globals(), function.__name__, function.__defaults__)
164
164
165
165
166 # we still need to run things using the asyncio eventloop, but there is no
166 # we still need to run things using the asyncio eventloop, but there is no
167 # async integration
167 # async integration
168 from .async_helpers import (_asyncio_runner, _asyncify, _pseudo_sync_runner)
168 from .async_helpers import (_asyncio_runner, _asyncify, _pseudo_sync_runner)
169 from .async_helpers import _curio_runner, _trio_runner, _should_be_async
169 from .async_helpers import _curio_runner, _trio_runner, _should_be_async
170
170
171
171
172 def _ast_asyncify(cell:str, wrapper_name:str) -> ast.Module:
172 def _ast_asyncify(cell:str, wrapper_name:str) -> ast.Module:
173 """
173 """
174 Parse a cell with top-level await and modify the AST to be able to run it later.
174 Parse a cell with top-level await and modify the AST to be able to run it later.
175
175
176 Parameter
176 Parameter
177 ---------
177 ---------
178
178
179 cell: str
179 cell: str
180 The code cell to asyncronify
180 The code cell to asyncronify
181 wrapper_name: str
181 wrapper_name: str
182 The name of the function to be used to wrap the passed `cell`. It is
182 The name of the function to be used to wrap the passed `cell`. It is
183 advised to **not** use a python identifier in order to not pollute the
183 advised to **not** use a python identifier in order to not pollute the
184 global namespace in which the function will be ran.
184 global namespace in which the function will be ran.
185
185
186 Return
186 Return
187 ------
187 ------
188
188
189 A module object AST containing **one** function named `wrapper_name`.
189 A module object AST containing **one** function named `wrapper_name`.
190
190
191 The given code is wrapped in a async-def function, parsed into an AST, and
191 The given code is wrapped in a async-def function, parsed into an AST, and
192 the resulting function definition AST is modified to return the last
192 the resulting function definition AST is modified to return the last
193 expression.
193 expression.
194
194
195 The last expression or await node is moved into a return statement at the
195 The last expression or await node is moved into a return statement at the
196 end of the function, and removed from its original location. If the last
196 end of the function, and removed from its original location. If the last
197 node is not Expr or Await nothing is done.
197 node is not Expr or Await nothing is done.
198
198
199 The function `__code__` will need to be later modified (by
199 The function `__code__` will need to be later modified (by
200 ``removed_co_newlocals``) in a subsequent step to not create new `locals()`
200 ``removed_co_newlocals``) in a subsequent step to not create new `locals()`
201 meaning that the local and global scope are the same, ie as if the body of
201 meaning that the local and global scope are the same, ie as if the body of
202 the function was at module level.
202 the function was at module level.
203
203
204 Lastly a call to `locals()` is made just before the last expression of the
204 Lastly a call to `locals()` is made just before the last expression of the
205 function, or just after the last assignment or statement to make sure the
205 function, or just after the last assignment or statement to make sure the
206 global dict is updated as python function work with a local fast cache which
206 global dict is updated as python function work with a local fast cache which
207 is updated only on `local()` calls.
207 is updated only on `local()` calls.
208 """
208 """
209
209
210 from ast import Expr, Await, Return
210 from ast import Expr, Await, Return
211 if sys.version_info >= (3,8):
211 if sys.version_info >= (3,8):
212 return ast.parse(cell)
212 return ast.parse(cell)
213 tree = ast.parse(_asyncify(cell))
213 tree = ast.parse(_asyncify(cell))
214
214
215 function_def = tree.body[0]
215 function_def = tree.body[0]
216 function_def.name = wrapper_name
216 function_def.name = wrapper_name
217 try_block = function_def.body[0]
217 try_block = function_def.body[0]
218 lastexpr = try_block.body[-1]
218 lastexpr = try_block.body[-1]
219 if isinstance(lastexpr, (Expr, Await)):
219 if isinstance(lastexpr, (Expr, Await)):
220 try_block.body[-1] = Return(lastexpr.value)
220 try_block.body[-1] = Return(lastexpr.value)
221 ast.fix_missing_locations(tree)
221 ast.fix_missing_locations(tree)
222 return tree
222 return tree
223 #-----------------------------------------------------------------------------
223 #-----------------------------------------------------------------------------
224 # Globals
224 # Globals
225 #-----------------------------------------------------------------------------
225 #-----------------------------------------------------------------------------
226
226
227 # compiled regexps for autoindent management
227 # compiled regexps for autoindent management
228 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
228 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
229
229
230 #-----------------------------------------------------------------------------
230 #-----------------------------------------------------------------------------
231 # Utilities
231 # Utilities
232 #-----------------------------------------------------------------------------
232 #-----------------------------------------------------------------------------
233
233
234 @undoc
234 @undoc
235 def softspace(file, newvalue):
235 def softspace(file, newvalue):
236 """Copied from code.py, to remove the dependency"""
236 """Copied from code.py, to remove the dependency"""
237
237
238 oldvalue = 0
238 oldvalue = 0
239 try:
239 try:
240 oldvalue = file.softspace
240 oldvalue = file.softspace
241 except AttributeError:
241 except AttributeError:
242 pass
242 pass
243 try:
243 try:
244 file.softspace = newvalue
244 file.softspace = newvalue
245 except (AttributeError, TypeError):
245 except (AttributeError, TypeError):
246 # "attribute-less object" or "read-only attributes"
246 # "attribute-less object" or "read-only attributes"
247 pass
247 pass
248 return oldvalue
248 return oldvalue
249
249
250 @undoc
250 @undoc
251 def no_op(*a, **kw):
251 def no_op(*a, **kw):
252 pass
252 pass
253
253
254
254
255 class SpaceInInput(Exception): pass
255 class SpaceInInput(Exception): pass
256
256
257
257
258 def get_default_colors():
258 def get_default_colors():
259 "DEPRECATED"
259 "DEPRECATED"
260 warn('get_default_color is deprecated since IPython 5.0, and returns `Neutral` on all platforms.',
260 warn('get_default_color is deprecated since IPython 5.0, and returns `Neutral` on all platforms.',
261 DeprecationWarning, stacklevel=2)
261 DeprecationWarning, stacklevel=2)
262 return 'Neutral'
262 return 'Neutral'
263
263
264
264
265 class SeparateUnicode(Unicode):
265 class SeparateUnicode(Unicode):
266 r"""A Unicode subclass to validate separate_in, separate_out, etc.
266 r"""A Unicode subclass to validate separate_in, separate_out, etc.
267
267
268 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
268 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
269 """
269 """
270
270
271 def validate(self, obj, value):
271 def validate(self, obj, value):
272 if value == '0': value = ''
272 if value == '0': value = ''
273 value = value.replace('\\n','\n')
273 value = value.replace('\\n','\n')
274 return super(SeparateUnicode, self).validate(obj, value)
274 return super(SeparateUnicode, self).validate(obj, value)
275
275
276
276
277 @undoc
277 @undoc
278 class DummyMod(object):
278 class DummyMod(object):
279 """A dummy module used for IPython's interactive module when
279 """A dummy module used for IPython's interactive module when
280 a namespace must be assigned to the module's __dict__."""
280 a namespace must be assigned to the module's __dict__."""
281 __spec__ = None
281 __spec__ = None
282
282
283
283
284 class ExecutionInfo(object):
284 class ExecutionInfo(object):
285 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
285 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
286
286
287 Stores information about what is going to happen.
287 Stores information about what is going to happen.
288 """
288 """
289 raw_cell = None
289 raw_cell = None
290 store_history = False
290 store_history = False
291 silent = False
291 silent = False
292 shell_futures = True
292 shell_futures = True
293
293
294 def __init__(self, raw_cell, store_history, silent, shell_futures):
294 def __init__(self, raw_cell, store_history, silent, shell_futures):
295 self.raw_cell = raw_cell
295 self.raw_cell = raw_cell
296 self.store_history = store_history
296 self.store_history = store_history
297 self.silent = silent
297 self.silent = silent
298 self.shell_futures = shell_futures
298 self.shell_futures = shell_futures
299
299
300 def __repr__(self):
300 def __repr__(self):
301 name = self.__class__.__qualname__
301 name = self.__class__.__qualname__
302 raw_cell = ((self.raw_cell[:50] + '..')
302 raw_cell = ((self.raw_cell[:50] + '..')
303 if len(self.raw_cell) > 50 else self.raw_cell)
303 if len(self.raw_cell) > 50 else self.raw_cell)
304 return '<%s object at %x, raw_cell="%s" store_history=%s silent=%s shell_futures=%s>' %\
304 return '<%s object at %x, raw_cell="%s" store_history=%s silent=%s shell_futures=%s>' %\
305 (name, id(self), raw_cell, self.store_history, self.silent, self.shell_futures)
305 (name, id(self), raw_cell, self.store_history, self.silent, self.shell_futures)
306
306
307
307
308 class ExecutionResult(object):
308 class ExecutionResult(object):
309 """The result of a call to :meth:`InteractiveShell.run_cell`
309 """The result of a call to :meth:`InteractiveShell.run_cell`
310
310
311 Stores information about what took place.
311 Stores information about what took place.
312 """
312 """
313 execution_count = None
313 execution_count = None
314 error_before_exec = None
314 error_before_exec = None
315 error_in_exec = None
315 error_in_exec = None
316 info = None
316 info = None
317 result = None
317 result = None
318
318
319 def __init__(self, info):
319 def __init__(self, info):
320 self.info = info
320 self.info = info
321
321
322 @property
322 @property
323 def success(self):
323 def success(self):
324 return (self.error_before_exec is None) and (self.error_in_exec is None)
324 return (self.error_before_exec is None) and (self.error_in_exec is None)
325
325
326 def raise_error(self):
326 def raise_error(self):
327 """Reraises error if `success` is `False`, otherwise does nothing"""
327 """Reraises error if `success` is `False`, otherwise does nothing"""
328 if self.error_before_exec is not None:
328 if self.error_before_exec is not None:
329 raise self.error_before_exec
329 raise self.error_before_exec
330 if self.error_in_exec is not None:
330 if self.error_in_exec is not None:
331 raise self.error_in_exec
331 raise self.error_in_exec
332
332
333 def __repr__(self):
333 def __repr__(self):
334 name = self.__class__.__qualname__
334 name = self.__class__.__qualname__
335 return '<%s object at %x, execution_count=%s error_before_exec=%s error_in_exec=%s info=%s result=%s>' %\
335 return '<%s object at %x, execution_count=%s error_before_exec=%s error_in_exec=%s info=%s result=%s>' %\
336 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))
336 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))
337
337
338
338
339 class InteractiveShell(SingletonConfigurable):
339 class InteractiveShell(SingletonConfigurable):
340 """An enhanced, interactive shell for Python."""
340 """An enhanced, interactive shell for Python."""
341
341
342 _instance = None
342 _instance = None
343
343
344 ast_transformers = List([], help=
344 ast_transformers = List([], help=
345 """
345 """
346 A list of ast.NodeTransformer subclass instances, which will be applied
346 A list of ast.NodeTransformer subclass instances, which will be applied
347 to user input before code is run.
347 to user input before code is run.
348 """
348 """
349 ).tag(config=True)
349 ).tag(config=True)
350
350
351 autocall = Enum((0,1,2), default_value=0, help=
351 autocall = Enum((0,1,2), default_value=0, help=
352 """
352 """
353 Make IPython automatically call any callable object even if you didn't
353 Make IPython automatically call any callable object even if you didn't
354 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
354 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
355 automatically. The value can be '0' to disable the feature, '1' for
355 automatically. The value can be '0' to disable the feature, '1' for
356 'smart' autocall, where it is not applied if there are no more
356 'smart' autocall, where it is not applied if there are no more
357 arguments on the line, and '2' for 'full' autocall, where all callable
357 arguments on the line, and '2' for 'full' autocall, where all callable
358 objects are automatically called (even if no arguments are present).
358 objects are automatically called (even if no arguments are present).
359 """
359 """
360 ).tag(config=True)
360 ).tag(config=True)
361
361
362 autoindent = Bool(True, help=
362 autoindent = Bool(True, help=
363 """
363 """
364 Autoindent IPython code entered interactively.
364 Autoindent IPython code entered interactively.
365 """
365 """
366 ).tag(config=True)
366 ).tag(config=True)
367
367
368 autoawait = Bool(True, help=
368 autoawait = Bool(True, help=
369 """
369 """
370 Automatically run await statement in the top level repl.
370 Automatically run await statement in the top level repl.
371 """
371 """
372 ).tag(config=True)
372 ).tag(config=True)
373
373
374 loop_runner_map ={
374 loop_runner_map ={
375 'asyncio':(_asyncio_runner, True),
375 'asyncio':(_asyncio_runner, True),
376 'curio':(_curio_runner, True),
376 'curio':(_curio_runner, True),
377 'trio':(_trio_runner, True),
377 'trio':(_trio_runner, True),
378 'sync': (_pseudo_sync_runner, False)
378 'sync': (_pseudo_sync_runner, False)
379 }
379 }
380
380
381 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",
381 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",
382 allow_none=True,
382 allow_none=True,
383 help="""Select the loop runner that will be used to execute top-level asynchronous code"""
383 help="""Select the loop runner that will be used to execute top-level asynchronous code"""
384 ).tag(config=True)
384 ).tag(config=True)
385
385
386 @default('loop_runner')
386 @default('loop_runner')
387 def _default_loop_runner(self):
387 def _default_loop_runner(self):
388 return import_item("IPython.core.interactiveshell._asyncio_runner")
388 return import_item("IPython.core.interactiveshell._asyncio_runner")
389
389
390 @validate('loop_runner')
390 @validate('loop_runner')
391 def _import_runner(self, proposal):
391 def _import_runner(self, proposal):
392 if isinstance(proposal.value, str):
392 if isinstance(proposal.value, str):
393 if proposal.value in self.loop_runner_map:
393 if proposal.value in self.loop_runner_map:
394 runner, autoawait = self.loop_runner_map[proposal.value]
394 runner, autoawait = self.loop_runner_map[proposal.value]
395 self.autoawait = autoawait
395 self.autoawait = autoawait
396 return runner
396 return runner
397 runner = import_item(proposal.value)
397 runner = import_item(proposal.value)
398 if not callable(runner):
398 if not callable(runner):
399 raise ValueError('loop_runner must be callable')
399 raise ValueError('loop_runner must be callable')
400 return runner
400 return runner
401 if not callable(proposal.value):
401 if not callable(proposal.value):
402 raise ValueError('loop_runner must be callable')
402 raise ValueError('loop_runner must be callable')
403 return proposal.value
403 return proposal.value
404
404
405 automagic = Bool(True, help=
405 automagic = Bool(True, help=
406 """
406 """
407 Enable magic commands to be called without the leading %.
407 Enable magic commands to be called without the leading %.
408 """
408 """
409 ).tag(config=True)
409 ).tag(config=True)
410
410
411 banner1 = Unicode(default_banner,
411 banner1 = Unicode(default_banner,
412 help="""The part of the banner to be printed before the profile"""
412 help="""The part of the banner to be printed before the profile"""
413 ).tag(config=True)
413 ).tag(config=True)
414 banner2 = Unicode('',
414 banner2 = Unicode('',
415 help="""The part of the banner to be printed after the profile"""
415 help="""The part of the banner to be printed after the profile"""
416 ).tag(config=True)
416 ).tag(config=True)
417
417
418 cache_size = Integer(1000, help=
418 cache_size = Integer(1000, help=
419 """
419 """
420 Set the size of the output cache. The default is 1000, you can
420 Set the size of the output cache. The default is 1000, you can
421 change it permanently in your config file. Setting it to 0 completely
421 change it permanently in your config file. Setting it to 0 completely
422 disables the caching system, and the minimum value accepted is 3 (if
422 disables the caching system, and the minimum value accepted is 3 (if
423 you provide a value less than 3, it is reset to 0 and a warning is
423 you provide a value less than 3, it is reset to 0 and a warning is
424 issued). This limit is defined because otherwise you'll spend more
424 issued). This limit is defined because otherwise you'll spend more
425 time re-flushing a too small cache than working
425 time re-flushing a too small cache than working
426 """
426 """
427 ).tag(config=True)
427 ).tag(config=True)
428 color_info = Bool(True, help=
428 color_info = Bool(True, help=
429 """
429 """
430 Use colors for displaying information about objects. Because this
430 Use colors for displaying information about objects. Because this
431 information is passed through a pager (like 'less'), and some pagers
431 information is passed through a pager (like 'less'), and some pagers
432 get confused with color codes, this capability can be turned off.
432 get confused with color codes, this capability can be turned off.
433 """
433 """
434 ).tag(config=True)
434 ).tag(config=True)
435 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
435 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
436 default_value='Neutral',
436 default_value='Neutral',
437 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
437 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
438 ).tag(config=True)
438 ).tag(config=True)
439 debug = Bool(False).tag(config=True)
439 debug = Bool(False).tag(config=True)
440 disable_failing_post_execute = Bool(False,
440 disable_failing_post_execute = Bool(False,
441 help="Don't call post-execute functions that have failed in the past."
441 help="Don't call post-execute functions that have failed in the past."
442 ).tag(config=True)
442 ).tag(config=True)
443 display_formatter = Instance(DisplayFormatter, allow_none=True)
443 display_formatter = Instance(DisplayFormatter, allow_none=True)
444 displayhook_class = Type(DisplayHook)
444 displayhook_class = Type(DisplayHook)
445 display_pub_class = Type(DisplayPublisher)
445 display_pub_class = Type(DisplayPublisher)
446
446
447 sphinxify_docstring = Bool(False, help=
447 sphinxify_docstring = Bool(False, help=
448 """
448 """
449 Enables rich html representation of docstrings. (This requires the
449 Enables rich html representation of docstrings. (This requires the
450 docrepr module).
450 docrepr module).
451 """).tag(config=True)
451 """).tag(config=True)
452
452
453 @observe("sphinxify_docstring")
453 @observe("sphinxify_docstring")
454 def _sphinxify_docstring_changed(self, change):
454 def _sphinxify_docstring_changed(self, change):
455 if change['new']:
455 if change['new']:
456 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
456 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
457
457
458 enable_html_pager = Bool(False, help=
458 enable_html_pager = Bool(False, help=
459 """
459 """
460 (Provisional API) enables html representation in mime bundles sent
460 (Provisional API) enables html representation in mime bundles sent
461 to pagers.
461 to pagers.
462 """).tag(config=True)
462 """).tag(config=True)
463
463
464 @observe("enable_html_pager")
464 @observe("enable_html_pager")
465 def _enable_html_pager_changed(self, change):
465 def _enable_html_pager_changed(self, change):
466 if change['new']:
466 if change['new']:
467 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
467 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
468
468
469 data_pub_class = None
469 data_pub_class = None
470
470
471 exit_now = Bool(False)
471 exit_now = Bool(False)
472 exiter = Instance(ExitAutocall)
472 exiter = Instance(ExitAutocall)
473 @default('exiter')
473 @default('exiter')
474 def _exiter_default(self):
474 def _exiter_default(self):
475 return ExitAutocall(self)
475 return ExitAutocall(self)
476 # Monotonically increasing execution counter
476 # Monotonically increasing execution counter
477 execution_count = Integer(1)
477 execution_count = Integer(1)
478 filename = Unicode("<ipython console>")
478 filename = Unicode("<ipython console>")
479 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
479 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
480
480
481 # Used to transform cells before running them, and check whether code is complete
481 # Used to transform cells before running them, and check whether code is complete
482 input_transformer_manager = Instance('IPython.core.inputtransformer2.TransformerManager',
482 input_transformer_manager = Instance('IPython.core.inputtransformer2.TransformerManager',
483 ())
483 ())
484
484
485 @property
485 @property
486 def input_transformers_cleanup(self):
486 def input_transformers_cleanup(self):
487 return self.input_transformer_manager.cleanup_transforms
487 return self.input_transformer_manager.cleanup_transforms
488
488
489 input_transformers_post = List([],
489 input_transformers_post = List([],
490 help="A list of string input transformers, to be applied after IPython's "
490 help="A list of string input transformers, to be applied after IPython's "
491 "own input transformations."
491 "own input transformations."
492 )
492 )
493
493
494 @property
494 @property
495 def input_splitter(self):
495 def input_splitter(self):
496 """Make this available for backward compatibility (pre-7.0 release) with existing code.
496 """Make this available for backward compatibility (pre-7.0 release) with existing code.
497
497
498 For example, ipykernel ipykernel currently uses
498 For example, ipykernel ipykernel currently uses
499 `shell.input_splitter.check_complete`
499 `shell.input_splitter.check_complete`
500 """
500 """
501 from warnings import warn
501 from warnings import warn
502 warn("`input_splitter` is deprecated since IPython 7.0, prefer `input_transformer_manager`.",
502 warn("`input_splitter` is deprecated since IPython 7.0, prefer `input_transformer_manager`.",
503 DeprecationWarning, stacklevel=2
503 DeprecationWarning, stacklevel=2
504 )
504 )
505 return self.input_transformer_manager
505 return self.input_transformer_manager
506
506
507 logstart = Bool(False, help=
507 logstart = Bool(False, help=
508 """
508 """
509 Start logging to the default log file in overwrite mode.
509 Start logging to the default log file in overwrite mode.
510 Use `logappend` to specify a log file to **append** logs to.
510 Use `logappend` to specify a log file to **append** logs to.
511 """
511 """
512 ).tag(config=True)
512 ).tag(config=True)
513 logfile = Unicode('', help=
513 logfile = Unicode('', help=
514 """
514 """
515 The name of the logfile to use.
515 The name of the logfile to use.
516 """
516 """
517 ).tag(config=True)
517 ).tag(config=True)
518 logappend = Unicode('', help=
518 logappend = Unicode('', help=
519 """
519 """
520 Start logging to the given file in append mode.
520 Start logging to the given file in append mode.
521 Use `logfile` to specify a log file to **overwrite** logs to.
521 Use `logfile` to specify a log file to **overwrite** logs to.
522 """
522 """
523 ).tag(config=True)
523 ).tag(config=True)
524 object_info_string_level = Enum((0,1,2), default_value=0,
524 object_info_string_level = Enum((0,1,2), default_value=0,
525 ).tag(config=True)
525 ).tag(config=True)
526 pdb = Bool(False, help=
526 pdb = Bool(False, help=
527 """
527 """
528 Automatically call the pdb debugger after every exception.
528 Automatically call the pdb debugger after every exception.
529 """
529 """
530 ).tag(config=True)
530 ).tag(config=True)
531 display_page = Bool(False,
531 display_page = Bool(False,
532 help="""If True, anything that would be passed to the pager
532 help="""If True, anything that would be passed to the pager
533 will be displayed as regular output instead."""
533 will be displayed as regular output instead."""
534 ).tag(config=True)
534 ).tag(config=True)
535
535
536 # deprecated prompt traits:
536 # deprecated prompt traits:
537
537
538 prompt_in1 = Unicode('In [\\#]: ',
538 prompt_in1 = Unicode('In [\\#]: ',
539 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
539 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
540 ).tag(config=True)
540 ).tag(config=True)
541 prompt_in2 = Unicode(' .\\D.: ',
541 prompt_in2 = Unicode(' .\\D.: ',
542 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
542 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
543 ).tag(config=True)
543 ).tag(config=True)
544 prompt_out = Unicode('Out[\\#]: ',
544 prompt_out = Unicode('Out[\\#]: ',
545 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
545 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
546 ).tag(config=True)
546 ).tag(config=True)
547 prompts_pad_left = Bool(True,
547 prompts_pad_left = Bool(True,
548 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
548 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
549 ).tag(config=True)
549 ).tag(config=True)
550
550
551 @observe('prompt_in1', 'prompt_in2', 'prompt_out', 'prompt_pad_left')
551 @observe('prompt_in1', 'prompt_in2', 'prompt_out', 'prompt_pad_left')
552 def _prompt_trait_changed(self, change):
552 def _prompt_trait_changed(self, change):
553 name = change['name']
553 name = change['name']
554 warn("InteractiveShell.{name} is deprecated since IPython 4.0"
554 warn("InteractiveShell.{name} is deprecated since IPython 4.0"
555 " and ignored since 5.0, set TerminalInteractiveShell.prompts"
555 " and ignored since 5.0, set TerminalInteractiveShell.prompts"
556 " object directly.".format(name=name))
556 " object directly.".format(name=name))
557
557
558 # protect against weird cases where self.config may not exist:
558 # protect against weird cases where self.config may not exist:
559
559
560 show_rewritten_input = Bool(True,
560 show_rewritten_input = Bool(True,
561 help="Show rewritten input, e.g. for autocall."
561 help="Show rewritten input, e.g. for autocall."
562 ).tag(config=True)
562 ).tag(config=True)
563
563
564 quiet = Bool(False).tag(config=True)
564 quiet = Bool(False).tag(config=True)
565
565
566 history_length = Integer(10000,
566 history_length = Integer(10000,
567 help='Total length of command history'
567 help='Total length of command history'
568 ).tag(config=True)
568 ).tag(config=True)
569
569
570 history_load_length = Integer(1000, help=
570 history_load_length = Integer(1000, help=
571 """
571 """
572 The number of saved history entries to be loaded
572 The number of saved history entries to be loaded
573 into the history buffer at startup.
573 into the history buffer at startup.
574 """
574 """
575 ).tag(config=True)
575 ).tag(config=True)
576
576
577 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
577 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
578 default_value='last_expr',
578 default_value='last_expr',
579 help="""
579 help="""
580 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
580 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
581 which nodes should be run interactively (displaying output from expressions).
581 which nodes should be run interactively (displaying output from expressions).
582 """
582 """
583 ).tag(config=True)
583 ).tag(config=True)
584
584
585 # TODO: this part of prompt management should be moved to the frontends.
585 # TODO: this part of prompt management should be moved to the frontends.
586 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
586 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
587 separate_in = SeparateUnicode('\n').tag(config=True)
587 separate_in = SeparateUnicode('\n').tag(config=True)
588 separate_out = SeparateUnicode('').tag(config=True)
588 separate_out = SeparateUnicode('').tag(config=True)
589 separate_out2 = SeparateUnicode('').tag(config=True)
589 separate_out2 = SeparateUnicode('').tag(config=True)
590 wildcards_case_sensitive = Bool(True).tag(config=True)
590 wildcards_case_sensitive = Bool(True).tag(config=True)
591 xmode = CaselessStrEnum(('Context', 'Plain', 'Verbose', 'Minimal'),
591 xmode = CaselessStrEnum(('Context', 'Plain', 'Verbose', 'Minimal'),
592 default_value='Context',
592 default_value='Context',
593 help="Switch modes for the IPython exception handlers."
593 help="Switch modes for the IPython exception handlers."
594 ).tag(config=True)
594 ).tag(config=True)
595
595
596 # Subcomponents of InteractiveShell
596 # Subcomponents of InteractiveShell
597 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
597 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
598 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
598 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
599 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
599 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
600 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
600 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
601 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
601 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
602 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
602 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
603 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
603 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
604 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
604 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
605
605
606 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
606 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
607 @property
607 @property
608 def profile(self):
608 def profile(self):
609 if self.profile_dir is not None:
609 if self.profile_dir is not None:
610 name = os.path.basename(self.profile_dir.location)
610 name = os.path.basename(self.profile_dir.location)
611 return name.replace('profile_','')
611 return name.replace('profile_','')
612
612
613
613
614 # Private interface
614 # Private interface
615 _post_execute = Dict()
615 _post_execute = Dict()
616
616
617 # Tracks any GUI loop loaded for pylab
617 # Tracks any GUI loop loaded for pylab
618 pylab_gui_select = None
618 pylab_gui_select = None
619
619
620 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
620 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
621
621
622 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
622 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
623
623
624 def __init__(self, ipython_dir=None, profile_dir=None,
624 def __init__(self, ipython_dir=None, profile_dir=None,
625 user_module=None, user_ns=None,
625 user_module=None, user_ns=None,
626 custom_exceptions=((), None), **kwargs):
626 custom_exceptions=((), None), **kwargs):
627
627
628 # This is where traits with a config_key argument are updated
628 # This is where traits with a config_key argument are updated
629 # from the values on config.
629 # from the values on config.
630 super(InteractiveShell, self).__init__(**kwargs)
630 super(InteractiveShell, self).__init__(**kwargs)
631 if 'PromptManager' in self.config:
631 if 'PromptManager' in self.config:
632 warn('As of IPython 5.0 `PromptManager` config will have no effect'
632 warn('As of IPython 5.0 `PromptManager` config will have no effect'
633 ' and has been replaced by TerminalInteractiveShell.prompts_class')
633 ' and has been replaced by TerminalInteractiveShell.prompts_class')
634 self.configurables = [self]
634 self.configurables = [self]
635
635
636 # These are relatively independent and stateless
636 # These are relatively independent and stateless
637 self.init_ipython_dir(ipython_dir)
637 self.init_ipython_dir(ipython_dir)
638 self.init_profile_dir(profile_dir)
638 self.init_profile_dir(profile_dir)
639 self.init_instance_attrs()
639 self.init_instance_attrs()
640 self.init_environment()
640 self.init_environment()
641
641
642 # Check if we're in a virtualenv, and set up sys.path.
642 # Check if we're in a virtualenv, and set up sys.path.
643 self.init_virtualenv()
643 self.init_virtualenv()
644
644
645 # Create namespaces (user_ns, user_global_ns, etc.)
645 # Create namespaces (user_ns, user_global_ns, etc.)
646 self.init_create_namespaces(user_module, user_ns)
646 self.init_create_namespaces(user_module, user_ns)
647 # This has to be done after init_create_namespaces because it uses
647 # This has to be done after init_create_namespaces because it uses
648 # something in self.user_ns, but before init_sys_modules, which
648 # something in self.user_ns, but before init_sys_modules, which
649 # is the first thing to modify sys.
649 # is the first thing to modify sys.
650 # TODO: When we override sys.stdout and sys.stderr before this class
650 # TODO: When we override sys.stdout and sys.stderr before this class
651 # is created, we are saving the overridden ones here. Not sure if this
651 # is created, we are saving the overridden ones here. Not sure if this
652 # is what we want to do.
652 # is what we want to do.
653 self.save_sys_module_state()
653 self.save_sys_module_state()
654 self.init_sys_modules()
654 self.init_sys_modules()
655
655
656 # While we're trying to have each part of the code directly access what
656 # While we're trying to have each part of the code directly access what
657 # it needs without keeping redundant references to objects, we have too
657 # it needs without keeping redundant references to objects, we have too
658 # much legacy code that expects ip.db to exist.
658 # much legacy code that expects ip.db to exist.
659 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
659 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
660
660
661 self.init_history()
661 self.init_history()
662 self.init_encoding()
662 self.init_encoding()
663 self.init_prefilter()
663 self.init_prefilter()
664
664
665 self.init_syntax_highlighting()
665 self.init_syntax_highlighting()
666 self.init_hooks()
666 self.init_hooks()
667 self.init_events()
667 self.init_events()
668 self.init_pushd_popd_magic()
668 self.init_pushd_popd_magic()
669 self.init_user_ns()
669 self.init_user_ns()
670 self.init_logger()
670 self.init_logger()
671 self.init_builtins()
671 self.init_builtins()
672
672
673 # The following was in post_config_initialization
673 # The following was in post_config_initialization
674 self.init_inspector()
674 self.init_inspector()
675 self.raw_input_original = input
675 self.raw_input_original = input
676 self.init_completer()
676 self.init_completer()
677 # TODO: init_io() needs to happen before init_traceback handlers
677 # TODO: init_io() needs to happen before init_traceback handlers
678 # because the traceback handlers hardcode the stdout/stderr streams.
678 # because the traceback handlers hardcode the stdout/stderr streams.
679 # This logic in in debugger.Pdb and should eventually be changed.
679 # This logic in in debugger.Pdb and should eventually be changed.
680 self.init_io()
680 self.init_io()
681 self.init_traceback_handlers(custom_exceptions)
681 self.init_traceback_handlers(custom_exceptions)
682 self.init_prompts()
682 self.init_prompts()
683 self.init_display_formatter()
683 self.init_display_formatter()
684 self.init_display_pub()
684 self.init_display_pub()
685 self.init_data_pub()
685 self.init_data_pub()
686 self.init_displayhook()
686 self.init_displayhook()
687 self.init_magics()
687 self.init_magics()
688 self.init_alias()
688 self.init_alias()
689 self.init_logstart()
689 self.init_logstart()
690 self.init_pdb()
690 self.init_pdb()
691 self.init_extension_manager()
691 self.init_extension_manager()
692 self.init_payload()
692 self.init_payload()
693 self.init_deprecation_warnings()
693 self.init_deprecation_warnings()
694 self.hooks.late_startup_hook()
694 self.hooks.late_startup_hook()
695 self.events.trigger('shell_initialized', self)
695 self.events.trigger('shell_initialized', self)
696 atexit.register(self.atexit_operations)
696 atexit.register(self.atexit_operations)
697
697
698 # The trio runner is used for running Trio in the foreground thread. It
698 # The trio runner is used for running Trio in the foreground thread. It
699 # is different from `_trio_runner(async_fn)` in `async_helpers.py`
699 # is different from `_trio_runner(async_fn)` in `async_helpers.py`
700 # which calls `trio.run()` for every cell. This runner runs all cells
700 # which calls `trio.run()` for every cell. This runner runs all cells
701 # inside a single Trio event loop. If used, it is set from
701 # inside a single Trio event loop. If used, it is set from
702 # `ipykernel.kernelapp`.
702 # `ipykernel.kernelapp`.
703 self.trio_runner = None
703 self.trio_runner = None
704
704
705 def get_ipython(self):
705 def get_ipython(self):
706 """Return the currently running IPython instance."""
706 """Return the currently running IPython instance."""
707 return self
707 return self
708
708
709 #-------------------------------------------------------------------------
709 #-------------------------------------------------------------------------
710 # Trait changed handlers
710 # Trait changed handlers
711 #-------------------------------------------------------------------------
711 #-------------------------------------------------------------------------
712 @observe('ipython_dir')
712 @observe('ipython_dir')
713 def _ipython_dir_changed(self, change):
713 def _ipython_dir_changed(self, change):
714 ensure_dir_exists(change['new'])
714 ensure_dir_exists(change['new'])
715
715
716 def set_autoindent(self,value=None):
716 def set_autoindent(self,value=None):
717 """Set the autoindent flag.
717 """Set the autoindent flag.
718
718
719 If called with no arguments, it acts as a toggle."""
719 If called with no arguments, it acts as a toggle."""
720 if value is None:
720 if value is None:
721 self.autoindent = not self.autoindent
721 self.autoindent = not self.autoindent
722 else:
722 else:
723 self.autoindent = value
723 self.autoindent = value
724
724
725 def set_trio_runner(self, tr):
725 def set_trio_runner(self, tr):
726 self.trio_runner = tr
726 self.trio_runner = tr
727
727
728 #-------------------------------------------------------------------------
728 #-------------------------------------------------------------------------
729 # init_* methods called by __init__
729 # init_* methods called by __init__
730 #-------------------------------------------------------------------------
730 #-------------------------------------------------------------------------
731
731
732 def init_ipython_dir(self, ipython_dir):
732 def init_ipython_dir(self, ipython_dir):
733 if ipython_dir is not None:
733 if ipython_dir is not None:
734 self.ipython_dir = ipython_dir
734 self.ipython_dir = ipython_dir
735 return
735 return
736
736
737 self.ipython_dir = get_ipython_dir()
737 self.ipython_dir = get_ipython_dir()
738
738
739 def init_profile_dir(self, profile_dir):
739 def init_profile_dir(self, profile_dir):
740 if profile_dir is not None:
740 if profile_dir is not None:
741 self.profile_dir = profile_dir
741 self.profile_dir = profile_dir
742 return
742 return
743 self.profile_dir =\
743 self.profile_dir =\
744 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
744 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
745
745
746 def init_instance_attrs(self):
746 def init_instance_attrs(self):
747 self.more = False
747 self.more = False
748
748
749 # command compiler
749 # command compiler
750 self.compile = CachingCompiler()
750 self.compile = CachingCompiler()
751
751
752 # Make an empty namespace, which extension writers can rely on both
752 # Make an empty namespace, which extension writers can rely on both
753 # existing and NEVER being used by ipython itself. This gives them a
753 # existing and NEVER being used by ipython itself. This gives them a
754 # convenient location for storing additional information and state
754 # convenient location for storing additional information and state
755 # their extensions may require, without fear of collisions with other
755 # their extensions may require, without fear of collisions with other
756 # ipython names that may develop later.
756 # ipython names that may develop later.
757 self.meta = Struct()
757 self.meta = Struct()
758
758
759 # Temporary files used for various purposes. Deleted at exit.
759 # Temporary files used for various purposes. Deleted at exit.
760 self.tempfiles = []
760 self.tempfiles = []
761 self.tempdirs = []
761 self.tempdirs = []
762
762
763 # keep track of where we started running (mainly for crash post-mortem)
763 # keep track of where we started running (mainly for crash post-mortem)
764 # This is not being used anywhere currently.
764 # This is not being used anywhere currently.
765 self.starting_dir = os.getcwd()
765 self.starting_dir = os.getcwd()
766
766
767 # Indentation management
767 # Indentation management
768 self.indent_current_nsp = 0
768 self.indent_current_nsp = 0
769
769
770 # Dict to track post-execution functions that have been registered
770 # Dict to track post-execution functions that have been registered
771 self._post_execute = {}
771 self._post_execute = {}
772
772
773 def init_environment(self):
773 def init_environment(self):
774 """Any changes we need to make to the user's environment."""
774 """Any changes we need to make to the user's environment."""
775 pass
775 pass
776
776
777 def init_encoding(self):
777 def init_encoding(self):
778 # Get system encoding at startup time. Certain terminals (like Emacs
778 # Get system encoding at startup time. Certain terminals (like Emacs
779 # under Win32 have it set to None, and we need to have a known valid
779 # under Win32 have it set to None, and we need to have a known valid
780 # encoding to use in the raw_input() method
780 # encoding to use in the raw_input() method
781 try:
781 try:
782 self.stdin_encoding = sys.stdin.encoding or 'ascii'
782 self.stdin_encoding = sys.stdin.encoding or 'ascii'
783 except AttributeError:
783 except AttributeError:
784 self.stdin_encoding = 'ascii'
784 self.stdin_encoding = 'ascii'
785
785
786
786
787 @observe('colors')
787 @observe('colors')
788 def init_syntax_highlighting(self, changes=None):
788 def init_syntax_highlighting(self, changes=None):
789 # Python source parser/formatter for syntax highlighting
789 # Python source parser/formatter for syntax highlighting
790 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
790 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
791 self.pycolorize = lambda src: pyformat(src,'str')
791 self.pycolorize = lambda src: pyformat(src,'str')
792
792
793 def refresh_style(self):
793 def refresh_style(self):
794 # No-op here, used in subclass
794 # No-op here, used in subclass
795 pass
795 pass
796
796
797 def init_pushd_popd_magic(self):
797 def init_pushd_popd_magic(self):
798 # for pushd/popd management
798 # for pushd/popd management
799 self.home_dir = get_home_dir()
799 self.home_dir = get_home_dir()
800
800
801 self.dir_stack = []
801 self.dir_stack = []
802
802
803 def init_logger(self):
803 def init_logger(self):
804 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
804 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
805 logmode='rotate')
805 logmode='rotate')
806
806
807 def init_logstart(self):
807 def init_logstart(self):
808 """Initialize logging in case it was requested at the command line.
808 """Initialize logging in case it was requested at the command line.
809 """
809 """
810 if self.logappend:
810 if self.logappend:
811 self.magic('logstart %s append' % self.logappend)
811 self.magic('logstart %s append' % self.logappend)
812 elif self.logfile:
812 elif self.logfile:
813 self.magic('logstart %s' % self.logfile)
813 self.magic('logstart %s' % self.logfile)
814 elif self.logstart:
814 elif self.logstart:
815 self.magic('logstart')
815 self.magic('logstart')
816
816
817 def init_deprecation_warnings(self):
817 def init_deprecation_warnings(self):
818 """
818 """
819 register default filter for deprecation warning.
819 register default filter for deprecation warning.
820
820
821 This will allow deprecation warning of function used interactively to show
821 This will allow deprecation warning of function used interactively to show
822 warning to users, and still hide deprecation warning from libraries import.
822 warning to users, and still hide deprecation warning from libraries import.
823 """
823 """
824 if sys.version_info < (3,7):
824 if sys.version_info < (3,7):
825 warnings.filterwarnings("default", category=DeprecationWarning, module=self.user_ns.get("__name__"))
825 warnings.filterwarnings("default", category=DeprecationWarning, module=self.user_ns.get("__name__"))
826
826
827
827
828 def init_builtins(self):
828 def init_builtins(self):
829 # A single, static flag that we set to True. Its presence indicates
829 # A single, static flag that we set to True. Its presence indicates
830 # that an IPython shell has been created, and we make no attempts at
830 # that an IPython shell has been created, and we make no attempts at
831 # removing on exit or representing the existence of more than one
831 # removing on exit or representing the existence of more than one
832 # IPython at a time.
832 # IPython at a time.
833 builtin_mod.__dict__['__IPYTHON__'] = True
833 builtin_mod.__dict__['__IPYTHON__'] = True
834 builtin_mod.__dict__['display'] = display
834 builtin_mod.__dict__['display'] = display
835
835
836 self.builtin_trap = BuiltinTrap(shell=self)
836 self.builtin_trap = BuiltinTrap(shell=self)
837
837
838 @observe('colors')
838 @observe('colors')
839 def init_inspector(self, changes=None):
839 def init_inspector(self, changes=None):
840 # Object inspector
840 # Object inspector
841 self.inspector = oinspect.Inspector(oinspect.InspectColors,
841 self.inspector = oinspect.Inspector(oinspect.InspectColors,
842 PyColorize.ANSICodeColors,
842 PyColorize.ANSICodeColors,
843 self.colors,
843 self.colors,
844 self.object_info_string_level)
844 self.object_info_string_level)
845
845
846 def init_io(self):
846 def init_io(self):
847 # This will just use sys.stdout and sys.stderr. If you want to
847 # This will just use sys.stdout and sys.stderr. If you want to
848 # override sys.stdout and sys.stderr themselves, you need to do that
848 # override sys.stdout and sys.stderr themselves, you need to do that
849 # *before* instantiating this class, because io holds onto
849 # *before* instantiating this class, because io holds onto
850 # references to the underlying streams.
850 # references to the underlying streams.
851 # io.std* are deprecated, but don't show our own deprecation warnings
851 # io.std* are deprecated, but don't show our own deprecation warnings
852 # during initialization of the deprecated API.
852 # during initialization of the deprecated API.
853 with warnings.catch_warnings():
853 with warnings.catch_warnings():
854 warnings.simplefilter('ignore', DeprecationWarning)
854 warnings.simplefilter('ignore', DeprecationWarning)
855 io.stdout = io.IOStream(sys.stdout)
855 io.stdout = io.IOStream(sys.stdout)
856 io.stderr = io.IOStream(sys.stderr)
856 io.stderr = io.IOStream(sys.stderr)
857
857
858 def init_prompts(self):
858 def init_prompts(self):
859 # Set system prompts, so that scripts can decide if they are running
859 # Set system prompts, so that scripts can decide if they are running
860 # interactively.
860 # interactively.
861 sys.ps1 = 'In : '
861 sys.ps1 = 'In : '
862 sys.ps2 = '...: '
862 sys.ps2 = '...: '
863 sys.ps3 = 'Out: '
863 sys.ps3 = 'Out: '
864
864
865 def init_display_formatter(self):
865 def init_display_formatter(self):
866 self.display_formatter = DisplayFormatter(parent=self)
866 self.display_formatter = DisplayFormatter(parent=self)
867 self.configurables.append(self.display_formatter)
867 self.configurables.append(self.display_formatter)
868
868
869 def init_display_pub(self):
869 def init_display_pub(self):
870 self.display_pub = self.display_pub_class(parent=self, shell=self)
870 self.display_pub = self.display_pub_class(parent=self, shell=self)
871 self.configurables.append(self.display_pub)
871 self.configurables.append(self.display_pub)
872
872
873 def init_data_pub(self):
873 def init_data_pub(self):
874 if not self.data_pub_class:
874 if not self.data_pub_class:
875 self.data_pub = None
875 self.data_pub = None
876 return
876 return
877 self.data_pub = self.data_pub_class(parent=self)
877 self.data_pub = self.data_pub_class(parent=self)
878 self.configurables.append(self.data_pub)
878 self.configurables.append(self.data_pub)
879
879
880 def init_displayhook(self):
880 def init_displayhook(self):
881 # Initialize displayhook, set in/out prompts and printing system
881 # Initialize displayhook, set in/out prompts and printing system
882 self.displayhook = self.displayhook_class(
882 self.displayhook = self.displayhook_class(
883 parent=self,
883 parent=self,
884 shell=self,
884 shell=self,
885 cache_size=self.cache_size,
885 cache_size=self.cache_size,
886 )
886 )
887 self.configurables.append(self.displayhook)
887 self.configurables.append(self.displayhook)
888 # This is a context manager that installs/revmoes the displayhook at
888 # This is a context manager that installs/revmoes the displayhook at
889 # the appropriate time.
889 # the appropriate time.
890 self.display_trap = DisplayTrap(hook=self.displayhook)
890 self.display_trap = DisplayTrap(hook=self.displayhook)
891
891
892 def init_virtualenv(self):
892 def init_virtualenv(self):
893 """Add a virtualenv to sys.path so the user can import modules from it.
893 """Add a virtualenv to sys.path so the user can import modules from it.
894 This isn't perfect: it doesn't use the Python interpreter with which the
894 This isn't perfect: it doesn't use the Python interpreter with which the
895 virtualenv was built, and it ignores the --no-site-packages option. A
895 virtualenv was built, and it ignores the --no-site-packages option. A
896 warning will appear suggesting the user installs IPython in the
896 warning will appear suggesting the user installs IPython in the
897 virtualenv, but for many cases, it probably works well enough.
897 virtualenv, but for many cases, it probably works well enough.
898
898
899 Adapted from code snippets online.
899 Adapted from code snippets online.
900
900
901 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
901 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
902 """
902 """
903 if 'VIRTUAL_ENV' not in os.environ:
903 if 'VIRTUAL_ENV' not in os.environ:
904 # Not in a virtualenv
904 # Not in a virtualenv
905 return
905 return
906
906
907 p = os.path.normcase(sys.executable)
907 p = os.path.normcase(sys.executable)
908 p_venv = os.path.normcase(os.environ['VIRTUAL_ENV'])
908 p_venv = os.path.normcase(os.environ['VIRTUAL_ENV'])
909
909
910 # executable path should end like /bin/python or \\scripts\\python.exe
910 # executable path should end like /bin/python or \\scripts\\python.exe
911 p_exe_up2 = os.path.dirname(os.path.dirname(p))
911 p_exe_up2 = os.path.dirname(os.path.dirname(p))
912 if p_exe_up2 and os.path.exists(p_venv) and os.path.samefile(p_exe_up2, p_venv):
912 if p_exe_up2 and os.path.exists(p_venv) and os.path.samefile(p_exe_up2, p_venv):
913 # Our exe is inside the virtualenv, don't need to do anything.
913 # Our exe is inside the virtualenv, don't need to do anything.
914 return
914 return
915
915
916 # fallback venv detection:
916 # fallback venv detection:
917 # stdlib venv may symlink sys.executable, so we can't use realpath.
917 # stdlib venv may symlink sys.executable, so we can't use realpath.
918 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
918 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
919 # So we just check every item in the symlink tree (generally <= 3)
919 # So we just check every item in the symlink tree (generally <= 3)
920 paths = [p]
920 paths = [p]
921 while os.path.islink(p):
921 while os.path.islink(p):
922 p = os.path.normcase(os.path.join(os.path.dirname(p), os.readlink(p)))
922 p = os.path.normcase(os.path.join(os.path.dirname(p), os.readlink(p)))
923 paths.append(p)
923 paths.append(p)
924
924
925 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
925 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
926 if p_venv.startswith('\\cygdrive'):
926 if p_venv.startswith('\\cygdrive'):
927 p_venv = p_venv[11:]
927 p_venv = p_venv[11:]
928 elif len(p_venv) >= 2 and p_venv[1] == ':':
928 elif len(p_venv) >= 2 and p_venv[1] == ':':
929 p_venv = p_venv[2:]
929 p_venv = p_venv[2:]
930
930
931 if any(p_venv in p for p in paths):
931 if any(p_venv in p for p in paths):
932 # Running properly in the virtualenv, don't need to do anything
932 # Running properly in the virtualenv, don't need to do anything
933 return
933 return
934
934
935 warn("Attempting to work in a virtualenv. If you encounter problems, please "
935 warn("Attempting to work in a virtualenv. If you encounter problems, please "
936 "install IPython inside the virtualenv.")
936 "install IPython inside the virtualenv.")
937 if sys.platform == "win32":
937 if sys.platform == "win32":
938 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
938 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
939 else:
939 else:
940 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
940 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
941 'python%d.%d' % sys.version_info[:2], 'site-packages')
941 'python%d.%d' % sys.version_info[:2], 'site-packages')
942
942
943 import site
943 import site
944 sys.path.insert(0, virtual_env)
944 sys.path.insert(0, virtual_env)
945 site.addsitedir(virtual_env)
945 site.addsitedir(virtual_env)
946
946
947 #-------------------------------------------------------------------------
947 #-------------------------------------------------------------------------
948 # Things related to injections into the sys module
948 # Things related to injections into the sys module
949 #-------------------------------------------------------------------------
949 #-------------------------------------------------------------------------
950
950
951 def save_sys_module_state(self):
951 def save_sys_module_state(self):
952 """Save the state of hooks in the sys module.
952 """Save the state of hooks in the sys module.
953
953
954 This has to be called after self.user_module is created.
954 This has to be called after self.user_module is created.
955 """
955 """
956 self._orig_sys_module_state = {'stdin': sys.stdin,
956 self._orig_sys_module_state = {'stdin': sys.stdin,
957 'stdout': sys.stdout,
957 'stdout': sys.stdout,
958 'stderr': sys.stderr,
958 'stderr': sys.stderr,
959 'excepthook': sys.excepthook}
959 'excepthook': sys.excepthook}
960 self._orig_sys_modules_main_name = self.user_module.__name__
960 self._orig_sys_modules_main_name = self.user_module.__name__
961 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
961 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
962
962
963 def restore_sys_module_state(self):
963 def restore_sys_module_state(self):
964 """Restore the state of the sys module."""
964 """Restore the state of the sys module."""
965 try:
965 try:
966 for k, v in self._orig_sys_module_state.items():
966 for k, v in self._orig_sys_module_state.items():
967 setattr(sys, k, v)
967 setattr(sys, k, v)
968 except AttributeError:
968 except AttributeError:
969 pass
969 pass
970 # Reset what what done in self.init_sys_modules
970 # Reset what what done in self.init_sys_modules
971 if self._orig_sys_modules_main_mod is not None:
971 if self._orig_sys_modules_main_mod is not None:
972 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
972 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
973
973
974 #-------------------------------------------------------------------------
974 #-------------------------------------------------------------------------
975 # Things related to the banner
975 # Things related to the banner
976 #-------------------------------------------------------------------------
976 #-------------------------------------------------------------------------
977
977
978 @property
978 @property
979 def banner(self):
979 def banner(self):
980 banner = self.banner1
980 banner = self.banner1
981 if self.profile and self.profile != 'default':
981 if self.profile and self.profile != 'default':
982 banner += '\nIPython profile: %s\n' % self.profile
982 banner += '\nIPython profile: %s\n' % self.profile
983 if self.banner2:
983 if self.banner2:
984 banner += '\n' + self.banner2
984 banner += '\n' + self.banner2
985 return banner
985 return banner
986
986
987 def show_banner(self, banner=None):
987 def show_banner(self, banner=None):
988 if banner is None:
988 if banner is None:
989 banner = self.banner
989 banner = self.banner
990 sys.stdout.write(banner)
990 sys.stdout.write(banner)
991
991
992 #-------------------------------------------------------------------------
992 #-------------------------------------------------------------------------
993 # Things related to hooks
993 # Things related to hooks
994 #-------------------------------------------------------------------------
994 #-------------------------------------------------------------------------
995
995
996 def init_hooks(self):
996 def init_hooks(self):
997 # hooks holds pointers used for user-side customizations
997 # hooks holds pointers used for user-side customizations
998 self.hooks = Struct()
998 self.hooks = Struct()
999
999
1000 self.strdispatchers = {}
1000 self.strdispatchers = {}
1001
1001
1002 # Set all default hooks, defined in the IPython.hooks module.
1002 # Set all default hooks, defined in the IPython.hooks module.
1003 hooks = IPython.core.hooks
1003 hooks = IPython.core.hooks
1004 for hook_name in hooks.__all__:
1004 for hook_name in hooks.__all__:
1005 # default hooks have priority 100, i.e. low; user hooks should have
1005 # default hooks have priority 100, i.e. low; user hooks should have
1006 # 0-100 priority
1006 # 0-100 priority
1007 self.set_hook(hook_name,getattr(hooks,hook_name), 100, _warn_deprecated=False)
1007 self.set_hook(hook_name,getattr(hooks,hook_name), 100, _warn_deprecated=False)
1008
1008
1009 if self.display_page:
1009 if self.display_page:
1010 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
1010 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
1011
1011
1012 def set_hook(self,name,hook, priority=50, str_key=None, re_key=None,
1012 def set_hook(self,name,hook, priority=50, str_key=None, re_key=None,
1013 _warn_deprecated=True):
1013 _warn_deprecated=True):
1014 """set_hook(name,hook) -> sets an internal IPython hook.
1014 """set_hook(name,hook) -> sets an internal IPython hook.
1015
1015
1016 IPython exposes some of its internal API as user-modifiable hooks. By
1016 IPython exposes some of its internal API as user-modifiable hooks. By
1017 adding your function to one of these hooks, you can modify IPython's
1017 adding your function to one of these hooks, you can modify IPython's
1018 behavior to call at runtime your own routines."""
1018 behavior to call at runtime your own routines."""
1019
1019
1020 # At some point in the future, this should validate the hook before it
1020 # At some point in the future, this should validate the hook before it
1021 # accepts it. Probably at least check that the hook takes the number
1021 # accepts it. Probably at least check that the hook takes the number
1022 # of args it's supposed to.
1022 # of args it's supposed to.
1023
1023
1024 f = types.MethodType(hook,self)
1024 f = types.MethodType(hook,self)
1025
1025
1026 # check if the hook is for strdispatcher first
1026 # check if the hook is for strdispatcher first
1027 if str_key is not None:
1027 if str_key is not None:
1028 sdp = self.strdispatchers.get(name, StrDispatch())
1028 sdp = self.strdispatchers.get(name, StrDispatch())
1029 sdp.add_s(str_key, f, priority )
1029 sdp.add_s(str_key, f, priority )
1030 self.strdispatchers[name] = sdp
1030 self.strdispatchers[name] = sdp
1031 return
1031 return
1032 if re_key is not None:
1032 if re_key is not None:
1033 sdp = self.strdispatchers.get(name, StrDispatch())
1033 sdp = self.strdispatchers.get(name, StrDispatch())
1034 sdp.add_re(re.compile(re_key), f, priority )
1034 sdp.add_re(re.compile(re_key), f, priority )
1035 self.strdispatchers[name] = sdp
1035 self.strdispatchers[name] = sdp
1036 return
1036 return
1037
1037
1038 dp = getattr(self.hooks, name, None)
1038 dp = getattr(self.hooks, name, None)
1039 if name not in IPython.core.hooks.__all__:
1039 if name not in IPython.core.hooks.__all__:
1040 print("Warning! Hook '%s' is not one of %s" % \
1040 print("Warning! Hook '%s' is not one of %s" % \
1041 (name, IPython.core.hooks.__all__ ))
1041 (name, IPython.core.hooks.__all__ ))
1042
1042
1043 if _warn_deprecated and (name in IPython.core.hooks.deprecated):
1043 if _warn_deprecated and (name in IPython.core.hooks.deprecated):
1044 alternative = IPython.core.hooks.deprecated[name]
1044 alternative = IPython.core.hooks.deprecated[name]
1045 warn("Hook {} is deprecated. Use {} instead.".format(name, alternative), stacklevel=2)
1045 warn("Hook {} is deprecated. Use {} instead.".format(name, alternative), stacklevel=2)
1046
1046
1047 if not dp:
1047 if not dp:
1048 dp = IPython.core.hooks.CommandChainDispatcher()
1048 dp = IPython.core.hooks.CommandChainDispatcher()
1049
1049
1050 try:
1050 try:
1051 dp.add(f,priority)
1051 dp.add(f,priority)
1052 except AttributeError:
1052 except AttributeError:
1053 # it was not commandchain, plain old func - replace
1053 # it was not commandchain, plain old func - replace
1054 dp = f
1054 dp = f
1055
1055
1056 setattr(self.hooks,name, dp)
1056 setattr(self.hooks,name, dp)
1057
1057
1058 #-------------------------------------------------------------------------
1058 #-------------------------------------------------------------------------
1059 # Things related to events
1059 # Things related to events
1060 #-------------------------------------------------------------------------
1060 #-------------------------------------------------------------------------
1061
1061
1062 def init_events(self):
1062 def init_events(self):
1063 self.events = EventManager(self, available_events)
1063 self.events = EventManager(self, available_events)
1064
1064
1065 self.events.register("pre_execute", self._clear_warning_registry)
1065 self.events.register("pre_execute", self._clear_warning_registry)
1066
1066
1067 def register_post_execute(self, func):
1067 def register_post_execute(self, func):
1068 """DEPRECATED: Use ip.events.register('post_run_cell', func)
1068 """DEPRECATED: Use ip.events.register('post_run_cell', func)
1069
1069
1070 Register a function for calling after code execution.
1070 Register a function for calling after code execution.
1071 """
1071 """
1072 warn("ip.register_post_execute is deprecated, use "
1072 warn("ip.register_post_execute is deprecated, use "
1073 "ip.events.register('post_run_cell', func) instead.", stacklevel=2)
1073 "ip.events.register('post_run_cell', func) instead.", stacklevel=2)
1074 self.events.register('post_run_cell', func)
1074 self.events.register('post_run_cell', func)
1075
1075
1076 def _clear_warning_registry(self):
1076 def _clear_warning_registry(self):
1077 # clear the warning registry, so that different code blocks with
1077 # clear the warning registry, so that different code blocks with
1078 # overlapping line number ranges don't cause spurious suppression of
1078 # overlapping line number ranges don't cause spurious suppression of
1079 # warnings (see gh-6611 for details)
1079 # warnings (see gh-6611 for details)
1080 if "__warningregistry__" in self.user_global_ns:
1080 if "__warningregistry__" in self.user_global_ns:
1081 del self.user_global_ns["__warningregistry__"]
1081 del self.user_global_ns["__warningregistry__"]
1082
1082
1083 #-------------------------------------------------------------------------
1083 #-------------------------------------------------------------------------
1084 # Things related to the "main" module
1084 # Things related to the "main" module
1085 #-------------------------------------------------------------------------
1085 #-------------------------------------------------------------------------
1086
1086
1087 def new_main_mod(self, filename, modname):
1087 def new_main_mod(self, filename, modname):
1088 """Return a new 'main' module object for user code execution.
1088 """Return a new 'main' module object for user code execution.
1089
1089
1090 ``filename`` should be the path of the script which will be run in the
1090 ``filename`` should be the path of the script which will be run in the
1091 module. Requests with the same filename will get the same module, with
1091 module. Requests with the same filename will get the same module, with
1092 its namespace cleared.
1092 its namespace cleared.
1093
1093
1094 ``modname`` should be the module name - normally either '__main__' or
1094 ``modname`` should be the module name - normally either '__main__' or
1095 the basename of the file without the extension.
1095 the basename of the file without the extension.
1096
1096
1097 When scripts are executed via %run, we must keep a reference to their
1097 When scripts are executed via %run, we must keep a reference to their
1098 __main__ module around so that Python doesn't
1098 __main__ module around so that Python doesn't
1099 clear it, rendering references to module globals useless.
1099 clear it, rendering references to module globals useless.
1100
1100
1101 This method keeps said reference in a private dict, keyed by the
1101 This method keeps said reference in a private dict, keyed by the
1102 absolute path of the script. This way, for multiple executions of the
1102 absolute path of the script. This way, for multiple executions of the
1103 same script we only keep one copy of the namespace (the last one),
1103 same script we only keep one copy of the namespace (the last one),
1104 thus preventing memory leaks from old references while allowing the
1104 thus preventing memory leaks from old references while allowing the
1105 objects from the last execution to be accessible.
1105 objects from the last execution to be accessible.
1106 """
1106 """
1107 filename = os.path.abspath(filename)
1107 filename = os.path.abspath(filename)
1108 try:
1108 try:
1109 main_mod = self._main_mod_cache[filename]
1109 main_mod = self._main_mod_cache[filename]
1110 except KeyError:
1110 except KeyError:
1111 main_mod = self._main_mod_cache[filename] = types.ModuleType(
1111 main_mod = self._main_mod_cache[filename] = types.ModuleType(
1112 modname,
1112 modname,
1113 doc="Module created for script run in IPython")
1113 doc="Module created for script run in IPython")
1114 else:
1114 else:
1115 main_mod.__dict__.clear()
1115 main_mod.__dict__.clear()
1116 main_mod.__name__ = modname
1116 main_mod.__name__ = modname
1117
1117
1118 main_mod.__file__ = filename
1118 main_mod.__file__ = filename
1119 # It seems pydoc (and perhaps others) needs any module instance to
1119 # It seems pydoc (and perhaps others) needs any module instance to
1120 # implement a __nonzero__ method
1120 # implement a __nonzero__ method
1121 main_mod.__nonzero__ = lambda : True
1121 main_mod.__nonzero__ = lambda : True
1122
1122
1123 return main_mod
1123 return main_mod
1124
1124
1125 def clear_main_mod_cache(self):
1125 def clear_main_mod_cache(self):
1126 """Clear the cache of main modules.
1126 """Clear the cache of main modules.
1127
1127
1128 Mainly for use by utilities like %reset.
1128 Mainly for use by utilities like %reset.
1129
1129
1130 Examples
1130 Examples
1131 --------
1131 --------
1132
1132
1133 In [15]: import IPython
1133 In [15]: import IPython
1134
1134
1135 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
1135 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
1136
1136
1137 In [17]: len(_ip._main_mod_cache) > 0
1137 In [17]: len(_ip._main_mod_cache) > 0
1138 Out[17]: True
1138 Out[17]: True
1139
1139
1140 In [18]: _ip.clear_main_mod_cache()
1140 In [18]: _ip.clear_main_mod_cache()
1141
1141
1142 In [19]: len(_ip._main_mod_cache) == 0
1142 In [19]: len(_ip._main_mod_cache) == 0
1143 Out[19]: True
1143 Out[19]: True
1144 """
1144 """
1145 self._main_mod_cache.clear()
1145 self._main_mod_cache.clear()
1146
1146
1147 #-------------------------------------------------------------------------
1147 #-------------------------------------------------------------------------
1148 # Things related to debugging
1148 # Things related to debugging
1149 #-------------------------------------------------------------------------
1149 #-------------------------------------------------------------------------
1150
1150
1151 def init_pdb(self):
1151 def init_pdb(self):
1152 # Set calling of pdb on exceptions
1152 # Set calling of pdb on exceptions
1153 # self.call_pdb is a property
1153 # self.call_pdb is a property
1154 self.call_pdb = self.pdb
1154 self.call_pdb = self.pdb
1155
1155
1156 def _get_call_pdb(self):
1156 def _get_call_pdb(self):
1157 return self._call_pdb
1157 return self._call_pdb
1158
1158
1159 def _set_call_pdb(self,val):
1159 def _set_call_pdb(self,val):
1160
1160
1161 if val not in (0,1,False,True):
1161 if val not in (0,1,False,True):
1162 raise ValueError('new call_pdb value must be boolean')
1162 raise ValueError('new call_pdb value must be boolean')
1163
1163
1164 # store value in instance
1164 # store value in instance
1165 self._call_pdb = val
1165 self._call_pdb = val
1166
1166
1167 # notify the actual exception handlers
1167 # notify the actual exception handlers
1168 self.InteractiveTB.call_pdb = val
1168 self.InteractiveTB.call_pdb = val
1169
1169
1170 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1170 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1171 'Control auto-activation of pdb at exceptions')
1171 'Control auto-activation of pdb at exceptions')
1172
1172
1173 def debugger(self,force=False):
1173 def debugger(self,force=False):
1174 """Call the pdb debugger.
1174 """Call the pdb debugger.
1175
1175
1176 Keywords:
1176 Keywords:
1177
1177
1178 - force(False): by default, this routine checks the instance call_pdb
1178 - force(False): by default, this routine checks the instance call_pdb
1179 flag and does not actually invoke the debugger if the flag is false.
1179 flag and does not actually invoke the debugger if the flag is false.
1180 The 'force' option forces the debugger to activate even if the flag
1180 The 'force' option forces the debugger to activate even if the flag
1181 is false.
1181 is false.
1182 """
1182 """
1183
1183
1184 if not (force or self.call_pdb):
1184 if not (force or self.call_pdb):
1185 return
1185 return
1186
1186
1187 if not hasattr(sys,'last_traceback'):
1187 if not hasattr(sys,'last_traceback'):
1188 error('No traceback has been produced, nothing to debug.')
1188 error('No traceback has been produced, nothing to debug.')
1189 return
1189 return
1190
1190
1191 self.InteractiveTB.debugger(force=True)
1191 self.InteractiveTB.debugger(force=True)
1192
1192
1193 #-------------------------------------------------------------------------
1193 #-------------------------------------------------------------------------
1194 # Things related to IPython's various namespaces
1194 # Things related to IPython's various namespaces
1195 #-------------------------------------------------------------------------
1195 #-------------------------------------------------------------------------
1196 default_user_namespaces = True
1196 default_user_namespaces = True
1197
1197
1198 def init_create_namespaces(self, user_module=None, user_ns=None):
1198 def init_create_namespaces(self, user_module=None, user_ns=None):
1199 # Create the namespace where the user will operate. user_ns is
1199 # Create the namespace where the user will operate. user_ns is
1200 # normally the only one used, and it is passed to the exec calls as
1200 # normally the only one used, and it is passed to the exec calls as
1201 # the locals argument. But we do carry a user_global_ns namespace
1201 # the locals argument. But we do carry a user_global_ns namespace
1202 # given as the exec 'globals' argument, This is useful in embedding
1202 # given as the exec 'globals' argument, This is useful in embedding
1203 # situations where the ipython shell opens in a context where the
1203 # situations where the ipython shell opens in a context where the
1204 # distinction between locals and globals is meaningful. For
1204 # distinction between locals and globals is meaningful. For
1205 # non-embedded contexts, it is just the same object as the user_ns dict.
1205 # non-embedded contexts, it is just the same object as the user_ns dict.
1206
1206
1207 # FIXME. For some strange reason, __builtins__ is showing up at user
1207 # FIXME. For some strange reason, __builtins__ is showing up at user
1208 # level as a dict instead of a module. This is a manual fix, but I
1208 # level as a dict instead of a module. This is a manual fix, but I
1209 # should really track down where the problem is coming from. Alex
1209 # should really track down where the problem is coming from. Alex
1210 # Schmolck reported this problem first.
1210 # Schmolck reported this problem first.
1211
1211
1212 # A useful post by Alex Martelli on this topic:
1212 # A useful post by Alex Martelli on this topic:
1213 # Re: inconsistent value from __builtins__
1213 # Re: inconsistent value from __builtins__
1214 # Von: Alex Martelli <aleaxit@yahoo.com>
1214 # Von: Alex Martelli <aleaxit@yahoo.com>
1215 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1215 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1216 # Gruppen: comp.lang.python
1216 # Gruppen: comp.lang.python
1217
1217
1218 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1218 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1219 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1219 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1220 # > <type 'dict'>
1220 # > <type 'dict'>
1221 # > >>> print type(__builtins__)
1221 # > >>> print type(__builtins__)
1222 # > <type 'module'>
1222 # > <type 'module'>
1223 # > Is this difference in return value intentional?
1223 # > Is this difference in return value intentional?
1224
1224
1225 # Well, it's documented that '__builtins__' can be either a dictionary
1225 # Well, it's documented that '__builtins__' can be either a dictionary
1226 # or a module, and it's been that way for a long time. Whether it's
1226 # or a module, and it's been that way for a long time. Whether it's
1227 # intentional (or sensible), I don't know. In any case, the idea is
1227 # intentional (or sensible), I don't know. In any case, the idea is
1228 # that if you need to access the built-in namespace directly, you
1228 # that if you need to access the built-in namespace directly, you
1229 # should start with "import __builtin__" (note, no 's') which will
1229 # should start with "import __builtin__" (note, no 's') which will
1230 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1230 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1231
1231
1232 # These routines return a properly built module and dict as needed by
1232 # These routines return a properly built module and dict as needed by
1233 # the rest of the code, and can also be used by extension writers to
1233 # the rest of the code, and can also be used by extension writers to
1234 # generate properly initialized namespaces.
1234 # generate properly initialized namespaces.
1235 if (user_ns is not None) or (user_module is not None):
1235 if (user_ns is not None) or (user_module is not None):
1236 self.default_user_namespaces = False
1236 self.default_user_namespaces = False
1237 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1237 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1238
1238
1239 # A record of hidden variables we have added to the user namespace, so
1239 # A record of hidden variables we have added to the user namespace, so
1240 # we can list later only variables defined in actual interactive use.
1240 # we can list later only variables defined in actual interactive use.
1241 self.user_ns_hidden = {}
1241 self.user_ns_hidden = {}
1242
1242
1243 # Now that FakeModule produces a real module, we've run into a nasty
1243 # Now that FakeModule produces a real module, we've run into a nasty
1244 # problem: after script execution (via %run), the module where the user
1244 # problem: after script execution (via %run), the module where the user
1245 # code ran is deleted. Now that this object is a true module (needed
1245 # code ran is deleted. Now that this object is a true module (needed
1246 # so doctest and other tools work correctly), the Python module
1246 # so doctest and other tools work correctly), the Python module
1247 # teardown mechanism runs over it, and sets to None every variable
1247 # teardown mechanism runs over it, and sets to None every variable
1248 # present in that module. Top-level references to objects from the
1248 # present in that module. Top-level references to objects from the
1249 # script survive, because the user_ns is updated with them. However,
1249 # script survive, because the user_ns is updated with them. However,
1250 # calling functions defined in the script that use other things from
1250 # calling functions defined in the script that use other things from
1251 # the script will fail, because the function's closure had references
1251 # the script will fail, because the function's closure had references
1252 # to the original objects, which are now all None. So we must protect
1252 # to the original objects, which are now all None. So we must protect
1253 # these modules from deletion by keeping a cache.
1253 # these modules from deletion by keeping a cache.
1254 #
1254 #
1255 # To avoid keeping stale modules around (we only need the one from the
1255 # To avoid keeping stale modules around (we only need the one from the
1256 # last run), we use a dict keyed with the full path to the script, so
1256 # last run), we use a dict keyed with the full path to the script, so
1257 # only the last version of the module is held in the cache. Note,
1257 # only the last version of the module is held in the cache. Note,
1258 # however, that we must cache the module *namespace contents* (their
1258 # however, that we must cache the module *namespace contents* (their
1259 # __dict__). Because if we try to cache the actual modules, old ones
1259 # __dict__). Because if we try to cache the actual modules, old ones
1260 # (uncached) could be destroyed while still holding references (such as
1260 # (uncached) could be destroyed while still holding references (such as
1261 # those held by GUI objects that tend to be long-lived)>
1261 # those held by GUI objects that tend to be long-lived)>
1262 #
1262 #
1263 # The %reset command will flush this cache. See the cache_main_mod()
1263 # The %reset command will flush this cache. See the cache_main_mod()
1264 # and clear_main_mod_cache() methods for details on use.
1264 # and clear_main_mod_cache() methods for details on use.
1265
1265
1266 # This is the cache used for 'main' namespaces
1266 # This is the cache used for 'main' namespaces
1267 self._main_mod_cache = {}
1267 self._main_mod_cache = {}
1268
1268
1269 # A table holding all the namespaces IPython deals with, so that
1269 # A table holding all the namespaces IPython deals with, so that
1270 # introspection facilities can search easily.
1270 # introspection facilities can search easily.
1271 self.ns_table = {'user_global':self.user_module.__dict__,
1271 self.ns_table = {'user_global':self.user_module.__dict__,
1272 'user_local':self.user_ns,
1272 'user_local':self.user_ns,
1273 'builtin':builtin_mod.__dict__
1273 'builtin':builtin_mod.__dict__
1274 }
1274 }
1275
1275
1276 @property
1276 @property
1277 def user_global_ns(self):
1277 def user_global_ns(self):
1278 return self.user_module.__dict__
1278 return self.user_module.__dict__
1279
1279
1280 def prepare_user_module(self, user_module=None, user_ns=None):
1280 def prepare_user_module(self, user_module=None, user_ns=None):
1281 """Prepare the module and namespace in which user code will be run.
1281 """Prepare the module and namespace in which user code will be run.
1282
1282
1283 When IPython is started normally, both parameters are None: a new module
1283 When IPython is started normally, both parameters are None: a new module
1284 is created automatically, and its __dict__ used as the namespace.
1284 is created automatically, and its __dict__ used as the namespace.
1285
1285
1286 If only user_module is provided, its __dict__ is used as the namespace.
1286 If only user_module is provided, its __dict__ is used as the namespace.
1287 If only user_ns is provided, a dummy module is created, and user_ns
1287 If only user_ns is provided, a dummy module is created, and user_ns
1288 becomes the global namespace. If both are provided (as they may be
1288 becomes the global namespace. If both are provided (as they may be
1289 when embedding), user_ns is the local namespace, and user_module
1289 when embedding), user_ns is the local namespace, and user_module
1290 provides the global namespace.
1290 provides the global namespace.
1291
1291
1292 Parameters
1292 Parameters
1293 ----------
1293 ----------
1294 user_module : module, optional
1294 user_module : module, optional
1295 The current user module in which IPython is being run. If None,
1295 The current user module in which IPython is being run. If None,
1296 a clean module will be created.
1296 a clean module will be created.
1297 user_ns : dict, optional
1297 user_ns : dict, optional
1298 A namespace in which to run interactive commands.
1298 A namespace in which to run interactive commands.
1299
1299
1300 Returns
1300 Returns
1301 -------
1301 -------
1302 A tuple of user_module and user_ns, each properly initialised.
1302 A tuple of user_module and user_ns, each properly initialised.
1303 """
1303 """
1304 if user_module is None and user_ns is not None:
1304 if user_module is None and user_ns is not None:
1305 user_ns.setdefault("__name__", "__main__")
1305 user_ns.setdefault("__name__", "__main__")
1306 user_module = DummyMod()
1306 user_module = DummyMod()
1307 user_module.__dict__ = user_ns
1307 user_module.__dict__ = user_ns
1308
1308
1309 if user_module is None:
1309 if user_module is None:
1310 user_module = types.ModuleType("__main__",
1310 user_module = types.ModuleType("__main__",
1311 doc="Automatically created module for IPython interactive environment")
1311 doc="Automatically created module for IPython interactive environment")
1312
1312
1313 # We must ensure that __builtin__ (without the final 's') is always
1313 # We must ensure that __builtin__ (without the final 's') is always
1314 # available and pointing to the __builtin__ *module*. For more details:
1314 # available and pointing to the __builtin__ *module*. For more details:
1315 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1315 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1316 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1316 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1317 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1317 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1318
1318
1319 if user_ns is None:
1319 if user_ns is None:
1320 user_ns = user_module.__dict__
1320 user_ns = user_module.__dict__
1321
1321
1322 return user_module, user_ns
1322 return user_module, user_ns
1323
1323
1324 def init_sys_modules(self):
1324 def init_sys_modules(self):
1325 # We need to insert into sys.modules something that looks like a
1325 # We need to insert into sys.modules something that looks like a
1326 # module but which accesses the IPython namespace, for shelve and
1326 # module but which accesses the IPython namespace, for shelve and
1327 # pickle to work interactively. Normally they rely on getting
1327 # pickle to work interactively. Normally they rely on getting
1328 # everything out of __main__, but for embedding purposes each IPython
1328 # everything out of __main__, but for embedding purposes each IPython
1329 # instance has its own private namespace, so we can't go shoving
1329 # instance has its own private namespace, so we can't go shoving
1330 # everything into __main__.
1330 # everything into __main__.
1331
1331
1332 # note, however, that we should only do this for non-embedded
1332 # note, however, that we should only do this for non-embedded
1333 # ipythons, which really mimic the __main__.__dict__ with their own
1333 # ipythons, which really mimic the __main__.__dict__ with their own
1334 # namespace. Embedded instances, on the other hand, should not do
1334 # namespace. Embedded instances, on the other hand, should not do
1335 # this because they need to manage the user local/global namespaces
1335 # this because they need to manage the user local/global namespaces
1336 # only, but they live within a 'normal' __main__ (meaning, they
1336 # only, but they live within a 'normal' __main__ (meaning, they
1337 # shouldn't overtake the execution environment of the script they're
1337 # shouldn't overtake the execution environment of the script they're
1338 # embedded in).
1338 # embedded in).
1339
1339
1340 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1340 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1341 main_name = self.user_module.__name__
1341 main_name = self.user_module.__name__
1342 sys.modules[main_name] = self.user_module
1342 sys.modules[main_name] = self.user_module
1343
1343
1344 def init_user_ns(self):
1344 def init_user_ns(self):
1345 """Initialize all user-visible namespaces to their minimum defaults.
1345 """Initialize all user-visible namespaces to their minimum defaults.
1346
1346
1347 Certain history lists are also initialized here, as they effectively
1347 Certain history lists are also initialized here, as they effectively
1348 act as user namespaces.
1348 act as user namespaces.
1349
1349
1350 Notes
1350 Notes
1351 -----
1351 -----
1352 All data structures here are only filled in, they are NOT reset by this
1352 All data structures here are only filled in, they are NOT reset by this
1353 method. If they were not empty before, data will simply be added to
1353 method. If they were not empty before, data will simply be added to
1354 them.
1354 them.
1355 """
1355 """
1356 # This function works in two parts: first we put a few things in
1356 # This function works in two parts: first we put a few things in
1357 # user_ns, and we sync that contents into user_ns_hidden so that these
1357 # user_ns, and we sync that contents into user_ns_hidden so that these
1358 # initial variables aren't shown by %who. After the sync, we add the
1358 # initial variables aren't shown by %who. After the sync, we add the
1359 # rest of what we *do* want the user to see with %who even on a new
1359 # rest of what we *do* want the user to see with %who even on a new
1360 # session (probably nothing, so they really only see their own stuff)
1360 # session (probably nothing, so they really only see their own stuff)
1361
1361
1362 # The user dict must *always* have a __builtin__ reference to the
1362 # The user dict must *always* have a __builtin__ reference to the
1363 # Python standard __builtin__ namespace, which must be imported.
1363 # Python standard __builtin__ namespace, which must be imported.
1364 # This is so that certain operations in prompt evaluation can be
1364 # This is so that certain operations in prompt evaluation can be
1365 # reliably executed with builtins. Note that we can NOT use
1365 # reliably executed with builtins. Note that we can NOT use
1366 # __builtins__ (note the 's'), because that can either be a dict or a
1366 # __builtins__ (note the 's'), because that can either be a dict or a
1367 # module, and can even mutate at runtime, depending on the context
1367 # module, and can even mutate at runtime, depending on the context
1368 # (Python makes no guarantees on it). In contrast, __builtin__ is
1368 # (Python makes no guarantees on it). In contrast, __builtin__ is
1369 # always a module object, though it must be explicitly imported.
1369 # always a module object, though it must be explicitly imported.
1370
1370
1371 # For more details:
1371 # For more details:
1372 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1372 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1373 ns = {}
1373 ns = {}
1374
1374
1375 # make global variables for user access to the histories
1375 # make global variables for user access to the histories
1376 ns['_ih'] = self.history_manager.input_hist_parsed
1376 ns['_ih'] = self.history_manager.input_hist_parsed
1377 ns['_oh'] = self.history_manager.output_hist
1377 ns['_oh'] = self.history_manager.output_hist
1378 ns['_dh'] = self.history_manager.dir_hist
1378 ns['_dh'] = self.history_manager.dir_hist
1379
1379
1380 # user aliases to input and output histories. These shouldn't show up
1380 # user aliases to input and output histories. These shouldn't show up
1381 # in %who, as they can have very large reprs.
1381 # in %who, as they can have very large reprs.
1382 ns['In'] = self.history_manager.input_hist_parsed
1382 ns['In'] = self.history_manager.input_hist_parsed
1383 ns['Out'] = self.history_manager.output_hist
1383 ns['Out'] = self.history_manager.output_hist
1384
1384
1385 # Store myself as the public api!!!
1385 # Store myself as the public api!!!
1386 ns['get_ipython'] = self.get_ipython
1386 ns['get_ipython'] = self.get_ipython
1387
1387
1388 ns['exit'] = self.exiter
1388 ns['exit'] = self.exiter
1389 ns['quit'] = self.exiter
1389 ns['quit'] = self.exiter
1390
1390
1391 # Sync what we've added so far to user_ns_hidden so these aren't seen
1391 # Sync what we've added so far to user_ns_hidden so these aren't seen
1392 # by %who
1392 # by %who
1393 self.user_ns_hidden.update(ns)
1393 self.user_ns_hidden.update(ns)
1394
1394
1395 # Anything put into ns now would show up in %who. Think twice before
1395 # Anything put into ns now would show up in %who. Think twice before
1396 # putting anything here, as we really want %who to show the user their
1396 # putting anything here, as we really want %who to show the user their
1397 # stuff, not our variables.
1397 # stuff, not our variables.
1398
1398
1399 # Finally, update the real user's namespace
1399 # Finally, update the real user's namespace
1400 self.user_ns.update(ns)
1400 self.user_ns.update(ns)
1401
1401
1402 @property
1402 @property
1403 def all_ns_refs(self):
1403 def all_ns_refs(self):
1404 """Get a list of references to all the namespace dictionaries in which
1404 """Get a list of references to all the namespace dictionaries in which
1405 IPython might store a user-created object.
1405 IPython might store a user-created object.
1406
1406
1407 Note that this does not include the displayhook, which also caches
1407 Note that this does not include the displayhook, which also caches
1408 objects from the output."""
1408 objects from the output."""
1409 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1409 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1410 [m.__dict__ for m in self._main_mod_cache.values()]
1410 [m.__dict__ for m in self._main_mod_cache.values()]
1411
1411
1412 def reset(self, new_session=True):
1412 def reset(self, new_session=True):
1413 """Clear all internal namespaces, and attempt to release references to
1413 """Clear all internal namespaces, and attempt to release references to
1414 user objects.
1414 user objects.
1415
1415
1416 If new_session is True, a new history session will be opened.
1416 If new_session is True, a new history session will be opened.
1417 """
1417 """
1418 # Clear histories
1418 # Clear histories
1419 self.history_manager.reset(new_session)
1419 self.history_manager.reset(new_session)
1420 # Reset counter used to index all histories
1420 # Reset counter used to index all histories
1421 if new_session:
1421 if new_session:
1422 self.execution_count = 1
1422 self.execution_count = 1
1423
1423
1424 # Reset last execution result
1424 # Reset last execution result
1425 self.last_execution_succeeded = True
1425 self.last_execution_succeeded = True
1426 self.last_execution_result = None
1426 self.last_execution_result = None
1427
1427
1428 # Flush cached output items
1428 # Flush cached output items
1429 if self.displayhook.do_full_cache:
1429 if self.displayhook.do_full_cache:
1430 self.displayhook.flush()
1430 self.displayhook.flush()
1431
1431
1432 # The main execution namespaces must be cleared very carefully,
1432 # The main execution namespaces must be cleared very carefully,
1433 # skipping the deletion of the builtin-related keys, because doing so
1433 # skipping the deletion of the builtin-related keys, because doing so
1434 # would cause errors in many object's __del__ methods.
1434 # would cause errors in many object's __del__ methods.
1435 if self.user_ns is not self.user_global_ns:
1435 if self.user_ns is not self.user_global_ns:
1436 self.user_ns.clear()
1436 self.user_ns.clear()
1437 ns = self.user_global_ns
1437 ns = self.user_global_ns
1438 drop_keys = set(ns.keys())
1438 drop_keys = set(ns.keys())
1439 drop_keys.discard('__builtin__')
1439 drop_keys.discard('__builtin__')
1440 drop_keys.discard('__builtins__')
1440 drop_keys.discard('__builtins__')
1441 drop_keys.discard('__name__')
1441 drop_keys.discard('__name__')
1442 for k in drop_keys:
1442 for k in drop_keys:
1443 del ns[k]
1443 del ns[k]
1444
1444
1445 self.user_ns_hidden.clear()
1445 self.user_ns_hidden.clear()
1446
1446
1447 # Restore the user namespaces to minimal usability
1447 # Restore the user namespaces to minimal usability
1448 self.init_user_ns()
1448 self.init_user_ns()
1449
1449
1450 # Restore the default and user aliases
1450 # Restore the default and user aliases
1451 self.alias_manager.clear_aliases()
1451 self.alias_manager.clear_aliases()
1452 self.alias_manager.init_aliases()
1452 self.alias_manager.init_aliases()
1453
1453
1454 # Now define aliases that only make sense on the terminal, because they
1454 # Now define aliases that only make sense on the terminal, because they
1455 # need direct access to the console in a way that we can't emulate in
1455 # need direct access to the console in a way that we can't emulate in
1456 # GUI or web frontend
1456 # GUI or web frontend
1457 if os.name == 'posix':
1457 if os.name == 'posix':
1458 for cmd in ('clear', 'more', 'less', 'man'):
1458 for cmd in ('clear', 'more', 'less', 'man'):
1459 if cmd not in self.magics_manager.magics['line']:
1459 if cmd not in self.magics_manager.magics['line']:
1460 self.alias_manager.soft_define_alias(cmd, cmd)
1460 self.alias_manager.soft_define_alias(cmd, cmd)
1461
1461
1462 # Flush the private list of module references kept for script
1462 # Flush the private list of module references kept for script
1463 # execution protection
1463 # execution protection
1464 self.clear_main_mod_cache()
1464 self.clear_main_mod_cache()
1465
1465
1466 def del_var(self, varname, by_name=False):
1466 def del_var(self, varname, by_name=False):
1467 """Delete a variable from the various namespaces, so that, as
1467 """Delete a variable from the various namespaces, so that, as
1468 far as possible, we're not keeping any hidden references to it.
1468 far as possible, we're not keeping any hidden references to it.
1469
1469
1470 Parameters
1470 Parameters
1471 ----------
1471 ----------
1472 varname : str
1472 varname : str
1473 The name of the variable to delete.
1473 The name of the variable to delete.
1474 by_name : bool
1474 by_name : bool
1475 If True, delete variables with the given name in each
1475 If True, delete variables with the given name in each
1476 namespace. If False (default), find the variable in the user
1476 namespace. If False (default), find the variable in the user
1477 namespace, and delete references to it.
1477 namespace, and delete references to it.
1478 """
1478 """
1479 if varname in ('__builtin__', '__builtins__'):
1479 if varname in ('__builtin__', '__builtins__'):
1480 raise ValueError("Refusing to delete %s" % varname)
1480 raise ValueError("Refusing to delete %s" % varname)
1481
1481
1482 ns_refs = self.all_ns_refs
1482 ns_refs = self.all_ns_refs
1483
1483
1484 if by_name: # Delete by name
1484 if by_name: # Delete by name
1485 for ns in ns_refs:
1485 for ns in ns_refs:
1486 try:
1486 try:
1487 del ns[varname]
1487 del ns[varname]
1488 except KeyError:
1488 except KeyError:
1489 pass
1489 pass
1490 else: # Delete by object
1490 else: # Delete by object
1491 try:
1491 try:
1492 obj = self.user_ns[varname]
1492 obj = self.user_ns[varname]
1493 except KeyError:
1493 except KeyError as e:
1494 raise NameError("name '%s' is not defined" % varname)
1494 raise NameError("name '%s' is not defined" % varname) from e
1495 # Also check in output history
1495 # Also check in output history
1496 ns_refs.append(self.history_manager.output_hist)
1496 ns_refs.append(self.history_manager.output_hist)
1497 for ns in ns_refs:
1497 for ns in ns_refs:
1498 to_delete = [n for n, o in ns.items() if o is obj]
1498 to_delete = [n for n, o in ns.items() if o is obj]
1499 for name in to_delete:
1499 for name in to_delete:
1500 del ns[name]
1500 del ns[name]
1501
1501
1502 # Ensure it is removed from the last execution result
1502 # Ensure it is removed from the last execution result
1503 if self.last_execution_result.result is obj:
1503 if self.last_execution_result.result is obj:
1504 self.last_execution_result = None
1504 self.last_execution_result = None
1505
1505
1506 # displayhook keeps extra references, but not in a dictionary
1506 # displayhook keeps extra references, but not in a dictionary
1507 for name in ('_', '__', '___'):
1507 for name in ('_', '__', '___'):
1508 if getattr(self.displayhook, name) is obj:
1508 if getattr(self.displayhook, name) is obj:
1509 setattr(self.displayhook, name, None)
1509 setattr(self.displayhook, name, None)
1510
1510
1511 def reset_selective(self, regex=None):
1511 def reset_selective(self, regex=None):
1512 """Clear selective variables from internal namespaces based on a
1512 """Clear selective variables from internal namespaces based on a
1513 specified regular expression.
1513 specified regular expression.
1514
1514
1515 Parameters
1515 Parameters
1516 ----------
1516 ----------
1517 regex : string or compiled pattern, optional
1517 regex : string or compiled pattern, optional
1518 A regular expression pattern that will be used in searching
1518 A regular expression pattern that will be used in searching
1519 variable names in the users namespaces.
1519 variable names in the users namespaces.
1520 """
1520 """
1521 if regex is not None:
1521 if regex is not None:
1522 try:
1522 try:
1523 m = re.compile(regex)
1523 m = re.compile(regex)
1524 except TypeError:
1524 except TypeError as e:
1525 raise TypeError('regex must be a string or compiled pattern')
1525 raise TypeError('regex must be a string or compiled pattern') from e
1526 # Search for keys in each namespace that match the given regex
1526 # Search for keys in each namespace that match the given regex
1527 # If a match is found, delete the key/value pair.
1527 # If a match is found, delete the key/value pair.
1528 for ns in self.all_ns_refs:
1528 for ns in self.all_ns_refs:
1529 for var in ns:
1529 for var in ns:
1530 if m.search(var):
1530 if m.search(var):
1531 del ns[var]
1531 del ns[var]
1532
1532
1533 def push(self, variables, interactive=True):
1533 def push(self, variables, interactive=True):
1534 """Inject a group of variables into the IPython user namespace.
1534 """Inject a group of variables into the IPython user namespace.
1535
1535
1536 Parameters
1536 Parameters
1537 ----------
1537 ----------
1538 variables : dict, str or list/tuple of str
1538 variables : dict, str or list/tuple of str
1539 The variables to inject into the user's namespace. If a dict, a
1539 The variables to inject into the user's namespace. If a dict, a
1540 simple update is done. If a str, the string is assumed to have
1540 simple update is done. If a str, the string is assumed to have
1541 variable names separated by spaces. A list/tuple of str can also
1541 variable names separated by spaces. A list/tuple of str can also
1542 be used to give the variable names. If just the variable names are
1542 be used to give the variable names. If just the variable names are
1543 give (list/tuple/str) then the variable values looked up in the
1543 give (list/tuple/str) then the variable values looked up in the
1544 callers frame.
1544 callers frame.
1545 interactive : bool
1545 interactive : bool
1546 If True (default), the variables will be listed with the ``who``
1546 If True (default), the variables will be listed with the ``who``
1547 magic.
1547 magic.
1548 """
1548 """
1549 vdict = None
1549 vdict = None
1550
1550
1551 # We need a dict of name/value pairs to do namespace updates.
1551 # We need a dict of name/value pairs to do namespace updates.
1552 if isinstance(variables, dict):
1552 if isinstance(variables, dict):
1553 vdict = variables
1553 vdict = variables
1554 elif isinstance(variables, (str, list, tuple)):
1554 elif isinstance(variables, (str, list, tuple)):
1555 if isinstance(variables, str):
1555 if isinstance(variables, str):
1556 vlist = variables.split()
1556 vlist = variables.split()
1557 else:
1557 else:
1558 vlist = variables
1558 vlist = variables
1559 vdict = {}
1559 vdict = {}
1560 cf = sys._getframe(1)
1560 cf = sys._getframe(1)
1561 for name in vlist:
1561 for name in vlist:
1562 try:
1562 try:
1563 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1563 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1564 except:
1564 except:
1565 print('Could not get variable %s from %s' %
1565 print('Could not get variable %s from %s' %
1566 (name,cf.f_code.co_name))
1566 (name,cf.f_code.co_name))
1567 else:
1567 else:
1568 raise ValueError('variables must be a dict/str/list/tuple')
1568 raise ValueError('variables must be a dict/str/list/tuple')
1569
1569
1570 # Propagate variables to user namespace
1570 # Propagate variables to user namespace
1571 self.user_ns.update(vdict)
1571 self.user_ns.update(vdict)
1572
1572
1573 # And configure interactive visibility
1573 # And configure interactive visibility
1574 user_ns_hidden = self.user_ns_hidden
1574 user_ns_hidden = self.user_ns_hidden
1575 if interactive:
1575 if interactive:
1576 for name in vdict:
1576 for name in vdict:
1577 user_ns_hidden.pop(name, None)
1577 user_ns_hidden.pop(name, None)
1578 else:
1578 else:
1579 user_ns_hidden.update(vdict)
1579 user_ns_hidden.update(vdict)
1580
1580
1581 def drop_by_id(self, variables):
1581 def drop_by_id(self, variables):
1582 """Remove a dict of variables from the user namespace, if they are the
1582 """Remove a dict of variables from the user namespace, if they are the
1583 same as the values in the dictionary.
1583 same as the values in the dictionary.
1584
1584
1585 This is intended for use by extensions: variables that they've added can
1585 This is intended for use by extensions: variables that they've added can
1586 be taken back out if they are unloaded, without removing any that the
1586 be taken back out if they are unloaded, without removing any that the
1587 user has overwritten.
1587 user has overwritten.
1588
1588
1589 Parameters
1589 Parameters
1590 ----------
1590 ----------
1591 variables : dict
1591 variables : dict
1592 A dictionary mapping object names (as strings) to the objects.
1592 A dictionary mapping object names (as strings) to the objects.
1593 """
1593 """
1594 for name, obj in variables.items():
1594 for name, obj in variables.items():
1595 if name in self.user_ns and self.user_ns[name] is obj:
1595 if name in self.user_ns and self.user_ns[name] is obj:
1596 del self.user_ns[name]
1596 del self.user_ns[name]
1597 self.user_ns_hidden.pop(name, None)
1597 self.user_ns_hidden.pop(name, None)
1598
1598
1599 #-------------------------------------------------------------------------
1599 #-------------------------------------------------------------------------
1600 # Things related to object introspection
1600 # Things related to object introspection
1601 #-------------------------------------------------------------------------
1601 #-------------------------------------------------------------------------
1602
1602
1603 def _ofind(self, oname, namespaces=None):
1603 def _ofind(self, oname, namespaces=None):
1604 """Find an object in the available namespaces.
1604 """Find an object in the available namespaces.
1605
1605
1606 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1606 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1607
1607
1608 Has special code to detect magic functions.
1608 Has special code to detect magic functions.
1609 """
1609 """
1610 oname = oname.strip()
1610 oname = oname.strip()
1611 if not oname.startswith(ESC_MAGIC) and \
1611 if not oname.startswith(ESC_MAGIC) and \
1612 not oname.startswith(ESC_MAGIC2) and \
1612 not oname.startswith(ESC_MAGIC2) and \
1613 not all(a.isidentifier() for a in oname.split(".")):
1613 not all(a.isidentifier() for a in oname.split(".")):
1614 return {'found': False}
1614 return {'found': False}
1615
1615
1616 if namespaces is None:
1616 if namespaces is None:
1617 # Namespaces to search in:
1617 # Namespaces to search in:
1618 # Put them in a list. The order is important so that we
1618 # Put them in a list. The order is important so that we
1619 # find things in the same order that Python finds them.
1619 # find things in the same order that Python finds them.
1620 namespaces = [ ('Interactive', self.user_ns),
1620 namespaces = [ ('Interactive', self.user_ns),
1621 ('Interactive (global)', self.user_global_ns),
1621 ('Interactive (global)', self.user_global_ns),
1622 ('Python builtin', builtin_mod.__dict__),
1622 ('Python builtin', builtin_mod.__dict__),
1623 ]
1623 ]
1624
1624
1625 ismagic = False
1625 ismagic = False
1626 isalias = False
1626 isalias = False
1627 found = False
1627 found = False
1628 ospace = None
1628 ospace = None
1629 parent = None
1629 parent = None
1630 obj = None
1630 obj = None
1631
1631
1632
1632
1633 # Look for the given name by splitting it in parts. If the head is
1633 # Look for the given name by splitting it in parts. If the head is
1634 # found, then we look for all the remaining parts as members, and only
1634 # found, then we look for all the remaining parts as members, and only
1635 # declare success if we can find them all.
1635 # declare success if we can find them all.
1636 oname_parts = oname.split('.')
1636 oname_parts = oname.split('.')
1637 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1637 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1638 for nsname,ns in namespaces:
1638 for nsname,ns in namespaces:
1639 try:
1639 try:
1640 obj = ns[oname_head]
1640 obj = ns[oname_head]
1641 except KeyError:
1641 except KeyError:
1642 continue
1642 continue
1643 else:
1643 else:
1644 for idx, part in enumerate(oname_rest):
1644 for idx, part in enumerate(oname_rest):
1645 try:
1645 try:
1646 parent = obj
1646 parent = obj
1647 # The last part is looked up in a special way to avoid
1647 # The last part is looked up in a special way to avoid
1648 # descriptor invocation as it may raise or have side
1648 # descriptor invocation as it may raise or have side
1649 # effects.
1649 # effects.
1650 if idx == len(oname_rest) - 1:
1650 if idx == len(oname_rest) - 1:
1651 obj = self._getattr_property(obj, part)
1651 obj = self._getattr_property(obj, part)
1652 else:
1652 else:
1653 obj = getattr(obj, part)
1653 obj = getattr(obj, part)
1654 except:
1654 except:
1655 # Blanket except b/c some badly implemented objects
1655 # Blanket except b/c some badly implemented objects
1656 # allow __getattr__ to raise exceptions other than
1656 # allow __getattr__ to raise exceptions other than
1657 # AttributeError, which then crashes IPython.
1657 # AttributeError, which then crashes IPython.
1658 break
1658 break
1659 else:
1659 else:
1660 # If we finish the for loop (no break), we got all members
1660 # If we finish the for loop (no break), we got all members
1661 found = True
1661 found = True
1662 ospace = nsname
1662 ospace = nsname
1663 break # namespace loop
1663 break # namespace loop
1664
1664
1665 # Try to see if it's magic
1665 # Try to see if it's magic
1666 if not found:
1666 if not found:
1667 obj = None
1667 obj = None
1668 if oname.startswith(ESC_MAGIC2):
1668 if oname.startswith(ESC_MAGIC2):
1669 oname = oname.lstrip(ESC_MAGIC2)
1669 oname = oname.lstrip(ESC_MAGIC2)
1670 obj = self.find_cell_magic(oname)
1670 obj = self.find_cell_magic(oname)
1671 elif oname.startswith(ESC_MAGIC):
1671 elif oname.startswith(ESC_MAGIC):
1672 oname = oname.lstrip(ESC_MAGIC)
1672 oname = oname.lstrip(ESC_MAGIC)
1673 obj = self.find_line_magic(oname)
1673 obj = self.find_line_magic(oname)
1674 else:
1674 else:
1675 # search without prefix, so run? will find %run?
1675 # search without prefix, so run? will find %run?
1676 obj = self.find_line_magic(oname)
1676 obj = self.find_line_magic(oname)
1677 if obj is None:
1677 if obj is None:
1678 obj = self.find_cell_magic(oname)
1678 obj = self.find_cell_magic(oname)
1679 if obj is not None:
1679 if obj is not None:
1680 found = True
1680 found = True
1681 ospace = 'IPython internal'
1681 ospace = 'IPython internal'
1682 ismagic = True
1682 ismagic = True
1683 isalias = isinstance(obj, Alias)
1683 isalias = isinstance(obj, Alias)
1684
1684
1685 # Last try: special-case some literals like '', [], {}, etc:
1685 # Last try: special-case some literals like '', [], {}, etc:
1686 if not found and oname_head in ["''",'""','[]','{}','()']:
1686 if not found and oname_head in ["''",'""','[]','{}','()']:
1687 obj = eval(oname_head)
1687 obj = eval(oname_head)
1688 found = True
1688 found = True
1689 ospace = 'Interactive'
1689 ospace = 'Interactive'
1690
1690
1691 return {
1691 return {
1692 'obj':obj,
1692 'obj':obj,
1693 'found':found,
1693 'found':found,
1694 'parent':parent,
1694 'parent':parent,
1695 'ismagic':ismagic,
1695 'ismagic':ismagic,
1696 'isalias':isalias,
1696 'isalias':isalias,
1697 'namespace':ospace
1697 'namespace':ospace
1698 }
1698 }
1699
1699
1700 @staticmethod
1700 @staticmethod
1701 def _getattr_property(obj, attrname):
1701 def _getattr_property(obj, attrname):
1702 """Property-aware getattr to use in object finding.
1702 """Property-aware getattr to use in object finding.
1703
1703
1704 If attrname represents a property, return it unevaluated (in case it has
1704 If attrname represents a property, return it unevaluated (in case it has
1705 side effects or raises an error.
1705 side effects or raises an error.
1706
1706
1707 """
1707 """
1708 if not isinstance(obj, type):
1708 if not isinstance(obj, type):
1709 try:
1709 try:
1710 # `getattr(type(obj), attrname)` is not guaranteed to return
1710 # `getattr(type(obj), attrname)` is not guaranteed to return
1711 # `obj`, but does so for property:
1711 # `obj`, but does so for property:
1712 #
1712 #
1713 # property.__get__(self, None, cls) -> self
1713 # property.__get__(self, None, cls) -> self
1714 #
1714 #
1715 # The universal alternative is to traverse the mro manually
1715 # The universal alternative is to traverse the mro manually
1716 # searching for attrname in class dicts.
1716 # searching for attrname in class dicts.
1717 attr = getattr(type(obj), attrname)
1717 attr = getattr(type(obj), attrname)
1718 except AttributeError:
1718 except AttributeError:
1719 pass
1719 pass
1720 else:
1720 else:
1721 # This relies on the fact that data descriptors (with both
1721 # This relies on the fact that data descriptors (with both
1722 # __get__ & __set__ magic methods) take precedence over
1722 # __get__ & __set__ magic methods) take precedence over
1723 # instance-level attributes:
1723 # instance-level attributes:
1724 #
1724 #
1725 # class A(object):
1725 # class A(object):
1726 # @property
1726 # @property
1727 # def foobar(self): return 123
1727 # def foobar(self): return 123
1728 # a = A()
1728 # a = A()
1729 # a.__dict__['foobar'] = 345
1729 # a.__dict__['foobar'] = 345
1730 # a.foobar # == 123
1730 # a.foobar # == 123
1731 #
1731 #
1732 # So, a property may be returned right away.
1732 # So, a property may be returned right away.
1733 if isinstance(attr, property):
1733 if isinstance(attr, property):
1734 return attr
1734 return attr
1735
1735
1736 # Nothing helped, fall back.
1736 # Nothing helped, fall back.
1737 return getattr(obj, attrname)
1737 return getattr(obj, attrname)
1738
1738
1739 def _object_find(self, oname, namespaces=None):
1739 def _object_find(self, oname, namespaces=None):
1740 """Find an object and return a struct with info about it."""
1740 """Find an object and return a struct with info about it."""
1741 return Struct(self._ofind(oname, namespaces))
1741 return Struct(self._ofind(oname, namespaces))
1742
1742
1743 def _inspect(self, meth, oname, namespaces=None, **kw):
1743 def _inspect(self, meth, oname, namespaces=None, **kw):
1744 """Generic interface to the inspector system.
1744 """Generic interface to the inspector system.
1745
1745
1746 This function is meant to be called by pdef, pdoc & friends.
1746 This function is meant to be called by pdef, pdoc & friends.
1747 """
1747 """
1748 info = self._object_find(oname, namespaces)
1748 info = self._object_find(oname, namespaces)
1749 docformat = sphinxify if self.sphinxify_docstring else None
1749 docformat = sphinxify if self.sphinxify_docstring else None
1750 if info.found:
1750 if info.found:
1751 pmethod = getattr(self.inspector, meth)
1751 pmethod = getattr(self.inspector, meth)
1752 # TODO: only apply format_screen to the plain/text repr of the mime
1752 # TODO: only apply format_screen to the plain/text repr of the mime
1753 # bundle.
1753 # bundle.
1754 formatter = format_screen if info.ismagic else docformat
1754 formatter = format_screen if info.ismagic else docformat
1755 if meth == 'pdoc':
1755 if meth == 'pdoc':
1756 pmethod(info.obj, oname, formatter)
1756 pmethod(info.obj, oname, formatter)
1757 elif meth == 'pinfo':
1757 elif meth == 'pinfo':
1758 pmethod(info.obj, oname, formatter, info,
1758 pmethod(info.obj, oname, formatter, info,
1759 enable_html_pager=self.enable_html_pager, **kw)
1759 enable_html_pager=self.enable_html_pager, **kw)
1760 else:
1760 else:
1761 pmethod(info.obj, oname)
1761 pmethod(info.obj, oname)
1762 else:
1762 else:
1763 print('Object `%s` not found.' % oname)
1763 print('Object `%s` not found.' % oname)
1764 return 'not found' # so callers can take other action
1764 return 'not found' # so callers can take other action
1765
1765
1766 def object_inspect(self, oname, detail_level=0):
1766 def object_inspect(self, oname, detail_level=0):
1767 """Get object info about oname"""
1767 """Get object info about oname"""
1768 with self.builtin_trap:
1768 with self.builtin_trap:
1769 info = self._object_find(oname)
1769 info = self._object_find(oname)
1770 if info.found:
1770 if info.found:
1771 return self.inspector.info(info.obj, oname, info=info,
1771 return self.inspector.info(info.obj, oname, info=info,
1772 detail_level=detail_level
1772 detail_level=detail_level
1773 )
1773 )
1774 else:
1774 else:
1775 return oinspect.object_info(name=oname, found=False)
1775 return oinspect.object_info(name=oname, found=False)
1776
1776
1777 def object_inspect_text(self, oname, detail_level=0):
1777 def object_inspect_text(self, oname, detail_level=0):
1778 """Get object info as formatted text"""
1778 """Get object info as formatted text"""
1779 return self.object_inspect_mime(oname, detail_level)['text/plain']
1779 return self.object_inspect_mime(oname, detail_level)['text/plain']
1780
1780
1781 def object_inspect_mime(self, oname, detail_level=0):
1781 def object_inspect_mime(self, oname, detail_level=0):
1782 """Get object info as a mimebundle of formatted representations.
1782 """Get object info as a mimebundle of formatted representations.
1783
1783
1784 A mimebundle is a dictionary, keyed by mime-type.
1784 A mimebundle is a dictionary, keyed by mime-type.
1785 It must always have the key `'text/plain'`.
1785 It must always have the key `'text/plain'`.
1786 """
1786 """
1787 with self.builtin_trap:
1787 with self.builtin_trap:
1788 info = self._object_find(oname)
1788 info = self._object_find(oname)
1789 if info.found:
1789 if info.found:
1790 return self.inspector._get_info(info.obj, oname, info=info,
1790 return self.inspector._get_info(info.obj, oname, info=info,
1791 detail_level=detail_level
1791 detail_level=detail_level
1792 )
1792 )
1793 else:
1793 else:
1794 raise KeyError(oname)
1794 raise KeyError(oname)
1795
1795
1796 #-------------------------------------------------------------------------
1796 #-------------------------------------------------------------------------
1797 # Things related to history management
1797 # Things related to history management
1798 #-------------------------------------------------------------------------
1798 #-------------------------------------------------------------------------
1799
1799
1800 def init_history(self):
1800 def init_history(self):
1801 """Sets up the command history, and starts regular autosaves."""
1801 """Sets up the command history, and starts regular autosaves."""
1802 self.history_manager = HistoryManager(shell=self, parent=self)
1802 self.history_manager = HistoryManager(shell=self, parent=self)
1803 self.configurables.append(self.history_manager)
1803 self.configurables.append(self.history_manager)
1804
1804
1805 #-------------------------------------------------------------------------
1805 #-------------------------------------------------------------------------
1806 # Things related to exception handling and tracebacks (not debugging)
1806 # Things related to exception handling and tracebacks (not debugging)
1807 #-------------------------------------------------------------------------
1807 #-------------------------------------------------------------------------
1808
1808
1809 debugger_cls = Pdb
1809 debugger_cls = Pdb
1810
1810
1811 def init_traceback_handlers(self, custom_exceptions):
1811 def init_traceback_handlers(self, custom_exceptions):
1812 # Syntax error handler.
1812 # Syntax error handler.
1813 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1813 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1814
1814
1815 # The interactive one is initialized with an offset, meaning we always
1815 # The interactive one is initialized with an offset, meaning we always
1816 # want to remove the topmost item in the traceback, which is our own
1816 # want to remove the topmost item in the traceback, which is our own
1817 # internal code. Valid modes: ['Plain','Context','Verbose','Minimal']
1817 # internal code. Valid modes: ['Plain','Context','Verbose','Minimal']
1818 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1818 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1819 color_scheme='NoColor',
1819 color_scheme='NoColor',
1820 tb_offset = 1,
1820 tb_offset = 1,
1821 check_cache=check_linecache_ipython,
1821 check_cache=check_linecache_ipython,
1822 debugger_cls=self.debugger_cls, parent=self)
1822 debugger_cls=self.debugger_cls, parent=self)
1823
1823
1824 # The instance will store a pointer to the system-wide exception hook,
1824 # The instance will store a pointer to the system-wide exception hook,
1825 # so that runtime code (such as magics) can access it. This is because
1825 # so that runtime code (such as magics) can access it. This is because
1826 # during the read-eval loop, it may get temporarily overwritten.
1826 # during the read-eval loop, it may get temporarily overwritten.
1827 self.sys_excepthook = sys.excepthook
1827 self.sys_excepthook = sys.excepthook
1828
1828
1829 # and add any custom exception handlers the user may have specified
1829 # and add any custom exception handlers the user may have specified
1830 self.set_custom_exc(*custom_exceptions)
1830 self.set_custom_exc(*custom_exceptions)
1831
1831
1832 # Set the exception mode
1832 # Set the exception mode
1833 self.InteractiveTB.set_mode(mode=self.xmode)
1833 self.InteractiveTB.set_mode(mode=self.xmode)
1834
1834
1835 def set_custom_exc(self, exc_tuple, handler):
1835 def set_custom_exc(self, exc_tuple, handler):
1836 """set_custom_exc(exc_tuple, handler)
1836 """set_custom_exc(exc_tuple, handler)
1837
1837
1838 Set a custom exception handler, which will be called if any of the
1838 Set a custom exception handler, which will be called if any of the
1839 exceptions in exc_tuple occur in the mainloop (specifically, in the
1839 exceptions in exc_tuple occur in the mainloop (specifically, in the
1840 run_code() method).
1840 run_code() method).
1841
1841
1842 Parameters
1842 Parameters
1843 ----------
1843 ----------
1844
1844
1845 exc_tuple : tuple of exception classes
1845 exc_tuple : tuple of exception classes
1846 A *tuple* of exception classes, for which to call the defined
1846 A *tuple* of exception classes, for which to call the defined
1847 handler. It is very important that you use a tuple, and NOT A
1847 handler. It is very important that you use a tuple, and NOT A
1848 LIST here, because of the way Python's except statement works. If
1848 LIST here, because of the way Python's except statement works. If
1849 you only want to trap a single exception, use a singleton tuple::
1849 you only want to trap a single exception, use a singleton tuple::
1850
1850
1851 exc_tuple == (MyCustomException,)
1851 exc_tuple == (MyCustomException,)
1852
1852
1853 handler : callable
1853 handler : callable
1854 handler must have the following signature::
1854 handler must have the following signature::
1855
1855
1856 def my_handler(self, etype, value, tb, tb_offset=None):
1856 def my_handler(self, etype, value, tb, tb_offset=None):
1857 ...
1857 ...
1858 return structured_traceback
1858 return structured_traceback
1859
1859
1860 Your handler must return a structured traceback (a list of strings),
1860 Your handler must return a structured traceback (a list of strings),
1861 or None.
1861 or None.
1862
1862
1863 This will be made into an instance method (via types.MethodType)
1863 This will be made into an instance method (via types.MethodType)
1864 of IPython itself, and it will be called if any of the exceptions
1864 of IPython itself, and it will be called if any of the exceptions
1865 listed in the exc_tuple are caught. If the handler is None, an
1865 listed in the exc_tuple are caught. If the handler is None, an
1866 internal basic one is used, which just prints basic info.
1866 internal basic one is used, which just prints basic info.
1867
1867
1868 To protect IPython from crashes, if your handler ever raises an
1868 To protect IPython from crashes, if your handler ever raises an
1869 exception or returns an invalid result, it will be immediately
1869 exception or returns an invalid result, it will be immediately
1870 disabled.
1870 disabled.
1871
1871
1872 WARNING: by putting in your own exception handler into IPython's main
1872 WARNING: by putting in your own exception handler into IPython's main
1873 execution loop, you run a very good chance of nasty crashes. This
1873 execution loop, you run a very good chance of nasty crashes. This
1874 facility should only be used if you really know what you are doing."""
1874 facility should only be used if you really know what you are doing."""
1875 if not isinstance(exc_tuple, tuple):
1875 if not isinstance(exc_tuple, tuple):
1876 raise TypeError("The custom exceptions must be given as a tuple.")
1876 raise TypeError("The custom exceptions must be given as a tuple.")
1877
1877
1878 def dummy_handler(self, etype, value, tb, tb_offset=None):
1878 def dummy_handler(self, etype, value, tb, tb_offset=None):
1879 print('*** Simple custom exception handler ***')
1879 print('*** Simple custom exception handler ***')
1880 print('Exception type :', etype)
1880 print('Exception type :', etype)
1881 print('Exception value:', value)
1881 print('Exception value:', value)
1882 print('Traceback :', tb)
1882 print('Traceback :', tb)
1883
1883
1884 def validate_stb(stb):
1884 def validate_stb(stb):
1885 """validate structured traceback return type
1885 """validate structured traceback return type
1886
1886
1887 return type of CustomTB *should* be a list of strings, but allow
1887 return type of CustomTB *should* be a list of strings, but allow
1888 single strings or None, which are harmless.
1888 single strings or None, which are harmless.
1889
1889
1890 This function will *always* return a list of strings,
1890 This function will *always* return a list of strings,
1891 and will raise a TypeError if stb is inappropriate.
1891 and will raise a TypeError if stb is inappropriate.
1892 """
1892 """
1893 msg = "CustomTB must return list of strings, not %r" % stb
1893 msg = "CustomTB must return list of strings, not %r" % stb
1894 if stb is None:
1894 if stb is None:
1895 return []
1895 return []
1896 elif isinstance(stb, str):
1896 elif isinstance(stb, str):
1897 return [stb]
1897 return [stb]
1898 elif not isinstance(stb, list):
1898 elif not isinstance(stb, list):
1899 raise TypeError(msg)
1899 raise TypeError(msg)
1900 # it's a list
1900 # it's a list
1901 for line in stb:
1901 for line in stb:
1902 # check every element
1902 # check every element
1903 if not isinstance(line, str):
1903 if not isinstance(line, str):
1904 raise TypeError(msg)
1904 raise TypeError(msg)
1905 return stb
1905 return stb
1906
1906
1907 if handler is None:
1907 if handler is None:
1908 wrapped = dummy_handler
1908 wrapped = dummy_handler
1909 else:
1909 else:
1910 def wrapped(self,etype,value,tb,tb_offset=None):
1910 def wrapped(self,etype,value,tb,tb_offset=None):
1911 """wrap CustomTB handler, to protect IPython from user code
1911 """wrap CustomTB handler, to protect IPython from user code
1912
1912
1913 This makes it harder (but not impossible) for custom exception
1913 This makes it harder (but not impossible) for custom exception
1914 handlers to crash IPython.
1914 handlers to crash IPython.
1915 """
1915 """
1916 try:
1916 try:
1917 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1917 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1918 return validate_stb(stb)
1918 return validate_stb(stb)
1919 except:
1919 except:
1920 # clear custom handler immediately
1920 # clear custom handler immediately
1921 self.set_custom_exc((), None)
1921 self.set_custom_exc((), None)
1922 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1922 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1923 # show the exception in handler first
1923 # show the exception in handler first
1924 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1924 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1925 print(self.InteractiveTB.stb2text(stb))
1925 print(self.InteractiveTB.stb2text(stb))
1926 print("The original exception:")
1926 print("The original exception:")
1927 stb = self.InteractiveTB.structured_traceback(
1927 stb = self.InteractiveTB.structured_traceback(
1928 (etype,value,tb), tb_offset=tb_offset
1928 (etype,value,tb), tb_offset=tb_offset
1929 )
1929 )
1930 return stb
1930 return stb
1931
1931
1932 self.CustomTB = types.MethodType(wrapped,self)
1932 self.CustomTB = types.MethodType(wrapped,self)
1933 self.custom_exceptions = exc_tuple
1933 self.custom_exceptions = exc_tuple
1934
1934
1935 def excepthook(self, etype, value, tb):
1935 def excepthook(self, etype, value, tb):
1936 """One more defense for GUI apps that call sys.excepthook.
1936 """One more defense for GUI apps that call sys.excepthook.
1937
1937
1938 GUI frameworks like wxPython trap exceptions and call
1938 GUI frameworks like wxPython trap exceptions and call
1939 sys.excepthook themselves. I guess this is a feature that
1939 sys.excepthook themselves. I guess this is a feature that
1940 enables them to keep running after exceptions that would
1940 enables them to keep running after exceptions that would
1941 otherwise kill their mainloop. This is a bother for IPython
1941 otherwise kill their mainloop. This is a bother for IPython
1942 which excepts to catch all of the program exceptions with a try:
1942 which excepts to catch all of the program exceptions with a try:
1943 except: statement.
1943 except: statement.
1944
1944
1945 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1945 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1946 any app directly invokes sys.excepthook, it will look to the user like
1946 any app directly invokes sys.excepthook, it will look to the user like
1947 IPython crashed. In order to work around this, we can disable the
1947 IPython crashed. In order to work around this, we can disable the
1948 CrashHandler and replace it with this excepthook instead, which prints a
1948 CrashHandler and replace it with this excepthook instead, which prints a
1949 regular traceback using our InteractiveTB. In this fashion, apps which
1949 regular traceback using our InteractiveTB. In this fashion, apps which
1950 call sys.excepthook will generate a regular-looking exception from
1950 call sys.excepthook will generate a regular-looking exception from
1951 IPython, and the CrashHandler will only be triggered by real IPython
1951 IPython, and the CrashHandler will only be triggered by real IPython
1952 crashes.
1952 crashes.
1953
1953
1954 This hook should be used sparingly, only in places which are not likely
1954 This hook should be used sparingly, only in places which are not likely
1955 to be true IPython errors.
1955 to be true IPython errors.
1956 """
1956 """
1957 self.showtraceback((etype, value, tb), tb_offset=0)
1957 self.showtraceback((etype, value, tb), tb_offset=0)
1958
1958
1959 def _get_exc_info(self, exc_tuple=None):
1959 def _get_exc_info(self, exc_tuple=None):
1960 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1960 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1961
1961
1962 Ensures sys.last_type,value,traceback hold the exc_info we found,
1962 Ensures sys.last_type,value,traceback hold the exc_info we found,
1963 from whichever source.
1963 from whichever source.
1964
1964
1965 raises ValueError if none of these contain any information
1965 raises ValueError if none of these contain any information
1966 """
1966 """
1967 if exc_tuple is None:
1967 if exc_tuple is None:
1968 etype, value, tb = sys.exc_info()
1968 etype, value, tb = sys.exc_info()
1969 else:
1969 else:
1970 etype, value, tb = exc_tuple
1970 etype, value, tb = exc_tuple
1971
1971
1972 if etype is None:
1972 if etype is None:
1973 if hasattr(sys, 'last_type'):
1973 if hasattr(sys, 'last_type'):
1974 etype, value, tb = sys.last_type, sys.last_value, \
1974 etype, value, tb = sys.last_type, sys.last_value, \
1975 sys.last_traceback
1975 sys.last_traceback
1976
1976
1977 if etype is None:
1977 if etype is None:
1978 raise ValueError("No exception to find")
1978 raise ValueError("No exception to find")
1979
1979
1980 # Now store the exception info in sys.last_type etc.
1980 # Now store the exception info in sys.last_type etc.
1981 # WARNING: these variables are somewhat deprecated and not
1981 # WARNING: these variables are somewhat deprecated and not
1982 # necessarily safe to use in a threaded environment, but tools
1982 # necessarily safe to use in a threaded environment, but tools
1983 # like pdb depend on their existence, so let's set them. If we
1983 # like pdb depend on their existence, so let's set them. If we
1984 # find problems in the field, we'll need to revisit their use.
1984 # find problems in the field, we'll need to revisit their use.
1985 sys.last_type = etype
1985 sys.last_type = etype
1986 sys.last_value = value
1986 sys.last_value = value
1987 sys.last_traceback = tb
1987 sys.last_traceback = tb
1988
1988
1989 return etype, value, tb
1989 return etype, value, tb
1990
1990
1991 def show_usage_error(self, exc):
1991 def show_usage_error(self, exc):
1992 """Show a short message for UsageErrors
1992 """Show a short message for UsageErrors
1993
1993
1994 These are special exceptions that shouldn't show a traceback.
1994 These are special exceptions that shouldn't show a traceback.
1995 """
1995 """
1996 print("UsageError: %s" % exc, file=sys.stderr)
1996 print("UsageError: %s" % exc, file=sys.stderr)
1997
1997
1998 def get_exception_only(self, exc_tuple=None):
1998 def get_exception_only(self, exc_tuple=None):
1999 """
1999 """
2000 Return as a string (ending with a newline) the exception that
2000 Return as a string (ending with a newline) the exception that
2001 just occurred, without any traceback.
2001 just occurred, without any traceback.
2002 """
2002 """
2003 etype, value, tb = self._get_exc_info(exc_tuple)
2003 etype, value, tb = self._get_exc_info(exc_tuple)
2004 msg = traceback.format_exception_only(etype, value)
2004 msg = traceback.format_exception_only(etype, value)
2005 return ''.join(msg)
2005 return ''.join(msg)
2006
2006
2007 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
2007 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
2008 exception_only=False, running_compiled_code=False):
2008 exception_only=False, running_compiled_code=False):
2009 """Display the exception that just occurred.
2009 """Display the exception that just occurred.
2010
2010
2011 If nothing is known about the exception, this is the method which
2011 If nothing is known about the exception, this is the method which
2012 should be used throughout the code for presenting user tracebacks,
2012 should be used throughout the code for presenting user tracebacks,
2013 rather than directly invoking the InteractiveTB object.
2013 rather than directly invoking the InteractiveTB object.
2014
2014
2015 A specific showsyntaxerror() also exists, but this method can take
2015 A specific showsyntaxerror() also exists, but this method can take
2016 care of calling it if needed, so unless you are explicitly catching a
2016 care of calling it if needed, so unless you are explicitly catching a
2017 SyntaxError exception, don't try to analyze the stack manually and
2017 SyntaxError exception, don't try to analyze the stack manually and
2018 simply call this method."""
2018 simply call this method."""
2019
2019
2020 try:
2020 try:
2021 try:
2021 try:
2022 etype, value, tb = self._get_exc_info(exc_tuple)
2022 etype, value, tb = self._get_exc_info(exc_tuple)
2023 except ValueError:
2023 except ValueError:
2024 print('No traceback available to show.', file=sys.stderr)
2024 print('No traceback available to show.', file=sys.stderr)
2025 return
2025 return
2026
2026
2027 if issubclass(etype, SyntaxError):
2027 if issubclass(etype, SyntaxError):
2028 # Though this won't be called by syntax errors in the input
2028 # Though this won't be called by syntax errors in the input
2029 # line, there may be SyntaxError cases with imported code.
2029 # line, there may be SyntaxError cases with imported code.
2030 self.showsyntaxerror(filename, running_compiled_code)
2030 self.showsyntaxerror(filename, running_compiled_code)
2031 elif etype is UsageError:
2031 elif etype is UsageError:
2032 self.show_usage_error(value)
2032 self.show_usage_error(value)
2033 else:
2033 else:
2034 if exception_only:
2034 if exception_only:
2035 stb = ['An exception has occurred, use %tb to see '
2035 stb = ['An exception has occurred, use %tb to see '
2036 'the full traceback.\n']
2036 'the full traceback.\n']
2037 stb.extend(self.InteractiveTB.get_exception_only(etype,
2037 stb.extend(self.InteractiveTB.get_exception_only(etype,
2038 value))
2038 value))
2039 else:
2039 else:
2040 try:
2040 try:
2041 # Exception classes can customise their traceback - we
2041 # Exception classes can customise their traceback - we
2042 # use this in IPython.parallel for exceptions occurring
2042 # use this in IPython.parallel for exceptions occurring
2043 # in the engines. This should return a list of strings.
2043 # in the engines. This should return a list of strings.
2044 stb = value._render_traceback_()
2044 stb = value._render_traceback_()
2045 except Exception:
2045 except Exception:
2046 stb = self.InteractiveTB.structured_traceback(etype,
2046 stb = self.InteractiveTB.structured_traceback(etype,
2047 value, tb, tb_offset=tb_offset)
2047 value, tb, tb_offset=tb_offset)
2048
2048
2049 self._showtraceback(etype, value, stb)
2049 self._showtraceback(etype, value, stb)
2050 if self.call_pdb:
2050 if self.call_pdb:
2051 # drop into debugger
2051 # drop into debugger
2052 self.debugger(force=True)
2052 self.debugger(force=True)
2053 return
2053 return
2054
2054
2055 # Actually show the traceback
2055 # Actually show the traceback
2056 self._showtraceback(etype, value, stb)
2056 self._showtraceback(etype, value, stb)
2057
2057
2058 except KeyboardInterrupt:
2058 except KeyboardInterrupt:
2059 print('\n' + self.get_exception_only(), file=sys.stderr)
2059 print('\n' + self.get_exception_only(), file=sys.stderr)
2060
2060
2061 def _showtraceback(self, etype, evalue, stb):
2061 def _showtraceback(self, etype, evalue, stb):
2062 """Actually show a traceback.
2062 """Actually show a traceback.
2063
2063
2064 Subclasses may override this method to put the traceback on a different
2064 Subclasses may override this method to put the traceback on a different
2065 place, like a side channel.
2065 place, like a side channel.
2066 """
2066 """
2067 print(self.InteractiveTB.stb2text(stb))
2067 print(self.InteractiveTB.stb2text(stb))
2068
2068
2069 def showsyntaxerror(self, filename=None, running_compiled_code=False):
2069 def showsyntaxerror(self, filename=None, running_compiled_code=False):
2070 """Display the syntax error that just occurred.
2070 """Display the syntax error that just occurred.
2071
2071
2072 This doesn't display a stack trace because there isn't one.
2072 This doesn't display a stack trace because there isn't one.
2073
2073
2074 If a filename is given, it is stuffed in the exception instead
2074 If a filename is given, it is stuffed in the exception instead
2075 of what was there before (because Python's parser always uses
2075 of what was there before (because Python's parser always uses
2076 "<string>" when reading from a string).
2076 "<string>" when reading from a string).
2077
2077
2078 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
2078 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
2079 longer stack trace will be displayed.
2079 longer stack trace will be displayed.
2080 """
2080 """
2081 etype, value, last_traceback = self._get_exc_info()
2081 etype, value, last_traceback = self._get_exc_info()
2082
2082
2083 if filename and issubclass(etype, SyntaxError):
2083 if filename and issubclass(etype, SyntaxError):
2084 try:
2084 try:
2085 value.filename = filename
2085 value.filename = filename
2086 except:
2086 except:
2087 # Not the format we expect; leave it alone
2087 # Not the format we expect; leave it alone
2088 pass
2088 pass
2089
2089
2090 # If the error occurred when executing compiled code, we should provide full stacktrace.
2090 # If the error occurred when executing compiled code, we should provide full stacktrace.
2091 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
2091 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
2092 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
2092 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
2093 self._showtraceback(etype, value, stb)
2093 self._showtraceback(etype, value, stb)
2094
2094
2095 # This is overridden in TerminalInteractiveShell to show a message about
2095 # This is overridden in TerminalInteractiveShell to show a message about
2096 # the %paste magic.
2096 # the %paste magic.
2097 def showindentationerror(self):
2097 def showindentationerror(self):
2098 """Called by _run_cell when there's an IndentationError in code entered
2098 """Called by _run_cell when there's an IndentationError in code entered
2099 at the prompt.
2099 at the prompt.
2100
2100
2101 This is overridden in TerminalInteractiveShell to show a message about
2101 This is overridden in TerminalInteractiveShell to show a message about
2102 the %paste magic."""
2102 the %paste magic."""
2103 self.showsyntaxerror()
2103 self.showsyntaxerror()
2104
2104
2105 #-------------------------------------------------------------------------
2105 #-------------------------------------------------------------------------
2106 # Things related to readline
2106 # Things related to readline
2107 #-------------------------------------------------------------------------
2107 #-------------------------------------------------------------------------
2108
2108
2109 def init_readline(self):
2109 def init_readline(self):
2110 """DEPRECATED
2110 """DEPRECATED
2111
2111
2112 Moved to terminal subclass, here only to simplify the init logic."""
2112 Moved to terminal subclass, here only to simplify the init logic."""
2113 # Set a number of methods that depend on readline to be no-op
2113 # Set a number of methods that depend on readline to be no-op
2114 warnings.warn('`init_readline` is no-op since IPython 5.0 and is Deprecated',
2114 warnings.warn('`init_readline` is no-op since IPython 5.0 and is Deprecated',
2115 DeprecationWarning, stacklevel=2)
2115 DeprecationWarning, stacklevel=2)
2116 self.set_custom_completer = no_op
2116 self.set_custom_completer = no_op
2117
2117
2118 @skip_doctest
2118 @skip_doctest
2119 def set_next_input(self, s, replace=False):
2119 def set_next_input(self, s, replace=False):
2120 """ Sets the 'default' input string for the next command line.
2120 """ Sets the 'default' input string for the next command line.
2121
2121
2122 Example::
2122 Example::
2123
2123
2124 In [1]: _ip.set_next_input("Hello Word")
2124 In [1]: _ip.set_next_input("Hello Word")
2125 In [2]: Hello Word_ # cursor is here
2125 In [2]: Hello Word_ # cursor is here
2126 """
2126 """
2127 self.rl_next_input = s
2127 self.rl_next_input = s
2128
2128
2129 def _indent_current_str(self):
2129 def _indent_current_str(self):
2130 """return the current level of indentation as a string"""
2130 """return the current level of indentation as a string"""
2131 return self.input_splitter.get_indent_spaces() * ' '
2131 return self.input_splitter.get_indent_spaces() * ' '
2132
2132
2133 #-------------------------------------------------------------------------
2133 #-------------------------------------------------------------------------
2134 # Things related to text completion
2134 # Things related to text completion
2135 #-------------------------------------------------------------------------
2135 #-------------------------------------------------------------------------
2136
2136
2137 def init_completer(self):
2137 def init_completer(self):
2138 """Initialize the completion machinery.
2138 """Initialize the completion machinery.
2139
2139
2140 This creates completion machinery that can be used by client code,
2140 This creates completion machinery that can be used by client code,
2141 either interactively in-process (typically triggered by the readline
2141 either interactively in-process (typically triggered by the readline
2142 library), programmatically (such as in test suites) or out-of-process
2142 library), programmatically (such as in test suites) or out-of-process
2143 (typically over the network by remote frontends).
2143 (typically over the network by remote frontends).
2144 """
2144 """
2145 from IPython.core.completer import IPCompleter
2145 from IPython.core.completer import IPCompleter
2146 from IPython.core.completerlib import (module_completer,
2146 from IPython.core.completerlib import (module_completer,
2147 magic_run_completer, cd_completer, reset_completer)
2147 magic_run_completer, cd_completer, reset_completer)
2148
2148
2149 self.Completer = IPCompleter(shell=self,
2149 self.Completer = IPCompleter(shell=self,
2150 namespace=self.user_ns,
2150 namespace=self.user_ns,
2151 global_namespace=self.user_global_ns,
2151 global_namespace=self.user_global_ns,
2152 parent=self,
2152 parent=self,
2153 )
2153 )
2154 self.configurables.append(self.Completer)
2154 self.configurables.append(self.Completer)
2155
2155
2156 # Add custom completers to the basic ones built into IPCompleter
2156 # Add custom completers to the basic ones built into IPCompleter
2157 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
2157 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
2158 self.strdispatchers['complete_command'] = sdisp
2158 self.strdispatchers['complete_command'] = sdisp
2159 self.Completer.custom_completers = sdisp
2159 self.Completer.custom_completers = sdisp
2160
2160
2161 self.set_hook('complete_command', module_completer, str_key = 'import')
2161 self.set_hook('complete_command', module_completer, str_key = 'import')
2162 self.set_hook('complete_command', module_completer, str_key = 'from')
2162 self.set_hook('complete_command', module_completer, str_key = 'from')
2163 self.set_hook('complete_command', module_completer, str_key = '%aimport')
2163 self.set_hook('complete_command', module_completer, str_key = '%aimport')
2164 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
2164 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
2165 self.set_hook('complete_command', cd_completer, str_key = '%cd')
2165 self.set_hook('complete_command', cd_completer, str_key = '%cd')
2166 self.set_hook('complete_command', reset_completer, str_key = '%reset')
2166 self.set_hook('complete_command', reset_completer, str_key = '%reset')
2167
2167
2168 @skip_doctest
2168 @skip_doctest
2169 def complete(self, text, line=None, cursor_pos=None):
2169 def complete(self, text, line=None, cursor_pos=None):
2170 """Return the completed text and a list of completions.
2170 """Return the completed text and a list of completions.
2171
2171
2172 Parameters
2172 Parameters
2173 ----------
2173 ----------
2174
2174
2175 text : string
2175 text : string
2176 A string of text to be completed on. It can be given as empty and
2176 A string of text to be completed on. It can be given as empty and
2177 instead a line/position pair are given. In this case, the
2177 instead a line/position pair are given. In this case, the
2178 completer itself will split the line like readline does.
2178 completer itself will split the line like readline does.
2179
2179
2180 line : string, optional
2180 line : string, optional
2181 The complete line that text is part of.
2181 The complete line that text is part of.
2182
2182
2183 cursor_pos : int, optional
2183 cursor_pos : int, optional
2184 The position of the cursor on the input line.
2184 The position of the cursor on the input line.
2185
2185
2186 Returns
2186 Returns
2187 -------
2187 -------
2188 text : string
2188 text : string
2189 The actual text that was completed.
2189 The actual text that was completed.
2190
2190
2191 matches : list
2191 matches : list
2192 A sorted list with all possible completions.
2192 A sorted list with all possible completions.
2193
2193
2194 The optional arguments allow the completion to take more context into
2194 The optional arguments allow the completion to take more context into
2195 account, and are part of the low-level completion API.
2195 account, and are part of the low-level completion API.
2196
2196
2197 This is a wrapper around the completion mechanism, similar to what
2197 This is a wrapper around the completion mechanism, similar to what
2198 readline does at the command line when the TAB key is hit. By
2198 readline does at the command line when the TAB key is hit. By
2199 exposing it as a method, it can be used by other non-readline
2199 exposing it as a method, it can be used by other non-readline
2200 environments (such as GUIs) for text completion.
2200 environments (such as GUIs) for text completion.
2201
2201
2202 Simple usage example:
2202 Simple usage example:
2203
2203
2204 In [1]: x = 'hello'
2204 In [1]: x = 'hello'
2205
2205
2206 In [2]: _ip.complete('x.l')
2206 In [2]: _ip.complete('x.l')
2207 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2207 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2208 """
2208 """
2209
2209
2210 # Inject names into __builtin__ so we can complete on the added names.
2210 # Inject names into __builtin__ so we can complete on the added names.
2211 with self.builtin_trap:
2211 with self.builtin_trap:
2212 return self.Completer.complete(text, line, cursor_pos)
2212 return self.Completer.complete(text, line, cursor_pos)
2213
2213
2214 def set_custom_completer(self, completer, pos=0):
2214 def set_custom_completer(self, completer, pos=0):
2215 """Adds a new custom completer function.
2215 """Adds a new custom completer function.
2216
2216
2217 The position argument (defaults to 0) is the index in the completers
2217 The position argument (defaults to 0) is the index in the completers
2218 list where you want the completer to be inserted."""
2218 list where you want the completer to be inserted."""
2219
2219
2220 newcomp = types.MethodType(completer, self.Completer)
2220 newcomp = types.MethodType(completer, self.Completer)
2221 self.Completer.custom_matchers.insert(pos,newcomp)
2221 self.Completer.custom_matchers.insert(pos,newcomp)
2222
2222
2223 def set_completer_frame(self, frame=None):
2223 def set_completer_frame(self, frame=None):
2224 """Set the frame of the completer."""
2224 """Set the frame of the completer."""
2225 if frame:
2225 if frame:
2226 self.Completer.namespace = frame.f_locals
2226 self.Completer.namespace = frame.f_locals
2227 self.Completer.global_namespace = frame.f_globals
2227 self.Completer.global_namespace = frame.f_globals
2228 else:
2228 else:
2229 self.Completer.namespace = self.user_ns
2229 self.Completer.namespace = self.user_ns
2230 self.Completer.global_namespace = self.user_global_ns
2230 self.Completer.global_namespace = self.user_global_ns
2231
2231
2232 #-------------------------------------------------------------------------
2232 #-------------------------------------------------------------------------
2233 # Things related to magics
2233 # Things related to magics
2234 #-------------------------------------------------------------------------
2234 #-------------------------------------------------------------------------
2235
2235
2236 def init_magics(self):
2236 def init_magics(self):
2237 from IPython.core import magics as m
2237 from IPython.core import magics as m
2238 self.magics_manager = magic.MagicsManager(shell=self,
2238 self.magics_manager = magic.MagicsManager(shell=self,
2239 parent=self,
2239 parent=self,
2240 user_magics=m.UserMagics(self))
2240 user_magics=m.UserMagics(self))
2241 self.configurables.append(self.magics_manager)
2241 self.configurables.append(self.magics_manager)
2242
2242
2243 # Expose as public API from the magics manager
2243 # Expose as public API from the magics manager
2244 self.register_magics = self.magics_manager.register
2244 self.register_magics = self.magics_manager.register
2245
2245
2246 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2246 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2247 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2247 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2248 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2248 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2249 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,
2249 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,
2250 m.PylabMagics, m.ScriptMagics,
2250 m.PylabMagics, m.ScriptMagics,
2251 )
2251 )
2252 self.register_magics(m.AsyncMagics)
2252 self.register_magics(m.AsyncMagics)
2253
2253
2254 # Register Magic Aliases
2254 # Register Magic Aliases
2255 mman = self.magics_manager
2255 mman = self.magics_manager
2256 # FIXME: magic aliases should be defined by the Magics classes
2256 # FIXME: magic aliases should be defined by the Magics classes
2257 # or in MagicsManager, not here
2257 # or in MagicsManager, not here
2258 mman.register_alias('ed', 'edit')
2258 mman.register_alias('ed', 'edit')
2259 mman.register_alias('hist', 'history')
2259 mman.register_alias('hist', 'history')
2260 mman.register_alias('rep', 'recall')
2260 mman.register_alias('rep', 'recall')
2261 mman.register_alias('SVG', 'svg', 'cell')
2261 mman.register_alias('SVG', 'svg', 'cell')
2262 mman.register_alias('HTML', 'html', 'cell')
2262 mman.register_alias('HTML', 'html', 'cell')
2263 mman.register_alias('file', 'writefile', 'cell')
2263 mman.register_alias('file', 'writefile', 'cell')
2264
2264
2265 # FIXME: Move the color initialization to the DisplayHook, which
2265 # FIXME: Move the color initialization to the DisplayHook, which
2266 # should be split into a prompt manager and displayhook. We probably
2266 # should be split into a prompt manager and displayhook. We probably
2267 # even need a centralize colors management object.
2267 # even need a centralize colors management object.
2268 self.run_line_magic('colors', self.colors)
2268 self.run_line_magic('colors', self.colors)
2269
2269
2270 # Defined here so that it's included in the documentation
2270 # Defined here so that it's included in the documentation
2271 @functools.wraps(magic.MagicsManager.register_function)
2271 @functools.wraps(magic.MagicsManager.register_function)
2272 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2272 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2273 self.magics_manager.register_function(func,
2273 self.magics_manager.register_function(func,
2274 magic_kind=magic_kind, magic_name=magic_name)
2274 magic_kind=magic_kind, magic_name=magic_name)
2275
2275
2276 def run_line_magic(self, magic_name, line, _stack_depth=1):
2276 def run_line_magic(self, magic_name, line, _stack_depth=1):
2277 """Execute the given line magic.
2277 """Execute the given line magic.
2278
2278
2279 Parameters
2279 Parameters
2280 ----------
2280 ----------
2281 magic_name : str
2281 magic_name : str
2282 Name of the desired magic function, without '%' prefix.
2282 Name of the desired magic function, without '%' prefix.
2283
2283
2284 line : str
2284 line : str
2285 The rest of the input line as a single string.
2285 The rest of the input line as a single string.
2286
2286
2287 _stack_depth : int
2287 _stack_depth : int
2288 If run_line_magic() is called from magic() then _stack_depth=2.
2288 If run_line_magic() is called from magic() then _stack_depth=2.
2289 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2289 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2290 """
2290 """
2291 fn = self.find_line_magic(magic_name)
2291 fn = self.find_line_magic(magic_name)
2292 if fn is None:
2292 if fn is None:
2293 cm = self.find_cell_magic(magic_name)
2293 cm = self.find_cell_magic(magic_name)
2294 etpl = "Line magic function `%%%s` not found%s."
2294 etpl = "Line magic function `%%%s` not found%s."
2295 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2295 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2296 'did you mean that instead?)' % magic_name )
2296 'did you mean that instead?)' % magic_name )
2297 raise UsageError(etpl % (magic_name, extra))
2297 raise UsageError(etpl % (magic_name, extra))
2298 else:
2298 else:
2299 # Note: this is the distance in the stack to the user's frame.
2299 # Note: this is the distance in the stack to the user's frame.
2300 # This will need to be updated if the internal calling logic gets
2300 # This will need to be updated if the internal calling logic gets
2301 # refactored, or else we'll be expanding the wrong variables.
2301 # refactored, or else we'll be expanding the wrong variables.
2302
2302
2303 # Determine stack_depth depending on where run_line_magic() has been called
2303 # Determine stack_depth depending on where run_line_magic() has been called
2304 stack_depth = _stack_depth
2304 stack_depth = _stack_depth
2305 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2305 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2306 # magic has opted out of var_expand
2306 # magic has opted out of var_expand
2307 magic_arg_s = line
2307 magic_arg_s = line
2308 else:
2308 else:
2309 magic_arg_s = self.var_expand(line, stack_depth)
2309 magic_arg_s = self.var_expand(line, stack_depth)
2310 # Put magic args in a list so we can call with f(*a) syntax
2310 # Put magic args in a list so we can call with f(*a) syntax
2311 args = [magic_arg_s]
2311 args = [magic_arg_s]
2312 kwargs = {}
2312 kwargs = {}
2313 # Grab local namespace if we need it:
2313 # Grab local namespace if we need it:
2314 if getattr(fn, "needs_local_scope", False):
2314 if getattr(fn, "needs_local_scope", False):
2315 kwargs['local_ns'] = sys._getframe(stack_depth).f_locals
2315 kwargs['local_ns'] = sys._getframe(stack_depth).f_locals
2316 with self.builtin_trap:
2316 with self.builtin_trap:
2317 result = fn(*args, **kwargs)
2317 result = fn(*args, **kwargs)
2318 return result
2318 return result
2319
2319
2320 def run_cell_magic(self, magic_name, line, cell):
2320 def run_cell_magic(self, magic_name, line, cell):
2321 """Execute the given cell magic.
2321 """Execute the given cell magic.
2322
2322
2323 Parameters
2323 Parameters
2324 ----------
2324 ----------
2325 magic_name : str
2325 magic_name : str
2326 Name of the desired magic function, without '%' prefix.
2326 Name of the desired magic function, without '%' prefix.
2327
2327
2328 line : str
2328 line : str
2329 The rest of the first input line as a single string.
2329 The rest of the first input line as a single string.
2330
2330
2331 cell : str
2331 cell : str
2332 The body of the cell as a (possibly multiline) string.
2332 The body of the cell as a (possibly multiline) string.
2333 """
2333 """
2334 fn = self.find_cell_magic(magic_name)
2334 fn = self.find_cell_magic(magic_name)
2335 if fn is None:
2335 if fn is None:
2336 lm = self.find_line_magic(magic_name)
2336 lm = self.find_line_magic(magic_name)
2337 etpl = "Cell magic `%%{0}` not found{1}."
2337 etpl = "Cell magic `%%{0}` not found{1}."
2338 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2338 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2339 'did you mean that instead?)'.format(magic_name))
2339 'did you mean that instead?)'.format(magic_name))
2340 raise UsageError(etpl.format(magic_name, extra))
2340 raise UsageError(etpl.format(magic_name, extra))
2341 elif cell == '':
2341 elif cell == '':
2342 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2342 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2343 if self.find_line_magic(magic_name) is not None:
2343 if self.find_line_magic(magic_name) is not None:
2344 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2344 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2345 raise UsageError(message)
2345 raise UsageError(message)
2346 else:
2346 else:
2347 # Note: this is the distance in the stack to the user's frame.
2347 # Note: this is the distance in the stack to the user's frame.
2348 # This will need to be updated if the internal calling logic gets
2348 # This will need to be updated if the internal calling logic gets
2349 # refactored, or else we'll be expanding the wrong variables.
2349 # refactored, or else we'll be expanding the wrong variables.
2350 stack_depth = 2
2350 stack_depth = 2
2351 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2351 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2352 # magic has opted out of var_expand
2352 # magic has opted out of var_expand
2353 magic_arg_s = line
2353 magic_arg_s = line
2354 else:
2354 else:
2355 magic_arg_s = self.var_expand(line, stack_depth)
2355 magic_arg_s = self.var_expand(line, stack_depth)
2356 kwargs = {}
2356 kwargs = {}
2357 if getattr(fn, "needs_local_scope", False):
2357 if getattr(fn, "needs_local_scope", False):
2358 kwargs['local_ns'] = self.user_ns
2358 kwargs['local_ns'] = self.user_ns
2359
2359
2360 with self.builtin_trap:
2360 with self.builtin_trap:
2361 args = (magic_arg_s, cell)
2361 args = (magic_arg_s, cell)
2362 result = fn(*args, **kwargs)
2362 result = fn(*args, **kwargs)
2363 return result
2363 return result
2364
2364
2365 def find_line_magic(self, magic_name):
2365 def find_line_magic(self, magic_name):
2366 """Find and return a line magic by name.
2366 """Find and return a line magic by name.
2367
2367
2368 Returns None if the magic isn't found."""
2368 Returns None if the magic isn't found."""
2369 return self.magics_manager.magics['line'].get(magic_name)
2369 return self.magics_manager.magics['line'].get(magic_name)
2370
2370
2371 def find_cell_magic(self, magic_name):
2371 def find_cell_magic(self, magic_name):
2372 """Find and return a cell magic by name.
2372 """Find and return a cell magic by name.
2373
2373
2374 Returns None if the magic isn't found."""
2374 Returns None if the magic isn't found."""
2375 return self.magics_manager.magics['cell'].get(magic_name)
2375 return self.magics_manager.magics['cell'].get(magic_name)
2376
2376
2377 def find_magic(self, magic_name, magic_kind='line'):
2377 def find_magic(self, magic_name, magic_kind='line'):
2378 """Find and return a magic of the given type by name.
2378 """Find and return a magic of the given type by name.
2379
2379
2380 Returns None if the magic isn't found."""
2380 Returns None if the magic isn't found."""
2381 return self.magics_manager.magics[magic_kind].get(magic_name)
2381 return self.magics_manager.magics[magic_kind].get(magic_name)
2382
2382
2383 def magic(self, arg_s):
2383 def magic(self, arg_s):
2384 """DEPRECATED. Use run_line_magic() instead.
2384 """DEPRECATED. Use run_line_magic() instead.
2385
2385
2386 Call a magic function by name.
2386 Call a magic function by name.
2387
2387
2388 Input: a string containing the name of the magic function to call and
2388 Input: a string containing the name of the magic function to call and
2389 any additional arguments to be passed to the magic.
2389 any additional arguments to be passed to the magic.
2390
2390
2391 magic('name -opt foo bar') is equivalent to typing at the ipython
2391 magic('name -opt foo bar') is equivalent to typing at the ipython
2392 prompt:
2392 prompt:
2393
2393
2394 In[1]: %name -opt foo bar
2394 In[1]: %name -opt foo bar
2395
2395
2396 To call a magic without arguments, simply use magic('name').
2396 To call a magic without arguments, simply use magic('name').
2397
2397
2398 This provides a proper Python function to call IPython's magics in any
2398 This provides a proper Python function to call IPython's magics in any
2399 valid Python code you can type at the interpreter, including loops and
2399 valid Python code you can type at the interpreter, including loops and
2400 compound statements.
2400 compound statements.
2401 """
2401 """
2402 # TODO: should we issue a loud deprecation warning here?
2402 # TODO: should we issue a loud deprecation warning here?
2403 magic_name, _, magic_arg_s = arg_s.partition(' ')
2403 magic_name, _, magic_arg_s = arg_s.partition(' ')
2404 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2404 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2405 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2405 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2406
2406
2407 #-------------------------------------------------------------------------
2407 #-------------------------------------------------------------------------
2408 # Things related to macros
2408 # Things related to macros
2409 #-------------------------------------------------------------------------
2409 #-------------------------------------------------------------------------
2410
2410
2411 def define_macro(self, name, themacro):
2411 def define_macro(self, name, themacro):
2412 """Define a new macro
2412 """Define a new macro
2413
2413
2414 Parameters
2414 Parameters
2415 ----------
2415 ----------
2416 name : str
2416 name : str
2417 The name of the macro.
2417 The name of the macro.
2418 themacro : str or Macro
2418 themacro : str or Macro
2419 The action to do upon invoking the macro. If a string, a new
2419 The action to do upon invoking the macro. If a string, a new
2420 Macro object is created by passing the string to it.
2420 Macro object is created by passing the string to it.
2421 """
2421 """
2422
2422
2423 from IPython.core import macro
2423 from IPython.core import macro
2424
2424
2425 if isinstance(themacro, str):
2425 if isinstance(themacro, str):
2426 themacro = macro.Macro(themacro)
2426 themacro = macro.Macro(themacro)
2427 if not isinstance(themacro, macro.Macro):
2427 if not isinstance(themacro, macro.Macro):
2428 raise ValueError('A macro must be a string or a Macro instance.')
2428 raise ValueError('A macro must be a string or a Macro instance.')
2429 self.user_ns[name] = themacro
2429 self.user_ns[name] = themacro
2430
2430
2431 #-------------------------------------------------------------------------
2431 #-------------------------------------------------------------------------
2432 # Things related to the running of system commands
2432 # Things related to the running of system commands
2433 #-------------------------------------------------------------------------
2433 #-------------------------------------------------------------------------
2434
2434
2435 def system_piped(self, cmd):
2435 def system_piped(self, cmd):
2436 """Call the given cmd in a subprocess, piping stdout/err
2436 """Call the given cmd in a subprocess, piping stdout/err
2437
2437
2438 Parameters
2438 Parameters
2439 ----------
2439 ----------
2440 cmd : str
2440 cmd : str
2441 Command to execute (can not end in '&', as background processes are
2441 Command to execute (can not end in '&', as background processes are
2442 not supported. Should not be a command that expects input
2442 not supported. Should not be a command that expects input
2443 other than simple text.
2443 other than simple text.
2444 """
2444 """
2445 if cmd.rstrip().endswith('&'):
2445 if cmd.rstrip().endswith('&'):
2446 # this is *far* from a rigorous test
2446 # this is *far* from a rigorous test
2447 # We do not support backgrounding processes because we either use
2447 # We do not support backgrounding processes because we either use
2448 # pexpect or pipes to read from. Users can always just call
2448 # pexpect or pipes to read from. Users can always just call
2449 # os.system() or use ip.system=ip.system_raw
2449 # os.system() or use ip.system=ip.system_raw
2450 # if they really want a background process.
2450 # if they really want a background process.
2451 raise OSError("Background processes not supported.")
2451 raise OSError("Background processes not supported.")
2452
2452
2453 # we explicitly do NOT return the subprocess status code, because
2453 # we explicitly do NOT return the subprocess status code, because
2454 # a non-None value would trigger :func:`sys.displayhook` calls.
2454 # a non-None value would trigger :func:`sys.displayhook` calls.
2455 # Instead, we store the exit_code in user_ns.
2455 # Instead, we store the exit_code in user_ns.
2456 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2456 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2457
2457
2458 def system_raw(self, cmd):
2458 def system_raw(self, cmd):
2459 """Call the given cmd in a subprocess using os.system on Windows or
2459 """Call the given cmd in a subprocess using os.system on Windows or
2460 subprocess.call using the system shell on other platforms.
2460 subprocess.call using the system shell on other platforms.
2461
2461
2462 Parameters
2462 Parameters
2463 ----------
2463 ----------
2464 cmd : str
2464 cmd : str
2465 Command to execute.
2465 Command to execute.
2466 """
2466 """
2467 cmd = self.var_expand(cmd, depth=1)
2467 cmd = self.var_expand(cmd, depth=1)
2468 # protect os.system from UNC paths on Windows, which it can't handle:
2468 # protect os.system from UNC paths on Windows, which it can't handle:
2469 if sys.platform == 'win32':
2469 if sys.platform == 'win32':
2470 from IPython.utils._process_win32 import AvoidUNCPath
2470 from IPython.utils._process_win32 import AvoidUNCPath
2471 with AvoidUNCPath() as path:
2471 with AvoidUNCPath() as path:
2472 if path is not None:
2472 if path is not None:
2473 cmd = '"pushd %s &&"%s' % (path, cmd)
2473 cmd = '"pushd %s &&"%s' % (path, cmd)
2474 try:
2474 try:
2475 ec = os.system(cmd)
2475 ec = os.system(cmd)
2476 except KeyboardInterrupt:
2476 except KeyboardInterrupt:
2477 print('\n' + self.get_exception_only(), file=sys.stderr)
2477 print('\n' + self.get_exception_only(), file=sys.stderr)
2478 ec = -2
2478 ec = -2
2479 else:
2479 else:
2480 # For posix the result of the subprocess.call() below is an exit
2480 # For posix the result of the subprocess.call() below is an exit
2481 # code, which by convention is zero for success, positive for
2481 # code, which by convention is zero for success, positive for
2482 # program failure. Exit codes above 128 are reserved for signals,
2482 # program failure. Exit codes above 128 are reserved for signals,
2483 # and the formula for converting a signal to an exit code is usually
2483 # and the formula for converting a signal to an exit code is usually
2484 # signal_number+128. To more easily differentiate between exit
2484 # signal_number+128. To more easily differentiate between exit
2485 # codes and signals, ipython uses negative numbers. For instance
2485 # codes and signals, ipython uses negative numbers. For instance
2486 # since control-c is signal 2 but exit code 130, ipython's
2486 # since control-c is signal 2 but exit code 130, ipython's
2487 # _exit_code variable will read -2. Note that some shells like
2487 # _exit_code variable will read -2. Note that some shells like
2488 # csh and fish don't follow sh/bash conventions for exit codes.
2488 # csh and fish don't follow sh/bash conventions for exit codes.
2489 executable = os.environ.get('SHELL', None)
2489 executable = os.environ.get('SHELL', None)
2490 try:
2490 try:
2491 # Use env shell instead of default /bin/sh
2491 # Use env shell instead of default /bin/sh
2492 ec = subprocess.call(cmd, shell=True, executable=executable)
2492 ec = subprocess.call(cmd, shell=True, executable=executable)
2493 except KeyboardInterrupt:
2493 except KeyboardInterrupt:
2494 # intercept control-C; a long traceback is not useful here
2494 # intercept control-C; a long traceback is not useful here
2495 print('\n' + self.get_exception_only(), file=sys.stderr)
2495 print('\n' + self.get_exception_only(), file=sys.stderr)
2496 ec = 130
2496 ec = 130
2497 if ec > 128:
2497 if ec > 128:
2498 ec = -(ec - 128)
2498 ec = -(ec - 128)
2499
2499
2500 # We explicitly do NOT return the subprocess status code, because
2500 # We explicitly do NOT return the subprocess status code, because
2501 # a non-None value would trigger :func:`sys.displayhook` calls.
2501 # a non-None value would trigger :func:`sys.displayhook` calls.
2502 # Instead, we store the exit_code in user_ns. Note the semantics
2502 # Instead, we store the exit_code in user_ns. Note the semantics
2503 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2503 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2504 # but raising SystemExit(_exit_code) will give status 254!
2504 # but raising SystemExit(_exit_code) will give status 254!
2505 self.user_ns['_exit_code'] = ec
2505 self.user_ns['_exit_code'] = ec
2506
2506
2507 # use piped system by default, because it is better behaved
2507 # use piped system by default, because it is better behaved
2508 system = system_piped
2508 system = system_piped
2509
2509
2510 def getoutput(self, cmd, split=True, depth=0):
2510 def getoutput(self, cmd, split=True, depth=0):
2511 """Get output (possibly including stderr) from a subprocess.
2511 """Get output (possibly including stderr) from a subprocess.
2512
2512
2513 Parameters
2513 Parameters
2514 ----------
2514 ----------
2515 cmd : str
2515 cmd : str
2516 Command to execute (can not end in '&', as background processes are
2516 Command to execute (can not end in '&', as background processes are
2517 not supported.
2517 not supported.
2518 split : bool, optional
2518 split : bool, optional
2519 If True, split the output into an IPython SList. Otherwise, an
2519 If True, split the output into an IPython SList. Otherwise, an
2520 IPython LSString is returned. These are objects similar to normal
2520 IPython LSString is returned. These are objects similar to normal
2521 lists and strings, with a few convenience attributes for easier
2521 lists and strings, with a few convenience attributes for easier
2522 manipulation of line-based output. You can use '?' on them for
2522 manipulation of line-based output. You can use '?' on them for
2523 details.
2523 details.
2524 depth : int, optional
2524 depth : int, optional
2525 How many frames above the caller are the local variables which should
2525 How many frames above the caller are the local variables which should
2526 be expanded in the command string? The default (0) assumes that the
2526 be expanded in the command string? The default (0) assumes that the
2527 expansion variables are in the stack frame calling this function.
2527 expansion variables are in the stack frame calling this function.
2528 """
2528 """
2529 if cmd.rstrip().endswith('&'):
2529 if cmd.rstrip().endswith('&'):
2530 # this is *far* from a rigorous test
2530 # this is *far* from a rigorous test
2531 raise OSError("Background processes not supported.")
2531 raise OSError("Background processes not supported.")
2532 out = getoutput(self.var_expand(cmd, depth=depth+1))
2532 out = getoutput(self.var_expand(cmd, depth=depth+1))
2533 if split:
2533 if split:
2534 out = SList(out.splitlines())
2534 out = SList(out.splitlines())
2535 else:
2535 else:
2536 out = LSString(out)
2536 out = LSString(out)
2537 return out
2537 return out
2538
2538
2539 #-------------------------------------------------------------------------
2539 #-------------------------------------------------------------------------
2540 # Things related to aliases
2540 # Things related to aliases
2541 #-------------------------------------------------------------------------
2541 #-------------------------------------------------------------------------
2542
2542
2543 def init_alias(self):
2543 def init_alias(self):
2544 self.alias_manager = AliasManager(shell=self, parent=self)
2544 self.alias_manager = AliasManager(shell=self, parent=self)
2545 self.configurables.append(self.alias_manager)
2545 self.configurables.append(self.alias_manager)
2546
2546
2547 #-------------------------------------------------------------------------
2547 #-------------------------------------------------------------------------
2548 # Things related to extensions
2548 # Things related to extensions
2549 #-------------------------------------------------------------------------
2549 #-------------------------------------------------------------------------
2550
2550
2551 def init_extension_manager(self):
2551 def init_extension_manager(self):
2552 self.extension_manager = ExtensionManager(shell=self, parent=self)
2552 self.extension_manager = ExtensionManager(shell=self, parent=self)
2553 self.configurables.append(self.extension_manager)
2553 self.configurables.append(self.extension_manager)
2554
2554
2555 #-------------------------------------------------------------------------
2555 #-------------------------------------------------------------------------
2556 # Things related to payloads
2556 # Things related to payloads
2557 #-------------------------------------------------------------------------
2557 #-------------------------------------------------------------------------
2558
2558
2559 def init_payload(self):
2559 def init_payload(self):
2560 self.payload_manager = PayloadManager(parent=self)
2560 self.payload_manager = PayloadManager(parent=self)
2561 self.configurables.append(self.payload_manager)
2561 self.configurables.append(self.payload_manager)
2562
2562
2563 #-------------------------------------------------------------------------
2563 #-------------------------------------------------------------------------
2564 # Things related to the prefilter
2564 # Things related to the prefilter
2565 #-------------------------------------------------------------------------
2565 #-------------------------------------------------------------------------
2566
2566
2567 def init_prefilter(self):
2567 def init_prefilter(self):
2568 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2568 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2569 self.configurables.append(self.prefilter_manager)
2569 self.configurables.append(self.prefilter_manager)
2570 # Ultimately this will be refactored in the new interpreter code, but
2570 # Ultimately this will be refactored in the new interpreter code, but
2571 # for now, we should expose the main prefilter method (there's legacy
2571 # for now, we should expose the main prefilter method (there's legacy
2572 # code out there that may rely on this).
2572 # code out there that may rely on this).
2573 self.prefilter = self.prefilter_manager.prefilter_lines
2573 self.prefilter = self.prefilter_manager.prefilter_lines
2574
2574
2575 def auto_rewrite_input(self, cmd):
2575 def auto_rewrite_input(self, cmd):
2576 """Print to the screen the rewritten form of the user's command.
2576 """Print to the screen the rewritten form of the user's command.
2577
2577
2578 This shows visual feedback by rewriting input lines that cause
2578 This shows visual feedback by rewriting input lines that cause
2579 automatic calling to kick in, like::
2579 automatic calling to kick in, like::
2580
2580
2581 /f x
2581 /f x
2582
2582
2583 into::
2583 into::
2584
2584
2585 ------> f(x)
2585 ------> f(x)
2586
2586
2587 after the user's input prompt. This helps the user understand that the
2587 after the user's input prompt. This helps the user understand that the
2588 input line was transformed automatically by IPython.
2588 input line was transformed automatically by IPython.
2589 """
2589 """
2590 if not self.show_rewritten_input:
2590 if not self.show_rewritten_input:
2591 return
2591 return
2592
2592
2593 # This is overridden in TerminalInteractiveShell to use fancy prompts
2593 # This is overridden in TerminalInteractiveShell to use fancy prompts
2594 print("------> " + cmd)
2594 print("------> " + cmd)
2595
2595
2596 #-------------------------------------------------------------------------
2596 #-------------------------------------------------------------------------
2597 # Things related to extracting values/expressions from kernel and user_ns
2597 # Things related to extracting values/expressions from kernel and user_ns
2598 #-------------------------------------------------------------------------
2598 #-------------------------------------------------------------------------
2599
2599
2600 def _user_obj_error(self):
2600 def _user_obj_error(self):
2601 """return simple exception dict
2601 """return simple exception dict
2602
2602
2603 for use in user_expressions
2603 for use in user_expressions
2604 """
2604 """
2605
2605
2606 etype, evalue, tb = self._get_exc_info()
2606 etype, evalue, tb = self._get_exc_info()
2607 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2607 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2608
2608
2609 exc_info = {
2609 exc_info = {
2610 u'status' : 'error',
2610 u'status' : 'error',
2611 u'traceback' : stb,
2611 u'traceback' : stb,
2612 u'ename' : etype.__name__,
2612 u'ename' : etype.__name__,
2613 u'evalue' : py3compat.safe_unicode(evalue),
2613 u'evalue' : py3compat.safe_unicode(evalue),
2614 }
2614 }
2615
2615
2616 return exc_info
2616 return exc_info
2617
2617
2618 def _format_user_obj(self, obj):
2618 def _format_user_obj(self, obj):
2619 """format a user object to display dict
2619 """format a user object to display dict
2620
2620
2621 for use in user_expressions
2621 for use in user_expressions
2622 """
2622 """
2623
2623
2624 data, md = self.display_formatter.format(obj)
2624 data, md = self.display_formatter.format(obj)
2625 value = {
2625 value = {
2626 'status' : 'ok',
2626 'status' : 'ok',
2627 'data' : data,
2627 'data' : data,
2628 'metadata' : md,
2628 'metadata' : md,
2629 }
2629 }
2630 return value
2630 return value
2631
2631
2632 def user_expressions(self, expressions):
2632 def user_expressions(self, expressions):
2633 """Evaluate a dict of expressions in the user's namespace.
2633 """Evaluate a dict of expressions in the user's namespace.
2634
2634
2635 Parameters
2635 Parameters
2636 ----------
2636 ----------
2637 expressions : dict
2637 expressions : dict
2638 A dict with string keys and string values. The expression values
2638 A dict with string keys and string values. The expression values
2639 should be valid Python expressions, each of which will be evaluated
2639 should be valid Python expressions, each of which will be evaluated
2640 in the user namespace.
2640 in the user namespace.
2641
2641
2642 Returns
2642 Returns
2643 -------
2643 -------
2644 A dict, keyed like the input expressions dict, with the rich mime-typed
2644 A dict, keyed like the input expressions dict, with the rich mime-typed
2645 display_data of each value.
2645 display_data of each value.
2646 """
2646 """
2647 out = {}
2647 out = {}
2648 user_ns = self.user_ns
2648 user_ns = self.user_ns
2649 global_ns = self.user_global_ns
2649 global_ns = self.user_global_ns
2650
2650
2651 for key, expr in expressions.items():
2651 for key, expr in expressions.items():
2652 try:
2652 try:
2653 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2653 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2654 except:
2654 except:
2655 value = self._user_obj_error()
2655 value = self._user_obj_error()
2656 out[key] = value
2656 out[key] = value
2657 return out
2657 return out
2658
2658
2659 #-------------------------------------------------------------------------
2659 #-------------------------------------------------------------------------
2660 # Things related to the running of code
2660 # Things related to the running of code
2661 #-------------------------------------------------------------------------
2661 #-------------------------------------------------------------------------
2662
2662
2663 def ex(self, cmd):
2663 def ex(self, cmd):
2664 """Execute a normal python statement in user namespace."""
2664 """Execute a normal python statement in user namespace."""
2665 with self.builtin_trap:
2665 with self.builtin_trap:
2666 exec(cmd, self.user_global_ns, self.user_ns)
2666 exec(cmd, self.user_global_ns, self.user_ns)
2667
2667
2668 def ev(self, expr):
2668 def ev(self, expr):
2669 """Evaluate python expression expr in user namespace.
2669 """Evaluate python expression expr in user namespace.
2670
2670
2671 Returns the result of evaluation
2671 Returns the result of evaluation
2672 """
2672 """
2673 with self.builtin_trap:
2673 with self.builtin_trap:
2674 return eval(expr, self.user_global_ns, self.user_ns)
2674 return eval(expr, self.user_global_ns, self.user_ns)
2675
2675
2676 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2676 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2677 """A safe version of the builtin execfile().
2677 """A safe version of the builtin execfile().
2678
2678
2679 This version will never throw an exception, but instead print
2679 This version will never throw an exception, but instead print
2680 helpful error messages to the screen. This only works on pure
2680 helpful error messages to the screen. This only works on pure
2681 Python files with the .py extension.
2681 Python files with the .py extension.
2682
2682
2683 Parameters
2683 Parameters
2684 ----------
2684 ----------
2685 fname : string
2685 fname : string
2686 The name of the file to be executed.
2686 The name of the file to be executed.
2687 where : tuple
2687 where : tuple
2688 One or two namespaces, passed to execfile() as (globals,locals).
2688 One or two namespaces, passed to execfile() as (globals,locals).
2689 If only one is given, it is passed as both.
2689 If only one is given, it is passed as both.
2690 exit_ignore : bool (False)
2690 exit_ignore : bool (False)
2691 If True, then silence SystemExit for non-zero status (it is always
2691 If True, then silence SystemExit for non-zero status (it is always
2692 silenced for zero status, as it is so common).
2692 silenced for zero status, as it is so common).
2693 raise_exceptions : bool (False)
2693 raise_exceptions : bool (False)
2694 If True raise exceptions everywhere. Meant for testing.
2694 If True raise exceptions everywhere. Meant for testing.
2695 shell_futures : bool (False)
2695 shell_futures : bool (False)
2696 If True, the code will share future statements with the interactive
2696 If True, the code will share future statements with the interactive
2697 shell. It will both be affected by previous __future__ imports, and
2697 shell. It will both be affected by previous __future__ imports, and
2698 any __future__ imports in the code will affect the shell. If False,
2698 any __future__ imports in the code will affect the shell. If False,
2699 __future__ imports are not shared in either direction.
2699 __future__ imports are not shared in either direction.
2700
2700
2701 """
2701 """
2702 fname = os.path.abspath(os.path.expanduser(fname))
2702 fname = os.path.abspath(os.path.expanduser(fname))
2703
2703
2704 # Make sure we can open the file
2704 # Make sure we can open the file
2705 try:
2705 try:
2706 with open(fname):
2706 with open(fname):
2707 pass
2707 pass
2708 except:
2708 except:
2709 warn('Could not open file <%s> for safe execution.' % fname)
2709 warn('Could not open file <%s> for safe execution.' % fname)
2710 return
2710 return
2711
2711
2712 # Find things also in current directory. This is needed to mimic the
2712 # Find things also in current directory. This is needed to mimic the
2713 # behavior of running a script from the system command line, where
2713 # behavior of running a script from the system command line, where
2714 # Python inserts the script's directory into sys.path
2714 # Python inserts the script's directory into sys.path
2715 dname = os.path.dirname(fname)
2715 dname = os.path.dirname(fname)
2716
2716
2717 with prepended_to_syspath(dname), self.builtin_trap:
2717 with prepended_to_syspath(dname), self.builtin_trap:
2718 try:
2718 try:
2719 glob, loc = (where + (None, ))[:2]
2719 glob, loc = (where + (None, ))[:2]
2720 py3compat.execfile(
2720 py3compat.execfile(
2721 fname, glob, loc,
2721 fname, glob, loc,
2722 self.compile if shell_futures else None)
2722 self.compile if shell_futures else None)
2723 except SystemExit as status:
2723 except SystemExit as status:
2724 # If the call was made with 0 or None exit status (sys.exit(0)
2724 # If the call was made with 0 or None exit status (sys.exit(0)
2725 # or sys.exit() ), don't bother showing a traceback, as both of
2725 # or sys.exit() ), don't bother showing a traceback, as both of
2726 # these are considered normal by the OS:
2726 # these are considered normal by the OS:
2727 # > python -c'import sys;sys.exit(0)'; echo $?
2727 # > python -c'import sys;sys.exit(0)'; echo $?
2728 # 0
2728 # 0
2729 # > python -c'import sys;sys.exit()'; echo $?
2729 # > python -c'import sys;sys.exit()'; echo $?
2730 # 0
2730 # 0
2731 # For other exit status, we show the exception unless
2731 # For other exit status, we show the exception unless
2732 # explicitly silenced, but only in short form.
2732 # explicitly silenced, but only in short form.
2733 if status.code:
2733 if status.code:
2734 if raise_exceptions:
2734 if raise_exceptions:
2735 raise
2735 raise
2736 if not exit_ignore:
2736 if not exit_ignore:
2737 self.showtraceback(exception_only=True)
2737 self.showtraceback(exception_only=True)
2738 except:
2738 except:
2739 if raise_exceptions:
2739 if raise_exceptions:
2740 raise
2740 raise
2741 # tb offset is 2 because we wrap execfile
2741 # tb offset is 2 because we wrap execfile
2742 self.showtraceback(tb_offset=2)
2742 self.showtraceback(tb_offset=2)
2743
2743
2744 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2744 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2745 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2745 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2746
2746
2747 Parameters
2747 Parameters
2748 ----------
2748 ----------
2749 fname : str
2749 fname : str
2750 The name of the file to execute. The filename must have a
2750 The name of the file to execute. The filename must have a
2751 .ipy or .ipynb extension.
2751 .ipy or .ipynb extension.
2752 shell_futures : bool (False)
2752 shell_futures : bool (False)
2753 If True, the code will share future statements with the interactive
2753 If True, the code will share future statements with the interactive
2754 shell. It will both be affected by previous __future__ imports, and
2754 shell. It will both be affected by previous __future__ imports, and
2755 any __future__ imports in the code will affect the shell. If False,
2755 any __future__ imports in the code will affect the shell. If False,
2756 __future__ imports are not shared in either direction.
2756 __future__ imports are not shared in either direction.
2757 raise_exceptions : bool (False)
2757 raise_exceptions : bool (False)
2758 If True raise exceptions everywhere. Meant for testing.
2758 If True raise exceptions everywhere. Meant for testing.
2759 """
2759 """
2760 fname = os.path.abspath(os.path.expanduser(fname))
2760 fname = os.path.abspath(os.path.expanduser(fname))
2761
2761
2762 # Make sure we can open the file
2762 # Make sure we can open the file
2763 try:
2763 try:
2764 with open(fname):
2764 with open(fname):
2765 pass
2765 pass
2766 except:
2766 except:
2767 warn('Could not open file <%s> for safe execution.' % fname)
2767 warn('Could not open file <%s> for safe execution.' % fname)
2768 return
2768 return
2769
2769
2770 # Find things also in current directory. This is needed to mimic the
2770 # Find things also in current directory. This is needed to mimic the
2771 # behavior of running a script from the system command line, where
2771 # behavior of running a script from the system command line, where
2772 # Python inserts the script's directory into sys.path
2772 # Python inserts the script's directory into sys.path
2773 dname = os.path.dirname(fname)
2773 dname = os.path.dirname(fname)
2774
2774
2775 def get_cells():
2775 def get_cells():
2776 """generator for sequence of code blocks to run"""
2776 """generator for sequence of code blocks to run"""
2777 if fname.endswith('.ipynb'):
2777 if fname.endswith('.ipynb'):
2778 from nbformat import read
2778 from nbformat import read
2779 nb = read(fname, as_version=4)
2779 nb = read(fname, as_version=4)
2780 if not nb.cells:
2780 if not nb.cells:
2781 return
2781 return
2782 for cell in nb.cells:
2782 for cell in nb.cells:
2783 if cell.cell_type == 'code':
2783 if cell.cell_type == 'code':
2784 yield cell.source
2784 yield cell.source
2785 else:
2785 else:
2786 with open(fname) as f:
2786 with open(fname) as f:
2787 yield f.read()
2787 yield f.read()
2788
2788
2789 with prepended_to_syspath(dname):
2789 with prepended_to_syspath(dname):
2790 try:
2790 try:
2791 for cell in get_cells():
2791 for cell in get_cells():
2792 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2792 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2793 if raise_exceptions:
2793 if raise_exceptions:
2794 result.raise_error()
2794 result.raise_error()
2795 elif not result.success:
2795 elif not result.success:
2796 break
2796 break
2797 except:
2797 except:
2798 if raise_exceptions:
2798 if raise_exceptions:
2799 raise
2799 raise
2800 self.showtraceback()
2800 self.showtraceback()
2801 warn('Unknown failure executing file: <%s>' % fname)
2801 warn('Unknown failure executing file: <%s>' % fname)
2802
2802
2803 def safe_run_module(self, mod_name, where):
2803 def safe_run_module(self, mod_name, where):
2804 """A safe version of runpy.run_module().
2804 """A safe version of runpy.run_module().
2805
2805
2806 This version will never throw an exception, but instead print
2806 This version will never throw an exception, but instead print
2807 helpful error messages to the screen.
2807 helpful error messages to the screen.
2808
2808
2809 `SystemExit` exceptions with status code 0 or None are ignored.
2809 `SystemExit` exceptions with status code 0 or None are ignored.
2810
2810
2811 Parameters
2811 Parameters
2812 ----------
2812 ----------
2813 mod_name : string
2813 mod_name : string
2814 The name of the module to be executed.
2814 The name of the module to be executed.
2815 where : dict
2815 where : dict
2816 The globals namespace.
2816 The globals namespace.
2817 """
2817 """
2818 try:
2818 try:
2819 try:
2819 try:
2820 where.update(
2820 where.update(
2821 runpy.run_module(str(mod_name), run_name="__main__",
2821 runpy.run_module(str(mod_name), run_name="__main__",
2822 alter_sys=True)
2822 alter_sys=True)
2823 )
2823 )
2824 except SystemExit as status:
2824 except SystemExit as status:
2825 if status.code:
2825 if status.code:
2826 raise
2826 raise
2827 except:
2827 except:
2828 self.showtraceback()
2828 self.showtraceback()
2829 warn('Unknown failure executing module: <%s>' % mod_name)
2829 warn('Unknown failure executing module: <%s>' % mod_name)
2830
2830
2831 def run_cell(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2831 def run_cell(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2832 """Run a complete IPython cell.
2832 """Run a complete IPython cell.
2833
2833
2834 Parameters
2834 Parameters
2835 ----------
2835 ----------
2836 raw_cell : str
2836 raw_cell : str
2837 The code (including IPython code such as %magic functions) to run.
2837 The code (including IPython code such as %magic functions) to run.
2838 store_history : bool
2838 store_history : bool
2839 If True, the raw and translated cell will be stored in IPython's
2839 If True, the raw and translated cell will be stored in IPython's
2840 history. For user code calling back into IPython's machinery, this
2840 history. For user code calling back into IPython's machinery, this
2841 should be set to False.
2841 should be set to False.
2842 silent : bool
2842 silent : bool
2843 If True, avoid side-effects, such as implicit displayhooks and
2843 If True, avoid side-effects, such as implicit displayhooks and
2844 and logging. silent=True forces store_history=False.
2844 and logging. silent=True forces store_history=False.
2845 shell_futures : bool
2845 shell_futures : bool
2846 If True, the code will share future statements with the interactive
2846 If True, the code will share future statements with the interactive
2847 shell. It will both be affected by previous __future__ imports, and
2847 shell. It will both be affected by previous __future__ imports, and
2848 any __future__ imports in the code will affect the shell. If False,
2848 any __future__ imports in the code will affect the shell. If False,
2849 __future__ imports are not shared in either direction.
2849 __future__ imports are not shared in either direction.
2850
2850
2851 Returns
2851 Returns
2852 -------
2852 -------
2853 result : :class:`ExecutionResult`
2853 result : :class:`ExecutionResult`
2854 """
2854 """
2855 result = None
2855 result = None
2856 try:
2856 try:
2857 result = self._run_cell(
2857 result = self._run_cell(
2858 raw_cell, store_history, silent, shell_futures)
2858 raw_cell, store_history, silent, shell_futures)
2859 finally:
2859 finally:
2860 self.events.trigger('post_execute')
2860 self.events.trigger('post_execute')
2861 if not silent:
2861 if not silent:
2862 self.events.trigger('post_run_cell', result)
2862 self.events.trigger('post_run_cell', result)
2863 return result
2863 return result
2864
2864
2865 def _run_cell(self, raw_cell:str, store_history:bool, silent:bool, shell_futures:bool):
2865 def _run_cell(self, raw_cell:str, store_history:bool, silent:bool, shell_futures:bool):
2866 """Internal method to run a complete IPython cell."""
2866 """Internal method to run a complete IPython cell."""
2867 coro = self.run_cell_async(
2867 coro = self.run_cell_async(
2868 raw_cell,
2868 raw_cell,
2869 store_history=store_history,
2869 store_history=store_history,
2870 silent=silent,
2870 silent=silent,
2871 shell_futures=shell_futures,
2871 shell_futures=shell_futures,
2872 )
2872 )
2873
2873
2874 # run_cell_async is async, but may not actually need an eventloop.
2874 # run_cell_async is async, but may not actually need an eventloop.
2875 # when this is the case, we want to run it using the pseudo_sync_runner
2875 # when this is the case, we want to run it using the pseudo_sync_runner
2876 # so that code can invoke eventloops (for example via the %run , and
2876 # so that code can invoke eventloops (for example via the %run , and
2877 # `%paste` magic.
2877 # `%paste` magic.
2878 if self.trio_runner:
2878 if self.trio_runner:
2879 runner = self.trio_runner
2879 runner = self.trio_runner
2880 elif self.should_run_async(raw_cell):
2880 elif self.should_run_async(raw_cell):
2881 runner = self.loop_runner
2881 runner = self.loop_runner
2882 else:
2882 else:
2883 runner = _pseudo_sync_runner
2883 runner = _pseudo_sync_runner
2884
2884
2885 try:
2885 try:
2886 return runner(coro)
2886 return runner(coro)
2887 except BaseException as e:
2887 except BaseException as e:
2888 info = ExecutionInfo(raw_cell, store_history, silent, shell_futures)
2888 info = ExecutionInfo(raw_cell, store_history, silent, shell_futures)
2889 result = ExecutionResult(info)
2889 result = ExecutionResult(info)
2890 result.error_in_exec = e
2890 result.error_in_exec = e
2891 self.showtraceback(running_compiled_code=True)
2891 self.showtraceback(running_compiled_code=True)
2892 return result
2892 return result
2893 return
2893 return
2894
2894
2895 def should_run_async(self, raw_cell: str) -> bool:
2895 def should_run_async(self, raw_cell: str) -> bool:
2896 """Return whether a cell should be run asynchronously via a coroutine runner
2896 """Return whether a cell should be run asynchronously via a coroutine runner
2897
2897
2898 Parameters
2898 Parameters
2899 ----------
2899 ----------
2900 raw_cell: str
2900 raw_cell: str
2901 The code to be executed
2901 The code to be executed
2902
2902
2903 Returns
2903 Returns
2904 -------
2904 -------
2905 result: bool
2905 result: bool
2906 Whether the code needs to be run with a coroutine runner or not
2906 Whether the code needs to be run with a coroutine runner or not
2907
2907
2908 .. versionadded: 7.0
2908 .. versionadded: 7.0
2909 """
2909 """
2910 if not self.autoawait:
2910 if not self.autoawait:
2911 return False
2911 return False
2912 try:
2912 try:
2913 cell = self.transform_cell(raw_cell)
2913 cell = self.transform_cell(raw_cell)
2914 except Exception:
2914 except Exception:
2915 # any exception during transform will be raised
2915 # any exception during transform will be raised
2916 # prior to execution
2916 # prior to execution
2917 return False
2917 return False
2918 return _should_be_async(cell)
2918 return _should_be_async(cell)
2919
2919
2920 async def run_cell_async(self, raw_cell: str, store_history=False, silent=False, shell_futures=True) -> ExecutionResult:
2920 async def run_cell_async(self, raw_cell: str, store_history=False, silent=False, shell_futures=True) -> ExecutionResult:
2921 """Run a complete IPython cell asynchronously.
2921 """Run a complete IPython cell asynchronously.
2922
2922
2923 Parameters
2923 Parameters
2924 ----------
2924 ----------
2925 raw_cell : str
2925 raw_cell : str
2926 The code (including IPython code such as %magic functions) to run.
2926 The code (including IPython code such as %magic functions) to run.
2927 store_history : bool
2927 store_history : bool
2928 If True, the raw and translated cell will be stored in IPython's
2928 If True, the raw and translated cell will be stored in IPython's
2929 history. For user code calling back into IPython's machinery, this
2929 history. For user code calling back into IPython's machinery, this
2930 should be set to False.
2930 should be set to False.
2931 silent : bool
2931 silent : bool
2932 If True, avoid side-effects, such as implicit displayhooks and
2932 If True, avoid side-effects, such as implicit displayhooks and
2933 and logging. silent=True forces store_history=False.
2933 and logging. silent=True forces store_history=False.
2934 shell_futures : bool
2934 shell_futures : bool
2935 If True, the code will share future statements with the interactive
2935 If True, the code will share future statements with the interactive
2936 shell. It will both be affected by previous __future__ imports, and
2936 shell. It will both be affected by previous __future__ imports, and
2937 any __future__ imports in the code will affect the shell. If False,
2937 any __future__ imports in the code will affect the shell. If False,
2938 __future__ imports are not shared in either direction.
2938 __future__ imports are not shared in either direction.
2939
2939
2940 Returns
2940 Returns
2941 -------
2941 -------
2942 result : :class:`ExecutionResult`
2942 result : :class:`ExecutionResult`
2943
2943
2944 .. versionadded: 7.0
2944 .. versionadded: 7.0
2945 """
2945 """
2946 info = ExecutionInfo(
2946 info = ExecutionInfo(
2947 raw_cell, store_history, silent, shell_futures)
2947 raw_cell, store_history, silent, shell_futures)
2948 result = ExecutionResult(info)
2948 result = ExecutionResult(info)
2949
2949
2950 if (not raw_cell) or raw_cell.isspace():
2950 if (not raw_cell) or raw_cell.isspace():
2951 self.last_execution_succeeded = True
2951 self.last_execution_succeeded = True
2952 self.last_execution_result = result
2952 self.last_execution_result = result
2953 return result
2953 return result
2954
2954
2955 if silent:
2955 if silent:
2956 store_history = False
2956 store_history = False
2957
2957
2958 if store_history:
2958 if store_history:
2959 result.execution_count = self.execution_count
2959 result.execution_count = self.execution_count
2960
2960
2961 def error_before_exec(value):
2961 def error_before_exec(value):
2962 if store_history:
2962 if store_history:
2963 self.execution_count += 1
2963 self.execution_count += 1
2964 result.error_before_exec = value
2964 result.error_before_exec = value
2965 self.last_execution_succeeded = False
2965 self.last_execution_succeeded = False
2966 self.last_execution_result = result
2966 self.last_execution_result = result
2967 return result
2967 return result
2968
2968
2969 self.events.trigger('pre_execute')
2969 self.events.trigger('pre_execute')
2970 if not silent:
2970 if not silent:
2971 self.events.trigger('pre_run_cell', info)
2971 self.events.trigger('pre_run_cell', info)
2972
2972
2973 # If any of our input transformation (input_transformer_manager or
2973 # If any of our input transformation (input_transformer_manager or
2974 # prefilter_manager) raises an exception, we store it in this variable
2974 # prefilter_manager) raises an exception, we store it in this variable
2975 # so that we can display the error after logging the input and storing
2975 # so that we can display the error after logging the input and storing
2976 # it in the history.
2976 # it in the history.
2977 try:
2977 try:
2978 cell = self.transform_cell(raw_cell)
2978 cell = self.transform_cell(raw_cell)
2979 except Exception:
2979 except Exception:
2980 preprocessing_exc_tuple = sys.exc_info()
2980 preprocessing_exc_tuple = sys.exc_info()
2981 cell = raw_cell # cell has to exist so it can be stored/logged
2981 cell = raw_cell # cell has to exist so it can be stored/logged
2982 else:
2982 else:
2983 preprocessing_exc_tuple = None
2983 preprocessing_exc_tuple = None
2984
2984
2985 # Store raw and processed history
2985 # Store raw and processed history
2986 if store_history:
2986 if store_history:
2987 self.history_manager.store_inputs(self.execution_count,
2987 self.history_manager.store_inputs(self.execution_count,
2988 cell, raw_cell)
2988 cell, raw_cell)
2989 if not silent:
2989 if not silent:
2990 self.logger.log(cell, raw_cell)
2990 self.logger.log(cell, raw_cell)
2991
2991
2992 # Display the exception if input processing failed.
2992 # Display the exception if input processing failed.
2993 if preprocessing_exc_tuple is not None:
2993 if preprocessing_exc_tuple is not None:
2994 self.showtraceback(preprocessing_exc_tuple)
2994 self.showtraceback(preprocessing_exc_tuple)
2995 if store_history:
2995 if store_history:
2996 self.execution_count += 1
2996 self.execution_count += 1
2997 return error_before_exec(preprocessing_exc_tuple[1])
2997 return error_before_exec(preprocessing_exc_tuple[1])
2998
2998
2999 # Our own compiler remembers the __future__ environment. If we want to
2999 # Our own compiler remembers the __future__ environment. If we want to
3000 # run code with a separate __future__ environment, use the default
3000 # run code with a separate __future__ environment, use the default
3001 # compiler
3001 # compiler
3002 compiler = self.compile if shell_futures else CachingCompiler()
3002 compiler = self.compile if shell_futures else CachingCompiler()
3003
3003
3004 _run_async = False
3004 _run_async = False
3005
3005
3006 with self.builtin_trap:
3006 with self.builtin_trap:
3007 cell_name = self.compile.cache(cell, self.execution_count)
3007 cell_name = self.compile.cache(cell, self.execution_count)
3008
3008
3009 with self.display_trap:
3009 with self.display_trap:
3010 # Compile to bytecode
3010 # Compile to bytecode
3011 try:
3011 try:
3012 if sys.version_info < (3,8) and self.autoawait:
3012 if sys.version_info < (3,8) and self.autoawait:
3013 if _should_be_async(cell):
3013 if _should_be_async(cell):
3014 # the code AST below will not be user code: we wrap it
3014 # the code AST below will not be user code: we wrap it
3015 # in an `async def`. This will likely make some AST
3015 # in an `async def`. This will likely make some AST
3016 # transformer below miss some transform opportunity and
3016 # transformer below miss some transform opportunity and
3017 # introduce a small coupling to run_code (in which we
3017 # introduce a small coupling to run_code (in which we
3018 # bake some assumptions of what _ast_asyncify returns.
3018 # bake some assumptions of what _ast_asyncify returns.
3019 # they are ways around (like grafting part of the ast
3019 # they are ways around (like grafting part of the ast
3020 # later:
3020 # later:
3021 # - Here, return code_ast.body[0].body[1:-1], as well
3021 # - Here, return code_ast.body[0].body[1:-1], as well
3022 # as last expression in return statement which is
3022 # as last expression in return statement which is
3023 # the user code part.
3023 # the user code part.
3024 # - Let it go through the AST transformers, and graft
3024 # - Let it go through the AST transformers, and graft
3025 # - it back after the AST transform
3025 # - it back after the AST transform
3026 # But that seem unreasonable, at least while we
3026 # But that seem unreasonable, at least while we
3027 # do not need it.
3027 # do not need it.
3028 code_ast = _ast_asyncify(cell, 'async-def-wrapper')
3028 code_ast = _ast_asyncify(cell, 'async-def-wrapper')
3029 _run_async = True
3029 _run_async = True
3030 else:
3030 else:
3031 code_ast = compiler.ast_parse(cell, filename=cell_name)
3031 code_ast = compiler.ast_parse(cell, filename=cell_name)
3032 else:
3032 else:
3033 code_ast = compiler.ast_parse(cell, filename=cell_name)
3033 code_ast = compiler.ast_parse(cell, filename=cell_name)
3034 except self.custom_exceptions as e:
3034 except self.custom_exceptions as e:
3035 etype, value, tb = sys.exc_info()
3035 etype, value, tb = sys.exc_info()
3036 self.CustomTB(etype, value, tb)
3036 self.CustomTB(etype, value, tb)
3037 return error_before_exec(e)
3037 return error_before_exec(e)
3038 except IndentationError as e:
3038 except IndentationError as e:
3039 self.showindentationerror()
3039 self.showindentationerror()
3040 return error_before_exec(e)
3040 return error_before_exec(e)
3041 except (OverflowError, SyntaxError, ValueError, TypeError,
3041 except (OverflowError, SyntaxError, ValueError, TypeError,
3042 MemoryError) as e:
3042 MemoryError) as e:
3043 self.showsyntaxerror()
3043 self.showsyntaxerror()
3044 return error_before_exec(e)
3044 return error_before_exec(e)
3045
3045
3046 # Apply AST transformations
3046 # Apply AST transformations
3047 try:
3047 try:
3048 code_ast = self.transform_ast(code_ast)
3048 code_ast = self.transform_ast(code_ast)
3049 except InputRejected as e:
3049 except InputRejected as e:
3050 self.showtraceback()
3050 self.showtraceback()
3051 return error_before_exec(e)
3051 return error_before_exec(e)
3052
3052
3053 # Give the displayhook a reference to our ExecutionResult so it
3053 # Give the displayhook a reference to our ExecutionResult so it
3054 # can fill in the output value.
3054 # can fill in the output value.
3055 self.displayhook.exec_result = result
3055 self.displayhook.exec_result = result
3056
3056
3057 # Execute the user code
3057 # Execute the user code
3058 interactivity = "none" if silent else self.ast_node_interactivity
3058 interactivity = "none" if silent else self.ast_node_interactivity
3059 if _run_async:
3059 if _run_async:
3060 interactivity = 'async'
3060 interactivity = 'async'
3061
3061
3062 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,
3062 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,
3063 interactivity=interactivity, compiler=compiler, result=result)
3063 interactivity=interactivity, compiler=compiler, result=result)
3064
3064
3065 self.last_execution_succeeded = not has_raised
3065 self.last_execution_succeeded = not has_raised
3066 self.last_execution_result = result
3066 self.last_execution_result = result
3067
3067
3068 # Reset this so later displayed values do not modify the
3068 # Reset this so later displayed values do not modify the
3069 # ExecutionResult
3069 # ExecutionResult
3070 self.displayhook.exec_result = None
3070 self.displayhook.exec_result = None
3071
3071
3072 if store_history:
3072 if store_history:
3073 # Write output to the database. Does nothing unless
3073 # Write output to the database. Does nothing unless
3074 # history output logging is enabled.
3074 # history output logging is enabled.
3075 self.history_manager.store_output(self.execution_count)
3075 self.history_manager.store_output(self.execution_count)
3076 # Each cell is a *single* input, regardless of how many lines it has
3076 # Each cell is a *single* input, regardless of how many lines it has
3077 self.execution_count += 1
3077 self.execution_count += 1
3078
3078
3079 return result
3079 return result
3080
3080
3081 def transform_cell(self, raw_cell):
3081 def transform_cell(self, raw_cell):
3082 """Transform an input cell before parsing it.
3082 """Transform an input cell before parsing it.
3083
3083
3084 Static transformations, implemented in IPython.core.inputtransformer2,
3084 Static transformations, implemented in IPython.core.inputtransformer2,
3085 deal with things like ``%magic`` and ``!system`` commands.
3085 deal with things like ``%magic`` and ``!system`` commands.
3086 These run on all input.
3086 These run on all input.
3087 Dynamic transformations, for things like unescaped magics and the exit
3087 Dynamic transformations, for things like unescaped magics and the exit
3088 autocall, depend on the state of the interpreter.
3088 autocall, depend on the state of the interpreter.
3089 These only apply to single line inputs.
3089 These only apply to single line inputs.
3090
3090
3091 These string-based transformations are followed by AST transformations;
3091 These string-based transformations are followed by AST transformations;
3092 see :meth:`transform_ast`.
3092 see :meth:`transform_ast`.
3093 """
3093 """
3094 # Static input transformations
3094 # Static input transformations
3095 cell = self.input_transformer_manager.transform_cell(raw_cell)
3095 cell = self.input_transformer_manager.transform_cell(raw_cell)
3096
3096
3097 if len(cell.splitlines()) == 1:
3097 if len(cell.splitlines()) == 1:
3098 # Dynamic transformations - only applied for single line commands
3098 # Dynamic transformations - only applied for single line commands
3099 with self.builtin_trap:
3099 with self.builtin_trap:
3100 # use prefilter_lines to handle trailing newlines
3100 # use prefilter_lines to handle trailing newlines
3101 # restore trailing newline for ast.parse
3101 # restore trailing newline for ast.parse
3102 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
3102 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
3103
3103
3104 lines = cell.splitlines(keepends=True)
3104 lines = cell.splitlines(keepends=True)
3105 for transform in self.input_transformers_post:
3105 for transform in self.input_transformers_post:
3106 lines = transform(lines)
3106 lines = transform(lines)
3107 cell = ''.join(lines)
3107 cell = ''.join(lines)
3108
3108
3109 return cell
3109 return cell
3110
3110
3111 def transform_ast(self, node):
3111 def transform_ast(self, node):
3112 """Apply the AST transformations from self.ast_transformers
3112 """Apply the AST transformations from self.ast_transformers
3113
3113
3114 Parameters
3114 Parameters
3115 ----------
3115 ----------
3116 node : ast.Node
3116 node : ast.Node
3117 The root node to be transformed. Typically called with the ast.Module
3117 The root node to be transformed. Typically called with the ast.Module
3118 produced by parsing user input.
3118 produced by parsing user input.
3119
3119
3120 Returns
3120 Returns
3121 -------
3121 -------
3122 An ast.Node corresponding to the node it was called with. Note that it
3122 An ast.Node corresponding to the node it was called with. Note that it
3123 may also modify the passed object, so don't rely on references to the
3123 may also modify the passed object, so don't rely on references to the
3124 original AST.
3124 original AST.
3125 """
3125 """
3126 for transformer in self.ast_transformers:
3126 for transformer in self.ast_transformers:
3127 try:
3127 try:
3128 node = transformer.visit(node)
3128 node = transformer.visit(node)
3129 except InputRejected:
3129 except InputRejected:
3130 # User-supplied AST transformers can reject an input by raising
3130 # User-supplied AST transformers can reject an input by raising
3131 # an InputRejected. Short-circuit in this case so that we
3131 # an InputRejected. Short-circuit in this case so that we
3132 # don't unregister the transform.
3132 # don't unregister the transform.
3133 raise
3133 raise
3134 except Exception:
3134 except Exception:
3135 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
3135 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
3136 self.ast_transformers.remove(transformer)
3136 self.ast_transformers.remove(transformer)
3137
3137
3138 if self.ast_transformers:
3138 if self.ast_transformers:
3139 ast.fix_missing_locations(node)
3139 ast.fix_missing_locations(node)
3140 return node
3140 return node
3141
3141
3142 async def run_ast_nodes(self, nodelist:ListType[AST], cell_name:str, interactivity='last_expr',
3142 async def run_ast_nodes(self, nodelist:ListType[AST], cell_name:str, interactivity='last_expr',
3143 compiler=compile, result=None):
3143 compiler=compile, result=None):
3144 """Run a sequence of AST nodes. The execution mode depends on the
3144 """Run a sequence of AST nodes. The execution mode depends on the
3145 interactivity parameter.
3145 interactivity parameter.
3146
3146
3147 Parameters
3147 Parameters
3148 ----------
3148 ----------
3149 nodelist : list
3149 nodelist : list
3150 A sequence of AST nodes to run.
3150 A sequence of AST nodes to run.
3151 cell_name : str
3151 cell_name : str
3152 Will be passed to the compiler as the filename of the cell. Typically
3152 Will be passed to the compiler as the filename of the cell. Typically
3153 the value returned by ip.compile.cache(cell).
3153 the value returned by ip.compile.cache(cell).
3154 interactivity : str
3154 interactivity : str
3155 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
3155 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
3156 specifying which nodes should be run interactively (displaying output
3156 specifying which nodes should be run interactively (displaying output
3157 from expressions). 'last_expr' will run the last node interactively
3157 from expressions). 'last_expr' will run the last node interactively
3158 only if it is an expression (i.e. expressions in loops or other blocks
3158 only if it is an expression (i.e. expressions in loops or other blocks
3159 are not displayed) 'last_expr_or_assign' will run the last expression
3159 are not displayed) 'last_expr_or_assign' will run the last expression
3160 or the last assignment. Other values for this parameter will raise a
3160 or the last assignment. Other values for this parameter will raise a
3161 ValueError.
3161 ValueError.
3162
3162
3163 Experimental value: 'async' Will try to run top level interactive
3163 Experimental value: 'async' Will try to run top level interactive
3164 async/await code in default runner, this will not respect the
3164 async/await code in default runner, this will not respect the
3165 interactivity setting and will only run the last node if it is an
3165 interactivity setting and will only run the last node if it is an
3166 expression.
3166 expression.
3167
3167
3168 compiler : callable
3168 compiler : callable
3169 A function with the same interface as the built-in compile(), to turn
3169 A function with the same interface as the built-in compile(), to turn
3170 the AST nodes into code objects. Default is the built-in compile().
3170 the AST nodes into code objects. Default is the built-in compile().
3171 result : ExecutionResult, optional
3171 result : ExecutionResult, optional
3172 An object to store exceptions that occur during execution.
3172 An object to store exceptions that occur during execution.
3173
3173
3174 Returns
3174 Returns
3175 -------
3175 -------
3176 True if an exception occurred while running code, False if it finished
3176 True if an exception occurred while running code, False if it finished
3177 running.
3177 running.
3178 """
3178 """
3179 if not nodelist:
3179 if not nodelist:
3180 return
3180 return
3181
3181
3182 if interactivity == 'last_expr_or_assign':
3182 if interactivity == 'last_expr_or_assign':
3183 if isinstance(nodelist[-1], _assign_nodes):
3183 if isinstance(nodelist[-1], _assign_nodes):
3184 asg = nodelist[-1]
3184 asg = nodelist[-1]
3185 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
3185 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
3186 target = asg.targets[0]
3186 target = asg.targets[0]
3187 elif isinstance(asg, _single_targets_nodes):
3187 elif isinstance(asg, _single_targets_nodes):
3188 target = asg.target
3188 target = asg.target
3189 else:
3189 else:
3190 target = None
3190 target = None
3191 if isinstance(target, ast.Name):
3191 if isinstance(target, ast.Name):
3192 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
3192 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
3193 ast.fix_missing_locations(nnode)
3193 ast.fix_missing_locations(nnode)
3194 nodelist.append(nnode)
3194 nodelist.append(nnode)
3195 interactivity = 'last_expr'
3195 interactivity = 'last_expr'
3196
3196
3197 _async = False
3197 _async = False
3198 if interactivity == 'last_expr':
3198 if interactivity == 'last_expr':
3199 if isinstance(nodelist[-1], ast.Expr):
3199 if isinstance(nodelist[-1], ast.Expr):
3200 interactivity = "last"
3200 interactivity = "last"
3201 else:
3201 else:
3202 interactivity = "none"
3202 interactivity = "none"
3203
3203
3204 if interactivity == 'none':
3204 if interactivity == 'none':
3205 to_run_exec, to_run_interactive = nodelist, []
3205 to_run_exec, to_run_interactive = nodelist, []
3206 elif interactivity == 'last':
3206 elif interactivity == 'last':
3207 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
3207 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
3208 elif interactivity == 'all':
3208 elif interactivity == 'all':
3209 to_run_exec, to_run_interactive = [], nodelist
3209 to_run_exec, to_run_interactive = [], nodelist
3210 elif interactivity == 'async':
3210 elif interactivity == 'async':
3211 to_run_exec, to_run_interactive = [], nodelist
3211 to_run_exec, to_run_interactive = [], nodelist
3212 _async = True
3212 _async = True
3213 else:
3213 else:
3214 raise ValueError("Interactivity was %r" % interactivity)
3214 raise ValueError("Interactivity was %r" % interactivity)
3215
3215
3216 try:
3216 try:
3217 if _async and sys.version_info > (3,8):
3217 if _async and sys.version_info > (3,8):
3218 raise ValueError("This branch should never happen on Python 3.8 and above, "
3218 raise ValueError("This branch should never happen on Python 3.8 and above, "
3219 "please try to upgrade IPython and open a bug report with your case.")
3219 "please try to upgrade IPython and open a bug report with your case.")
3220 if _async:
3220 if _async:
3221 # If interactivity is async the semantics of run_code are
3221 # If interactivity is async the semantics of run_code are
3222 # completely different Skip usual machinery.
3222 # completely different Skip usual machinery.
3223 mod = Module(nodelist, [])
3223 mod = Module(nodelist, [])
3224 async_wrapper_code = compiler(mod, cell_name, 'exec')
3224 async_wrapper_code = compiler(mod, cell_name, 'exec')
3225 exec(async_wrapper_code, self.user_global_ns, self.user_ns)
3225 exec(async_wrapper_code, self.user_global_ns, self.user_ns)
3226 async_code = removed_co_newlocals(self.user_ns.pop('async-def-wrapper')).__code__
3226 async_code = removed_co_newlocals(self.user_ns.pop('async-def-wrapper')).__code__
3227 if (await self.run_code(async_code, result, async_=True)):
3227 if (await self.run_code(async_code, result, async_=True)):
3228 return True
3228 return True
3229 else:
3229 else:
3230 if sys.version_info > (3, 8):
3230 if sys.version_info > (3, 8):
3231 def compare(code):
3231 def compare(code):
3232 is_async = (inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE)
3232 is_async = (inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE)
3233 return is_async
3233 return is_async
3234 else:
3234 else:
3235 def compare(code):
3235 def compare(code):
3236 return _async
3236 return _async
3237
3237
3238 # refactor that to just change the mod constructor.
3238 # refactor that to just change the mod constructor.
3239 to_run = []
3239 to_run = []
3240 for node in to_run_exec:
3240 for node in to_run_exec:
3241 to_run.append((node, 'exec'))
3241 to_run.append((node, 'exec'))
3242
3242
3243 for node in to_run_interactive:
3243 for node in to_run_interactive:
3244 to_run.append((node, 'single'))
3244 to_run.append((node, 'single'))
3245
3245
3246 for node,mode in to_run:
3246 for node,mode in to_run:
3247 if mode == 'exec':
3247 if mode == 'exec':
3248 mod = Module([node], [])
3248 mod = Module([node], [])
3249 elif mode == 'single':
3249 elif mode == 'single':
3250 mod = ast.Interactive([node])
3250 mod = ast.Interactive([node])
3251 with compiler.extra_flags(getattr(ast, 'PyCF_ALLOW_TOP_LEVEL_AWAIT', 0x0) if self.autoawait else 0x0):
3251 with compiler.extra_flags(getattr(ast, 'PyCF_ALLOW_TOP_LEVEL_AWAIT', 0x0) if self.autoawait else 0x0):
3252 code = compiler(mod, cell_name, mode)
3252 code = compiler(mod, cell_name, mode)
3253 asy = compare(code)
3253 asy = compare(code)
3254 if (await self.run_code(code, result, async_=asy)):
3254 if (await self.run_code(code, result, async_=asy)):
3255 return True
3255 return True
3256
3256
3257 # Flush softspace
3257 # Flush softspace
3258 if softspace(sys.stdout, 0):
3258 if softspace(sys.stdout, 0):
3259 print()
3259 print()
3260
3260
3261 except:
3261 except:
3262 # It's possible to have exceptions raised here, typically by
3262 # It's possible to have exceptions raised here, typically by
3263 # compilation of odd code (such as a naked 'return' outside a
3263 # compilation of odd code (such as a naked 'return' outside a
3264 # function) that did parse but isn't valid. Typically the exception
3264 # function) that did parse but isn't valid. Typically the exception
3265 # is a SyntaxError, but it's safest just to catch anything and show
3265 # is a SyntaxError, but it's safest just to catch anything and show
3266 # the user a traceback.
3266 # the user a traceback.
3267
3267
3268 # We do only one try/except outside the loop to minimize the impact
3268 # We do only one try/except outside the loop to minimize the impact
3269 # on runtime, and also because if any node in the node list is
3269 # on runtime, and also because if any node in the node list is
3270 # broken, we should stop execution completely.
3270 # broken, we should stop execution completely.
3271 if result:
3271 if result:
3272 result.error_before_exec = sys.exc_info()[1]
3272 result.error_before_exec = sys.exc_info()[1]
3273 self.showtraceback()
3273 self.showtraceback()
3274 return True
3274 return True
3275
3275
3276 return False
3276 return False
3277
3277
3278 def _async_exec(self, code_obj: types.CodeType, user_ns: dict):
3278 def _async_exec(self, code_obj: types.CodeType, user_ns: dict):
3279 """
3279 """
3280 Evaluate an asynchronous code object using a code runner
3280 Evaluate an asynchronous code object using a code runner
3281
3281
3282 Fake asynchronous execution of code_object in a namespace via a proxy namespace.
3282 Fake asynchronous execution of code_object in a namespace via a proxy namespace.
3283
3283
3284 Returns coroutine object, which can be executed via async loop runner
3284 Returns coroutine object, which can be executed via async loop runner
3285
3285
3286 WARNING: The semantics of `async_exec` are quite different from `exec`,
3286 WARNING: The semantics of `async_exec` are quite different from `exec`,
3287 in particular you can only pass a single namespace. It also return a
3287 in particular you can only pass a single namespace. It also return a
3288 handle to the value of the last things returned by code_object.
3288 handle to the value of the last things returned by code_object.
3289 """
3289 """
3290
3290
3291 return eval(code_obj, user_ns)
3291 return eval(code_obj, user_ns)
3292
3292
3293 async def run_code(self, code_obj, result=None, *, async_=False):
3293 async def run_code(self, code_obj, result=None, *, async_=False):
3294 """Execute a code object.
3294 """Execute a code object.
3295
3295
3296 When an exception occurs, self.showtraceback() is called to display a
3296 When an exception occurs, self.showtraceback() is called to display a
3297 traceback.
3297 traceback.
3298
3298
3299 Parameters
3299 Parameters
3300 ----------
3300 ----------
3301 code_obj : code object
3301 code_obj : code object
3302 A compiled code object, to be executed
3302 A compiled code object, to be executed
3303 result : ExecutionResult, optional
3303 result : ExecutionResult, optional
3304 An object to store exceptions that occur during execution.
3304 An object to store exceptions that occur during execution.
3305 async_ : Bool (Experimental)
3305 async_ : Bool (Experimental)
3306 Attempt to run top-level asynchronous code in a default loop.
3306 Attempt to run top-level asynchronous code in a default loop.
3307
3307
3308 Returns
3308 Returns
3309 -------
3309 -------
3310 False : successful execution.
3310 False : successful execution.
3311 True : an error occurred.
3311 True : an error occurred.
3312 """
3312 """
3313 # Set our own excepthook in case the user code tries to call it
3313 # Set our own excepthook in case the user code tries to call it
3314 # directly, so that the IPython crash handler doesn't get triggered
3314 # directly, so that the IPython crash handler doesn't get triggered
3315 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
3315 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
3316
3316
3317 # we save the original sys.excepthook in the instance, in case config
3317 # we save the original sys.excepthook in the instance, in case config
3318 # code (such as magics) needs access to it.
3318 # code (such as magics) needs access to it.
3319 self.sys_excepthook = old_excepthook
3319 self.sys_excepthook = old_excepthook
3320 outflag = True # happens in more places, so it's easier as default
3320 outflag = True # happens in more places, so it's easier as default
3321 try:
3321 try:
3322 try:
3322 try:
3323 self.hooks.pre_run_code_hook()
3323 self.hooks.pre_run_code_hook()
3324 if async_ and sys.version_info < (3,8):
3324 if async_ and sys.version_info < (3,8):
3325 last_expr = (await self._async_exec(code_obj, self.user_ns))
3325 last_expr = (await self._async_exec(code_obj, self.user_ns))
3326 code = compile('last_expr', 'fake', "single")
3326 code = compile('last_expr', 'fake', "single")
3327 exec(code, {'last_expr': last_expr})
3327 exec(code, {'last_expr': last_expr})
3328 elif async_ :
3328 elif async_ :
3329 await eval(code_obj, self.user_global_ns, self.user_ns)
3329 await eval(code_obj, self.user_global_ns, self.user_ns)
3330 else:
3330 else:
3331 exec(code_obj, self.user_global_ns, self.user_ns)
3331 exec(code_obj, self.user_global_ns, self.user_ns)
3332 finally:
3332 finally:
3333 # Reset our crash handler in place
3333 # Reset our crash handler in place
3334 sys.excepthook = old_excepthook
3334 sys.excepthook = old_excepthook
3335 except SystemExit as e:
3335 except SystemExit as e:
3336 if result is not None:
3336 if result is not None:
3337 result.error_in_exec = e
3337 result.error_in_exec = e
3338 self.showtraceback(exception_only=True)
3338 self.showtraceback(exception_only=True)
3339 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
3339 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
3340 except self.custom_exceptions:
3340 except self.custom_exceptions:
3341 etype, value, tb = sys.exc_info()
3341 etype, value, tb = sys.exc_info()
3342 if result is not None:
3342 if result is not None:
3343 result.error_in_exec = value
3343 result.error_in_exec = value
3344 self.CustomTB(etype, value, tb)
3344 self.CustomTB(etype, value, tb)
3345 except:
3345 except:
3346 if result is not None:
3346 if result is not None:
3347 result.error_in_exec = sys.exc_info()[1]
3347 result.error_in_exec = sys.exc_info()[1]
3348 self.showtraceback(running_compiled_code=True)
3348 self.showtraceback(running_compiled_code=True)
3349 else:
3349 else:
3350 outflag = False
3350 outflag = False
3351 return outflag
3351 return outflag
3352
3352
3353 # For backwards compatibility
3353 # For backwards compatibility
3354 runcode = run_code
3354 runcode = run_code
3355
3355
3356 def check_complete(self, code: str) -> Tuple[str, str]:
3356 def check_complete(self, code: str) -> Tuple[str, str]:
3357 """Return whether a block of code is ready to execute, or should be continued
3357 """Return whether a block of code is ready to execute, or should be continued
3358
3358
3359 Parameters
3359 Parameters
3360 ----------
3360 ----------
3361 source : string
3361 source : string
3362 Python input code, which can be multiline.
3362 Python input code, which can be multiline.
3363
3363
3364 Returns
3364 Returns
3365 -------
3365 -------
3366 status : str
3366 status : str
3367 One of 'complete', 'incomplete', or 'invalid' if source is not a
3367 One of 'complete', 'incomplete', or 'invalid' if source is not a
3368 prefix of valid code.
3368 prefix of valid code.
3369 indent : str
3369 indent : str
3370 When status is 'incomplete', this is some whitespace to insert on
3370 When status is 'incomplete', this is some whitespace to insert on
3371 the next line of the prompt.
3371 the next line of the prompt.
3372 """
3372 """
3373 status, nspaces = self.input_transformer_manager.check_complete(code)
3373 status, nspaces = self.input_transformer_manager.check_complete(code)
3374 return status, ' ' * (nspaces or 0)
3374 return status, ' ' * (nspaces or 0)
3375
3375
3376 #-------------------------------------------------------------------------
3376 #-------------------------------------------------------------------------
3377 # Things related to GUI support and pylab
3377 # Things related to GUI support and pylab
3378 #-------------------------------------------------------------------------
3378 #-------------------------------------------------------------------------
3379
3379
3380 active_eventloop = None
3380 active_eventloop = None
3381
3381
3382 def enable_gui(self, gui=None):
3382 def enable_gui(self, gui=None):
3383 raise NotImplementedError('Implement enable_gui in a subclass')
3383 raise NotImplementedError('Implement enable_gui in a subclass')
3384
3384
3385 def enable_matplotlib(self, gui=None):
3385 def enable_matplotlib(self, gui=None):
3386 """Enable interactive matplotlib and inline figure support.
3386 """Enable interactive matplotlib and inline figure support.
3387
3387
3388 This takes the following steps:
3388 This takes the following steps:
3389
3389
3390 1. select the appropriate eventloop and matplotlib backend
3390 1. select the appropriate eventloop and matplotlib backend
3391 2. set up matplotlib for interactive use with that backend
3391 2. set up matplotlib for interactive use with that backend
3392 3. configure formatters for inline figure display
3392 3. configure formatters for inline figure display
3393 4. enable the selected gui eventloop
3393 4. enable the selected gui eventloop
3394
3394
3395 Parameters
3395 Parameters
3396 ----------
3396 ----------
3397 gui : optional, string
3397 gui : optional, string
3398 If given, dictates the choice of matplotlib GUI backend to use
3398 If given, dictates the choice of matplotlib GUI backend to use
3399 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3399 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3400 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3400 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3401 matplotlib (as dictated by the matplotlib build-time options plus the
3401 matplotlib (as dictated by the matplotlib build-time options plus the
3402 user's matplotlibrc configuration file). Note that not all backends
3402 user's matplotlibrc configuration file). Note that not all backends
3403 make sense in all contexts, for example a terminal ipython can't
3403 make sense in all contexts, for example a terminal ipython can't
3404 display figures inline.
3404 display figures inline.
3405 """
3405 """
3406 from IPython.core import pylabtools as pt
3406 from IPython.core import pylabtools as pt
3407 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3407 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3408
3408
3409 if gui != 'inline':
3409 if gui != 'inline':
3410 # If we have our first gui selection, store it
3410 # If we have our first gui selection, store it
3411 if self.pylab_gui_select is None:
3411 if self.pylab_gui_select is None:
3412 self.pylab_gui_select = gui
3412 self.pylab_gui_select = gui
3413 # Otherwise if they are different
3413 # Otherwise if they are different
3414 elif gui != self.pylab_gui_select:
3414 elif gui != self.pylab_gui_select:
3415 print('Warning: Cannot change to a different GUI toolkit: %s.'
3415 print('Warning: Cannot change to a different GUI toolkit: %s.'
3416 ' Using %s instead.' % (gui, self.pylab_gui_select))
3416 ' Using %s instead.' % (gui, self.pylab_gui_select))
3417 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3417 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3418
3418
3419 pt.activate_matplotlib(backend)
3419 pt.activate_matplotlib(backend)
3420 pt.configure_inline_support(self, backend)
3420 pt.configure_inline_support(self, backend)
3421
3421
3422 # Now we must activate the gui pylab wants to use, and fix %run to take
3422 # Now we must activate the gui pylab wants to use, and fix %run to take
3423 # plot updates into account
3423 # plot updates into account
3424 self.enable_gui(gui)
3424 self.enable_gui(gui)
3425 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3425 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3426 pt.mpl_runner(self.safe_execfile)
3426 pt.mpl_runner(self.safe_execfile)
3427
3427
3428 return gui, backend
3428 return gui, backend
3429
3429
3430 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3430 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3431 """Activate pylab support at runtime.
3431 """Activate pylab support at runtime.
3432
3432
3433 This turns on support for matplotlib, preloads into the interactive
3433 This turns on support for matplotlib, preloads into the interactive
3434 namespace all of numpy and pylab, and configures IPython to correctly
3434 namespace all of numpy and pylab, and configures IPython to correctly
3435 interact with the GUI event loop. The GUI backend to be used can be
3435 interact with the GUI event loop. The GUI backend to be used can be
3436 optionally selected with the optional ``gui`` argument.
3436 optionally selected with the optional ``gui`` argument.
3437
3437
3438 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3438 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3439
3439
3440 Parameters
3440 Parameters
3441 ----------
3441 ----------
3442 gui : optional, string
3442 gui : optional, string
3443 If given, dictates the choice of matplotlib GUI backend to use
3443 If given, dictates the choice of matplotlib GUI backend to use
3444 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3444 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3445 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3445 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3446 matplotlib (as dictated by the matplotlib build-time options plus the
3446 matplotlib (as dictated by the matplotlib build-time options plus the
3447 user's matplotlibrc configuration file). Note that not all backends
3447 user's matplotlibrc configuration file). Note that not all backends
3448 make sense in all contexts, for example a terminal ipython can't
3448 make sense in all contexts, for example a terminal ipython can't
3449 display figures inline.
3449 display figures inline.
3450 import_all : optional, bool, default: True
3450 import_all : optional, bool, default: True
3451 Whether to do `from numpy import *` and `from pylab import *`
3451 Whether to do `from numpy import *` and `from pylab import *`
3452 in addition to module imports.
3452 in addition to module imports.
3453 welcome_message : deprecated
3453 welcome_message : deprecated
3454 This argument is ignored, no welcome message will be displayed.
3454 This argument is ignored, no welcome message will be displayed.
3455 """
3455 """
3456 from IPython.core.pylabtools import import_pylab
3456 from IPython.core.pylabtools import import_pylab
3457
3457
3458 gui, backend = self.enable_matplotlib(gui)
3458 gui, backend = self.enable_matplotlib(gui)
3459
3459
3460 # We want to prevent the loading of pylab to pollute the user's
3460 # We want to prevent the loading of pylab to pollute the user's
3461 # namespace as shown by the %who* magics, so we execute the activation
3461 # namespace as shown by the %who* magics, so we execute the activation
3462 # code in an empty namespace, and we update *both* user_ns and
3462 # code in an empty namespace, and we update *both* user_ns and
3463 # user_ns_hidden with this information.
3463 # user_ns_hidden with this information.
3464 ns = {}
3464 ns = {}
3465 import_pylab(ns, import_all)
3465 import_pylab(ns, import_all)
3466 # warn about clobbered names
3466 # warn about clobbered names
3467 ignored = {"__builtins__"}
3467 ignored = {"__builtins__"}
3468 both = set(ns).intersection(self.user_ns).difference(ignored)
3468 both = set(ns).intersection(self.user_ns).difference(ignored)
3469 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3469 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3470 self.user_ns.update(ns)
3470 self.user_ns.update(ns)
3471 self.user_ns_hidden.update(ns)
3471 self.user_ns_hidden.update(ns)
3472 return gui, backend, clobbered
3472 return gui, backend, clobbered
3473
3473
3474 #-------------------------------------------------------------------------
3474 #-------------------------------------------------------------------------
3475 # Utilities
3475 # Utilities
3476 #-------------------------------------------------------------------------
3476 #-------------------------------------------------------------------------
3477
3477
3478 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3478 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3479 """Expand python variables in a string.
3479 """Expand python variables in a string.
3480
3480
3481 The depth argument indicates how many frames above the caller should
3481 The depth argument indicates how many frames above the caller should
3482 be walked to look for the local namespace where to expand variables.
3482 be walked to look for the local namespace where to expand variables.
3483
3483
3484 The global namespace for expansion is always the user's interactive
3484 The global namespace for expansion is always the user's interactive
3485 namespace.
3485 namespace.
3486 """
3486 """
3487 ns = self.user_ns.copy()
3487 ns = self.user_ns.copy()
3488 try:
3488 try:
3489 frame = sys._getframe(depth+1)
3489 frame = sys._getframe(depth+1)
3490 except ValueError:
3490 except ValueError:
3491 # This is thrown if there aren't that many frames on the stack,
3491 # This is thrown if there aren't that many frames on the stack,
3492 # e.g. if a script called run_line_magic() directly.
3492 # e.g. if a script called run_line_magic() directly.
3493 pass
3493 pass
3494 else:
3494 else:
3495 ns.update(frame.f_locals)
3495 ns.update(frame.f_locals)
3496
3496
3497 try:
3497 try:
3498 # We have to use .vformat() here, because 'self' is a valid and common
3498 # We have to use .vformat() here, because 'self' is a valid and common
3499 # name, and expanding **ns for .format() would make it collide with
3499 # name, and expanding **ns for .format() would make it collide with
3500 # the 'self' argument of the method.
3500 # the 'self' argument of the method.
3501 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3501 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3502 except Exception:
3502 except Exception:
3503 # if formatter couldn't format, just let it go untransformed
3503 # if formatter couldn't format, just let it go untransformed
3504 pass
3504 pass
3505 return cmd
3505 return cmd
3506
3506
3507 def mktempfile(self, data=None, prefix='ipython_edit_'):
3507 def mktempfile(self, data=None, prefix='ipython_edit_'):
3508 """Make a new tempfile and return its filename.
3508 """Make a new tempfile and return its filename.
3509
3509
3510 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3510 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3511 but it registers the created filename internally so ipython cleans it up
3511 but it registers the created filename internally so ipython cleans it up
3512 at exit time.
3512 at exit time.
3513
3513
3514 Optional inputs:
3514 Optional inputs:
3515
3515
3516 - data(None): if data is given, it gets written out to the temp file
3516 - data(None): if data is given, it gets written out to the temp file
3517 immediately, and the file is closed again."""
3517 immediately, and the file is closed again."""
3518
3518
3519 dirname = tempfile.mkdtemp(prefix=prefix)
3519 dirname = tempfile.mkdtemp(prefix=prefix)
3520 self.tempdirs.append(dirname)
3520 self.tempdirs.append(dirname)
3521
3521
3522 handle, filename = tempfile.mkstemp('.py', prefix, dir=dirname)
3522 handle, filename = tempfile.mkstemp('.py', prefix, dir=dirname)
3523 os.close(handle) # On Windows, there can only be one open handle on a file
3523 os.close(handle) # On Windows, there can only be one open handle on a file
3524 self.tempfiles.append(filename)
3524 self.tempfiles.append(filename)
3525
3525
3526 if data:
3526 if data:
3527 with open(filename, 'w') as tmp_file:
3527 with open(filename, 'w') as tmp_file:
3528 tmp_file.write(data)
3528 tmp_file.write(data)
3529 return filename
3529 return filename
3530
3530
3531 @undoc
3531 @undoc
3532 def write(self,data):
3532 def write(self,data):
3533 """DEPRECATED: Write a string to the default output"""
3533 """DEPRECATED: Write a string to the default output"""
3534 warn('InteractiveShell.write() is deprecated, use sys.stdout instead',
3534 warn('InteractiveShell.write() is deprecated, use sys.stdout instead',
3535 DeprecationWarning, stacklevel=2)
3535 DeprecationWarning, stacklevel=2)
3536 sys.stdout.write(data)
3536 sys.stdout.write(data)
3537
3537
3538 @undoc
3538 @undoc
3539 def write_err(self,data):
3539 def write_err(self,data):
3540 """DEPRECATED: Write a string to the default error output"""
3540 """DEPRECATED: Write a string to the default error output"""
3541 warn('InteractiveShell.write_err() is deprecated, use sys.stderr instead',
3541 warn('InteractiveShell.write_err() is deprecated, use sys.stderr instead',
3542 DeprecationWarning, stacklevel=2)
3542 DeprecationWarning, stacklevel=2)
3543 sys.stderr.write(data)
3543 sys.stderr.write(data)
3544
3544
3545 def ask_yes_no(self, prompt, default=None, interrupt=None):
3545 def ask_yes_no(self, prompt, default=None, interrupt=None):
3546 if self.quiet:
3546 if self.quiet:
3547 return True
3547 return True
3548 return ask_yes_no(prompt,default,interrupt)
3548 return ask_yes_no(prompt,default,interrupt)
3549
3549
3550 def show_usage(self):
3550 def show_usage(self):
3551 """Show a usage message"""
3551 """Show a usage message"""
3552 page.page(IPython.core.usage.interactive_usage)
3552 page.page(IPython.core.usage.interactive_usage)
3553
3553
3554 def extract_input_lines(self, range_str, raw=False):
3554 def extract_input_lines(self, range_str, raw=False):
3555 """Return as a string a set of input history slices.
3555 """Return as a string a set of input history slices.
3556
3556
3557 Parameters
3557 Parameters
3558 ----------
3558 ----------
3559 range_str : string
3559 range_str : string
3560 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3560 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3561 since this function is for use by magic functions which get their
3561 since this function is for use by magic functions which get their
3562 arguments as strings. The number before the / is the session
3562 arguments as strings. The number before the / is the session
3563 number: ~n goes n back from the current session.
3563 number: ~n goes n back from the current session.
3564
3564
3565 raw : bool, optional
3565 raw : bool, optional
3566 By default, the processed input is used. If this is true, the raw
3566 By default, the processed input is used. If this is true, the raw
3567 input history is used instead.
3567 input history is used instead.
3568
3568
3569 Notes
3569 Notes
3570 -----
3570 -----
3571
3571
3572 Slices can be described with two notations:
3572 Slices can be described with two notations:
3573
3573
3574 * ``N:M`` -> standard python form, means including items N...(M-1).
3574 * ``N:M`` -> standard python form, means including items N...(M-1).
3575 * ``N-M`` -> include items N..M (closed endpoint).
3575 * ``N-M`` -> include items N..M (closed endpoint).
3576 """
3576 """
3577 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3577 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3578 return "\n".join(x for _, _, x in lines)
3578 return "\n".join(x for _, _, x in lines)
3579
3579
3580 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3580 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3581 """Get a code string from history, file, url, or a string or macro.
3581 """Get a code string from history, file, url, or a string or macro.
3582
3582
3583 This is mainly used by magic functions.
3583 This is mainly used by magic functions.
3584
3584
3585 Parameters
3585 Parameters
3586 ----------
3586 ----------
3587
3587
3588 target : str
3588 target : str
3589
3589
3590 A string specifying code to retrieve. This will be tried respectively
3590 A string specifying code to retrieve. This will be tried respectively
3591 as: ranges of input history (see %history for syntax), url,
3591 as: ranges of input history (see %history for syntax), url,
3592 corresponding .py file, filename, or an expression evaluating to a
3592 corresponding .py file, filename, or an expression evaluating to a
3593 string or Macro in the user namespace.
3593 string or Macro in the user namespace.
3594
3594
3595 raw : bool
3595 raw : bool
3596 If true (default), retrieve raw history. Has no effect on the other
3596 If true (default), retrieve raw history. Has no effect on the other
3597 retrieval mechanisms.
3597 retrieval mechanisms.
3598
3598
3599 py_only : bool (default False)
3599 py_only : bool (default False)
3600 Only try to fetch python code, do not try alternative methods to decode file
3600 Only try to fetch python code, do not try alternative methods to decode file
3601 if unicode fails.
3601 if unicode fails.
3602
3602
3603 Returns
3603 Returns
3604 -------
3604 -------
3605 A string of code.
3605 A string of code.
3606
3606
3607 ValueError is raised if nothing is found, and TypeError if it evaluates
3607 ValueError is raised if nothing is found, and TypeError if it evaluates
3608 to an object of another type. In each case, .args[0] is a printable
3608 to an object of another type. In each case, .args[0] is a printable
3609 message.
3609 message.
3610 """
3610 """
3611 code = self.extract_input_lines(target, raw=raw) # Grab history
3611 code = self.extract_input_lines(target, raw=raw) # Grab history
3612 if code:
3612 if code:
3613 return code
3613 return code
3614 try:
3614 try:
3615 if target.startswith(('http://', 'https://')):
3615 if target.startswith(('http://', 'https://')):
3616 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3616 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3617 except UnicodeDecodeError:
3617 except UnicodeDecodeError as e:
3618 if not py_only :
3618 if not py_only :
3619 # Deferred import
3619 # Deferred import
3620 from urllib.request import urlopen
3620 from urllib.request import urlopen
3621 response = urlopen(target)
3621 response = urlopen(target)
3622 return response.read().decode('latin1')
3622 return response.read().decode('latin1')
3623 raise ValueError(("'%s' seem to be unreadable.") % target)
3623 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3624
3624
3625 potential_target = [target]
3625 potential_target = [target]
3626 try :
3626 try :
3627 potential_target.insert(0,get_py_filename(target))
3627 potential_target.insert(0,get_py_filename(target))
3628 except IOError:
3628 except IOError:
3629 pass
3629 pass
3630
3630
3631 for tgt in potential_target :
3631 for tgt in potential_target :
3632 if os.path.isfile(tgt): # Read file
3632 if os.path.isfile(tgt): # Read file
3633 try :
3633 try :
3634 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3634 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3635 except UnicodeDecodeError :
3635 except UnicodeDecodeError as e:
3636 if not py_only :
3636 if not py_only :
3637 with io_open(tgt,'r', encoding='latin1') as f :
3637 with io_open(tgt,'r', encoding='latin1') as f :
3638 return f.read()
3638 return f.read()
3639 raise ValueError(("'%s' seem to be unreadable.") % target)
3639 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3640 elif os.path.isdir(os.path.expanduser(tgt)):
3640 elif os.path.isdir(os.path.expanduser(tgt)):
3641 raise ValueError("'%s' is a directory, not a regular file." % target)
3641 raise ValueError("'%s' is a directory, not a regular file." % target)
3642
3642
3643 if search_ns:
3643 if search_ns:
3644 # Inspect namespace to load object source
3644 # Inspect namespace to load object source
3645 object_info = self.object_inspect(target, detail_level=1)
3645 object_info = self.object_inspect(target, detail_level=1)
3646 if object_info['found'] and object_info['source']:
3646 if object_info['found'] and object_info['source']:
3647 return object_info['source']
3647 return object_info['source']
3648
3648
3649 try: # User namespace
3649 try: # User namespace
3650 codeobj = eval(target, self.user_ns)
3650 codeobj = eval(target, self.user_ns)
3651 except Exception:
3651 except Exception as e:
3652 raise ValueError(("'%s' was not found in history, as a file, url, "
3652 raise ValueError(("'%s' was not found in history, as a file, url, "
3653 "nor in the user namespace.") % target)
3653 "nor in the user namespace.") % target) from e
3654
3654
3655 if isinstance(codeobj, str):
3655 if isinstance(codeobj, str):
3656 return codeobj
3656 return codeobj
3657 elif isinstance(codeobj, Macro):
3657 elif isinstance(codeobj, Macro):
3658 return codeobj.value
3658 return codeobj.value
3659
3659
3660 raise TypeError("%s is neither a string nor a macro." % target,
3660 raise TypeError("%s is neither a string nor a macro." % target,
3661 codeobj)
3661 codeobj)
3662
3662
3663 #-------------------------------------------------------------------------
3663 #-------------------------------------------------------------------------
3664 # Things related to IPython exiting
3664 # Things related to IPython exiting
3665 #-------------------------------------------------------------------------
3665 #-------------------------------------------------------------------------
3666 def atexit_operations(self):
3666 def atexit_operations(self):
3667 """This will be executed at the time of exit.
3667 """This will be executed at the time of exit.
3668
3668
3669 Cleanup operations and saving of persistent data that is done
3669 Cleanup operations and saving of persistent data that is done
3670 unconditionally by IPython should be performed here.
3670 unconditionally by IPython should be performed here.
3671
3671
3672 For things that may depend on startup flags or platform specifics (such
3672 For things that may depend on startup flags or platform specifics (such
3673 as having readline or not), register a separate atexit function in the
3673 as having readline or not), register a separate atexit function in the
3674 code that has the appropriate information, rather than trying to
3674 code that has the appropriate information, rather than trying to
3675 clutter
3675 clutter
3676 """
3676 """
3677 # Close the history session (this stores the end time and line count)
3677 # Close the history session (this stores the end time and line count)
3678 # this must be *before* the tempfile cleanup, in case of temporary
3678 # this must be *before* the tempfile cleanup, in case of temporary
3679 # history db
3679 # history db
3680 self.history_manager.end_session()
3680 self.history_manager.end_session()
3681
3681
3682 # Cleanup all tempfiles and folders left around
3682 # Cleanup all tempfiles and folders left around
3683 for tfile in self.tempfiles:
3683 for tfile in self.tempfiles:
3684 try:
3684 try:
3685 os.unlink(tfile)
3685 os.unlink(tfile)
3686 except OSError:
3686 except OSError:
3687 pass
3687 pass
3688
3688
3689 for tdir in self.tempdirs:
3689 for tdir in self.tempdirs:
3690 try:
3690 try:
3691 os.rmdir(tdir)
3691 os.rmdir(tdir)
3692 except OSError:
3692 except OSError:
3693 pass
3693 pass
3694
3694
3695 # Clear all user namespaces to release all references cleanly.
3695 # Clear all user namespaces to release all references cleanly.
3696 self.reset(new_session=False)
3696 self.reset(new_session=False)
3697
3697
3698 # Run user hooks
3698 # Run user hooks
3699 self.hooks.shutdown_hook()
3699 self.hooks.shutdown_hook()
3700
3700
3701 def cleanup(self):
3701 def cleanup(self):
3702 self.restore_sys_module_state()
3702 self.restore_sys_module_state()
3703
3703
3704
3704
3705 # Overridden in terminal subclass to change prompts
3705 # Overridden in terminal subclass to change prompts
3706 def switch_doctest_mode(self, mode):
3706 def switch_doctest_mode(self, mode):
3707 pass
3707 pass
3708
3708
3709
3709
3710 class InteractiveShellABC(metaclass=abc.ABCMeta):
3710 class InteractiveShellABC(metaclass=abc.ABCMeta):
3711 """An abstract base class for InteractiveShell."""
3711 """An abstract base class for InteractiveShell."""
3712
3712
3713 InteractiveShellABC.register(InteractiveShell)
3713 InteractiveShellABC.register(InteractiveShell)
@@ -1,703 +1,703
1 # encoding: utf-8
1 # encoding: utf-8
2 """Magic functions for InteractiveShell.
2 """Magic functions for InteractiveShell.
3 """
3 """
4
4
5 #-----------------------------------------------------------------------------
5 #-----------------------------------------------------------------------------
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001 Fernando Perez <fperez@colorado.edu>
7 # Copyright (C) 2001 Fernando Perez <fperez@colorado.edu>
8 # Copyright (C) 2008 The IPython Development Team
8 # Copyright (C) 2008 The IPython Development Team
9
9
10 # Distributed under the terms of the BSD License. The full license is in
10 # Distributed under the terms of the BSD License. The full license is in
11 # the file COPYING, distributed as part of this software.
11 # the file COPYING, distributed as part of this software.
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13
13
14 import os
14 import os
15 import re
15 import re
16 import sys
16 import sys
17 from getopt import getopt, GetoptError
17 from getopt import getopt, GetoptError
18
18
19 from traitlets.config.configurable import Configurable
19 from traitlets.config.configurable import Configurable
20 from . import oinspect
20 from . import oinspect
21 from .error import UsageError
21 from .error import UsageError
22 from .inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
22 from .inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
23 from decorator import decorator
23 from decorator import decorator
24 from ..utils.ipstruct import Struct
24 from ..utils.ipstruct import Struct
25 from ..utils.process import arg_split
25 from ..utils.process import arg_split
26 from ..utils.text import dedent
26 from ..utils.text import dedent
27 from traitlets import Bool, Dict, Instance, observe
27 from traitlets import Bool, Dict, Instance, observe
28 from logging import error
28 from logging import error
29
29
30 #-----------------------------------------------------------------------------
30 #-----------------------------------------------------------------------------
31 # Globals
31 # Globals
32 #-----------------------------------------------------------------------------
32 #-----------------------------------------------------------------------------
33
33
34 # A dict we'll use for each class that has magics, used as temporary storage to
34 # A dict we'll use for each class that has magics, used as temporary storage to
35 # pass information between the @line/cell_magic method decorators and the
35 # pass information between the @line/cell_magic method decorators and the
36 # @magics_class class decorator, because the method decorators have no
36 # @magics_class class decorator, because the method decorators have no
37 # access to the class when they run. See for more details:
37 # access to the class when they run. See for more details:
38 # http://stackoverflow.com/questions/2366713/can-a-python-decorator-of-an-instance-method-access-the-class
38 # http://stackoverflow.com/questions/2366713/can-a-python-decorator-of-an-instance-method-access-the-class
39
39
40 magics = dict(line={}, cell={})
40 magics = dict(line={}, cell={})
41
41
42 magic_kinds = ('line', 'cell')
42 magic_kinds = ('line', 'cell')
43 magic_spec = ('line', 'cell', 'line_cell')
43 magic_spec = ('line', 'cell', 'line_cell')
44 magic_escapes = dict(line=ESC_MAGIC, cell=ESC_MAGIC2)
44 magic_escapes = dict(line=ESC_MAGIC, cell=ESC_MAGIC2)
45
45
46 #-----------------------------------------------------------------------------
46 #-----------------------------------------------------------------------------
47 # Utility classes and functions
47 # Utility classes and functions
48 #-----------------------------------------------------------------------------
48 #-----------------------------------------------------------------------------
49
49
50 class Bunch: pass
50 class Bunch: pass
51
51
52
52
53 def on_off(tag):
53 def on_off(tag):
54 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
54 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
55 return ['OFF','ON'][tag]
55 return ['OFF','ON'][tag]
56
56
57
57
58 def compress_dhist(dh):
58 def compress_dhist(dh):
59 """Compress a directory history into a new one with at most 20 entries.
59 """Compress a directory history into a new one with at most 20 entries.
60
60
61 Return a new list made from the first and last 10 elements of dhist after
61 Return a new list made from the first and last 10 elements of dhist after
62 removal of duplicates.
62 removal of duplicates.
63 """
63 """
64 head, tail = dh[:-10], dh[-10:]
64 head, tail = dh[:-10], dh[-10:]
65
65
66 newhead = []
66 newhead = []
67 done = set()
67 done = set()
68 for h in head:
68 for h in head:
69 if h in done:
69 if h in done:
70 continue
70 continue
71 newhead.append(h)
71 newhead.append(h)
72 done.add(h)
72 done.add(h)
73
73
74 return newhead + tail
74 return newhead + tail
75
75
76
76
77 def needs_local_scope(func):
77 def needs_local_scope(func):
78 """Decorator to mark magic functions which need to local scope to run."""
78 """Decorator to mark magic functions which need to local scope to run."""
79 func.needs_local_scope = True
79 func.needs_local_scope = True
80 return func
80 return func
81
81
82 #-----------------------------------------------------------------------------
82 #-----------------------------------------------------------------------------
83 # Class and method decorators for registering magics
83 # Class and method decorators for registering magics
84 #-----------------------------------------------------------------------------
84 #-----------------------------------------------------------------------------
85
85
86 def magics_class(cls):
86 def magics_class(cls):
87 """Class decorator for all subclasses of the main Magics class.
87 """Class decorator for all subclasses of the main Magics class.
88
88
89 Any class that subclasses Magics *must* also apply this decorator, to
89 Any class that subclasses Magics *must* also apply this decorator, to
90 ensure that all the methods that have been decorated as line/cell magics
90 ensure that all the methods that have been decorated as line/cell magics
91 get correctly registered in the class instance. This is necessary because
91 get correctly registered in the class instance. This is necessary because
92 when method decorators run, the class does not exist yet, so they
92 when method decorators run, the class does not exist yet, so they
93 temporarily store their information into a module global. Application of
93 temporarily store their information into a module global. Application of
94 this class decorator copies that global data to the class instance and
94 this class decorator copies that global data to the class instance and
95 clears the global.
95 clears the global.
96
96
97 Obviously, this mechanism is not thread-safe, which means that the
97 Obviously, this mechanism is not thread-safe, which means that the
98 *creation* of subclasses of Magic should only be done in a single-thread
98 *creation* of subclasses of Magic should only be done in a single-thread
99 context. Instantiation of the classes has no restrictions. Given that
99 context. Instantiation of the classes has no restrictions. Given that
100 these classes are typically created at IPython startup time and before user
100 these classes are typically created at IPython startup time and before user
101 application code becomes active, in practice this should not pose any
101 application code becomes active, in practice this should not pose any
102 problems.
102 problems.
103 """
103 """
104 cls.registered = True
104 cls.registered = True
105 cls.magics = dict(line = magics['line'],
105 cls.magics = dict(line = magics['line'],
106 cell = magics['cell'])
106 cell = magics['cell'])
107 magics['line'] = {}
107 magics['line'] = {}
108 magics['cell'] = {}
108 magics['cell'] = {}
109 return cls
109 return cls
110
110
111
111
112 def record_magic(dct, magic_kind, magic_name, func):
112 def record_magic(dct, magic_kind, magic_name, func):
113 """Utility function to store a function as a magic of a specific kind.
113 """Utility function to store a function as a magic of a specific kind.
114
114
115 Parameters
115 Parameters
116 ----------
116 ----------
117 dct : dict
117 dct : dict
118 A dictionary with 'line' and 'cell' subdicts.
118 A dictionary with 'line' and 'cell' subdicts.
119
119
120 magic_kind : str
120 magic_kind : str
121 Kind of magic to be stored.
121 Kind of magic to be stored.
122
122
123 magic_name : str
123 magic_name : str
124 Key to store the magic as.
124 Key to store the magic as.
125
125
126 func : function
126 func : function
127 Callable object to store.
127 Callable object to store.
128 """
128 """
129 if magic_kind == 'line_cell':
129 if magic_kind == 'line_cell':
130 dct['line'][magic_name] = dct['cell'][magic_name] = func
130 dct['line'][magic_name] = dct['cell'][magic_name] = func
131 else:
131 else:
132 dct[magic_kind][magic_name] = func
132 dct[magic_kind][magic_name] = func
133
133
134
134
135 def validate_type(magic_kind):
135 def validate_type(magic_kind):
136 """Ensure that the given magic_kind is valid.
136 """Ensure that the given magic_kind is valid.
137
137
138 Check that the given magic_kind is one of the accepted spec types (stored
138 Check that the given magic_kind is one of the accepted spec types (stored
139 in the global `magic_spec`), raise ValueError otherwise.
139 in the global `magic_spec`), raise ValueError otherwise.
140 """
140 """
141 if magic_kind not in magic_spec:
141 if magic_kind not in magic_spec:
142 raise ValueError('magic_kind must be one of %s, %s given' %
142 raise ValueError('magic_kind must be one of %s, %s given' %
143 magic_kinds, magic_kind)
143 magic_kinds, magic_kind)
144
144
145
145
146 # The docstrings for the decorator below will be fairly similar for the two
146 # The docstrings for the decorator below will be fairly similar for the two
147 # types (method and function), so we generate them here once and reuse the
147 # types (method and function), so we generate them here once and reuse the
148 # templates below.
148 # templates below.
149 _docstring_template = \
149 _docstring_template = \
150 """Decorate the given {0} as {1} magic.
150 """Decorate the given {0} as {1} magic.
151
151
152 The decorator can be used with or without arguments, as follows.
152 The decorator can be used with or without arguments, as follows.
153
153
154 i) without arguments: it will create a {1} magic named as the {0} being
154 i) without arguments: it will create a {1} magic named as the {0} being
155 decorated::
155 decorated::
156
156
157 @deco
157 @deco
158 def foo(...)
158 def foo(...)
159
159
160 will create a {1} magic named `foo`.
160 will create a {1} magic named `foo`.
161
161
162 ii) with one string argument: which will be used as the actual name of the
162 ii) with one string argument: which will be used as the actual name of the
163 resulting magic::
163 resulting magic::
164
164
165 @deco('bar')
165 @deco('bar')
166 def foo(...)
166 def foo(...)
167
167
168 will create a {1} magic named `bar`.
168 will create a {1} magic named `bar`.
169
169
170 To register a class magic use ``Interactiveshell.register_magic(class or instance)``.
170 To register a class magic use ``Interactiveshell.register_magic(class or instance)``.
171 """
171 """
172
172
173 # These two are decorator factories. While they are conceptually very similar,
173 # These two are decorator factories. While they are conceptually very similar,
174 # there are enough differences in the details that it's simpler to have them
174 # there are enough differences in the details that it's simpler to have them
175 # written as completely standalone functions rather than trying to share code
175 # written as completely standalone functions rather than trying to share code
176 # and make a single one with convoluted logic.
176 # and make a single one with convoluted logic.
177
177
178 def _method_magic_marker(magic_kind):
178 def _method_magic_marker(magic_kind):
179 """Decorator factory for methods in Magics subclasses.
179 """Decorator factory for methods in Magics subclasses.
180 """
180 """
181
181
182 validate_type(magic_kind)
182 validate_type(magic_kind)
183
183
184 # This is a closure to capture the magic_kind. We could also use a class,
184 # This is a closure to capture the magic_kind. We could also use a class,
185 # but it's overkill for just that one bit of state.
185 # but it's overkill for just that one bit of state.
186 def magic_deco(arg):
186 def magic_deco(arg):
187 call = lambda f, *a, **k: f(*a, **k)
187 call = lambda f, *a, **k: f(*a, **k)
188
188
189 if callable(arg):
189 if callable(arg):
190 # "Naked" decorator call (just @foo, no args)
190 # "Naked" decorator call (just @foo, no args)
191 func = arg
191 func = arg
192 name = func.__name__
192 name = func.__name__
193 retval = decorator(call, func)
193 retval = decorator(call, func)
194 record_magic(magics, magic_kind, name, name)
194 record_magic(magics, magic_kind, name, name)
195 elif isinstance(arg, str):
195 elif isinstance(arg, str):
196 # Decorator called with arguments (@foo('bar'))
196 # Decorator called with arguments (@foo('bar'))
197 name = arg
197 name = arg
198 def mark(func, *a, **kw):
198 def mark(func, *a, **kw):
199 record_magic(magics, magic_kind, name, func.__name__)
199 record_magic(magics, magic_kind, name, func.__name__)
200 return decorator(call, func)
200 return decorator(call, func)
201 retval = mark
201 retval = mark
202 else:
202 else:
203 raise TypeError("Decorator can only be called with "
203 raise TypeError("Decorator can only be called with "
204 "string or function")
204 "string or function")
205 return retval
205 return retval
206
206
207 # Ensure the resulting decorator has a usable docstring
207 # Ensure the resulting decorator has a usable docstring
208 magic_deco.__doc__ = _docstring_template.format('method', magic_kind)
208 magic_deco.__doc__ = _docstring_template.format('method', magic_kind)
209 return magic_deco
209 return magic_deco
210
210
211
211
212 def _function_magic_marker(magic_kind):
212 def _function_magic_marker(magic_kind):
213 """Decorator factory for standalone functions.
213 """Decorator factory for standalone functions.
214 """
214 """
215 validate_type(magic_kind)
215 validate_type(magic_kind)
216
216
217 # This is a closure to capture the magic_kind. We could also use a class,
217 # This is a closure to capture the magic_kind. We could also use a class,
218 # but it's overkill for just that one bit of state.
218 # but it's overkill for just that one bit of state.
219 def magic_deco(arg):
219 def magic_deco(arg):
220 call = lambda f, *a, **k: f(*a, **k)
220 call = lambda f, *a, **k: f(*a, **k)
221
221
222 # Find get_ipython() in the caller's namespace
222 # Find get_ipython() in the caller's namespace
223 caller = sys._getframe(1)
223 caller = sys._getframe(1)
224 for ns in ['f_locals', 'f_globals', 'f_builtins']:
224 for ns in ['f_locals', 'f_globals', 'f_builtins']:
225 get_ipython = getattr(caller, ns).get('get_ipython')
225 get_ipython = getattr(caller, ns).get('get_ipython')
226 if get_ipython is not None:
226 if get_ipython is not None:
227 break
227 break
228 else:
228 else:
229 raise NameError('Decorator can only run in context where '
229 raise NameError('Decorator can only run in context where '
230 '`get_ipython` exists')
230 '`get_ipython` exists')
231
231
232 ip = get_ipython()
232 ip = get_ipython()
233
233
234 if callable(arg):
234 if callable(arg):
235 # "Naked" decorator call (just @foo, no args)
235 # "Naked" decorator call (just @foo, no args)
236 func = arg
236 func = arg
237 name = func.__name__
237 name = func.__name__
238 ip.register_magic_function(func, magic_kind, name)
238 ip.register_magic_function(func, magic_kind, name)
239 retval = decorator(call, func)
239 retval = decorator(call, func)
240 elif isinstance(arg, str):
240 elif isinstance(arg, str):
241 # Decorator called with arguments (@foo('bar'))
241 # Decorator called with arguments (@foo('bar'))
242 name = arg
242 name = arg
243 def mark(func, *a, **kw):
243 def mark(func, *a, **kw):
244 ip.register_magic_function(func, magic_kind, name)
244 ip.register_magic_function(func, magic_kind, name)
245 return decorator(call, func)
245 return decorator(call, func)
246 retval = mark
246 retval = mark
247 else:
247 else:
248 raise TypeError("Decorator can only be called with "
248 raise TypeError("Decorator can only be called with "
249 "string or function")
249 "string or function")
250 return retval
250 return retval
251
251
252 # Ensure the resulting decorator has a usable docstring
252 # Ensure the resulting decorator has a usable docstring
253 ds = _docstring_template.format('function', magic_kind)
253 ds = _docstring_template.format('function', magic_kind)
254
254
255 ds += dedent("""
255 ds += dedent("""
256 Note: this decorator can only be used in a context where IPython is already
256 Note: this decorator can only be used in a context where IPython is already
257 active, so that the `get_ipython()` call succeeds. You can therefore use
257 active, so that the `get_ipython()` call succeeds. You can therefore use
258 it in your startup files loaded after IPython initializes, but *not* in the
258 it in your startup files loaded after IPython initializes, but *not* in the
259 IPython configuration file itself, which is executed before IPython is
259 IPython configuration file itself, which is executed before IPython is
260 fully up and running. Any file located in the `startup` subdirectory of
260 fully up and running. Any file located in the `startup` subdirectory of
261 your configuration profile will be OK in this sense.
261 your configuration profile will be OK in this sense.
262 """)
262 """)
263
263
264 magic_deco.__doc__ = ds
264 magic_deco.__doc__ = ds
265 return magic_deco
265 return magic_deco
266
266
267
267
268 MAGIC_NO_VAR_EXPAND_ATTR = '_ipython_magic_no_var_expand'
268 MAGIC_NO_VAR_EXPAND_ATTR = '_ipython_magic_no_var_expand'
269
269
270
270
271 def no_var_expand(magic_func):
271 def no_var_expand(magic_func):
272 """Mark a magic function as not needing variable expansion
272 """Mark a magic function as not needing variable expansion
273
273
274 By default, IPython interprets `{a}` or `$a` in the line passed to magics
274 By default, IPython interprets `{a}` or `$a` in the line passed to magics
275 as variables that should be interpolated from the interactive namespace
275 as variables that should be interpolated from the interactive namespace
276 before passing the line to the magic function.
276 before passing the line to the magic function.
277 This is not always desirable, e.g. when the magic executes Python code
277 This is not always desirable, e.g. when the magic executes Python code
278 (%timeit, %time, etc.).
278 (%timeit, %time, etc.).
279 Decorate magics with `@no_var_expand` to opt-out of variable expansion.
279 Decorate magics with `@no_var_expand` to opt-out of variable expansion.
280
280
281 .. versionadded:: 7.3
281 .. versionadded:: 7.3
282 """
282 """
283 setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
283 setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
284 return magic_func
284 return magic_func
285
285
286
286
287 # Create the actual decorators for public use
287 # Create the actual decorators for public use
288
288
289 # These three are used to decorate methods in class definitions
289 # These three are used to decorate methods in class definitions
290 line_magic = _method_magic_marker('line')
290 line_magic = _method_magic_marker('line')
291 cell_magic = _method_magic_marker('cell')
291 cell_magic = _method_magic_marker('cell')
292 line_cell_magic = _method_magic_marker('line_cell')
292 line_cell_magic = _method_magic_marker('line_cell')
293
293
294 # These three decorate standalone functions and perform the decoration
294 # These three decorate standalone functions and perform the decoration
295 # immediately. They can only run where get_ipython() works
295 # immediately. They can only run where get_ipython() works
296 register_line_magic = _function_magic_marker('line')
296 register_line_magic = _function_magic_marker('line')
297 register_cell_magic = _function_magic_marker('cell')
297 register_cell_magic = _function_magic_marker('cell')
298 register_line_cell_magic = _function_magic_marker('line_cell')
298 register_line_cell_magic = _function_magic_marker('line_cell')
299
299
300 #-----------------------------------------------------------------------------
300 #-----------------------------------------------------------------------------
301 # Core Magic classes
301 # Core Magic classes
302 #-----------------------------------------------------------------------------
302 #-----------------------------------------------------------------------------
303
303
304 class MagicsManager(Configurable):
304 class MagicsManager(Configurable):
305 """Object that handles all magic-related functionality for IPython.
305 """Object that handles all magic-related functionality for IPython.
306 """
306 """
307 # Non-configurable class attributes
307 # Non-configurable class attributes
308
308
309 # A two-level dict, first keyed by magic type, then by magic function, and
309 # A two-level dict, first keyed by magic type, then by magic function, and
310 # holding the actual callable object as value. This is the dict used for
310 # holding the actual callable object as value. This is the dict used for
311 # magic function dispatch
311 # magic function dispatch
312 magics = Dict()
312 magics = Dict()
313
313
314 # A registry of the original objects that we've been given holding magics.
314 # A registry of the original objects that we've been given holding magics.
315 registry = Dict()
315 registry = Dict()
316
316
317 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
317 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
318
318
319 auto_magic = Bool(True, help=
319 auto_magic = Bool(True, help=
320 "Automatically call line magics without requiring explicit % prefix"
320 "Automatically call line magics without requiring explicit % prefix"
321 ).tag(config=True)
321 ).tag(config=True)
322 @observe('auto_magic')
322 @observe('auto_magic')
323 def _auto_magic_changed(self, change):
323 def _auto_magic_changed(self, change):
324 self.shell.automagic = change['new']
324 self.shell.automagic = change['new']
325
325
326 _auto_status = [
326 _auto_status = [
327 'Automagic is OFF, % prefix IS needed for line magics.',
327 'Automagic is OFF, % prefix IS needed for line magics.',
328 'Automagic is ON, % prefix IS NOT needed for line magics.']
328 'Automagic is ON, % prefix IS NOT needed for line magics.']
329
329
330 user_magics = Instance('IPython.core.magics.UserMagics', allow_none=True)
330 user_magics = Instance('IPython.core.magics.UserMagics', allow_none=True)
331
331
332 def __init__(self, shell=None, config=None, user_magics=None, **traits):
332 def __init__(self, shell=None, config=None, user_magics=None, **traits):
333
333
334 super(MagicsManager, self).__init__(shell=shell, config=config,
334 super(MagicsManager, self).__init__(shell=shell, config=config,
335 user_magics=user_magics, **traits)
335 user_magics=user_magics, **traits)
336 self.magics = dict(line={}, cell={})
336 self.magics = dict(line={}, cell={})
337 # Let's add the user_magics to the registry for uniformity, so *all*
337 # Let's add the user_magics to the registry for uniformity, so *all*
338 # registered magic containers can be found there.
338 # registered magic containers can be found there.
339 self.registry[user_magics.__class__.__name__] = user_magics
339 self.registry[user_magics.__class__.__name__] = user_magics
340
340
341 def auto_status(self):
341 def auto_status(self):
342 """Return descriptive string with automagic status."""
342 """Return descriptive string with automagic status."""
343 return self._auto_status[self.auto_magic]
343 return self._auto_status[self.auto_magic]
344
344
345 def lsmagic(self):
345 def lsmagic(self):
346 """Return a dict of currently available magic functions.
346 """Return a dict of currently available magic functions.
347
347
348 The return dict has the keys 'line' and 'cell', corresponding to the
348 The return dict has the keys 'line' and 'cell', corresponding to the
349 two types of magics we support. Each value is a list of names.
349 two types of magics we support. Each value is a list of names.
350 """
350 """
351 return self.magics
351 return self.magics
352
352
353 def lsmagic_docs(self, brief=False, missing=''):
353 def lsmagic_docs(self, brief=False, missing=''):
354 """Return dict of documentation of magic functions.
354 """Return dict of documentation of magic functions.
355
355
356 The return dict has the keys 'line' and 'cell', corresponding to the
356 The return dict has the keys 'line' and 'cell', corresponding to the
357 two types of magics we support. Each value is a dict keyed by magic
357 two types of magics we support. Each value is a dict keyed by magic
358 name whose value is the function docstring. If a docstring is
358 name whose value is the function docstring. If a docstring is
359 unavailable, the value of `missing` is used instead.
359 unavailable, the value of `missing` is used instead.
360
360
361 If brief is True, only the first line of each docstring will be returned.
361 If brief is True, only the first line of each docstring will be returned.
362 """
362 """
363 docs = {}
363 docs = {}
364 for m_type in self.magics:
364 for m_type in self.magics:
365 m_docs = {}
365 m_docs = {}
366 for m_name, m_func in self.magics[m_type].items():
366 for m_name, m_func in self.magics[m_type].items():
367 if m_func.__doc__:
367 if m_func.__doc__:
368 if brief:
368 if brief:
369 m_docs[m_name] = m_func.__doc__.split('\n', 1)[0]
369 m_docs[m_name] = m_func.__doc__.split('\n', 1)[0]
370 else:
370 else:
371 m_docs[m_name] = m_func.__doc__.rstrip()
371 m_docs[m_name] = m_func.__doc__.rstrip()
372 else:
372 else:
373 m_docs[m_name] = missing
373 m_docs[m_name] = missing
374 docs[m_type] = m_docs
374 docs[m_type] = m_docs
375 return docs
375 return docs
376
376
377 def register(self, *magic_objects):
377 def register(self, *magic_objects):
378 """Register one or more instances of Magics.
378 """Register one or more instances of Magics.
379
379
380 Take one or more classes or instances of classes that subclass the main
380 Take one or more classes or instances of classes that subclass the main
381 `core.Magic` class, and register them with IPython to use the magic
381 `core.Magic` class, and register them with IPython to use the magic
382 functions they provide. The registration process will then ensure that
382 functions they provide. The registration process will then ensure that
383 any methods that have decorated to provide line and/or cell magics will
383 any methods that have decorated to provide line and/or cell magics will
384 be recognized with the `%x`/`%%x` syntax as a line/cell magic
384 be recognized with the `%x`/`%%x` syntax as a line/cell magic
385 respectively.
385 respectively.
386
386
387 If classes are given, they will be instantiated with the default
387 If classes are given, they will be instantiated with the default
388 constructor. If your classes need a custom constructor, you should
388 constructor. If your classes need a custom constructor, you should
389 instanitate them first and pass the instance.
389 instanitate them first and pass the instance.
390
390
391 The provided arguments can be an arbitrary mix of classes and instances.
391 The provided arguments can be an arbitrary mix of classes and instances.
392
392
393 Parameters
393 Parameters
394 ----------
394 ----------
395 magic_objects : one or more classes or instances
395 magic_objects : one or more classes or instances
396 """
396 """
397 # Start by validating them to ensure they have all had their magic
397 # Start by validating them to ensure they have all had their magic
398 # methods registered at the instance level
398 # methods registered at the instance level
399 for m in magic_objects:
399 for m in magic_objects:
400 if not m.registered:
400 if not m.registered:
401 raise ValueError("Class of magics %r was constructed without "
401 raise ValueError("Class of magics %r was constructed without "
402 "the @register_magics class decorator")
402 "the @register_magics class decorator")
403 if isinstance(m, type):
403 if isinstance(m, type):
404 # If we're given an uninstantiated class
404 # If we're given an uninstantiated class
405 m = m(shell=self.shell)
405 m = m(shell=self.shell)
406
406
407 # Now that we have an instance, we can register it and update the
407 # Now that we have an instance, we can register it and update the
408 # table of callables
408 # table of callables
409 self.registry[m.__class__.__name__] = m
409 self.registry[m.__class__.__name__] = m
410 for mtype in magic_kinds:
410 for mtype in magic_kinds:
411 self.magics[mtype].update(m.magics[mtype])
411 self.magics[mtype].update(m.magics[mtype])
412
412
413 def register_function(self, func, magic_kind='line', magic_name=None):
413 def register_function(self, func, magic_kind='line', magic_name=None):
414 """Expose a standalone function as magic function for IPython.
414 """Expose a standalone function as magic function for IPython.
415
415
416 This will create an IPython magic (line, cell or both) from a
416 This will create an IPython magic (line, cell or both) from a
417 standalone function. The functions should have the following
417 standalone function. The functions should have the following
418 signatures:
418 signatures:
419
419
420 * For line magics: `def f(line)`
420 * For line magics: `def f(line)`
421 * For cell magics: `def f(line, cell)`
421 * For cell magics: `def f(line, cell)`
422 * For a function that does both: `def f(line, cell=None)`
422 * For a function that does both: `def f(line, cell=None)`
423
423
424 In the latter case, the function will be called with `cell==None` when
424 In the latter case, the function will be called with `cell==None` when
425 invoked as `%f`, and with cell as a string when invoked as `%%f`.
425 invoked as `%f`, and with cell as a string when invoked as `%%f`.
426
426
427 Parameters
427 Parameters
428 ----------
428 ----------
429 func : callable
429 func : callable
430 Function to be registered as a magic.
430 Function to be registered as a magic.
431
431
432 magic_kind : str
432 magic_kind : str
433 Kind of magic, one of 'line', 'cell' or 'line_cell'
433 Kind of magic, one of 'line', 'cell' or 'line_cell'
434
434
435 magic_name : optional str
435 magic_name : optional str
436 If given, the name the magic will have in the IPython namespace. By
436 If given, the name the magic will have in the IPython namespace. By
437 default, the name of the function itself is used.
437 default, the name of the function itself is used.
438 """
438 """
439
439
440 # Create the new method in the user_magics and register it in the
440 # Create the new method in the user_magics and register it in the
441 # global table
441 # global table
442 validate_type(magic_kind)
442 validate_type(magic_kind)
443 magic_name = func.__name__ if magic_name is None else magic_name
443 magic_name = func.__name__ if magic_name is None else magic_name
444 setattr(self.user_magics, magic_name, func)
444 setattr(self.user_magics, magic_name, func)
445 record_magic(self.magics, magic_kind, magic_name, func)
445 record_magic(self.magics, magic_kind, magic_name, func)
446
446
447 def register_alias(self, alias_name, magic_name, magic_kind='line', magic_params=None):
447 def register_alias(self, alias_name, magic_name, magic_kind='line', magic_params=None):
448 """Register an alias to a magic function.
448 """Register an alias to a magic function.
449
449
450 The alias is an instance of :class:`MagicAlias`, which holds the
450 The alias is an instance of :class:`MagicAlias`, which holds the
451 name and kind of the magic it should call. Binding is done at
451 name and kind of the magic it should call. Binding is done at
452 call time, so if the underlying magic function is changed the alias
452 call time, so if the underlying magic function is changed the alias
453 will call the new function.
453 will call the new function.
454
454
455 Parameters
455 Parameters
456 ----------
456 ----------
457 alias_name : str
457 alias_name : str
458 The name of the magic to be registered.
458 The name of the magic to be registered.
459
459
460 magic_name : str
460 magic_name : str
461 The name of an existing magic.
461 The name of an existing magic.
462
462
463 magic_kind : str
463 magic_kind : str
464 Kind of magic, one of 'line' or 'cell'
464 Kind of magic, one of 'line' or 'cell'
465 """
465 """
466
466
467 # `validate_type` is too permissive, as it allows 'line_cell'
467 # `validate_type` is too permissive, as it allows 'line_cell'
468 # which we do not handle.
468 # which we do not handle.
469 if magic_kind not in magic_kinds:
469 if magic_kind not in magic_kinds:
470 raise ValueError('magic_kind must be one of %s, %s given' %
470 raise ValueError('magic_kind must be one of %s, %s given' %
471 magic_kinds, magic_kind)
471 magic_kinds, magic_kind)
472
472
473 alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
473 alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
474 setattr(self.user_magics, alias_name, alias)
474 setattr(self.user_magics, alias_name, alias)
475 record_magic(self.magics, magic_kind, alias_name, alias)
475 record_magic(self.magics, magic_kind, alias_name, alias)
476
476
477 # Key base class that provides the central functionality for magics.
477 # Key base class that provides the central functionality for magics.
478
478
479
479
480 class Magics(Configurable):
480 class Magics(Configurable):
481 """Base class for implementing magic functions.
481 """Base class for implementing magic functions.
482
482
483 Shell functions which can be reached as %function_name. All magic
483 Shell functions which can be reached as %function_name. All magic
484 functions should accept a string, which they can parse for their own
484 functions should accept a string, which they can parse for their own
485 needs. This can make some functions easier to type, eg `%cd ../`
485 needs. This can make some functions easier to type, eg `%cd ../`
486 vs. `%cd("../")`
486 vs. `%cd("../")`
487
487
488 Classes providing magic functions need to subclass this class, and they
488 Classes providing magic functions need to subclass this class, and they
489 MUST:
489 MUST:
490
490
491 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
491 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
492 individual methods as magic functions, AND
492 individual methods as magic functions, AND
493
493
494 - Use the class decorator `@magics_class` to ensure that the magic
494 - Use the class decorator `@magics_class` to ensure that the magic
495 methods are properly registered at the instance level upon instance
495 methods are properly registered at the instance level upon instance
496 initialization.
496 initialization.
497
497
498 See :mod:`magic_functions` for examples of actual implementation classes.
498 See :mod:`magic_functions` for examples of actual implementation classes.
499 """
499 """
500 # Dict holding all command-line options for each magic.
500 # Dict holding all command-line options for each magic.
501 options_table = None
501 options_table = None
502 # Dict for the mapping of magic names to methods, set by class decorator
502 # Dict for the mapping of magic names to methods, set by class decorator
503 magics = None
503 magics = None
504 # Flag to check that the class decorator was properly applied
504 # Flag to check that the class decorator was properly applied
505 registered = False
505 registered = False
506 # Instance of IPython shell
506 # Instance of IPython shell
507 shell = None
507 shell = None
508
508
509 def __init__(self, shell=None, **kwargs):
509 def __init__(self, shell=None, **kwargs):
510 if not(self.__class__.registered):
510 if not(self.__class__.registered):
511 raise ValueError('Magics subclass without registration - '
511 raise ValueError('Magics subclass without registration - '
512 'did you forget to apply @magics_class?')
512 'did you forget to apply @magics_class?')
513 if shell is not None:
513 if shell is not None:
514 if hasattr(shell, 'configurables'):
514 if hasattr(shell, 'configurables'):
515 shell.configurables.append(self)
515 shell.configurables.append(self)
516 if hasattr(shell, 'config'):
516 if hasattr(shell, 'config'):
517 kwargs.setdefault('parent', shell)
517 kwargs.setdefault('parent', shell)
518
518
519 self.shell = shell
519 self.shell = shell
520 self.options_table = {}
520 self.options_table = {}
521 # The method decorators are run when the instance doesn't exist yet, so
521 # The method decorators are run when the instance doesn't exist yet, so
522 # they can only record the names of the methods they are supposed to
522 # they can only record the names of the methods they are supposed to
523 # grab. Only now, that the instance exists, can we create the proper
523 # grab. Only now, that the instance exists, can we create the proper
524 # mapping to bound methods. So we read the info off the original names
524 # mapping to bound methods. So we read the info off the original names
525 # table and replace each method name by the actual bound method.
525 # table and replace each method name by the actual bound method.
526 # But we mustn't clobber the *class* mapping, in case of multiple instances.
526 # But we mustn't clobber the *class* mapping, in case of multiple instances.
527 class_magics = self.magics
527 class_magics = self.magics
528 self.magics = {}
528 self.magics = {}
529 for mtype in magic_kinds:
529 for mtype in magic_kinds:
530 tab = self.magics[mtype] = {}
530 tab = self.magics[mtype] = {}
531 cls_tab = class_magics[mtype]
531 cls_tab = class_magics[mtype]
532 for magic_name, meth_name in cls_tab.items():
532 for magic_name, meth_name in cls_tab.items():
533 if isinstance(meth_name, str):
533 if isinstance(meth_name, str):
534 # it's a method name, grab it
534 # it's a method name, grab it
535 tab[magic_name] = getattr(self, meth_name)
535 tab[magic_name] = getattr(self, meth_name)
536 else:
536 else:
537 # it's the real thing
537 # it's the real thing
538 tab[magic_name] = meth_name
538 tab[magic_name] = meth_name
539 # Configurable **needs** to be initiated at the end or the config
539 # Configurable **needs** to be initiated at the end or the config
540 # magics get screwed up.
540 # magics get screwed up.
541 super(Magics, self).__init__(**kwargs)
541 super(Magics, self).__init__(**kwargs)
542
542
543 def arg_err(self,func):
543 def arg_err(self,func):
544 """Print docstring if incorrect arguments were passed"""
544 """Print docstring if incorrect arguments were passed"""
545 print('Error in arguments:')
545 print('Error in arguments:')
546 print(oinspect.getdoc(func))
546 print(oinspect.getdoc(func))
547
547
548 def format_latex(self, strng):
548 def format_latex(self, strng):
549 """Format a string for latex inclusion."""
549 """Format a string for latex inclusion."""
550
550
551 # Characters that need to be escaped for latex:
551 # Characters that need to be escaped for latex:
552 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
552 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
553 # Magic command names as headers:
553 # Magic command names as headers:
554 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
554 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
555 re.MULTILINE)
555 re.MULTILINE)
556 # Magic commands
556 # Magic commands
557 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
557 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
558 re.MULTILINE)
558 re.MULTILINE)
559 # Paragraph continue
559 # Paragraph continue
560 par_re = re.compile(r'\\$',re.MULTILINE)
560 par_re = re.compile(r'\\$',re.MULTILINE)
561
561
562 # The "\n" symbol
562 # The "\n" symbol
563 newline_re = re.compile(r'\\n')
563 newline_re = re.compile(r'\\n')
564
564
565 # Now build the string for output:
565 # Now build the string for output:
566 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
566 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
567 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
567 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
568 strng)
568 strng)
569 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
569 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
570 strng = par_re.sub(r'\\\\',strng)
570 strng = par_re.sub(r'\\\\',strng)
571 strng = escape_re.sub(r'\\\1',strng)
571 strng = escape_re.sub(r'\\\1',strng)
572 strng = newline_re.sub(r'\\textbackslash{}n',strng)
572 strng = newline_re.sub(r'\\textbackslash{}n',strng)
573 return strng
573 return strng
574
574
575 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
575 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
576 """Parse options passed to an argument string.
576 """Parse options passed to an argument string.
577
577
578 The interface is similar to that of :func:`getopt.getopt`, but it
578 The interface is similar to that of :func:`getopt.getopt`, but it
579 returns a :class:`~IPython.utils.struct.Struct` with the options as keys
579 returns a :class:`~IPython.utils.struct.Struct` with the options as keys
580 and the stripped argument string still as a string.
580 and the stripped argument string still as a string.
581
581
582 arg_str is quoted as a true sys.argv vector by using shlex.split.
582 arg_str is quoted as a true sys.argv vector by using shlex.split.
583 This allows us to easily expand variables, glob files, quote
583 This allows us to easily expand variables, glob files, quote
584 arguments, etc.
584 arguments, etc.
585
585
586 Parameters
586 Parameters
587 ----------
587 ----------
588
588
589 arg_str : str
589 arg_str : str
590 The arguments to parse.
590 The arguments to parse.
591
591
592 opt_str : str
592 opt_str : str
593 The options specification.
593 The options specification.
594
594
595 mode : str, default 'string'
595 mode : str, default 'string'
596 If given as 'list', the argument string is returned as a list (split
596 If given as 'list', the argument string is returned as a list (split
597 on whitespace) instead of a string.
597 on whitespace) instead of a string.
598
598
599 list_all : bool, default False
599 list_all : bool, default False
600 Put all option values in lists. Normally only options
600 Put all option values in lists. Normally only options
601 appearing more than once are put in a list.
601 appearing more than once are put in a list.
602
602
603 posix : bool, default True
603 posix : bool, default True
604 Whether to split the input line in POSIX mode or not, as per the
604 Whether to split the input line in POSIX mode or not, as per the
605 conventions outlined in the :mod:`shlex` module from the standard
605 conventions outlined in the :mod:`shlex` module from the standard
606 library.
606 library.
607 """
607 """
608
608
609 # inject default options at the beginning of the input line
609 # inject default options at the beginning of the input line
610 caller = sys._getframe(1).f_code.co_name
610 caller = sys._getframe(1).f_code.co_name
611 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
611 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
612
612
613 mode = kw.get('mode','string')
613 mode = kw.get('mode','string')
614 if mode not in ['string','list']:
614 if mode not in ['string','list']:
615 raise ValueError('incorrect mode given: %s' % mode)
615 raise ValueError('incorrect mode given: %s' % mode)
616 # Get options
616 # Get options
617 list_all = kw.get('list_all',0)
617 list_all = kw.get('list_all',0)
618 posix = kw.get('posix', os.name == 'posix')
618 posix = kw.get('posix', os.name == 'posix')
619 strict = kw.get('strict', True)
619 strict = kw.get('strict', True)
620
620
621 # Check if we have more than one argument to warrant extra processing:
621 # Check if we have more than one argument to warrant extra processing:
622 odict = {} # Dictionary with options
622 odict = {} # Dictionary with options
623 args = arg_str.split()
623 args = arg_str.split()
624 if len(args) >= 1:
624 if len(args) >= 1:
625 # If the list of inputs only has 0 or 1 thing in it, there's no
625 # If the list of inputs only has 0 or 1 thing in it, there's no
626 # need to look for options
626 # need to look for options
627 argv = arg_split(arg_str, posix, strict)
627 argv = arg_split(arg_str, posix, strict)
628 # Do regular option processing
628 # Do regular option processing
629 try:
629 try:
630 opts,args = getopt(argv, opt_str, long_opts)
630 opts,args = getopt(argv, opt_str, long_opts)
631 except GetoptError as e:
631 except GetoptError as e:
632 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
632 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
633 " ".join(long_opts)))
633 " ".join(long_opts))) from e
634 for o,a in opts:
634 for o,a in opts:
635 if o.startswith('--'):
635 if o.startswith('--'):
636 o = o[2:]
636 o = o[2:]
637 else:
637 else:
638 o = o[1:]
638 o = o[1:]
639 try:
639 try:
640 odict[o].append(a)
640 odict[o].append(a)
641 except AttributeError:
641 except AttributeError:
642 odict[o] = [odict[o],a]
642 odict[o] = [odict[o],a]
643 except KeyError:
643 except KeyError:
644 if list_all:
644 if list_all:
645 odict[o] = [a]
645 odict[o] = [a]
646 else:
646 else:
647 odict[o] = a
647 odict[o] = a
648
648
649 # Prepare opts,args for return
649 # Prepare opts,args for return
650 opts = Struct(odict)
650 opts = Struct(odict)
651 if mode == 'string':
651 if mode == 'string':
652 args = ' '.join(args)
652 args = ' '.join(args)
653
653
654 return opts,args
654 return opts,args
655
655
656 def default_option(self, fn, optstr):
656 def default_option(self, fn, optstr):
657 """Make an entry in the options_table for fn, with value optstr"""
657 """Make an entry in the options_table for fn, with value optstr"""
658
658
659 if fn not in self.lsmagic():
659 if fn not in self.lsmagic():
660 error("%s is not a magic function" % fn)
660 error("%s is not a magic function" % fn)
661 self.options_table[fn] = optstr
661 self.options_table[fn] = optstr
662
662
663
663
664 class MagicAlias(object):
664 class MagicAlias(object):
665 """An alias to another magic function.
665 """An alias to another magic function.
666
666
667 An alias is determined by its magic name and magic kind. Lookup
667 An alias is determined by its magic name and magic kind. Lookup
668 is done at call time, so if the underlying magic changes the alias
668 is done at call time, so if the underlying magic changes the alias
669 will call the new function.
669 will call the new function.
670
670
671 Use the :meth:`MagicsManager.register_alias` method or the
671 Use the :meth:`MagicsManager.register_alias` method or the
672 `%alias_magic` magic function to create and register a new alias.
672 `%alias_magic` magic function to create and register a new alias.
673 """
673 """
674 def __init__(self, shell, magic_name, magic_kind, magic_params=None):
674 def __init__(self, shell, magic_name, magic_kind, magic_params=None):
675 self.shell = shell
675 self.shell = shell
676 self.magic_name = magic_name
676 self.magic_name = magic_name
677 self.magic_params = magic_params
677 self.magic_params = magic_params
678 self.magic_kind = magic_kind
678 self.magic_kind = magic_kind
679
679
680 self.pretty_target = '%s%s' % (magic_escapes[self.magic_kind], self.magic_name)
680 self.pretty_target = '%s%s' % (magic_escapes[self.magic_kind], self.magic_name)
681 self.__doc__ = "Alias for `%s`." % self.pretty_target
681 self.__doc__ = "Alias for `%s`." % self.pretty_target
682
682
683 self._in_call = False
683 self._in_call = False
684
684
685 def __call__(self, *args, **kwargs):
685 def __call__(self, *args, **kwargs):
686 """Call the magic alias."""
686 """Call the magic alias."""
687 fn = self.shell.find_magic(self.magic_name, self.magic_kind)
687 fn = self.shell.find_magic(self.magic_name, self.magic_kind)
688 if fn is None:
688 if fn is None:
689 raise UsageError("Magic `%s` not found." % self.pretty_target)
689 raise UsageError("Magic `%s` not found." % self.pretty_target)
690
690
691 # Protect against infinite recursion.
691 # Protect against infinite recursion.
692 if self._in_call:
692 if self._in_call:
693 raise UsageError("Infinite recursion detected; "
693 raise UsageError("Infinite recursion detected; "
694 "magic aliases cannot call themselves.")
694 "magic aliases cannot call themselves.")
695 self._in_call = True
695 self._in_call = True
696 try:
696 try:
697 if self.magic_params:
697 if self.magic_params:
698 args_list = list(args)
698 args_list = list(args)
699 args_list[0] = self.magic_params + " " + args[0]
699 args_list[0] = self.magic_params + " " + args[0]
700 args = tuple(args_list)
700 args = tuple(args_list)
701 return fn(*args, **kwargs)
701 return fn(*args, **kwargs)
702 finally:
702 finally:
703 self._in_call = False
703 self._in_call = False
@@ -1,730 +1,730
1 """Implementation of code management magic functions.
1 """Implementation of code management magic functions.
2 """
2 """
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Copyright (c) 2012 The IPython Development Team.
4 # Copyright (c) 2012 The IPython Development Team.
5 #
5 #
6 # Distributed under the terms of the Modified BSD License.
6 # Distributed under the terms of the Modified BSD License.
7 #
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10
10
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12 # Imports
12 # Imports
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14
14
15 # Stdlib
15 # Stdlib
16 import inspect
16 import inspect
17 import io
17 import io
18 import os
18 import os
19 import re
19 import re
20 import sys
20 import sys
21 import ast
21 import ast
22 from itertools import chain
22 from itertools import chain
23 from urllib.request import urlopen
23 from urllib.request import urlopen
24 from urllib.parse import urlencode
24 from urllib.parse import urlencode
25
25
26 # Our own packages
26 # Our own packages
27 from IPython.core.error import TryNext, StdinNotImplementedError, UsageError
27 from IPython.core.error import TryNext, StdinNotImplementedError, UsageError
28 from IPython.core.macro import Macro
28 from IPython.core.macro import Macro
29 from IPython.core.magic import Magics, magics_class, line_magic
29 from IPython.core.magic import Magics, magics_class, line_magic
30 from IPython.core.oinspect import find_file, find_source_lines
30 from IPython.core.oinspect import find_file, find_source_lines
31 from IPython.testing.skipdoctest import skip_doctest
31 from IPython.testing.skipdoctest import skip_doctest
32 from IPython.utils.contexts import preserve_keys
32 from IPython.utils.contexts import preserve_keys
33 from IPython.utils.path import get_py_filename
33 from IPython.utils.path import get_py_filename
34 from warnings import warn
34 from warnings import warn
35 from logging import error
35 from logging import 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 split by lines.
57 ready to use as a slice of the content split 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 def extract_symbols(code, symbols):
84 def extract_symbols(code, symbols):
85 """
85 """
86 Return a tuple (blocks, not_found)
86 Return a tuple (blocks, not_found)
87 where ``blocks`` is a list of code fragments
87 where ``blocks`` is a list of code fragments
88 for each symbol parsed from code, and ``not_found`` are
88 for each symbol parsed from code, and ``not_found`` are
89 symbols not found in the code.
89 symbols not found in the code.
90
90
91 For example::
91 For example::
92
92
93 In [1]: code = '''a = 10
93 In [1]: code = '''a = 10
94 ...: def b(): return 42
94 ...: def b(): return 42
95 ...: class A: pass'''
95 ...: class A: pass'''
96
96
97 In [2]: extract_symbols(code, 'A,b,z')
97 In [2]: extract_symbols(code, 'A,b,z')
98 Out[2]: (['class A: pass\\n', 'def b(): return 42\\n'], ['z'])
98 Out[2]: (['class A: pass\\n', 'def b(): return 42\\n'], ['z'])
99 """
99 """
100 symbols = symbols.split(',')
100 symbols = symbols.split(',')
101
101
102 # this will raise SyntaxError if code isn't valid Python
102 # this will raise SyntaxError if code isn't valid Python
103 py_code = ast.parse(code)
103 py_code = ast.parse(code)
104
104
105 marks = [(getattr(s, 'name', None), s.lineno) for s in py_code.body]
105 marks = [(getattr(s, 'name', None), s.lineno) for s in py_code.body]
106 code = code.split('\n')
106 code = code.split('\n')
107
107
108 symbols_lines = {}
108 symbols_lines = {}
109
109
110 # we already know the start_lineno of each symbol (marks).
110 # we already know the start_lineno of each symbol (marks).
111 # To find each end_lineno, we traverse in reverse order until each
111 # To find each end_lineno, we traverse in reverse order until each
112 # non-blank line
112 # non-blank line
113 end = len(code)
113 end = len(code)
114 for name, start in reversed(marks):
114 for name, start in reversed(marks):
115 while not code[end - 1].strip():
115 while not code[end - 1].strip():
116 end -= 1
116 end -= 1
117 if name:
117 if name:
118 symbols_lines[name] = (start - 1, end)
118 symbols_lines[name] = (start - 1, end)
119 end = start - 1
119 end = start - 1
120
120
121 # Now symbols_lines is a map
121 # Now symbols_lines is a map
122 # {'symbol_name': (start_lineno, end_lineno), ...}
122 # {'symbol_name': (start_lineno, end_lineno), ...}
123
123
124 # fill a list with chunks of codes for each requested symbol
124 # fill a list with chunks of codes for each requested symbol
125 blocks = []
125 blocks = []
126 not_found = []
126 not_found = []
127 for symbol in symbols:
127 for symbol in symbols:
128 if symbol in symbols_lines:
128 if symbol in symbols_lines:
129 start, end = symbols_lines[symbol]
129 start, end = symbols_lines[symbol]
130 blocks.append('\n'.join(code[start:end]) + '\n')
130 blocks.append('\n'.join(code[start:end]) + '\n')
131 else:
131 else:
132 not_found.append(symbol)
132 not_found.append(symbol)
133
133
134 return blocks, not_found
134 return blocks, not_found
135
135
136 def strip_initial_indent(lines):
136 def strip_initial_indent(lines):
137 """For %load, strip indent from lines until finding an unindented line.
137 """For %load, strip indent from lines until finding an unindented line.
138
138
139 https://github.com/ipython/ipython/issues/9775
139 https://github.com/ipython/ipython/issues/9775
140 """
140 """
141 indent_re = re.compile(r'\s+')
141 indent_re = re.compile(r'\s+')
142
142
143 it = iter(lines)
143 it = iter(lines)
144 first_line = next(it)
144 first_line = next(it)
145 indent_match = indent_re.match(first_line)
145 indent_match = indent_re.match(first_line)
146
146
147 if indent_match:
147 if indent_match:
148 # First line was indented
148 # First line was indented
149 indent = indent_match.group()
149 indent = indent_match.group()
150 yield first_line[len(indent):]
150 yield first_line[len(indent):]
151
151
152 for line in it:
152 for line in it:
153 if line.startswith(indent):
153 if line.startswith(indent):
154 yield line[len(indent):]
154 yield line[len(indent):]
155 else:
155 else:
156 # Less indented than the first line - stop dedenting
156 # Less indented than the first line - stop dedenting
157 yield line
157 yield line
158 break
158 break
159 else:
159 else:
160 yield first_line
160 yield first_line
161
161
162 # Pass the remaining lines through without dedenting
162 # Pass the remaining lines through without dedenting
163 for line in it:
163 for line in it:
164 yield line
164 yield line
165
165
166
166
167 class InteractivelyDefined(Exception):
167 class InteractivelyDefined(Exception):
168 """Exception for interactively defined variable in magic_edit"""
168 """Exception for interactively defined variable in magic_edit"""
169 def __init__(self, index):
169 def __init__(self, index):
170 self.index = index
170 self.index = index
171
171
172
172
173 @magics_class
173 @magics_class
174 class CodeMagics(Magics):
174 class CodeMagics(Magics):
175 """Magics related to code management (loading, saving, editing, ...)."""
175 """Magics related to code management (loading, saving, editing, ...)."""
176
176
177 def __init__(self, *args, **kwargs):
177 def __init__(self, *args, **kwargs):
178 self._knowntemps = set()
178 self._knowntemps = set()
179 super(CodeMagics, self).__init__(*args, **kwargs)
179 super(CodeMagics, self).__init__(*args, **kwargs)
180
180
181 @line_magic
181 @line_magic
182 def save(self, parameter_s=''):
182 def save(self, parameter_s=''):
183 """Save a set of lines or a macro to a given filename.
183 """Save a set of lines or a macro to a given filename.
184
184
185 Usage:\\
185 Usage:\\
186 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
186 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
187
187
188 Options:
188 Options:
189
189
190 -r: use 'raw' input. By default, the 'processed' history is used,
190 -r: use 'raw' input. By default, the 'processed' history is used,
191 so that magics are loaded in their transformed version to valid
191 so that magics are loaded in their transformed version to valid
192 Python. If this option is given, the raw input as typed as the
192 Python. If this option is given, the raw input as typed as the
193 command line is used instead.
193 command line is used instead.
194
194
195 -f: force overwrite. If file exists, %save will prompt for overwrite
195 -f: force overwrite. If file exists, %save will prompt for overwrite
196 unless -f is given.
196 unless -f is given.
197
197
198 -a: append to the file instead of overwriting it.
198 -a: append to the file instead of overwriting it.
199
199
200 This function uses the same syntax as %history for input ranges,
200 This function uses the same syntax as %history for input ranges,
201 then saves the lines to the filename you specify.
201 then saves the lines to the filename you specify.
202
202
203 It adds a '.py' extension to the file if you don't do so yourself, and
203 It adds a '.py' extension to the file if you don't do so yourself, and
204 it asks for confirmation before overwriting existing files.
204 it asks for confirmation before overwriting existing files.
205
205
206 If `-r` option is used, the default extension is `.ipy`.
206 If `-r` option is used, the default extension is `.ipy`.
207 """
207 """
208
208
209 opts,args = self.parse_options(parameter_s,'fra',mode='list')
209 opts,args = self.parse_options(parameter_s,'fra',mode='list')
210 if not args:
210 if not args:
211 raise UsageError('Missing filename.')
211 raise UsageError('Missing filename.')
212 raw = 'r' in opts
212 raw = 'r' in opts
213 force = 'f' in opts
213 force = 'f' in opts
214 append = 'a' in opts
214 append = 'a' in opts
215 mode = 'a' if append else 'w'
215 mode = 'a' if append else 'w'
216 ext = '.ipy' if raw else '.py'
216 ext = '.ipy' if raw else '.py'
217 fname, codefrom = args[0], " ".join(args[1:])
217 fname, codefrom = args[0], " ".join(args[1:])
218 if not fname.endswith(('.py','.ipy')):
218 if not fname.endswith(('.py','.ipy')):
219 fname += ext
219 fname += ext
220 file_exists = os.path.isfile(fname)
220 file_exists = os.path.isfile(fname)
221 if file_exists and not force and not append:
221 if file_exists and not force and not append:
222 try:
222 try:
223 overwrite = self.shell.ask_yes_no('File `%s` exists. Overwrite (y/[N])? ' % fname, default='n')
223 overwrite = self.shell.ask_yes_no('File `%s` exists. Overwrite (y/[N])? ' % fname, default='n')
224 except StdinNotImplementedError:
224 except StdinNotImplementedError:
225 print("File `%s` exists. Use `%%save -f %s` to force overwrite" % (fname, parameter_s))
225 print("File `%s` exists. Use `%%save -f %s` to force overwrite" % (fname, parameter_s))
226 return
226 return
227 if not overwrite :
227 if not overwrite :
228 print('Operation cancelled.')
228 print('Operation cancelled.')
229 return
229 return
230 try:
230 try:
231 cmds = self.shell.find_user_code(codefrom,raw)
231 cmds = self.shell.find_user_code(codefrom,raw)
232 except (TypeError, ValueError) as e:
232 except (TypeError, ValueError) as e:
233 print(e.args[0])
233 print(e.args[0])
234 return
234 return
235 with io.open(fname, mode, encoding="utf-8") as f:
235 with io.open(fname, mode, encoding="utf-8") as f:
236 if not file_exists or not append:
236 if not file_exists or not append:
237 f.write("# coding: utf-8\n")
237 f.write("# coding: utf-8\n")
238 f.write(cmds)
238 f.write(cmds)
239 # make sure we end on a newline
239 # make sure we end on a newline
240 if not cmds.endswith('\n'):
240 if not cmds.endswith('\n'):
241 f.write('\n')
241 f.write('\n')
242 print('The following commands were written to file `%s`:' % fname)
242 print('The following commands were written to file `%s`:' % fname)
243 print(cmds)
243 print(cmds)
244
244
245 @line_magic
245 @line_magic
246 def pastebin(self, parameter_s=''):
246 def pastebin(self, parameter_s=''):
247 """Upload code to dpaste's paste bin, returning the URL.
247 """Upload code to dpaste's paste bin, returning the URL.
248
248
249 Usage:\\
249 Usage:\\
250 %pastebin [-d "Custom description"] 1-7
250 %pastebin [-d "Custom description"] 1-7
251
251
252 The argument can be an input history range, a filename, or the name of a
252 The argument can be an input history range, a filename, or the name of a
253 string or macro.
253 string or macro.
254
254
255 Options:
255 Options:
256
256
257 -d: Pass a custom description for the gist. The default will say
257 -d: Pass a custom description for the gist. The default will say
258 "Pasted from IPython".
258 "Pasted from IPython".
259 """
259 """
260 opts, args = self.parse_options(parameter_s, 'd:')
260 opts, args = self.parse_options(parameter_s, 'd:')
261
261
262 try:
262 try:
263 code = self.shell.find_user_code(args)
263 code = self.shell.find_user_code(args)
264 except (ValueError, TypeError) as e:
264 except (ValueError, TypeError) as e:
265 print(e.args[0])
265 print(e.args[0])
266 return
266 return
267
267
268 post_data = urlencode({
268 post_data = urlencode({
269 "title": opts.get('d', "Pasted from IPython"),
269 "title": opts.get('d', "Pasted from IPython"),
270 "syntax": "python3",
270 "syntax": "python3",
271 "content": code
271 "content": code
272 }).encode('utf-8')
272 }).encode('utf-8')
273
273
274 response = urlopen("http://dpaste.com/api/v2/", post_data)
274 response = urlopen("http://dpaste.com/api/v2/", post_data)
275 return response.headers.get('Location')
275 return response.headers.get('Location')
276
276
277 @line_magic
277 @line_magic
278 def loadpy(self, arg_s):
278 def loadpy(self, arg_s):
279 """Alias of `%load`
279 """Alias of `%load`
280
280
281 `%loadpy` has gained some flexibility and dropped the requirement of a `.py`
281 `%loadpy` has gained some flexibility and dropped the requirement of a `.py`
282 extension. So it has been renamed simply into %load. You can look at
282 extension. So it has been renamed simply into %load. You can look at
283 `%load`'s docstring for more info.
283 `%load`'s docstring for more info.
284 """
284 """
285 self.load(arg_s)
285 self.load(arg_s)
286
286
287 @line_magic
287 @line_magic
288 def load(self, arg_s):
288 def load(self, arg_s):
289 """Load code into the current frontend.
289 """Load code into the current frontend.
290
290
291 Usage:\\
291 Usage:\\
292 %load [options] source
292 %load [options] source
293
293
294 where source can be a filename, URL, input history range, macro, or
294 where source can be a filename, URL, input history range, macro, or
295 element in the user namespace
295 element in the user namespace
296
296
297 Options:
297 Options:
298
298
299 -r <lines>: Specify lines or ranges of lines to load from the source.
299 -r <lines>: Specify lines or ranges of lines to load from the source.
300 Ranges could be specified as x-y (x..y) or in python-style x:y
300 Ranges could be specified as x-y (x..y) or in python-style x:y
301 (x..(y-1)). Both limits x and y can be left blank (meaning the
301 (x..(y-1)). Both limits x and y can be left blank (meaning the
302 beginning and end of the file, respectively).
302 beginning and end of the file, respectively).
303
303
304 -s <symbols>: Specify function or classes to load from python source.
304 -s <symbols>: Specify function or classes to load from python source.
305
305
306 -y : Don't ask confirmation for loading source above 200 000 characters.
306 -y : Don't ask confirmation for loading source above 200 000 characters.
307
307
308 -n : Include the user's namespace when searching for source code.
308 -n : Include the user's namespace when searching for source code.
309
309
310 This magic command can either take a local filename, a URL, an history
310 This magic command can either take a local filename, a URL, an history
311 range (see %history) or a macro as argument, it will prompt for
311 range (see %history) or a macro as argument, it will prompt for
312 confirmation before loading source with more than 200 000 characters, unless
312 confirmation before loading source with more than 200 000 characters, unless
313 -y flag is passed or if the frontend does not support raw_input::
313 -y flag is passed or if the frontend does not support raw_input::
314
314
315 %load myscript.py
315 %load myscript.py
316 %load 7-27
316 %load 7-27
317 %load myMacro
317 %load myMacro
318 %load http://www.example.com/myscript.py
318 %load http://www.example.com/myscript.py
319 %load -r 5-10 myscript.py
319 %load -r 5-10 myscript.py
320 %load -r 10-20,30,40: foo.py
320 %load -r 10-20,30,40: foo.py
321 %load -s MyClass,wonder_function myscript.py
321 %load -s MyClass,wonder_function myscript.py
322 %load -n MyClass
322 %load -n MyClass
323 %load -n my_module.wonder_function
323 %load -n my_module.wonder_function
324 """
324 """
325 opts,args = self.parse_options(arg_s,'yns:r:')
325 opts,args = self.parse_options(arg_s,'yns:r:')
326
326
327 if not args:
327 if not args:
328 raise UsageError('Missing filename, URL, input history range, '
328 raise UsageError('Missing filename, URL, input history range, '
329 'macro, or element in the user namespace.')
329 'macro, or element in the user namespace.')
330
330
331 search_ns = 'n' in opts
331 search_ns = 'n' in opts
332
332
333 contents = self.shell.find_user_code(args, search_ns=search_ns)
333 contents = self.shell.find_user_code(args, search_ns=search_ns)
334
334
335 if 's' in opts:
335 if 's' in opts:
336 try:
336 try:
337 blocks, not_found = extract_symbols(contents, opts['s'])
337 blocks, not_found = extract_symbols(contents, opts['s'])
338 except SyntaxError:
338 except SyntaxError:
339 # non python code
339 # non python code
340 error("Unable to parse the input as valid Python code")
340 error("Unable to parse the input as valid Python code")
341 return
341 return
342
342
343 if len(not_found) == 1:
343 if len(not_found) == 1:
344 warn('The symbol `%s` was not found' % not_found[0])
344 warn('The symbol `%s` was not found' % not_found[0])
345 elif len(not_found) > 1:
345 elif len(not_found) > 1:
346 warn('The symbols %s were not found' % get_text_list(not_found,
346 warn('The symbols %s were not found' % get_text_list(not_found,
347 wrap_item_with='`')
347 wrap_item_with='`')
348 )
348 )
349
349
350 contents = '\n'.join(blocks)
350 contents = '\n'.join(blocks)
351
351
352 if 'r' in opts:
352 if 'r' in opts:
353 ranges = opts['r'].replace(',', ' ')
353 ranges = opts['r'].replace(',', ' ')
354 lines = contents.split('\n')
354 lines = contents.split('\n')
355 slices = extract_code_ranges(ranges)
355 slices = extract_code_ranges(ranges)
356 contents = [lines[slice(*slc)] for slc in slices]
356 contents = [lines[slice(*slc)] for slc in slices]
357 contents = '\n'.join(strip_initial_indent(chain.from_iterable(contents)))
357 contents = '\n'.join(strip_initial_indent(chain.from_iterable(contents)))
358
358
359 l = len(contents)
359 l = len(contents)
360
360
361 # 200 000 is ~ 2500 full 80 character lines
361 # 200 000 is ~ 2500 full 80 character lines
362 # so in average, more than 5000 lines
362 # so in average, more than 5000 lines
363 if l > 200000 and 'y' not in opts:
363 if l > 200000 and 'y' not in opts:
364 try:
364 try:
365 ans = self.shell.ask_yes_no(("The text you're trying to load seems pretty big"\
365 ans = self.shell.ask_yes_no(("The text you're trying to load seems pretty big"\
366 " (%d characters). Continue (y/[N]) ?" % l), default='n' )
366 " (%d characters). Continue (y/[N]) ?" % l), default='n' )
367 except StdinNotImplementedError:
367 except StdinNotImplementedError:
368 #assume yes if raw input not implemented
368 #assume yes if raw input not implemented
369 ans = True
369 ans = True
370
370
371 if ans is False :
371 if ans is False :
372 print('Operation cancelled.')
372 print('Operation cancelled.')
373 return
373 return
374
374
375 contents = "# %load {}\n".format(arg_s) + contents
375 contents = "# %load {}\n".format(arg_s) + contents
376
376
377 self.shell.set_next_input(contents, replace=True)
377 self.shell.set_next_input(contents, replace=True)
378
378
379 @staticmethod
379 @staticmethod
380 def _find_edit_target(shell, args, opts, last_call):
380 def _find_edit_target(shell, args, opts, last_call):
381 """Utility method used by magic_edit to find what to edit."""
381 """Utility method used by magic_edit to find what to edit."""
382
382
383 def make_filename(arg):
383 def make_filename(arg):
384 "Make a filename from the given args"
384 "Make a filename from the given args"
385 try:
385 try:
386 filename = get_py_filename(arg)
386 filename = get_py_filename(arg)
387 except IOError:
387 except IOError:
388 # If it ends with .py but doesn't already exist, assume we want
388 # If it ends with .py but doesn't already exist, assume we want
389 # a new file.
389 # a new file.
390 if arg.endswith('.py'):
390 if arg.endswith('.py'):
391 filename = arg
391 filename = arg
392 else:
392 else:
393 filename = None
393 filename = None
394 return filename
394 return filename
395
395
396 # Set a few locals from the options for convenience:
396 # Set a few locals from the options for convenience:
397 opts_prev = 'p' in opts
397 opts_prev = 'p' in opts
398 opts_raw = 'r' in opts
398 opts_raw = 'r' in opts
399
399
400 # custom exceptions
400 # custom exceptions
401 class DataIsObject(Exception): pass
401 class DataIsObject(Exception): pass
402
402
403 # Default line number value
403 # Default line number value
404 lineno = opts.get('n',None)
404 lineno = opts.get('n',None)
405
405
406 if opts_prev:
406 if opts_prev:
407 args = '_%s' % last_call[0]
407 args = '_%s' % last_call[0]
408 if args not in shell.user_ns:
408 if args not in shell.user_ns:
409 args = last_call[1]
409 args = last_call[1]
410
410
411 # by default this is done with temp files, except when the given
411 # by default this is done with temp files, except when the given
412 # arg is a filename
412 # arg is a filename
413 use_temp = True
413 use_temp = True
414
414
415 data = ''
415 data = ''
416
416
417 # First, see if the arguments should be a filename.
417 # First, see if the arguments should be a filename.
418 filename = make_filename(args)
418 filename = make_filename(args)
419 if filename:
419 if filename:
420 use_temp = False
420 use_temp = False
421 elif args:
421 elif args:
422 # Mode where user specifies ranges of lines, like in %macro.
422 # Mode where user specifies ranges of lines, like in %macro.
423 data = shell.extract_input_lines(args, opts_raw)
423 data = shell.extract_input_lines(args, opts_raw)
424 if not data:
424 if not data:
425 try:
425 try:
426 # Load the parameter given as a variable. If not a string,
426 # Load the parameter given as a variable. If not a string,
427 # process it as an object instead (below)
427 # process it as an object instead (below)
428
428
429 #print '*** args',args,'type',type(args) # dbg
429 #print '*** args',args,'type',type(args) # dbg
430 data = eval(args, shell.user_ns)
430 data = eval(args, shell.user_ns)
431 if not isinstance(data, str):
431 if not isinstance(data, str):
432 raise DataIsObject
432 raise DataIsObject
433
433
434 except (NameError,SyntaxError):
434 except (NameError,SyntaxError):
435 # given argument is not a variable, try as a filename
435 # given argument is not a variable, try as a filename
436 filename = make_filename(args)
436 filename = make_filename(args)
437 if filename is None:
437 if filename is None:
438 warn("Argument given (%s) can't be found as a variable "
438 warn("Argument given (%s) can't be found as a variable "
439 "or as a filename." % args)
439 "or as a filename." % args)
440 return (None, None, None)
440 return (None, None, None)
441 use_temp = False
441 use_temp = False
442
442
443 except DataIsObject:
443 except DataIsObject as e:
444 # macros have a special edit function
444 # macros have a special edit function
445 if isinstance(data, Macro):
445 if isinstance(data, Macro):
446 raise MacroToEdit(data)
446 raise MacroToEdit(data) from e
447
447
448 # For objects, try to edit the file where they are defined
448 # For objects, try to edit the file where they are defined
449 filename = find_file(data)
449 filename = find_file(data)
450 if filename:
450 if filename:
451 if 'fakemodule' in filename.lower() and \
451 if 'fakemodule' in filename.lower() and \
452 inspect.isclass(data):
452 inspect.isclass(data):
453 # class created by %edit? Try to find source
453 # class created by %edit? Try to find source
454 # by looking for method definitions instead, the
454 # by looking for method definitions instead, the
455 # __module__ in those classes is FakeModule.
455 # __module__ in those classes is FakeModule.
456 attrs = [getattr(data, aname) for aname in dir(data)]
456 attrs = [getattr(data, aname) for aname in dir(data)]
457 for attr in attrs:
457 for attr in attrs:
458 if not inspect.ismethod(attr):
458 if not inspect.ismethod(attr):
459 continue
459 continue
460 filename = find_file(attr)
460 filename = find_file(attr)
461 if filename and \
461 if filename and \
462 'fakemodule' not in filename.lower():
462 'fakemodule' not in filename.lower():
463 # change the attribute to be the edit
463 # change the attribute to be the edit
464 # target instead
464 # target instead
465 data = attr
465 data = attr
466 break
466 break
467
467
468 m = ipython_input_pat.match(os.path.basename(filename))
468 m = ipython_input_pat.match(os.path.basename(filename))
469 if m:
469 if m:
470 raise InteractivelyDefined(int(m.groups()[0]))
470 raise InteractivelyDefined(int(m.groups()[0])) from e
471
471
472 datafile = 1
472 datafile = 1
473 if filename is None:
473 if filename is None:
474 filename = make_filename(args)
474 filename = make_filename(args)
475 datafile = 1
475 datafile = 1
476 if filename is not None:
476 if filename is not None:
477 # only warn about this if we get a real name
477 # only warn about this if we get a real name
478 warn('Could not find file where `%s` is defined.\n'
478 warn('Could not find file where `%s` is defined.\n'
479 'Opening a file named `%s`' % (args, filename))
479 'Opening a file named `%s`' % (args, filename))
480 # Now, make sure we can actually read the source (if it was
480 # Now, make sure we can actually read the source (if it was
481 # in a temp file it's gone by now).
481 # in a temp file it's gone by now).
482 if datafile:
482 if datafile:
483 if lineno is None:
483 if lineno is None:
484 lineno = find_source_lines(data)
484 lineno = find_source_lines(data)
485 if lineno is None:
485 if lineno is None:
486 filename = make_filename(args)
486 filename = make_filename(args)
487 if filename is None:
487 if filename is None:
488 warn('The file where `%s` was defined '
488 warn('The file where `%s` was defined '
489 'cannot be read or found.' % data)
489 'cannot be read or found.' % data)
490 return (None, None, None)
490 return (None, None, None)
491 use_temp = False
491 use_temp = False
492
492
493 if use_temp:
493 if use_temp:
494 filename = shell.mktempfile(data)
494 filename = shell.mktempfile(data)
495 print('IPython will make a temporary file named:',filename)
495 print('IPython will make a temporary file named:',filename)
496
496
497 # use last_call to remember the state of the previous call, but don't
497 # use last_call to remember the state of the previous call, but don't
498 # let it be clobbered by successive '-p' calls.
498 # let it be clobbered by successive '-p' calls.
499 try:
499 try:
500 last_call[0] = shell.displayhook.prompt_count
500 last_call[0] = shell.displayhook.prompt_count
501 if not opts_prev:
501 if not opts_prev:
502 last_call[1] = args
502 last_call[1] = args
503 except:
503 except:
504 pass
504 pass
505
505
506
506
507 return filename, lineno, use_temp
507 return filename, lineno, use_temp
508
508
509 def _edit_macro(self,mname,macro):
509 def _edit_macro(self,mname,macro):
510 """open an editor with the macro data in a file"""
510 """open an editor with the macro data in a file"""
511 filename = self.shell.mktempfile(macro.value)
511 filename = self.shell.mktempfile(macro.value)
512 self.shell.hooks.editor(filename)
512 self.shell.hooks.editor(filename)
513
513
514 # and make a new macro object, to replace the old one
514 # and make a new macro object, to replace the old one
515 with open(filename) as mfile:
515 with open(filename) as mfile:
516 mvalue = mfile.read()
516 mvalue = mfile.read()
517 self.shell.user_ns[mname] = Macro(mvalue)
517 self.shell.user_ns[mname] = Macro(mvalue)
518
518
519 @skip_doctest
519 @skip_doctest
520 @line_magic
520 @line_magic
521 def edit(self, parameter_s='',last_call=['','']):
521 def edit(self, parameter_s='',last_call=['','']):
522 """Bring up an editor and execute the resulting code.
522 """Bring up an editor and execute the resulting code.
523
523
524 Usage:
524 Usage:
525 %edit [options] [args]
525 %edit [options] [args]
526
526
527 %edit runs IPython's editor hook. The default version of this hook is
527 %edit runs IPython's editor hook. The default version of this hook is
528 set to call the editor specified by your $EDITOR environment variable.
528 set to call the editor specified by your $EDITOR environment variable.
529 If this isn't found, it will default to vi under Linux/Unix and to
529 If this isn't found, it will default to vi under Linux/Unix and to
530 notepad under Windows. See the end of this docstring for how to change
530 notepad under Windows. See the end of this docstring for how to change
531 the editor hook.
531 the editor hook.
532
532
533 You can also set the value of this editor via the
533 You can also set the value of this editor via the
534 ``TerminalInteractiveShell.editor`` option in your configuration file.
534 ``TerminalInteractiveShell.editor`` option in your configuration file.
535 This is useful if you wish to use a different editor from your typical
535 This is useful if you wish to use a different editor from your typical
536 default with IPython (and for Windows users who typically don't set
536 default with IPython (and for Windows users who typically don't set
537 environment variables).
537 environment variables).
538
538
539 This command allows you to conveniently edit multi-line code right in
539 This command allows you to conveniently edit multi-line code right in
540 your IPython session.
540 your IPython session.
541
541
542 If called without arguments, %edit opens up an empty editor with a
542 If called without arguments, %edit opens up an empty editor with a
543 temporary file and will execute the contents of this file when you
543 temporary file and will execute the contents of this file when you
544 close it (don't forget to save it!).
544 close it (don't forget to save it!).
545
545
546
546
547 Options:
547 Options:
548
548
549 -n <number>: open the editor at a specified line number. By default,
549 -n <number>: open the editor at a specified line number. By default,
550 the IPython editor hook uses the unix syntax 'editor +N filename', but
550 the IPython editor hook uses the unix syntax 'editor +N filename', but
551 you can configure this by providing your own modified hook if your
551 you can configure this by providing your own modified hook if your
552 favorite editor supports line-number specifications with a different
552 favorite editor supports line-number specifications with a different
553 syntax.
553 syntax.
554
554
555 -p: this will call the editor with the same data as the previous time
555 -p: this will call the editor with the same data as the previous time
556 it was used, regardless of how long ago (in your current session) it
556 it was used, regardless of how long ago (in your current session) it
557 was.
557 was.
558
558
559 -r: use 'raw' input. This option only applies to input taken from the
559 -r: use 'raw' input. This option only applies to input taken from the
560 user's history. By default, the 'processed' history is used, so that
560 user's history. By default, the 'processed' history is used, so that
561 magics are loaded in their transformed version to valid Python. If
561 magics are loaded in their transformed version to valid Python. If
562 this option is given, the raw input as typed as the command line is
562 this option is given, the raw input as typed as the command line is
563 used instead. When you exit the editor, it will be executed by
563 used instead. When you exit the editor, it will be executed by
564 IPython's own processor.
564 IPython's own processor.
565
565
566 -x: do not execute the edited code immediately upon exit. This is
566 -x: do not execute the edited code immediately upon exit. This is
567 mainly useful if you are editing programs which need to be called with
567 mainly useful if you are editing programs which need to be called with
568 command line arguments, which you can then do using %run.
568 command line arguments, which you can then do using %run.
569
569
570
570
571 Arguments:
571 Arguments:
572
572
573 If arguments are given, the following possibilities exist:
573 If arguments are given, the following possibilities exist:
574
574
575 - If the argument is a filename, IPython will load that into the
575 - If the argument is a filename, IPython will load that into the
576 editor. It will execute its contents with execfile() when you exit,
576 editor. It will execute its contents with execfile() when you exit,
577 loading any code in the file into your interactive namespace.
577 loading any code in the file into your interactive namespace.
578
578
579 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
579 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
580 The syntax is the same as in the %history magic.
580 The syntax is the same as in the %history magic.
581
581
582 - If the argument is a string variable, its contents are loaded
582 - If the argument is a string variable, its contents are loaded
583 into the editor. You can thus edit any string which contains
583 into the editor. You can thus edit any string which contains
584 python code (including the result of previous edits).
584 python code (including the result of previous edits).
585
585
586 - If the argument is the name of an object (other than a string),
586 - If the argument is the name of an object (other than a string),
587 IPython will try to locate the file where it was defined and open the
587 IPython will try to locate the file where it was defined and open the
588 editor at the point where it is defined. You can use `%edit function`
588 editor at the point where it is defined. You can use `%edit function`
589 to load an editor exactly at the point where 'function' is defined,
589 to load an editor exactly at the point where 'function' is defined,
590 edit it and have the file be executed automatically.
590 edit it and have the file be executed automatically.
591
591
592 - If the object is a macro (see %macro for details), this opens up your
592 - If the object is a macro (see %macro for details), this opens up your
593 specified editor with a temporary file containing the macro's data.
593 specified editor with a temporary file containing the macro's data.
594 Upon exit, the macro is reloaded with the contents of the file.
594 Upon exit, the macro is reloaded with the contents of the file.
595
595
596 Note: opening at an exact line is only supported under Unix, and some
596 Note: opening at an exact line is only supported under Unix, and some
597 editors (like kedit and gedit up to Gnome 2.8) do not understand the
597 editors (like kedit and gedit up to Gnome 2.8) do not understand the
598 '+NUMBER' parameter necessary for this feature. Good editors like
598 '+NUMBER' parameter necessary for this feature. Good editors like
599 (X)Emacs, vi, jed, pico and joe all do.
599 (X)Emacs, vi, jed, pico and joe all do.
600
600
601 After executing your code, %edit will return as output the code you
601 After executing your code, %edit will return as output the code you
602 typed in the editor (except when it was an existing file). This way
602 typed in the editor (except when it was an existing file). This way
603 you can reload the code in further invocations of %edit as a variable,
603 you can reload the code in further invocations of %edit as a variable,
604 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
604 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
605 the output.
605 the output.
606
606
607 Note that %edit is also available through the alias %ed.
607 Note that %edit is also available through the alias %ed.
608
608
609 This is an example of creating a simple function inside the editor and
609 This is an example of creating a simple function inside the editor and
610 then modifying it. First, start up the editor::
610 then modifying it. First, start up the editor::
611
611
612 In [1]: edit
612 In [1]: edit
613 Editing... done. Executing edited code...
613 Editing... done. Executing edited code...
614 Out[1]: 'def foo():\\n print "foo() was defined in an editing
614 Out[1]: 'def foo():\\n print "foo() was defined in an editing
615 session"\\n'
615 session"\\n'
616
616
617 We can then call the function foo()::
617 We can then call the function foo()::
618
618
619 In [2]: foo()
619 In [2]: foo()
620 foo() was defined in an editing session
620 foo() was defined in an editing session
621
621
622 Now we edit foo. IPython automatically loads the editor with the
622 Now we edit foo. IPython automatically loads the editor with the
623 (temporary) file where foo() was previously defined::
623 (temporary) file where foo() was previously defined::
624
624
625 In [3]: edit foo
625 In [3]: edit foo
626 Editing... done. Executing edited code...
626 Editing... done. Executing edited code...
627
627
628 And if we call foo() again we get the modified version::
628 And if we call foo() again we get the modified version::
629
629
630 In [4]: foo()
630 In [4]: foo()
631 foo() has now been changed!
631 foo() has now been changed!
632
632
633 Here is an example of how to edit a code snippet successive
633 Here is an example of how to edit a code snippet successive
634 times. First we call the editor::
634 times. First we call the editor::
635
635
636 In [5]: edit
636 In [5]: edit
637 Editing... done. Executing edited code...
637 Editing... done. Executing edited code...
638 hello
638 hello
639 Out[5]: "print 'hello'\\n"
639 Out[5]: "print 'hello'\\n"
640
640
641 Now we call it again with the previous output (stored in _)::
641 Now we call it again with the previous output (stored in _)::
642
642
643 In [6]: edit _
643 In [6]: edit _
644 Editing... done. Executing edited code...
644 Editing... done. Executing edited code...
645 hello world
645 hello world
646 Out[6]: "print 'hello world'\\n"
646 Out[6]: "print 'hello world'\\n"
647
647
648 Now we call it with the output #8 (stored in _8, also as Out[8])::
648 Now we call it with the output #8 (stored in _8, also as Out[8])::
649
649
650 In [7]: edit _8
650 In [7]: edit _8
651 Editing... done. Executing edited code...
651 Editing... done. Executing edited code...
652 hello again
652 hello again
653 Out[7]: "print 'hello again'\\n"
653 Out[7]: "print 'hello again'\\n"
654
654
655
655
656 Changing the default editor hook:
656 Changing the default editor hook:
657
657
658 If you wish to write your own editor hook, you can put it in a
658 If you wish to write your own editor hook, you can put it in a
659 configuration file which you load at startup time. The default hook
659 configuration file which you load at startup time. The default hook
660 is defined in the IPython.core.hooks module, and you can use that as a
660 is defined in the IPython.core.hooks module, and you can use that as a
661 starting example for further modifications. That file also has
661 starting example for further modifications. That file also has
662 general instructions on how to set a new hook for use once you've
662 general instructions on how to set a new hook for use once you've
663 defined it."""
663 defined it."""
664 opts,args = self.parse_options(parameter_s,'prxn:')
664 opts,args = self.parse_options(parameter_s,'prxn:')
665
665
666 try:
666 try:
667 filename, lineno, is_temp = self._find_edit_target(self.shell,
667 filename, lineno, is_temp = self._find_edit_target(self.shell,
668 args, opts, last_call)
668 args, opts, last_call)
669 except MacroToEdit as e:
669 except MacroToEdit as e:
670 self._edit_macro(args, e.args[0])
670 self._edit_macro(args, e.args[0])
671 return
671 return
672 except InteractivelyDefined as e:
672 except InteractivelyDefined as e:
673 print("Editing In[%i]" % e.index)
673 print("Editing In[%i]" % e.index)
674 args = str(e.index)
674 args = str(e.index)
675 filename, lineno, is_temp = self._find_edit_target(self.shell,
675 filename, lineno, is_temp = self._find_edit_target(self.shell,
676 args, opts, last_call)
676 args, opts, last_call)
677 if filename is None:
677 if filename is None:
678 # nothing was found, warnings have already been issued,
678 # nothing was found, warnings have already been issued,
679 # just give up.
679 # just give up.
680 return
680 return
681
681
682 if is_temp:
682 if is_temp:
683 self._knowntemps.add(filename)
683 self._knowntemps.add(filename)
684 elif (filename in self._knowntemps):
684 elif (filename in self._knowntemps):
685 is_temp = True
685 is_temp = True
686
686
687
687
688 # do actual editing here
688 # do actual editing here
689 print('Editing...', end=' ')
689 print('Editing...', end=' ')
690 sys.stdout.flush()
690 sys.stdout.flush()
691 try:
691 try:
692 # Quote filenames that may have spaces in them
692 # Quote filenames that may have spaces in them
693 if ' ' in filename:
693 if ' ' in filename:
694 filename = "'%s'" % filename
694 filename = "'%s'" % filename
695 self.shell.hooks.editor(filename,lineno)
695 self.shell.hooks.editor(filename,lineno)
696 except TryNext:
696 except TryNext:
697 warn('Could not open editor')
697 warn('Could not open editor')
698 return
698 return
699
699
700 # XXX TODO: should this be generalized for all string vars?
700 # XXX TODO: should this be generalized for all string vars?
701 # For now, this is special-cased to blocks created by cpaste
701 # For now, this is special-cased to blocks created by cpaste
702 if args.strip() == 'pasted_block':
702 if args.strip() == 'pasted_block':
703 with open(filename, 'r') as f:
703 with open(filename, 'r') as f:
704 self.shell.user_ns['pasted_block'] = f.read()
704 self.shell.user_ns['pasted_block'] = f.read()
705
705
706 if 'x' in opts: # -x prevents actual execution
706 if 'x' in opts: # -x prevents actual execution
707 print()
707 print()
708 else:
708 else:
709 print('done. Executing edited code...')
709 print('done. Executing edited code...')
710 with preserve_keys(self.shell.user_ns, '__file__'):
710 with preserve_keys(self.shell.user_ns, '__file__'):
711 if not is_temp:
711 if not is_temp:
712 self.shell.user_ns['__file__'] = filename
712 self.shell.user_ns['__file__'] = filename
713 if 'r' in opts: # Untranslated IPython code
713 if 'r' in opts: # Untranslated IPython code
714 with open(filename, 'r') as f:
714 with open(filename, 'r') as f:
715 source = f.read()
715 source = f.read()
716 self.shell.run_cell(source, store_history=False)
716 self.shell.run_cell(source, store_history=False)
717 else:
717 else:
718 self.shell.safe_execfile(filename, self.shell.user_ns,
718 self.shell.safe_execfile(filename, self.shell.user_ns,
719 self.shell.user_ns)
719 self.shell.user_ns)
720
720
721 if is_temp:
721 if is_temp:
722 try:
722 try:
723 with open(filename) as f:
723 with open(filename) as f:
724 return f.read()
724 return f.read()
725 except IOError as msg:
725 except IOError as msg:
726 if msg.filename == filename:
726 if msg.filename == filename:
727 warn('File not found. Did you forget to save?')
727 warn('File not found. Did you forget to save?')
728 return
728 return
729 else:
729 else:
730 self.shell.showtraceback()
730 self.shell.showtraceback()
@@ -1,1490 +1,1490
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Implementation of execution-related magic functions."""
2 """Implementation of execution-related magic functions."""
3
3
4 # Copyright (c) IPython Development Team.
4 # Copyright (c) IPython Development Team.
5 # Distributed under the terms of the Modified BSD License.
5 # Distributed under the terms of the Modified BSD License.
6
6
7
7
8 import ast
8 import ast
9 import bdb
9 import bdb
10 import builtins as builtin_mod
10 import builtins as builtin_mod
11 import gc
11 import gc
12 import itertools
12 import itertools
13 import os
13 import os
14 import shlex
14 import shlex
15 import sys
15 import sys
16 import time
16 import time
17 import timeit
17 import timeit
18 import math
18 import math
19 import re
19 import re
20 from pdb import Restart
20 from pdb import Restart
21
21
22 import cProfile as profile
22 import cProfile as profile
23 import pstats
23 import pstats
24
24
25 from IPython.core import oinspect
25 from IPython.core import oinspect
26 from IPython.core import magic_arguments
26 from IPython.core import magic_arguments
27 from IPython.core import page
27 from IPython.core import page
28 from IPython.core.error import UsageError
28 from IPython.core.error import UsageError
29 from IPython.core.macro import Macro
29 from IPython.core.macro import Macro
30 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
30 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
31 line_cell_magic, on_off, needs_local_scope,
31 line_cell_magic, on_off, needs_local_scope,
32 no_var_expand)
32 no_var_expand)
33 from IPython.testing.skipdoctest import skip_doctest
33 from IPython.testing.skipdoctest import skip_doctest
34 from IPython.utils.contexts import preserve_keys
34 from IPython.utils.contexts import preserve_keys
35 from IPython.utils.capture import capture_output
35 from IPython.utils.capture import capture_output
36 from IPython.utils.ipstruct import Struct
36 from IPython.utils.ipstruct import Struct
37 from IPython.utils.module_paths import find_mod
37 from IPython.utils.module_paths import find_mod
38 from IPython.utils.path import get_py_filename, shellglob
38 from IPython.utils.path import get_py_filename, shellglob
39 from IPython.utils.timing import clock, clock2
39 from IPython.utils.timing import clock, clock2
40 from warnings import warn
40 from warnings import warn
41 from logging import error
41 from logging import error
42 from io import StringIO
42 from io import StringIO
43
43
44 if sys.version_info > (3,8):
44 if sys.version_info > (3,8):
45 from ast import Module
45 from ast import Module
46 else :
46 else :
47 # mock the new API, ignore second argument
47 # mock the new API, ignore second argument
48 # see https://github.com/ipython/ipython/issues/11590
48 # see https://github.com/ipython/ipython/issues/11590
49 from ast import Module as OriginalModule
49 from ast import Module as OriginalModule
50 Module = lambda nodelist, type_ignores: OriginalModule(nodelist)
50 Module = lambda nodelist, type_ignores: OriginalModule(nodelist)
51
51
52
52
53 #-----------------------------------------------------------------------------
53 #-----------------------------------------------------------------------------
54 # Magic implementation classes
54 # Magic implementation classes
55 #-----------------------------------------------------------------------------
55 #-----------------------------------------------------------------------------
56
56
57
57
58 class TimeitResult(object):
58 class TimeitResult(object):
59 """
59 """
60 Object returned by the timeit magic with info about the run.
60 Object returned by the timeit magic with info about the run.
61
61
62 Contains the following attributes :
62 Contains the following attributes :
63
63
64 loops: (int) number of loops done per measurement
64 loops: (int) number of loops done per measurement
65 repeat: (int) number of times the measurement has been repeated
65 repeat: (int) number of times the measurement has been repeated
66 best: (float) best execution time / number
66 best: (float) best execution time / number
67 all_runs: (list of float) execution time of each run (in s)
67 all_runs: (list of float) execution time of each run (in s)
68 compile_time: (float) time of statement compilation (s)
68 compile_time: (float) time of statement compilation (s)
69
69
70 """
70 """
71 def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
71 def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
72 self.loops = loops
72 self.loops = loops
73 self.repeat = repeat
73 self.repeat = repeat
74 self.best = best
74 self.best = best
75 self.worst = worst
75 self.worst = worst
76 self.all_runs = all_runs
76 self.all_runs = all_runs
77 self.compile_time = compile_time
77 self.compile_time = compile_time
78 self._precision = precision
78 self._precision = precision
79 self.timings = [ dt / self.loops for dt in all_runs]
79 self.timings = [ dt / self.loops for dt in all_runs]
80
80
81 @property
81 @property
82 def average(self):
82 def average(self):
83 return math.fsum(self.timings) / len(self.timings)
83 return math.fsum(self.timings) / len(self.timings)
84
84
85 @property
85 @property
86 def stdev(self):
86 def stdev(self):
87 mean = self.average
87 mean = self.average
88 return (math.fsum([(x - mean) ** 2 for x in self.timings]) / len(self.timings)) ** 0.5
88 return (math.fsum([(x - mean) ** 2 for x in self.timings]) / len(self.timings)) ** 0.5
89
89
90 def __str__(self):
90 def __str__(self):
91 pm = '+-'
91 pm = '+-'
92 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
92 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
93 try:
93 try:
94 u'\xb1'.encode(sys.stdout.encoding)
94 u'\xb1'.encode(sys.stdout.encoding)
95 pm = u'\xb1'
95 pm = u'\xb1'
96 except:
96 except:
97 pass
97 pass
98 return (
98 return (
99 u"{mean} {pm} {std} per loop (mean {pm} std. dev. of {runs} run{run_plural}, {loops} loop{loop_plural} each)"
99 u"{mean} {pm} {std} per loop (mean {pm} std. dev. of {runs} run{run_plural}, {loops} loop{loop_plural} each)"
100 .format(
100 .format(
101 pm = pm,
101 pm = pm,
102 runs = self.repeat,
102 runs = self.repeat,
103 loops = self.loops,
103 loops = self.loops,
104 loop_plural = "" if self.loops == 1 else "s",
104 loop_plural = "" if self.loops == 1 else "s",
105 run_plural = "" if self.repeat == 1 else "s",
105 run_plural = "" if self.repeat == 1 else "s",
106 mean = _format_time(self.average, self._precision),
106 mean = _format_time(self.average, self._precision),
107 std = _format_time(self.stdev, self._precision))
107 std = _format_time(self.stdev, self._precision))
108 )
108 )
109
109
110 def _repr_pretty_(self, p , cycle):
110 def _repr_pretty_(self, p , cycle):
111 unic = self.__str__()
111 unic = self.__str__()
112 p.text(u'<TimeitResult : '+unic+u'>')
112 p.text(u'<TimeitResult : '+unic+u'>')
113
113
114
114
115 class TimeitTemplateFiller(ast.NodeTransformer):
115 class TimeitTemplateFiller(ast.NodeTransformer):
116 """Fill in the AST template for timing execution.
116 """Fill in the AST template for timing execution.
117
117
118 This is quite closely tied to the template definition, which is in
118 This is quite closely tied to the template definition, which is in
119 :meth:`ExecutionMagics.timeit`.
119 :meth:`ExecutionMagics.timeit`.
120 """
120 """
121 def __init__(self, ast_setup, ast_stmt):
121 def __init__(self, ast_setup, ast_stmt):
122 self.ast_setup = ast_setup
122 self.ast_setup = ast_setup
123 self.ast_stmt = ast_stmt
123 self.ast_stmt = ast_stmt
124
124
125 def visit_FunctionDef(self, node):
125 def visit_FunctionDef(self, node):
126 "Fill in the setup statement"
126 "Fill in the setup statement"
127 self.generic_visit(node)
127 self.generic_visit(node)
128 if node.name == "inner":
128 if node.name == "inner":
129 node.body[:1] = self.ast_setup.body
129 node.body[:1] = self.ast_setup.body
130
130
131 return node
131 return node
132
132
133 def visit_For(self, node):
133 def visit_For(self, node):
134 "Fill in the statement to be timed"
134 "Fill in the statement to be timed"
135 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
135 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
136 node.body = self.ast_stmt.body
136 node.body = self.ast_stmt.body
137 return node
137 return node
138
138
139
139
140 class Timer(timeit.Timer):
140 class Timer(timeit.Timer):
141 """Timer class that explicitly uses self.inner
141 """Timer class that explicitly uses self.inner
142
142
143 which is an undocumented implementation detail of CPython,
143 which is an undocumented implementation detail of CPython,
144 not shared by PyPy.
144 not shared by PyPy.
145 """
145 """
146 # Timer.timeit copied from CPython 3.4.2
146 # Timer.timeit copied from CPython 3.4.2
147 def timeit(self, number=timeit.default_number):
147 def timeit(self, number=timeit.default_number):
148 """Time 'number' executions of the main statement.
148 """Time 'number' executions of the main statement.
149
149
150 To be precise, this executes the setup statement once, and
150 To be precise, this executes the setup statement once, and
151 then returns the time it takes to execute the main statement
151 then returns the time it takes to execute the main statement
152 a number of times, as a float measured in seconds. The
152 a number of times, as a float measured in seconds. The
153 argument is the number of times through the loop, defaulting
153 argument is the number of times through the loop, defaulting
154 to one million. The main statement, the setup statement and
154 to one million. The main statement, the setup statement and
155 the timer function to be used are passed to the constructor.
155 the timer function to be used are passed to the constructor.
156 """
156 """
157 it = itertools.repeat(None, number)
157 it = itertools.repeat(None, number)
158 gcold = gc.isenabled()
158 gcold = gc.isenabled()
159 gc.disable()
159 gc.disable()
160 try:
160 try:
161 timing = self.inner(it, self.timer)
161 timing = self.inner(it, self.timer)
162 finally:
162 finally:
163 if gcold:
163 if gcold:
164 gc.enable()
164 gc.enable()
165 return timing
165 return timing
166
166
167
167
168 @magics_class
168 @magics_class
169 class ExecutionMagics(Magics):
169 class ExecutionMagics(Magics):
170 """Magics related to code execution, debugging, profiling, etc.
170 """Magics related to code execution, debugging, profiling, etc.
171
171
172 """
172 """
173
173
174 def __init__(self, shell):
174 def __init__(self, shell):
175 super(ExecutionMagics, self).__init__(shell)
175 super(ExecutionMagics, self).__init__(shell)
176 # Default execution function used to actually run user code.
176 # Default execution function used to actually run user code.
177 self.default_runner = None
177 self.default_runner = None
178
178
179 @skip_doctest
179 @skip_doctest
180 @no_var_expand
180 @no_var_expand
181 @line_cell_magic
181 @line_cell_magic
182 def prun(self, parameter_s='', cell=None):
182 def prun(self, parameter_s='', cell=None):
183
183
184 """Run a statement through the python code profiler.
184 """Run a statement through the python code profiler.
185
185
186 Usage, in line mode:
186 Usage, in line mode:
187 %prun [options] statement
187 %prun [options] statement
188
188
189 Usage, in cell mode:
189 Usage, in cell mode:
190 %%prun [options] [statement]
190 %%prun [options] [statement]
191 code...
191 code...
192 code...
192 code...
193
193
194 In cell mode, the additional code lines are appended to the (possibly
194 In cell mode, the additional code lines are appended to the (possibly
195 empty) statement in the first line. Cell mode allows you to easily
195 empty) statement in the first line. Cell mode allows you to easily
196 profile multiline blocks without having to put them in a separate
196 profile multiline blocks without having to put them in a separate
197 function.
197 function.
198
198
199 The given statement (which doesn't require quote marks) is run via the
199 The given statement (which doesn't require quote marks) is run via the
200 python profiler in a manner similar to the profile.run() function.
200 python profiler in a manner similar to the profile.run() function.
201 Namespaces are internally managed to work correctly; profile.run
201 Namespaces are internally managed to work correctly; profile.run
202 cannot be used in IPython because it makes certain assumptions about
202 cannot be used in IPython because it makes certain assumptions about
203 namespaces which do not hold under IPython.
203 namespaces which do not hold under IPython.
204
204
205 Options:
205 Options:
206
206
207 -l <limit>
207 -l <limit>
208 you can place restrictions on what or how much of the
208 you can place restrictions on what or how much of the
209 profile gets printed. The limit value can be:
209 profile gets printed. The limit value can be:
210
210
211 * A string: only information for function names containing this string
211 * A string: only information for function names containing this string
212 is printed.
212 is printed.
213
213
214 * An integer: only these many lines are printed.
214 * An integer: only these many lines are printed.
215
215
216 * A float (between 0 and 1): this fraction of the report is printed
216 * A float (between 0 and 1): this fraction of the report is printed
217 (for example, use a limit of 0.4 to see the topmost 40% only).
217 (for example, use a limit of 0.4 to see the topmost 40% only).
218
218
219 You can combine several limits with repeated use of the option. For
219 You can combine several limits with repeated use of the option. For
220 example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
220 example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
221 information about class constructors.
221 information about class constructors.
222
222
223 -r
223 -r
224 return the pstats.Stats object generated by the profiling. This
224 return the pstats.Stats object generated by the profiling. This
225 object has all the information about the profile in it, and you can
225 object has all the information about the profile in it, and you can
226 later use it for further analysis or in other functions.
226 later use it for further analysis or in other functions.
227
227
228 -s <key>
228 -s <key>
229 sort profile by given key. You can provide more than one key
229 sort profile by given key. You can provide more than one key
230 by using the option several times: '-s key1 -s key2 -s key3...'. The
230 by using the option several times: '-s key1 -s key2 -s key3...'. The
231 default sorting key is 'time'.
231 default sorting key is 'time'.
232
232
233 The following is copied verbatim from the profile documentation
233 The following is copied verbatim from the profile documentation
234 referenced below:
234 referenced below:
235
235
236 When more than one key is provided, additional keys are used as
236 When more than one key is provided, additional keys are used as
237 secondary criteria when the there is equality in all keys selected
237 secondary criteria when the there is equality in all keys selected
238 before them.
238 before them.
239
239
240 Abbreviations can be used for any key names, as long as the
240 Abbreviations can be used for any key names, as long as the
241 abbreviation is unambiguous. The following are the keys currently
241 abbreviation is unambiguous. The following are the keys currently
242 defined:
242 defined:
243
243
244 ============ =====================
244 ============ =====================
245 Valid Arg Meaning
245 Valid Arg Meaning
246 ============ =====================
246 ============ =====================
247 "calls" call count
247 "calls" call count
248 "cumulative" cumulative time
248 "cumulative" cumulative time
249 "file" file name
249 "file" file name
250 "module" file name
250 "module" file name
251 "pcalls" primitive call count
251 "pcalls" primitive call count
252 "line" line number
252 "line" line number
253 "name" function name
253 "name" function name
254 "nfl" name/file/line
254 "nfl" name/file/line
255 "stdname" standard name
255 "stdname" standard name
256 "time" internal time
256 "time" internal time
257 ============ =====================
257 ============ =====================
258
258
259 Note that all sorts on statistics are in descending order (placing
259 Note that all sorts on statistics are in descending order (placing
260 most time consuming items first), where as name, file, and line number
260 most time consuming items first), where as name, file, and line number
261 searches are in ascending order (i.e., alphabetical). The subtle
261 searches are in ascending order (i.e., alphabetical). The subtle
262 distinction between "nfl" and "stdname" is that the standard name is a
262 distinction between "nfl" and "stdname" is that the standard name is a
263 sort of the name as printed, which means that the embedded line
263 sort of the name as printed, which means that the embedded line
264 numbers get compared in an odd way. For example, lines 3, 20, and 40
264 numbers get compared in an odd way. For example, lines 3, 20, and 40
265 would (if the file names were the same) appear in the string order
265 would (if the file names were the same) appear in the string order
266 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
266 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
267 line numbers. In fact, sort_stats("nfl") is the same as
267 line numbers. In fact, sort_stats("nfl") is the same as
268 sort_stats("name", "file", "line").
268 sort_stats("name", "file", "line").
269
269
270 -T <filename>
270 -T <filename>
271 save profile results as shown on screen to a text
271 save profile results as shown on screen to a text
272 file. The profile is still shown on screen.
272 file. The profile is still shown on screen.
273
273
274 -D <filename>
274 -D <filename>
275 save (via dump_stats) profile statistics to given
275 save (via dump_stats) profile statistics to given
276 filename. This data is in a format understood by the pstats module, and
276 filename. This data is in a format understood by the pstats module, and
277 is generated by a call to the dump_stats() method of profile
277 is generated by a call to the dump_stats() method of profile
278 objects. The profile is still shown on screen.
278 objects. The profile is still shown on screen.
279
279
280 -q
280 -q
281 suppress output to the pager. Best used with -T and/or -D above.
281 suppress output to the pager. Best used with -T and/or -D above.
282
282
283 If you want to run complete programs under the profiler's control, use
283 If you want to run complete programs under the profiler's control, use
284 ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
284 ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
285 contains profiler specific options as described here.
285 contains profiler specific options as described here.
286
286
287 You can read the complete documentation for the profile module with::
287 You can read the complete documentation for the profile module with::
288
288
289 In [1]: import profile; profile.help()
289 In [1]: import profile; profile.help()
290
290
291 .. versionchanged:: 7.3
291 .. versionchanged:: 7.3
292 User variables are no longer expanded,
292 User variables are no longer expanded,
293 the magic line is always left unmodified.
293 the magic line is always left unmodified.
294
294
295 """
295 """
296 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
296 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
297 list_all=True, posix=False)
297 list_all=True, posix=False)
298 if cell is not None:
298 if cell is not None:
299 arg_str += '\n' + cell
299 arg_str += '\n' + cell
300 arg_str = self.shell.transform_cell(arg_str)
300 arg_str = self.shell.transform_cell(arg_str)
301 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
301 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
302
302
303 def _run_with_profiler(self, code, opts, namespace):
303 def _run_with_profiler(self, code, opts, namespace):
304 """
304 """
305 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
305 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
306
306
307 Parameters
307 Parameters
308 ----------
308 ----------
309 code : str
309 code : str
310 Code to be executed.
310 Code to be executed.
311 opts : Struct
311 opts : Struct
312 Options parsed by `self.parse_options`.
312 Options parsed by `self.parse_options`.
313 namespace : dict
313 namespace : dict
314 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
314 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
315
315
316 """
316 """
317
317
318 # Fill default values for unspecified options:
318 # Fill default values for unspecified options:
319 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
319 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
320
320
321 prof = profile.Profile()
321 prof = profile.Profile()
322 try:
322 try:
323 prof = prof.runctx(code, namespace, namespace)
323 prof = prof.runctx(code, namespace, namespace)
324 sys_exit = ''
324 sys_exit = ''
325 except SystemExit:
325 except SystemExit:
326 sys_exit = """*** SystemExit exception caught in code being profiled."""
326 sys_exit = """*** SystemExit exception caught in code being profiled."""
327
327
328 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
328 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
329
329
330 lims = opts.l
330 lims = opts.l
331 if lims:
331 if lims:
332 lims = [] # rebuild lims with ints/floats/strings
332 lims = [] # rebuild lims with ints/floats/strings
333 for lim in opts.l:
333 for lim in opts.l:
334 try:
334 try:
335 lims.append(int(lim))
335 lims.append(int(lim))
336 except ValueError:
336 except ValueError:
337 try:
337 try:
338 lims.append(float(lim))
338 lims.append(float(lim))
339 except ValueError:
339 except ValueError:
340 lims.append(lim)
340 lims.append(lim)
341
341
342 # Trap output.
342 # Trap output.
343 stdout_trap = StringIO()
343 stdout_trap = StringIO()
344 stats_stream = stats.stream
344 stats_stream = stats.stream
345 try:
345 try:
346 stats.stream = stdout_trap
346 stats.stream = stdout_trap
347 stats.print_stats(*lims)
347 stats.print_stats(*lims)
348 finally:
348 finally:
349 stats.stream = stats_stream
349 stats.stream = stats_stream
350
350
351 output = stdout_trap.getvalue()
351 output = stdout_trap.getvalue()
352 output = output.rstrip()
352 output = output.rstrip()
353
353
354 if 'q' not in opts:
354 if 'q' not in opts:
355 page.page(output)
355 page.page(output)
356 print(sys_exit, end=' ')
356 print(sys_exit, end=' ')
357
357
358 dump_file = opts.D[0]
358 dump_file = opts.D[0]
359 text_file = opts.T[0]
359 text_file = opts.T[0]
360 if dump_file:
360 if dump_file:
361 prof.dump_stats(dump_file)
361 prof.dump_stats(dump_file)
362 print('\n*** Profile stats marshalled to file',\
362 print('\n*** Profile stats marshalled to file',\
363 repr(dump_file)+'.',sys_exit)
363 repr(dump_file)+'.',sys_exit)
364 if text_file:
364 if text_file:
365 with open(text_file, 'w') as pfile:
365 with open(text_file, 'w') as pfile:
366 pfile.write(output)
366 pfile.write(output)
367 print('\n*** Profile printout saved to text file',\
367 print('\n*** Profile printout saved to text file',\
368 repr(text_file)+'.',sys_exit)
368 repr(text_file)+'.',sys_exit)
369
369
370 if 'r' in opts:
370 if 'r' in opts:
371 return stats
371 return stats
372 else:
372 else:
373 return None
373 return None
374
374
375 @line_magic
375 @line_magic
376 def pdb(self, parameter_s=''):
376 def pdb(self, parameter_s=''):
377 """Control the automatic calling of the pdb interactive debugger.
377 """Control the automatic calling of the pdb interactive debugger.
378
378
379 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
379 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
380 argument it works as a toggle.
380 argument it works as a toggle.
381
381
382 When an exception is triggered, IPython can optionally call the
382 When an exception is triggered, IPython can optionally call the
383 interactive pdb debugger after the traceback printout. %pdb toggles
383 interactive pdb debugger after the traceback printout. %pdb toggles
384 this feature on and off.
384 this feature on and off.
385
385
386 The initial state of this feature is set in your configuration
386 The initial state of this feature is set in your configuration
387 file (the option is ``InteractiveShell.pdb``).
387 file (the option is ``InteractiveShell.pdb``).
388
388
389 If you want to just activate the debugger AFTER an exception has fired,
389 If you want to just activate the debugger AFTER an exception has fired,
390 without having to type '%pdb on' and rerunning your code, you can use
390 without having to type '%pdb on' and rerunning your code, you can use
391 the %debug magic."""
391 the %debug magic."""
392
392
393 par = parameter_s.strip().lower()
393 par = parameter_s.strip().lower()
394
394
395 if par:
395 if par:
396 try:
396 try:
397 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
397 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
398 except KeyError:
398 except KeyError:
399 print ('Incorrect argument. Use on/1, off/0, '
399 print ('Incorrect argument. Use on/1, off/0, '
400 'or nothing for a toggle.')
400 'or nothing for a toggle.')
401 return
401 return
402 else:
402 else:
403 # toggle
403 # toggle
404 new_pdb = not self.shell.call_pdb
404 new_pdb = not self.shell.call_pdb
405
405
406 # set on the shell
406 # set on the shell
407 self.shell.call_pdb = new_pdb
407 self.shell.call_pdb = new_pdb
408 print('Automatic pdb calling has been turned',on_off(new_pdb))
408 print('Automatic pdb calling has been turned',on_off(new_pdb))
409
409
410 @skip_doctest
410 @skip_doctest
411 @magic_arguments.magic_arguments()
411 @magic_arguments.magic_arguments()
412 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
412 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
413 help="""
413 help="""
414 Set break point at LINE in FILE.
414 Set break point at LINE in FILE.
415 """
415 """
416 )
416 )
417 @magic_arguments.argument('statement', nargs='*',
417 @magic_arguments.argument('statement', nargs='*',
418 help="""
418 help="""
419 Code to run in debugger.
419 Code to run in debugger.
420 You can omit this in cell magic mode.
420 You can omit this in cell magic mode.
421 """
421 """
422 )
422 )
423 @no_var_expand
423 @no_var_expand
424 @line_cell_magic
424 @line_cell_magic
425 def debug(self, line='', cell=None):
425 def debug(self, line='', cell=None):
426 """Activate the interactive debugger.
426 """Activate the interactive debugger.
427
427
428 This magic command support two ways of activating debugger.
428 This magic command support two ways of activating debugger.
429 One is to activate debugger before executing code. This way, you
429 One is to activate debugger before executing code. This way, you
430 can set a break point, to step through the code from the point.
430 can set a break point, to step through the code from the point.
431 You can use this mode by giving statements to execute and optionally
431 You can use this mode by giving statements to execute and optionally
432 a breakpoint.
432 a breakpoint.
433
433
434 The other one is to activate debugger in post-mortem mode. You can
434 The other one is to activate debugger in post-mortem mode. You can
435 activate this mode simply running %debug without any argument.
435 activate this mode simply running %debug without any argument.
436 If an exception has just occurred, this lets you inspect its stack
436 If an exception has just occurred, this lets you inspect its stack
437 frames interactively. Note that this will always work only on the last
437 frames interactively. Note that this will always work only on the last
438 traceback that occurred, so you must call this quickly after an
438 traceback that occurred, so you must call this quickly after an
439 exception that you wish to inspect has fired, because if another one
439 exception that you wish to inspect has fired, because if another one
440 occurs, it clobbers the previous one.
440 occurs, it clobbers the previous one.
441
441
442 If you want IPython to automatically do this on every exception, see
442 If you want IPython to automatically do this on every exception, see
443 the %pdb magic for more details.
443 the %pdb magic for more details.
444
444
445 .. versionchanged:: 7.3
445 .. versionchanged:: 7.3
446 When running code, user variables are no longer expanded,
446 When running code, user variables are no longer expanded,
447 the magic line is always left unmodified.
447 the magic line is always left unmodified.
448
448
449 """
449 """
450 args = magic_arguments.parse_argstring(self.debug, line)
450 args = magic_arguments.parse_argstring(self.debug, line)
451
451
452 if not (args.breakpoint or args.statement or cell):
452 if not (args.breakpoint or args.statement or cell):
453 self._debug_post_mortem()
453 self._debug_post_mortem()
454 else:
454 else:
455 code = "\n".join(args.statement)
455 code = "\n".join(args.statement)
456 if cell:
456 if cell:
457 code += "\n" + cell
457 code += "\n" + cell
458 self._debug_exec(code, args.breakpoint)
458 self._debug_exec(code, args.breakpoint)
459
459
460 def _debug_post_mortem(self):
460 def _debug_post_mortem(self):
461 self.shell.debugger(force=True)
461 self.shell.debugger(force=True)
462
462
463 def _debug_exec(self, code, breakpoint):
463 def _debug_exec(self, code, breakpoint):
464 if breakpoint:
464 if breakpoint:
465 (filename, bp_line) = breakpoint.rsplit(':', 1)
465 (filename, bp_line) = breakpoint.rsplit(':', 1)
466 bp_line = int(bp_line)
466 bp_line = int(bp_line)
467 else:
467 else:
468 (filename, bp_line) = (None, None)
468 (filename, bp_line) = (None, None)
469 self._run_with_debugger(code, self.shell.user_ns, filename, bp_line)
469 self._run_with_debugger(code, self.shell.user_ns, filename, bp_line)
470
470
471 @line_magic
471 @line_magic
472 def tb(self, s):
472 def tb(self, s):
473 """Print the last traceback.
473 """Print the last traceback.
474
474
475 Optionally, specify an exception reporting mode, tuning the
475 Optionally, specify an exception reporting mode, tuning the
476 verbosity of the traceback. By default the currently-active exception
476 verbosity of the traceback. By default the currently-active exception
477 mode is used. See %xmode for changing exception reporting modes.
477 mode is used. See %xmode for changing exception reporting modes.
478
478
479 Valid modes: Plain, Context, Verbose, and Minimal.
479 Valid modes: Plain, Context, Verbose, and Minimal.
480 """
480 """
481 interactive_tb = self.shell.InteractiveTB
481 interactive_tb = self.shell.InteractiveTB
482 if s:
482 if s:
483 # Switch exception reporting mode for this one call.
483 # Switch exception reporting mode for this one call.
484 # Ensure it is switched back.
484 # Ensure it is switched back.
485 def xmode_switch_err(name):
485 def xmode_switch_err(name):
486 warn('Error changing %s exception modes.\n%s' %
486 warn('Error changing %s exception modes.\n%s' %
487 (name,sys.exc_info()[1]))
487 (name,sys.exc_info()[1]))
488
488
489 new_mode = s.strip().capitalize()
489 new_mode = s.strip().capitalize()
490 original_mode = interactive_tb.mode
490 original_mode = interactive_tb.mode
491 try:
491 try:
492 try:
492 try:
493 interactive_tb.set_mode(mode=new_mode)
493 interactive_tb.set_mode(mode=new_mode)
494 except Exception:
494 except Exception:
495 xmode_switch_err('user')
495 xmode_switch_err('user')
496 else:
496 else:
497 self.shell.showtraceback()
497 self.shell.showtraceback()
498 finally:
498 finally:
499 interactive_tb.set_mode(mode=original_mode)
499 interactive_tb.set_mode(mode=original_mode)
500 else:
500 else:
501 self.shell.showtraceback()
501 self.shell.showtraceback()
502
502
503 @skip_doctest
503 @skip_doctest
504 @line_magic
504 @line_magic
505 def run(self, parameter_s='', runner=None,
505 def run(self, parameter_s='', runner=None,
506 file_finder=get_py_filename):
506 file_finder=get_py_filename):
507 """Run the named file inside IPython as a program.
507 """Run the named file inside IPython as a program.
508
508
509 Usage::
509 Usage::
510
510
511 %run [-n -i -e -G]
511 %run [-n -i -e -G]
512 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
512 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
513 ( -m mod | file ) [args]
513 ( -m mod | file ) [args]
514
514
515 Parameters after the filename are passed as command-line arguments to
515 Parameters after the filename are passed as command-line arguments to
516 the program (put in sys.argv). Then, control returns to IPython's
516 the program (put in sys.argv). Then, control returns to IPython's
517 prompt.
517 prompt.
518
518
519 This is similar to running at a system prompt ``python file args``,
519 This is similar to running at a system prompt ``python file args``,
520 but with the advantage of giving you IPython's tracebacks, and of
520 but with the advantage of giving you IPython's tracebacks, and of
521 loading all variables into your interactive namespace for further use
521 loading all variables into your interactive namespace for further use
522 (unless -p is used, see below).
522 (unless -p is used, see below).
523
523
524 The file is executed in a namespace initially consisting only of
524 The file is executed in a namespace initially consisting only of
525 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
525 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
526 sees its environment as if it were being run as a stand-alone program
526 sees its environment as if it were being run as a stand-alone program
527 (except for sharing global objects such as previously imported
527 (except for sharing global objects such as previously imported
528 modules). But after execution, the IPython interactive namespace gets
528 modules). But after execution, the IPython interactive namespace gets
529 updated with all variables defined in the program (except for __name__
529 updated with all variables defined in the program (except for __name__
530 and sys.argv). This allows for very convenient loading of code for
530 and sys.argv). This allows for very convenient loading of code for
531 interactive work, while giving each program a 'clean sheet' to run in.
531 interactive work, while giving each program a 'clean sheet' to run in.
532
532
533 Arguments are expanded using shell-like glob match. Patterns
533 Arguments are expanded using shell-like glob match. Patterns
534 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
534 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
535 tilde '~' will be expanded into user's home directory. Unlike
535 tilde '~' will be expanded into user's home directory. Unlike
536 real shells, quotation does not suppress expansions. Use
536 real shells, quotation does not suppress expansions. Use
537 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
537 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
538 To completely disable these expansions, you can use -G flag.
538 To completely disable these expansions, you can use -G flag.
539
539
540 On Windows systems, the use of single quotes `'` when specifying
540 On Windows systems, the use of single quotes `'` when specifying
541 a file is not supported. Use double quotes `"`.
541 a file is not supported. Use double quotes `"`.
542
542
543 Options:
543 Options:
544
544
545 -n
545 -n
546 __name__ is NOT set to '__main__', but to the running file's name
546 __name__ is NOT set to '__main__', but to the running file's name
547 without extension (as python does under import). This allows running
547 without extension (as python does under import). This allows running
548 scripts and reloading the definitions in them without calling code
548 scripts and reloading the definitions in them without calling code
549 protected by an ``if __name__ == "__main__"`` clause.
549 protected by an ``if __name__ == "__main__"`` clause.
550
550
551 -i
551 -i
552 run the file in IPython's namespace instead of an empty one. This
552 run the file in IPython's namespace instead of an empty one. This
553 is useful if you are experimenting with code written in a text editor
553 is useful if you are experimenting with code written in a text editor
554 which depends on variables defined interactively.
554 which depends on variables defined interactively.
555
555
556 -e
556 -e
557 ignore sys.exit() calls or SystemExit exceptions in the script
557 ignore sys.exit() calls or SystemExit exceptions in the script
558 being run. This is particularly useful if IPython is being used to
558 being run. This is particularly useful if IPython is being used to
559 run unittests, which always exit with a sys.exit() call. In such
559 run unittests, which always exit with a sys.exit() call. In such
560 cases you are interested in the output of the test results, not in
560 cases you are interested in the output of the test results, not in
561 seeing a traceback of the unittest module.
561 seeing a traceback of the unittest module.
562
562
563 -t
563 -t
564 print timing information at the end of the run. IPython will give
564 print timing information at the end of the run. IPython will give
565 you an estimated CPU time consumption for your script, which under
565 you an estimated CPU time consumption for your script, which under
566 Unix uses the resource module to avoid the wraparound problems of
566 Unix uses the resource module to avoid the wraparound problems of
567 time.clock(). Under Unix, an estimate of time spent on system tasks
567 time.clock(). Under Unix, an estimate of time spent on system tasks
568 is also given (for Windows platforms this is reported as 0.0).
568 is also given (for Windows platforms this is reported as 0.0).
569
569
570 If -t is given, an additional ``-N<N>`` option can be given, where <N>
570 If -t is given, an additional ``-N<N>`` option can be given, where <N>
571 must be an integer indicating how many times you want the script to
571 must be an integer indicating how many times you want the script to
572 run. The final timing report will include total and per run results.
572 run. The final timing report will include total and per run results.
573
573
574 For example (testing the script uniq_stable.py)::
574 For example (testing the script uniq_stable.py)::
575
575
576 In [1]: run -t uniq_stable
576 In [1]: run -t uniq_stable
577
577
578 IPython CPU timings (estimated):
578 IPython CPU timings (estimated):
579 User : 0.19597 s.
579 User : 0.19597 s.
580 System: 0.0 s.
580 System: 0.0 s.
581
581
582 In [2]: run -t -N5 uniq_stable
582 In [2]: run -t -N5 uniq_stable
583
583
584 IPython CPU timings (estimated):
584 IPython CPU timings (estimated):
585 Total runs performed: 5
585 Total runs performed: 5
586 Times : Total Per run
586 Times : Total Per run
587 User : 0.910862 s, 0.1821724 s.
587 User : 0.910862 s, 0.1821724 s.
588 System: 0.0 s, 0.0 s.
588 System: 0.0 s, 0.0 s.
589
589
590 -d
590 -d
591 run your program under the control of pdb, the Python debugger.
591 run your program under the control of pdb, the Python debugger.
592 This allows you to execute your program step by step, watch variables,
592 This allows you to execute your program step by step, watch variables,
593 etc. Internally, what IPython does is similar to calling::
593 etc. Internally, what IPython does is similar to calling::
594
594
595 pdb.run('execfile("YOURFILENAME")')
595 pdb.run('execfile("YOURFILENAME")')
596
596
597 with a breakpoint set on line 1 of your file. You can change the line
597 with a breakpoint set on line 1 of your file. You can change the line
598 number for this automatic breakpoint to be <N> by using the -bN option
598 number for this automatic breakpoint to be <N> by using the -bN option
599 (where N must be an integer). For example::
599 (where N must be an integer). For example::
600
600
601 %run -d -b40 myscript
601 %run -d -b40 myscript
602
602
603 will set the first breakpoint at line 40 in myscript.py. Note that
603 will set the first breakpoint at line 40 in myscript.py. Note that
604 the first breakpoint must be set on a line which actually does
604 the first breakpoint must be set on a line which actually does
605 something (not a comment or docstring) for it to stop execution.
605 something (not a comment or docstring) for it to stop execution.
606
606
607 Or you can specify a breakpoint in a different file::
607 Or you can specify a breakpoint in a different file::
608
608
609 %run -d -b myotherfile.py:20 myscript
609 %run -d -b myotherfile.py:20 myscript
610
610
611 When the pdb debugger starts, you will see a (Pdb) prompt. You must
611 When the pdb debugger starts, you will see a (Pdb) prompt. You must
612 first enter 'c' (without quotes) to start execution up to the first
612 first enter 'c' (without quotes) to start execution up to the first
613 breakpoint.
613 breakpoint.
614
614
615 Entering 'help' gives information about the use of the debugger. You
615 Entering 'help' gives information about the use of the debugger. You
616 can easily see pdb's full documentation with "import pdb;pdb.help()"
616 can easily see pdb's full documentation with "import pdb;pdb.help()"
617 at a prompt.
617 at a prompt.
618
618
619 -p
619 -p
620 run program under the control of the Python profiler module (which
620 run program under the control of the Python profiler module (which
621 prints a detailed report of execution times, function calls, etc).
621 prints a detailed report of execution times, function calls, etc).
622
622
623 You can pass other options after -p which affect the behavior of the
623 You can pass other options after -p which affect the behavior of the
624 profiler itself. See the docs for %prun for details.
624 profiler itself. See the docs for %prun for details.
625
625
626 In this mode, the program's variables do NOT propagate back to the
626 In this mode, the program's variables do NOT propagate back to the
627 IPython interactive namespace (because they remain in the namespace
627 IPython interactive namespace (because they remain in the namespace
628 where the profiler executes them).
628 where the profiler executes them).
629
629
630 Internally this triggers a call to %prun, see its documentation for
630 Internally this triggers a call to %prun, see its documentation for
631 details on the options available specifically for profiling.
631 details on the options available specifically for profiling.
632
632
633 There is one special usage for which the text above doesn't apply:
633 There is one special usage for which the text above doesn't apply:
634 if the filename ends with .ipy[nb], the file is run as ipython script,
634 if the filename ends with .ipy[nb], the file is run as ipython script,
635 just as if the commands were written on IPython prompt.
635 just as if the commands were written on IPython prompt.
636
636
637 -m
637 -m
638 specify module name to load instead of script path. Similar to
638 specify module name to load instead of script path. Similar to
639 the -m option for the python interpreter. Use this option last if you
639 the -m option for the python interpreter. Use this option last if you
640 want to combine with other %run options. Unlike the python interpreter
640 want to combine with other %run options. Unlike the python interpreter
641 only source modules are allowed no .pyc or .pyo files.
641 only source modules are allowed no .pyc or .pyo files.
642 For example::
642 For example::
643
643
644 %run -m example
644 %run -m example
645
645
646 will run the example module.
646 will run the example module.
647
647
648 -G
648 -G
649 disable shell-like glob expansion of arguments.
649 disable shell-like glob expansion of arguments.
650
650
651 """
651 """
652
652
653 # Logic to handle issue #3664
653 # Logic to handle issue #3664
654 # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
654 # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
655 if '-m' in parameter_s and '--' not in parameter_s:
655 if '-m' in parameter_s and '--' not in parameter_s:
656 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
656 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
657 for idx, arg in enumerate(argv):
657 for idx, arg in enumerate(argv):
658 if arg and arg.startswith('-') and arg != '-':
658 if arg and arg.startswith('-') and arg != '-':
659 if arg == '-m':
659 if arg == '-m':
660 argv.insert(idx + 2, '--')
660 argv.insert(idx + 2, '--')
661 break
661 break
662 else:
662 else:
663 # Positional arg, break
663 # Positional arg, break
664 break
664 break
665 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
665 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
666
666
667 # get arguments and set sys.argv for program to be run.
667 # get arguments and set sys.argv for program to be run.
668 opts, arg_lst = self.parse_options(parameter_s,
668 opts, arg_lst = self.parse_options(parameter_s,
669 'nidtN:b:pD:l:rs:T:em:G',
669 'nidtN:b:pD:l:rs:T:em:G',
670 mode='list', list_all=1)
670 mode='list', list_all=1)
671 if "m" in opts:
671 if "m" in opts:
672 modulename = opts["m"][0]
672 modulename = opts["m"][0]
673 modpath = find_mod(modulename)
673 modpath = find_mod(modulename)
674 if modpath is None:
674 if modpath is None:
675 msg = '%r is not a valid modulename on sys.path'%modulename
675 msg = '%r is not a valid modulename on sys.path'%modulename
676 raise Exception(msg)
676 raise Exception(msg)
677 arg_lst = [modpath] + arg_lst
677 arg_lst = [modpath] + arg_lst
678 try:
678 try:
679 fpath = None # initialize to make sure fpath is in scope later
679 fpath = None # initialize to make sure fpath is in scope later
680 fpath = arg_lst[0]
680 fpath = arg_lst[0]
681 filename = file_finder(fpath)
681 filename = file_finder(fpath)
682 except IndexError:
682 except IndexError as e:
683 msg = 'you must provide at least a filename.'
683 msg = 'you must provide at least a filename.'
684 raise Exception(msg)
684 raise Exception(msg) from e
685 except IOError as e:
685 except IOError as e:
686 try:
686 try:
687 msg = str(e)
687 msg = str(e)
688 except UnicodeError:
688 except UnicodeError:
689 msg = e.message
689 msg = e.message
690 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
690 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
691 warn('For Windows, use double quotes to wrap a filename: %run "mypath\\myfile.py"')
691 warn('For Windows, use double quotes to wrap a filename: %run "mypath\\myfile.py"')
692 raise Exception(msg)
692 raise Exception(msg) from e
693 except TypeError:
693 except TypeError:
694 if fpath in sys.meta_path:
694 if fpath in sys.meta_path:
695 filename = ""
695 filename = ""
696 else:
696 else:
697 raise
697 raise
698
698
699 if filename.lower().endswith(('.ipy', '.ipynb')):
699 if filename.lower().endswith(('.ipy', '.ipynb')):
700 with preserve_keys(self.shell.user_ns, '__file__'):
700 with preserve_keys(self.shell.user_ns, '__file__'):
701 self.shell.user_ns['__file__'] = filename
701 self.shell.user_ns['__file__'] = filename
702 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
702 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
703 return
703 return
704
704
705 # Control the response to exit() calls made by the script being run
705 # Control the response to exit() calls made by the script being run
706 exit_ignore = 'e' in opts
706 exit_ignore = 'e' in opts
707
707
708 # Make sure that the running script gets a proper sys.argv as if it
708 # Make sure that the running script gets a proper sys.argv as if it
709 # were run from a system shell.
709 # were run from a system shell.
710 save_argv = sys.argv # save it for later restoring
710 save_argv = sys.argv # save it for later restoring
711
711
712 if 'G' in opts:
712 if 'G' in opts:
713 args = arg_lst[1:]
713 args = arg_lst[1:]
714 else:
714 else:
715 # tilde and glob expansion
715 # tilde and glob expansion
716 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
716 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
717
717
718 sys.argv = [filename] + args # put in the proper filename
718 sys.argv = [filename] + args # put in the proper filename
719
719
720 if 'n' in opts:
720 if 'n' in opts:
721 name = os.path.splitext(os.path.basename(filename))[0]
721 name = os.path.splitext(os.path.basename(filename))[0]
722 else:
722 else:
723 name = '__main__'
723 name = '__main__'
724
724
725 if 'i' in opts:
725 if 'i' in opts:
726 # Run in user's interactive namespace
726 # Run in user's interactive namespace
727 prog_ns = self.shell.user_ns
727 prog_ns = self.shell.user_ns
728 __name__save = self.shell.user_ns['__name__']
728 __name__save = self.shell.user_ns['__name__']
729 prog_ns['__name__'] = name
729 prog_ns['__name__'] = name
730 main_mod = self.shell.user_module
730 main_mod = self.shell.user_module
731
731
732 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
732 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
733 # set the __file__ global in the script's namespace
733 # set the __file__ global in the script's namespace
734 # TK: Is this necessary in interactive mode?
734 # TK: Is this necessary in interactive mode?
735 prog_ns['__file__'] = filename
735 prog_ns['__file__'] = filename
736 else:
736 else:
737 # Run in a fresh, empty namespace
737 # Run in a fresh, empty namespace
738
738
739 # The shell MUST hold a reference to prog_ns so after %run
739 # The shell MUST hold a reference to prog_ns so after %run
740 # exits, the python deletion mechanism doesn't zero it out
740 # exits, the python deletion mechanism doesn't zero it out
741 # (leaving dangling references). See interactiveshell for details
741 # (leaving dangling references). See interactiveshell for details
742 main_mod = self.shell.new_main_mod(filename, name)
742 main_mod = self.shell.new_main_mod(filename, name)
743 prog_ns = main_mod.__dict__
743 prog_ns = main_mod.__dict__
744
744
745 # pickle fix. See interactiveshell for an explanation. But we need to
745 # pickle fix. See interactiveshell for an explanation. But we need to
746 # make sure that, if we overwrite __main__, we replace it at the end
746 # make sure that, if we overwrite __main__, we replace it at the end
747 main_mod_name = prog_ns['__name__']
747 main_mod_name = prog_ns['__name__']
748
748
749 if main_mod_name == '__main__':
749 if main_mod_name == '__main__':
750 restore_main = sys.modules['__main__']
750 restore_main = sys.modules['__main__']
751 else:
751 else:
752 restore_main = False
752 restore_main = False
753
753
754 # This needs to be undone at the end to prevent holding references to
754 # This needs to be undone at the end to prevent holding references to
755 # every single object ever created.
755 # every single object ever created.
756 sys.modules[main_mod_name] = main_mod
756 sys.modules[main_mod_name] = main_mod
757
757
758 if 'p' in opts or 'd' in opts:
758 if 'p' in opts or 'd' in opts:
759 if 'm' in opts:
759 if 'm' in opts:
760 code = 'run_module(modulename, prog_ns)'
760 code = 'run_module(modulename, prog_ns)'
761 code_ns = {
761 code_ns = {
762 'run_module': self.shell.safe_run_module,
762 'run_module': self.shell.safe_run_module,
763 'prog_ns': prog_ns,
763 'prog_ns': prog_ns,
764 'modulename': modulename,
764 'modulename': modulename,
765 }
765 }
766 else:
766 else:
767 if 'd' in opts:
767 if 'd' in opts:
768 # allow exceptions to raise in debug mode
768 # allow exceptions to raise in debug mode
769 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
769 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
770 else:
770 else:
771 code = 'execfile(filename, prog_ns)'
771 code = 'execfile(filename, prog_ns)'
772 code_ns = {
772 code_ns = {
773 'execfile': self.shell.safe_execfile,
773 'execfile': self.shell.safe_execfile,
774 'prog_ns': prog_ns,
774 'prog_ns': prog_ns,
775 'filename': get_py_filename(filename),
775 'filename': get_py_filename(filename),
776 }
776 }
777
777
778 try:
778 try:
779 stats = None
779 stats = None
780 if 'p' in opts:
780 if 'p' in opts:
781 stats = self._run_with_profiler(code, opts, code_ns)
781 stats = self._run_with_profiler(code, opts, code_ns)
782 else:
782 else:
783 if 'd' in opts:
783 if 'd' in opts:
784 bp_file, bp_line = parse_breakpoint(
784 bp_file, bp_line = parse_breakpoint(
785 opts.get('b', ['1'])[0], filename)
785 opts.get('b', ['1'])[0], filename)
786 self._run_with_debugger(
786 self._run_with_debugger(
787 code, code_ns, filename, bp_line, bp_file)
787 code, code_ns, filename, bp_line, bp_file)
788 else:
788 else:
789 if 'm' in opts:
789 if 'm' in opts:
790 def run():
790 def run():
791 self.shell.safe_run_module(modulename, prog_ns)
791 self.shell.safe_run_module(modulename, prog_ns)
792 else:
792 else:
793 if runner is None:
793 if runner is None:
794 runner = self.default_runner
794 runner = self.default_runner
795 if runner is None:
795 if runner is None:
796 runner = self.shell.safe_execfile
796 runner = self.shell.safe_execfile
797
797
798 def run():
798 def run():
799 runner(filename, prog_ns, prog_ns,
799 runner(filename, prog_ns, prog_ns,
800 exit_ignore=exit_ignore)
800 exit_ignore=exit_ignore)
801
801
802 if 't' in opts:
802 if 't' in opts:
803 # timed execution
803 # timed execution
804 try:
804 try:
805 nruns = int(opts['N'][0])
805 nruns = int(opts['N'][0])
806 if nruns < 1:
806 if nruns < 1:
807 error('Number of runs must be >=1')
807 error('Number of runs must be >=1')
808 return
808 return
809 except (KeyError):
809 except (KeyError):
810 nruns = 1
810 nruns = 1
811 self._run_with_timing(run, nruns)
811 self._run_with_timing(run, nruns)
812 else:
812 else:
813 # regular execution
813 # regular execution
814 run()
814 run()
815
815
816 if 'i' in opts:
816 if 'i' in opts:
817 self.shell.user_ns['__name__'] = __name__save
817 self.shell.user_ns['__name__'] = __name__save
818 else:
818 else:
819 # update IPython interactive namespace
819 # update IPython interactive namespace
820
820
821 # Some forms of read errors on the file may mean the
821 # Some forms of read errors on the file may mean the
822 # __name__ key was never set; using pop we don't have to
822 # __name__ key was never set; using pop we don't have to
823 # worry about a possible KeyError.
823 # worry about a possible KeyError.
824 prog_ns.pop('__name__', None)
824 prog_ns.pop('__name__', None)
825
825
826 with preserve_keys(self.shell.user_ns, '__file__'):
826 with preserve_keys(self.shell.user_ns, '__file__'):
827 self.shell.user_ns.update(prog_ns)
827 self.shell.user_ns.update(prog_ns)
828 finally:
828 finally:
829 # It's a bit of a mystery why, but __builtins__ can change from
829 # It's a bit of a mystery why, but __builtins__ can change from
830 # being a module to becoming a dict missing some key data after
830 # being a module to becoming a dict missing some key data after
831 # %run. As best I can see, this is NOT something IPython is doing
831 # %run. As best I can see, this is NOT something IPython is doing
832 # at all, and similar problems have been reported before:
832 # at all, and similar problems have been reported before:
833 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
833 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
834 # Since this seems to be done by the interpreter itself, the best
834 # Since this seems to be done by the interpreter itself, the best
835 # we can do is to at least restore __builtins__ for the user on
835 # we can do is to at least restore __builtins__ for the user on
836 # exit.
836 # exit.
837 self.shell.user_ns['__builtins__'] = builtin_mod
837 self.shell.user_ns['__builtins__'] = builtin_mod
838
838
839 # Ensure key global structures are restored
839 # Ensure key global structures are restored
840 sys.argv = save_argv
840 sys.argv = save_argv
841 if restore_main:
841 if restore_main:
842 sys.modules['__main__'] = restore_main
842 sys.modules['__main__'] = restore_main
843 if '__mp_main__' in sys.modules:
843 if '__mp_main__' in sys.modules:
844 sys.modules['__mp_main__'] = restore_main
844 sys.modules['__mp_main__'] = restore_main
845 else:
845 else:
846 # Remove from sys.modules the reference to main_mod we'd
846 # Remove from sys.modules the reference to main_mod we'd
847 # added. Otherwise it will trap references to objects
847 # added. Otherwise it will trap references to objects
848 # contained therein.
848 # contained therein.
849 del sys.modules[main_mod_name]
849 del sys.modules[main_mod_name]
850
850
851 return stats
851 return stats
852
852
853 def _run_with_debugger(self, code, code_ns, filename=None,
853 def _run_with_debugger(self, code, code_ns, filename=None,
854 bp_line=None, bp_file=None):
854 bp_line=None, bp_file=None):
855 """
855 """
856 Run `code` in debugger with a break point.
856 Run `code` in debugger with a break point.
857
857
858 Parameters
858 Parameters
859 ----------
859 ----------
860 code : str
860 code : str
861 Code to execute.
861 Code to execute.
862 code_ns : dict
862 code_ns : dict
863 A namespace in which `code` is executed.
863 A namespace in which `code` is executed.
864 filename : str
864 filename : str
865 `code` is ran as if it is in `filename`.
865 `code` is ran as if it is in `filename`.
866 bp_line : int, optional
866 bp_line : int, optional
867 Line number of the break point.
867 Line number of the break point.
868 bp_file : str, optional
868 bp_file : str, optional
869 Path to the file in which break point is specified.
869 Path to the file in which break point is specified.
870 `filename` is used if not given.
870 `filename` is used if not given.
871
871
872 Raises
872 Raises
873 ------
873 ------
874 UsageError
874 UsageError
875 If the break point given by `bp_line` is not valid.
875 If the break point given by `bp_line` is not valid.
876
876
877 """
877 """
878 deb = self.shell.InteractiveTB.pdb
878 deb = self.shell.InteractiveTB.pdb
879 if not deb:
879 if not deb:
880 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
880 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
881 deb = self.shell.InteractiveTB.pdb
881 deb = self.shell.InteractiveTB.pdb
882
882
883 # deb.checkline() fails if deb.curframe exists but is None; it can
883 # deb.checkline() fails if deb.curframe exists but is None; it can
884 # handle it not existing. https://github.com/ipython/ipython/issues/10028
884 # handle it not existing. https://github.com/ipython/ipython/issues/10028
885 if hasattr(deb, 'curframe'):
885 if hasattr(deb, 'curframe'):
886 del deb.curframe
886 del deb.curframe
887
887
888 # reset Breakpoint state, which is moronically kept
888 # reset Breakpoint state, which is moronically kept
889 # in a class
889 # in a class
890 bdb.Breakpoint.next = 1
890 bdb.Breakpoint.next = 1
891 bdb.Breakpoint.bplist = {}
891 bdb.Breakpoint.bplist = {}
892 bdb.Breakpoint.bpbynumber = [None]
892 bdb.Breakpoint.bpbynumber = [None]
893 deb.clear_all_breaks()
893 deb.clear_all_breaks()
894 if bp_line is not None:
894 if bp_line is not None:
895 # Set an initial breakpoint to stop execution
895 # Set an initial breakpoint to stop execution
896 maxtries = 10
896 maxtries = 10
897 bp_file = bp_file or filename
897 bp_file = bp_file or filename
898 checkline = deb.checkline(bp_file, bp_line)
898 checkline = deb.checkline(bp_file, bp_line)
899 if not checkline:
899 if not checkline:
900 for bp in range(bp_line + 1, bp_line + maxtries + 1):
900 for bp in range(bp_line + 1, bp_line + maxtries + 1):
901 if deb.checkline(bp_file, bp):
901 if deb.checkline(bp_file, bp):
902 break
902 break
903 else:
903 else:
904 msg = ("\nI failed to find a valid line to set "
904 msg = ("\nI failed to find a valid line to set "
905 "a breakpoint\n"
905 "a breakpoint\n"
906 "after trying up to line: %s.\n"
906 "after trying up to line: %s.\n"
907 "Please set a valid breakpoint manually "
907 "Please set a valid breakpoint manually "
908 "with the -b option." % bp)
908 "with the -b option." % bp)
909 raise UsageError(msg)
909 raise UsageError(msg)
910 # if we find a good linenumber, set the breakpoint
910 # if we find a good linenumber, set the breakpoint
911 deb.do_break('%s:%s' % (bp_file, bp_line))
911 deb.do_break('%s:%s' % (bp_file, bp_line))
912
912
913 if filename:
913 if filename:
914 # Mimic Pdb._runscript(...)
914 # Mimic Pdb._runscript(...)
915 deb._wait_for_mainpyfile = True
915 deb._wait_for_mainpyfile = True
916 deb.mainpyfile = deb.canonic(filename)
916 deb.mainpyfile = deb.canonic(filename)
917
917
918 # Start file run
918 # Start file run
919 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
919 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
920 try:
920 try:
921 if filename:
921 if filename:
922 # save filename so it can be used by methods on the deb object
922 # save filename so it can be used by methods on the deb object
923 deb._exec_filename = filename
923 deb._exec_filename = filename
924 while True:
924 while True:
925 try:
925 try:
926 trace = sys.gettrace()
926 trace = sys.gettrace()
927 deb.run(code, code_ns)
927 deb.run(code, code_ns)
928 except Restart:
928 except Restart:
929 print("Restarting")
929 print("Restarting")
930 if filename:
930 if filename:
931 deb._wait_for_mainpyfile = True
931 deb._wait_for_mainpyfile = True
932 deb.mainpyfile = deb.canonic(filename)
932 deb.mainpyfile = deb.canonic(filename)
933 continue
933 continue
934 else:
934 else:
935 break
935 break
936 finally:
936 finally:
937 sys.settrace(trace)
937 sys.settrace(trace)
938
938
939
939
940 except:
940 except:
941 etype, value, tb = sys.exc_info()
941 etype, value, tb = sys.exc_info()
942 # Skip three frames in the traceback: the %run one,
942 # Skip three frames in the traceback: the %run one,
943 # one inside bdb.py, and the command-line typed by the
943 # one inside bdb.py, and the command-line typed by the
944 # user (run by exec in pdb itself).
944 # user (run by exec in pdb itself).
945 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
945 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
946
946
947 @staticmethod
947 @staticmethod
948 def _run_with_timing(run, nruns):
948 def _run_with_timing(run, nruns):
949 """
949 """
950 Run function `run` and print timing information.
950 Run function `run` and print timing information.
951
951
952 Parameters
952 Parameters
953 ----------
953 ----------
954 run : callable
954 run : callable
955 Any callable object which takes no argument.
955 Any callable object which takes no argument.
956 nruns : int
956 nruns : int
957 Number of times to execute `run`.
957 Number of times to execute `run`.
958
958
959 """
959 """
960 twall0 = time.perf_counter()
960 twall0 = time.perf_counter()
961 if nruns == 1:
961 if nruns == 1:
962 t0 = clock2()
962 t0 = clock2()
963 run()
963 run()
964 t1 = clock2()
964 t1 = clock2()
965 t_usr = t1[0] - t0[0]
965 t_usr = t1[0] - t0[0]
966 t_sys = t1[1] - t0[1]
966 t_sys = t1[1] - t0[1]
967 print("\nIPython CPU timings (estimated):")
967 print("\nIPython CPU timings (estimated):")
968 print(" User : %10.2f s." % t_usr)
968 print(" User : %10.2f s." % t_usr)
969 print(" System : %10.2f s." % t_sys)
969 print(" System : %10.2f s." % t_sys)
970 else:
970 else:
971 runs = range(nruns)
971 runs = range(nruns)
972 t0 = clock2()
972 t0 = clock2()
973 for nr in runs:
973 for nr in runs:
974 run()
974 run()
975 t1 = clock2()
975 t1 = clock2()
976 t_usr = t1[0] - t0[0]
976 t_usr = t1[0] - t0[0]
977 t_sys = t1[1] - t0[1]
977 t_sys = t1[1] - t0[1]
978 print("\nIPython CPU timings (estimated):")
978 print("\nIPython CPU timings (estimated):")
979 print("Total runs performed:", nruns)
979 print("Total runs performed:", nruns)
980 print(" Times : %10s %10s" % ('Total', 'Per run'))
980 print(" Times : %10s %10s" % ('Total', 'Per run'))
981 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
981 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
982 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
982 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
983 twall1 = time.perf_counter()
983 twall1 = time.perf_counter()
984 print("Wall time: %10.2f s." % (twall1 - twall0))
984 print("Wall time: %10.2f s." % (twall1 - twall0))
985
985
986 @skip_doctest
986 @skip_doctest
987 @no_var_expand
987 @no_var_expand
988 @line_cell_magic
988 @line_cell_magic
989 @needs_local_scope
989 @needs_local_scope
990 def timeit(self, line='', cell=None, local_ns=None):
990 def timeit(self, line='', cell=None, local_ns=None):
991 """Time execution of a Python statement or expression
991 """Time execution of a Python statement or expression
992
992
993 Usage, in line mode:
993 Usage, in line mode:
994 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
994 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
995 or in cell mode:
995 or in cell mode:
996 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
996 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
997 code
997 code
998 code...
998 code...
999
999
1000 Time execution of a Python statement or expression using the timeit
1000 Time execution of a Python statement or expression using the timeit
1001 module. This function can be used both as a line and cell magic:
1001 module. This function can be used both as a line and cell magic:
1002
1002
1003 - In line mode you can time a single-line statement (though multiple
1003 - In line mode you can time a single-line statement (though multiple
1004 ones can be chained with using semicolons).
1004 ones can be chained with using semicolons).
1005
1005
1006 - In cell mode, the statement in the first line is used as setup code
1006 - In cell mode, the statement in the first line is used as setup code
1007 (executed but not timed) and the body of the cell is timed. The cell
1007 (executed but not timed) and the body of the cell is timed. The cell
1008 body has access to any variables created in the setup code.
1008 body has access to any variables created in the setup code.
1009
1009
1010 Options:
1010 Options:
1011 -n<N>: execute the given statement <N> times in a loop. If <N> is not
1011 -n<N>: execute the given statement <N> times in a loop. If <N> is not
1012 provided, <N> is determined so as to get sufficient accuracy.
1012 provided, <N> is determined so as to get sufficient accuracy.
1013
1013
1014 -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
1014 -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
1015 best result.
1015 best result.
1016 Default: 7
1016 Default: 7
1017
1017
1018 -t: use time.time to measure the time, which is the default on Unix.
1018 -t: use time.time to measure the time, which is the default on Unix.
1019 This function measures wall time.
1019 This function measures wall time.
1020
1020
1021 -c: use time.clock to measure the time, which is the default on
1021 -c: use time.clock to measure the time, which is the default on
1022 Windows and measures wall time. On Unix, resource.getrusage is used
1022 Windows and measures wall time. On Unix, resource.getrusage is used
1023 instead and returns the CPU user time.
1023 instead and returns the CPU user time.
1024
1024
1025 -p<P>: use a precision of <P> digits to display the timing result.
1025 -p<P>: use a precision of <P> digits to display the timing result.
1026 Default: 3
1026 Default: 3
1027
1027
1028 -q: Quiet, do not print result.
1028 -q: Quiet, do not print result.
1029
1029
1030 -o: return a TimeitResult that can be stored in a variable to inspect
1030 -o: return a TimeitResult that can be stored in a variable to inspect
1031 the result in more details.
1031 the result in more details.
1032
1032
1033 .. versionchanged:: 7.3
1033 .. versionchanged:: 7.3
1034 User variables are no longer expanded,
1034 User variables are no longer expanded,
1035 the magic line is always left unmodified.
1035 the magic line is always left unmodified.
1036
1036
1037 Examples
1037 Examples
1038 --------
1038 --------
1039 ::
1039 ::
1040
1040
1041 In [1]: %timeit pass
1041 In [1]: %timeit pass
1042 8.26 ns Β± 0.12 ns per loop (mean Β± std. dev. of 7 runs, 100000000 loops each)
1042 8.26 ns Β± 0.12 ns per loop (mean Β± std. dev. of 7 runs, 100000000 loops each)
1043
1043
1044 In [2]: u = None
1044 In [2]: u = None
1045
1045
1046 In [3]: %timeit u is None
1046 In [3]: %timeit u is None
1047 29.9 ns Β± 0.643 ns per loop (mean Β± std. dev. of 7 runs, 10000000 loops each)
1047 29.9 ns Β± 0.643 ns per loop (mean Β± std. dev. of 7 runs, 10000000 loops each)
1048
1048
1049 In [4]: %timeit -r 4 u == None
1049 In [4]: %timeit -r 4 u == None
1050
1050
1051 In [5]: import time
1051 In [5]: import time
1052
1052
1053 In [6]: %timeit -n1 time.sleep(2)
1053 In [6]: %timeit -n1 time.sleep(2)
1054
1054
1055
1055
1056 The times reported by %timeit will be slightly higher than those
1056 The times reported by %timeit will be slightly higher than those
1057 reported by the timeit.py script when variables are accessed. This is
1057 reported by the timeit.py script when variables are accessed. This is
1058 due to the fact that %timeit executes the statement in the namespace
1058 due to the fact that %timeit executes the statement in the namespace
1059 of the shell, compared with timeit.py, which uses a single setup
1059 of the shell, compared with timeit.py, which uses a single setup
1060 statement to import function or create variables. Generally, the bias
1060 statement to import function or create variables. Generally, the bias
1061 does not matter as long as results from timeit.py are not mixed with
1061 does not matter as long as results from timeit.py are not mixed with
1062 those from %timeit."""
1062 those from %timeit."""
1063
1063
1064 opts, stmt = self.parse_options(line,'n:r:tcp:qo',
1064 opts, stmt = self.parse_options(line,'n:r:tcp:qo',
1065 posix=False, strict=False)
1065 posix=False, strict=False)
1066 if stmt == "" and cell is None:
1066 if stmt == "" and cell is None:
1067 return
1067 return
1068
1068
1069 timefunc = timeit.default_timer
1069 timefunc = timeit.default_timer
1070 number = int(getattr(opts, "n", 0))
1070 number = int(getattr(opts, "n", 0))
1071 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1071 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1072 repeat = int(getattr(opts, "r", default_repeat))
1072 repeat = int(getattr(opts, "r", default_repeat))
1073 precision = int(getattr(opts, "p", 3))
1073 precision = int(getattr(opts, "p", 3))
1074 quiet = 'q' in opts
1074 quiet = 'q' in opts
1075 return_result = 'o' in opts
1075 return_result = 'o' in opts
1076 if hasattr(opts, "t"):
1076 if hasattr(opts, "t"):
1077 timefunc = time.time
1077 timefunc = time.time
1078 if hasattr(opts, "c"):
1078 if hasattr(opts, "c"):
1079 timefunc = clock
1079 timefunc = clock
1080
1080
1081 timer = Timer(timer=timefunc)
1081 timer = Timer(timer=timefunc)
1082 # this code has tight coupling to the inner workings of timeit.Timer,
1082 # this code has tight coupling to the inner workings of timeit.Timer,
1083 # but is there a better way to achieve that the code stmt has access
1083 # but is there a better way to achieve that the code stmt has access
1084 # to the shell namespace?
1084 # to the shell namespace?
1085 transform = self.shell.transform_cell
1085 transform = self.shell.transform_cell
1086
1086
1087 if cell is None:
1087 if cell is None:
1088 # called as line magic
1088 # called as line magic
1089 ast_setup = self.shell.compile.ast_parse("pass")
1089 ast_setup = self.shell.compile.ast_parse("pass")
1090 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1090 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1091 else:
1091 else:
1092 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1092 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1093 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1093 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1094
1094
1095 ast_setup = self.shell.transform_ast(ast_setup)
1095 ast_setup = self.shell.transform_ast(ast_setup)
1096 ast_stmt = self.shell.transform_ast(ast_stmt)
1096 ast_stmt = self.shell.transform_ast(ast_stmt)
1097
1097
1098 # Check that these compile to valid Python code *outside* the timer func
1098 # Check that these compile to valid Python code *outside* the timer func
1099 # Invalid code may become valid when put inside the function & loop,
1099 # Invalid code may become valid when put inside the function & loop,
1100 # which messes up error messages.
1100 # which messes up error messages.
1101 # https://github.com/ipython/ipython/issues/10636
1101 # https://github.com/ipython/ipython/issues/10636
1102 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1102 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1103 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1103 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1104
1104
1105 # This codestring is taken from timeit.template - we fill it in as an
1105 # This codestring is taken from timeit.template - we fill it in as an
1106 # AST, so that we can apply our AST transformations to the user code
1106 # AST, so that we can apply our AST transformations to the user code
1107 # without affecting the timing code.
1107 # without affecting the timing code.
1108 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1108 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1109 ' setup\n'
1109 ' setup\n'
1110 ' _t0 = _timer()\n'
1110 ' _t0 = _timer()\n'
1111 ' for _i in _it:\n'
1111 ' for _i in _it:\n'
1112 ' stmt\n'
1112 ' stmt\n'
1113 ' _t1 = _timer()\n'
1113 ' _t1 = _timer()\n'
1114 ' return _t1 - _t0\n')
1114 ' return _t1 - _t0\n')
1115
1115
1116 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1116 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1117 timeit_ast = ast.fix_missing_locations(timeit_ast)
1117 timeit_ast = ast.fix_missing_locations(timeit_ast)
1118
1118
1119 # Track compilation time so it can be reported if too long
1119 # Track compilation time so it can be reported if too long
1120 # Minimum time above which compilation time will be reported
1120 # Minimum time above which compilation time will be reported
1121 tc_min = 0.1
1121 tc_min = 0.1
1122
1122
1123 t0 = clock()
1123 t0 = clock()
1124 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1124 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1125 tc = clock()-t0
1125 tc = clock()-t0
1126
1126
1127 ns = {}
1127 ns = {}
1128 glob = self.shell.user_ns
1128 glob = self.shell.user_ns
1129 # handles global vars with same name as local vars. We store them in conflict_globs.
1129 # handles global vars with same name as local vars. We store them in conflict_globs.
1130 conflict_globs = {}
1130 conflict_globs = {}
1131 if local_ns and cell is None:
1131 if local_ns and cell is None:
1132 for var_name, var_val in glob.items():
1132 for var_name, var_val in glob.items():
1133 if var_name in local_ns:
1133 if var_name in local_ns:
1134 conflict_globs[var_name] = var_val
1134 conflict_globs[var_name] = var_val
1135 glob.update(local_ns)
1135 glob.update(local_ns)
1136
1136
1137 exec(code, glob, ns)
1137 exec(code, glob, ns)
1138 timer.inner = ns["inner"]
1138 timer.inner = ns["inner"]
1139
1139
1140 # This is used to check if there is a huge difference between the
1140 # This is used to check if there is a huge difference between the
1141 # best and worst timings.
1141 # best and worst timings.
1142 # Issue: https://github.com/ipython/ipython/issues/6471
1142 # Issue: https://github.com/ipython/ipython/issues/6471
1143 if number == 0:
1143 if number == 0:
1144 # determine number so that 0.2 <= total time < 2.0
1144 # determine number so that 0.2 <= total time < 2.0
1145 for index in range(0, 10):
1145 for index in range(0, 10):
1146 number = 10 ** index
1146 number = 10 ** index
1147 time_number = timer.timeit(number)
1147 time_number = timer.timeit(number)
1148 if time_number >= 0.2:
1148 if time_number >= 0.2:
1149 break
1149 break
1150
1150
1151 all_runs = timer.repeat(repeat, number)
1151 all_runs = timer.repeat(repeat, number)
1152 best = min(all_runs) / number
1152 best = min(all_runs) / number
1153 worst = max(all_runs) / number
1153 worst = max(all_runs) / number
1154 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1154 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1155
1155
1156 # Restore global vars from conflict_globs
1156 # Restore global vars from conflict_globs
1157 if conflict_globs:
1157 if conflict_globs:
1158 glob.update(conflict_globs)
1158 glob.update(conflict_globs)
1159
1159
1160 if not quiet :
1160 if not quiet :
1161 # Check best timing is greater than zero to avoid a
1161 # Check best timing is greater than zero to avoid a
1162 # ZeroDivisionError.
1162 # ZeroDivisionError.
1163 # In cases where the slowest timing is lesser than a microsecond
1163 # In cases where the slowest timing is lesser than a microsecond
1164 # we assume that it does not really matter if the fastest
1164 # we assume that it does not really matter if the fastest
1165 # timing is 4 times faster than the slowest timing or not.
1165 # timing is 4 times faster than the slowest timing or not.
1166 if worst > 4 * best and best > 0 and worst > 1e-6:
1166 if worst > 4 * best and best > 0 and worst > 1e-6:
1167 print("The slowest run took %0.2f times longer than the "
1167 print("The slowest run took %0.2f times longer than the "
1168 "fastest. This could mean that an intermediate result "
1168 "fastest. This could mean that an intermediate result "
1169 "is being cached." % (worst / best))
1169 "is being cached." % (worst / best))
1170
1170
1171 print( timeit_result )
1171 print( timeit_result )
1172
1172
1173 if tc > tc_min:
1173 if tc > tc_min:
1174 print("Compiler time: %.2f s" % tc)
1174 print("Compiler time: %.2f s" % tc)
1175 if return_result:
1175 if return_result:
1176 return timeit_result
1176 return timeit_result
1177
1177
1178 @skip_doctest
1178 @skip_doctest
1179 @no_var_expand
1179 @no_var_expand
1180 @needs_local_scope
1180 @needs_local_scope
1181 @line_cell_magic
1181 @line_cell_magic
1182 def time(self,line='', cell=None, local_ns=None):
1182 def time(self,line='', cell=None, local_ns=None):
1183 """Time execution of a Python statement or expression.
1183 """Time execution of a Python statement or expression.
1184
1184
1185 The CPU and wall clock times are printed, and the value of the
1185 The CPU and wall clock times are printed, and the value of the
1186 expression (if any) is returned. Note that under Win32, system time
1186 expression (if any) is returned. Note that under Win32, system time
1187 is always reported as 0, since it can not be measured.
1187 is always reported as 0, since it can not be measured.
1188
1188
1189 This function can be used both as a line and cell magic:
1189 This function can be used both as a line and cell magic:
1190
1190
1191 - In line mode you can time a single-line statement (though multiple
1191 - In line mode you can time a single-line statement (though multiple
1192 ones can be chained with using semicolons).
1192 ones can be chained with using semicolons).
1193
1193
1194 - In cell mode, you can time the cell body (a directly
1194 - In cell mode, you can time the cell body (a directly
1195 following statement raises an error).
1195 following statement raises an error).
1196
1196
1197 This function provides very basic timing functionality. Use the timeit
1197 This function provides very basic timing functionality. Use the timeit
1198 magic for more control over the measurement.
1198 magic for more control over the measurement.
1199
1199
1200 .. versionchanged:: 7.3
1200 .. versionchanged:: 7.3
1201 User variables are no longer expanded,
1201 User variables are no longer expanded,
1202 the magic line is always left unmodified.
1202 the magic line is always left unmodified.
1203
1203
1204 Examples
1204 Examples
1205 --------
1205 --------
1206 ::
1206 ::
1207
1207
1208 In [1]: %time 2**128
1208 In [1]: %time 2**128
1209 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1209 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1210 Wall time: 0.00
1210 Wall time: 0.00
1211 Out[1]: 340282366920938463463374607431768211456L
1211 Out[1]: 340282366920938463463374607431768211456L
1212
1212
1213 In [2]: n = 1000000
1213 In [2]: n = 1000000
1214
1214
1215 In [3]: %time sum(range(n))
1215 In [3]: %time sum(range(n))
1216 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1216 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1217 Wall time: 1.37
1217 Wall time: 1.37
1218 Out[3]: 499999500000L
1218 Out[3]: 499999500000L
1219
1219
1220 In [4]: %time print 'hello world'
1220 In [4]: %time print 'hello world'
1221 hello world
1221 hello world
1222 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1222 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1223 Wall time: 0.00
1223 Wall time: 0.00
1224
1224
1225 Note that the time needed by Python to compile the given expression
1225 Note that the time needed by Python to compile the given expression
1226 will be reported if it is more than 0.1s. In this example, the
1226 will be reported if it is more than 0.1s. In this example, the
1227 actual exponentiation is done by Python at compilation time, so while
1227 actual exponentiation is done by Python at compilation time, so while
1228 the expression can take a noticeable amount of time to compute, that
1228 the expression can take a noticeable amount of time to compute, that
1229 time is purely due to the compilation:
1229 time is purely due to the compilation:
1230
1230
1231 In [5]: %time 3**9999;
1231 In [5]: %time 3**9999;
1232 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1232 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1233 Wall time: 0.00 s
1233 Wall time: 0.00 s
1234
1234
1235 In [6]: %time 3**999999;
1235 In [6]: %time 3**999999;
1236 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1236 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1237 Wall time: 0.00 s
1237 Wall time: 0.00 s
1238 Compiler : 0.78 s
1238 Compiler : 0.78 s
1239 """
1239 """
1240
1240
1241 # fail immediately if the given expression can't be compiled
1241 # fail immediately if the given expression can't be compiled
1242
1242
1243 if line and cell:
1243 if line and cell:
1244 raise UsageError("Can't use statement directly after '%%time'!")
1244 raise UsageError("Can't use statement directly after '%%time'!")
1245
1245
1246 if cell:
1246 if cell:
1247 expr = self.shell.transform_cell(cell)
1247 expr = self.shell.transform_cell(cell)
1248 else:
1248 else:
1249 expr = self.shell.transform_cell(line)
1249 expr = self.shell.transform_cell(line)
1250
1250
1251 # Minimum time above which parse time will be reported
1251 # Minimum time above which parse time will be reported
1252 tp_min = 0.1
1252 tp_min = 0.1
1253
1253
1254 t0 = clock()
1254 t0 = clock()
1255 expr_ast = self.shell.compile.ast_parse(expr)
1255 expr_ast = self.shell.compile.ast_parse(expr)
1256 tp = clock()-t0
1256 tp = clock()-t0
1257
1257
1258 # Apply AST transformations
1258 # Apply AST transformations
1259 expr_ast = self.shell.transform_ast(expr_ast)
1259 expr_ast = self.shell.transform_ast(expr_ast)
1260
1260
1261 # Minimum time above which compilation time will be reported
1261 # Minimum time above which compilation time will be reported
1262 tc_min = 0.1
1262 tc_min = 0.1
1263
1263
1264 expr_val=None
1264 expr_val=None
1265 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1265 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1266 mode = 'eval'
1266 mode = 'eval'
1267 source = '<timed eval>'
1267 source = '<timed eval>'
1268 expr_ast = ast.Expression(expr_ast.body[0].value)
1268 expr_ast = ast.Expression(expr_ast.body[0].value)
1269 else:
1269 else:
1270 mode = 'exec'
1270 mode = 'exec'
1271 source = '<timed exec>'
1271 source = '<timed exec>'
1272 # multi-line %%time case
1272 # multi-line %%time case
1273 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1273 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1274 expr_val= expr_ast.body[-1]
1274 expr_val= expr_ast.body[-1]
1275 expr_ast = expr_ast.body[:-1]
1275 expr_ast = expr_ast.body[:-1]
1276 expr_ast = Module(expr_ast, [])
1276 expr_ast = Module(expr_ast, [])
1277 expr_val = ast.Expression(expr_val.value)
1277 expr_val = ast.Expression(expr_val.value)
1278
1278
1279 t0 = clock()
1279 t0 = clock()
1280 code = self.shell.compile(expr_ast, source, mode)
1280 code = self.shell.compile(expr_ast, source, mode)
1281 tc = clock()-t0
1281 tc = clock()-t0
1282
1282
1283 # skew measurement as little as possible
1283 # skew measurement as little as possible
1284 glob = self.shell.user_ns
1284 glob = self.shell.user_ns
1285 wtime = time.time
1285 wtime = time.time
1286 # time execution
1286 # time execution
1287 wall_st = wtime()
1287 wall_st = wtime()
1288 if mode=='eval':
1288 if mode=='eval':
1289 st = clock2()
1289 st = clock2()
1290 try:
1290 try:
1291 out = eval(code, glob, local_ns)
1291 out = eval(code, glob, local_ns)
1292 except:
1292 except:
1293 self.shell.showtraceback()
1293 self.shell.showtraceback()
1294 return
1294 return
1295 end = clock2()
1295 end = clock2()
1296 else:
1296 else:
1297 st = clock2()
1297 st = clock2()
1298 try:
1298 try:
1299 exec(code, glob, local_ns)
1299 exec(code, glob, local_ns)
1300 out=None
1300 out=None
1301 # multi-line %%time case
1301 # multi-line %%time case
1302 if expr_val is not None:
1302 if expr_val is not None:
1303 code_2 = self.shell.compile(expr_val, source, 'eval')
1303 code_2 = self.shell.compile(expr_val, source, 'eval')
1304 out = eval(code_2, glob, local_ns)
1304 out = eval(code_2, glob, local_ns)
1305 except:
1305 except:
1306 self.shell.showtraceback()
1306 self.shell.showtraceback()
1307 return
1307 return
1308 end = clock2()
1308 end = clock2()
1309
1309
1310 wall_end = wtime()
1310 wall_end = wtime()
1311 # Compute actual times and report
1311 # Compute actual times and report
1312 wall_time = wall_end-wall_st
1312 wall_time = wall_end-wall_st
1313 cpu_user = end[0]-st[0]
1313 cpu_user = end[0]-st[0]
1314 cpu_sys = end[1]-st[1]
1314 cpu_sys = end[1]-st[1]
1315 cpu_tot = cpu_user+cpu_sys
1315 cpu_tot = cpu_user+cpu_sys
1316 # On windows cpu_sys is always zero, so no new information to the next print
1316 # On windows cpu_sys is always zero, so no new information to the next print
1317 if sys.platform != 'win32':
1317 if sys.platform != 'win32':
1318 print("CPU times: user %s, sys: %s, total: %s" % \
1318 print("CPU times: user %s, sys: %s, total: %s" % \
1319 (_format_time(cpu_user),_format_time(cpu_sys),_format_time(cpu_tot)))
1319 (_format_time(cpu_user),_format_time(cpu_sys),_format_time(cpu_tot)))
1320 print("Wall time: %s" % _format_time(wall_time))
1320 print("Wall time: %s" % _format_time(wall_time))
1321 if tc > tc_min:
1321 if tc > tc_min:
1322 print("Compiler : %s" % _format_time(tc))
1322 print("Compiler : %s" % _format_time(tc))
1323 if tp > tp_min:
1323 if tp > tp_min:
1324 print("Parser : %s" % _format_time(tp))
1324 print("Parser : %s" % _format_time(tp))
1325 return out
1325 return out
1326
1326
1327 @skip_doctest
1327 @skip_doctest
1328 @line_magic
1328 @line_magic
1329 def macro(self, parameter_s=''):
1329 def macro(self, parameter_s=''):
1330 """Define a macro for future re-execution. It accepts ranges of history,
1330 """Define a macro for future re-execution. It accepts ranges of history,
1331 filenames or string objects.
1331 filenames or string objects.
1332
1332
1333 Usage:\\
1333 Usage:\\
1334 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1334 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1335
1335
1336 Options:
1336 Options:
1337
1337
1338 -r: use 'raw' input. By default, the 'processed' history is used,
1338 -r: use 'raw' input. By default, the 'processed' history is used,
1339 so that magics are loaded in their transformed version to valid
1339 so that magics are loaded in their transformed version to valid
1340 Python. If this option is given, the raw input as typed at the
1340 Python. If this option is given, the raw input as typed at the
1341 command line is used instead.
1341 command line is used instead.
1342
1342
1343 -q: quiet macro definition. By default, a tag line is printed
1343 -q: quiet macro definition. By default, a tag line is printed
1344 to indicate the macro has been created, and then the contents of
1344 to indicate the macro has been created, and then the contents of
1345 the macro are printed. If this option is given, then no printout
1345 the macro are printed. If this option is given, then no printout
1346 is produced once the macro is created.
1346 is produced once the macro is created.
1347
1347
1348 This will define a global variable called `name` which is a string
1348 This will define a global variable called `name` which is a string
1349 made of joining the slices and lines you specify (n1,n2,... numbers
1349 made of joining the slices and lines you specify (n1,n2,... numbers
1350 above) from your input history into a single string. This variable
1350 above) from your input history into a single string. This variable
1351 acts like an automatic function which re-executes those lines as if
1351 acts like an automatic function which re-executes those lines as if
1352 you had typed them. You just type 'name' at the prompt and the code
1352 you had typed them. You just type 'name' at the prompt and the code
1353 executes.
1353 executes.
1354
1354
1355 The syntax for indicating input ranges is described in %history.
1355 The syntax for indicating input ranges is described in %history.
1356
1356
1357 Note: as a 'hidden' feature, you can also use traditional python slice
1357 Note: as a 'hidden' feature, you can also use traditional python slice
1358 notation, where N:M means numbers N through M-1.
1358 notation, where N:M means numbers N through M-1.
1359
1359
1360 For example, if your history contains (print using %hist -n )::
1360 For example, if your history contains (print using %hist -n )::
1361
1361
1362 44: x=1
1362 44: x=1
1363 45: y=3
1363 45: y=3
1364 46: z=x+y
1364 46: z=x+y
1365 47: print x
1365 47: print x
1366 48: a=5
1366 48: a=5
1367 49: print 'x',x,'y',y
1367 49: print 'x',x,'y',y
1368
1368
1369 you can create a macro with lines 44 through 47 (included) and line 49
1369 you can create a macro with lines 44 through 47 (included) and line 49
1370 called my_macro with::
1370 called my_macro with::
1371
1371
1372 In [55]: %macro my_macro 44-47 49
1372 In [55]: %macro my_macro 44-47 49
1373
1373
1374 Now, typing `my_macro` (without quotes) will re-execute all this code
1374 Now, typing `my_macro` (without quotes) will re-execute all this code
1375 in one pass.
1375 in one pass.
1376
1376
1377 You don't need to give the line-numbers in order, and any given line
1377 You don't need to give the line-numbers in order, and any given line
1378 number can appear multiple times. You can assemble macros with any
1378 number can appear multiple times. You can assemble macros with any
1379 lines from your input history in any order.
1379 lines from your input history in any order.
1380
1380
1381 The macro is a simple object which holds its value in an attribute,
1381 The macro is a simple object which holds its value in an attribute,
1382 but IPython's display system checks for macros and executes them as
1382 but IPython's display system checks for macros and executes them as
1383 code instead of printing them when you type their name.
1383 code instead of printing them when you type their name.
1384
1384
1385 You can view a macro's contents by explicitly printing it with::
1385 You can view a macro's contents by explicitly printing it with::
1386
1386
1387 print macro_name
1387 print macro_name
1388
1388
1389 """
1389 """
1390 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1390 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1391 if not args: # List existing macros
1391 if not args: # List existing macros
1392 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1392 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1393 if len(args) == 1:
1393 if len(args) == 1:
1394 raise UsageError(
1394 raise UsageError(
1395 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1395 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1396 name, codefrom = args[0], " ".join(args[1:])
1396 name, codefrom = args[0], " ".join(args[1:])
1397
1397
1398 #print 'rng',ranges # dbg
1398 #print 'rng',ranges # dbg
1399 try:
1399 try:
1400 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1400 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1401 except (ValueError, TypeError) as e:
1401 except (ValueError, TypeError) as e:
1402 print(e.args[0])
1402 print(e.args[0])
1403 return
1403 return
1404 macro = Macro(lines)
1404 macro = Macro(lines)
1405 self.shell.define_macro(name, macro)
1405 self.shell.define_macro(name, macro)
1406 if not ( 'q' in opts) :
1406 if not ( 'q' in opts) :
1407 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1407 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1408 print('=== Macro contents: ===')
1408 print('=== Macro contents: ===')
1409 print(macro, end=' ')
1409 print(macro, end=' ')
1410
1410
1411 @magic_arguments.magic_arguments()
1411 @magic_arguments.magic_arguments()
1412 @magic_arguments.argument('output', type=str, default='', nargs='?',
1412 @magic_arguments.argument('output', type=str, default='', nargs='?',
1413 help="""The name of the variable in which to store output.
1413 help="""The name of the variable in which to store output.
1414 This is a utils.io.CapturedIO object with stdout/err attributes
1414 This is a utils.io.CapturedIO object with stdout/err attributes
1415 for the text of the captured output.
1415 for the text of the captured output.
1416
1416
1417 CapturedOutput also has a show() method for displaying the output,
1417 CapturedOutput also has a show() method for displaying the output,
1418 and __call__ as well, so you can use that to quickly display the
1418 and __call__ as well, so you can use that to quickly display the
1419 output.
1419 output.
1420
1420
1421 If unspecified, captured output is discarded.
1421 If unspecified, captured output is discarded.
1422 """
1422 """
1423 )
1423 )
1424 @magic_arguments.argument('--no-stderr', action="store_true",
1424 @magic_arguments.argument('--no-stderr', action="store_true",
1425 help="""Don't capture stderr."""
1425 help="""Don't capture stderr."""
1426 )
1426 )
1427 @magic_arguments.argument('--no-stdout', action="store_true",
1427 @magic_arguments.argument('--no-stdout', action="store_true",
1428 help="""Don't capture stdout."""
1428 help="""Don't capture stdout."""
1429 )
1429 )
1430 @magic_arguments.argument('--no-display', action="store_true",
1430 @magic_arguments.argument('--no-display', action="store_true",
1431 help="""Don't capture IPython's rich display."""
1431 help="""Don't capture IPython's rich display."""
1432 )
1432 )
1433 @cell_magic
1433 @cell_magic
1434 def capture(self, line, cell):
1434 def capture(self, line, cell):
1435 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1435 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1436 args = magic_arguments.parse_argstring(self.capture, line)
1436 args = magic_arguments.parse_argstring(self.capture, line)
1437 out = not args.no_stdout
1437 out = not args.no_stdout
1438 err = not args.no_stderr
1438 err = not args.no_stderr
1439 disp = not args.no_display
1439 disp = not args.no_display
1440 with capture_output(out, err, disp) as io:
1440 with capture_output(out, err, disp) as io:
1441 self.shell.run_cell(cell)
1441 self.shell.run_cell(cell)
1442 if args.output:
1442 if args.output:
1443 self.shell.user_ns[args.output] = io
1443 self.shell.user_ns[args.output] = io
1444
1444
1445 def parse_breakpoint(text, current_file):
1445 def parse_breakpoint(text, current_file):
1446 '''Returns (file, line) for file:line and (current_file, line) for line'''
1446 '''Returns (file, line) for file:line and (current_file, line) for line'''
1447 colon = text.find(':')
1447 colon = text.find(':')
1448 if colon == -1:
1448 if colon == -1:
1449 return current_file, int(text)
1449 return current_file, int(text)
1450 else:
1450 else:
1451 return text[:colon], int(text[colon+1:])
1451 return text[:colon], int(text[colon+1:])
1452
1452
1453 def _format_time(timespan, precision=3):
1453 def _format_time(timespan, precision=3):
1454 """Formats the timespan in a human readable form"""
1454 """Formats the timespan in a human readable form"""
1455
1455
1456 if timespan >= 60.0:
1456 if timespan >= 60.0:
1457 # we have more than a minute, format that in a human readable form
1457 # we have more than a minute, format that in a human readable form
1458 # Idea from http://snipplr.com/view/5713/
1458 # Idea from http://snipplr.com/view/5713/
1459 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1459 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1460 time = []
1460 time = []
1461 leftover = timespan
1461 leftover = timespan
1462 for suffix, length in parts:
1462 for suffix, length in parts:
1463 value = int(leftover / length)
1463 value = int(leftover / length)
1464 if value > 0:
1464 if value > 0:
1465 leftover = leftover % length
1465 leftover = leftover % length
1466 time.append(u'%s%s' % (str(value), suffix))
1466 time.append(u'%s%s' % (str(value), suffix))
1467 if leftover < 1:
1467 if leftover < 1:
1468 break
1468 break
1469 return " ".join(time)
1469 return " ".join(time)
1470
1470
1471
1471
1472 # Unfortunately the unicode 'micro' symbol can cause problems in
1472 # Unfortunately the unicode 'micro' symbol can cause problems in
1473 # certain terminals.
1473 # certain terminals.
1474 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1474 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1475 # Try to prevent crashes by being more secure than it needs to
1475 # Try to prevent crashes by being more secure than it needs to
1476 # E.g. eclipse is able to print a Β΅, but has no sys.stdout.encoding set.
1476 # E.g. eclipse is able to print a Β΅, but has no sys.stdout.encoding set.
1477 units = [u"s", u"ms",u'us',"ns"] # the save value
1477 units = [u"s", u"ms",u'us',"ns"] # the save value
1478 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1478 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1479 try:
1479 try:
1480 u'\xb5'.encode(sys.stdout.encoding)
1480 u'\xb5'.encode(sys.stdout.encoding)
1481 units = [u"s", u"ms",u'\xb5s',"ns"]
1481 units = [u"s", u"ms",u'\xb5s',"ns"]
1482 except:
1482 except:
1483 pass
1483 pass
1484 scaling = [1, 1e3, 1e6, 1e9]
1484 scaling = [1, 1e3, 1e6, 1e9]
1485
1485
1486 if timespan > 0.0:
1486 if timespan > 0.0:
1487 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1487 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1488 else:
1488 else:
1489 order = 3
1489 order = 3
1490 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
1490 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
@@ -1,708 +1,708
1 """Implementation of namespace-related magic functions.
1 """Implementation of namespace-related magic functions.
2 """
2 """
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Copyright (c) 2012 The IPython Development Team.
4 # Copyright (c) 2012 The IPython Development Team.
5 #
5 #
6 # Distributed under the terms of the Modified BSD License.
6 # Distributed under the terms of the Modified BSD License.
7 #
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10
10
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12 # Imports
12 # Imports
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14
14
15 # Stdlib
15 # Stdlib
16 import gc
16 import gc
17 import re
17 import re
18 import sys
18 import sys
19
19
20 # Our own packages
20 # Our own packages
21 from IPython.core import page
21 from IPython.core import page
22 from IPython.core.error import StdinNotImplementedError, UsageError
22 from IPython.core.error import StdinNotImplementedError, UsageError
23 from IPython.core.magic import Magics, magics_class, line_magic
23 from IPython.core.magic import Magics, magics_class, line_magic
24 from IPython.testing.skipdoctest import skip_doctest
24 from IPython.testing.skipdoctest import skip_doctest
25 from IPython.utils.encoding import DEFAULT_ENCODING
25 from IPython.utils.encoding import DEFAULT_ENCODING
26 from IPython.utils.openpy import read_py_file
26 from IPython.utils.openpy import read_py_file
27 from IPython.utils.path import get_py_filename
27 from IPython.utils.path import get_py_filename
28
28
29 #-----------------------------------------------------------------------------
29 #-----------------------------------------------------------------------------
30 # Magic implementation classes
30 # Magic implementation classes
31 #-----------------------------------------------------------------------------
31 #-----------------------------------------------------------------------------
32
32
33 @magics_class
33 @magics_class
34 class NamespaceMagics(Magics):
34 class NamespaceMagics(Magics):
35 """Magics to manage various aspects of the user's namespace.
35 """Magics to manage various aspects of the user's namespace.
36
36
37 These include listing variables, introspecting into them, etc.
37 These include listing variables, introspecting into them, etc.
38 """
38 """
39
39
40 @line_magic
40 @line_magic
41 def pinfo(self, parameter_s='', namespaces=None):
41 def pinfo(self, parameter_s='', namespaces=None):
42 """Provide detailed information about an object.
42 """Provide detailed information about an object.
43
43
44 '%pinfo object' is just a synonym for object? or ?object."""
44 '%pinfo object' is just a synonym for object? or ?object."""
45
45
46 #print 'pinfo par: <%s>' % parameter_s # dbg
46 #print 'pinfo par: <%s>' % parameter_s # dbg
47 # detail_level: 0 -> obj? , 1 -> obj??
47 # detail_level: 0 -> obj? , 1 -> obj??
48 detail_level = 0
48 detail_level = 0
49 # We need to detect if we got called as 'pinfo pinfo foo', which can
49 # We need to detect if we got called as 'pinfo pinfo foo', which can
50 # happen if the user types 'pinfo foo?' at the cmd line.
50 # happen if the user types 'pinfo foo?' at the cmd line.
51 pinfo,qmark1,oname,qmark2 = \
51 pinfo,qmark1,oname,qmark2 = \
52 re.match(r'(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
52 re.match(r'(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
53 if pinfo or qmark1 or qmark2:
53 if pinfo or qmark1 or qmark2:
54 detail_level = 1
54 detail_level = 1
55 if "*" in oname:
55 if "*" in oname:
56 self.psearch(oname)
56 self.psearch(oname)
57 else:
57 else:
58 self.shell._inspect('pinfo', oname, detail_level=detail_level,
58 self.shell._inspect('pinfo', oname, detail_level=detail_level,
59 namespaces=namespaces)
59 namespaces=namespaces)
60
60
61 @line_magic
61 @line_magic
62 def pinfo2(self, parameter_s='', namespaces=None):
62 def pinfo2(self, parameter_s='', namespaces=None):
63 """Provide extra detailed information about an object.
63 """Provide extra detailed information about an object.
64
64
65 '%pinfo2 object' is just a synonym for object?? or ??object."""
65 '%pinfo2 object' is just a synonym for object?? or ??object."""
66 self.shell._inspect('pinfo', parameter_s, detail_level=1,
66 self.shell._inspect('pinfo', parameter_s, detail_level=1,
67 namespaces=namespaces)
67 namespaces=namespaces)
68
68
69 @skip_doctest
69 @skip_doctest
70 @line_magic
70 @line_magic
71 def pdef(self, parameter_s='', namespaces=None):
71 def pdef(self, parameter_s='', namespaces=None):
72 """Print the call signature for any callable object.
72 """Print the call signature for any callable object.
73
73
74 If the object is a class, print the constructor information.
74 If the object is a class, print the constructor information.
75
75
76 Examples
76 Examples
77 --------
77 --------
78 ::
78 ::
79
79
80 In [3]: %pdef urllib.urlopen
80 In [3]: %pdef urllib.urlopen
81 urllib.urlopen(url, data=None, proxies=None)
81 urllib.urlopen(url, data=None, proxies=None)
82 """
82 """
83 self.shell._inspect('pdef',parameter_s, namespaces)
83 self.shell._inspect('pdef',parameter_s, namespaces)
84
84
85 @line_magic
85 @line_magic
86 def pdoc(self, parameter_s='', namespaces=None):
86 def pdoc(self, parameter_s='', namespaces=None):
87 """Print the docstring for an object.
87 """Print the docstring for an object.
88
88
89 If the given object is a class, it will print both the class and the
89 If the given object is a class, it will print both the class and the
90 constructor docstrings."""
90 constructor docstrings."""
91 self.shell._inspect('pdoc',parameter_s, namespaces)
91 self.shell._inspect('pdoc',parameter_s, namespaces)
92
92
93 @line_magic
93 @line_magic
94 def psource(self, parameter_s='', namespaces=None):
94 def psource(self, parameter_s='', namespaces=None):
95 """Print (or run through pager) the source code for an object."""
95 """Print (or run through pager) the source code for an object."""
96 if not parameter_s:
96 if not parameter_s:
97 raise UsageError('Missing object name.')
97 raise UsageError('Missing object name.')
98 self.shell._inspect('psource',parameter_s, namespaces)
98 self.shell._inspect('psource',parameter_s, namespaces)
99
99
100 @line_magic
100 @line_magic
101 def pfile(self, parameter_s='', namespaces=None):
101 def pfile(self, parameter_s='', namespaces=None):
102 """Print (or run through pager) the file where an object is defined.
102 """Print (or run through pager) the file where an object is defined.
103
103
104 The file opens at the line where the object definition begins. IPython
104 The file opens at the line where the object definition begins. IPython
105 will honor the environment variable PAGER if set, and otherwise will
105 will honor the environment variable PAGER if set, and otherwise will
106 do its best to print the file in a convenient form.
106 do its best to print the file in a convenient form.
107
107
108 If the given argument is not an object currently defined, IPython will
108 If the given argument is not an object currently defined, IPython will
109 try to interpret it as a filename (automatically adding a .py extension
109 try to interpret it as a filename (automatically adding a .py extension
110 if needed). You can thus use %pfile as a syntax highlighting code
110 if needed). You can thus use %pfile as a syntax highlighting code
111 viewer."""
111 viewer."""
112
112
113 # first interpret argument as an object name
113 # first interpret argument as an object name
114 out = self.shell._inspect('pfile',parameter_s, namespaces)
114 out = self.shell._inspect('pfile',parameter_s, namespaces)
115 # if not, try the input as a filename
115 # if not, try the input as a filename
116 if out == 'not found':
116 if out == 'not found':
117 try:
117 try:
118 filename = get_py_filename(parameter_s)
118 filename = get_py_filename(parameter_s)
119 except IOError as msg:
119 except IOError as msg:
120 print(msg)
120 print(msg)
121 return
121 return
122 page.page(self.shell.pycolorize(read_py_file(filename, skip_encoding_cookie=False)))
122 page.page(self.shell.pycolorize(read_py_file(filename, skip_encoding_cookie=False)))
123
123
124 @line_magic
124 @line_magic
125 def psearch(self, parameter_s=''):
125 def psearch(self, parameter_s=''):
126 """Search for object in namespaces by wildcard.
126 """Search for object in namespaces by wildcard.
127
127
128 %psearch [options] PATTERN [OBJECT TYPE]
128 %psearch [options] PATTERN [OBJECT TYPE]
129
129
130 Note: ? can be used as a synonym for %psearch, at the beginning or at
130 Note: ? can be used as a synonym for %psearch, at the beginning or at
131 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
131 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
132 rest of the command line must be unchanged (options come first), so
132 rest of the command line must be unchanged (options come first), so
133 for example the following forms are equivalent
133 for example the following forms are equivalent
134
134
135 %psearch -i a* function
135 %psearch -i a* function
136 -i a* function?
136 -i a* function?
137 ?-i a* function
137 ?-i a* function
138
138
139 Arguments:
139 Arguments:
140
140
141 PATTERN
141 PATTERN
142
142
143 where PATTERN is a string containing * as a wildcard similar to its
143 where PATTERN is a string containing * as a wildcard similar to its
144 use in a shell. The pattern is matched in all namespaces on the
144 use in a shell. The pattern is matched in all namespaces on the
145 search path. By default objects starting with a single _ are not
145 search path. By default objects starting with a single _ are not
146 matched, many IPython generated objects have a single
146 matched, many IPython generated objects have a single
147 underscore. The default is case insensitive matching. Matching is
147 underscore. The default is case insensitive matching. Matching is
148 also done on the attributes of objects and not only on the objects
148 also done on the attributes of objects and not only on the objects
149 in a module.
149 in a module.
150
150
151 [OBJECT TYPE]
151 [OBJECT TYPE]
152
152
153 Is the name of a python type from the types module. The name is
153 Is the name of a python type from the types module. The name is
154 given in lowercase without the ending type, ex. StringType is
154 given in lowercase without the ending type, ex. StringType is
155 written string. By adding a type here only objects matching the
155 written string. By adding a type here only objects matching the
156 given type are matched. Using all here makes the pattern match all
156 given type are matched. Using all here makes the pattern match all
157 types (this is the default).
157 types (this is the default).
158
158
159 Options:
159 Options:
160
160
161 -a: makes the pattern match even objects whose names start with a
161 -a: makes the pattern match even objects whose names start with a
162 single underscore. These names are normally omitted from the
162 single underscore. These names are normally omitted from the
163 search.
163 search.
164
164
165 -i/-c: make the pattern case insensitive/sensitive. If neither of
165 -i/-c: make the pattern case insensitive/sensitive. If neither of
166 these options are given, the default is read from your configuration
166 these options are given, the default is read from your configuration
167 file, with the option ``InteractiveShell.wildcards_case_sensitive``.
167 file, with the option ``InteractiveShell.wildcards_case_sensitive``.
168 If this option is not specified in your configuration file, IPython's
168 If this option is not specified in your configuration file, IPython's
169 internal default is to do a case sensitive search.
169 internal default is to do a case sensitive search.
170
170
171 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
171 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
172 specify can be searched in any of the following namespaces:
172 specify can be searched in any of the following namespaces:
173 'builtin', 'user', 'user_global','internal', 'alias', where
173 'builtin', 'user', 'user_global','internal', 'alias', where
174 'builtin' and 'user' are the search defaults. Note that you should
174 'builtin' and 'user' are the search defaults. Note that you should
175 not use quotes when specifying namespaces.
175 not use quotes when specifying namespaces.
176
176
177 -l: List all available object types for object matching. This function
177 -l: List all available object types for object matching. This function
178 can be used without arguments.
178 can be used without arguments.
179
179
180 'Builtin' contains the python module builtin, 'user' contains all
180 'Builtin' contains the python module builtin, 'user' contains all
181 user data, 'alias' only contain the shell aliases and no python
181 user data, 'alias' only contain the shell aliases and no python
182 objects, 'internal' contains objects used by IPython. The
182 objects, 'internal' contains objects used by IPython. The
183 'user_global' namespace is only used by embedded IPython instances,
183 'user_global' namespace is only used by embedded IPython instances,
184 and it contains module-level globals. You can add namespaces to the
184 and it contains module-level globals. You can add namespaces to the
185 search with -s or exclude them with -e (these options can be given
185 search with -s or exclude them with -e (these options can be given
186 more than once).
186 more than once).
187
187
188 Examples
188 Examples
189 --------
189 --------
190 ::
190 ::
191
191
192 %psearch a* -> objects beginning with an a
192 %psearch a* -> objects beginning with an a
193 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
193 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
194 %psearch a* function -> all functions beginning with an a
194 %psearch a* function -> all functions beginning with an a
195 %psearch re.e* -> objects beginning with an e in module re
195 %psearch re.e* -> objects beginning with an e in module re
196 %psearch r*.e* -> objects that start with e in modules starting in r
196 %psearch r*.e* -> objects that start with e in modules starting in r
197 %psearch r*.* string -> all strings in modules beginning with r
197 %psearch r*.* string -> all strings in modules beginning with r
198
198
199 Case sensitive search::
199 Case sensitive search::
200
200
201 %psearch -c a* list all object beginning with lower case a
201 %psearch -c a* list all object beginning with lower case a
202
202
203 Show objects beginning with a single _::
203 Show objects beginning with a single _::
204
204
205 %psearch -a _* list objects beginning with a single underscore
205 %psearch -a _* list objects beginning with a single underscore
206
206
207 List available objects::
207 List available objects::
208
208
209 %psearch -l list all available object types
209 %psearch -l list all available object types
210 """
210 """
211 # default namespaces to be searched
211 # default namespaces to be searched
212 def_search = ['user_local', 'user_global', 'builtin']
212 def_search = ['user_local', 'user_global', 'builtin']
213
213
214 # Process options/args
214 # Process options/args
215 opts,args = self.parse_options(parameter_s,'cias:e:l',list_all=True)
215 opts,args = self.parse_options(parameter_s,'cias:e:l',list_all=True)
216 opt = opts.get
216 opt = opts.get
217 shell = self.shell
217 shell = self.shell
218 psearch = shell.inspector.psearch
218 psearch = shell.inspector.psearch
219
219
220 # select list object types
220 # select list object types
221 list_types = False
221 list_types = False
222 if 'l' in opts:
222 if 'l' in opts:
223 list_types = True
223 list_types = True
224
224
225 # select case options
225 # select case options
226 if 'i' in opts:
226 if 'i' in opts:
227 ignore_case = True
227 ignore_case = True
228 elif 'c' in opts:
228 elif 'c' in opts:
229 ignore_case = False
229 ignore_case = False
230 else:
230 else:
231 ignore_case = not shell.wildcards_case_sensitive
231 ignore_case = not shell.wildcards_case_sensitive
232
232
233 # Build list of namespaces to search from user options
233 # Build list of namespaces to search from user options
234 def_search.extend(opt('s',[]))
234 def_search.extend(opt('s',[]))
235 ns_exclude = ns_exclude=opt('e',[])
235 ns_exclude = ns_exclude=opt('e',[])
236 ns_search = [nm for nm in def_search if nm not in ns_exclude]
236 ns_search = [nm for nm in def_search if nm not in ns_exclude]
237
237
238 # Call the actual search
238 # Call the actual search
239 try:
239 try:
240 psearch(args,shell.ns_table,ns_search,
240 psearch(args,shell.ns_table,ns_search,
241 show_all=opt('a'),ignore_case=ignore_case, list_types=list_types)
241 show_all=opt('a'),ignore_case=ignore_case, list_types=list_types)
242 except:
242 except:
243 shell.showtraceback()
243 shell.showtraceback()
244
244
245 @skip_doctest
245 @skip_doctest
246 @line_magic
246 @line_magic
247 def who_ls(self, parameter_s=''):
247 def who_ls(self, parameter_s=''):
248 """Return a sorted list of all interactive variables.
248 """Return a sorted list of all interactive variables.
249
249
250 If arguments are given, only variables of types matching these
250 If arguments are given, only variables of types matching these
251 arguments are returned.
251 arguments are returned.
252
252
253 Examples
253 Examples
254 --------
254 --------
255
255
256 Define two variables and list them with who_ls::
256 Define two variables and list them with who_ls::
257
257
258 In [1]: alpha = 123
258 In [1]: alpha = 123
259
259
260 In [2]: beta = 'test'
260 In [2]: beta = 'test'
261
261
262 In [3]: %who_ls
262 In [3]: %who_ls
263 Out[3]: ['alpha', 'beta']
263 Out[3]: ['alpha', 'beta']
264
264
265 In [4]: %who_ls int
265 In [4]: %who_ls int
266 Out[4]: ['alpha']
266 Out[4]: ['alpha']
267
267
268 In [5]: %who_ls str
268 In [5]: %who_ls str
269 Out[5]: ['beta']
269 Out[5]: ['beta']
270 """
270 """
271
271
272 user_ns = self.shell.user_ns
272 user_ns = self.shell.user_ns
273 user_ns_hidden = self.shell.user_ns_hidden
273 user_ns_hidden = self.shell.user_ns_hidden
274 nonmatching = object() # This can never be in user_ns
274 nonmatching = object() # This can never be in user_ns
275 out = [ i for i in user_ns
275 out = [ i for i in user_ns
276 if not i.startswith('_') \
276 if not i.startswith('_') \
277 and (user_ns[i] is not user_ns_hidden.get(i, nonmatching)) ]
277 and (user_ns[i] is not user_ns_hidden.get(i, nonmatching)) ]
278
278
279 typelist = parameter_s.split()
279 typelist = parameter_s.split()
280 if typelist:
280 if typelist:
281 typeset = set(typelist)
281 typeset = set(typelist)
282 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
282 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
283
283
284 out.sort()
284 out.sort()
285 return out
285 return out
286
286
287 @skip_doctest
287 @skip_doctest
288 @line_magic
288 @line_magic
289 def who(self, parameter_s=''):
289 def who(self, parameter_s=''):
290 """Print all interactive variables, with some minimal formatting.
290 """Print all interactive variables, with some minimal formatting.
291
291
292 If any arguments are given, only variables whose type matches one of
292 If any arguments are given, only variables whose type matches one of
293 these are printed. For example::
293 these are printed. For example::
294
294
295 %who function str
295 %who function str
296
296
297 will only list functions and strings, excluding all other types of
297 will only list functions and strings, excluding all other types of
298 variables. To find the proper type names, simply use type(var) at a
298 variables. To find the proper type names, simply use type(var) at a
299 command line to see how python prints type names. For example:
299 command line to see how python prints type names. For example:
300
300
301 ::
301 ::
302
302
303 In [1]: type('hello')\\
303 In [1]: type('hello')\\
304 Out[1]: <type 'str'>
304 Out[1]: <type 'str'>
305
305
306 indicates that the type name for strings is 'str'.
306 indicates that the type name for strings is 'str'.
307
307
308 ``%who`` always excludes executed names loaded through your configuration
308 ``%who`` always excludes executed names loaded through your configuration
309 file and things which are internal to IPython.
309 file and things which are internal to IPython.
310
310
311 This is deliberate, as typically you may load many modules and the
311 This is deliberate, as typically you may load many modules and the
312 purpose of %who is to show you only what you've manually defined.
312 purpose of %who is to show you only what you've manually defined.
313
313
314 Examples
314 Examples
315 --------
315 --------
316
316
317 Define two variables and list them with who::
317 Define two variables and list them with who::
318
318
319 In [1]: alpha = 123
319 In [1]: alpha = 123
320
320
321 In [2]: beta = 'test'
321 In [2]: beta = 'test'
322
322
323 In [3]: %who
323 In [3]: %who
324 alpha beta
324 alpha beta
325
325
326 In [4]: %who int
326 In [4]: %who int
327 alpha
327 alpha
328
328
329 In [5]: %who str
329 In [5]: %who str
330 beta
330 beta
331 """
331 """
332
332
333 varlist = self.who_ls(parameter_s)
333 varlist = self.who_ls(parameter_s)
334 if not varlist:
334 if not varlist:
335 if parameter_s:
335 if parameter_s:
336 print('No variables match your requested type.')
336 print('No variables match your requested type.')
337 else:
337 else:
338 print('Interactive namespace is empty.')
338 print('Interactive namespace is empty.')
339 return
339 return
340
340
341 # if we have variables, move on...
341 # if we have variables, move on...
342 count = 0
342 count = 0
343 for i in varlist:
343 for i in varlist:
344 print(i+'\t', end=' ')
344 print(i+'\t', end=' ')
345 count += 1
345 count += 1
346 if count > 8:
346 if count > 8:
347 count = 0
347 count = 0
348 print()
348 print()
349 print()
349 print()
350
350
351 @skip_doctest
351 @skip_doctest
352 @line_magic
352 @line_magic
353 def whos(self, parameter_s=''):
353 def whos(self, parameter_s=''):
354 """Like %who, but gives some extra information about each variable.
354 """Like %who, but gives some extra information about each variable.
355
355
356 The same type filtering of %who can be applied here.
356 The same type filtering of %who can be applied here.
357
357
358 For all variables, the type is printed. Additionally it prints:
358 For all variables, the type is printed. Additionally it prints:
359
359
360 - For {},[],(): their length.
360 - For {},[],(): their length.
361
361
362 - For numpy arrays, a summary with shape, number of
362 - For numpy arrays, a summary with shape, number of
363 elements, typecode and size in memory.
363 elements, typecode and size in memory.
364
364
365 - Everything else: a string representation, snipping their middle if
365 - Everything else: a string representation, snipping their middle if
366 too long.
366 too long.
367
367
368 Examples
368 Examples
369 --------
369 --------
370
370
371 Define two variables and list them with whos::
371 Define two variables and list them with whos::
372
372
373 In [1]: alpha = 123
373 In [1]: alpha = 123
374
374
375 In [2]: beta = 'test'
375 In [2]: beta = 'test'
376
376
377 In [3]: %whos
377 In [3]: %whos
378 Variable Type Data/Info
378 Variable Type Data/Info
379 --------------------------------
379 --------------------------------
380 alpha int 123
380 alpha int 123
381 beta str test
381 beta str test
382 """
382 """
383
383
384 varnames = self.who_ls(parameter_s)
384 varnames = self.who_ls(parameter_s)
385 if not varnames:
385 if not varnames:
386 if parameter_s:
386 if parameter_s:
387 print('No variables match your requested type.')
387 print('No variables match your requested type.')
388 else:
388 else:
389 print('Interactive namespace is empty.')
389 print('Interactive namespace is empty.')
390 return
390 return
391
391
392 # if we have variables, move on...
392 # if we have variables, move on...
393
393
394 # for these types, show len() instead of data:
394 # for these types, show len() instead of data:
395 seq_types = ['dict', 'list', 'tuple']
395 seq_types = ['dict', 'list', 'tuple']
396
396
397 # for numpy arrays, display summary info
397 # for numpy arrays, display summary info
398 ndarray_type = None
398 ndarray_type = None
399 if 'numpy' in sys.modules:
399 if 'numpy' in sys.modules:
400 try:
400 try:
401 from numpy import ndarray
401 from numpy import ndarray
402 except ImportError:
402 except ImportError:
403 pass
403 pass
404 else:
404 else:
405 ndarray_type = ndarray.__name__
405 ndarray_type = ndarray.__name__
406
406
407 # Find all variable names and types so we can figure out column sizes
407 # Find all variable names and types so we can figure out column sizes
408
408
409 # some types are well known and can be shorter
409 # some types are well known and can be shorter
410 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
410 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
411 def type_name(v):
411 def type_name(v):
412 tn = type(v).__name__
412 tn = type(v).__name__
413 return abbrevs.get(tn,tn)
413 return abbrevs.get(tn,tn)
414
414
415 varlist = [self.shell.user_ns[n] for n in varnames]
415 varlist = [self.shell.user_ns[n] for n in varnames]
416
416
417 typelist = []
417 typelist = []
418 for vv in varlist:
418 for vv in varlist:
419 tt = type_name(vv)
419 tt = type_name(vv)
420
420
421 if tt=='instance':
421 if tt=='instance':
422 typelist.append( abbrevs.get(str(vv.__class__),
422 typelist.append( abbrevs.get(str(vv.__class__),
423 str(vv.__class__)))
423 str(vv.__class__)))
424 else:
424 else:
425 typelist.append(tt)
425 typelist.append(tt)
426
426
427 # column labels and # of spaces as separator
427 # column labels and # of spaces as separator
428 varlabel = 'Variable'
428 varlabel = 'Variable'
429 typelabel = 'Type'
429 typelabel = 'Type'
430 datalabel = 'Data/Info'
430 datalabel = 'Data/Info'
431 colsep = 3
431 colsep = 3
432 # variable format strings
432 # variable format strings
433 vformat = "{0:<{varwidth}}{1:<{typewidth}}"
433 vformat = "{0:<{varwidth}}{1:<{typewidth}}"
434 aformat = "%s: %s elems, type `%s`, %s bytes"
434 aformat = "%s: %s elems, type `%s`, %s bytes"
435 # find the size of the columns to format the output nicely
435 # find the size of the columns to format the output nicely
436 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
436 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
437 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
437 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
438 # table header
438 # table header
439 print(varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
439 print(varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
440 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1))
440 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1))
441 # and the table itself
441 # and the table itself
442 kb = 1024
442 kb = 1024
443 Mb = 1048576 # kb**2
443 Mb = 1048576 # kb**2
444 for vname,var,vtype in zip(varnames,varlist,typelist):
444 for vname,var,vtype in zip(varnames,varlist,typelist):
445 print(vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth), end=' ')
445 print(vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth), end=' ')
446 if vtype in seq_types:
446 if vtype in seq_types:
447 print("n="+str(len(var)))
447 print("n="+str(len(var)))
448 elif vtype == ndarray_type:
448 elif vtype == ndarray_type:
449 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
449 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
450 if vtype==ndarray_type:
450 if vtype==ndarray_type:
451 # numpy
451 # numpy
452 vsize = var.size
452 vsize = var.size
453 vbytes = vsize*var.itemsize
453 vbytes = vsize*var.itemsize
454 vdtype = var.dtype
454 vdtype = var.dtype
455
455
456 if vbytes < 100000:
456 if vbytes < 100000:
457 print(aformat % (vshape, vsize, vdtype, vbytes))
457 print(aformat % (vshape, vsize, vdtype, vbytes))
458 else:
458 else:
459 print(aformat % (vshape, vsize, vdtype, vbytes), end=' ')
459 print(aformat % (vshape, vsize, vdtype, vbytes), end=' ')
460 if vbytes < Mb:
460 if vbytes < Mb:
461 print('(%s kb)' % (vbytes/kb,))
461 print('(%s kb)' % (vbytes/kb,))
462 else:
462 else:
463 print('(%s Mb)' % (vbytes/Mb,))
463 print('(%s Mb)' % (vbytes/Mb,))
464 else:
464 else:
465 try:
465 try:
466 vstr = str(var)
466 vstr = str(var)
467 except UnicodeEncodeError:
467 except UnicodeEncodeError:
468 vstr = var.encode(DEFAULT_ENCODING,
468 vstr = var.encode(DEFAULT_ENCODING,
469 'backslashreplace')
469 'backslashreplace')
470 except:
470 except:
471 vstr = "<object with id %d (str() failed)>" % id(var)
471 vstr = "<object with id %d (str() failed)>" % id(var)
472 vstr = vstr.replace('\n', '\\n')
472 vstr = vstr.replace('\n', '\\n')
473 if len(vstr) < 50:
473 if len(vstr) < 50:
474 print(vstr)
474 print(vstr)
475 else:
475 else:
476 print(vstr[:25] + "<...>" + vstr[-25:])
476 print(vstr[:25] + "<...>" + vstr[-25:])
477
477
478 @line_magic
478 @line_magic
479 def reset(self, parameter_s=''):
479 def reset(self, parameter_s=''):
480 """Resets the namespace by removing all names defined by the user, if
480 """Resets the namespace by removing all names defined by the user, if
481 called without arguments, or by removing some types of objects, such
481 called without arguments, or by removing some types of objects, such
482 as everything currently in IPython's In[] and Out[] containers (see
482 as everything currently in IPython's In[] and Out[] containers (see
483 the parameters for details).
483 the parameters for details).
484
484
485 Parameters
485 Parameters
486 ----------
486 ----------
487 -f : force reset without asking for confirmation.
487 -f : force reset without asking for confirmation.
488
488
489 -s : 'Soft' reset: Only clears your namespace, leaving history intact.
489 -s : 'Soft' reset: Only clears your namespace, leaving history intact.
490 References to objects may be kept. By default (without this option),
490 References to objects may be kept. By default (without this option),
491 we do a 'hard' reset, giving you a new session and removing all
491 we do a 'hard' reset, giving you a new session and removing all
492 references to objects from the current session.
492 references to objects from the current session.
493
493
494 in : reset input history
494 in : reset input history
495
495
496 out : reset output history
496 out : reset output history
497
497
498 dhist : reset directory history
498 dhist : reset directory history
499
499
500 array : reset only variables that are NumPy arrays
500 array : reset only variables that are NumPy arrays
501
501
502 See Also
502 See Also
503 --------
503 --------
504 reset_selective : invoked as ``%reset_selective``
504 reset_selective : invoked as ``%reset_selective``
505
505
506 Examples
506 Examples
507 --------
507 --------
508 ::
508 ::
509
509
510 In [6]: a = 1
510 In [6]: a = 1
511
511
512 In [7]: a
512 In [7]: a
513 Out[7]: 1
513 Out[7]: 1
514
514
515 In [8]: 'a' in get_ipython().user_ns
515 In [8]: 'a' in get_ipython().user_ns
516 Out[8]: True
516 Out[8]: True
517
517
518 In [9]: %reset -f
518 In [9]: %reset -f
519
519
520 In [1]: 'a' in get_ipython().user_ns
520 In [1]: 'a' in get_ipython().user_ns
521 Out[1]: False
521 Out[1]: False
522
522
523 In [2]: %reset -f in
523 In [2]: %reset -f in
524 Flushing input history
524 Flushing input history
525
525
526 In [3]: %reset -f dhist in
526 In [3]: %reset -f dhist in
527 Flushing directory history
527 Flushing directory history
528 Flushing input history
528 Flushing input history
529
529
530 Notes
530 Notes
531 -----
531 -----
532 Calling this magic from clients that do not implement standard input,
532 Calling this magic from clients that do not implement standard input,
533 such as the ipython notebook interface, will reset the namespace
533 such as the ipython notebook interface, will reset the namespace
534 without confirmation.
534 without confirmation.
535 """
535 """
536 opts, args = self.parse_options(parameter_s,'sf', mode='list')
536 opts, args = self.parse_options(parameter_s,'sf', mode='list')
537 if 'f' in opts:
537 if 'f' in opts:
538 ans = True
538 ans = True
539 else:
539 else:
540 try:
540 try:
541 ans = self.shell.ask_yes_no(
541 ans = self.shell.ask_yes_no(
542 "Once deleted, variables cannot be recovered. Proceed (y/[n])?",
542 "Once deleted, variables cannot be recovered. Proceed (y/[n])?",
543 default='n')
543 default='n')
544 except StdinNotImplementedError:
544 except StdinNotImplementedError:
545 ans = True
545 ans = True
546 if not ans:
546 if not ans:
547 print('Nothing done.')
547 print('Nothing done.')
548 return
548 return
549
549
550 if 's' in opts: # Soft reset
550 if 's' in opts: # Soft reset
551 user_ns = self.shell.user_ns
551 user_ns = self.shell.user_ns
552 for i in self.who_ls():
552 for i in self.who_ls():
553 del(user_ns[i])
553 del(user_ns[i])
554 elif len(args) == 0: # Hard reset
554 elif len(args) == 0: # Hard reset
555 self.shell.reset(new_session = False)
555 self.shell.reset(new_session = False)
556
556
557 # reset in/out/dhist/array: previously extensinions/clearcmd.py
557 # reset in/out/dhist/array: previously extensinions/clearcmd.py
558 ip = self.shell
558 ip = self.shell
559 user_ns = self.shell.user_ns # local lookup, heavily used
559 user_ns = self.shell.user_ns # local lookup, heavily used
560
560
561 for target in args:
561 for target in args:
562 target = target.lower() # make matches case insensitive
562 target = target.lower() # make matches case insensitive
563 if target == 'out':
563 if target == 'out':
564 print("Flushing output cache (%d entries)" % len(user_ns['_oh']))
564 print("Flushing output cache (%d entries)" % len(user_ns['_oh']))
565 self.shell.displayhook.flush()
565 self.shell.displayhook.flush()
566
566
567 elif target == 'in':
567 elif target == 'in':
568 print("Flushing input history")
568 print("Flushing input history")
569 pc = self.shell.displayhook.prompt_count + 1
569 pc = self.shell.displayhook.prompt_count + 1
570 for n in range(1, pc):
570 for n in range(1, pc):
571 key = '_i'+repr(n)
571 key = '_i'+repr(n)
572 user_ns.pop(key,None)
572 user_ns.pop(key,None)
573 user_ns.update(dict(_i=u'',_ii=u'',_iii=u''))
573 user_ns.update(dict(_i=u'',_ii=u'',_iii=u''))
574 hm = ip.history_manager
574 hm = ip.history_manager
575 # don't delete these, as %save and %macro depending on the
575 # don't delete these, as %save and %macro depending on the
576 # length of these lists to be preserved
576 # length of these lists to be preserved
577 hm.input_hist_parsed[:] = [''] * pc
577 hm.input_hist_parsed[:] = [''] * pc
578 hm.input_hist_raw[:] = [''] * pc
578 hm.input_hist_raw[:] = [''] * pc
579 # hm has internal machinery for _i,_ii,_iii, clear it out
579 # hm has internal machinery for _i,_ii,_iii, clear it out
580 hm._i = hm._ii = hm._iii = hm._i00 = u''
580 hm._i = hm._ii = hm._iii = hm._i00 = u''
581
581
582 elif target == 'array':
582 elif target == 'array':
583 # Support cleaning up numpy arrays
583 # Support cleaning up numpy arrays
584 try:
584 try:
585 from numpy import ndarray
585 from numpy import ndarray
586 # This must be done with items and not iteritems because
586 # This must be done with items and not iteritems because
587 # we're going to modify the dict in-place.
587 # we're going to modify the dict in-place.
588 for x,val in list(user_ns.items()):
588 for x,val in list(user_ns.items()):
589 if isinstance(val,ndarray):
589 if isinstance(val,ndarray):
590 del user_ns[x]
590 del user_ns[x]
591 except ImportError:
591 except ImportError:
592 print("reset array only works if Numpy is available.")
592 print("reset array only works if Numpy is available.")
593
593
594 elif target == 'dhist':
594 elif target == 'dhist':
595 print("Flushing directory history")
595 print("Flushing directory history")
596 del user_ns['_dh'][:]
596 del user_ns['_dh'][:]
597
597
598 else:
598 else:
599 print("Don't know how to reset ", end=' ')
599 print("Don't know how to reset ", end=' ')
600 print(target + ", please run `%reset?` for details")
600 print(target + ", please run `%reset?` for details")
601
601
602 gc.collect()
602 gc.collect()
603
603
604 @line_magic
604 @line_magic
605 def reset_selective(self, parameter_s=''):
605 def reset_selective(self, parameter_s=''):
606 """Resets the namespace by removing names defined by the user.
606 """Resets the namespace by removing names defined by the user.
607
607
608 Input/Output history are left around in case you need them.
608 Input/Output history are left around in case you need them.
609
609
610 %reset_selective [-f] regex
610 %reset_selective [-f] regex
611
611
612 No action is taken if regex is not included
612 No action is taken if regex is not included
613
613
614 Options
614 Options
615 -f : force reset without asking for confirmation.
615 -f : force reset without asking for confirmation.
616
616
617 See Also
617 See Also
618 --------
618 --------
619 reset : invoked as ``%reset``
619 reset : invoked as ``%reset``
620
620
621 Examples
621 Examples
622 --------
622 --------
623
623
624 We first fully reset the namespace so your output looks identical to
624 We first fully reset the namespace so your output looks identical to
625 this example for pedagogical reasons; in practice you do not need a
625 this example for pedagogical reasons; in practice you do not need a
626 full reset::
626 full reset::
627
627
628 In [1]: %reset -f
628 In [1]: %reset -f
629
629
630 Now, with a clean namespace we can make a few variables and use
630 Now, with a clean namespace we can make a few variables and use
631 ``%reset_selective`` to only delete names that match our regexp::
631 ``%reset_selective`` to only delete names that match our regexp::
632
632
633 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
633 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
634
634
635 In [3]: who_ls
635 In [3]: who_ls
636 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
636 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
637
637
638 In [4]: %reset_selective -f b[2-3]m
638 In [4]: %reset_selective -f b[2-3]m
639
639
640 In [5]: who_ls
640 In [5]: who_ls
641 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
641 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
642
642
643 In [6]: %reset_selective -f d
643 In [6]: %reset_selective -f d
644
644
645 In [7]: who_ls
645 In [7]: who_ls
646 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
646 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
647
647
648 In [8]: %reset_selective -f c
648 In [8]: %reset_selective -f c
649
649
650 In [9]: who_ls
650 In [9]: who_ls
651 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
651 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
652
652
653 In [10]: %reset_selective -f b
653 In [10]: %reset_selective -f b
654
654
655 In [11]: who_ls
655 In [11]: who_ls
656 Out[11]: ['a']
656 Out[11]: ['a']
657
657
658 Notes
658 Notes
659 -----
659 -----
660 Calling this magic from clients that do not implement standard input,
660 Calling this magic from clients that do not implement standard input,
661 such as the ipython notebook interface, will reset the namespace
661 such as the ipython notebook interface, will reset the namespace
662 without confirmation.
662 without confirmation.
663 """
663 """
664
664
665 opts, regex = self.parse_options(parameter_s,'f')
665 opts, regex = self.parse_options(parameter_s,'f')
666
666
667 if 'f' in opts:
667 if 'f' in opts:
668 ans = True
668 ans = True
669 else:
669 else:
670 try:
670 try:
671 ans = self.shell.ask_yes_no(
671 ans = self.shell.ask_yes_no(
672 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
672 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
673 default='n')
673 default='n')
674 except StdinNotImplementedError:
674 except StdinNotImplementedError:
675 ans = True
675 ans = True
676 if not ans:
676 if not ans:
677 print('Nothing done.')
677 print('Nothing done.')
678 return
678 return
679 user_ns = self.shell.user_ns
679 user_ns = self.shell.user_ns
680 if not regex:
680 if not regex:
681 print('No regex pattern specified. Nothing done.')
681 print('No regex pattern specified. Nothing done.')
682 return
682 return
683 else:
683 else:
684 try:
684 try:
685 m = re.compile(regex)
685 m = re.compile(regex)
686 except TypeError:
686 except TypeError as e:
687 raise TypeError('regex must be a string or compiled pattern')
687 raise TypeError('regex must be a string or compiled pattern') from e
688 for i in self.who_ls():
688 for i in self.who_ls():
689 if m.search(i):
689 if m.search(i):
690 del(user_ns[i])
690 del(user_ns[i])
691
691
692 @line_magic
692 @line_magic
693 def xdel(self, parameter_s=''):
693 def xdel(self, parameter_s=''):
694 """Delete a variable, trying to clear it from anywhere that
694 """Delete a variable, trying to clear it from anywhere that
695 IPython's machinery has references to it. By default, this uses
695 IPython's machinery has references to it. By default, this uses
696 the identity of the named object in the user namespace to remove
696 the identity of the named object in the user namespace to remove
697 references held under other names. The object is also removed
697 references held under other names. The object is also removed
698 from the output history.
698 from the output history.
699
699
700 Options
700 Options
701 -n : Delete the specified name from all namespaces, without
701 -n : Delete the specified name from all namespaces, without
702 checking their identity.
702 checking their identity.
703 """
703 """
704 opts, varname = self.parse_options(parameter_s,'n')
704 opts, varname = self.parse_options(parameter_s,'n')
705 try:
705 try:
706 self.shell.del_var(varname, ('n' in opts))
706 self.shell.del_var(varname, ('n' in opts))
707 except (NameError, ValueError) as e:
707 except (NameError, ValueError) as e:
708 print(type(e).__name__ +": "+ str(e))
708 print(type(e).__name__ +": "+ str(e))
@@ -1,857 +1,857
1 """Implementation of magic functions for interaction with the OS.
1 """Implementation of magic functions for interaction with the OS.
2
2
3 Note: this module is named 'osm' instead of 'os' to avoid a collision with the
3 Note: this module is named 'osm' instead of 'os' to avoid a collision with the
4 builtin.
4 builtin.
5 """
5 """
6 # Copyright (c) IPython Development Team.
6 # Copyright (c) IPython Development Team.
7 # Distributed under the terms of the Modified BSD License.
7 # Distributed under the terms of the Modified BSD License.
8
8
9 import io
9 import io
10 import os
10 import os
11 import re
11 import re
12 import sys
12 import sys
13 from pprint import pformat
13 from pprint import pformat
14
14
15 from IPython.core import magic_arguments
15 from IPython.core import magic_arguments
16 from IPython.core import oinspect
16 from IPython.core import oinspect
17 from IPython.core import page
17 from IPython.core import page
18 from IPython.core.alias import AliasError, Alias
18 from IPython.core.alias import AliasError, Alias
19 from IPython.core.error import UsageError
19 from IPython.core.error import UsageError
20 from IPython.core.magic import (
20 from IPython.core.magic import (
21 Magics, compress_dhist, magics_class, line_magic, cell_magic, line_cell_magic
21 Magics, compress_dhist, magics_class, line_magic, cell_magic, line_cell_magic
22 )
22 )
23 from IPython.testing.skipdoctest import skip_doctest
23 from IPython.testing.skipdoctest import skip_doctest
24 from IPython.utils.openpy import source_to_unicode
24 from IPython.utils.openpy import source_to_unicode
25 from IPython.utils.process import abbrev_cwd
25 from IPython.utils.process import abbrev_cwd
26 from IPython.utils.terminal import set_term_title
26 from IPython.utils.terminal import set_term_title
27 from traitlets import Bool
27 from traitlets import Bool
28 from warnings import warn
28 from warnings import warn
29
29
30
30
31 @magics_class
31 @magics_class
32 class OSMagics(Magics):
32 class OSMagics(Magics):
33 """Magics to interact with the underlying OS (shell-type functionality).
33 """Magics to interact with the underlying OS (shell-type functionality).
34 """
34 """
35
35
36 cd_force_quiet = Bool(False,
36 cd_force_quiet = Bool(False,
37 help="Force %cd magic to be quiet even if -q is not passed."
37 help="Force %cd magic to be quiet even if -q is not passed."
38 ).tag(config=True)
38 ).tag(config=True)
39
39
40 def __init__(self, shell=None, **kwargs):
40 def __init__(self, shell=None, **kwargs):
41
41
42 # Now define isexec in a cross platform manner.
42 # Now define isexec in a cross platform manner.
43 self.is_posix = False
43 self.is_posix = False
44 self.execre = None
44 self.execre = None
45 if os.name == 'posix':
45 if os.name == 'posix':
46 self.is_posix = True
46 self.is_posix = True
47 else:
47 else:
48 try:
48 try:
49 winext = os.environ['pathext'].replace(';','|').replace('.','')
49 winext = os.environ['pathext'].replace(';','|').replace('.','')
50 except KeyError:
50 except KeyError:
51 winext = 'exe|com|bat|py'
51 winext = 'exe|com|bat|py'
52 try:
52 try:
53 self.execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
53 self.execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
54 except re.error:
54 except re.error:
55 warn("Seems like your pathext environmental "
55 warn("Seems like your pathext environmental "
56 "variable is malformed. Please check it to "
56 "variable is malformed. Please check it to "
57 "enable a proper handle of file extensions "
57 "enable a proper handle of file extensions "
58 "managed for your system")
58 "managed for your system")
59 winext = 'exe|com|bat|py'
59 winext = 'exe|com|bat|py'
60 self.execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
60 self.execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
61
61
62 # call up the chain
62 # call up the chain
63 super().__init__(shell=shell, **kwargs)
63 super().__init__(shell=shell, **kwargs)
64
64
65
65
66 @skip_doctest
66 @skip_doctest
67 def _isexec_POSIX(self, file):
67 def _isexec_POSIX(self, file):
68 """
68 """
69 Test for executable on a POSIX system
69 Test for executable on a POSIX system
70 """
70 """
71 if os.access(file.path, os.X_OK):
71 if os.access(file.path, os.X_OK):
72 # will fail on maxOS if access is not X_OK
72 # will fail on maxOS if access is not X_OK
73 return file.is_file()
73 return file.is_file()
74 return False
74 return False
75
75
76
76
77
77
78 @skip_doctest
78 @skip_doctest
79 def _isexec_WIN(self, file):
79 def _isexec_WIN(self, file):
80 """
80 """
81 Test for executable file on non POSIX system
81 Test for executable file on non POSIX system
82 """
82 """
83 return file.is_file() and self.execre.match(file.name) is not None
83 return file.is_file() and self.execre.match(file.name) is not None
84
84
85 @skip_doctest
85 @skip_doctest
86 def isexec(self, file):
86 def isexec(self, file):
87 """
87 """
88 Test for executable file on non POSIX system
88 Test for executable file on non POSIX system
89 """
89 """
90 if self.is_posix:
90 if self.is_posix:
91 return self._isexec_POSIX(file)
91 return self._isexec_POSIX(file)
92 else:
92 else:
93 return self._isexec_WIN(file)
93 return self._isexec_WIN(file)
94
94
95
95
96 @skip_doctest
96 @skip_doctest
97 @line_magic
97 @line_magic
98 def alias(self, parameter_s=''):
98 def alias(self, parameter_s=''):
99 """Define an alias for a system command.
99 """Define an alias for a system command.
100
100
101 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
101 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
102
102
103 Then, typing 'alias_name params' will execute the system command 'cmd
103 Then, typing 'alias_name params' will execute the system command 'cmd
104 params' (from your underlying operating system).
104 params' (from your underlying operating system).
105
105
106 Aliases have lower precedence than magic functions and Python normal
106 Aliases have lower precedence than magic functions and Python normal
107 variables, so if 'foo' is both a Python variable and an alias, the
107 variables, so if 'foo' is both a Python variable and an alias, the
108 alias can not be executed until 'del foo' removes the Python variable.
108 alias can not be executed until 'del foo' removes the Python variable.
109
109
110 You can use the %l specifier in an alias definition to represent the
110 You can use the %l specifier in an alias definition to represent the
111 whole line when the alias is called. For example::
111 whole line when the alias is called. For example::
112
112
113 In [2]: alias bracket echo "Input in brackets: <%l>"
113 In [2]: alias bracket echo "Input in brackets: <%l>"
114 In [3]: bracket hello world
114 In [3]: bracket hello world
115 Input in brackets: <hello world>
115 Input in brackets: <hello world>
116
116
117 You can also define aliases with parameters using %s specifiers (one
117 You can also define aliases with parameters using %s specifiers (one
118 per parameter)::
118 per parameter)::
119
119
120 In [1]: alias parts echo first %s second %s
120 In [1]: alias parts echo first %s second %s
121 In [2]: %parts A B
121 In [2]: %parts A B
122 first A second B
122 first A second B
123 In [3]: %parts A
123 In [3]: %parts A
124 Incorrect number of arguments: 2 expected.
124 Incorrect number of arguments: 2 expected.
125 parts is an alias to: 'echo first %s second %s'
125 parts is an alias to: 'echo first %s second %s'
126
126
127 Note that %l and %s are mutually exclusive. You can only use one or
127 Note that %l and %s are mutually exclusive. You can only use one or
128 the other in your aliases.
128 the other in your aliases.
129
129
130 Aliases expand Python variables just like system calls using ! or !!
130 Aliases expand Python variables just like system calls using ! or !!
131 do: all expressions prefixed with '$' get expanded. For details of
131 do: all expressions prefixed with '$' get expanded. For details of
132 the semantic rules, see PEP-215:
132 the semantic rules, see PEP-215:
133 http://www.python.org/peps/pep-0215.html. This is the library used by
133 http://www.python.org/peps/pep-0215.html. This is the library used by
134 IPython for variable expansion. If you want to access a true shell
134 IPython for variable expansion. If you want to access a true shell
135 variable, an extra $ is necessary to prevent its expansion by
135 variable, an extra $ is necessary to prevent its expansion by
136 IPython::
136 IPython::
137
137
138 In [6]: alias show echo
138 In [6]: alias show echo
139 In [7]: PATH='A Python string'
139 In [7]: PATH='A Python string'
140 In [8]: show $PATH
140 In [8]: show $PATH
141 A Python string
141 A Python string
142 In [9]: show $$PATH
142 In [9]: show $$PATH
143 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
143 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
144
144
145 You can use the alias facility to access all of $PATH. See the %rehashx
145 You can use the alias facility to access all of $PATH. See the %rehashx
146 function, which automatically creates aliases for the contents of your
146 function, which automatically creates aliases for the contents of your
147 $PATH.
147 $PATH.
148
148
149 If called with no parameters, %alias prints the current alias table
149 If called with no parameters, %alias prints the current alias table
150 for your system. For posix systems, the default aliases are 'cat',
150 for your system. For posix systems, the default aliases are 'cat',
151 'cp', 'mv', 'rm', 'rmdir', and 'mkdir', and other platform-specific
151 'cp', 'mv', 'rm', 'rmdir', and 'mkdir', and other platform-specific
152 aliases are added. For windows-based systems, the default aliases are
152 aliases are added. For windows-based systems, the default aliases are
153 'copy', 'ddir', 'echo', 'ls', 'ldir', 'mkdir', 'ren', and 'rmdir'.
153 'copy', 'ddir', 'echo', 'ls', 'ldir', 'mkdir', 'ren', and 'rmdir'.
154
154
155 You can see the definition of alias by adding a question mark in the
155 You can see the definition of alias by adding a question mark in the
156 end::
156 end::
157
157
158 In [1]: cat?
158 In [1]: cat?
159 Repr: <alias cat for 'cat'>"""
159 Repr: <alias cat for 'cat'>"""
160
160
161 par = parameter_s.strip()
161 par = parameter_s.strip()
162 if not par:
162 if not par:
163 aliases = sorted(self.shell.alias_manager.aliases)
163 aliases = sorted(self.shell.alias_manager.aliases)
164 # stored = self.shell.db.get('stored_aliases', {} )
164 # stored = self.shell.db.get('stored_aliases', {} )
165 # for k, v in stored:
165 # for k, v in stored:
166 # atab.append(k, v[0])
166 # atab.append(k, v[0])
167
167
168 print("Total number of aliases:", len(aliases))
168 print("Total number of aliases:", len(aliases))
169 sys.stdout.flush()
169 sys.stdout.flush()
170 return aliases
170 return aliases
171
171
172 # Now try to define a new one
172 # Now try to define a new one
173 try:
173 try:
174 alias,cmd = par.split(None, 1)
174 alias,cmd = par.split(None, 1)
175 except TypeError:
175 except TypeError:
176 print(oinspect.getdoc(self.alias))
176 print(oinspect.getdoc(self.alias))
177 return
177 return
178
178
179 try:
179 try:
180 self.shell.alias_manager.define_alias(alias, cmd)
180 self.shell.alias_manager.define_alias(alias, cmd)
181 except AliasError as e:
181 except AliasError as e:
182 print(e)
182 print(e)
183 # end magic_alias
183 # end magic_alias
184
184
185 @line_magic
185 @line_magic
186 def unalias(self, parameter_s=''):
186 def unalias(self, parameter_s=''):
187 """Remove an alias"""
187 """Remove an alias"""
188
188
189 aname = parameter_s.strip()
189 aname = parameter_s.strip()
190 try:
190 try:
191 self.shell.alias_manager.undefine_alias(aname)
191 self.shell.alias_manager.undefine_alias(aname)
192 except ValueError as e:
192 except ValueError as e:
193 print(e)
193 print(e)
194 return
194 return
195
195
196 stored = self.shell.db.get('stored_aliases', {} )
196 stored = self.shell.db.get('stored_aliases', {} )
197 if aname in stored:
197 if aname in stored:
198 print("Removing %stored alias",aname)
198 print("Removing %stored alias",aname)
199 del stored[aname]
199 del stored[aname]
200 self.shell.db['stored_aliases'] = stored
200 self.shell.db['stored_aliases'] = stored
201
201
202 @line_magic
202 @line_magic
203 def rehashx(self, parameter_s=''):
203 def rehashx(self, parameter_s=''):
204 """Update the alias table with all executable files in $PATH.
204 """Update the alias table with all executable files in $PATH.
205
205
206 rehashx explicitly checks that every entry in $PATH is a file
206 rehashx explicitly checks that every entry in $PATH is a file
207 with execute access (os.X_OK).
207 with execute access (os.X_OK).
208
208
209 Under Windows, it checks executability as a match against a
209 Under Windows, it checks executability as a match against a
210 '|'-separated string of extensions, stored in the IPython config
210 '|'-separated string of extensions, stored in the IPython config
211 variable win_exec_ext. This defaults to 'exe|com|bat'.
211 variable win_exec_ext. This defaults to 'exe|com|bat'.
212
212
213 This function also resets the root module cache of module completer,
213 This function also resets the root module cache of module completer,
214 used on slow filesystems.
214 used on slow filesystems.
215 """
215 """
216 from IPython.core.alias import InvalidAliasError
216 from IPython.core.alias import InvalidAliasError
217
217
218 # for the benefit of module completer in ipy_completers.py
218 # for the benefit of module completer in ipy_completers.py
219 del self.shell.db['rootmodules_cache']
219 del self.shell.db['rootmodules_cache']
220
220
221 path = [os.path.abspath(os.path.expanduser(p)) for p in
221 path = [os.path.abspath(os.path.expanduser(p)) for p in
222 os.environ.get('PATH','').split(os.pathsep)]
222 os.environ.get('PATH','').split(os.pathsep)]
223
223
224 syscmdlist = []
224 syscmdlist = []
225 savedir = os.getcwd()
225 savedir = os.getcwd()
226
226
227 # Now walk the paths looking for executables to alias.
227 # Now walk the paths looking for executables to alias.
228 try:
228 try:
229 # write the whole loop for posix/Windows so we don't have an if in
229 # write the whole loop for posix/Windows so we don't have an if in
230 # the innermost part
230 # the innermost part
231 if self.is_posix:
231 if self.is_posix:
232 for pdir in path:
232 for pdir in path:
233 try:
233 try:
234 os.chdir(pdir)
234 os.chdir(pdir)
235 except OSError:
235 except OSError:
236 continue
236 continue
237
237
238 # for python 3.6+ rewrite to: with os.scandir(pdir) as dirlist:
238 # for python 3.6+ rewrite to: with os.scandir(pdir) as dirlist:
239 dirlist = os.scandir(path=pdir)
239 dirlist = os.scandir(path=pdir)
240 for ff in dirlist:
240 for ff in dirlist:
241 if self.isexec(ff):
241 if self.isexec(ff):
242 fname = ff.name
242 fname = ff.name
243 try:
243 try:
244 # Removes dots from the name since ipython
244 # Removes dots from the name since ipython
245 # will assume names with dots to be python.
245 # will assume names with dots to be python.
246 if not self.shell.alias_manager.is_alias(fname):
246 if not self.shell.alias_manager.is_alias(fname):
247 self.shell.alias_manager.define_alias(
247 self.shell.alias_manager.define_alias(
248 fname.replace('.',''), fname)
248 fname.replace('.',''), fname)
249 except InvalidAliasError:
249 except InvalidAliasError:
250 pass
250 pass
251 else:
251 else:
252 syscmdlist.append(fname)
252 syscmdlist.append(fname)
253 else:
253 else:
254 no_alias = Alias.blacklist
254 no_alias = Alias.blacklist
255 for pdir in path:
255 for pdir in path:
256 try:
256 try:
257 os.chdir(pdir)
257 os.chdir(pdir)
258 except OSError:
258 except OSError:
259 continue
259 continue
260
260
261 # for python 3.6+ rewrite to: with os.scandir(pdir) as dirlist:
261 # for python 3.6+ rewrite to: with os.scandir(pdir) as dirlist:
262 dirlist = os.scandir(pdir)
262 dirlist = os.scandir(pdir)
263 for ff in dirlist:
263 for ff in dirlist:
264 fname = ff.name
264 fname = ff.name
265 base, ext = os.path.splitext(fname)
265 base, ext = os.path.splitext(fname)
266 if self.isexec(ff) and base.lower() not in no_alias:
266 if self.isexec(ff) and base.lower() not in no_alias:
267 if ext.lower() == '.exe':
267 if ext.lower() == '.exe':
268 fname = base
268 fname = base
269 try:
269 try:
270 # Removes dots from the name since ipython
270 # Removes dots from the name since ipython
271 # will assume names with dots to be python.
271 # will assume names with dots to be python.
272 self.shell.alias_manager.define_alias(
272 self.shell.alias_manager.define_alias(
273 base.lower().replace('.',''), fname)
273 base.lower().replace('.',''), fname)
274 except InvalidAliasError:
274 except InvalidAliasError:
275 pass
275 pass
276 syscmdlist.append(fname)
276 syscmdlist.append(fname)
277
277
278 self.shell.db['syscmdlist'] = syscmdlist
278 self.shell.db['syscmdlist'] = syscmdlist
279 finally:
279 finally:
280 os.chdir(savedir)
280 os.chdir(savedir)
281
281
282 @skip_doctest
282 @skip_doctest
283 @line_magic
283 @line_magic
284 def pwd(self, parameter_s=''):
284 def pwd(self, parameter_s=''):
285 """Return the current working directory path.
285 """Return the current working directory path.
286
286
287 Examples
287 Examples
288 --------
288 --------
289 ::
289 ::
290
290
291 In [9]: pwd
291 In [9]: pwd
292 Out[9]: '/home/tsuser/sprint/ipython'
292 Out[9]: '/home/tsuser/sprint/ipython'
293 """
293 """
294 try:
294 try:
295 return os.getcwd()
295 return os.getcwd()
296 except FileNotFoundError:
296 except FileNotFoundError as e:
297 raise UsageError("CWD no longer exists - please use %cd to change directory.")
297 raise UsageError("CWD no longer exists - please use %cd to change directory.") from e
298
298
299 @skip_doctest
299 @skip_doctest
300 @line_magic
300 @line_magic
301 def cd(self, parameter_s=''):
301 def cd(self, parameter_s=''):
302 """Change the current working directory.
302 """Change the current working directory.
303
303
304 This command automatically maintains an internal list of directories
304 This command automatically maintains an internal list of directories
305 you visit during your IPython session, in the variable _dh. The
305 you visit during your IPython session, in the variable _dh. The
306 command %dhist shows this history nicely formatted. You can also
306 command %dhist shows this history nicely formatted. You can also
307 do 'cd -<tab>' to see directory history conveniently.
307 do 'cd -<tab>' to see directory history conveniently.
308
308
309 Usage:
309 Usage:
310
310
311 cd 'dir': changes to directory 'dir'.
311 cd 'dir': changes to directory 'dir'.
312
312
313 cd -: changes to the last visited directory.
313 cd -: changes to the last visited directory.
314
314
315 cd -<n>: changes to the n-th directory in the directory history.
315 cd -<n>: changes to the n-th directory in the directory history.
316
316
317 cd --foo: change to directory that matches 'foo' in history
317 cd --foo: change to directory that matches 'foo' in history
318
318
319 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
319 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
320 (note: cd <bookmark_name> is enough if there is no
320 (note: cd <bookmark_name> is enough if there is no
321 directory <bookmark_name>, but a bookmark with the name exists.)
321 directory <bookmark_name>, but a bookmark with the name exists.)
322 'cd -b <tab>' allows you to tab-complete bookmark names.
322 'cd -b <tab>' allows you to tab-complete bookmark names.
323
323
324 Options:
324 Options:
325
325
326 -q: quiet. Do not print the working directory after the cd command is
326 -q: quiet. Do not print the working directory after the cd command is
327 executed. By default IPython's cd command does print this directory,
327 executed. By default IPython's cd command does print this directory,
328 since the default prompts do not display path information.
328 since the default prompts do not display path information.
329
329
330 Note that !cd doesn't work for this purpose because the shell where
330 Note that !cd doesn't work for this purpose because the shell where
331 !command runs is immediately discarded after executing 'command'.
331 !command runs is immediately discarded after executing 'command'.
332
332
333 Examples
333 Examples
334 --------
334 --------
335 ::
335 ::
336
336
337 In [10]: cd parent/child
337 In [10]: cd parent/child
338 /home/tsuser/parent/child
338 /home/tsuser/parent/child
339 """
339 """
340
340
341 try:
341 try:
342 oldcwd = os.getcwd()
342 oldcwd = os.getcwd()
343 except FileNotFoundError:
343 except FileNotFoundError:
344 # Happens if the CWD has been deleted.
344 # Happens if the CWD has been deleted.
345 oldcwd = None
345 oldcwd = None
346
346
347 numcd = re.match(r'(-)(\d+)$',parameter_s)
347 numcd = re.match(r'(-)(\d+)$',parameter_s)
348 # jump in directory history by number
348 # jump in directory history by number
349 if numcd:
349 if numcd:
350 nn = int(numcd.group(2))
350 nn = int(numcd.group(2))
351 try:
351 try:
352 ps = self.shell.user_ns['_dh'][nn]
352 ps = self.shell.user_ns['_dh'][nn]
353 except IndexError:
353 except IndexError:
354 print('The requested directory does not exist in history.')
354 print('The requested directory does not exist in history.')
355 return
355 return
356 else:
356 else:
357 opts = {}
357 opts = {}
358 elif parameter_s.startswith('--'):
358 elif parameter_s.startswith('--'):
359 ps = None
359 ps = None
360 fallback = None
360 fallback = None
361 pat = parameter_s[2:]
361 pat = parameter_s[2:]
362 dh = self.shell.user_ns['_dh']
362 dh = self.shell.user_ns['_dh']
363 # first search only by basename (last component)
363 # first search only by basename (last component)
364 for ent in reversed(dh):
364 for ent in reversed(dh):
365 if pat in os.path.basename(ent) and os.path.isdir(ent):
365 if pat in os.path.basename(ent) and os.path.isdir(ent):
366 ps = ent
366 ps = ent
367 break
367 break
368
368
369 if fallback is None and pat in ent and os.path.isdir(ent):
369 if fallback is None and pat in ent and os.path.isdir(ent):
370 fallback = ent
370 fallback = ent
371
371
372 # if we have no last part match, pick the first full path match
372 # if we have no last part match, pick the first full path match
373 if ps is None:
373 if ps is None:
374 ps = fallback
374 ps = fallback
375
375
376 if ps is None:
376 if ps is None:
377 print("No matching entry in directory history")
377 print("No matching entry in directory history")
378 return
378 return
379 else:
379 else:
380 opts = {}
380 opts = {}
381
381
382
382
383 else:
383 else:
384 opts, ps = self.parse_options(parameter_s, 'qb', mode='string')
384 opts, ps = self.parse_options(parameter_s, 'qb', mode='string')
385 # jump to previous
385 # jump to previous
386 if ps == '-':
386 if ps == '-':
387 try:
387 try:
388 ps = self.shell.user_ns['_dh'][-2]
388 ps = self.shell.user_ns['_dh'][-2]
389 except IndexError:
389 except IndexError as e:
390 raise UsageError('%cd -: No previous directory to change to.')
390 raise UsageError('%cd -: No previous directory to change to.') from e
391 # jump to bookmark if needed
391 # jump to bookmark if needed
392 else:
392 else:
393 if not os.path.isdir(ps) or 'b' in opts:
393 if not os.path.isdir(ps) or 'b' in opts:
394 bkms = self.shell.db.get('bookmarks', {})
394 bkms = self.shell.db.get('bookmarks', {})
395
395
396 if ps in bkms:
396 if ps in bkms:
397 target = bkms[ps]
397 target = bkms[ps]
398 print('(bookmark:%s) -> %s' % (ps, target))
398 print('(bookmark:%s) -> %s' % (ps, target))
399 ps = target
399 ps = target
400 else:
400 else:
401 if 'b' in opts:
401 if 'b' in opts:
402 raise UsageError("Bookmark '%s' not found. "
402 raise UsageError("Bookmark '%s' not found. "
403 "Use '%%bookmark -l' to see your bookmarks." % ps)
403 "Use '%%bookmark -l' to see your bookmarks." % ps)
404
404
405 # at this point ps should point to the target dir
405 # at this point ps should point to the target dir
406 if ps:
406 if ps:
407 try:
407 try:
408 os.chdir(os.path.expanduser(ps))
408 os.chdir(os.path.expanduser(ps))
409 if hasattr(self.shell, 'term_title') and self.shell.term_title:
409 if hasattr(self.shell, 'term_title') and self.shell.term_title:
410 set_term_title(self.shell.term_title_format.format(cwd=abbrev_cwd()))
410 set_term_title(self.shell.term_title_format.format(cwd=abbrev_cwd()))
411 except OSError:
411 except OSError:
412 print(sys.exc_info()[1])
412 print(sys.exc_info()[1])
413 else:
413 else:
414 cwd = os.getcwd()
414 cwd = os.getcwd()
415 dhist = self.shell.user_ns['_dh']
415 dhist = self.shell.user_ns['_dh']
416 if oldcwd != cwd:
416 if oldcwd != cwd:
417 dhist.append(cwd)
417 dhist.append(cwd)
418 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
418 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
419
419
420 else:
420 else:
421 os.chdir(self.shell.home_dir)
421 os.chdir(self.shell.home_dir)
422 if hasattr(self.shell, 'term_title') and self.shell.term_title:
422 if hasattr(self.shell, 'term_title') and self.shell.term_title:
423 set_term_title(self.shell.term_title_format.format(cwd="~"))
423 set_term_title(self.shell.term_title_format.format(cwd="~"))
424 cwd = os.getcwd()
424 cwd = os.getcwd()
425 dhist = self.shell.user_ns['_dh']
425 dhist = self.shell.user_ns['_dh']
426
426
427 if oldcwd != cwd:
427 if oldcwd != cwd:
428 dhist.append(cwd)
428 dhist.append(cwd)
429 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
429 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
430 if not 'q' in opts and not self.cd_force_quiet and self.shell.user_ns['_dh']:
430 if not 'q' in opts and not self.cd_force_quiet and self.shell.user_ns['_dh']:
431 print(self.shell.user_ns['_dh'][-1])
431 print(self.shell.user_ns['_dh'][-1])
432
432
433 @line_magic
433 @line_magic
434 def env(self, parameter_s=''):
434 def env(self, parameter_s=''):
435 """Get, set, or list environment variables.
435 """Get, set, or list environment variables.
436
436
437 Usage:\\
437 Usage:\\
438
438
439 %env: lists all environment variables/values
439 %env: lists all environment variables/values
440 %env var: get value for var
440 %env var: get value for var
441 %env var val: set value for var
441 %env var val: set value for var
442 %env var=val: set value for var
442 %env var=val: set value for var
443 %env var=$val: set value for var, using python expansion if possible
443 %env var=$val: set value for var, using python expansion if possible
444 """
444 """
445 if parameter_s.strip():
445 if parameter_s.strip():
446 split = '=' if '=' in parameter_s else ' '
446 split = '=' if '=' in parameter_s else ' '
447 bits = parameter_s.split(split)
447 bits = parameter_s.split(split)
448 if len(bits) == 1:
448 if len(bits) == 1:
449 key = parameter_s.strip()
449 key = parameter_s.strip()
450 if key in os.environ:
450 if key in os.environ:
451 return os.environ[key]
451 return os.environ[key]
452 else:
452 else:
453 err = "Environment does not have key: {0}".format(key)
453 err = "Environment does not have key: {0}".format(key)
454 raise UsageError(err)
454 raise UsageError(err)
455 if len(bits) > 1:
455 if len(bits) > 1:
456 return self.set_env(parameter_s)
456 return self.set_env(parameter_s)
457 env = dict(os.environ)
457 env = dict(os.environ)
458 # hide likely secrets when printing the whole environment
458 # hide likely secrets when printing the whole environment
459 for key in list(env):
459 for key in list(env):
460 if any(s in key.lower() for s in ('key', 'token', 'secret')):
460 if any(s in key.lower() for s in ('key', 'token', 'secret')):
461 env[key] = '<hidden>'
461 env[key] = '<hidden>'
462
462
463 return env
463 return env
464
464
465 @line_magic
465 @line_magic
466 def set_env(self, parameter_s):
466 def set_env(self, parameter_s):
467 """Set environment variables. Assumptions are that either "val" is a
467 """Set environment variables. Assumptions are that either "val" is a
468 name in the user namespace, or val is something that evaluates to a
468 name in the user namespace, or val is something that evaluates to a
469 string.
469 string.
470
470
471 Usage:\\
471 Usage:\\
472 %set_env var val: set value for var
472 %set_env var val: set value for var
473 %set_env var=val: set value for var
473 %set_env var=val: set value for var
474 %set_env var=$val: set value for var, using python expansion if possible
474 %set_env var=$val: set value for var, using python expansion if possible
475 """
475 """
476 split = '=' if '=' in parameter_s else ' '
476 split = '=' if '=' in parameter_s else ' '
477 bits = parameter_s.split(split, 1)
477 bits = parameter_s.split(split, 1)
478 if not parameter_s.strip() or len(bits)<2:
478 if not parameter_s.strip() or len(bits)<2:
479 raise UsageError("usage is 'set_env var=val'")
479 raise UsageError("usage is 'set_env var=val'")
480 var = bits[0].strip()
480 var = bits[0].strip()
481 val = bits[1].strip()
481 val = bits[1].strip()
482 if re.match(r'.*\s.*', var):
482 if re.match(r'.*\s.*', var):
483 # an environment variable with whitespace is almost certainly
483 # an environment variable with whitespace is almost certainly
484 # not what the user intended. what's more likely is the wrong
484 # not what the user intended. what's more likely is the wrong
485 # split was chosen, ie for "set_env cmd_args A=B", we chose
485 # split was chosen, ie for "set_env cmd_args A=B", we chose
486 # '=' for the split and should have chosen ' '. to get around
486 # '=' for the split and should have chosen ' '. to get around
487 # this, users should just assign directly to os.environ or use
487 # this, users should just assign directly to os.environ or use
488 # standard magic {var} expansion.
488 # standard magic {var} expansion.
489 err = "refusing to set env var with whitespace: '{0}'"
489 err = "refusing to set env var with whitespace: '{0}'"
490 err = err.format(val)
490 err = err.format(val)
491 raise UsageError(err)
491 raise UsageError(err)
492 os.environ[var] = val
492 os.environ[var] = val
493 print('env: {0}={1}'.format(var,val))
493 print('env: {0}={1}'.format(var,val))
494
494
495 @line_magic
495 @line_magic
496 def pushd(self, parameter_s=''):
496 def pushd(self, parameter_s=''):
497 """Place the current dir on stack and change directory.
497 """Place the current dir on stack and change directory.
498
498
499 Usage:\\
499 Usage:\\
500 %pushd ['dirname']
500 %pushd ['dirname']
501 """
501 """
502
502
503 dir_s = self.shell.dir_stack
503 dir_s = self.shell.dir_stack
504 tgt = os.path.expanduser(parameter_s)
504 tgt = os.path.expanduser(parameter_s)
505 cwd = os.getcwd().replace(self.shell.home_dir,'~')
505 cwd = os.getcwd().replace(self.shell.home_dir,'~')
506 if tgt:
506 if tgt:
507 self.cd(parameter_s)
507 self.cd(parameter_s)
508 dir_s.insert(0,cwd)
508 dir_s.insert(0,cwd)
509 return self.shell.run_line_magic('dirs', '')
509 return self.shell.run_line_magic('dirs', '')
510
510
511 @line_magic
511 @line_magic
512 def popd(self, parameter_s=''):
512 def popd(self, parameter_s=''):
513 """Change to directory popped off the top of the stack.
513 """Change to directory popped off the top of the stack.
514 """
514 """
515 if not self.shell.dir_stack:
515 if not self.shell.dir_stack:
516 raise UsageError("%popd on empty stack")
516 raise UsageError("%popd on empty stack")
517 top = self.shell.dir_stack.pop(0)
517 top = self.shell.dir_stack.pop(0)
518 self.cd(top)
518 self.cd(top)
519 print("popd ->",top)
519 print("popd ->",top)
520
520
521 @line_magic
521 @line_magic
522 def dirs(self, parameter_s=''):
522 def dirs(self, parameter_s=''):
523 """Return the current directory stack."""
523 """Return the current directory stack."""
524
524
525 return self.shell.dir_stack
525 return self.shell.dir_stack
526
526
527 @line_magic
527 @line_magic
528 def dhist(self, parameter_s=''):
528 def dhist(self, parameter_s=''):
529 """Print your history of visited directories.
529 """Print your history of visited directories.
530
530
531 %dhist -> print full history\\
531 %dhist -> print full history\\
532 %dhist n -> print last n entries only\\
532 %dhist n -> print last n entries only\\
533 %dhist n1 n2 -> print entries between n1 and n2 (n2 not included)\\
533 %dhist n1 n2 -> print entries between n1 and n2 (n2 not included)\\
534
534
535 This history is automatically maintained by the %cd command, and
535 This history is automatically maintained by the %cd command, and
536 always available as the global list variable _dh. You can use %cd -<n>
536 always available as the global list variable _dh. You can use %cd -<n>
537 to go to directory number <n>.
537 to go to directory number <n>.
538
538
539 Note that most of time, you should view directory history by entering
539 Note that most of time, you should view directory history by entering
540 cd -<TAB>.
540 cd -<TAB>.
541
541
542 """
542 """
543
543
544 dh = self.shell.user_ns['_dh']
544 dh = self.shell.user_ns['_dh']
545 if parameter_s:
545 if parameter_s:
546 try:
546 try:
547 args = map(int,parameter_s.split())
547 args = map(int,parameter_s.split())
548 except:
548 except:
549 self.arg_err(self.dhist)
549 self.arg_err(self.dhist)
550 return
550 return
551 if len(args) == 1:
551 if len(args) == 1:
552 ini,fin = max(len(dh)-(args[0]),0),len(dh)
552 ini,fin = max(len(dh)-(args[0]),0),len(dh)
553 elif len(args) == 2:
553 elif len(args) == 2:
554 ini,fin = args
554 ini,fin = args
555 fin = min(fin, len(dh))
555 fin = min(fin, len(dh))
556 else:
556 else:
557 self.arg_err(self.dhist)
557 self.arg_err(self.dhist)
558 return
558 return
559 else:
559 else:
560 ini,fin = 0,len(dh)
560 ini,fin = 0,len(dh)
561 print('Directory history (kept in _dh)')
561 print('Directory history (kept in _dh)')
562 for i in range(ini, fin):
562 for i in range(ini, fin):
563 print("%d: %s" % (i, dh[i]))
563 print("%d: %s" % (i, dh[i]))
564
564
565 @skip_doctest
565 @skip_doctest
566 @line_magic
566 @line_magic
567 def sc(self, parameter_s=''):
567 def sc(self, parameter_s=''):
568 """Shell capture - run shell command and capture output (DEPRECATED use !).
568 """Shell capture - run shell command and capture output (DEPRECATED use !).
569
569
570 DEPRECATED. Suboptimal, retained for backwards compatibility.
570 DEPRECATED. Suboptimal, retained for backwards compatibility.
571
571
572 You should use the form 'var = !command' instead. Example:
572 You should use the form 'var = !command' instead. Example:
573
573
574 "%sc -l myfiles = ls ~" should now be written as
574 "%sc -l myfiles = ls ~" should now be written as
575
575
576 "myfiles = !ls ~"
576 "myfiles = !ls ~"
577
577
578 myfiles.s, myfiles.l and myfiles.n still apply as documented
578 myfiles.s, myfiles.l and myfiles.n still apply as documented
579 below.
579 below.
580
580
581 --
581 --
582 %sc [options] varname=command
582 %sc [options] varname=command
583
583
584 IPython will run the given command using commands.getoutput(), and
584 IPython will run the given command using commands.getoutput(), and
585 will then update the user's interactive namespace with a variable
585 will then update the user's interactive namespace with a variable
586 called varname, containing the value of the call. Your command can
586 called varname, containing the value of the call. Your command can
587 contain shell wildcards, pipes, etc.
587 contain shell wildcards, pipes, etc.
588
588
589 The '=' sign in the syntax is mandatory, and the variable name you
589 The '=' sign in the syntax is mandatory, and the variable name you
590 supply must follow Python's standard conventions for valid names.
590 supply must follow Python's standard conventions for valid names.
591
591
592 (A special format without variable name exists for internal use)
592 (A special format without variable name exists for internal use)
593
593
594 Options:
594 Options:
595
595
596 -l: list output. Split the output on newlines into a list before
596 -l: list output. Split the output on newlines into a list before
597 assigning it to the given variable. By default the output is stored
597 assigning it to the given variable. By default the output is stored
598 as a single string.
598 as a single string.
599
599
600 -v: verbose. Print the contents of the variable.
600 -v: verbose. Print the contents of the variable.
601
601
602 In most cases you should not need to split as a list, because the
602 In most cases you should not need to split as a list, because the
603 returned value is a special type of string which can automatically
603 returned value is a special type of string which can automatically
604 provide its contents either as a list (split on newlines) or as a
604 provide its contents either as a list (split on newlines) or as a
605 space-separated string. These are convenient, respectively, either
605 space-separated string. These are convenient, respectively, either
606 for sequential processing or to be passed to a shell command.
606 for sequential processing or to be passed to a shell command.
607
607
608 For example::
608 For example::
609
609
610 # Capture into variable a
610 # Capture into variable a
611 In [1]: sc a=ls *py
611 In [1]: sc a=ls *py
612
612
613 # a is a string with embedded newlines
613 # a is a string with embedded newlines
614 In [2]: a
614 In [2]: a
615 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
615 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
616
616
617 # which can be seen as a list:
617 # which can be seen as a list:
618 In [3]: a.l
618 In [3]: a.l
619 Out[3]: ['setup.py', 'win32_manual_post_install.py']
619 Out[3]: ['setup.py', 'win32_manual_post_install.py']
620
620
621 # or as a whitespace-separated string:
621 # or as a whitespace-separated string:
622 In [4]: a.s
622 In [4]: a.s
623 Out[4]: 'setup.py win32_manual_post_install.py'
623 Out[4]: 'setup.py win32_manual_post_install.py'
624
624
625 # a.s is useful to pass as a single command line:
625 # a.s is useful to pass as a single command line:
626 In [5]: !wc -l $a.s
626 In [5]: !wc -l $a.s
627 146 setup.py
627 146 setup.py
628 130 win32_manual_post_install.py
628 130 win32_manual_post_install.py
629 276 total
629 276 total
630
630
631 # while the list form is useful to loop over:
631 # while the list form is useful to loop over:
632 In [6]: for f in a.l:
632 In [6]: for f in a.l:
633 ...: !wc -l $f
633 ...: !wc -l $f
634 ...:
634 ...:
635 146 setup.py
635 146 setup.py
636 130 win32_manual_post_install.py
636 130 win32_manual_post_install.py
637
637
638 Similarly, the lists returned by the -l option are also special, in
638 Similarly, the lists returned by the -l option are also special, in
639 the sense that you can equally invoke the .s attribute on them to
639 the sense that you can equally invoke the .s attribute on them to
640 automatically get a whitespace-separated string from their contents::
640 automatically get a whitespace-separated string from their contents::
641
641
642 In [7]: sc -l b=ls *py
642 In [7]: sc -l b=ls *py
643
643
644 In [8]: b
644 In [8]: b
645 Out[8]: ['setup.py', 'win32_manual_post_install.py']
645 Out[8]: ['setup.py', 'win32_manual_post_install.py']
646
646
647 In [9]: b.s
647 In [9]: b.s
648 Out[9]: 'setup.py win32_manual_post_install.py'
648 Out[9]: 'setup.py win32_manual_post_install.py'
649
649
650 In summary, both the lists and strings used for output capture have
650 In summary, both the lists and strings used for output capture have
651 the following special attributes::
651 the following special attributes::
652
652
653 .l (or .list) : value as list.
653 .l (or .list) : value as list.
654 .n (or .nlstr): value as newline-separated string.
654 .n (or .nlstr): value as newline-separated string.
655 .s (or .spstr): value as space-separated string.
655 .s (or .spstr): value as space-separated string.
656 """
656 """
657
657
658 opts,args = self.parse_options(parameter_s, 'lv')
658 opts,args = self.parse_options(parameter_s, 'lv')
659 # Try to get a variable name and command to run
659 # Try to get a variable name and command to run
660 try:
660 try:
661 # the variable name must be obtained from the parse_options
661 # the variable name must be obtained from the parse_options
662 # output, which uses shlex.split to strip options out.
662 # output, which uses shlex.split to strip options out.
663 var,_ = args.split('=', 1)
663 var,_ = args.split('=', 1)
664 var = var.strip()
664 var = var.strip()
665 # But the command has to be extracted from the original input
665 # But the command has to be extracted from the original input
666 # parameter_s, not on what parse_options returns, to avoid the
666 # parameter_s, not on what parse_options returns, to avoid the
667 # quote stripping which shlex.split performs on it.
667 # quote stripping which shlex.split performs on it.
668 _,cmd = parameter_s.split('=', 1)
668 _,cmd = parameter_s.split('=', 1)
669 except ValueError:
669 except ValueError:
670 var,cmd = '',''
670 var,cmd = '',''
671 # If all looks ok, proceed
671 # If all looks ok, proceed
672 split = 'l' in opts
672 split = 'l' in opts
673 out = self.shell.getoutput(cmd, split=split)
673 out = self.shell.getoutput(cmd, split=split)
674 if 'v' in opts:
674 if 'v' in opts:
675 print('%s ==\n%s' % (var, pformat(out)))
675 print('%s ==\n%s' % (var, pformat(out)))
676 if var:
676 if var:
677 self.shell.user_ns.update({var:out})
677 self.shell.user_ns.update({var:out})
678 else:
678 else:
679 return out
679 return out
680
680
681 @line_cell_magic
681 @line_cell_magic
682 def sx(self, line='', cell=None):
682 def sx(self, line='', cell=None):
683 """Shell execute - run shell command and capture output (!! is short-hand).
683 """Shell execute - run shell command and capture output (!! is short-hand).
684
684
685 %sx command
685 %sx command
686
686
687 IPython will run the given command using commands.getoutput(), and
687 IPython will run the given command using commands.getoutput(), and
688 return the result formatted as a list (split on '\\n'). Since the
688 return the result formatted as a list (split on '\\n'). Since the
689 output is _returned_, it will be stored in ipython's regular output
689 output is _returned_, it will be stored in ipython's regular output
690 cache Out[N] and in the '_N' automatic variables.
690 cache Out[N] and in the '_N' automatic variables.
691
691
692 Notes:
692 Notes:
693
693
694 1) If an input line begins with '!!', then %sx is automatically
694 1) If an input line begins with '!!', then %sx is automatically
695 invoked. That is, while::
695 invoked. That is, while::
696
696
697 !ls
697 !ls
698
698
699 causes ipython to simply issue system('ls'), typing::
699 causes ipython to simply issue system('ls'), typing::
700
700
701 !!ls
701 !!ls
702
702
703 is a shorthand equivalent to::
703 is a shorthand equivalent to::
704
704
705 %sx ls
705 %sx ls
706
706
707 2) %sx differs from %sc in that %sx automatically splits into a list,
707 2) %sx differs from %sc in that %sx automatically splits into a list,
708 like '%sc -l'. The reason for this is to make it as easy as possible
708 like '%sc -l'. The reason for this is to make it as easy as possible
709 to process line-oriented shell output via further python commands.
709 to process line-oriented shell output via further python commands.
710 %sc is meant to provide much finer control, but requires more
710 %sc is meant to provide much finer control, but requires more
711 typing.
711 typing.
712
712
713 3) Just like %sc -l, this is a list with special attributes:
713 3) Just like %sc -l, this is a list with special attributes:
714 ::
714 ::
715
715
716 .l (or .list) : value as list.
716 .l (or .list) : value as list.
717 .n (or .nlstr): value as newline-separated string.
717 .n (or .nlstr): value as newline-separated string.
718 .s (or .spstr): value as whitespace-separated string.
718 .s (or .spstr): value as whitespace-separated string.
719
719
720 This is very useful when trying to use such lists as arguments to
720 This is very useful when trying to use such lists as arguments to
721 system commands."""
721 system commands."""
722
722
723 if cell is None:
723 if cell is None:
724 # line magic
724 # line magic
725 return self.shell.getoutput(line)
725 return self.shell.getoutput(line)
726 else:
726 else:
727 opts,args = self.parse_options(line, '', 'out=')
727 opts,args = self.parse_options(line, '', 'out=')
728 output = self.shell.getoutput(cell)
728 output = self.shell.getoutput(cell)
729 out_name = opts.get('out', opts.get('o'))
729 out_name = opts.get('out', opts.get('o'))
730 if out_name:
730 if out_name:
731 self.shell.user_ns[out_name] = output
731 self.shell.user_ns[out_name] = output
732 else:
732 else:
733 return output
733 return output
734
734
735 system = line_cell_magic('system')(sx)
735 system = line_cell_magic('system')(sx)
736 bang = cell_magic('!')(sx)
736 bang = cell_magic('!')(sx)
737
737
738 @line_magic
738 @line_magic
739 def bookmark(self, parameter_s=''):
739 def bookmark(self, parameter_s=''):
740 """Manage IPython's bookmark system.
740 """Manage IPython's bookmark system.
741
741
742 %bookmark <name> - set bookmark to current dir
742 %bookmark <name> - set bookmark to current dir
743 %bookmark <name> <dir> - set bookmark to <dir>
743 %bookmark <name> <dir> - set bookmark to <dir>
744 %bookmark -l - list all bookmarks
744 %bookmark -l - list all bookmarks
745 %bookmark -d <name> - remove bookmark
745 %bookmark -d <name> - remove bookmark
746 %bookmark -r - remove all bookmarks
746 %bookmark -r - remove all bookmarks
747
747
748 You can later on access a bookmarked folder with::
748 You can later on access a bookmarked folder with::
749
749
750 %cd -b <name>
750 %cd -b <name>
751
751
752 or simply '%cd <name>' if there is no directory called <name> AND
752 or simply '%cd <name>' if there is no directory called <name> AND
753 there is such a bookmark defined.
753 there is such a bookmark defined.
754
754
755 Your bookmarks persist through IPython sessions, but they are
755 Your bookmarks persist through IPython sessions, but they are
756 associated with each profile."""
756 associated with each profile."""
757
757
758 opts,args = self.parse_options(parameter_s,'drl',mode='list')
758 opts,args = self.parse_options(parameter_s,'drl',mode='list')
759 if len(args) > 2:
759 if len(args) > 2:
760 raise UsageError("%bookmark: too many arguments")
760 raise UsageError("%bookmark: too many arguments")
761
761
762 bkms = self.shell.db.get('bookmarks',{})
762 bkms = self.shell.db.get('bookmarks',{})
763
763
764 if 'd' in opts:
764 if 'd' in opts:
765 try:
765 try:
766 todel = args[0]
766 todel = args[0]
767 except IndexError:
767 except IndexError as e:
768 raise UsageError(
768 raise UsageError(
769 "%bookmark -d: must provide a bookmark to delete")
769 "%bookmark -d: must provide a bookmark to delete") from e
770 else:
770 else:
771 try:
771 try:
772 del bkms[todel]
772 del bkms[todel]
773 except KeyError:
773 except KeyError as e:
774 raise UsageError(
774 raise UsageError(
775 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
775 "%%bookmark -d: Can't delete bookmark '%s'" % todel) from e
776
776
777 elif 'r' in opts:
777 elif 'r' in opts:
778 bkms = {}
778 bkms = {}
779 elif 'l' in opts:
779 elif 'l' in opts:
780 bks = sorted(bkms)
780 bks = sorted(bkms)
781 if bks:
781 if bks:
782 size = max(map(len, bks))
782 size = max(map(len, bks))
783 else:
783 else:
784 size = 0
784 size = 0
785 fmt = '%-'+str(size)+'s -> %s'
785 fmt = '%-'+str(size)+'s -> %s'
786 print('Current bookmarks:')
786 print('Current bookmarks:')
787 for bk in bks:
787 for bk in bks:
788 print(fmt % (bk, bkms[bk]))
788 print(fmt % (bk, bkms[bk]))
789 else:
789 else:
790 if not args:
790 if not args:
791 raise UsageError("%bookmark: You must specify the bookmark name")
791 raise UsageError("%bookmark: You must specify the bookmark name")
792 elif len(args)==1:
792 elif len(args)==1:
793 bkms[args[0]] = os.getcwd()
793 bkms[args[0]] = os.getcwd()
794 elif len(args)==2:
794 elif len(args)==2:
795 bkms[args[0]] = args[1]
795 bkms[args[0]] = args[1]
796 self.shell.db['bookmarks'] = bkms
796 self.shell.db['bookmarks'] = bkms
797
797
798 @line_magic
798 @line_magic
799 def pycat(self, parameter_s=''):
799 def pycat(self, parameter_s=''):
800 """Show a syntax-highlighted file through a pager.
800 """Show a syntax-highlighted file through a pager.
801
801
802 This magic is similar to the cat utility, but it will assume the file
802 This magic is similar to the cat utility, but it will assume the file
803 to be Python source and will show it with syntax highlighting.
803 to be Python source and will show it with syntax highlighting.
804
804
805 This magic command can either take a local filename, an url,
805 This magic command can either take a local filename, an url,
806 an history range (see %history) or a macro as argument ::
806 an history range (see %history) or a macro as argument ::
807
807
808 %pycat myscript.py
808 %pycat myscript.py
809 %pycat 7-27
809 %pycat 7-27
810 %pycat myMacro
810 %pycat myMacro
811 %pycat http://www.example.com/myscript.py
811 %pycat http://www.example.com/myscript.py
812 """
812 """
813 if not parameter_s:
813 if not parameter_s:
814 raise UsageError('Missing filename, URL, input history range, '
814 raise UsageError('Missing filename, URL, input history range, '
815 'or macro.')
815 'or macro.')
816
816
817 try :
817 try :
818 cont = self.shell.find_user_code(parameter_s, skip_encoding_cookie=False)
818 cont = self.shell.find_user_code(parameter_s, skip_encoding_cookie=False)
819 except (ValueError, IOError):
819 except (ValueError, IOError):
820 print("Error: no such file, variable, URL, history range or macro")
820 print("Error: no such file, variable, URL, history range or macro")
821 return
821 return
822
822
823 page.page(self.shell.pycolorize(source_to_unicode(cont)))
823 page.page(self.shell.pycolorize(source_to_unicode(cont)))
824
824
825 @magic_arguments.magic_arguments()
825 @magic_arguments.magic_arguments()
826 @magic_arguments.argument(
826 @magic_arguments.argument(
827 '-a', '--append', action='store_true', default=False,
827 '-a', '--append', action='store_true', default=False,
828 help='Append contents of the cell to an existing file. '
828 help='Append contents of the cell to an existing file. '
829 'The file will be created if it does not exist.'
829 'The file will be created if it does not exist.'
830 )
830 )
831 @magic_arguments.argument(
831 @magic_arguments.argument(
832 'filename', type=str,
832 'filename', type=str,
833 help='file to write'
833 help='file to write'
834 )
834 )
835 @cell_magic
835 @cell_magic
836 def writefile(self, line, cell):
836 def writefile(self, line, cell):
837 """Write the contents of the cell to a file.
837 """Write the contents of the cell to a file.
838
838
839 The file will be overwritten unless the -a (--append) flag is specified.
839 The file will be overwritten unless the -a (--append) flag is specified.
840 """
840 """
841 args = magic_arguments.parse_argstring(self.writefile, line)
841 args = magic_arguments.parse_argstring(self.writefile, line)
842 if re.match(r'^(\'.*\')|(".*")$', args.filename):
842 if re.match(r'^(\'.*\')|(".*")$', args.filename):
843 filename = os.path.expanduser(args.filename[1:-1])
843 filename = os.path.expanduser(args.filename[1:-1])
844 else:
844 else:
845 filename = os.path.expanduser(args.filename)
845 filename = os.path.expanduser(args.filename)
846
846
847 if os.path.exists(filename):
847 if os.path.exists(filename):
848 if args.append:
848 if args.append:
849 print("Appending to %s" % filename)
849 print("Appending to %s" % filename)
850 else:
850 else:
851 print("Overwriting %s" % filename)
851 print("Overwriting %s" % filename)
852 else:
852 else:
853 print("Writing %s" % filename)
853 print("Writing %s" % filename)
854
854
855 mode = 'a' if args.append else 'w'
855 mode = 'a' if args.append else 'w'
856 with io.open(filename, mode, encoding='utf-8') as f:
856 with io.open(filename, mode, encoding='utf-8') as f:
857 f.write(cell)
857 f.write(cell)
General Comments 0
You need to be logged in to leave comments. Login now