##// END OF EJS Templates
Implementing decorator
nfgf -
Show More
@@ -1,325 +1,331 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Displayhook for IPython.
2 """Displayhook for IPython.
3
3
4 This defines a callable class that IPython uses for `sys.displayhook`.
4 This defines a callable class that IPython uses for `sys.displayhook`.
5 """
5 """
6
6
7 # Copyright (c) IPython Development Team.
7 # Copyright (c) IPython Development Team.
8 # Distributed under the terms of the Modified BSD License.
8 # Distributed under the terms of the Modified BSD License.
9
9
10 import builtins as builtin_mod
10 import builtins as builtin_mod
11 import sys
11 import sys
12 import io as _io
12 import io as _io
13 import tokenize
13 import tokenize
14
14
15 from traitlets.config.configurable import Configurable
15 from traitlets.config.configurable import Configurable
16 from traitlets import Instance, Float
16 from traitlets import Instance, Float
17 from warnings import warn
17 from warnings import warn
18
18
19 # TODO: Move the various attributes (cache_size, [others now moved]). Some
19 # TODO: Move the various attributes (cache_size, [others now moved]). Some
20 # of these are also attributes of InteractiveShell. They should be on ONE object
20 # of these are also attributes of InteractiveShell. They should be on ONE object
21 # only and the other objects should ask that one object for their values.
21 # only and the other objects should ask that one object for their values.
22
22
23 class DisplayHook(Configurable):
23 class DisplayHook(Configurable):
24 """The custom IPython displayhook to replace sys.displayhook.
24 """The custom IPython displayhook to replace sys.displayhook.
25
25
26 This class does many things, but the basic idea is that it is a callable
26 This class does many things, but the basic idea is that it is a callable
27 that gets called anytime user code returns a value.
27 that gets called anytime user code returns a value.
28 """
28 """
29
29
30 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC',
30 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC',
31 allow_none=True)
31 allow_none=True)
32 exec_result = Instance('IPython.core.interactiveshell.ExecutionResult',
32 exec_result = Instance('IPython.core.interactiveshell.ExecutionResult',
33 allow_none=True)
33 allow_none=True)
34 cull_fraction = Float(0.2)
34 cull_fraction = Float(0.2)
35
35
36 def __init__(self, shell=None, cache_size=1000, **kwargs):
36 def __init__(self, shell=None, cache_size=1000, **kwargs):
37 super(DisplayHook, self).__init__(shell=shell, **kwargs)
37 super(DisplayHook, self).__init__(shell=shell, **kwargs)
38 cache_size_min = 3
38 cache_size_min = 3
39 if cache_size <= 0:
39 if cache_size <= 0:
40 self.do_full_cache = 0
40 self.do_full_cache = 0
41 cache_size = 0
41 cache_size = 0
42 elif cache_size < cache_size_min:
42 elif cache_size < cache_size_min:
43 self.do_full_cache = 0
43 self.do_full_cache = 0
44 cache_size = 0
44 cache_size = 0
45 warn('caching was disabled (min value for cache size is %s).' %
45 warn('caching was disabled (min value for cache size is %s).' %
46 cache_size_min,stacklevel=3)
46 cache_size_min,stacklevel=3)
47 else:
47 else:
48 self.do_full_cache = 1
48 self.do_full_cache = 1
49
49
50 self.cache_size = cache_size
50 self.cache_size = cache_size
51
51
52 # we need a reference to the user-level namespace
52 # we need a reference to the user-level namespace
53 self.shell = shell
53 self.shell = shell
54
54
55 self._,self.__,self.___ = '','',''
55 self._,self.__,self.___ = '','',''
56
56
57 # these are deliberately global:
57 # these are deliberately global:
58 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
58 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
59 self.shell.user_ns.update(to_user_ns)
59 self.shell.user_ns.update(to_user_ns)
60
60
61 @property
61 @property
62 def prompt_count(self):
62 def prompt_count(self):
63 return self.shell.execution_count
63 return self.shell.execution_count
64
64
65 #-------------------------------------------------------------------------
65 #-------------------------------------------------------------------------
66 # Methods used in __call__. Override these methods to modify the behavior
66 # Methods used in __call__. Override these methods to modify the behavior
67 # of the displayhook.
67 # of the displayhook.
68 #-------------------------------------------------------------------------
68 #-------------------------------------------------------------------------
69
69
70 def check_for_underscore(self):
70 def check_for_underscore(self):
71 """Check if the user has set the '_' variable by hand."""
71 """Check if the user has set the '_' variable by hand."""
72 # If something injected a '_' variable in __builtin__, delete
72 # If something injected a '_' variable in __builtin__, delete
73 # ipython's automatic one so we don't clobber that. gettext() in
73 # ipython's automatic one so we don't clobber that. gettext() in
74 # particular uses _, so we need to stay away from it.
74 # particular uses _, so we need to stay away from it.
75 if '_' in builtin_mod.__dict__:
75 if '_' in builtin_mod.__dict__:
76 try:
76 try:
77 user_value = self.shell.user_ns['_']
77 user_value = self.shell.user_ns['_']
78 if user_value is not self._:
78 if user_value is not self._:
79 return
79 return
80 del self.shell.user_ns['_']
80 del self.shell.user_ns['_']
81 except KeyError:
81 except KeyError:
82 pass
82 pass
83
83
84 def quiet(self):
84 def quiet(self):
85 """Should we silence the display hook because of ';'?"""
85 """Should we silence the display hook because of ';'?"""
86 # do not print output if input ends in ';'
86 # do not print output if input ends in ';'
87
87
88 try:
88 try:
89 cell = self.shell.history_manager.input_hist_parsed[-1]
89 cell = self.shell.history_manager.input_hist_parsed[-1]
90 except IndexError:
90 except IndexError:
91 # some uses of ipshellembed may fail here
91 # some uses of ipshellembed may fail here
92 return False
92 return False
93
93
94 sio = _io.StringIO(cell)
94 return self.semicolon_at_end_of_expression(cell)
95
96 @staticmethod
97 def semicolon_at_end_of_expression(expression):
98 """Parse Python expression and detects whether last token is ';'"""
99
100 sio = _io.StringIO(expression)
95 tokens = list(tokenize.generate_tokens(sio.readline))
101 tokens = list(tokenize.generate_tokens(sio.readline))
96
102
97 for token in reversed(tokens):
103 for token in reversed(tokens):
98 if token[0] in (tokenize.ENDMARKER, tokenize.NL, tokenize.NEWLINE, tokenize.COMMENT):
104 if token[0] in (tokenize.ENDMARKER, tokenize.NL, tokenize.NEWLINE, tokenize.COMMENT):
99 continue
105 continue
100 if (token[0] == tokenize.OP) and (token[1] == ';'):
106 if (token[0] == tokenize.OP) and (token[1] == ';'):
101 return True
107 return True
102 else:
108 else:
103 return False
109 return False
104
110
105 def start_displayhook(self):
111 def start_displayhook(self):
106 """Start the displayhook, initializing resources."""
112 """Start the displayhook, initializing resources."""
107 pass
113 pass
108
114
109 def write_output_prompt(self):
115 def write_output_prompt(self):
110 """Write the output prompt.
116 """Write the output prompt.
111
117
112 The default implementation simply writes the prompt to
118 The default implementation simply writes the prompt to
113 ``sys.stdout``.
119 ``sys.stdout``.
114 """
120 """
115 # Use write, not print which adds an extra space.
121 # Use write, not print which adds an extra space.
116 sys.stdout.write(self.shell.separate_out)
122 sys.stdout.write(self.shell.separate_out)
117 outprompt = 'Out[{}]: '.format(self.shell.execution_count)
123 outprompt = 'Out[{}]: '.format(self.shell.execution_count)
118 if self.do_full_cache:
124 if self.do_full_cache:
119 sys.stdout.write(outprompt)
125 sys.stdout.write(outprompt)
120
126
121 def compute_format_data(self, result):
127 def compute_format_data(self, result):
122 """Compute format data of the object to be displayed.
128 """Compute format data of the object to be displayed.
123
129
124 The format data is a generalization of the :func:`repr` of an object.
130 The format data is a generalization of the :func:`repr` of an object.
125 In the default implementation the format data is a :class:`dict` of
131 In the default implementation the format data is a :class:`dict` of
126 key value pair where the keys are valid MIME types and the values
132 key value pair where the keys are valid MIME types and the values
127 are JSON'able data structure containing the raw data for that MIME
133 are JSON'able data structure containing the raw data for that MIME
128 type. It is up to frontends to determine pick a MIME to to use and
134 type. It is up to frontends to determine pick a MIME to to use and
129 display that data in an appropriate manner.
135 display that data in an appropriate manner.
130
136
131 This method only computes the format data for the object and should
137 This method only computes the format data for the object and should
132 NOT actually print or write that to a stream.
138 NOT actually print or write that to a stream.
133
139
134 Parameters
140 Parameters
135 ----------
141 ----------
136 result : object
142 result : object
137 The Python object passed to the display hook, whose format will be
143 The Python object passed to the display hook, whose format will be
138 computed.
144 computed.
139
145
140 Returns
146 Returns
141 -------
147 -------
142 (format_dict, md_dict) : dict
148 (format_dict, md_dict) : dict
143 format_dict is a :class:`dict` whose keys are valid MIME types and values are
149 format_dict is a :class:`dict` whose keys are valid MIME types and values are
144 JSON'able raw data for that MIME type. It is recommended that
150 JSON'able raw data for that MIME type. It is recommended that
145 all return values of this should always include the "text/plain"
151 all return values of this should always include the "text/plain"
146 MIME type representation of the object.
152 MIME type representation of the object.
147 md_dict is a :class:`dict` with the same MIME type keys
153 md_dict is a :class:`dict` with the same MIME type keys
148 of metadata associated with each output.
154 of metadata associated with each output.
149
155
150 """
156 """
151 return self.shell.display_formatter.format(result)
157 return self.shell.display_formatter.format(result)
152
158
153 # This can be set to True by the write_output_prompt method in a subclass
159 # This can be set to True by the write_output_prompt method in a subclass
154 prompt_end_newline = False
160 prompt_end_newline = False
155
161
156 def write_format_data(self, format_dict, md_dict=None) -> None:
162 def write_format_data(self, format_dict, md_dict=None) -> None:
157 """Write the format data dict to the frontend.
163 """Write the format data dict to the frontend.
158
164
159 This default version of this method simply writes the plain text
165 This default version of this method simply writes the plain text
160 representation of the object to ``sys.stdout``. Subclasses should
166 representation of the object to ``sys.stdout``. Subclasses should
161 override this method to send the entire `format_dict` to the
167 override this method to send the entire `format_dict` to the
162 frontends.
168 frontends.
163
169
164 Parameters
170 Parameters
165 ----------
171 ----------
166 format_dict : dict
172 format_dict : dict
167 The format dict for the object passed to `sys.displayhook`.
173 The format dict for the object passed to `sys.displayhook`.
168 md_dict : dict (optional)
174 md_dict : dict (optional)
169 The metadata dict to be associated with the display data.
175 The metadata dict to be associated with the display data.
170 """
176 """
171 if 'text/plain' not in format_dict:
177 if 'text/plain' not in format_dict:
172 # nothing to do
178 # nothing to do
173 return
179 return
174 # We want to print because we want to always make sure we have a
180 # We want to print because we want to always make sure we have a
175 # newline, even if all the prompt separators are ''. This is the
181 # newline, even if all the prompt separators are ''. This is the
176 # standard IPython behavior.
182 # standard IPython behavior.
177 result_repr = format_dict['text/plain']
183 result_repr = format_dict['text/plain']
178 if '\n' in result_repr:
184 if '\n' in result_repr:
179 # So that multi-line strings line up with the left column of
185 # So that multi-line strings line up with the left column of
180 # the screen, instead of having the output prompt mess up
186 # the screen, instead of having the output prompt mess up
181 # their first line.
187 # their first line.
182 # We use the prompt template instead of the expanded prompt
188 # We use the prompt template instead of the expanded prompt
183 # because the expansion may add ANSI escapes that will interfere
189 # because the expansion may add ANSI escapes that will interfere
184 # with our ability to determine whether or not we should add
190 # with our ability to determine whether or not we should add
185 # a newline.
191 # a newline.
186 if not self.prompt_end_newline:
192 if not self.prompt_end_newline:
187 # But avoid extraneous empty lines.
193 # But avoid extraneous empty lines.
188 result_repr = '\n' + result_repr
194 result_repr = '\n' + result_repr
189
195
190 try:
196 try:
191 print(result_repr)
197 print(result_repr)
192 except UnicodeEncodeError:
198 except UnicodeEncodeError:
193 # If a character is not supported by the terminal encoding replace
199 # If a character is not supported by the terminal encoding replace
194 # it with its \u or \x representation
200 # it with its \u or \x representation
195 print(result_repr.encode(sys.stdout.encoding,'backslashreplace').decode(sys.stdout.encoding))
201 print(result_repr.encode(sys.stdout.encoding,'backslashreplace').decode(sys.stdout.encoding))
196
202
197 def update_user_ns(self, result):
203 def update_user_ns(self, result):
198 """Update user_ns with various things like _, __, _1, etc."""
204 """Update user_ns with various things like _, __, _1, etc."""
199
205
200 # Avoid recursive reference when displaying _oh/Out
206 # Avoid recursive reference when displaying _oh/Out
201 if self.cache_size and result is not self.shell.user_ns['_oh']:
207 if self.cache_size and result is not self.shell.user_ns['_oh']:
202 if len(self.shell.user_ns['_oh']) >= self.cache_size and self.do_full_cache:
208 if len(self.shell.user_ns['_oh']) >= self.cache_size and self.do_full_cache:
203 self.cull_cache()
209 self.cull_cache()
204
210
205 # Don't overwrite '_' and friends if '_' is in __builtin__
211 # Don't overwrite '_' and friends if '_' is in __builtin__
206 # (otherwise we cause buggy behavior for things like gettext). and
212 # (otherwise we cause buggy behavior for things like gettext). and
207 # do not overwrite _, __ or ___ if one of these has been assigned
213 # do not overwrite _, __ or ___ if one of these has been assigned
208 # by the user.
214 # by the user.
209 update_unders = True
215 update_unders = True
210 for unders in ['_'*i for i in range(1,4)]:
216 for unders in ['_'*i for i in range(1,4)]:
211 if not unders in self.shell.user_ns:
217 if not unders in self.shell.user_ns:
212 continue
218 continue
213 if getattr(self, unders) is not self.shell.user_ns.get(unders):
219 if getattr(self, unders) is not self.shell.user_ns.get(unders):
214 update_unders = False
220 update_unders = False
215
221
216 self.___ = self.__
222 self.___ = self.__
217 self.__ = self._
223 self.__ = self._
218 self._ = result
224 self._ = result
219
225
220 if ('_' not in builtin_mod.__dict__) and (update_unders):
226 if ('_' not in builtin_mod.__dict__) and (update_unders):
221 self.shell.push({'_':self._,
227 self.shell.push({'_':self._,
222 '__':self.__,
228 '__':self.__,
223 '___':self.___}, interactive=False)
229 '___':self.___}, interactive=False)
224
230
225 # hackish access to top-level namespace to create _1,_2... dynamically
231 # hackish access to top-level namespace to create _1,_2... dynamically
226 to_main = {}
232 to_main = {}
227 if self.do_full_cache:
233 if self.do_full_cache:
228 new_result = '_%s' % self.prompt_count
234 new_result = '_%s' % self.prompt_count
229 to_main[new_result] = result
235 to_main[new_result] = result
230 self.shell.push(to_main, interactive=False)
236 self.shell.push(to_main, interactive=False)
231 self.shell.user_ns['_oh'][self.prompt_count] = result
237 self.shell.user_ns['_oh'][self.prompt_count] = result
232
238
233 def fill_exec_result(self, result):
239 def fill_exec_result(self, result):
234 if self.exec_result is not None:
240 if self.exec_result is not None:
235 self.exec_result.result = result
241 self.exec_result.result = result
236
242
237 def log_output(self, format_dict):
243 def log_output(self, format_dict):
238 """Log the output."""
244 """Log the output."""
239 if 'text/plain' not in format_dict:
245 if 'text/plain' not in format_dict:
240 # nothing to do
246 # nothing to do
241 return
247 return
242 if self.shell.logger.log_output:
248 if self.shell.logger.log_output:
243 self.shell.logger.log_write(format_dict['text/plain'], 'output')
249 self.shell.logger.log_write(format_dict['text/plain'], 'output')
244 self.shell.history_manager.output_hist_reprs[self.prompt_count] = \
250 self.shell.history_manager.output_hist_reprs[self.prompt_count] = \
245 format_dict['text/plain']
251 format_dict['text/plain']
246
252
247 def finish_displayhook(self):
253 def finish_displayhook(self):
248 """Finish up all displayhook activities."""
254 """Finish up all displayhook activities."""
249 sys.stdout.write(self.shell.separate_out2)
255 sys.stdout.write(self.shell.separate_out2)
250 sys.stdout.flush()
256 sys.stdout.flush()
251
257
252 def __call__(self, result=None):
258 def __call__(self, result=None):
253 """Printing with history cache management.
259 """Printing with history cache management.
254
260
255 This is invoked every time the interpreter needs to print, and is
261 This is invoked every time the interpreter needs to print, and is
256 activated by setting the variable sys.displayhook to it.
262 activated by setting the variable sys.displayhook to it.
257 """
263 """
258 self.check_for_underscore()
264 self.check_for_underscore()
259 if result is not None and not self.quiet():
265 if result is not None and not self.quiet():
260 self.start_displayhook()
266 self.start_displayhook()
261 self.write_output_prompt()
267 self.write_output_prompt()
262 format_dict, md_dict = self.compute_format_data(result)
268 format_dict, md_dict = self.compute_format_data(result)
263 self.update_user_ns(result)
269 self.update_user_ns(result)
264 self.fill_exec_result(result)
270 self.fill_exec_result(result)
265 if format_dict:
271 if format_dict:
266 self.write_format_data(format_dict, md_dict)
272 self.write_format_data(format_dict, md_dict)
267 self.log_output(format_dict)
273 self.log_output(format_dict)
268 self.finish_displayhook()
274 self.finish_displayhook()
269
275
270 def cull_cache(self):
276 def cull_cache(self):
271 """Output cache is full, cull the oldest entries"""
277 """Output cache is full, cull the oldest entries"""
272 oh = self.shell.user_ns.get('_oh', {})
278 oh = self.shell.user_ns.get('_oh', {})
273 sz = len(oh)
279 sz = len(oh)
274 cull_count = max(int(sz * self.cull_fraction), 2)
280 cull_count = max(int(sz * self.cull_fraction), 2)
275 warn('Output cache limit (currently {sz} entries) hit.\n'
281 warn('Output cache limit (currently {sz} entries) hit.\n'
276 'Flushing oldest {cull_count} entries.'.format(sz=sz, cull_count=cull_count))
282 'Flushing oldest {cull_count} entries.'.format(sz=sz, cull_count=cull_count))
277
283
278 for i, n in enumerate(sorted(oh)):
284 for i, n in enumerate(sorted(oh)):
279 if i >= cull_count:
285 if i >= cull_count:
280 break
286 break
281 self.shell.user_ns.pop('_%i' % n, None)
287 self.shell.user_ns.pop('_%i' % n, None)
282 oh.pop(n, None)
288 oh.pop(n, None)
283
289
284
290
285 def flush(self):
291 def flush(self):
286 if not self.do_full_cache:
292 if not self.do_full_cache:
287 raise ValueError("You shouldn't have reached the cache flush "
293 raise ValueError("You shouldn't have reached the cache flush "
288 "if full caching is not enabled!")
294 "if full caching is not enabled!")
289 # delete auto-generated vars from global namespace
295 # delete auto-generated vars from global namespace
290
296
291 for n in range(1,self.prompt_count + 1):
297 for n in range(1,self.prompt_count + 1):
292 key = '_'+repr(n)
298 key = '_'+repr(n)
293 try:
299 try:
294 del self.shell.user_ns[key]
300 del self.shell.user_ns[key]
295 except: pass
301 except: pass
296 # In some embedded circumstances, the user_ns doesn't have the
302 # In some embedded circumstances, the user_ns doesn't have the
297 # '_oh' key set up.
303 # '_oh' key set up.
298 oh = self.shell.user_ns.get('_oh', None)
304 oh = self.shell.user_ns.get('_oh', None)
299 if oh is not None:
305 if oh is not None:
300 oh.clear()
306 oh.clear()
301
307
302 # Release our own references to objects:
308 # Release our own references to objects:
303 self._, self.__, self.___ = '', '', ''
309 self._, self.__, self.___ = '', '', ''
304
310
305 if '_' not in builtin_mod.__dict__:
311 if '_' not in builtin_mod.__dict__:
306 self.shell.user_ns.update({'_':self._,'__':self.__,'___':self.___})
312 self.shell.user_ns.update({'_':self._,'__':self.__,'___':self.___})
307 import gc
313 import gc
308 # TODO: Is this really needed?
314 # TODO: Is this really needed?
309 # IronPython blocks here forever
315 # IronPython blocks here forever
310 if sys.platform != "cli":
316 if sys.platform != "cli":
311 gc.collect()
317 gc.collect()
312
318
313
319
314 class CapturingDisplayHook(object):
320 class CapturingDisplayHook(object):
315 def __init__(self, shell, outputs=None):
321 def __init__(self, shell, outputs=None):
316 self.shell = shell
322 self.shell = shell
317 if outputs is None:
323 if outputs is None:
318 outputs = []
324 outputs = []
319 self.outputs = outputs
325 self.outputs = outputs
320
326
321 def __call__(self, result=None):
327 def __call__(self, result=None):
322 if result is None:
328 if result is None:
323 return
329 return
324 format_dict, md_dict = self.shell.display_formatter.format(result)
330 format_dict, md_dict = self.shell.display_formatter.format(result)
325 self.outputs.append({ 'data': format_dict, 'metadata': md_dict })
331 self.outputs.append({ 'data': format_dict, 'metadata': md_dict })
@@ -1,3843 +1,3843 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Main IPython class."""
2 """Main IPython class."""
3
3
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 # Copyright (C) 2008-2011 The IPython Development Team
7 # Copyright (C) 2008-2011 The IPython Development Team
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13
13
14 import abc
14 import abc
15 import ast
15 import ast
16 import atexit
16 import atexit
17 import bdb
17 import bdb
18 import builtins as builtin_mod
18 import builtins as builtin_mod
19 import functools
19 import functools
20 import inspect
20 import inspect
21 import os
21 import os
22 import re
22 import re
23 import runpy
23 import runpy
24 import subprocess
24 import subprocess
25 import sys
25 import sys
26 import tempfile
26 import tempfile
27 import traceback
27 import traceback
28 import types
28 import types
29 import warnings
29 import warnings
30 from ast import stmt
30 from ast import stmt
31 from io import open as io_open
31 from io import open as io_open
32 from logging import error
32 from logging import error
33 from pathlib import Path
33 from pathlib import Path
34 from typing import Callable
34 from typing import Callable
35 from typing import List as ListType
35 from typing import List as ListType
36 from typing import Optional, Tuple
36 from typing import Optional, Tuple
37 from warnings import warn
37 from warnings import warn
38
38
39 from pickleshare import PickleShareDB
39 from pickleshare import PickleShareDB
40 from tempfile import TemporaryDirectory
40 from tempfile import TemporaryDirectory
41 from traitlets import (
41 from traitlets import (
42 Any,
42 Any,
43 Bool,
43 Bool,
44 CaselessStrEnum,
44 CaselessStrEnum,
45 Dict,
45 Dict,
46 Enum,
46 Enum,
47 Instance,
47 Instance,
48 Integer,
48 Integer,
49 List,
49 List,
50 Type,
50 Type,
51 Unicode,
51 Unicode,
52 default,
52 default,
53 observe,
53 observe,
54 validate,
54 validate,
55 )
55 )
56 from traitlets.config.configurable import SingletonConfigurable
56 from traitlets.config.configurable import SingletonConfigurable
57 from traitlets.utils.importstring import import_item
57 from traitlets.utils.importstring import import_item
58
58
59 import IPython.core.hooks
59 import IPython.core.hooks
60 from IPython.core import magic, oinspect, page, prefilter, ultratb
60 from IPython.core import magic, oinspect, page, prefilter, ultratb
61 from IPython.core.alias import Alias, AliasManager
61 from IPython.core.alias import Alias, AliasManager
62 from IPython.core.autocall import ExitAutocall
62 from IPython.core.autocall import ExitAutocall
63 from IPython.core.builtin_trap import BuiltinTrap
63 from IPython.core.builtin_trap import BuiltinTrap
64 from IPython.core.compilerop import CachingCompiler
64 from IPython.core.compilerop import CachingCompiler
65 from IPython.core.debugger import InterruptiblePdb
65 from IPython.core.debugger import InterruptiblePdb
66 from IPython.core.display_trap import DisplayTrap
66 from IPython.core.display_trap import DisplayTrap
67 from IPython.core.displayhook import DisplayHook
67 from IPython.core.displayhook import DisplayHook
68 from IPython.core.displaypub import DisplayPublisher
68 from IPython.core.displaypub import DisplayPublisher
69 from IPython.core.error import InputRejected, UsageError
69 from IPython.core.error import InputRejected, UsageError
70 from IPython.core.events import EventManager, available_events
70 from IPython.core.events import EventManager, available_events
71 from IPython.core.extensions import ExtensionManager
71 from IPython.core.extensions import ExtensionManager
72 from IPython.core.formatters import DisplayFormatter
72 from IPython.core.formatters import DisplayFormatter
73 from IPython.core.history import HistoryManager
73 from IPython.core.history import HistoryManager
74 from IPython.core.inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
74 from IPython.core.inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
75 from IPython.core.logger import Logger
75 from IPython.core.logger import Logger
76 from IPython.core.macro import Macro
76 from IPython.core.macro import Macro
77 from IPython.core.payload import PayloadManager
77 from IPython.core.payload import PayloadManager
78 from IPython.core.prefilter import PrefilterManager
78 from IPython.core.prefilter import PrefilterManager
79 from IPython.core.profiledir import ProfileDir
79 from IPython.core.profiledir import ProfileDir
80 from IPython.core.usage import default_banner
80 from IPython.core.usage import default_banner
81 from IPython.display import display
81 from IPython.display import display
82 from IPython.paths import get_ipython_dir
82 from IPython.paths import get_ipython_dir
83 from IPython.testing.skipdoctest import skip_doctest
83 from IPython.testing.skipdoctest import skip_doctest
84 from IPython.utils import PyColorize, io, openpy, py3compat
84 from IPython.utils import PyColorize, io, openpy, py3compat
85 from IPython.utils.decorators import undoc
85 from IPython.utils.decorators import undoc
86 from IPython.utils.io import ask_yes_no
86 from IPython.utils.io import ask_yes_no
87 from IPython.utils.ipstruct import Struct
87 from IPython.utils.ipstruct import Struct
88 from IPython.utils.path import ensure_dir_exists, get_home_dir, get_py_filename
88 from IPython.utils.path import ensure_dir_exists, get_home_dir, get_py_filename
89 from IPython.utils.process import getoutput, system
89 from IPython.utils.process import getoutput, system
90 from IPython.utils.strdispatch import StrDispatch
90 from IPython.utils.strdispatch import StrDispatch
91 from IPython.utils.syspathcontext import prepended_to_syspath
91 from IPython.utils.syspathcontext import prepended_to_syspath
92 from IPython.utils.text import DollarFormatter, LSString, SList, format_screen
92 from IPython.utils.text import DollarFormatter, LSString, SList, format_screen
93
93
94 sphinxify: Optional[Callable]
94 sphinxify: Optional[Callable]
95
95
96 try:
96 try:
97 import docrepr.sphinxify as sphx
97 import docrepr.sphinxify as sphx
98
98
99 def sphinxify(oinfo):
99 def sphinxify(oinfo):
100 wrapped_docstring = sphx.wrap_main_docstring(oinfo)
100 wrapped_docstring = sphx.wrap_main_docstring(oinfo)
101
101
102 def sphinxify_docstring(docstring):
102 def sphinxify_docstring(docstring):
103 with TemporaryDirectory() as dirname:
103 with TemporaryDirectory() as dirname:
104 return {
104 return {
105 "text/html": sphx.sphinxify(wrapped_docstring, dirname),
105 "text/html": sphx.sphinxify(wrapped_docstring, dirname),
106 "text/plain": docstring,
106 "text/plain": docstring,
107 }
107 }
108
108
109 return sphinxify_docstring
109 return sphinxify_docstring
110 except ImportError:
110 except ImportError:
111 sphinxify = None
111 sphinxify = None
112
112
113
113
114 class ProvisionalWarning(DeprecationWarning):
114 class ProvisionalWarning(DeprecationWarning):
115 """
115 """
116 Warning class for unstable features
116 Warning class for unstable features
117 """
117 """
118 pass
118 pass
119
119
120 from ast import Module
120 from ast import Module
121
121
122 _assign_nodes = (ast.AugAssign, ast.AnnAssign, ast.Assign)
122 _assign_nodes = (ast.AugAssign, ast.AnnAssign, ast.Assign)
123 _single_targets_nodes = (ast.AugAssign, ast.AnnAssign)
123 _single_targets_nodes = (ast.AugAssign, ast.AnnAssign)
124
124
125 #-----------------------------------------------------------------------------
125 #-----------------------------------------------------------------------------
126 # Await Helpers
126 # Await Helpers
127 #-----------------------------------------------------------------------------
127 #-----------------------------------------------------------------------------
128
128
129 # we still need to run things using the asyncio eventloop, but there is no
129 # we still need to run things using the asyncio eventloop, but there is no
130 # async integration
130 # async integration
131 from .async_helpers import (
131 from .async_helpers import (
132 _asyncio_runner,
132 _asyncio_runner,
133 _curio_runner,
133 _curio_runner,
134 _pseudo_sync_runner,
134 _pseudo_sync_runner,
135 _should_be_async,
135 _should_be_async,
136 _trio_runner,
136 _trio_runner,
137 )
137 )
138
138
139 #-----------------------------------------------------------------------------
139 #-----------------------------------------------------------------------------
140 # Globals
140 # Globals
141 #-----------------------------------------------------------------------------
141 #-----------------------------------------------------------------------------
142
142
143 # compiled regexps for autoindent management
143 # compiled regexps for autoindent management
144 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
144 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
145
145
146 #-----------------------------------------------------------------------------
146 #-----------------------------------------------------------------------------
147 # Utilities
147 # Utilities
148 #-----------------------------------------------------------------------------
148 #-----------------------------------------------------------------------------
149
149
150
150
151 def is_integer_string(s: str):
151 def is_integer_string(s: str):
152 """
152 """
153 Variant of "str.isnumeric()" that allow negative values and other ints.
153 Variant of "str.isnumeric()" that allow negative values and other ints.
154 """
154 """
155 try:
155 try:
156 int(s)
156 int(s)
157 return True
157 return True
158 except ValueError:
158 except ValueError:
159 return False
159 return False
160 raise ValueError("Unexpected error")
160 raise ValueError("Unexpected error")
161
161
162
162
163 @undoc
163 @undoc
164 def softspace(file, newvalue):
164 def softspace(file, newvalue):
165 """Copied from code.py, to remove the dependency"""
165 """Copied from code.py, to remove the dependency"""
166
166
167 oldvalue = 0
167 oldvalue = 0
168 try:
168 try:
169 oldvalue = file.softspace
169 oldvalue = file.softspace
170 except AttributeError:
170 except AttributeError:
171 pass
171 pass
172 try:
172 try:
173 file.softspace = newvalue
173 file.softspace = newvalue
174 except (AttributeError, TypeError):
174 except (AttributeError, TypeError):
175 # "attribute-less object" or "read-only attributes"
175 # "attribute-less object" or "read-only attributes"
176 pass
176 pass
177 return oldvalue
177 return oldvalue
178
178
179 @undoc
179 @undoc
180 def no_op(*a, **kw):
180 def no_op(*a, **kw):
181 pass
181 pass
182
182
183
183
184 class SpaceInInput(Exception): pass
184 class SpaceInInput(Exception): pass
185
185
186
186
187 class SeparateUnicode(Unicode):
187 class SeparateUnicode(Unicode):
188 r"""A Unicode subclass to validate separate_in, separate_out, etc.
188 r"""A Unicode subclass to validate separate_in, separate_out, etc.
189
189
190 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
190 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
191 """
191 """
192
192
193 def validate(self, obj, value):
193 def validate(self, obj, value):
194 if value == '0': value = ''
194 if value == '0': value = ''
195 value = value.replace('\\n','\n')
195 value = value.replace('\\n','\n')
196 return super(SeparateUnicode, self).validate(obj, value)
196 return super(SeparateUnicode, self).validate(obj, value)
197
197
198
198
199 @undoc
199 @undoc
200 class DummyMod(object):
200 class DummyMod(object):
201 """A dummy module used for IPython's interactive module when
201 """A dummy module used for IPython's interactive module when
202 a namespace must be assigned to the module's __dict__."""
202 a namespace must be assigned to the module's __dict__."""
203 __spec__ = None
203 __spec__ = None
204
204
205
205
206 class ExecutionInfo(object):
206 class ExecutionInfo(object):
207 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
207 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
208
208
209 Stores information about what is going to happen.
209 Stores information about what is going to happen.
210 """
210 """
211 raw_cell = None
211 raw_cell = None
212 store_history = False
212 store_history = False
213 silent = False
213 silent = False
214 shell_futures = True
214 shell_futures = True
215 cell_id = None
215 cell_id = None
216
216
217 def __init__(self, raw_cell, store_history, silent, shell_futures, cell_id):
217 def __init__(self, raw_cell, store_history, silent, shell_futures, cell_id):
218 self.raw_cell = raw_cell
218 self.raw_cell = raw_cell
219 self.store_history = store_history
219 self.store_history = store_history
220 self.silent = silent
220 self.silent = silent
221 self.shell_futures = shell_futures
221 self.shell_futures = shell_futures
222 self.cell_id = cell_id
222 self.cell_id = cell_id
223
223
224 def __repr__(self):
224 def __repr__(self):
225 name = self.__class__.__qualname__
225 name = self.__class__.__qualname__
226 raw_cell = (
226 raw_cell = (
227 (self.raw_cell[:50] + "..") if len(self.raw_cell) > 50 else self.raw_cell
227 (self.raw_cell[:50] + "..") if len(self.raw_cell) > 50 else self.raw_cell
228 )
228 )
229 return (
229 return (
230 '<%s object at %x, raw_cell="%s" store_history=%s silent=%s shell_futures=%s cell_id=%s>'
230 '<%s object at %x, raw_cell="%s" store_history=%s silent=%s shell_futures=%s cell_id=%s>'
231 % (
231 % (
232 name,
232 name,
233 id(self),
233 id(self),
234 raw_cell,
234 raw_cell,
235 self.store_history,
235 self.store_history,
236 self.silent,
236 self.silent,
237 self.shell_futures,
237 self.shell_futures,
238 self.cell_id,
238 self.cell_id,
239 )
239 )
240 )
240 )
241
241
242
242
243 class ExecutionResult(object):
243 class ExecutionResult(object):
244 """The result of a call to :meth:`InteractiveShell.run_cell`
244 """The result of a call to :meth:`InteractiveShell.run_cell`
245
245
246 Stores information about what took place.
246 Stores information about what took place.
247 """
247 """
248 execution_count = None
248 execution_count = None
249 error_before_exec = None
249 error_before_exec = None
250 error_in_exec: Optional[BaseException] = None
250 error_in_exec: Optional[BaseException] = None
251 info = None
251 info = None
252 result = None
252 result = None
253
253
254 def __init__(self, info):
254 def __init__(self, info):
255 self.info = info
255 self.info = info
256
256
257 @property
257 @property
258 def success(self):
258 def success(self):
259 return (self.error_before_exec is None) and (self.error_in_exec is None)
259 return (self.error_before_exec is None) and (self.error_in_exec is None)
260
260
261 def raise_error(self):
261 def raise_error(self):
262 """Reraises error if `success` is `False`, otherwise does nothing"""
262 """Reraises error if `success` is `False`, otherwise does nothing"""
263 if self.error_before_exec is not None:
263 if self.error_before_exec is not None:
264 raise self.error_before_exec
264 raise self.error_before_exec
265 if self.error_in_exec is not None:
265 if self.error_in_exec is not None:
266 raise self.error_in_exec
266 raise self.error_in_exec
267
267
268 def __repr__(self):
268 def __repr__(self):
269 name = self.__class__.__qualname__
269 name = self.__class__.__qualname__
270 return '<%s object at %x, execution_count=%s error_before_exec=%s error_in_exec=%s info=%s result=%s>' %\
270 return '<%s object at %x, execution_count=%s error_before_exec=%s error_in_exec=%s info=%s result=%s>' %\
271 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))
271 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))
272
272
273 @functools.wraps(io_open)
273 @functools.wraps(io_open)
274 def _modified_open(file, *args, **kwargs):
274 def _modified_open(file, *args, **kwargs):
275 if file in {0, 1, 2}:
275 if file in {0, 1, 2}:
276 raise ValueError(
276 raise ValueError(
277 f"IPython won't let you open fd={file} by default "
277 f"IPython won't let you open fd={file} by default "
278 "as it is likely to crash IPython. If you know what you are doing, "
278 "as it is likely to crash IPython. If you know what you are doing, "
279 "you can use builtins' open."
279 "you can use builtins' open."
280 )
280 )
281
281
282 return io_open(file, *args, **kwargs)
282 return io_open(file, *args, **kwargs)
283
283
284 class InteractiveShell(SingletonConfigurable):
284 class InteractiveShell(SingletonConfigurable):
285 """An enhanced, interactive shell for Python."""
285 """An enhanced, interactive shell for Python."""
286
286
287 _instance = None
287 _instance = None
288
288
289 ast_transformers = List([], help=
289 ast_transformers = List([], help=
290 """
290 """
291 A list of ast.NodeTransformer subclass instances, which will be applied
291 A list of ast.NodeTransformer subclass instances, which will be applied
292 to user input before code is run.
292 to user input before code is run.
293 """
293 """
294 ).tag(config=True)
294 ).tag(config=True)
295
295
296 autocall = Enum((0,1,2), default_value=0, help=
296 autocall = Enum((0,1,2), default_value=0, help=
297 """
297 """
298 Make IPython automatically call any callable object even if you didn't
298 Make IPython automatically call any callable object even if you didn't
299 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
299 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
300 automatically. The value can be '0' to disable the feature, '1' for
300 automatically. The value can be '0' to disable the feature, '1' for
301 'smart' autocall, where it is not applied if there are no more
301 'smart' autocall, where it is not applied if there are no more
302 arguments on the line, and '2' for 'full' autocall, where all callable
302 arguments on the line, and '2' for 'full' autocall, where all callable
303 objects are automatically called (even if no arguments are present).
303 objects are automatically called (even if no arguments are present).
304 """
304 """
305 ).tag(config=True)
305 ).tag(config=True)
306
306
307 autoindent = Bool(True, help=
307 autoindent = Bool(True, help=
308 """
308 """
309 Autoindent IPython code entered interactively.
309 Autoindent IPython code entered interactively.
310 """
310 """
311 ).tag(config=True)
311 ).tag(config=True)
312
312
313 autoawait = Bool(True, help=
313 autoawait = Bool(True, help=
314 """
314 """
315 Automatically run await statement in the top level repl.
315 Automatically run await statement in the top level repl.
316 """
316 """
317 ).tag(config=True)
317 ).tag(config=True)
318
318
319 loop_runner_map ={
319 loop_runner_map ={
320 'asyncio':(_asyncio_runner, True),
320 'asyncio':(_asyncio_runner, True),
321 'curio':(_curio_runner, True),
321 'curio':(_curio_runner, True),
322 'trio':(_trio_runner, True),
322 'trio':(_trio_runner, True),
323 'sync': (_pseudo_sync_runner, False)
323 'sync': (_pseudo_sync_runner, False)
324 }
324 }
325
325
326 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",
326 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",
327 allow_none=True,
327 allow_none=True,
328 help="""Select the loop runner that will be used to execute top-level asynchronous code"""
328 help="""Select the loop runner that will be used to execute top-level asynchronous code"""
329 ).tag(config=True)
329 ).tag(config=True)
330
330
331 @default('loop_runner')
331 @default('loop_runner')
332 def _default_loop_runner(self):
332 def _default_loop_runner(self):
333 return import_item("IPython.core.interactiveshell._asyncio_runner")
333 return import_item("IPython.core.interactiveshell._asyncio_runner")
334
334
335 @validate('loop_runner')
335 @validate('loop_runner')
336 def _import_runner(self, proposal):
336 def _import_runner(self, proposal):
337 if isinstance(proposal.value, str):
337 if isinstance(proposal.value, str):
338 if proposal.value in self.loop_runner_map:
338 if proposal.value in self.loop_runner_map:
339 runner, autoawait = self.loop_runner_map[proposal.value]
339 runner, autoawait = self.loop_runner_map[proposal.value]
340 self.autoawait = autoawait
340 self.autoawait = autoawait
341 return runner
341 return runner
342 runner = import_item(proposal.value)
342 runner = import_item(proposal.value)
343 if not callable(runner):
343 if not callable(runner):
344 raise ValueError('loop_runner must be callable')
344 raise ValueError('loop_runner must be callable')
345 return runner
345 return runner
346 if not callable(proposal.value):
346 if not callable(proposal.value):
347 raise ValueError('loop_runner must be callable')
347 raise ValueError('loop_runner must be callable')
348 return proposal.value
348 return proposal.value
349
349
350 automagic = Bool(True, help=
350 automagic = Bool(True, help=
351 """
351 """
352 Enable magic commands to be called without the leading %.
352 Enable magic commands to be called without the leading %.
353 """
353 """
354 ).tag(config=True)
354 ).tag(config=True)
355
355
356 banner1 = Unicode(default_banner,
356 banner1 = Unicode(default_banner,
357 help="""The part of the banner to be printed before the profile"""
357 help="""The part of the banner to be printed before the profile"""
358 ).tag(config=True)
358 ).tag(config=True)
359 banner2 = Unicode('',
359 banner2 = Unicode('',
360 help="""The part of the banner to be printed after the profile"""
360 help="""The part of the banner to be printed after the profile"""
361 ).tag(config=True)
361 ).tag(config=True)
362
362
363 cache_size = Integer(1000, help=
363 cache_size = Integer(1000, help=
364 """
364 """
365 Set the size of the output cache. The default is 1000, you can
365 Set the size of the output cache. The default is 1000, you can
366 change it permanently in your config file. Setting it to 0 completely
366 change it permanently in your config file. Setting it to 0 completely
367 disables the caching system, and the minimum value accepted is 3 (if
367 disables the caching system, and the minimum value accepted is 3 (if
368 you provide a value less than 3, it is reset to 0 and a warning is
368 you provide a value less than 3, it is reset to 0 and a warning is
369 issued). This limit is defined because otherwise you'll spend more
369 issued). This limit is defined because otherwise you'll spend more
370 time re-flushing a too small cache than working
370 time re-flushing a too small cache than working
371 """
371 """
372 ).tag(config=True)
372 ).tag(config=True)
373 color_info = Bool(True, help=
373 color_info = Bool(True, help=
374 """
374 """
375 Use colors for displaying information about objects. Because this
375 Use colors for displaying information about objects. Because this
376 information is passed through a pager (like 'less'), and some pagers
376 information is passed through a pager (like 'less'), and some pagers
377 get confused with color codes, this capability can be turned off.
377 get confused with color codes, this capability can be turned off.
378 """
378 """
379 ).tag(config=True)
379 ).tag(config=True)
380 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
380 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
381 default_value='Neutral',
381 default_value='Neutral',
382 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
382 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
383 ).tag(config=True)
383 ).tag(config=True)
384 debug = Bool(False).tag(config=True)
384 debug = Bool(False).tag(config=True)
385 disable_failing_post_execute = Bool(False,
385 disable_failing_post_execute = Bool(False,
386 help="Don't call post-execute functions that have failed in the past."
386 help="Don't call post-execute functions that have failed in the past."
387 ).tag(config=True)
387 ).tag(config=True)
388 display_formatter = Instance(DisplayFormatter, allow_none=True)
388 display_formatter = Instance(DisplayFormatter, allow_none=True)
389 displayhook_class = Type(DisplayHook)
389 displayhook_class = Type(DisplayHook)
390 display_pub_class = Type(DisplayPublisher)
390 display_pub_class = Type(DisplayPublisher)
391 compiler_class = Type(CachingCompiler)
391 compiler_class = Type(CachingCompiler)
392
392
393 sphinxify_docstring = Bool(False, help=
393 sphinxify_docstring = Bool(False, help=
394 """
394 """
395 Enables rich html representation of docstrings. (This requires the
395 Enables rich html representation of docstrings. (This requires the
396 docrepr module).
396 docrepr module).
397 """).tag(config=True)
397 """).tag(config=True)
398
398
399 @observe("sphinxify_docstring")
399 @observe("sphinxify_docstring")
400 def _sphinxify_docstring_changed(self, change):
400 def _sphinxify_docstring_changed(self, change):
401 if change['new']:
401 if change['new']:
402 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
402 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
403
403
404 enable_html_pager = Bool(False, help=
404 enable_html_pager = Bool(False, help=
405 """
405 """
406 (Provisional API) enables html representation in mime bundles sent
406 (Provisional API) enables html representation in mime bundles sent
407 to pagers.
407 to pagers.
408 """).tag(config=True)
408 """).tag(config=True)
409
409
410 @observe("enable_html_pager")
410 @observe("enable_html_pager")
411 def _enable_html_pager_changed(self, change):
411 def _enable_html_pager_changed(self, change):
412 if change['new']:
412 if change['new']:
413 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
413 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
414
414
415 data_pub_class = None
415 data_pub_class = None
416
416
417 exit_now = Bool(False)
417 exit_now = Bool(False)
418 exiter = Instance(ExitAutocall)
418 exiter = Instance(ExitAutocall)
419 @default('exiter')
419 @default('exiter')
420 def _exiter_default(self):
420 def _exiter_default(self):
421 return ExitAutocall(self)
421 return ExitAutocall(self)
422 # Monotonically increasing execution counter
422 # Monotonically increasing execution counter
423 execution_count = Integer(1)
423 execution_count = Integer(1)
424 filename = Unicode("<ipython console>")
424 filename = Unicode("<ipython console>")
425 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
425 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
426
426
427 # Used to transform cells before running them, and check whether code is complete
427 # Used to transform cells before running them, and check whether code is complete
428 input_transformer_manager = Instance('IPython.core.inputtransformer2.TransformerManager',
428 input_transformer_manager = Instance('IPython.core.inputtransformer2.TransformerManager',
429 ())
429 ())
430
430
431 @property
431 @property
432 def input_transformers_cleanup(self):
432 def input_transformers_cleanup(self):
433 return self.input_transformer_manager.cleanup_transforms
433 return self.input_transformer_manager.cleanup_transforms
434
434
435 input_transformers_post = List([],
435 input_transformers_post = List([],
436 help="A list of string input transformers, to be applied after IPython's "
436 help="A list of string input transformers, to be applied after IPython's "
437 "own input transformations."
437 "own input transformations."
438 )
438 )
439
439
440 @property
440 @property
441 def input_splitter(self):
441 def input_splitter(self):
442 """Make this available for backward compatibility (pre-7.0 release) with existing code.
442 """Make this available for backward compatibility (pre-7.0 release) with existing code.
443
443
444 For example, ipykernel ipykernel currently uses
444 For example, ipykernel ipykernel currently uses
445 `shell.input_splitter.check_complete`
445 `shell.input_splitter.check_complete`
446 """
446 """
447 from warnings import warn
447 from warnings import warn
448 warn("`input_splitter` is deprecated since IPython 7.0, prefer `input_transformer_manager`.",
448 warn("`input_splitter` is deprecated since IPython 7.0, prefer `input_transformer_manager`.",
449 DeprecationWarning, stacklevel=2
449 DeprecationWarning, stacklevel=2
450 )
450 )
451 return self.input_transformer_manager
451 return self.input_transformer_manager
452
452
453 logstart = Bool(False, help=
453 logstart = Bool(False, help=
454 """
454 """
455 Start logging to the default log file in overwrite mode.
455 Start logging to the default log file in overwrite mode.
456 Use `logappend` to specify a log file to **append** logs to.
456 Use `logappend` to specify a log file to **append** logs to.
457 """
457 """
458 ).tag(config=True)
458 ).tag(config=True)
459 logfile = Unicode('', help=
459 logfile = Unicode('', help=
460 """
460 """
461 The name of the logfile to use.
461 The name of the logfile to use.
462 """
462 """
463 ).tag(config=True)
463 ).tag(config=True)
464 logappend = Unicode('', help=
464 logappend = Unicode('', help=
465 """
465 """
466 Start logging to the given file in append mode.
466 Start logging to the given file in append mode.
467 Use `logfile` to specify a log file to **overwrite** logs to.
467 Use `logfile` to specify a log file to **overwrite** logs to.
468 """
468 """
469 ).tag(config=True)
469 ).tag(config=True)
470 object_info_string_level = Enum((0,1,2), default_value=0,
470 object_info_string_level = Enum((0,1,2), default_value=0,
471 ).tag(config=True)
471 ).tag(config=True)
472 pdb = Bool(False, help=
472 pdb = Bool(False, help=
473 """
473 """
474 Automatically call the pdb debugger after every exception.
474 Automatically call the pdb debugger after every exception.
475 """
475 """
476 ).tag(config=True)
476 ).tag(config=True)
477 display_page = Bool(False,
477 display_page = Bool(False,
478 help="""If True, anything that would be passed to the pager
478 help="""If True, anything that would be passed to the pager
479 will be displayed as regular output instead."""
479 will be displayed as regular output instead."""
480 ).tag(config=True)
480 ).tag(config=True)
481
481
482
482
483 show_rewritten_input = Bool(True,
483 show_rewritten_input = Bool(True,
484 help="Show rewritten input, e.g. for autocall."
484 help="Show rewritten input, e.g. for autocall."
485 ).tag(config=True)
485 ).tag(config=True)
486
486
487 quiet = Bool(False).tag(config=True)
487 quiet = Bool(False).tag(config=True)
488
488
489 history_length = Integer(10000,
489 history_length = Integer(10000,
490 help='Total length of command history'
490 help='Total length of command history'
491 ).tag(config=True)
491 ).tag(config=True)
492
492
493 history_load_length = Integer(1000, help=
493 history_load_length = Integer(1000, help=
494 """
494 """
495 The number of saved history entries to be loaded
495 The number of saved history entries to be loaded
496 into the history buffer at startup.
496 into the history buffer at startup.
497 """
497 """
498 ).tag(config=True)
498 ).tag(config=True)
499
499
500 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
500 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
501 default_value='last_expr',
501 default_value='last_expr',
502 help="""
502 help="""
503 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
503 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
504 which nodes should be run interactively (displaying output from expressions).
504 which nodes should be run interactively (displaying output from expressions).
505 """
505 """
506 ).tag(config=True)
506 ).tag(config=True)
507
507
508 warn_venv = Bool(
508 warn_venv = Bool(
509 True,
509 True,
510 help="Warn if running in a virtual environment with no IPython installed (so IPython from the global environment is used).",
510 help="Warn if running in a virtual environment with no IPython installed (so IPython from the global environment is used).",
511 ).tag(config=True)
511 ).tag(config=True)
512
512
513 # TODO: this part of prompt management should be moved to the frontends.
513 # TODO: this part of prompt management should be moved to the frontends.
514 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
514 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
515 separate_in = SeparateUnicode('\n').tag(config=True)
515 separate_in = SeparateUnicode('\n').tag(config=True)
516 separate_out = SeparateUnicode('').tag(config=True)
516 separate_out = SeparateUnicode('').tag(config=True)
517 separate_out2 = SeparateUnicode('').tag(config=True)
517 separate_out2 = SeparateUnicode('').tag(config=True)
518 wildcards_case_sensitive = Bool(True).tag(config=True)
518 wildcards_case_sensitive = Bool(True).tag(config=True)
519 xmode = CaselessStrEnum(('Context', 'Plain', 'Verbose', 'Minimal'),
519 xmode = CaselessStrEnum(('Context', 'Plain', 'Verbose', 'Minimal'),
520 default_value='Context',
520 default_value='Context',
521 help="Switch modes for the IPython exception handlers."
521 help="Switch modes for the IPython exception handlers."
522 ).tag(config=True)
522 ).tag(config=True)
523
523
524 # Subcomponents of InteractiveShell
524 # Subcomponents of InteractiveShell
525 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
525 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
526 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
526 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
527 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
527 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
528 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
528 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
529 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
529 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
530 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
530 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
531 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
531 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
532 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
532 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
533
533
534 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
534 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
535 @property
535 @property
536 def profile(self):
536 def profile(self):
537 if self.profile_dir is not None:
537 if self.profile_dir is not None:
538 name = os.path.basename(self.profile_dir.location)
538 name = os.path.basename(self.profile_dir.location)
539 return name.replace('profile_','')
539 return name.replace('profile_','')
540
540
541
541
542 # Private interface
542 # Private interface
543 _post_execute = Dict()
543 _post_execute = Dict()
544
544
545 # Tracks any GUI loop loaded for pylab
545 # Tracks any GUI loop loaded for pylab
546 pylab_gui_select = None
546 pylab_gui_select = None
547
547
548 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
548 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
549
549
550 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
550 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
551
551
552 def __init__(self, ipython_dir=None, profile_dir=None,
552 def __init__(self, ipython_dir=None, profile_dir=None,
553 user_module=None, user_ns=None,
553 user_module=None, user_ns=None,
554 custom_exceptions=((), None), **kwargs):
554 custom_exceptions=((), None), **kwargs):
555 # This is where traits with a config_key argument are updated
555 # This is where traits with a config_key argument are updated
556 # from the values on config.
556 # from the values on config.
557 super(InteractiveShell, self).__init__(**kwargs)
557 super(InteractiveShell, self).__init__(**kwargs)
558 if 'PromptManager' in self.config:
558 if 'PromptManager' in self.config:
559 warn('As of IPython 5.0 `PromptManager` config will have no effect'
559 warn('As of IPython 5.0 `PromptManager` config will have no effect'
560 ' and has been replaced by TerminalInteractiveShell.prompts_class')
560 ' and has been replaced by TerminalInteractiveShell.prompts_class')
561 self.configurables = [self]
561 self.configurables = [self]
562
562
563 # These are relatively independent and stateless
563 # These are relatively independent and stateless
564 self.init_ipython_dir(ipython_dir)
564 self.init_ipython_dir(ipython_dir)
565 self.init_profile_dir(profile_dir)
565 self.init_profile_dir(profile_dir)
566 self.init_instance_attrs()
566 self.init_instance_attrs()
567 self.init_environment()
567 self.init_environment()
568
568
569 # Check if we're in a virtualenv, and set up sys.path.
569 # Check if we're in a virtualenv, and set up sys.path.
570 self.init_virtualenv()
570 self.init_virtualenv()
571
571
572 # Create namespaces (user_ns, user_global_ns, etc.)
572 # Create namespaces (user_ns, user_global_ns, etc.)
573 self.init_create_namespaces(user_module, user_ns)
573 self.init_create_namespaces(user_module, user_ns)
574 # This has to be done after init_create_namespaces because it uses
574 # This has to be done after init_create_namespaces because it uses
575 # something in self.user_ns, but before init_sys_modules, which
575 # something in self.user_ns, but before init_sys_modules, which
576 # is the first thing to modify sys.
576 # is the first thing to modify sys.
577 # TODO: When we override sys.stdout and sys.stderr before this class
577 # TODO: When we override sys.stdout and sys.stderr before this class
578 # is created, we are saving the overridden ones here. Not sure if this
578 # is created, we are saving the overridden ones here. Not sure if this
579 # is what we want to do.
579 # is what we want to do.
580 self.save_sys_module_state()
580 self.save_sys_module_state()
581 self.init_sys_modules()
581 self.init_sys_modules()
582
582
583 # While we're trying to have each part of the code directly access what
583 # While we're trying to have each part of the code directly access what
584 # it needs without keeping redundant references to objects, we have too
584 # it needs without keeping redundant references to objects, we have too
585 # much legacy code that expects ip.db to exist.
585 # much legacy code that expects ip.db to exist.
586 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
586 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
587
587
588 self.init_history()
588 self.init_history()
589 self.init_encoding()
589 self.init_encoding()
590 self.init_prefilter()
590 self.init_prefilter()
591
591
592 self.init_syntax_highlighting()
592 self.init_syntax_highlighting()
593 self.init_hooks()
593 self.init_hooks()
594 self.init_events()
594 self.init_events()
595 self.init_pushd_popd_magic()
595 self.init_pushd_popd_magic()
596 self.init_user_ns()
596 self.init_user_ns()
597 self.init_logger()
597 self.init_logger()
598 self.init_builtins()
598 self.init_builtins()
599
599
600 # The following was in post_config_initialization
600 # The following was in post_config_initialization
601 self.init_inspector()
601 self.init_inspector()
602 self.raw_input_original = input
602 self.raw_input_original = input
603 self.init_completer()
603 self.init_completer()
604 # TODO: init_io() needs to happen before init_traceback handlers
604 # TODO: init_io() needs to happen before init_traceback handlers
605 # because the traceback handlers hardcode the stdout/stderr streams.
605 # because the traceback handlers hardcode the stdout/stderr streams.
606 # This logic in in debugger.Pdb and should eventually be changed.
606 # This logic in in debugger.Pdb and should eventually be changed.
607 self.init_io()
607 self.init_io()
608 self.init_traceback_handlers(custom_exceptions)
608 self.init_traceback_handlers(custom_exceptions)
609 self.init_prompts()
609 self.init_prompts()
610 self.init_display_formatter()
610 self.init_display_formatter()
611 self.init_display_pub()
611 self.init_display_pub()
612 self.init_data_pub()
612 self.init_data_pub()
613 self.init_displayhook()
613 self.init_displayhook()
614 self.init_magics()
614 self.init_magics()
615 self.init_alias()
615 self.init_alias()
616 self.init_logstart()
616 self.init_logstart()
617 self.init_pdb()
617 self.init_pdb()
618 self.init_extension_manager()
618 self.init_extension_manager()
619 self.init_payload()
619 self.init_payload()
620 self.events.trigger('shell_initialized', self)
620 self.events.trigger('shell_initialized', self)
621 atexit.register(self.atexit_operations)
621 atexit.register(self.atexit_operations)
622
622
623 # The trio runner is used for running Trio in the foreground thread. It
623 # The trio runner is used for running Trio in the foreground thread. It
624 # is different from `_trio_runner(async_fn)` in `async_helpers.py`
624 # is different from `_trio_runner(async_fn)` in `async_helpers.py`
625 # which calls `trio.run()` for every cell. This runner runs all cells
625 # which calls `trio.run()` for every cell. This runner runs all cells
626 # inside a single Trio event loop. If used, it is set from
626 # inside a single Trio event loop. If used, it is set from
627 # `ipykernel.kernelapp`.
627 # `ipykernel.kernelapp`.
628 self.trio_runner = None
628 self.trio_runner = None
629
629
630 def get_ipython(self):
630 def get_ipython(self):
631 """Return the currently running IPython instance."""
631 """Return the currently running IPython instance."""
632 return self
632 return self
633
633
634 #-------------------------------------------------------------------------
634 #-------------------------------------------------------------------------
635 # Trait changed handlers
635 # Trait changed handlers
636 #-------------------------------------------------------------------------
636 #-------------------------------------------------------------------------
637 @observe('ipython_dir')
637 @observe('ipython_dir')
638 def _ipython_dir_changed(self, change):
638 def _ipython_dir_changed(self, change):
639 ensure_dir_exists(change['new'])
639 ensure_dir_exists(change['new'])
640
640
641 def set_autoindent(self,value=None):
641 def set_autoindent(self,value=None):
642 """Set the autoindent flag.
642 """Set the autoindent flag.
643
643
644 If called with no arguments, it acts as a toggle."""
644 If called with no arguments, it acts as a toggle."""
645 if value is None:
645 if value is None:
646 self.autoindent = not self.autoindent
646 self.autoindent = not self.autoindent
647 else:
647 else:
648 self.autoindent = value
648 self.autoindent = value
649
649
650 def set_trio_runner(self, tr):
650 def set_trio_runner(self, tr):
651 self.trio_runner = tr
651 self.trio_runner = tr
652
652
653 #-------------------------------------------------------------------------
653 #-------------------------------------------------------------------------
654 # init_* methods called by __init__
654 # init_* methods called by __init__
655 #-------------------------------------------------------------------------
655 #-------------------------------------------------------------------------
656
656
657 def init_ipython_dir(self, ipython_dir):
657 def init_ipython_dir(self, ipython_dir):
658 if ipython_dir is not None:
658 if ipython_dir is not None:
659 self.ipython_dir = ipython_dir
659 self.ipython_dir = ipython_dir
660 return
660 return
661
661
662 self.ipython_dir = get_ipython_dir()
662 self.ipython_dir = get_ipython_dir()
663
663
664 def init_profile_dir(self, profile_dir):
664 def init_profile_dir(self, profile_dir):
665 if profile_dir is not None:
665 if profile_dir is not None:
666 self.profile_dir = profile_dir
666 self.profile_dir = profile_dir
667 return
667 return
668 self.profile_dir = ProfileDir.create_profile_dir_by_name(
668 self.profile_dir = ProfileDir.create_profile_dir_by_name(
669 self.ipython_dir, "default"
669 self.ipython_dir, "default"
670 )
670 )
671
671
672 def init_instance_attrs(self):
672 def init_instance_attrs(self):
673 self.more = False
673 self.more = False
674
674
675 # command compiler
675 # command compiler
676 self.compile = self.compiler_class()
676 self.compile = self.compiler_class()
677
677
678 # Make an empty namespace, which extension writers can rely on both
678 # Make an empty namespace, which extension writers can rely on both
679 # existing and NEVER being used by ipython itself. This gives them a
679 # existing and NEVER being used by ipython itself. This gives them a
680 # convenient location for storing additional information and state
680 # convenient location for storing additional information and state
681 # their extensions may require, without fear of collisions with other
681 # their extensions may require, without fear of collisions with other
682 # ipython names that may develop later.
682 # ipython names that may develop later.
683 self.meta = Struct()
683 self.meta = Struct()
684
684
685 # Temporary files used for various purposes. Deleted at exit.
685 # Temporary files used for various purposes. Deleted at exit.
686 # The files here are stored with Path from Pathlib
686 # The files here are stored with Path from Pathlib
687 self.tempfiles = []
687 self.tempfiles = []
688 self.tempdirs = []
688 self.tempdirs = []
689
689
690 # keep track of where we started running (mainly for crash post-mortem)
690 # keep track of where we started running (mainly for crash post-mortem)
691 # This is not being used anywhere currently.
691 # This is not being used anywhere currently.
692 self.starting_dir = os.getcwd()
692 self.starting_dir = os.getcwd()
693
693
694 # Indentation management
694 # Indentation management
695 self.indent_current_nsp = 0
695 self.indent_current_nsp = 0
696
696
697 # Dict to track post-execution functions that have been registered
697 # Dict to track post-execution functions that have been registered
698 self._post_execute = {}
698 self._post_execute = {}
699
699
700 def init_environment(self):
700 def init_environment(self):
701 """Any changes we need to make to the user's environment."""
701 """Any changes we need to make to the user's environment."""
702 pass
702 pass
703
703
704 def init_encoding(self):
704 def init_encoding(self):
705 # Get system encoding at startup time. Certain terminals (like Emacs
705 # Get system encoding at startup time. Certain terminals (like Emacs
706 # under Win32 have it set to None, and we need to have a known valid
706 # under Win32 have it set to None, and we need to have a known valid
707 # encoding to use in the raw_input() method
707 # encoding to use in the raw_input() method
708 try:
708 try:
709 self.stdin_encoding = sys.stdin.encoding or 'ascii'
709 self.stdin_encoding = sys.stdin.encoding or 'ascii'
710 except AttributeError:
710 except AttributeError:
711 self.stdin_encoding = 'ascii'
711 self.stdin_encoding = 'ascii'
712
712
713
713
714 @observe('colors')
714 @observe('colors')
715 def init_syntax_highlighting(self, changes=None):
715 def init_syntax_highlighting(self, changes=None):
716 # Python source parser/formatter for syntax highlighting
716 # Python source parser/formatter for syntax highlighting
717 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
717 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
718 self.pycolorize = lambda src: pyformat(src,'str')
718 self.pycolorize = lambda src: pyformat(src,'str')
719
719
720 def refresh_style(self):
720 def refresh_style(self):
721 # No-op here, used in subclass
721 # No-op here, used in subclass
722 pass
722 pass
723
723
724 def init_pushd_popd_magic(self):
724 def init_pushd_popd_magic(self):
725 # for pushd/popd management
725 # for pushd/popd management
726 self.home_dir = get_home_dir()
726 self.home_dir = get_home_dir()
727
727
728 self.dir_stack = []
728 self.dir_stack = []
729
729
730 def init_logger(self):
730 def init_logger(self):
731 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
731 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
732 logmode='rotate')
732 logmode='rotate')
733
733
734 def init_logstart(self):
734 def init_logstart(self):
735 """Initialize logging in case it was requested at the command line.
735 """Initialize logging in case it was requested at the command line.
736 """
736 """
737 if self.logappend:
737 if self.logappend:
738 self.magic('logstart %s append' % self.logappend)
738 self.magic('logstart %s append' % self.logappend)
739 elif self.logfile:
739 elif self.logfile:
740 self.magic('logstart %s' % self.logfile)
740 self.magic('logstart %s' % self.logfile)
741 elif self.logstart:
741 elif self.logstart:
742 self.magic('logstart')
742 self.magic('logstart')
743
743
744
744
745 def init_builtins(self):
745 def init_builtins(self):
746 # A single, static flag that we set to True. Its presence indicates
746 # A single, static flag that we set to True. Its presence indicates
747 # that an IPython shell has been created, and we make no attempts at
747 # that an IPython shell has been created, and we make no attempts at
748 # removing on exit or representing the existence of more than one
748 # removing on exit or representing the existence of more than one
749 # IPython at a time.
749 # IPython at a time.
750 builtin_mod.__dict__['__IPYTHON__'] = True
750 builtin_mod.__dict__['__IPYTHON__'] = True
751 builtin_mod.__dict__['display'] = display
751 builtin_mod.__dict__['display'] = display
752
752
753 self.builtin_trap = BuiltinTrap(shell=self)
753 self.builtin_trap = BuiltinTrap(shell=self)
754
754
755 @observe('colors')
755 @observe('colors')
756 def init_inspector(self, changes=None):
756 def init_inspector(self, changes=None):
757 # Object inspector
757 # Object inspector
758 self.inspector = oinspect.Inspector(oinspect.InspectColors,
758 self.inspector = oinspect.Inspector(oinspect.InspectColors,
759 PyColorize.ANSICodeColors,
759 PyColorize.ANSICodeColors,
760 self.colors,
760 self.colors,
761 self.object_info_string_level)
761 self.object_info_string_level)
762
762
763 def init_io(self):
763 def init_io(self):
764 # implemented in subclasses, TerminalInteractiveShell does call
764 # implemented in subclasses, TerminalInteractiveShell does call
765 # colorama.init().
765 # colorama.init().
766 pass
766 pass
767
767
768 def init_prompts(self):
768 def init_prompts(self):
769 # Set system prompts, so that scripts can decide if they are running
769 # Set system prompts, so that scripts can decide if they are running
770 # interactively.
770 # interactively.
771 sys.ps1 = 'In : '
771 sys.ps1 = 'In : '
772 sys.ps2 = '...: '
772 sys.ps2 = '...: '
773 sys.ps3 = 'Out: '
773 sys.ps3 = 'Out: '
774
774
775 def init_display_formatter(self):
775 def init_display_formatter(self):
776 self.display_formatter = DisplayFormatter(parent=self)
776 self.display_formatter = DisplayFormatter(parent=self)
777 self.configurables.append(self.display_formatter)
777 self.configurables.append(self.display_formatter)
778
778
779 def init_display_pub(self):
779 def init_display_pub(self):
780 self.display_pub = self.display_pub_class(parent=self, shell=self)
780 self.display_pub = self.display_pub_class(parent=self, shell=self)
781 self.configurables.append(self.display_pub)
781 self.configurables.append(self.display_pub)
782
782
783 def init_data_pub(self):
783 def init_data_pub(self):
784 if not self.data_pub_class:
784 if not self.data_pub_class:
785 self.data_pub = None
785 self.data_pub = None
786 return
786 return
787 self.data_pub = self.data_pub_class(parent=self)
787 self.data_pub = self.data_pub_class(parent=self)
788 self.configurables.append(self.data_pub)
788 self.configurables.append(self.data_pub)
789
789
790 def init_displayhook(self):
790 def init_displayhook(self):
791 # Initialize displayhook, set in/out prompts and printing system
791 # Initialize displayhook, set in/out prompts and printing system
792 self.displayhook = self.displayhook_class(
792 self.displayhook = self.displayhook_class(
793 parent=self,
793 parent=self,
794 shell=self,
794 shell=self,
795 cache_size=self.cache_size,
795 cache_size=self.cache_size,
796 )
796 )
797 self.configurables.append(self.displayhook)
797 self.configurables.append(self.displayhook)
798 # This is a context manager that installs/revmoes the displayhook at
798 # This is a context manager that installs/revmoes the displayhook at
799 # the appropriate time.
799 # the appropriate time.
800 self.display_trap = DisplayTrap(hook=self.displayhook)
800 self.display_trap = DisplayTrap(hook=self.displayhook)
801
801
802 @staticmethod
802 @staticmethod
803 def get_path_links(p: Path):
803 def get_path_links(p: Path):
804 """Gets path links including all symlinks
804 """Gets path links including all symlinks
805
805
806 Examples
806 Examples
807 --------
807 --------
808 In [1]: from IPython.core.interactiveshell import InteractiveShell
808 In [1]: from IPython.core.interactiveshell import InteractiveShell
809
809
810 In [2]: import sys, pathlib
810 In [2]: import sys, pathlib
811
811
812 In [3]: paths = InteractiveShell.get_path_links(pathlib.Path(sys.executable))
812 In [3]: paths = InteractiveShell.get_path_links(pathlib.Path(sys.executable))
813
813
814 In [4]: len(paths) == len(set(paths))
814 In [4]: len(paths) == len(set(paths))
815 Out[4]: True
815 Out[4]: True
816
816
817 In [5]: bool(paths)
817 In [5]: bool(paths)
818 Out[5]: True
818 Out[5]: True
819 """
819 """
820 paths = [p]
820 paths = [p]
821 while p.is_symlink():
821 while p.is_symlink():
822 new_path = Path(os.readlink(p))
822 new_path = Path(os.readlink(p))
823 if not new_path.is_absolute():
823 if not new_path.is_absolute():
824 new_path = p.parent / new_path
824 new_path = p.parent / new_path
825 p = new_path
825 p = new_path
826 paths.append(p)
826 paths.append(p)
827 return paths
827 return paths
828
828
829 def init_virtualenv(self):
829 def init_virtualenv(self):
830 """Add the current virtualenv to sys.path so the user can import modules from it.
830 """Add the current virtualenv to sys.path so the user can import modules from it.
831 This isn't perfect: it doesn't use the Python interpreter with which the
831 This isn't perfect: it doesn't use the Python interpreter with which the
832 virtualenv was built, and it ignores the --no-site-packages option. A
832 virtualenv was built, and it ignores the --no-site-packages option. A
833 warning will appear suggesting the user installs IPython in the
833 warning will appear suggesting the user installs IPython in the
834 virtualenv, but for many cases, it probably works well enough.
834 virtualenv, but for many cases, it probably works well enough.
835
835
836 Adapted from code snippets online.
836 Adapted from code snippets online.
837
837
838 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
838 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
839 """
839 """
840 if 'VIRTUAL_ENV' not in os.environ:
840 if 'VIRTUAL_ENV' not in os.environ:
841 # Not in a virtualenv
841 # Not in a virtualenv
842 return
842 return
843 elif os.environ["VIRTUAL_ENV"] == "":
843 elif os.environ["VIRTUAL_ENV"] == "":
844 warn("Virtual env path set to '', please check if this is intended.")
844 warn("Virtual env path set to '', please check if this is intended.")
845 return
845 return
846
846
847 p = Path(sys.executable)
847 p = Path(sys.executable)
848 p_venv = Path(os.environ["VIRTUAL_ENV"])
848 p_venv = Path(os.environ["VIRTUAL_ENV"])
849
849
850 # fallback venv detection:
850 # fallback venv detection:
851 # stdlib venv may symlink sys.executable, so we can't use realpath.
851 # stdlib venv may symlink sys.executable, so we can't use realpath.
852 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
852 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
853 # So we just check every item in the symlink tree (generally <= 3)
853 # So we just check every item in the symlink tree (generally <= 3)
854 paths = self.get_path_links(p)
854 paths = self.get_path_links(p)
855
855
856 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
856 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
857 if p_venv.parts[1] == "cygdrive":
857 if p_venv.parts[1] == "cygdrive":
858 drive_name = p_venv.parts[2]
858 drive_name = p_venv.parts[2]
859 p_venv = (drive_name + ":/") / Path(*p_venv.parts[3:])
859 p_venv = (drive_name + ":/") / Path(*p_venv.parts[3:])
860
860
861 if any(p_venv == p.parents[1] for p in paths):
861 if any(p_venv == p.parents[1] for p in paths):
862 # Our exe is inside or has access to the virtualenv, don't need to do anything.
862 # Our exe is inside or has access to the virtualenv, don't need to do anything.
863 return
863 return
864
864
865 if sys.platform == "win32":
865 if sys.platform == "win32":
866 virtual_env = str(Path(os.environ["VIRTUAL_ENV"], "Lib", "site-packages"))
866 virtual_env = str(Path(os.environ["VIRTUAL_ENV"], "Lib", "site-packages"))
867 else:
867 else:
868 virtual_env_path = Path(
868 virtual_env_path = Path(
869 os.environ["VIRTUAL_ENV"], "lib", "python{}.{}", "site-packages"
869 os.environ["VIRTUAL_ENV"], "lib", "python{}.{}", "site-packages"
870 )
870 )
871 p_ver = sys.version_info[:2]
871 p_ver = sys.version_info[:2]
872
872
873 # Predict version from py[thon]-x.x in the $VIRTUAL_ENV
873 # Predict version from py[thon]-x.x in the $VIRTUAL_ENV
874 re_m = re.search(r"\bpy(?:thon)?([23])\.(\d+)\b", os.environ["VIRTUAL_ENV"])
874 re_m = re.search(r"\bpy(?:thon)?([23])\.(\d+)\b", os.environ["VIRTUAL_ENV"])
875 if re_m:
875 if re_m:
876 predicted_path = Path(str(virtual_env_path).format(*re_m.groups()))
876 predicted_path = Path(str(virtual_env_path).format(*re_m.groups()))
877 if predicted_path.exists():
877 if predicted_path.exists():
878 p_ver = re_m.groups()
878 p_ver = re_m.groups()
879
879
880 virtual_env = str(virtual_env_path).format(*p_ver)
880 virtual_env = str(virtual_env_path).format(*p_ver)
881 if self.warn_venv:
881 if self.warn_venv:
882 warn(
882 warn(
883 "Attempting to work in a virtualenv. If you encounter problems, "
883 "Attempting to work in a virtualenv. If you encounter problems, "
884 "please install IPython inside the virtualenv."
884 "please install IPython inside the virtualenv."
885 )
885 )
886 import site
886 import site
887 sys.path.insert(0, virtual_env)
887 sys.path.insert(0, virtual_env)
888 site.addsitedir(virtual_env)
888 site.addsitedir(virtual_env)
889
889
890 #-------------------------------------------------------------------------
890 #-------------------------------------------------------------------------
891 # Things related to injections into the sys module
891 # Things related to injections into the sys module
892 #-------------------------------------------------------------------------
892 #-------------------------------------------------------------------------
893
893
894 def save_sys_module_state(self):
894 def save_sys_module_state(self):
895 """Save the state of hooks in the sys module.
895 """Save the state of hooks in the sys module.
896
896
897 This has to be called after self.user_module is created.
897 This has to be called after self.user_module is created.
898 """
898 """
899 self._orig_sys_module_state = {'stdin': sys.stdin,
899 self._orig_sys_module_state = {'stdin': sys.stdin,
900 'stdout': sys.stdout,
900 'stdout': sys.stdout,
901 'stderr': sys.stderr,
901 'stderr': sys.stderr,
902 'excepthook': sys.excepthook}
902 'excepthook': sys.excepthook}
903 self._orig_sys_modules_main_name = self.user_module.__name__
903 self._orig_sys_modules_main_name = self.user_module.__name__
904 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
904 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
905
905
906 def restore_sys_module_state(self):
906 def restore_sys_module_state(self):
907 """Restore the state of the sys module."""
907 """Restore the state of the sys module."""
908 try:
908 try:
909 for k, v in self._orig_sys_module_state.items():
909 for k, v in self._orig_sys_module_state.items():
910 setattr(sys, k, v)
910 setattr(sys, k, v)
911 except AttributeError:
911 except AttributeError:
912 pass
912 pass
913 # Reset what what done in self.init_sys_modules
913 # Reset what what done in self.init_sys_modules
914 if self._orig_sys_modules_main_mod is not None:
914 if self._orig_sys_modules_main_mod is not None:
915 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
915 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
916
916
917 #-------------------------------------------------------------------------
917 #-------------------------------------------------------------------------
918 # Things related to the banner
918 # Things related to the banner
919 #-------------------------------------------------------------------------
919 #-------------------------------------------------------------------------
920
920
921 @property
921 @property
922 def banner(self):
922 def banner(self):
923 banner = self.banner1
923 banner = self.banner1
924 if self.profile and self.profile != 'default':
924 if self.profile and self.profile != 'default':
925 banner += '\nIPython profile: %s\n' % self.profile
925 banner += '\nIPython profile: %s\n' % self.profile
926 if self.banner2:
926 if self.banner2:
927 banner += '\n' + self.banner2
927 banner += '\n' + self.banner2
928 return banner
928 return banner
929
929
930 def show_banner(self, banner=None):
930 def show_banner(self, banner=None):
931 if banner is None:
931 if banner is None:
932 banner = self.banner
932 banner = self.banner
933 sys.stdout.write(banner)
933 sys.stdout.write(banner)
934
934
935 #-------------------------------------------------------------------------
935 #-------------------------------------------------------------------------
936 # Things related to hooks
936 # Things related to hooks
937 #-------------------------------------------------------------------------
937 #-------------------------------------------------------------------------
938
938
939 def init_hooks(self):
939 def init_hooks(self):
940 # hooks holds pointers used for user-side customizations
940 # hooks holds pointers used for user-side customizations
941 self.hooks = Struct()
941 self.hooks = Struct()
942
942
943 self.strdispatchers = {}
943 self.strdispatchers = {}
944
944
945 # Set all default hooks, defined in the IPython.hooks module.
945 # Set all default hooks, defined in the IPython.hooks module.
946 hooks = IPython.core.hooks
946 hooks = IPython.core.hooks
947 for hook_name in hooks.__all__:
947 for hook_name in hooks.__all__:
948 # default hooks have priority 100, i.e. low; user hooks should have
948 # default hooks have priority 100, i.e. low; user hooks should have
949 # 0-100 priority
949 # 0-100 priority
950 self.set_hook(hook_name, getattr(hooks, hook_name), 100)
950 self.set_hook(hook_name, getattr(hooks, hook_name), 100)
951
951
952 if self.display_page:
952 if self.display_page:
953 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
953 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
954
954
955 def set_hook(self, name, hook, priority=50, str_key=None, re_key=None):
955 def set_hook(self, name, hook, priority=50, str_key=None, re_key=None):
956 """set_hook(name,hook) -> sets an internal IPython hook.
956 """set_hook(name,hook) -> sets an internal IPython hook.
957
957
958 IPython exposes some of its internal API as user-modifiable hooks. By
958 IPython exposes some of its internal API as user-modifiable hooks. By
959 adding your function to one of these hooks, you can modify IPython's
959 adding your function to one of these hooks, you can modify IPython's
960 behavior to call at runtime your own routines."""
960 behavior to call at runtime your own routines."""
961
961
962 # At some point in the future, this should validate the hook before it
962 # At some point in the future, this should validate the hook before it
963 # accepts it. Probably at least check that the hook takes the number
963 # accepts it. Probably at least check that the hook takes the number
964 # of args it's supposed to.
964 # of args it's supposed to.
965
965
966 f = types.MethodType(hook,self)
966 f = types.MethodType(hook,self)
967
967
968 # check if the hook is for strdispatcher first
968 # check if the hook is for strdispatcher first
969 if str_key is not None:
969 if str_key is not None:
970 sdp = self.strdispatchers.get(name, StrDispatch())
970 sdp = self.strdispatchers.get(name, StrDispatch())
971 sdp.add_s(str_key, f, priority )
971 sdp.add_s(str_key, f, priority )
972 self.strdispatchers[name] = sdp
972 self.strdispatchers[name] = sdp
973 return
973 return
974 if re_key is not None:
974 if re_key is not None:
975 sdp = self.strdispatchers.get(name, StrDispatch())
975 sdp = self.strdispatchers.get(name, StrDispatch())
976 sdp.add_re(re.compile(re_key), f, priority )
976 sdp.add_re(re.compile(re_key), f, priority )
977 self.strdispatchers[name] = sdp
977 self.strdispatchers[name] = sdp
978 return
978 return
979
979
980 dp = getattr(self.hooks, name, None)
980 dp = getattr(self.hooks, name, None)
981 if name not in IPython.core.hooks.__all__:
981 if name not in IPython.core.hooks.__all__:
982 print("Warning! Hook '%s' is not one of %s" % \
982 print("Warning! Hook '%s' is not one of %s" % \
983 (name, IPython.core.hooks.__all__ ))
983 (name, IPython.core.hooks.__all__ ))
984
984
985 if name in IPython.core.hooks.deprecated:
985 if name in IPython.core.hooks.deprecated:
986 alternative = IPython.core.hooks.deprecated[name]
986 alternative = IPython.core.hooks.deprecated[name]
987 raise ValueError(
987 raise ValueError(
988 "Hook {} has been deprecated since IPython 5.0. Use {} instead.".format(
988 "Hook {} has been deprecated since IPython 5.0. Use {} instead.".format(
989 name, alternative
989 name, alternative
990 )
990 )
991 )
991 )
992
992
993 if not dp:
993 if not dp:
994 dp = IPython.core.hooks.CommandChainDispatcher()
994 dp = IPython.core.hooks.CommandChainDispatcher()
995
995
996 try:
996 try:
997 dp.add(f,priority)
997 dp.add(f,priority)
998 except AttributeError:
998 except AttributeError:
999 # it was not commandchain, plain old func - replace
999 # it was not commandchain, plain old func - replace
1000 dp = f
1000 dp = f
1001
1001
1002 setattr(self.hooks,name, dp)
1002 setattr(self.hooks,name, dp)
1003
1003
1004 #-------------------------------------------------------------------------
1004 #-------------------------------------------------------------------------
1005 # Things related to events
1005 # Things related to events
1006 #-------------------------------------------------------------------------
1006 #-------------------------------------------------------------------------
1007
1007
1008 def init_events(self):
1008 def init_events(self):
1009 self.events = EventManager(self, available_events)
1009 self.events = EventManager(self, available_events)
1010
1010
1011 self.events.register("pre_execute", self._clear_warning_registry)
1011 self.events.register("pre_execute", self._clear_warning_registry)
1012
1012
1013 def register_post_execute(self, func):
1013 def register_post_execute(self, func):
1014 """DEPRECATED: Use ip.events.register('post_run_cell', func)
1014 """DEPRECATED: Use ip.events.register('post_run_cell', func)
1015
1015
1016 Register a function for calling after code execution.
1016 Register a function for calling after code execution.
1017 """
1017 """
1018 raise ValueError(
1018 raise ValueError(
1019 "ip.register_post_execute is deprecated since IPython 1.0, use "
1019 "ip.register_post_execute is deprecated since IPython 1.0, use "
1020 "ip.events.register('post_run_cell', func) instead."
1020 "ip.events.register('post_run_cell', func) instead."
1021 )
1021 )
1022
1022
1023 def _clear_warning_registry(self):
1023 def _clear_warning_registry(self):
1024 # clear the warning registry, so that different code blocks with
1024 # clear the warning registry, so that different code blocks with
1025 # overlapping line number ranges don't cause spurious suppression of
1025 # overlapping line number ranges don't cause spurious suppression of
1026 # warnings (see gh-6611 for details)
1026 # warnings (see gh-6611 for details)
1027 if "__warningregistry__" in self.user_global_ns:
1027 if "__warningregistry__" in self.user_global_ns:
1028 del self.user_global_ns["__warningregistry__"]
1028 del self.user_global_ns["__warningregistry__"]
1029
1029
1030 #-------------------------------------------------------------------------
1030 #-------------------------------------------------------------------------
1031 # Things related to the "main" module
1031 # Things related to the "main" module
1032 #-------------------------------------------------------------------------
1032 #-------------------------------------------------------------------------
1033
1033
1034 def new_main_mod(self, filename, modname):
1034 def new_main_mod(self, filename, modname):
1035 """Return a new 'main' module object for user code execution.
1035 """Return a new 'main' module object for user code execution.
1036
1036
1037 ``filename`` should be the path of the script which will be run in the
1037 ``filename`` should be the path of the script which will be run in the
1038 module. Requests with the same filename will get the same module, with
1038 module. Requests with the same filename will get the same module, with
1039 its namespace cleared.
1039 its namespace cleared.
1040
1040
1041 ``modname`` should be the module name - normally either '__main__' or
1041 ``modname`` should be the module name - normally either '__main__' or
1042 the basename of the file without the extension.
1042 the basename of the file without the extension.
1043
1043
1044 When scripts are executed via %run, we must keep a reference to their
1044 When scripts are executed via %run, we must keep a reference to their
1045 __main__ module around so that Python doesn't
1045 __main__ module around so that Python doesn't
1046 clear it, rendering references to module globals useless.
1046 clear it, rendering references to module globals useless.
1047
1047
1048 This method keeps said reference in a private dict, keyed by the
1048 This method keeps said reference in a private dict, keyed by the
1049 absolute path of the script. This way, for multiple executions of the
1049 absolute path of the script. This way, for multiple executions of the
1050 same script we only keep one copy of the namespace (the last one),
1050 same script we only keep one copy of the namespace (the last one),
1051 thus preventing memory leaks from old references while allowing the
1051 thus preventing memory leaks from old references while allowing the
1052 objects from the last execution to be accessible.
1052 objects from the last execution to be accessible.
1053 """
1053 """
1054 filename = os.path.abspath(filename)
1054 filename = os.path.abspath(filename)
1055 try:
1055 try:
1056 main_mod = self._main_mod_cache[filename]
1056 main_mod = self._main_mod_cache[filename]
1057 except KeyError:
1057 except KeyError:
1058 main_mod = self._main_mod_cache[filename] = types.ModuleType(
1058 main_mod = self._main_mod_cache[filename] = types.ModuleType(
1059 modname,
1059 modname,
1060 doc="Module created for script run in IPython")
1060 doc="Module created for script run in IPython")
1061 else:
1061 else:
1062 main_mod.__dict__.clear()
1062 main_mod.__dict__.clear()
1063 main_mod.__name__ = modname
1063 main_mod.__name__ = modname
1064
1064
1065 main_mod.__file__ = filename
1065 main_mod.__file__ = filename
1066 # It seems pydoc (and perhaps others) needs any module instance to
1066 # It seems pydoc (and perhaps others) needs any module instance to
1067 # implement a __nonzero__ method
1067 # implement a __nonzero__ method
1068 main_mod.__nonzero__ = lambda : True
1068 main_mod.__nonzero__ = lambda : True
1069
1069
1070 return main_mod
1070 return main_mod
1071
1071
1072 def clear_main_mod_cache(self):
1072 def clear_main_mod_cache(self):
1073 """Clear the cache of main modules.
1073 """Clear the cache of main modules.
1074
1074
1075 Mainly for use by utilities like %reset.
1075 Mainly for use by utilities like %reset.
1076
1076
1077 Examples
1077 Examples
1078 --------
1078 --------
1079 In [15]: import IPython
1079 In [15]: import IPython
1080
1080
1081 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
1081 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
1082
1082
1083 In [17]: len(_ip._main_mod_cache) > 0
1083 In [17]: len(_ip._main_mod_cache) > 0
1084 Out[17]: True
1084 Out[17]: True
1085
1085
1086 In [18]: _ip.clear_main_mod_cache()
1086 In [18]: _ip.clear_main_mod_cache()
1087
1087
1088 In [19]: len(_ip._main_mod_cache) == 0
1088 In [19]: len(_ip._main_mod_cache) == 0
1089 Out[19]: True
1089 Out[19]: True
1090 """
1090 """
1091 self._main_mod_cache.clear()
1091 self._main_mod_cache.clear()
1092
1092
1093 #-------------------------------------------------------------------------
1093 #-------------------------------------------------------------------------
1094 # Things related to debugging
1094 # Things related to debugging
1095 #-------------------------------------------------------------------------
1095 #-------------------------------------------------------------------------
1096
1096
1097 def init_pdb(self):
1097 def init_pdb(self):
1098 # Set calling of pdb on exceptions
1098 # Set calling of pdb on exceptions
1099 # self.call_pdb is a property
1099 # self.call_pdb is a property
1100 self.call_pdb = self.pdb
1100 self.call_pdb = self.pdb
1101
1101
1102 def _get_call_pdb(self):
1102 def _get_call_pdb(self):
1103 return self._call_pdb
1103 return self._call_pdb
1104
1104
1105 def _set_call_pdb(self,val):
1105 def _set_call_pdb(self,val):
1106
1106
1107 if val not in (0,1,False,True):
1107 if val not in (0,1,False,True):
1108 raise ValueError('new call_pdb value must be boolean')
1108 raise ValueError('new call_pdb value must be boolean')
1109
1109
1110 # store value in instance
1110 # store value in instance
1111 self._call_pdb = val
1111 self._call_pdb = val
1112
1112
1113 # notify the actual exception handlers
1113 # notify the actual exception handlers
1114 self.InteractiveTB.call_pdb = val
1114 self.InteractiveTB.call_pdb = val
1115
1115
1116 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1116 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1117 'Control auto-activation of pdb at exceptions')
1117 'Control auto-activation of pdb at exceptions')
1118
1118
1119 def debugger(self,force=False):
1119 def debugger(self,force=False):
1120 """Call the pdb debugger.
1120 """Call the pdb debugger.
1121
1121
1122 Keywords:
1122 Keywords:
1123
1123
1124 - force(False): by default, this routine checks the instance call_pdb
1124 - force(False): by default, this routine checks the instance call_pdb
1125 flag and does not actually invoke the debugger if the flag is false.
1125 flag and does not actually invoke the debugger if the flag is false.
1126 The 'force' option forces the debugger to activate even if the flag
1126 The 'force' option forces the debugger to activate even if the flag
1127 is false.
1127 is false.
1128 """
1128 """
1129
1129
1130 if not (force or self.call_pdb):
1130 if not (force or self.call_pdb):
1131 return
1131 return
1132
1132
1133 if not hasattr(sys,'last_traceback'):
1133 if not hasattr(sys,'last_traceback'):
1134 error('No traceback has been produced, nothing to debug.')
1134 error('No traceback has been produced, nothing to debug.')
1135 return
1135 return
1136
1136
1137 self.InteractiveTB.debugger(force=True)
1137 self.InteractiveTB.debugger(force=True)
1138
1138
1139 #-------------------------------------------------------------------------
1139 #-------------------------------------------------------------------------
1140 # Things related to IPython's various namespaces
1140 # Things related to IPython's various namespaces
1141 #-------------------------------------------------------------------------
1141 #-------------------------------------------------------------------------
1142 default_user_namespaces = True
1142 default_user_namespaces = True
1143
1143
1144 def init_create_namespaces(self, user_module=None, user_ns=None):
1144 def init_create_namespaces(self, user_module=None, user_ns=None):
1145 # Create the namespace where the user will operate. user_ns is
1145 # Create the namespace where the user will operate. user_ns is
1146 # normally the only one used, and it is passed to the exec calls as
1146 # normally the only one used, and it is passed to the exec calls as
1147 # the locals argument. But we do carry a user_global_ns namespace
1147 # the locals argument. But we do carry a user_global_ns namespace
1148 # given as the exec 'globals' argument, This is useful in embedding
1148 # given as the exec 'globals' argument, This is useful in embedding
1149 # situations where the ipython shell opens in a context where the
1149 # situations where the ipython shell opens in a context where the
1150 # distinction between locals and globals is meaningful. For
1150 # distinction between locals and globals is meaningful. For
1151 # non-embedded contexts, it is just the same object as the user_ns dict.
1151 # non-embedded contexts, it is just the same object as the user_ns dict.
1152
1152
1153 # FIXME. For some strange reason, __builtins__ is showing up at user
1153 # FIXME. For some strange reason, __builtins__ is showing up at user
1154 # level as a dict instead of a module. This is a manual fix, but I
1154 # level as a dict instead of a module. This is a manual fix, but I
1155 # should really track down where the problem is coming from. Alex
1155 # should really track down where the problem is coming from. Alex
1156 # Schmolck reported this problem first.
1156 # Schmolck reported this problem first.
1157
1157
1158 # A useful post by Alex Martelli on this topic:
1158 # A useful post by Alex Martelli on this topic:
1159 # Re: inconsistent value from __builtins__
1159 # Re: inconsistent value from __builtins__
1160 # Von: Alex Martelli <aleaxit@yahoo.com>
1160 # Von: Alex Martelli <aleaxit@yahoo.com>
1161 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1161 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1162 # Gruppen: comp.lang.python
1162 # Gruppen: comp.lang.python
1163
1163
1164 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1164 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1165 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1165 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1166 # > <type 'dict'>
1166 # > <type 'dict'>
1167 # > >>> print type(__builtins__)
1167 # > >>> print type(__builtins__)
1168 # > <type 'module'>
1168 # > <type 'module'>
1169 # > Is this difference in return value intentional?
1169 # > Is this difference in return value intentional?
1170
1170
1171 # Well, it's documented that '__builtins__' can be either a dictionary
1171 # Well, it's documented that '__builtins__' can be either a dictionary
1172 # or a module, and it's been that way for a long time. Whether it's
1172 # or a module, and it's been that way for a long time. Whether it's
1173 # intentional (or sensible), I don't know. In any case, the idea is
1173 # intentional (or sensible), I don't know. In any case, the idea is
1174 # that if you need to access the built-in namespace directly, you
1174 # that if you need to access the built-in namespace directly, you
1175 # should start with "import __builtin__" (note, no 's') which will
1175 # should start with "import __builtin__" (note, no 's') which will
1176 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1176 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1177
1177
1178 # These routines return a properly built module and dict as needed by
1178 # These routines return a properly built module and dict as needed by
1179 # the rest of the code, and can also be used by extension writers to
1179 # the rest of the code, and can also be used by extension writers to
1180 # generate properly initialized namespaces.
1180 # generate properly initialized namespaces.
1181 if (user_ns is not None) or (user_module is not None):
1181 if (user_ns is not None) or (user_module is not None):
1182 self.default_user_namespaces = False
1182 self.default_user_namespaces = False
1183 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1183 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1184
1184
1185 # A record of hidden variables we have added to the user namespace, so
1185 # A record of hidden variables we have added to the user namespace, so
1186 # we can list later only variables defined in actual interactive use.
1186 # we can list later only variables defined in actual interactive use.
1187 self.user_ns_hidden = {}
1187 self.user_ns_hidden = {}
1188
1188
1189 # Now that FakeModule produces a real module, we've run into a nasty
1189 # Now that FakeModule produces a real module, we've run into a nasty
1190 # problem: after script execution (via %run), the module where the user
1190 # problem: after script execution (via %run), the module where the user
1191 # code ran is deleted. Now that this object is a true module (needed
1191 # code ran is deleted. Now that this object is a true module (needed
1192 # so doctest and other tools work correctly), the Python module
1192 # so doctest and other tools work correctly), the Python module
1193 # teardown mechanism runs over it, and sets to None every variable
1193 # teardown mechanism runs over it, and sets to None every variable
1194 # present in that module. Top-level references to objects from the
1194 # present in that module. Top-level references to objects from the
1195 # script survive, because the user_ns is updated with them. However,
1195 # script survive, because the user_ns is updated with them. However,
1196 # calling functions defined in the script that use other things from
1196 # calling functions defined in the script that use other things from
1197 # the script will fail, because the function's closure had references
1197 # the script will fail, because the function's closure had references
1198 # to the original objects, which are now all None. So we must protect
1198 # to the original objects, which are now all None. So we must protect
1199 # these modules from deletion by keeping a cache.
1199 # these modules from deletion by keeping a cache.
1200 #
1200 #
1201 # To avoid keeping stale modules around (we only need the one from the
1201 # To avoid keeping stale modules around (we only need the one from the
1202 # last run), we use a dict keyed with the full path to the script, so
1202 # last run), we use a dict keyed with the full path to the script, so
1203 # only the last version of the module is held in the cache. Note,
1203 # only the last version of the module is held in the cache. Note,
1204 # however, that we must cache the module *namespace contents* (their
1204 # however, that we must cache the module *namespace contents* (their
1205 # __dict__). Because if we try to cache the actual modules, old ones
1205 # __dict__). Because if we try to cache the actual modules, old ones
1206 # (uncached) could be destroyed while still holding references (such as
1206 # (uncached) could be destroyed while still holding references (such as
1207 # those held by GUI objects that tend to be long-lived)>
1207 # those held by GUI objects that tend to be long-lived)>
1208 #
1208 #
1209 # The %reset command will flush this cache. See the cache_main_mod()
1209 # The %reset command will flush this cache. See the cache_main_mod()
1210 # and clear_main_mod_cache() methods for details on use.
1210 # and clear_main_mod_cache() methods for details on use.
1211
1211
1212 # This is the cache used for 'main' namespaces
1212 # This is the cache used for 'main' namespaces
1213 self._main_mod_cache = {}
1213 self._main_mod_cache = {}
1214
1214
1215 # A table holding all the namespaces IPython deals with, so that
1215 # A table holding all the namespaces IPython deals with, so that
1216 # introspection facilities can search easily.
1216 # introspection facilities can search easily.
1217 self.ns_table = {'user_global':self.user_module.__dict__,
1217 self.ns_table = {'user_global':self.user_module.__dict__,
1218 'user_local':self.user_ns,
1218 'user_local':self.user_ns,
1219 'builtin':builtin_mod.__dict__
1219 'builtin':builtin_mod.__dict__
1220 }
1220 }
1221
1221
1222 @property
1222 @property
1223 def user_global_ns(self):
1223 def user_global_ns(self):
1224 return self.user_module.__dict__
1224 return self.user_module.__dict__
1225
1225
1226 def prepare_user_module(self, user_module=None, user_ns=None):
1226 def prepare_user_module(self, user_module=None, user_ns=None):
1227 """Prepare the module and namespace in which user code will be run.
1227 """Prepare the module and namespace in which user code will be run.
1228
1228
1229 When IPython is started normally, both parameters are None: a new module
1229 When IPython is started normally, both parameters are None: a new module
1230 is created automatically, and its __dict__ used as the namespace.
1230 is created automatically, and its __dict__ used as the namespace.
1231
1231
1232 If only user_module is provided, its __dict__ is used as the namespace.
1232 If only user_module is provided, its __dict__ is used as the namespace.
1233 If only user_ns is provided, a dummy module is created, and user_ns
1233 If only user_ns is provided, a dummy module is created, and user_ns
1234 becomes the global namespace. If both are provided (as they may be
1234 becomes the global namespace. If both are provided (as they may be
1235 when embedding), user_ns is the local namespace, and user_module
1235 when embedding), user_ns is the local namespace, and user_module
1236 provides the global namespace.
1236 provides the global namespace.
1237
1237
1238 Parameters
1238 Parameters
1239 ----------
1239 ----------
1240 user_module : module, optional
1240 user_module : module, optional
1241 The current user module in which IPython is being run. If None,
1241 The current user module in which IPython is being run. If None,
1242 a clean module will be created.
1242 a clean module will be created.
1243 user_ns : dict, optional
1243 user_ns : dict, optional
1244 A namespace in which to run interactive commands.
1244 A namespace in which to run interactive commands.
1245
1245
1246 Returns
1246 Returns
1247 -------
1247 -------
1248 A tuple of user_module and user_ns, each properly initialised.
1248 A tuple of user_module and user_ns, each properly initialised.
1249 """
1249 """
1250 if user_module is None and user_ns is not None:
1250 if user_module is None and user_ns is not None:
1251 user_ns.setdefault("__name__", "__main__")
1251 user_ns.setdefault("__name__", "__main__")
1252 user_module = DummyMod()
1252 user_module = DummyMod()
1253 user_module.__dict__ = user_ns
1253 user_module.__dict__ = user_ns
1254
1254
1255 if user_module is None:
1255 if user_module is None:
1256 user_module = types.ModuleType("__main__",
1256 user_module = types.ModuleType("__main__",
1257 doc="Automatically created module for IPython interactive environment")
1257 doc="Automatically created module for IPython interactive environment")
1258
1258
1259 # We must ensure that __builtin__ (without the final 's') is always
1259 # We must ensure that __builtin__ (without the final 's') is always
1260 # available and pointing to the __builtin__ *module*. For more details:
1260 # available and pointing to the __builtin__ *module*. For more details:
1261 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1261 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1262 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1262 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1263 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1263 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1264
1264
1265 if user_ns is None:
1265 if user_ns is None:
1266 user_ns = user_module.__dict__
1266 user_ns = user_module.__dict__
1267
1267
1268 return user_module, user_ns
1268 return user_module, user_ns
1269
1269
1270 def init_sys_modules(self):
1270 def init_sys_modules(self):
1271 # We need to insert into sys.modules something that looks like a
1271 # We need to insert into sys.modules something that looks like a
1272 # module but which accesses the IPython namespace, for shelve and
1272 # module but which accesses the IPython namespace, for shelve and
1273 # pickle to work interactively. Normally they rely on getting
1273 # pickle to work interactively. Normally they rely on getting
1274 # everything out of __main__, but for embedding purposes each IPython
1274 # everything out of __main__, but for embedding purposes each IPython
1275 # instance has its own private namespace, so we can't go shoving
1275 # instance has its own private namespace, so we can't go shoving
1276 # everything into __main__.
1276 # everything into __main__.
1277
1277
1278 # note, however, that we should only do this for non-embedded
1278 # note, however, that we should only do this for non-embedded
1279 # ipythons, which really mimic the __main__.__dict__ with their own
1279 # ipythons, which really mimic the __main__.__dict__ with their own
1280 # namespace. Embedded instances, on the other hand, should not do
1280 # namespace. Embedded instances, on the other hand, should not do
1281 # this because they need to manage the user local/global namespaces
1281 # this because they need to manage the user local/global namespaces
1282 # only, but they live within a 'normal' __main__ (meaning, they
1282 # only, but they live within a 'normal' __main__ (meaning, they
1283 # shouldn't overtake the execution environment of the script they're
1283 # shouldn't overtake the execution environment of the script they're
1284 # embedded in).
1284 # embedded in).
1285
1285
1286 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1286 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1287 main_name = self.user_module.__name__
1287 main_name = self.user_module.__name__
1288 sys.modules[main_name] = self.user_module
1288 sys.modules[main_name] = self.user_module
1289
1289
1290 def init_user_ns(self):
1290 def init_user_ns(self):
1291 """Initialize all user-visible namespaces to their minimum defaults.
1291 """Initialize all user-visible namespaces to their minimum defaults.
1292
1292
1293 Certain history lists are also initialized here, as they effectively
1293 Certain history lists are also initialized here, as they effectively
1294 act as user namespaces.
1294 act as user namespaces.
1295
1295
1296 Notes
1296 Notes
1297 -----
1297 -----
1298 All data structures here are only filled in, they are NOT reset by this
1298 All data structures here are only filled in, they are NOT reset by this
1299 method. If they were not empty before, data will simply be added to
1299 method. If they were not empty before, data will simply be added to
1300 them.
1300 them.
1301 """
1301 """
1302 # This function works in two parts: first we put a few things in
1302 # This function works in two parts: first we put a few things in
1303 # user_ns, and we sync that contents into user_ns_hidden so that these
1303 # user_ns, and we sync that contents into user_ns_hidden so that these
1304 # initial variables aren't shown by %who. After the sync, we add the
1304 # initial variables aren't shown by %who. After the sync, we add the
1305 # rest of what we *do* want the user to see with %who even on a new
1305 # rest of what we *do* want the user to see with %who even on a new
1306 # session (probably nothing, so they really only see their own stuff)
1306 # session (probably nothing, so they really only see their own stuff)
1307
1307
1308 # The user dict must *always* have a __builtin__ reference to the
1308 # The user dict must *always* have a __builtin__ reference to the
1309 # Python standard __builtin__ namespace, which must be imported.
1309 # Python standard __builtin__ namespace, which must be imported.
1310 # This is so that certain operations in prompt evaluation can be
1310 # This is so that certain operations in prompt evaluation can be
1311 # reliably executed with builtins. Note that we can NOT use
1311 # reliably executed with builtins. Note that we can NOT use
1312 # __builtins__ (note the 's'), because that can either be a dict or a
1312 # __builtins__ (note the 's'), because that can either be a dict or a
1313 # module, and can even mutate at runtime, depending on the context
1313 # module, and can even mutate at runtime, depending on the context
1314 # (Python makes no guarantees on it). In contrast, __builtin__ is
1314 # (Python makes no guarantees on it). In contrast, __builtin__ is
1315 # always a module object, though it must be explicitly imported.
1315 # always a module object, though it must be explicitly imported.
1316
1316
1317 # For more details:
1317 # For more details:
1318 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1318 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1319 ns = {}
1319 ns = {}
1320
1320
1321 # make global variables for user access to the histories
1321 # make global variables for user access to the histories
1322 ns['_ih'] = self.history_manager.input_hist_parsed
1322 ns['_ih'] = self.history_manager.input_hist_parsed
1323 ns['_oh'] = self.history_manager.output_hist
1323 ns['_oh'] = self.history_manager.output_hist
1324 ns['_dh'] = self.history_manager.dir_hist
1324 ns['_dh'] = self.history_manager.dir_hist
1325
1325
1326 # user aliases to input and output histories. These shouldn't show up
1326 # user aliases to input and output histories. These shouldn't show up
1327 # in %who, as they can have very large reprs.
1327 # in %who, as they can have very large reprs.
1328 ns['In'] = self.history_manager.input_hist_parsed
1328 ns['In'] = self.history_manager.input_hist_parsed
1329 ns['Out'] = self.history_manager.output_hist
1329 ns['Out'] = self.history_manager.output_hist
1330
1330
1331 # Store myself as the public api!!!
1331 # Store myself as the public api!!!
1332 ns['get_ipython'] = self.get_ipython
1332 ns['get_ipython'] = self.get_ipython
1333
1333
1334 ns['exit'] = self.exiter
1334 ns['exit'] = self.exiter
1335 ns['quit'] = self.exiter
1335 ns['quit'] = self.exiter
1336 ns["open"] = _modified_open
1336 ns["open"] = _modified_open
1337
1337
1338 # Sync what we've added so far to user_ns_hidden so these aren't seen
1338 # Sync what we've added so far to user_ns_hidden so these aren't seen
1339 # by %who
1339 # by %who
1340 self.user_ns_hidden.update(ns)
1340 self.user_ns_hidden.update(ns)
1341
1341
1342 # Anything put into ns now would show up in %who. Think twice before
1342 # Anything put into ns now would show up in %who. Think twice before
1343 # putting anything here, as we really want %who to show the user their
1343 # putting anything here, as we really want %who to show the user their
1344 # stuff, not our variables.
1344 # stuff, not our variables.
1345
1345
1346 # Finally, update the real user's namespace
1346 # Finally, update the real user's namespace
1347 self.user_ns.update(ns)
1347 self.user_ns.update(ns)
1348
1348
1349 @property
1349 @property
1350 def all_ns_refs(self):
1350 def all_ns_refs(self):
1351 """Get a list of references to all the namespace dictionaries in which
1351 """Get a list of references to all the namespace dictionaries in which
1352 IPython might store a user-created object.
1352 IPython might store a user-created object.
1353
1353
1354 Note that this does not include the displayhook, which also caches
1354 Note that this does not include the displayhook, which also caches
1355 objects from the output."""
1355 objects from the output."""
1356 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1356 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1357 [m.__dict__ for m in self._main_mod_cache.values()]
1357 [m.__dict__ for m in self._main_mod_cache.values()]
1358
1358
1359 def reset(self, new_session=True, aggressive=False):
1359 def reset(self, new_session=True, aggressive=False):
1360 """Clear all internal namespaces, and attempt to release references to
1360 """Clear all internal namespaces, and attempt to release references to
1361 user objects.
1361 user objects.
1362
1362
1363 If new_session is True, a new history session will be opened.
1363 If new_session is True, a new history session will be opened.
1364 """
1364 """
1365 # Clear histories
1365 # Clear histories
1366 self.history_manager.reset(new_session)
1366 self.history_manager.reset(new_session)
1367 # Reset counter used to index all histories
1367 # Reset counter used to index all histories
1368 if new_session:
1368 if new_session:
1369 self.execution_count = 1
1369 self.execution_count = 1
1370
1370
1371 # Reset last execution result
1371 # Reset last execution result
1372 self.last_execution_succeeded = True
1372 self.last_execution_succeeded = True
1373 self.last_execution_result = None
1373 self.last_execution_result = None
1374
1374
1375 # Flush cached output items
1375 # Flush cached output items
1376 if self.displayhook.do_full_cache:
1376 if self.displayhook.do_full_cache:
1377 self.displayhook.flush()
1377 self.displayhook.flush()
1378
1378
1379 # The main execution namespaces must be cleared very carefully,
1379 # The main execution namespaces must be cleared very carefully,
1380 # skipping the deletion of the builtin-related keys, because doing so
1380 # skipping the deletion of the builtin-related keys, because doing so
1381 # would cause errors in many object's __del__ methods.
1381 # would cause errors in many object's __del__ methods.
1382 if self.user_ns is not self.user_global_ns:
1382 if self.user_ns is not self.user_global_ns:
1383 self.user_ns.clear()
1383 self.user_ns.clear()
1384 ns = self.user_global_ns
1384 ns = self.user_global_ns
1385 drop_keys = set(ns.keys())
1385 drop_keys = set(ns.keys())
1386 drop_keys.discard('__builtin__')
1386 drop_keys.discard('__builtin__')
1387 drop_keys.discard('__builtins__')
1387 drop_keys.discard('__builtins__')
1388 drop_keys.discard('__name__')
1388 drop_keys.discard('__name__')
1389 for k in drop_keys:
1389 for k in drop_keys:
1390 del ns[k]
1390 del ns[k]
1391
1391
1392 self.user_ns_hidden.clear()
1392 self.user_ns_hidden.clear()
1393
1393
1394 # Restore the user namespaces to minimal usability
1394 # Restore the user namespaces to minimal usability
1395 self.init_user_ns()
1395 self.init_user_ns()
1396 if aggressive and not hasattr(self, "_sys_modules_keys"):
1396 if aggressive and not hasattr(self, "_sys_modules_keys"):
1397 print("Cannot restore sys.module, no snapshot")
1397 print("Cannot restore sys.module, no snapshot")
1398 elif aggressive:
1398 elif aggressive:
1399 print("culling sys module...")
1399 print("culling sys module...")
1400 current_keys = set(sys.modules.keys())
1400 current_keys = set(sys.modules.keys())
1401 for k in current_keys - self._sys_modules_keys:
1401 for k in current_keys - self._sys_modules_keys:
1402 if k.startswith("multiprocessing"):
1402 if k.startswith("multiprocessing"):
1403 continue
1403 continue
1404 del sys.modules[k]
1404 del sys.modules[k]
1405
1405
1406 # Restore the default and user aliases
1406 # Restore the default and user aliases
1407 self.alias_manager.clear_aliases()
1407 self.alias_manager.clear_aliases()
1408 self.alias_manager.init_aliases()
1408 self.alias_manager.init_aliases()
1409
1409
1410 # Now define aliases that only make sense on the terminal, because they
1410 # Now define aliases that only make sense on the terminal, because they
1411 # need direct access to the console in a way that we can't emulate in
1411 # need direct access to the console in a way that we can't emulate in
1412 # GUI or web frontend
1412 # GUI or web frontend
1413 if os.name == 'posix':
1413 if os.name == 'posix':
1414 for cmd in ('clear', 'more', 'less', 'man'):
1414 for cmd in ('clear', 'more', 'less', 'man'):
1415 if cmd not in self.magics_manager.magics['line']:
1415 if cmd not in self.magics_manager.magics['line']:
1416 self.alias_manager.soft_define_alias(cmd, cmd)
1416 self.alias_manager.soft_define_alias(cmd, cmd)
1417
1417
1418 # Flush the private list of module references kept for script
1418 # Flush the private list of module references kept for script
1419 # execution protection
1419 # execution protection
1420 self.clear_main_mod_cache()
1420 self.clear_main_mod_cache()
1421
1421
1422 def del_var(self, varname, by_name=False):
1422 def del_var(self, varname, by_name=False):
1423 """Delete a variable from the various namespaces, so that, as
1423 """Delete a variable from the various namespaces, so that, as
1424 far as possible, we're not keeping any hidden references to it.
1424 far as possible, we're not keeping any hidden references to it.
1425
1425
1426 Parameters
1426 Parameters
1427 ----------
1427 ----------
1428 varname : str
1428 varname : str
1429 The name of the variable to delete.
1429 The name of the variable to delete.
1430 by_name : bool
1430 by_name : bool
1431 If True, delete variables with the given name in each
1431 If True, delete variables with the given name in each
1432 namespace. If False (default), find the variable in the user
1432 namespace. If False (default), find the variable in the user
1433 namespace, and delete references to it.
1433 namespace, and delete references to it.
1434 """
1434 """
1435 if varname in ('__builtin__', '__builtins__'):
1435 if varname in ('__builtin__', '__builtins__'):
1436 raise ValueError("Refusing to delete %s" % varname)
1436 raise ValueError("Refusing to delete %s" % varname)
1437
1437
1438 ns_refs = self.all_ns_refs
1438 ns_refs = self.all_ns_refs
1439
1439
1440 if by_name: # Delete by name
1440 if by_name: # Delete by name
1441 for ns in ns_refs:
1441 for ns in ns_refs:
1442 try:
1442 try:
1443 del ns[varname]
1443 del ns[varname]
1444 except KeyError:
1444 except KeyError:
1445 pass
1445 pass
1446 else: # Delete by object
1446 else: # Delete by object
1447 try:
1447 try:
1448 obj = self.user_ns[varname]
1448 obj = self.user_ns[varname]
1449 except KeyError as e:
1449 except KeyError as e:
1450 raise NameError("name '%s' is not defined" % varname) from e
1450 raise NameError("name '%s' is not defined" % varname) from e
1451 # Also check in output history
1451 # Also check in output history
1452 ns_refs.append(self.history_manager.output_hist)
1452 ns_refs.append(self.history_manager.output_hist)
1453 for ns in ns_refs:
1453 for ns in ns_refs:
1454 to_delete = [n for n, o in ns.items() if o is obj]
1454 to_delete = [n for n, o in ns.items() if o is obj]
1455 for name in to_delete:
1455 for name in to_delete:
1456 del ns[name]
1456 del ns[name]
1457
1457
1458 # Ensure it is removed from the last execution result
1458 # Ensure it is removed from the last execution result
1459 if self.last_execution_result.result is obj:
1459 if self.last_execution_result.result is obj:
1460 self.last_execution_result = None
1460 self.last_execution_result = None
1461
1461
1462 # displayhook keeps extra references, but not in a dictionary
1462 # displayhook keeps extra references, but not in a dictionary
1463 for name in ('_', '__', '___'):
1463 for name in ('_', '__', '___'):
1464 if getattr(self.displayhook, name) is obj:
1464 if getattr(self.displayhook, name) is obj:
1465 setattr(self.displayhook, name, None)
1465 setattr(self.displayhook, name, None)
1466
1466
1467 def reset_selective(self, regex=None):
1467 def reset_selective(self, regex=None):
1468 """Clear selective variables from internal namespaces based on a
1468 """Clear selective variables from internal namespaces based on a
1469 specified regular expression.
1469 specified regular expression.
1470
1470
1471 Parameters
1471 Parameters
1472 ----------
1472 ----------
1473 regex : string or compiled pattern, optional
1473 regex : string or compiled pattern, optional
1474 A regular expression pattern that will be used in searching
1474 A regular expression pattern that will be used in searching
1475 variable names in the users namespaces.
1475 variable names in the users namespaces.
1476 """
1476 """
1477 if regex is not None:
1477 if regex is not None:
1478 try:
1478 try:
1479 m = re.compile(regex)
1479 m = re.compile(regex)
1480 except TypeError as e:
1480 except TypeError as e:
1481 raise TypeError('regex must be a string or compiled pattern') from e
1481 raise TypeError('regex must be a string or compiled pattern') from e
1482 # Search for keys in each namespace that match the given regex
1482 # Search for keys in each namespace that match the given regex
1483 # If a match is found, delete the key/value pair.
1483 # If a match is found, delete the key/value pair.
1484 for ns in self.all_ns_refs:
1484 for ns in self.all_ns_refs:
1485 for var in ns:
1485 for var in ns:
1486 if m.search(var):
1486 if m.search(var):
1487 del ns[var]
1487 del ns[var]
1488
1488
1489 def push(self, variables, interactive=True):
1489 def push(self, variables, interactive=True):
1490 """Inject a group of variables into the IPython user namespace.
1490 """Inject a group of variables into the IPython user namespace.
1491
1491
1492 Parameters
1492 Parameters
1493 ----------
1493 ----------
1494 variables : dict, str or list/tuple of str
1494 variables : dict, str or list/tuple of str
1495 The variables to inject into the user's namespace. If a dict, a
1495 The variables to inject into the user's namespace. If a dict, a
1496 simple update is done. If a str, the string is assumed to have
1496 simple update is done. If a str, the string is assumed to have
1497 variable names separated by spaces. A list/tuple of str can also
1497 variable names separated by spaces. A list/tuple of str can also
1498 be used to give the variable names. If just the variable names are
1498 be used to give the variable names. If just the variable names are
1499 give (list/tuple/str) then the variable values looked up in the
1499 give (list/tuple/str) then the variable values looked up in the
1500 callers frame.
1500 callers frame.
1501 interactive : bool
1501 interactive : bool
1502 If True (default), the variables will be listed with the ``who``
1502 If True (default), the variables will be listed with the ``who``
1503 magic.
1503 magic.
1504 """
1504 """
1505 vdict = None
1505 vdict = None
1506
1506
1507 # We need a dict of name/value pairs to do namespace updates.
1507 # We need a dict of name/value pairs to do namespace updates.
1508 if isinstance(variables, dict):
1508 if isinstance(variables, dict):
1509 vdict = variables
1509 vdict = variables
1510 elif isinstance(variables, (str, list, tuple)):
1510 elif isinstance(variables, (str, list, tuple)):
1511 if isinstance(variables, str):
1511 if isinstance(variables, str):
1512 vlist = variables.split()
1512 vlist = variables.split()
1513 else:
1513 else:
1514 vlist = variables
1514 vlist = variables
1515 vdict = {}
1515 vdict = {}
1516 cf = sys._getframe(1)
1516 cf = sys._getframe(1)
1517 for name in vlist:
1517 for name in vlist:
1518 try:
1518 try:
1519 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1519 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1520 except:
1520 except:
1521 print('Could not get variable %s from %s' %
1521 print('Could not get variable %s from %s' %
1522 (name,cf.f_code.co_name))
1522 (name,cf.f_code.co_name))
1523 else:
1523 else:
1524 raise ValueError('variables must be a dict/str/list/tuple')
1524 raise ValueError('variables must be a dict/str/list/tuple')
1525
1525
1526 # Propagate variables to user namespace
1526 # Propagate variables to user namespace
1527 self.user_ns.update(vdict)
1527 self.user_ns.update(vdict)
1528
1528
1529 # And configure interactive visibility
1529 # And configure interactive visibility
1530 user_ns_hidden = self.user_ns_hidden
1530 user_ns_hidden = self.user_ns_hidden
1531 if interactive:
1531 if interactive:
1532 for name in vdict:
1532 for name in vdict:
1533 user_ns_hidden.pop(name, None)
1533 user_ns_hidden.pop(name, None)
1534 else:
1534 else:
1535 user_ns_hidden.update(vdict)
1535 user_ns_hidden.update(vdict)
1536
1536
1537 def drop_by_id(self, variables):
1537 def drop_by_id(self, variables):
1538 """Remove a dict of variables from the user namespace, if they are the
1538 """Remove a dict of variables from the user namespace, if they are the
1539 same as the values in the dictionary.
1539 same as the values in the dictionary.
1540
1540
1541 This is intended for use by extensions: variables that they've added can
1541 This is intended for use by extensions: variables that they've added can
1542 be taken back out if they are unloaded, without removing any that the
1542 be taken back out if they are unloaded, without removing any that the
1543 user has overwritten.
1543 user has overwritten.
1544
1544
1545 Parameters
1545 Parameters
1546 ----------
1546 ----------
1547 variables : dict
1547 variables : dict
1548 A dictionary mapping object names (as strings) to the objects.
1548 A dictionary mapping object names (as strings) to the objects.
1549 """
1549 """
1550 for name, obj in variables.items():
1550 for name, obj in variables.items():
1551 if name in self.user_ns and self.user_ns[name] is obj:
1551 if name in self.user_ns and self.user_ns[name] is obj:
1552 del self.user_ns[name]
1552 del self.user_ns[name]
1553 self.user_ns_hidden.pop(name, None)
1553 self.user_ns_hidden.pop(name, None)
1554
1554
1555 #-------------------------------------------------------------------------
1555 #-------------------------------------------------------------------------
1556 # Things related to object introspection
1556 # Things related to object introspection
1557 #-------------------------------------------------------------------------
1557 #-------------------------------------------------------------------------
1558
1558
1559 def _ofind(self, oname, namespaces=None):
1559 def _ofind(self, oname, namespaces=None):
1560 """Find an object in the available namespaces.
1560 """Find an object in the available namespaces.
1561
1561
1562 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1562 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1563
1563
1564 Has special code to detect magic functions.
1564 Has special code to detect magic functions.
1565 """
1565 """
1566 oname = oname.strip()
1566 oname = oname.strip()
1567 raw_parts = oname.split(".")
1567 raw_parts = oname.split(".")
1568 parts = []
1568 parts = []
1569 parts_ok = True
1569 parts_ok = True
1570 for p in raw_parts:
1570 for p in raw_parts:
1571 if p.endswith("]"):
1571 if p.endswith("]"):
1572 var, *indices = p.split("[")
1572 var, *indices = p.split("[")
1573 if not var.isidentifier():
1573 if not var.isidentifier():
1574 parts_ok = False
1574 parts_ok = False
1575 break
1575 break
1576 parts.append(var)
1576 parts.append(var)
1577 for ind in indices:
1577 for ind in indices:
1578 if ind[-1] != "]" and not is_integer_string(ind[:-1]):
1578 if ind[-1] != "]" and not is_integer_string(ind[:-1]):
1579 parts_ok = False
1579 parts_ok = False
1580 break
1580 break
1581 parts.append(ind[:-1])
1581 parts.append(ind[:-1])
1582 continue
1582 continue
1583
1583
1584 if not p.isidentifier():
1584 if not p.isidentifier():
1585 parts_ok = False
1585 parts_ok = False
1586 parts.append(p)
1586 parts.append(p)
1587
1587
1588 if (
1588 if (
1589 not oname.startswith(ESC_MAGIC)
1589 not oname.startswith(ESC_MAGIC)
1590 and not oname.startswith(ESC_MAGIC2)
1590 and not oname.startswith(ESC_MAGIC2)
1591 and not parts_ok
1591 and not parts_ok
1592 ):
1592 ):
1593 return {"found": False}
1593 return {"found": False}
1594
1594
1595 if namespaces is None:
1595 if namespaces is None:
1596 # Namespaces to search in:
1596 # Namespaces to search in:
1597 # Put them in a list. The order is important so that we
1597 # Put them in a list. The order is important so that we
1598 # find things in the same order that Python finds them.
1598 # find things in the same order that Python finds them.
1599 namespaces = [ ('Interactive', self.user_ns),
1599 namespaces = [ ('Interactive', self.user_ns),
1600 ('Interactive (global)', self.user_global_ns),
1600 ('Interactive (global)', self.user_global_ns),
1601 ('Python builtin', builtin_mod.__dict__),
1601 ('Python builtin', builtin_mod.__dict__),
1602 ]
1602 ]
1603
1603
1604 ismagic = False
1604 ismagic = False
1605 isalias = False
1605 isalias = False
1606 found = False
1606 found = False
1607 ospace = None
1607 ospace = None
1608 parent = None
1608 parent = None
1609 obj = None
1609 obj = None
1610
1610
1611
1611
1612 # Look for the given name by splitting it in parts. If the head is
1612 # Look for the given name by splitting it in parts. If the head is
1613 # found, then we look for all the remaining parts as members, and only
1613 # found, then we look for all the remaining parts as members, and only
1614 # declare success if we can find them all.
1614 # declare success if we can find them all.
1615 oname_parts = parts
1615 oname_parts = parts
1616 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1616 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1617 for nsname,ns in namespaces:
1617 for nsname,ns in namespaces:
1618 try:
1618 try:
1619 obj = ns[oname_head]
1619 obj = ns[oname_head]
1620 except KeyError:
1620 except KeyError:
1621 continue
1621 continue
1622 else:
1622 else:
1623 for idx, part in enumerate(oname_rest):
1623 for idx, part in enumerate(oname_rest):
1624 try:
1624 try:
1625 parent = obj
1625 parent = obj
1626 # The last part is looked up in a special way to avoid
1626 # The last part is looked up in a special way to avoid
1627 # descriptor invocation as it may raise or have side
1627 # descriptor invocation as it may raise or have side
1628 # effects.
1628 # effects.
1629 if idx == len(oname_rest) - 1:
1629 if idx == len(oname_rest) - 1:
1630 obj = self._getattr_property(obj, part)
1630 obj = self._getattr_property(obj, part)
1631 else:
1631 else:
1632 if is_integer_string(part):
1632 if is_integer_string(part):
1633 obj = obj[int(part)]
1633 obj = obj[int(part)]
1634 else:
1634 else:
1635 obj = getattr(obj, part)
1635 obj = getattr(obj, part)
1636 except:
1636 except:
1637 # Blanket except b/c some badly implemented objects
1637 # Blanket except b/c some badly implemented objects
1638 # allow __getattr__ to raise exceptions other than
1638 # allow __getattr__ to raise exceptions other than
1639 # AttributeError, which then crashes IPython.
1639 # AttributeError, which then crashes IPython.
1640 break
1640 break
1641 else:
1641 else:
1642 # If we finish the for loop (no break), we got all members
1642 # If we finish the for loop (no break), we got all members
1643 found = True
1643 found = True
1644 ospace = nsname
1644 ospace = nsname
1645 break # namespace loop
1645 break # namespace loop
1646
1646
1647 # Try to see if it's magic
1647 # Try to see if it's magic
1648 if not found:
1648 if not found:
1649 obj = None
1649 obj = None
1650 if oname.startswith(ESC_MAGIC2):
1650 if oname.startswith(ESC_MAGIC2):
1651 oname = oname.lstrip(ESC_MAGIC2)
1651 oname = oname.lstrip(ESC_MAGIC2)
1652 obj = self.find_cell_magic(oname)
1652 obj = self.find_cell_magic(oname)
1653 elif oname.startswith(ESC_MAGIC):
1653 elif oname.startswith(ESC_MAGIC):
1654 oname = oname.lstrip(ESC_MAGIC)
1654 oname = oname.lstrip(ESC_MAGIC)
1655 obj = self.find_line_magic(oname)
1655 obj = self.find_line_magic(oname)
1656 else:
1656 else:
1657 # search without prefix, so run? will find %run?
1657 # search without prefix, so run? will find %run?
1658 obj = self.find_line_magic(oname)
1658 obj = self.find_line_magic(oname)
1659 if obj is None:
1659 if obj is None:
1660 obj = self.find_cell_magic(oname)
1660 obj = self.find_cell_magic(oname)
1661 if obj is not None:
1661 if obj is not None:
1662 found = True
1662 found = True
1663 ospace = 'IPython internal'
1663 ospace = 'IPython internal'
1664 ismagic = True
1664 ismagic = True
1665 isalias = isinstance(obj, Alias)
1665 isalias = isinstance(obj, Alias)
1666
1666
1667 # Last try: special-case some literals like '', [], {}, etc:
1667 # Last try: special-case some literals like '', [], {}, etc:
1668 if not found and oname_head in ["''",'""','[]','{}','()']:
1668 if not found and oname_head in ["''",'""','[]','{}','()']:
1669 obj = eval(oname_head)
1669 obj = eval(oname_head)
1670 found = True
1670 found = True
1671 ospace = 'Interactive'
1671 ospace = 'Interactive'
1672
1672
1673 return {
1673 return {
1674 'obj':obj,
1674 'obj':obj,
1675 'found':found,
1675 'found':found,
1676 'parent':parent,
1676 'parent':parent,
1677 'ismagic':ismagic,
1677 'ismagic':ismagic,
1678 'isalias':isalias,
1678 'isalias':isalias,
1679 'namespace':ospace
1679 'namespace':ospace
1680 }
1680 }
1681
1681
1682 @staticmethod
1682 @staticmethod
1683 def _getattr_property(obj, attrname):
1683 def _getattr_property(obj, attrname):
1684 """Property-aware getattr to use in object finding.
1684 """Property-aware getattr to use in object finding.
1685
1685
1686 If attrname represents a property, return it unevaluated (in case it has
1686 If attrname represents a property, return it unevaluated (in case it has
1687 side effects or raises an error.
1687 side effects or raises an error.
1688
1688
1689 """
1689 """
1690 if not isinstance(obj, type):
1690 if not isinstance(obj, type):
1691 try:
1691 try:
1692 # `getattr(type(obj), attrname)` is not guaranteed to return
1692 # `getattr(type(obj), attrname)` is not guaranteed to return
1693 # `obj`, but does so for property:
1693 # `obj`, but does so for property:
1694 #
1694 #
1695 # property.__get__(self, None, cls) -> self
1695 # property.__get__(self, None, cls) -> self
1696 #
1696 #
1697 # The universal alternative is to traverse the mro manually
1697 # The universal alternative is to traverse the mro manually
1698 # searching for attrname in class dicts.
1698 # searching for attrname in class dicts.
1699 if is_integer_string(attrname):
1699 if is_integer_string(attrname):
1700 return obj[int(attrname)]
1700 return obj[int(attrname)]
1701 else:
1701 else:
1702 attr = getattr(type(obj), attrname)
1702 attr = getattr(type(obj), attrname)
1703 except AttributeError:
1703 except AttributeError:
1704 pass
1704 pass
1705 else:
1705 else:
1706 # This relies on the fact that data descriptors (with both
1706 # This relies on the fact that data descriptors (with both
1707 # __get__ & __set__ magic methods) take precedence over
1707 # __get__ & __set__ magic methods) take precedence over
1708 # instance-level attributes:
1708 # instance-level attributes:
1709 #
1709 #
1710 # class A(object):
1710 # class A(object):
1711 # @property
1711 # @property
1712 # def foobar(self): return 123
1712 # def foobar(self): return 123
1713 # a = A()
1713 # a = A()
1714 # a.__dict__['foobar'] = 345
1714 # a.__dict__['foobar'] = 345
1715 # a.foobar # == 123
1715 # a.foobar # == 123
1716 #
1716 #
1717 # So, a property may be returned right away.
1717 # So, a property may be returned right away.
1718 if isinstance(attr, property):
1718 if isinstance(attr, property):
1719 return attr
1719 return attr
1720
1720
1721 # Nothing helped, fall back.
1721 # Nothing helped, fall back.
1722 return getattr(obj, attrname)
1722 return getattr(obj, attrname)
1723
1723
1724 def _object_find(self, oname, namespaces=None):
1724 def _object_find(self, oname, namespaces=None):
1725 """Find an object and return a struct with info about it."""
1725 """Find an object and return a struct with info about it."""
1726 return Struct(self._ofind(oname, namespaces))
1726 return Struct(self._ofind(oname, namespaces))
1727
1727
1728 def _inspect(self, meth, oname, namespaces=None, **kw):
1728 def _inspect(self, meth, oname, namespaces=None, **kw):
1729 """Generic interface to the inspector system.
1729 """Generic interface to the inspector system.
1730
1730
1731 This function is meant to be called by pdef, pdoc & friends.
1731 This function is meant to be called by pdef, pdoc & friends.
1732 """
1732 """
1733 info = self._object_find(oname, namespaces)
1733 info = self._object_find(oname, namespaces)
1734 docformat = (
1734 docformat = (
1735 sphinxify(self.object_inspect(oname)) if self.sphinxify_docstring else None
1735 sphinxify(self.object_inspect(oname)) if self.sphinxify_docstring else None
1736 )
1736 )
1737 if info.found:
1737 if info.found:
1738 pmethod = getattr(self.inspector, meth)
1738 pmethod = getattr(self.inspector, meth)
1739 # TODO: only apply format_screen to the plain/text repr of the mime
1739 # TODO: only apply format_screen to the plain/text repr of the mime
1740 # bundle.
1740 # bundle.
1741 formatter = format_screen if info.ismagic else docformat
1741 formatter = format_screen if info.ismagic else docformat
1742 if meth == 'pdoc':
1742 if meth == 'pdoc':
1743 pmethod(info.obj, oname, formatter)
1743 pmethod(info.obj, oname, formatter)
1744 elif meth == 'pinfo':
1744 elif meth == 'pinfo':
1745 pmethod(
1745 pmethod(
1746 info.obj,
1746 info.obj,
1747 oname,
1747 oname,
1748 formatter,
1748 formatter,
1749 info,
1749 info,
1750 enable_html_pager=self.enable_html_pager,
1750 enable_html_pager=self.enable_html_pager,
1751 **kw,
1751 **kw,
1752 )
1752 )
1753 else:
1753 else:
1754 pmethod(info.obj, oname)
1754 pmethod(info.obj, oname)
1755 else:
1755 else:
1756 print('Object `%s` not found.' % oname)
1756 print('Object `%s` not found.' % oname)
1757 return 'not found' # so callers can take other action
1757 return 'not found' # so callers can take other action
1758
1758
1759 def object_inspect(self, oname, detail_level=0):
1759 def object_inspect(self, oname, detail_level=0):
1760 """Get object info about oname"""
1760 """Get object info about oname"""
1761 with self.builtin_trap:
1761 with self.builtin_trap:
1762 info = self._object_find(oname)
1762 info = self._object_find(oname)
1763 if info.found:
1763 if info.found:
1764 return self.inspector.info(info.obj, oname, info=info,
1764 return self.inspector.info(info.obj, oname, info=info,
1765 detail_level=detail_level
1765 detail_level=detail_level
1766 )
1766 )
1767 else:
1767 else:
1768 return oinspect.object_info(name=oname, found=False)
1768 return oinspect.object_info(name=oname, found=False)
1769
1769
1770 def object_inspect_text(self, oname, detail_level=0):
1770 def object_inspect_text(self, oname, detail_level=0):
1771 """Get object info as formatted text"""
1771 """Get object info as formatted text"""
1772 return self.object_inspect_mime(oname, detail_level)['text/plain']
1772 return self.object_inspect_mime(oname, detail_level)['text/plain']
1773
1773
1774 def object_inspect_mime(self, oname, detail_level=0, omit_sections=()):
1774 def object_inspect_mime(self, oname, detail_level=0, omit_sections=()):
1775 """Get object info as a mimebundle of formatted representations.
1775 """Get object info as a mimebundle of formatted representations.
1776
1776
1777 A mimebundle is a dictionary, keyed by mime-type.
1777 A mimebundle is a dictionary, keyed by mime-type.
1778 It must always have the key `'text/plain'`.
1778 It must always have the key `'text/plain'`.
1779 """
1779 """
1780 with self.builtin_trap:
1780 with self.builtin_trap:
1781 info = self._object_find(oname)
1781 info = self._object_find(oname)
1782 if info.found:
1782 if info.found:
1783 docformat = (
1783 docformat = (
1784 sphinxify(self.object_inspect(oname))
1784 sphinxify(self.object_inspect(oname))
1785 if self.sphinxify_docstring
1785 if self.sphinxify_docstring
1786 else None
1786 else None
1787 )
1787 )
1788 return self.inspector._get_info(
1788 return self.inspector._get_info(
1789 info.obj,
1789 info.obj,
1790 oname,
1790 oname,
1791 info=info,
1791 info=info,
1792 detail_level=detail_level,
1792 detail_level=detail_level,
1793 formatter=docformat,
1793 formatter=docformat,
1794 omit_sections=omit_sections,
1794 omit_sections=omit_sections,
1795 )
1795 )
1796 else:
1796 else:
1797 raise KeyError(oname)
1797 raise KeyError(oname)
1798
1798
1799 #-------------------------------------------------------------------------
1799 #-------------------------------------------------------------------------
1800 # Things related to history management
1800 # Things related to history management
1801 #-------------------------------------------------------------------------
1801 #-------------------------------------------------------------------------
1802
1802
1803 def init_history(self):
1803 def init_history(self):
1804 """Sets up the command history, and starts regular autosaves."""
1804 """Sets up the command history, and starts regular autosaves."""
1805 self.history_manager = HistoryManager(shell=self, parent=self)
1805 self.history_manager = HistoryManager(shell=self, parent=self)
1806 self.configurables.append(self.history_manager)
1806 self.configurables.append(self.history_manager)
1807
1807
1808 #-------------------------------------------------------------------------
1808 #-------------------------------------------------------------------------
1809 # Things related to exception handling and tracebacks (not debugging)
1809 # Things related to exception handling and tracebacks (not debugging)
1810 #-------------------------------------------------------------------------
1810 #-------------------------------------------------------------------------
1811
1811
1812 debugger_cls = InterruptiblePdb
1812 debugger_cls = InterruptiblePdb
1813
1813
1814 def init_traceback_handlers(self, custom_exceptions):
1814 def init_traceback_handlers(self, custom_exceptions):
1815 # Syntax error handler.
1815 # Syntax error handler.
1816 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1816 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1817
1817
1818 # The interactive one is initialized with an offset, meaning we always
1818 # The interactive one is initialized with an offset, meaning we always
1819 # want to remove the topmost item in the traceback, which is our own
1819 # want to remove the topmost item in the traceback, which is our own
1820 # internal code. Valid modes: ['Plain','Context','Verbose','Minimal']
1820 # internal code. Valid modes: ['Plain','Context','Verbose','Minimal']
1821 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1821 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1822 color_scheme='NoColor',
1822 color_scheme='NoColor',
1823 tb_offset = 1,
1823 tb_offset = 1,
1824 debugger_cls=self.debugger_cls, parent=self)
1824 debugger_cls=self.debugger_cls, parent=self)
1825
1825
1826 # The instance will store a pointer to the system-wide exception hook,
1826 # The instance will store a pointer to the system-wide exception hook,
1827 # so that runtime code (such as magics) can access it. This is because
1827 # so that runtime code (such as magics) can access it. This is because
1828 # during the read-eval loop, it may get temporarily overwritten.
1828 # during the read-eval loop, it may get temporarily overwritten.
1829 self.sys_excepthook = sys.excepthook
1829 self.sys_excepthook = sys.excepthook
1830
1830
1831 # and add any custom exception handlers the user may have specified
1831 # and add any custom exception handlers the user may have specified
1832 self.set_custom_exc(*custom_exceptions)
1832 self.set_custom_exc(*custom_exceptions)
1833
1833
1834 # Set the exception mode
1834 # Set the exception mode
1835 self.InteractiveTB.set_mode(mode=self.xmode)
1835 self.InteractiveTB.set_mode(mode=self.xmode)
1836
1836
1837 def set_custom_exc(self, exc_tuple, handler):
1837 def set_custom_exc(self, exc_tuple, handler):
1838 """set_custom_exc(exc_tuple, handler)
1838 """set_custom_exc(exc_tuple, handler)
1839
1839
1840 Set a custom exception handler, which will be called if any of the
1840 Set a custom exception handler, which will be called if any of the
1841 exceptions in exc_tuple occur in the mainloop (specifically, in the
1841 exceptions in exc_tuple occur in the mainloop (specifically, in the
1842 run_code() method).
1842 run_code() method).
1843
1843
1844 Parameters
1844 Parameters
1845 ----------
1845 ----------
1846 exc_tuple : tuple of exception classes
1846 exc_tuple : tuple of exception classes
1847 A *tuple* of exception classes, for which to call the defined
1847 A *tuple* of exception classes, for which to call the defined
1848 handler. It is very important that you use a tuple, and NOT A
1848 handler. It is very important that you use a tuple, and NOT A
1849 LIST here, because of the way Python's except statement works. If
1849 LIST here, because of the way Python's except statement works. If
1850 you only want to trap a single exception, use a singleton tuple::
1850 you only want to trap a single exception, use a singleton tuple::
1851
1851
1852 exc_tuple == (MyCustomException,)
1852 exc_tuple == (MyCustomException,)
1853
1853
1854 handler : callable
1854 handler : callable
1855 handler must have the following signature::
1855 handler must have the following signature::
1856
1856
1857 def my_handler(self, etype, value, tb, tb_offset=None):
1857 def my_handler(self, etype, value, tb, tb_offset=None):
1858 ...
1858 ...
1859 return structured_traceback
1859 return structured_traceback
1860
1860
1861 Your handler must return a structured traceback (a list of strings),
1861 Your handler must return a structured traceback (a list of strings),
1862 or None.
1862 or None.
1863
1863
1864 This will be made into an instance method (via types.MethodType)
1864 This will be made into an instance method (via types.MethodType)
1865 of IPython itself, and it will be called if any of the exceptions
1865 of IPython itself, and it will be called if any of the exceptions
1866 listed in the exc_tuple are caught. If the handler is None, an
1866 listed in the exc_tuple are caught. If the handler is None, an
1867 internal basic one is used, which just prints basic info.
1867 internal basic one is used, which just prints basic info.
1868
1868
1869 To protect IPython from crashes, if your handler ever raises an
1869 To protect IPython from crashes, if your handler ever raises an
1870 exception or returns an invalid result, it will be immediately
1870 exception or returns an invalid result, it will be immediately
1871 disabled.
1871 disabled.
1872
1872
1873 Notes
1873 Notes
1874 -----
1874 -----
1875 WARNING: by putting in your own exception handler into IPython's main
1875 WARNING: by putting in your own exception handler into IPython's main
1876 execution loop, you run a very good chance of nasty crashes. This
1876 execution loop, you run a very good chance of nasty crashes. This
1877 facility should only be used if you really know what you are doing.
1877 facility should only be used if you really know what you are doing.
1878 """
1878 """
1879
1879
1880 if not isinstance(exc_tuple, tuple):
1880 if not isinstance(exc_tuple, tuple):
1881 raise TypeError("The custom exceptions must be given as a tuple.")
1881 raise TypeError("The custom exceptions must be given as a tuple.")
1882
1882
1883 def dummy_handler(self, etype, value, tb, tb_offset=None):
1883 def dummy_handler(self, etype, value, tb, tb_offset=None):
1884 print('*** Simple custom exception handler ***')
1884 print('*** Simple custom exception handler ***')
1885 print('Exception type :', etype)
1885 print('Exception type :', etype)
1886 print('Exception value:', value)
1886 print('Exception value:', value)
1887 print('Traceback :', tb)
1887 print('Traceback :', tb)
1888
1888
1889 def validate_stb(stb):
1889 def validate_stb(stb):
1890 """validate structured traceback return type
1890 """validate structured traceback return type
1891
1891
1892 return type of CustomTB *should* be a list of strings, but allow
1892 return type of CustomTB *should* be a list of strings, but allow
1893 single strings or None, which are harmless.
1893 single strings or None, which are harmless.
1894
1894
1895 This function will *always* return a list of strings,
1895 This function will *always* return a list of strings,
1896 and will raise a TypeError if stb is inappropriate.
1896 and will raise a TypeError if stb is inappropriate.
1897 """
1897 """
1898 msg = "CustomTB must return list of strings, not %r" % stb
1898 msg = "CustomTB must return list of strings, not %r" % stb
1899 if stb is None:
1899 if stb is None:
1900 return []
1900 return []
1901 elif isinstance(stb, str):
1901 elif isinstance(stb, str):
1902 return [stb]
1902 return [stb]
1903 elif not isinstance(stb, list):
1903 elif not isinstance(stb, list):
1904 raise TypeError(msg)
1904 raise TypeError(msg)
1905 # it's a list
1905 # it's a list
1906 for line in stb:
1906 for line in stb:
1907 # check every element
1907 # check every element
1908 if not isinstance(line, str):
1908 if not isinstance(line, str):
1909 raise TypeError(msg)
1909 raise TypeError(msg)
1910 return stb
1910 return stb
1911
1911
1912 if handler is None:
1912 if handler is None:
1913 wrapped = dummy_handler
1913 wrapped = dummy_handler
1914 else:
1914 else:
1915 def wrapped(self,etype,value,tb,tb_offset=None):
1915 def wrapped(self,etype,value,tb,tb_offset=None):
1916 """wrap CustomTB handler, to protect IPython from user code
1916 """wrap CustomTB handler, to protect IPython from user code
1917
1917
1918 This makes it harder (but not impossible) for custom exception
1918 This makes it harder (but not impossible) for custom exception
1919 handlers to crash IPython.
1919 handlers to crash IPython.
1920 """
1920 """
1921 try:
1921 try:
1922 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1922 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1923 return validate_stb(stb)
1923 return validate_stb(stb)
1924 except:
1924 except:
1925 # clear custom handler immediately
1925 # clear custom handler immediately
1926 self.set_custom_exc((), None)
1926 self.set_custom_exc((), None)
1927 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1927 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1928 # show the exception in handler first
1928 # show the exception in handler first
1929 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1929 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1930 print(self.InteractiveTB.stb2text(stb))
1930 print(self.InteractiveTB.stb2text(stb))
1931 print("The original exception:")
1931 print("The original exception:")
1932 stb = self.InteractiveTB.structured_traceback(
1932 stb = self.InteractiveTB.structured_traceback(
1933 (etype,value,tb), tb_offset=tb_offset
1933 (etype,value,tb), tb_offset=tb_offset
1934 )
1934 )
1935 return stb
1935 return stb
1936
1936
1937 self.CustomTB = types.MethodType(wrapped,self)
1937 self.CustomTB = types.MethodType(wrapped,self)
1938 self.custom_exceptions = exc_tuple
1938 self.custom_exceptions = exc_tuple
1939
1939
1940 def excepthook(self, etype, value, tb):
1940 def excepthook(self, etype, value, tb):
1941 """One more defense for GUI apps that call sys.excepthook.
1941 """One more defense for GUI apps that call sys.excepthook.
1942
1942
1943 GUI frameworks like wxPython trap exceptions and call
1943 GUI frameworks like wxPython trap exceptions and call
1944 sys.excepthook themselves. I guess this is a feature that
1944 sys.excepthook themselves. I guess this is a feature that
1945 enables them to keep running after exceptions that would
1945 enables them to keep running after exceptions that would
1946 otherwise kill their mainloop. This is a bother for IPython
1946 otherwise kill their mainloop. This is a bother for IPython
1947 which expects to catch all of the program exceptions with a try:
1947 which expects to catch all of the program exceptions with a try:
1948 except: statement.
1948 except: statement.
1949
1949
1950 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1950 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1951 any app directly invokes sys.excepthook, it will look to the user like
1951 any app directly invokes sys.excepthook, it will look to the user like
1952 IPython crashed. In order to work around this, we can disable the
1952 IPython crashed. In order to work around this, we can disable the
1953 CrashHandler and replace it with this excepthook instead, which prints a
1953 CrashHandler and replace it with this excepthook instead, which prints a
1954 regular traceback using our InteractiveTB. In this fashion, apps which
1954 regular traceback using our InteractiveTB. In this fashion, apps which
1955 call sys.excepthook will generate a regular-looking exception from
1955 call sys.excepthook will generate a regular-looking exception from
1956 IPython, and the CrashHandler will only be triggered by real IPython
1956 IPython, and the CrashHandler will only be triggered by real IPython
1957 crashes.
1957 crashes.
1958
1958
1959 This hook should be used sparingly, only in places which are not likely
1959 This hook should be used sparingly, only in places which are not likely
1960 to be true IPython errors.
1960 to be true IPython errors.
1961 """
1961 """
1962 self.showtraceback((etype, value, tb), tb_offset=0)
1962 self.showtraceback((etype, value, tb), tb_offset=0)
1963
1963
1964 def _get_exc_info(self, exc_tuple=None):
1964 def _get_exc_info(self, exc_tuple=None):
1965 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1965 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1966
1966
1967 Ensures sys.last_type,value,traceback hold the exc_info we found,
1967 Ensures sys.last_type,value,traceback hold the exc_info we found,
1968 from whichever source.
1968 from whichever source.
1969
1969
1970 raises ValueError if none of these contain any information
1970 raises ValueError if none of these contain any information
1971 """
1971 """
1972 if exc_tuple is None:
1972 if exc_tuple is None:
1973 etype, value, tb = sys.exc_info()
1973 etype, value, tb = sys.exc_info()
1974 else:
1974 else:
1975 etype, value, tb = exc_tuple
1975 etype, value, tb = exc_tuple
1976
1976
1977 if etype is None:
1977 if etype is None:
1978 if hasattr(sys, 'last_type'):
1978 if hasattr(sys, 'last_type'):
1979 etype, value, tb = sys.last_type, sys.last_value, \
1979 etype, value, tb = sys.last_type, sys.last_value, \
1980 sys.last_traceback
1980 sys.last_traceback
1981
1981
1982 if etype is None:
1982 if etype is None:
1983 raise ValueError("No exception to find")
1983 raise ValueError("No exception to find")
1984
1984
1985 # Now store the exception info in sys.last_type etc.
1985 # Now store the exception info in sys.last_type etc.
1986 # WARNING: these variables are somewhat deprecated and not
1986 # WARNING: these variables are somewhat deprecated and not
1987 # necessarily safe to use in a threaded environment, but tools
1987 # necessarily safe to use in a threaded environment, but tools
1988 # like pdb depend on their existence, so let's set them. If we
1988 # like pdb depend on their existence, so let's set them. If we
1989 # find problems in the field, we'll need to revisit their use.
1989 # find problems in the field, we'll need to revisit their use.
1990 sys.last_type = etype
1990 sys.last_type = etype
1991 sys.last_value = value
1991 sys.last_value = value
1992 sys.last_traceback = tb
1992 sys.last_traceback = tb
1993
1993
1994 return etype, value, tb
1994 return etype, value, tb
1995
1995
1996 def show_usage_error(self, exc):
1996 def show_usage_error(self, exc):
1997 """Show a short message for UsageErrors
1997 """Show a short message for UsageErrors
1998
1998
1999 These are special exceptions that shouldn't show a traceback.
1999 These are special exceptions that shouldn't show a traceback.
2000 """
2000 """
2001 print("UsageError: %s" % exc, file=sys.stderr)
2001 print("UsageError: %s" % exc, file=sys.stderr)
2002
2002
2003 def get_exception_only(self, exc_tuple=None):
2003 def get_exception_only(self, exc_tuple=None):
2004 """
2004 """
2005 Return as a string (ending with a newline) the exception that
2005 Return as a string (ending with a newline) the exception that
2006 just occurred, without any traceback.
2006 just occurred, without any traceback.
2007 """
2007 """
2008 etype, value, tb = self._get_exc_info(exc_tuple)
2008 etype, value, tb = self._get_exc_info(exc_tuple)
2009 msg = traceback.format_exception_only(etype, value)
2009 msg = traceback.format_exception_only(etype, value)
2010 return ''.join(msg)
2010 return ''.join(msg)
2011
2011
2012 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
2012 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
2013 exception_only=False, running_compiled_code=False):
2013 exception_only=False, running_compiled_code=False):
2014 """Display the exception that just occurred.
2014 """Display the exception that just occurred.
2015
2015
2016 If nothing is known about the exception, this is the method which
2016 If nothing is known about the exception, this is the method which
2017 should be used throughout the code for presenting user tracebacks,
2017 should be used throughout the code for presenting user tracebacks,
2018 rather than directly invoking the InteractiveTB object.
2018 rather than directly invoking the InteractiveTB object.
2019
2019
2020 A specific showsyntaxerror() also exists, but this method can take
2020 A specific showsyntaxerror() also exists, but this method can take
2021 care of calling it if needed, so unless you are explicitly catching a
2021 care of calling it if needed, so unless you are explicitly catching a
2022 SyntaxError exception, don't try to analyze the stack manually and
2022 SyntaxError exception, don't try to analyze the stack manually and
2023 simply call this method."""
2023 simply call this method."""
2024
2024
2025 try:
2025 try:
2026 try:
2026 try:
2027 etype, value, tb = self._get_exc_info(exc_tuple)
2027 etype, value, tb = self._get_exc_info(exc_tuple)
2028 except ValueError:
2028 except ValueError:
2029 print('No traceback available to show.', file=sys.stderr)
2029 print('No traceback available to show.', file=sys.stderr)
2030 return
2030 return
2031
2031
2032 if issubclass(etype, SyntaxError):
2032 if issubclass(etype, SyntaxError):
2033 # Though this won't be called by syntax errors in the input
2033 # Though this won't be called by syntax errors in the input
2034 # line, there may be SyntaxError cases with imported code.
2034 # line, there may be SyntaxError cases with imported code.
2035 self.showsyntaxerror(filename, running_compiled_code)
2035 self.showsyntaxerror(filename, running_compiled_code)
2036 elif etype is UsageError:
2036 elif etype is UsageError:
2037 self.show_usage_error(value)
2037 self.show_usage_error(value)
2038 else:
2038 else:
2039 if exception_only:
2039 if exception_only:
2040 stb = ['An exception has occurred, use %tb to see '
2040 stb = ['An exception has occurred, use %tb to see '
2041 'the full traceback.\n']
2041 'the full traceback.\n']
2042 stb.extend(self.InteractiveTB.get_exception_only(etype,
2042 stb.extend(self.InteractiveTB.get_exception_only(etype,
2043 value))
2043 value))
2044 else:
2044 else:
2045 try:
2045 try:
2046 # Exception classes can customise their traceback - we
2046 # Exception classes can customise their traceback - we
2047 # use this in IPython.parallel for exceptions occurring
2047 # use this in IPython.parallel for exceptions occurring
2048 # in the engines. This should return a list of strings.
2048 # in the engines. This should return a list of strings.
2049 if hasattr(value, "_render_traceback_"):
2049 if hasattr(value, "_render_traceback_"):
2050 stb = value._render_traceback_()
2050 stb = value._render_traceback_()
2051 else:
2051 else:
2052 stb = self.InteractiveTB.structured_traceback(
2052 stb = self.InteractiveTB.structured_traceback(
2053 etype, value, tb, tb_offset=tb_offset
2053 etype, value, tb, tb_offset=tb_offset
2054 )
2054 )
2055
2055
2056 except Exception:
2056 except Exception:
2057 print(
2057 print(
2058 "Unexpected exception formatting exception. Falling back to standard exception"
2058 "Unexpected exception formatting exception. Falling back to standard exception"
2059 )
2059 )
2060 traceback.print_exc()
2060 traceback.print_exc()
2061 return None
2061 return None
2062
2062
2063 self._showtraceback(etype, value, stb)
2063 self._showtraceback(etype, value, stb)
2064 if self.call_pdb:
2064 if self.call_pdb:
2065 # drop into debugger
2065 # drop into debugger
2066 self.debugger(force=True)
2066 self.debugger(force=True)
2067 return
2067 return
2068
2068
2069 # Actually show the traceback
2069 # Actually show the traceback
2070 self._showtraceback(etype, value, stb)
2070 self._showtraceback(etype, value, stb)
2071
2071
2072 except KeyboardInterrupt:
2072 except KeyboardInterrupt:
2073 print('\n' + self.get_exception_only(), file=sys.stderr)
2073 print('\n' + self.get_exception_only(), file=sys.stderr)
2074
2074
2075 def _showtraceback(self, etype, evalue, stb: str):
2075 def _showtraceback(self, etype, evalue, stb: str):
2076 """Actually show a traceback.
2076 """Actually show a traceback.
2077
2077
2078 Subclasses may override this method to put the traceback on a different
2078 Subclasses may override this method to put the traceback on a different
2079 place, like a side channel.
2079 place, like a side channel.
2080 """
2080 """
2081 val = self.InteractiveTB.stb2text(stb)
2081 val = self.InteractiveTB.stb2text(stb)
2082 try:
2082 try:
2083 print(val)
2083 print(val)
2084 except UnicodeEncodeError:
2084 except UnicodeEncodeError:
2085 print(val.encode("utf-8", "backslashreplace").decode())
2085 print(val.encode("utf-8", "backslashreplace").decode())
2086
2086
2087 def showsyntaxerror(self, filename=None, running_compiled_code=False):
2087 def showsyntaxerror(self, filename=None, running_compiled_code=False):
2088 """Display the syntax error that just occurred.
2088 """Display the syntax error that just occurred.
2089
2089
2090 This doesn't display a stack trace because there isn't one.
2090 This doesn't display a stack trace because there isn't one.
2091
2091
2092 If a filename is given, it is stuffed in the exception instead
2092 If a filename is given, it is stuffed in the exception instead
2093 of what was there before (because Python's parser always uses
2093 of what was there before (because Python's parser always uses
2094 "<string>" when reading from a string).
2094 "<string>" when reading from a string).
2095
2095
2096 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
2096 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
2097 longer stack trace will be displayed.
2097 longer stack trace will be displayed.
2098 """
2098 """
2099 etype, value, last_traceback = self._get_exc_info()
2099 etype, value, last_traceback = self._get_exc_info()
2100
2100
2101 if filename and issubclass(etype, SyntaxError):
2101 if filename and issubclass(etype, SyntaxError):
2102 try:
2102 try:
2103 value.filename = filename
2103 value.filename = filename
2104 except:
2104 except:
2105 # Not the format we expect; leave it alone
2105 # Not the format we expect; leave it alone
2106 pass
2106 pass
2107
2107
2108 # If the error occurred when executing compiled code, we should provide full stacktrace.
2108 # If the error occurred when executing compiled code, we should provide full stacktrace.
2109 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
2109 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
2110 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
2110 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
2111 self._showtraceback(etype, value, stb)
2111 self._showtraceback(etype, value, stb)
2112
2112
2113 # This is overridden in TerminalInteractiveShell to show a message about
2113 # This is overridden in TerminalInteractiveShell to show a message about
2114 # the %paste magic.
2114 # the %paste magic.
2115 def showindentationerror(self):
2115 def showindentationerror(self):
2116 """Called by _run_cell when there's an IndentationError in code entered
2116 """Called by _run_cell when there's an IndentationError in code entered
2117 at the prompt.
2117 at the prompt.
2118
2118
2119 This is overridden in TerminalInteractiveShell to show a message about
2119 This is overridden in TerminalInteractiveShell to show a message about
2120 the %paste magic."""
2120 the %paste magic."""
2121 self.showsyntaxerror()
2121 self.showsyntaxerror()
2122
2122
2123 @skip_doctest
2123 @skip_doctest
2124 def set_next_input(self, s, replace=False):
2124 def set_next_input(self, s, replace=False):
2125 """ Sets the 'default' input string for the next command line.
2125 """ Sets the 'default' input string for the next command line.
2126
2126
2127 Example::
2127 Example::
2128
2128
2129 In [1]: _ip.set_next_input("Hello Word")
2129 In [1]: _ip.set_next_input("Hello Word")
2130 In [2]: Hello Word_ # cursor is here
2130 In [2]: Hello Word_ # cursor is here
2131 """
2131 """
2132 self.rl_next_input = s
2132 self.rl_next_input = s
2133
2133
2134 def _indent_current_str(self):
2134 def _indent_current_str(self):
2135 """return the current level of indentation as a string"""
2135 """return the current level of indentation as a string"""
2136 return self.input_splitter.get_indent_spaces() * ' '
2136 return self.input_splitter.get_indent_spaces() * ' '
2137
2137
2138 #-------------------------------------------------------------------------
2138 #-------------------------------------------------------------------------
2139 # Things related to text completion
2139 # Things related to text completion
2140 #-------------------------------------------------------------------------
2140 #-------------------------------------------------------------------------
2141
2141
2142 def init_completer(self):
2142 def init_completer(self):
2143 """Initialize the completion machinery.
2143 """Initialize the completion machinery.
2144
2144
2145 This creates completion machinery that can be used by client code,
2145 This creates completion machinery that can be used by client code,
2146 either interactively in-process (typically triggered by the readline
2146 either interactively in-process (typically triggered by the readline
2147 library), programmatically (such as in test suites) or out-of-process
2147 library), programmatically (such as in test suites) or out-of-process
2148 (typically over the network by remote frontends).
2148 (typically over the network by remote frontends).
2149 """
2149 """
2150 from IPython.core.completer import IPCompleter
2150 from IPython.core.completer import IPCompleter
2151 from IPython.core.completerlib import (
2151 from IPython.core.completerlib import (
2152 cd_completer,
2152 cd_completer,
2153 magic_run_completer,
2153 magic_run_completer,
2154 module_completer,
2154 module_completer,
2155 reset_completer,
2155 reset_completer,
2156 )
2156 )
2157
2157
2158 self.Completer = IPCompleter(shell=self,
2158 self.Completer = IPCompleter(shell=self,
2159 namespace=self.user_ns,
2159 namespace=self.user_ns,
2160 global_namespace=self.user_global_ns,
2160 global_namespace=self.user_global_ns,
2161 parent=self,
2161 parent=self,
2162 )
2162 )
2163 self.configurables.append(self.Completer)
2163 self.configurables.append(self.Completer)
2164
2164
2165 # Add custom completers to the basic ones built into IPCompleter
2165 # Add custom completers to the basic ones built into IPCompleter
2166 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
2166 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
2167 self.strdispatchers['complete_command'] = sdisp
2167 self.strdispatchers['complete_command'] = sdisp
2168 self.Completer.custom_completers = sdisp
2168 self.Completer.custom_completers = sdisp
2169
2169
2170 self.set_hook('complete_command', module_completer, str_key = 'import')
2170 self.set_hook('complete_command', module_completer, str_key = 'import')
2171 self.set_hook('complete_command', module_completer, str_key = 'from')
2171 self.set_hook('complete_command', module_completer, str_key = 'from')
2172 self.set_hook('complete_command', module_completer, str_key = '%aimport')
2172 self.set_hook('complete_command', module_completer, str_key = '%aimport')
2173 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
2173 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
2174 self.set_hook('complete_command', cd_completer, str_key = '%cd')
2174 self.set_hook('complete_command', cd_completer, str_key = '%cd')
2175 self.set_hook('complete_command', reset_completer, str_key = '%reset')
2175 self.set_hook('complete_command', reset_completer, str_key = '%reset')
2176
2176
2177 @skip_doctest
2177 @skip_doctest
2178 def complete(self, text, line=None, cursor_pos=None):
2178 def complete(self, text, line=None, cursor_pos=None):
2179 """Return the completed text and a list of completions.
2179 """Return the completed text and a list of completions.
2180
2180
2181 Parameters
2181 Parameters
2182 ----------
2182 ----------
2183 text : string
2183 text : string
2184 A string of text to be completed on. It can be given as empty and
2184 A string of text to be completed on. It can be given as empty and
2185 instead a line/position pair are given. In this case, the
2185 instead a line/position pair are given. In this case, the
2186 completer itself will split the line like readline does.
2186 completer itself will split the line like readline does.
2187 line : string, optional
2187 line : string, optional
2188 The complete line that text is part of.
2188 The complete line that text is part of.
2189 cursor_pos : int, optional
2189 cursor_pos : int, optional
2190 The position of the cursor on the input line.
2190 The position of the cursor on the input line.
2191
2191
2192 Returns
2192 Returns
2193 -------
2193 -------
2194 text : string
2194 text : string
2195 The actual text that was completed.
2195 The actual text that was completed.
2196 matches : list
2196 matches : list
2197 A sorted list with all possible completions.
2197 A sorted list with all possible completions.
2198
2198
2199 Notes
2199 Notes
2200 -----
2200 -----
2201 The optional arguments allow the completion to take more context into
2201 The optional arguments allow the completion to take more context into
2202 account, and are part of the low-level completion API.
2202 account, and are part of the low-level completion API.
2203
2203
2204 This is a wrapper around the completion mechanism, similar to what
2204 This is a wrapper around the completion mechanism, similar to what
2205 readline does at the command line when the TAB key is hit. By
2205 readline does at the command line when the TAB key is hit. By
2206 exposing it as a method, it can be used by other non-readline
2206 exposing it as a method, it can be used by other non-readline
2207 environments (such as GUIs) for text completion.
2207 environments (such as GUIs) for text completion.
2208
2208
2209 Examples
2209 Examples
2210 --------
2210 --------
2211 In [1]: x = 'hello'
2211 In [1]: x = 'hello'
2212
2212
2213 In [2]: _ip.complete('x.l')
2213 In [2]: _ip.complete('x.l')
2214 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2214 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2215 """
2215 """
2216
2216
2217 # Inject names into __builtin__ so we can complete on the added names.
2217 # Inject names into __builtin__ so we can complete on the added names.
2218 with self.builtin_trap:
2218 with self.builtin_trap:
2219 return self.Completer.complete(text, line, cursor_pos)
2219 return self.Completer.complete(text, line, cursor_pos)
2220
2220
2221 def set_custom_completer(self, completer, pos=0) -> None:
2221 def set_custom_completer(self, completer, pos=0) -> None:
2222 """Adds a new custom completer function.
2222 """Adds a new custom completer function.
2223
2223
2224 The position argument (defaults to 0) is the index in the completers
2224 The position argument (defaults to 0) is the index in the completers
2225 list where you want the completer to be inserted.
2225 list where you want the completer to be inserted.
2226
2226
2227 `completer` should have the following signature::
2227 `completer` should have the following signature::
2228
2228
2229 def completion(self: Completer, text: string) -> List[str]:
2229 def completion(self: Completer, text: string) -> List[str]:
2230 raise NotImplementedError
2230 raise NotImplementedError
2231
2231
2232 It will be bound to the current Completer instance and pass some text
2232 It will be bound to the current Completer instance and pass some text
2233 and return a list with current completions to suggest to the user.
2233 and return a list with current completions to suggest to the user.
2234 """
2234 """
2235
2235
2236 newcomp = types.MethodType(completer, self.Completer)
2236 newcomp = types.MethodType(completer, self.Completer)
2237 self.Completer.custom_matchers.insert(pos,newcomp)
2237 self.Completer.custom_matchers.insert(pos,newcomp)
2238
2238
2239 def set_completer_frame(self, frame=None):
2239 def set_completer_frame(self, frame=None):
2240 """Set the frame of the completer."""
2240 """Set the frame of the completer."""
2241 if frame:
2241 if frame:
2242 self.Completer.namespace = frame.f_locals
2242 self.Completer.namespace = frame.f_locals
2243 self.Completer.global_namespace = frame.f_globals
2243 self.Completer.global_namespace = frame.f_globals
2244 else:
2244 else:
2245 self.Completer.namespace = self.user_ns
2245 self.Completer.namespace = self.user_ns
2246 self.Completer.global_namespace = self.user_global_ns
2246 self.Completer.global_namespace = self.user_global_ns
2247
2247
2248 #-------------------------------------------------------------------------
2248 #-------------------------------------------------------------------------
2249 # Things related to magics
2249 # Things related to magics
2250 #-------------------------------------------------------------------------
2250 #-------------------------------------------------------------------------
2251
2251
2252 def init_magics(self):
2252 def init_magics(self):
2253 from IPython.core import magics as m
2253 from IPython.core import magics as m
2254 self.magics_manager = magic.MagicsManager(shell=self,
2254 self.magics_manager = magic.MagicsManager(shell=self,
2255 parent=self,
2255 parent=self,
2256 user_magics=m.UserMagics(self))
2256 user_magics=m.UserMagics(self))
2257 self.configurables.append(self.magics_manager)
2257 self.configurables.append(self.magics_manager)
2258
2258
2259 # Expose as public API from the magics manager
2259 # Expose as public API from the magics manager
2260 self.register_magics = self.magics_manager.register
2260 self.register_magics = self.magics_manager.register
2261
2261
2262 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2262 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2263 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2263 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2264 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2264 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2265 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,
2265 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,
2266 m.PylabMagics, m.ScriptMagics,
2266 m.PylabMagics, m.ScriptMagics,
2267 )
2267 )
2268 self.register_magics(m.AsyncMagics)
2268 self.register_magics(m.AsyncMagics)
2269
2269
2270 # Register Magic Aliases
2270 # Register Magic Aliases
2271 mman = self.magics_manager
2271 mman = self.magics_manager
2272 # FIXME: magic aliases should be defined by the Magics classes
2272 # FIXME: magic aliases should be defined by the Magics classes
2273 # or in MagicsManager, not here
2273 # or in MagicsManager, not here
2274 mman.register_alias('ed', 'edit')
2274 mman.register_alias('ed', 'edit')
2275 mman.register_alias('hist', 'history')
2275 mman.register_alias('hist', 'history')
2276 mman.register_alias('rep', 'recall')
2276 mman.register_alias('rep', 'recall')
2277 mman.register_alias('SVG', 'svg', 'cell')
2277 mman.register_alias('SVG', 'svg', 'cell')
2278 mman.register_alias('HTML', 'html', 'cell')
2278 mman.register_alias('HTML', 'html', 'cell')
2279 mman.register_alias('file', 'writefile', 'cell')
2279 mman.register_alias('file', 'writefile', 'cell')
2280
2280
2281 # FIXME: Move the color initialization to the DisplayHook, which
2281 # FIXME: Move the color initialization to the DisplayHook, which
2282 # should be split into a prompt manager and displayhook. We probably
2282 # should be split into a prompt manager and displayhook. We probably
2283 # even need a centralize colors management object.
2283 # even need a centralize colors management object.
2284 self.run_line_magic('colors', self.colors)
2284 self.run_line_magic('colors', self.colors)
2285
2285
2286 # Defined here so that it's included in the documentation
2286 # Defined here so that it's included in the documentation
2287 @functools.wraps(magic.MagicsManager.register_function)
2287 @functools.wraps(magic.MagicsManager.register_function)
2288 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2288 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2289 self.magics_manager.register_function(
2289 self.magics_manager.register_function(
2290 func, magic_kind=magic_kind, magic_name=magic_name
2290 func, magic_kind=magic_kind, magic_name=magic_name
2291 )
2291 )
2292
2292
2293 def _find_with_lazy_load(self, /, type_, magic_name: str):
2293 def _find_with_lazy_load(self, /, type_, magic_name: str):
2294 """
2294 """
2295 Try to find a magic potentially lazy-loading it.
2295 Try to find a magic potentially lazy-loading it.
2296
2296
2297 Parameters
2297 Parameters
2298 ----------
2298 ----------
2299
2299
2300 type_: "line"|"cell"
2300 type_: "line"|"cell"
2301 the type of magics we are trying to find/lazy load.
2301 the type of magics we are trying to find/lazy load.
2302 magic_name: str
2302 magic_name: str
2303 The name of the magic we are trying to find/lazy load
2303 The name of the magic we are trying to find/lazy load
2304
2304
2305
2305
2306 Note that this may have any side effects
2306 Note that this may have any side effects
2307 """
2307 """
2308 finder = {"line": self.find_line_magic, "cell": self.find_cell_magic}[type_]
2308 finder = {"line": self.find_line_magic, "cell": self.find_cell_magic}[type_]
2309 fn = finder(magic_name)
2309 fn = finder(magic_name)
2310 if fn is not None:
2310 if fn is not None:
2311 return fn
2311 return fn
2312 lazy = self.magics_manager.lazy_magics.get(magic_name)
2312 lazy = self.magics_manager.lazy_magics.get(magic_name)
2313 if lazy is None:
2313 if lazy is None:
2314 return None
2314 return None
2315
2315
2316 self.run_line_magic("load_ext", lazy)
2316 self.run_line_magic("load_ext", lazy)
2317 res = finder(magic_name)
2317 res = finder(magic_name)
2318 return res
2318 return res
2319
2319
2320 def run_line_magic(self, magic_name: str, line, _stack_depth=1):
2320 def run_line_magic(self, magic_name: str, line, _stack_depth=1):
2321 """Execute the given line magic.
2321 """Execute the given line 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 line : str
2327 line : str
2328 The rest of the input line as a single string.
2328 The rest of the input line as a single string.
2329 _stack_depth : int
2329 _stack_depth : int
2330 If run_line_magic() is called from magic() then _stack_depth=2.
2330 If run_line_magic() is called from magic() then _stack_depth=2.
2331 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2331 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2332 """
2332 """
2333 fn = self._find_with_lazy_load("line", magic_name)
2333 fn = self._find_with_lazy_load("line", magic_name)
2334 if fn is None:
2334 if fn is None:
2335 lazy = self.magics_manager.lazy_magics.get(magic_name)
2335 lazy = self.magics_manager.lazy_magics.get(magic_name)
2336 if lazy:
2336 if lazy:
2337 self.run_line_magic("load_ext", lazy)
2337 self.run_line_magic("load_ext", lazy)
2338 fn = self.find_line_magic(magic_name)
2338 fn = self.find_line_magic(magic_name)
2339 if fn is None:
2339 if fn is None:
2340 cm = self.find_cell_magic(magic_name)
2340 cm = self.find_cell_magic(magic_name)
2341 etpl = "Line magic function `%%%s` not found%s."
2341 etpl = "Line magic function `%%%s` not found%s."
2342 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2342 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2343 'did you mean that instead?)' % magic_name )
2343 'did you mean that instead?)' % magic_name )
2344 raise UsageError(etpl % (magic_name, extra))
2344 raise UsageError(etpl % (magic_name, extra))
2345 else:
2345 else:
2346 # Note: this is the distance in the stack to the user's frame.
2346 # Note: this is the distance in the stack to the user's frame.
2347 # This will need to be updated if the internal calling logic gets
2347 # This will need to be updated if the internal calling logic gets
2348 # refactored, or else we'll be expanding the wrong variables.
2348 # refactored, or else we'll be expanding the wrong variables.
2349
2349
2350 # Determine stack_depth depending on where run_line_magic() has been called
2350 # Determine stack_depth depending on where run_line_magic() has been called
2351 stack_depth = _stack_depth
2351 stack_depth = _stack_depth
2352 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2352 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2353 # magic has opted out of var_expand
2353 # magic has opted out of var_expand
2354 magic_arg_s = line
2354 magic_arg_s = line
2355 else:
2355 else:
2356 magic_arg_s = self.var_expand(line, stack_depth)
2356 magic_arg_s = self.var_expand(line, stack_depth)
2357 # Put magic args in a list so we can call with f(*a) syntax
2357 # Put magic args in a list so we can call with f(*a) syntax
2358 args = [magic_arg_s]
2358 args = [magic_arg_s]
2359 kwargs = {}
2359 kwargs = {}
2360 # Grab local namespace if we need it:
2360 # Grab local namespace if we need it:
2361 if getattr(fn, "needs_local_scope", False):
2361 if getattr(fn, "needs_local_scope", False):
2362 kwargs['local_ns'] = self.get_local_scope(stack_depth)
2362 kwargs['local_ns'] = self.get_local_scope(stack_depth)
2363 with self.builtin_trap:
2363 with self.builtin_trap:
2364 result = fn(*args, **kwargs)
2364 result = fn(*args, **kwargs)
2365
2365
2366 # The code below prevents output from being displayed
2366 # The code below prevents the output from being displayed
2367 # when using magic %time.
2367 # when using magics with decodator @output_can_be_disabled
2368 # Output from '%time foo();', for instance, would never
2368 # when the last Python token in the expression is a ';'.
2369 # be displayed.
2369 if getattr(fn, magic.MAGIC_OUTPUT_CAN_BE_DISABLED, False):
2370 if magic_name == "time" and len(magic_arg_s) > 0 and magic_arg_s[-1] == ";":
2370 if DisplayHook.semicolon_at_end_of_expression(magic_arg_s):
2371 return None
2371 return None
2372
2372
2373 return result
2373 return result
2374
2374
2375 def get_local_scope(self, stack_depth):
2375 def get_local_scope(self, stack_depth):
2376 """Get local scope at given stack depth.
2376 """Get local scope at given stack depth.
2377
2377
2378 Parameters
2378 Parameters
2379 ----------
2379 ----------
2380 stack_depth : int
2380 stack_depth : int
2381 Depth relative to calling frame
2381 Depth relative to calling frame
2382 """
2382 """
2383 return sys._getframe(stack_depth + 1).f_locals
2383 return sys._getframe(stack_depth + 1).f_locals
2384
2384
2385 def run_cell_magic(self, magic_name, line, cell):
2385 def run_cell_magic(self, magic_name, line, cell):
2386 """Execute the given cell magic.
2386 """Execute the given cell magic.
2387
2387
2388 Parameters
2388 Parameters
2389 ----------
2389 ----------
2390 magic_name : str
2390 magic_name : str
2391 Name of the desired magic function, without '%' prefix.
2391 Name of the desired magic function, without '%' prefix.
2392 line : str
2392 line : str
2393 The rest of the first input line as a single string.
2393 The rest of the first input line as a single string.
2394 cell : str
2394 cell : str
2395 The body of the cell as a (possibly multiline) string.
2395 The body of the cell as a (possibly multiline) string.
2396 """
2396 """
2397 fn = self._find_with_lazy_load("cell", magic_name)
2397 fn = self._find_with_lazy_load("cell", magic_name)
2398 if fn is None:
2398 if fn is None:
2399 lm = self.find_line_magic(magic_name)
2399 lm = self.find_line_magic(magic_name)
2400 etpl = "Cell magic `%%{0}` not found{1}."
2400 etpl = "Cell magic `%%{0}` not found{1}."
2401 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2401 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2402 'did you mean that instead?)'.format(magic_name))
2402 'did you mean that instead?)'.format(magic_name))
2403 raise UsageError(etpl.format(magic_name, extra))
2403 raise UsageError(etpl.format(magic_name, extra))
2404 elif cell == '':
2404 elif cell == '':
2405 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2405 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2406 if self.find_line_magic(magic_name) is not None:
2406 if self.find_line_magic(magic_name) is not None:
2407 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2407 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2408 raise UsageError(message)
2408 raise UsageError(message)
2409 else:
2409 else:
2410 # Note: this is the distance in the stack to the user's frame.
2410 # Note: this is the distance in the stack to the user's frame.
2411 # This will need to be updated if the internal calling logic gets
2411 # This will need to be updated if the internal calling logic gets
2412 # refactored, or else we'll be expanding the wrong variables.
2412 # refactored, or else we'll be expanding the wrong variables.
2413 stack_depth = 2
2413 stack_depth = 2
2414 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2414 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2415 # magic has opted out of var_expand
2415 # magic has opted out of var_expand
2416 magic_arg_s = line
2416 magic_arg_s = line
2417 else:
2417 else:
2418 magic_arg_s = self.var_expand(line, stack_depth)
2418 magic_arg_s = self.var_expand(line, stack_depth)
2419 kwargs = {}
2419 kwargs = {}
2420 if getattr(fn, "needs_local_scope", False):
2420 if getattr(fn, "needs_local_scope", False):
2421 kwargs['local_ns'] = self.user_ns
2421 kwargs['local_ns'] = self.user_ns
2422
2422
2423 with self.builtin_trap:
2423 with self.builtin_trap:
2424 args = (magic_arg_s, cell)
2424 args = (magic_arg_s, cell)
2425 result = fn(*args, **kwargs)
2425 result = fn(*args, **kwargs)
2426 return result
2426 return result
2427
2427
2428 def find_line_magic(self, magic_name):
2428 def find_line_magic(self, magic_name):
2429 """Find and return a line magic by name.
2429 """Find and return a line magic by name.
2430
2430
2431 Returns None if the magic isn't found."""
2431 Returns None if the magic isn't found."""
2432 return self.magics_manager.magics['line'].get(magic_name)
2432 return self.magics_manager.magics['line'].get(magic_name)
2433
2433
2434 def find_cell_magic(self, magic_name):
2434 def find_cell_magic(self, magic_name):
2435 """Find and return a cell magic by name.
2435 """Find and return a cell magic by name.
2436
2436
2437 Returns None if the magic isn't found."""
2437 Returns None if the magic isn't found."""
2438 return self.magics_manager.magics['cell'].get(magic_name)
2438 return self.magics_manager.magics['cell'].get(magic_name)
2439
2439
2440 def find_magic(self, magic_name, magic_kind='line'):
2440 def find_magic(self, magic_name, magic_kind='line'):
2441 """Find and return a magic of the given type by name.
2441 """Find and return a magic of the given type by name.
2442
2442
2443 Returns None if the magic isn't found."""
2443 Returns None if the magic isn't found."""
2444 return self.magics_manager.magics[magic_kind].get(magic_name)
2444 return self.magics_manager.magics[magic_kind].get(magic_name)
2445
2445
2446 def magic(self, arg_s):
2446 def magic(self, arg_s):
2447 """
2447 """
2448 DEPRECATED
2448 DEPRECATED
2449
2449
2450 Deprecated since IPython 0.13 (warning added in
2450 Deprecated since IPython 0.13 (warning added in
2451 8.1), use run_line_magic(magic_name, parameter_s).
2451 8.1), use run_line_magic(magic_name, parameter_s).
2452
2452
2453 Call a magic function by name.
2453 Call a magic function by name.
2454
2454
2455 Input: a string containing the name of the magic function to call and
2455 Input: a string containing the name of the magic function to call and
2456 any additional arguments to be passed to the magic.
2456 any additional arguments to be passed to the magic.
2457
2457
2458 magic('name -opt foo bar') is equivalent to typing at the ipython
2458 magic('name -opt foo bar') is equivalent to typing at the ipython
2459 prompt:
2459 prompt:
2460
2460
2461 In[1]: %name -opt foo bar
2461 In[1]: %name -opt foo bar
2462
2462
2463 To call a magic without arguments, simply use magic('name').
2463 To call a magic without arguments, simply use magic('name').
2464
2464
2465 This provides a proper Python function to call IPython's magics in any
2465 This provides a proper Python function to call IPython's magics in any
2466 valid Python code you can type at the interpreter, including loops and
2466 valid Python code you can type at the interpreter, including loops and
2467 compound statements.
2467 compound statements.
2468 """
2468 """
2469 warnings.warn(
2469 warnings.warn(
2470 "`magic(...)` is deprecated since IPython 0.13 (warning added in "
2470 "`magic(...)` is deprecated since IPython 0.13 (warning added in "
2471 "8.1), use run_line_magic(magic_name, parameter_s).",
2471 "8.1), use run_line_magic(magic_name, parameter_s).",
2472 DeprecationWarning,
2472 DeprecationWarning,
2473 stacklevel=2,
2473 stacklevel=2,
2474 )
2474 )
2475 # TODO: should we issue a loud deprecation warning here?
2475 # TODO: should we issue a loud deprecation warning here?
2476 magic_name, _, magic_arg_s = arg_s.partition(' ')
2476 magic_name, _, magic_arg_s = arg_s.partition(' ')
2477 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2477 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2478 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2478 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2479
2479
2480 #-------------------------------------------------------------------------
2480 #-------------------------------------------------------------------------
2481 # Things related to macros
2481 # Things related to macros
2482 #-------------------------------------------------------------------------
2482 #-------------------------------------------------------------------------
2483
2483
2484 def define_macro(self, name, themacro):
2484 def define_macro(self, name, themacro):
2485 """Define a new macro
2485 """Define a new macro
2486
2486
2487 Parameters
2487 Parameters
2488 ----------
2488 ----------
2489 name : str
2489 name : str
2490 The name of the macro.
2490 The name of the macro.
2491 themacro : str or Macro
2491 themacro : str or Macro
2492 The action to do upon invoking the macro. If a string, a new
2492 The action to do upon invoking the macro. If a string, a new
2493 Macro object is created by passing the string to it.
2493 Macro object is created by passing the string to it.
2494 """
2494 """
2495
2495
2496 from IPython.core import macro
2496 from IPython.core import macro
2497
2497
2498 if isinstance(themacro, str):
2498 if isinstance(themacro, str):
2499 themacro = macro.Macro(themacro)
2499 themacro = macro.Macro(themacro)
2500 if not isinstance(themacro, macro.Macro):
2500 if not isinstance(themacro, macro.Macro):
2501 raise ValueError('A macro must be a string or a Macro instance.')
2501 raise ValueError('A macro must be a string or a Macro instance.')
2502 self.user_ns[name] = themacro
2502 self.user_ns[name] = themacro
2503
2503
2504 #-------------------------------------------------------------------------
2504 #-------------------------------------------------------------------------
2505 # Things related to the running of system commands
2505 # Things related to the running of system commands
2506 #-------------------------------------------------------------------------
2506 #-------------------------------------------------------------------------
2507
2507
2508 def system_piped(self, cmd):
2508 def system_piped(self, cmd):
2509 """Call the given cmd in a subprocess, piping stdout/err
2509 """Call the given cmd in a subprocess, piping stdout/err
2510
2510
2511 Parameters
2511 Parameters
2512 ----------
2512 ----------
2513 cmd : str
2513 cmd : str
2514 Command to execute (can not end in '&', as background processes are
2514 Command to execute (can not end in '&', as background processes are
2515 not supported. Should not be a command that expects input
2515 not supported. Should not be a command that expects input
2516 other than simple text.
2516 other than simple text.
2517 """
2517 """
2518 if cmd.rstrip().endswith('&'):
2518 if cmd.rstrip().endswith('&'):
2519 # this is *far* from a rigorous test
2519 # this is *far* from a rigorous test
2520 # We do not support backgrounding processes because we either use
2520 # We do not support backgrounding processes because we either use
2521 # pexpect or pipes to read from. Users can always just call
2521 # pexpect or pipes to read from. Users can always just call
2522 # os.system() or use ip.system=ip.system_raw
2522 # os.system() or use ip.system=ip.system_raw
2523 # if they really want a background process.
2523 # if they really want a background process.
2524 raise OSError("Background processes not supported.")
2524 raise OSError("Background processes not supported.")
2525
2525
2526 # we explicitly do NOT return the subprocess status code, because
2526 # we explicitly do NOT return the subprocess status code, because
2527 # a non-None value would trigger :func:`sys.displayhook` calls.
2527 # a non-None value would trigger :func:`sys.displayhook` calls.
2528 # Instead, we store the exit_code in user_ns.
2528 # Instead, we store the exit_code in user_ns.
2529 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2529 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2530
2530
2531 def system_raw(self, cmd):
2531 def system_raw(self, cmd):
2532 """Call the given cmd in a subprocess using os.system on Windows or
2532 """Call the given cmd in a subprocess using os.system on Windows or
2533 subprocess.call using the system shell on other platforms.
2533 subprocess.call using the system shell on other platforms.
2534
2534
2535 Parameters
2535 Parameters
2536 ----------
2536 ----------
2537 cmd : str
2537 cmd : str
2538 Command to execute.
2538 Command to execute.
2539 """
2539 """
2540 cmd = self.var_expand(cmd, depth=1)
2540 cmd = self.var_expand(cmd, depth=1)
2541 # warn if there is an IPython magic alternative.
2541 # warn if there is an IPython magic alternative.
2542 main_cmd = cmd.split()[0]
2542 main_cmd = cmd.split()[0]
2543 has_magic_alternatives = ("pip", "conda", "cd")
2543 has_magic_alternatives = ("pip", "conda", "cd")
2544
2544
2545 if main_cmd in has_magic_alternatives:
2545 if main_cmd in has_magic_alternatives:
2546 warnings.warn(
2546 warnings.warn(
2547 (
2547 (
2548 "You executed the system command !{0} which may not work "
2548 "You executed the system command !{0} which may not work "
2549 "as expected. Try the IPython magic %{0} instead."
2549 "as expected. Try the IPython magic %{0} instead."
2550 ).format(main_cmd)
2550 ).format(main_cmd)
2551 )
2551 )
2552
2552
2553 # protect os.system from UNC paths on Windows, which it can't handle:
2553 # protect os.system from UNC paths on Windows, which it can't handle:
2554 if sys.platform == 'win32':
2554 if sys.platform == 'win32':
2555 from IPython.utils._process_win32 import AvoidUNCPath
2555 from IPython.utils._process_win32 import AvoidUNCPath
2556 with AvoidUNCPath() as path:
2556 with AvoidUNCPath() as path:
2557 if path is not None:
2557 if path is not None:
2558 cmd = '"pushd %s &&"%s' % (path, cmd)
2558 cmd = '"pushd %s &&"%s' % (path, cmd)
2559 try:
2559 try:
2560 ec = os.system(cmd)
2560 ec = os.system(cmd)
2561 except KeyboardInterrupt:
2561 except KeyboardInterrupt:
2562 print('\n' + self.get_exception_only(), file=sys.stderr)
2562 print('\n' + self.get_exception_only(), file=sys.stderr)
2563 ec = -2
2563 ec = -2
2564 else:
2564 else:
2565 # For posix the result of the subprocess.call() below is an exit
2565 # For posix the result of the subprocess.call() below is an exit
2566 # code, which by convention is zero for success, positive for
2566 # code, which by convention is zero for success, positive for
2567 # program failure. Exit codes above 128 are reserved for signals,
2567 # program failure. Exit codes above 128 are reserved for signals,
2568 # and the formula for converting a signal to an exit code is usually
2568 # and the formula for converting a signal to an exit code is usually
2569 # signal_number+128. To more easily differentiate between exit
2569 # signal_number+128. To more easily differentiate between exit
2570 # codes and signals, ipython uses negative numbers. For instance
2570 # codes and signals, ipython uses negative numbers. For instance
2571 # since control-c is signal 2 but exit code 130, ipython's
2571 # since control-c is signal 2 but exit code 130, ipython's
2572 # _exit_code variable will read -2. Note that some shells like
2572 # _exit_code variable will read -2. Note that some shells like
2573 # csh and fish don't follow sh/bash conventions for exit codes.
2573 # csh and fish don't follow sh/bash conventions for exit codes.
2574 executable = os.environ.get('SHELL', None)
2574 executable = os.environ.get('SHELL', None)
2575 try:
2575 try:
2576 # Use env shell instead of default /bin/sh
2576 # Use env shell instead of default /bin/sh
2577 ec = subprocess.call(cmd, shell=True, executable=executable)
2577 ec = subprocess.call(cmd, shell=True, executable=executable)
2578 except KeyboardInterrupt:
2578 except KeyboardInterrupt:
2579 # intercept control-C; a long traceback is not useful here
2579 # intercept control-C; a long traceback is not useful here
2580 print('\n' + self.get_exception_only(), file=sys.stderr)
2580 print('\n' + self.get_exception_only(), file=sys.stderr)
2581 ec = 130
2581 ec = 130
2582 if ec > 128:
2582 if ec > 128:
2583 ec = -(ec - 128)
2583 ec = -(ec - 128)
2584
2584
2585 # We explicitly do NOT return the subprocess status code, because
2585 # We explicitly do NOT return the subprocess status code, because
2586 # a non-None value would trigger :func:`sys.displayhook` calls.
2586 # a non-None value would trigger :func:`sys.displayhook` calls.
2587 # Instead, we store the exit_code in user_ns. Note the semantics
2587 # Instead, we store the exit_code in user_ns. Note the semantics
2588 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2588 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2589 # but raising SystemExit(_exit_code) will give status 254!
2589 # but raising SystemExit(_exit_code) will give status 254!
2590 self.user_ns['_exit_code'] = ec
2590 self.user_ns['_exit_code'] = ec
2591
2591
2592 # use piped system by default, because it is better behaved
2592 # use piped system by default, because it is better behaved
2593 system = system_piped
2593 system = system_piped
2594
2594
2595 def getoutput(self, cmd, split=True, depth=0):
2595 def getoutput(self, cmd, split=True, depth=0):
2596 """Get output (possibly including stderr) from a subprocess.
2596 """Get output (possibly including stderr) from a subprocess.
2597
2597
2598 Parameters
2598 Parameters
2599 ----------
2599 ----------
2600 cmd : str
2600 cmd : str
2601 Command to execute (can not end in '&', as background processes are
2601 Command to execute (can not end in '&', as background processes are
2602 not supported.
2602 not supported.
2603 split : bool, optional
2603 split : bool, optional
2604 If True, split the output into an IPython SList. Otherwise, an
2604 If True, split the output into an IPython SList. Otherwise, an
2605 IPython LSString is returned. These are objects similar to normal
2605 IPython LSString is returned. These are objects similar to normal
2606 lists and strings, with a few convenience attributes for easier
2606 lists and strings, with a few convenience attributes for easier
2607 manipulation of line-based output. You can use '?' on them for
2607 manipulation of line-based output. You can use '?' on them for
2608 details.
2608 details.
2609 depth : int, optional
2609 depth : int, optional
2610 How many frames above the caller are the local variables which should
2610 How many frames above the caller are the local variables which should
2611 be expanded in the command string? The default (0) assumes that the
2611 be expanded in the command string? The default (0) assumes that the
2612 expansion variables are in the stack frame calling this function.
2612 expansion variables are in the stack frame calling this function.
2613 """
2613 """
2614 if cmd.rstrip().endswith('&'):
2614 if cmd.rstrip().endswith('&'):
2615 # this is *far* from a rigorous test
2615 # this is *far* from a rigorous test
2616 raise OSError("Background processes not supported.")
2616 raise OSError("Background processes not supported.")
2617 out = getoutput(self.var_expand(cmd, depth=depth+1))
2617 out = getoutput(self.var_expand(cmd, depth=depth+1))
2618 if split:
2618 if split:
2619 out = SList(out.splitlines())
2619 out = SList(out.splitlines())
2620 else:
2620 else:
2621 out = LSString(out)
2621 out = LSString(out)
2622 return out
2622 return out
2623
2623
2624 #-------------------------------------------------------------------------
2624 #-------------------------------------------------------------------------
2625 # Things related to aliases
2625 # Things related to aliases
2626 #-------------------------------------------------------------------------
2626 #-------------------------------------------------------------------------
2627
2627
2628 def init_alias(self):
2628 def init_alias(self):
2629 self.alias_manager = AliasManager(shell=self, parent=self)
2629 self.alias_manager = AliasManager(shell=self, parent=self)
2630 self.configurables.append(self.alias_manager)
2630 self.configurables.append(self.alias_manager)
2631
2631
2632 #-------------------------------------------------------------------------
2632 #-------------------------------------------------------------------------
2633 # Things related to extensions
2633 # Things related to extensions
2634 #-------------------------------------------------------------------------
2634 #-------------------------------------------------------------------------
2635
2635
2636 def init_extension_manager(self):
2636 def init_extension_manager(self):
2637 self.extension_manager = ExtensionManager(shell=self, parent=self)
2637 self.extension_manager = ExtensionManager(shell=self, parent=self)
2638 self.configurables.append(self.extension_manager)
2638 self.configurables.append(self.extension_manager)
2639
2639
2640 #-------------------------------------------------------------------------
2640 #-------------------------------------------------------------------------
2641 # Things related to payloads
2641 # Things related to payloads
2642 #-------------------------------------------------------------------------
2642 #-------------------------------------------------------------------------
2643
2643
2644 def init_payload(self):
2644 def init_payload(self):
2645 self.payload_manager = PayloadManager(parent=self)
2645 self.payload_manager = PayloadManager(parent=self)
2646 self.configurables.append(self.payload_manager)
2646 self.configurables.append(self.payload_manager)
2647
2647
2648 #-------------------------------------------------------------------------
2648 #-------------------------------------------------------------------------
2649 # Things related to the prefilter
2649 # Things related to the prefilter
2650 #-------------------------------------------------------------------------
2650 #-------------------------------------------------------------------------
2651
2651
2652 def init_prefilter(self):
2652 def init_prefilter(self):
2653 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2653 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2654 self.configurables.append(self.prefilter_manager)
2654 self.configurables.append(self.prefilter_manager)
2655 # Ultimately this will be refactored in the new interpreter code, but
2655 # Ultimately this will be refactored in the new interpreter code, but
2656 # for now, we should expose the main prefilter method (there's legacy
2656 # for now, we should expose the main prefilter method (there's legacy
2657 # code out there that may rely on this).
2657 # code out there that may rely on this).
2658 self.prefilter = self.prefilter_manager.prefilter_lines
2658 self.prefilter = self.prefilter_manager.prefilter_lines
2659
2659
2660 def auto_rewrite_input(self, cmd):
2660 def auto_rewrite_input(self, cmd):
2661 """Print to the screen the rewritten form of the user's command.
2661 """Print to the screen the rewritten form of the user's command.
2662
2662
2663 This shows visual feedback by rewriting input lines that cause
2663 This shows visual feedback by rewriting input lines that cause
2664 automatic calling to kick in, like::
2664 automatic calling to kick in, like::
2665
2665
2666 /f x
2666 /f x
2667
2667
2668 into::
2668 into::
2669
2669
2670 ------> f(x)
2670 ------> f(x)
2671
2671
2672 after the user's input prompt. This helps the user understand that the
2672 after the user's input prompt. This helps the user understand that the
2673 input line was transformed automatically by IPython.
2673 input line was transformed automatically by IPython.
2674 """
2674 """
2675 if not self.show_rewritten_input:
2675 if not self.show_rewritten_input:
2676 return
2676 return
2677
2677
2678 # This is overridden in TerminalInteractiveShell to use fancy prompts
2678 # This is overridden in TerminalInteractiveShell to use fancy prompts
2679 print("------> " + cmd)
2679 print("------> " + cmd)
2680
2680
2681 #-------------------------------------------------------------------------
2681 #-------------------------------------------------------------------------
2682 # Things related to extracting values/expressions from kernel and user_ns
2682 # Things related to extracting values/expressions from kernel and user_ns
2683 #-------------------------------------------------------------------------
2683 #-------------------------------------------------------------------------
2684
2684
2685 def _user_obj_error(self):
2685 def _user_obj_error(self):
2686 """return simple exception dict
2686 """return simple exception dict
2687
2687
2688 for use in user_expressions
2688 for use in user_expressions
2689 """
2689 """
2690
2690
2691 etype, evalue, tb = self._get_exc_info()
2691 etype, evalue, tb = self._get_exc_info()
2692 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2692 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2693
2693
2694 exc_info = {
2694 exc_info = {
2695 "status": "error",
2695 "status": "error",
2696 "traceback": stb,
2696 "traceback": stb,
2697 "ename": etype.__name__,
2697 "ename": etype.__name__,
2698 "evalue": py3compat.safe_unicode(evalue),
2698 "evalue": py3compat.safe_unicode(evalue),
2699 }
2699 }
2700
2700
2701 return exc_info
2701 return exc_info
2702
2702
2703 def _format_user_obj(self, obj):
2703 def _format_user_obj(self, obj):
2704 """format a user object to display dict
2704 """format a user object to display dict
2705
2705
2706 for use in user_expressions
2706 for use in user_expressions
2707 """
2707 """
2708
2708
2709 data, md = self.display_formatter.format(obj)
2709 data, md = self.display_formatter.format(obj)
2710 value = {
2710 value = {
2711 'status' : 'ok',
2711 'status' : 'ok',
2712 'data' : data,
2712 'data' : data,
2713 'metadata' : md,
2713 'metadata' : md,
2714 }
2714 }
2715 return value
2715 return value
2716
2716
2717 def user_expressions(self, expressions):
2717 def user_expressions(self, expressions):
2718 """Evaluate a dict of expressions in the user's namespace.
2718 """Evaluate a dict of expressions in the user's namespace.
2719
2719
2720 Parameters
2720 Parameters
2721 ----------
2721 ----------
2722 expressions : dict
2722 expressions : dict
2723 A dict with string keys and string values. The expression values
2723 A dict with string keys and string values. The expression values
2724 should be valid Python expressions, each of which will be evaluated
2724 should be valid Python expressions, each of which will be evaluated
2725 in the user namespace.
2725 in the user namespace.
2726
2726
2727 Returns
2727 Returns
2728 -------
2728 -------
2729 A dict, keyed like the input expressions dict, with the rich mime-typed
2729 A dict, keyed like the input expressions dict, with the rich mime-typed
2730 display_data of each value.
2730 display_data of each value.
2731 """
2731 """
2732 out = {}
2732 out = {}
2733 user_ns = self.user_ns
2733 user_ns = self.user_ns
2734 global_ns = self.user_global_ns
2734 global_ns = self.user_global_ns
2735
2735
2736 for key, expr in expressions.items():
2736 for key, expr in expressions.items():
2737 try:
2737 try:
2738 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2738 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2739 except:
2739 except:
2740 value = self._user_obj_error()
2740 value = self._user_obj_error()
2741 out[key] = value
2741 out[key] = value
2742 return out
2742 return out
2743
2743
2744 #-------------------------------------------------------------------------
2744 #-------------------------------------------------------------------------
2745 # Things related to the running of code
2745 # Things related to the running of code
2746 #-------------------------------------------------------------------------
2746 #-------------------------------------------------------------------------
2747
2747
2748 def ex(self, cmd):
2748 def ex(self, cmd):
2749 """Execute a normal python statement in user namespace."""
2749 """Execute a normal python statement in user namespace."""
2750 with self.builtin_trap:
2750 with self.builtin_trap:
2751 exec(cmd, self.user_global_ns, self.user_ns)
2751 exec(cmd, self.user_global_ns, self.user_ns)
2752
2752
2753 def ev(self, expr):
2753 def ev(self, expr):
2754 """Evaluate python expression expr in user namespace.
2754 """Evaluate python expression expr in user namespace.
2755
2755
2756 Returns the result of evaluation
2756 Returns the result of evaluation
2757 """
2757 """
2758 with self.builtin_trap:
2758 with self.builtin_trap:
2759 return eval(expr, self.user_global_ns, self.user_ns)
2759 return eval(expr, self.user_global_ns, self.user_ns)
2760
2760
2761 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2761 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2762 """A safe version of the builtin execfile().
2762 """A safe version of the builtin execfile().
2763
2763
2764 This version will never throw an exception, but instead print
2764 This version will never throw an exception, but instead print
2765 helpful error messages to the screen. This only works on pure
2765 helpful error messages to the screen. This only works on pure
2766 Python files with the .py extension.
2766 Python files with the .py extension.
2767
2767
2768 Parameters
2768 Parameters
2769 ----------
2769 ----------
2770 fname : string
2770 fname : string
2771 The name of the file to be executed.
2771 The name of the file to be executed.
2772 *where : tuple
2772 *where : tuple
2773 One or two namespaces, passed to execfile() as (globals,locals).
2773 One or two namespaces, passed to execfile() as (globals,locals).
2774 If only one is given, it is passed as both.
2774 If only one is given, it is passed as both.
2775 exit_ignore : bool (False)
2775 exit_ignore : bool (False)
2776 If True, then silence SystemExit for non-zero status (it is always
2776 If True, then silence SystemExit for non-zero status (it is always
2777 silenced for zero status, as it is so common).
2777 silenced for zero status, as it is so common).
2778 raise_exceptions : bool (False)
2778 raise_exceptions : bool (False)
2779 If True raise exceptions everywhere. Meant for testing.
2779 If True raise exceptions everywhere. Meant for testing.
2780 shell_futures : bool (False)
2780 shell_futures : bool (False)
2781 If True, the code will share future statements with the interactive
2781 If True, the code will share future statements with the interactive
2782 shell. It will both be affected by previous __future__ imports, and
2782 shell. It will both be affected by previous __future__ imports, and
2783 any __future__ imports in the code will affect the shell. If False,
2783 any __future__ imports in the code will affect the shell. If False,
2784 __future__ imports are not shared in either direction.
2784 __future__ imports are not shared in either direction.
2785
2785
2786 """
2786 """
2787 fname = Path(fname).expanduser().resolve()
2787 fname = Path(fname).expanduser().resolve()
2788
2788
2789 # Make sure we can open the file
2789 # Make sure we can open the file
2790 try:
2790 try:
2791 with fname.open("rb"):
2791 with fname.open("rb"):
2792 pass
2792 pass
2793 except:
2793 except:
2794 warn('Could not open file <%s> for safe execution.' % fname)
2794 warn('Could not open file <%s> for safe execution.' % fname)
2795 return
2795 return
2796
2796
2797 # Find things also in current directory. This is needed to mimic the
2797 # Find things also in current directory. This is needed to mimic the
2798 # behavior of running a script from the system command line, where
2798 # behavior of running a script from the system command line, where
2799 # Python inserts the script's directory into sys.path
2799 # Python inserts the script's directory into sys.path
2800 dname = str(fname.parent)
2800 dname = str(fname.parent)
2801
2801
2802 with prepended_to_syspath(dname), self.builtin_trap:
2802 with prepended_to_syspath(dname), self.builtin_trap:
2803 try:
2803 try:
2804 glob, loc = (where + (None, ))[:2]
2804 glob, loc = (where + (None, ))[:2]
2805 py3compat.execfile(
2805 py3compat.execfile(
2806 fname, glob, loc,
2806 fname, glob, loc,
2807 self.compile if shell_futures else None)
2807 self.compile if shell_futures else None)
2808 except SystemExit as status:
2808 except SystemExit as status:
2809 # If the call was made with 0 or None exit status (sys.exit(0)
2809 # If the call was made with 0 or None exit status (sys.exit(0)
2810 # or sys.exit() ), don't bother showing a traceback, as both of
2810 # or sys.exit() ), don't bother showing a traceback, as both of
2811 # these are considered normal by the OS:
2811 # these are considered normal by the OS:
2812 # > python -c'import sys;sys.exit(0)'; echo $?
2812 # > python -c'import sys;sys.exit(0)'; echo $?
2813 # 0
2813 # 0
2814 # > python -c'import sys;sys.exit()'; echo $?
2814 # > python -c'import sys;sys.exit()'; echo $?
2815 # 0
2815 # 0
2816 # For other exit status, we show the exception unless
2816 # For other exit status, we show the exception unless
2817 # explicitly silenced, but only in short form.
2817 # explicitly silenced, but only in short form.
2818 if status.code:
2818 if status.code:
2819 if raise_exceptions:
2819 if raise_exceptions:
2820 raise
2820 raise
2821 if not exit_ignore:
2821 if not exit_ignore:
2822 self.showtraceback(exception_only=True)
2822 self.showtraceback(exception_only=True)
2823 except:
2823 except:
2824 if raise_exceptions:
2824 if raise_exceptions:
2825 raise
2825 raise
2826 # tb offset is 2 because we wrap execfile
2826 # tb offset is 2 because we wrap execfile
2827 self.showtraceback(tb_offset=2)
2827 self.showtraceback(tb_offset=2)
2828
2828
2829 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2829 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2830 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2830 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2831
2831
2832 Parameters
2832 Parameters
2833 ----------
2833 ----------
2834 fname : str
2834 fname : str
2835 The name of the file to execute. The filename must have a
2835 The name of the file to execute. The filename must have a
2836 .ipy or .ipynb extension.
2836 .ipy or .ipynb extension.
2837 shell_futures : bool (False)
2837 shell_futures : bool (False)
2838 If True, the code will share future statements with the interactive
2838 If True, the code will share future statements with the interactive
2839 shell. It will both be affected by previous __future__ imports, and
2839 shell. It will both be affected by previous __future__ imports, and
2840 any __future__ imports in the code will affect the shell. If False,
2840 any __future__ imports in the code will affect the shell. If False,
2841 __future__ imports are not shared in either direction.
2841 __future__ imports are not shared in either direction.
2842 raise_exceptions : bool (False)
2842 raise_exceptions : bool (False)
2843 If True raise exceptions everywhere. Meant for testing.
2843 If True raise exceptions everywhere. Meant for testing.
2844 """
2844 """
2845 fname = Path(fname).expanduser().resolve()
2845 fname = Path(fname).expanduser().resolve()
2846
2846
2847 # Make sure we can open the file
2847 # Make sure we can open the file
2848 try:
2848 try:
2849 with fname.open("rb"):
2849 with fname.open("rb"):
2850 pass
2850 pass
2851 except:
2851 except:
2852 warn('Could not open file <%s> for safe execution.' % fname)
2852 warn('Could not open file <%s> for safe execution.' % fname)
2853 return
2853 return
2854
2854
2855 # Find things also in current directory. This is needed to mimic the
2855 # Find things also in current directory. This is needed to mimic the
2856 # behavior of running a script from the system command line, where
2856 # behavior of running a script from the system command line, where
2857 # Python inserts the script's directory into sys.path
2857 # Python inserts the script's directory into sys.path
2858 dname = str(fname.parent)
2858 dname = str(fname.parent)
2859
2859
2860 def get_cells():
2860 def get_cells():
2861 """generator for sequence of code blocks to run"""
2861 """generator for sequence of code blocks to run"""
2862 if fname.suffix == ".ipynb":
2862 if fname.suffix == ".ipynb":
2863 from nbformat import read
2863 from nbformat import read
2864 nb = read(fname, as_version=4)
2864 nb = read(fname, as_version=4)
2865 if not nb.cells:
2865 if not nb.cells:
2866 return
2866 return
2867 for cell in nb.cells:
2867 for cell in nb.cells:
2868 if cell.cell_type == 'code':
2868 if cell.cell_type == 'code':
2869 yield cell.source
2869 yield cell.source
2870 else:
2870 else:
2871 yield fname.read_text(encoding="utf-8")
2871 yield fname.read_text(encoding="utf-8")
2872
2872
2873 with prepended_to_syspath(dname):
2873 with prepended_to_syspath(dname):
2874 try:
2874 try:
2875 for cell in get_cells():
2875 for cell in get_cells():
2876 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2876 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2877 if raise_exceptions:
2877 if raise_exceptions:
2878 result.raise_error()
2878 result.raise_error()
2879 elif not result.success:
2879 elif not result.success:
2880 break
2880 break
2881 except:
2881 except:
2882 if raise_exceptions:
2882 if raise_exceptions:
2883 raise
2883 raise
2884 self.showtraceback()
2884 self.showtraceback()
2885 warn('Unknown failure executing file: <%s>' % fname)
2885 warn('Unknown failure executing file: <%s>' % fname)
2886
2886
2887 def safe_run_module(self, mod_name, where):
2887 def safe_run_module(self, mod_name, where):
2888 """A safe version of runpy.run_module().
2888 """A safe version of runpy.run_module().
2889
2889
2890 This version will never throw an exception, but instead print
2890 This version will never throw an exception, but instead print
2891 helpful error messages to the screen.
2891 helpful error messages to the screen.
2892
2892
2893 `SystemExit` exceptions with status code 0 or None are ignored.
2893 `SystemExit` exceptions with status code 0 or None are ignored.
2894
2894
2895 Parameters
2895 Parameters
2896 ----------
2896 ----------
2897 mod_name : string
2897 mod_name : string
2898 The name of the module to be executed.
2898 The name of the module to be executed.
2899 where : dict
2899 where : dict
2900 The globals namespace.
2900 The globals namespace.
2901 """
2901 """
2902 try:
2902 try:
2903 try:
2903 try:
2904 where.update(
2904 where.update(
2905 runpy.run_module(str(mod_name), run_name="__main__",
2905 runpy.run_module(str(mod_name), run_name="__main__",
2906 alter_sys=True)
2906 alter_sys=True)
2907 )
2907 )
2908 except SystemExit as status:
2908 except SystemExit as status:
2909 if status.code:
2909 if status.code:
2910 raise
2910 raise
2911 except:
2911 except:
2912 self.showtraceback()
2912 self.showtraceback()
2913 warn('Unknown failure executing module: <%s>' % mod_name)
2913 warn('Unknown failure executing module: <%s>' % mod_name)
2914
2914
2915 def run_cell(
2915 def run_cell(
2916 self,
2916 self,
2917 raw_cell,
2917 raw_cell,
2918 store_history=False,
2918 store_history=False,
2919 silent=False,
2919 silent=False,
2920 shell_futures=True,
2920 shell_futures=True,
2921 cell_id=None,
2921 cell_id=None,
2922 ):
2922 ):
2923 """Run a complete IPython cell.
2923 """Run a complete IPython cell.
2924
2924
2925 Parameters
2925 Parameters
2926 ----------
2926 ----------
2927 raw_cell : str
2927 raw_cell : str
2928 The code (including IPython code such as %magic functions) to run.
2928 The code (including IPython code such as %magic functions) to run.
2929 store_history : bool
2929 store_history : bool
2930 If True, the raw and translated cell will be stored in IPython's
2930 If True, the raw and translated cell will be stored in IPython's
2931 history. For user code calling back into IPython's machinery, this
2931 history. For user code calling back into IPython's machinery, this
2932 should be set to False.
2932 should be set to False.
2933 silent : bool
2933 silent : bool
2934 If True, avoid side-effects, such as implicit displayhooks and
2934 If True, avoid side-effects, such as implicit displayhooks and
2935 and logging. silent=True forces store_history=False.
2935 and logging. silent=True forces store_history=False.
2936 shell_futures : bool
2936 shell_futures : bool
2937 If True, the code will share future statements with the interactive
2937 If True, the code will share future statements with the interactive
2938 shell. It will both be affected by previous __future__ imports, and
2938 shell. It will both be affected by previous __future__ imports, and
2939 any __future__ imports in the code will affect the shell. If False,
2939 any __future__ imports in the code will affect the shell. If False,
2940 __future__ imports are not shared in either direction.
2940 __future__ imports are not shared in either direction.
2941
2941
2942 Returns
2942 Returns
2943 -------
2943 -------
2944 result : :class:`ExecutionResult`
2944 result : :class:`ExecutionResult`
2945 """
2945 """
2946 result = None
2946 result = None
2947 try:
2947 try:
2948 result = self._run_cell(
2948 result = self._run_cell(
2949 raw_cell, store_history, silent, shell_futures, cell_id
2949 raw_cell, store_history, silent, shell_futures, cell_id
2950 )
2950 )
2951 finally:
2951 finally:
2952 self.events.trigger('post_execute')
2952 self.events.trigger('post_execute')
2953 if not silent:
2953 if not silent:
2954 self.events.trigger('post_run_cell', result)
2954 self.events.trigger('post_run_cell', result)
2955 return result
2955 return result
2956
2956
2957 def _run_cell(
2957 def _run_cell(
2958 self,
2958 self,
2959 raw_cell: str,
2959 raw_cell: str,
2960 store_history: bool,
2960 store_history: bool,
2961 silent: bool,
2961 silent: bool,
2962 shell_futures: bool,
2962 shell_futures: bool,
2963 cell_id: str,
2963 cell_id: str,
2964 ) -> ExecutionResult:
2964 ) -> ExecutionResult:
2965 """Internal method to run a complete IPython cell."""
2965 """Internal method to run a complete IPython cell."""
2966
2966
2967 # we need to avoid calling self.transform_cell multiple time on the same thing
2967 # we need to avoid calling self.transform_cell multiple time on the same thing
2968 # so we need to store some results:
2968 # so we need to store some results:
2969 preprocessing_exc_tuple = None
2969 preprocessing_exc_tuple = None
2970 try:
2970 try:
2971 transformed_cell = self.transform_cell(raw_cell)
2971 transformed_cell = self.transform_cell(raw_cell)
2972 except Exception:
2972 except Exception:
2973 transformed_cell = raw_cell
2973 transformed_cell = raw_cell
2974 preprocessing_exc_tuple = sys.exc_info()
2974 preprocessing_exc_tuple = sys.exc_info()
2975
2975
2976 assert transformed_cell is not None
2976 assert transformed_cell is not None
2977 coro = self.run_cell_async(
2977 coro = self.run_cell_async(
2978 raw_cell,
2978 raw_cell,
2979 store_history=store_history,
2979 store_history=store_history,
2980 silent=silent,
2980 silent=silent,
2981 shell_futures=shell_futures,
2981 shell_futures=shell_futures,
2982 transformed_cell=transformed_cell,
2982 transformed_cell=transformed_cell,
2983 preprocessing_exc_tuple=preprocessing_exc_tuple,
2983 preprocessing_exc_tuple=preprocessing_exc_tuple,
2984 cell_id=cell_id,
2984 cell_id=cell_id,
2985 )
2985 )
2986
2986
2987 # run_cell_async is async, but may not actually need an eventloop.
2987 # run_cell_async is async, but may not actually need an eventloop.
2988 # when this is the case, we want to run it using the pseudo_sync_runner
2988 # when this is the case, we want to run it using the pseudo_sync_runner
2989 # so that code can invoke eventloops (for example via the %run , and
2989 # so that code can invoke eventloops (for example via the %run , and
2990 # `%paste` magic.
2990 # `%paste` magic.
2991 if self.trio_runner:
2991 if self.trio_runner:
2992 runner = self.trio_runner
2992 runner = self.trio_runner
2993 elif self.should_run_async(
2993 elif self.should_run_async(
2994 raw_cell,
2994 raw_cell,
2995 transformed_cell=transformed_cell,
2995 transformed_cell=transformed_cell,
2996 preprocessing_exc_tuple=preprocessing_exc_tuple,
2996 preprocessing_exc_tuple=preprocessing_exc_tuple,
2997 ):
2997 ):
2998 runner = self.loop_runner
2998 runner = self.loop_runner
2999 else:
2999 else:
3000 runner = _pseudo_sync_runner
3000 runner = _pseudo_sync_runner
3001
3001
3002 try:
3002 try:
3003 return runner(coro)
3003 return runner(coro)
3004 except BaseException as e:
3004 except BaseException as e:
3005 info = ExecutionInfo(
3005 info = ExecutionInfo(
3006 raw_cell, store_history, silent, shell_futures, cell_id
3006 raw_cell, store_history, silent, shell_futures, cell_id
3007 )
3007 )
3008 result = ExecutionResult(info)
3008 result = ExecutionResult(info)
3009 result.error_in_exec = e
3009 result.error_in_exec = e
3010 self.showtraceback(running_compiled_code=True)
3010 self.showtraceback(running_compiled_code=True)
3011 return result
3011 return result
3012
3012
3013 def should_run_async(
3013 def should_run_async(
3014 self, raw_cell: str, *, transformed_cell=None, preprocessing_exc_tuple=None
3014 self, raw_cell: str, *, transformed_cell=None, preprocessing_exc_tuple=None
3015 ) -> bool:
3015 ) -> bool:
3016 """Return whether a cell should be run asynchronously via a coroutine runner
3016 """Return whether a cell should be run asynchronously via a coroutine runner
3017
3017
3018 Parameters
3018 Parameters
3019 ----------
3019 ----------
3020 raw_cell : str
3020 raw_cell : str
3021 The code to be executed
3021 The code to be executed
3022
3022
3023 Returns
3023 Returns
3024 -------
3024 -------
3025 result: bool
3025 result: bool
3026 Whether the code needs to be run with a coroutine runner or not
3026 Whether the code needs to be run with a coroutine runner or not
3027 .. versionadded:: 7.0
3027 .. versionadded:: 7.0
3028 """
3028 """
3029 if not self.autoawait:
3029 if not self.autoawait:
3030 return False
3030 return False
3031 if preprocessing_exc_tuple is not None:
3031 if preprocessing_exc_tuple is not None:
3032 return False
3032 return False
3033 assert preprocessing_exc_tuple is None
3033 assert preprocessing_exc_tuple is None
3034 if transformed_cell is None:
3034 if transformed_cell is None:
3035 warnings.warn(
3035 warnings.warn(
3036 "`should_run_async` will not call `transform_cell`"
3036 "`should_run_async` will not call `transform_cell`"
3037 " automatically in the future. Please pass the result to"
3037 " automatically in the future. Please pass the result to"
3038 " `transformed_cell` argument and any exception that happen"
3038 " `transformed_cell` argument and any exception that happen"
3039 " during the"
3039 " during the"
3040 "transform in `preprocessing_exc_tuple` in"
3040 "transform in `preprocessing_exc_tuple` in"
3041 " IPython 7.17 and above.",
3041 " IPython 7.17 and above.",
3042 DeprecationWarning,
3042 DeprecationWarning,
3043 stacklevel=2,
3043 stacklevel=2,
3044 )
3044 )
3045 try:
3045 try:
3046 cell = self.transform_cell(raw_cell)
3046 cell = self.transform_cell(raw_cell)
3047 except Exception:
3047 except Exception:
3048 # any exception during transform will be raised
3048 # any exception during transform will be raised
3049 # prior to execution
3049 # prior to execution
3050 return False
3050 return False
3051 else:
3051 else:
3052 cell = transformed_cell
3052 cell = transformed_cell
3053 return _should_be_async(cell)
3053 return _should_be_async(cell)
3054
3054
3055 async def run_cell_async(
3055 async def run_cell_async(
3056 self,
3056 self,
3057 raw_cell: str,
3057 raw_cell: str,
3058 store_history=False,
3058 store_history=False,
3059 silent=False,
3059 silent=False,
3060 shell_futures=True,
3060 shell_futures=True,
3061 *,
3061 *,
3062 transformed_cell: Optional[str] = None,
3062 transformed_cell: Optional[str] = None,
3063 preprocessing_exc_tuple: Optional[Any] = None,
3063 preprocessing_exc_tuple: Optional[Any] = None,
3064 cell_id=None,
3064 cell_id=None,
3065 ) -> ExecutionResult:
3065 ) -> ExecutionResult:
3066 """Run a complete IPython cell asynchronously.
3066 """Run a complete IPython cell asynchronously.
3067
3067
3068 Parameters
3068 Parameters
3069 ----------
3069 ----------
3070 raw_cell : str
3070 raw_cell : str
3071 The code (including IPython code such as %magic functions) to run.
3071 The code (including IPython code such as %magic functions) to run.
3072 store_history : bool
3072 store_history : bool
3073 If True, the raw and translated cell will be stored in IPython's
3073 If True, the raw and translated cell will be stored in IPython's
3074 history. For user code calling back into IPython's machinery, this
3074 history. For user code calling back into IPython's machinery, this
3075 should be set to False.
3075 should be set to False.
3076 silent : bool
3076 silent : bool
3077 If True, avoid side-effects, such as implicit displayhooks and
3077 If True, avoid side-effects, such as implicit displayhooks and
3078 and logging. silent=True forces store_history=False.
3078 and logging. silent=True forces store_history=False.
3079 shell_futures : bool
3079 shell_futures : bool
3080 If True, the code will share future statements with the interactive
3080 If True, the code will share future statements with the interactive
3081 shell. It will both be affected by previous __future__ imports, and
3081 shell. It will both be affected by previous __future__ imports, and
3082 any __future__ imports in the code will affect the shell. If False,
3082 any __future__ imports in the code will affect the shell. If False,
3083 __future__ imports are not shared in either direction.
3083 __future__ imports are not shared in either direction.
3084 transformed_cell: str
3084 transformed_cell: str
3085 cell that was passed through transformers
3085 cell that was passed through transformers
3086 preprocessing_exc_tuple:
3086 preprocessing_exc_tuple:
3087 trace if the transformation failed.
3087 trace if the transformation failed.
3088
3088
3089 Returns
3089 Returns
3090 -------
3090 -------
3091 result : :class:`ExecutionResult`
3091 result : :class:`ExecutionResult`
3092
3092
3093 .. versionadded:: 7.0
3093 .. versionadded:: 7.0
3094 """
3094 """
3095 info = ExecutionInfo(raw_cell, store_history, silent, shell_futures, cell_id)
3095 info = ExecutionInfo(raw_cell, store_history, silent, shell_futures, cell_id)
3096 result = ExecutionResult(info)
3096 result = ExecutionResult(info)
3097
3097
3098 if (not raw_cell) or raw_cell.isspace():
3098 if (not raw_cell) or raw_cell.isspace():
3099 self.last_execution_succeeded = True
3099 self.last_execution_succeeded = True
3100 self.last_execution_result = result
3100 self.last_execution_result = result
3101 return result
3101 return result
3102
3102
3103 if silent:
3103 if silent:
3104 store_history = False
3104 store_history = False
3105
3105
3106 if store_history:
3106 if store_history:
3107 result.execution_count = self.execution_count
3107 result.execution_count = self.execution_count
3108
3108
3109 def error_before_exec(value):
3109 def error_before_exec(value):
3110 if store_history:
3110 if store_history:
3111 self.execution_count += 1
3111 self.execution_count += 1
3112 result.error_before_exec = value
3112 result.error_before_exec = value
3113 self.last_execution_succeeded = False
3113 self.last_execution_succeeded = False
3114 self.last_execution_result = result
3114 self.last_execution_result = result
3115 return result
3115 return result
3116
3116
3117 self.events.trigger('pre_execute')
3117 self.events.trigger('pre_execute')
3118 if not silent:
3118 if not silent:
3119 self.events.trigger('pre_run_cell', info)
3119 self.events.trigger('pre_run_cell', info)
3120
3120
3121 if transformed_cell is None:
3121 if transformed_cell is None:
3122 warnings.warn(
3122 warnings.warn(
3123 "`run_cell_async` will not call `transform_cell`"
3123 "`run_cell_async` will not call `transform_cell`"
3124 " automatically in the future. Please pass the result to"
3124 " automatically in the future. Please pass the result to"
3125 " `transformed_cell` argument and any exception that happen"
3125 " `transformed_cell` argument and any exception that happen"
3126 " during the"
3126 " during the"
3127 "transform in `preprocessing_exc_tuple` in"
3127 "transform in `preprocessing_exc_tuple` in"
3128 " IPython 7.17 and above.",
3128 " IPython 7.17 and above.",
3129 DeprecationWarning,
3129 DeprecationWarning,
3130 stacklevel=2,
3130 stacklevel=2,
3131 )
3131 )
3132 # If any of our input transformation (input_transformer_manager or
3132 # If any of our input transformation (input_transformer_manager or
3133 # prefilter_manager) raises an exception, we store it in this variable
3133 # prefilter_manager) raises an exception, we store it in this variable
3134 # so that we can display the error after logging the input and storing
3134 # so that we can display the error after logging the input and storing
3135 # it in the history.
3135 # it in the history.
3136 try:
3136 try:
3137 cell = self.transform_cell(raw_cell)
3137 cell = self.transform_cell(raw_cell)
3138 except Exception:
3138 except Exception:
3139 preprocessing_exc_tuple = sys.exc_info()
3139 preprocessing_exc_tuple = sys.exc_info()
3140 cell = raw_cell # cell has to exist so it can be stored/logged
3140 cell = raw_cell # cell has to exist so it can be stored/logged
3141 else:
3141 else:
3142 preprocessing_exc_tuple = None
3142 preprocessing_exc_tuple = None
3143 else:
3143 else:
3144 if preprocessing_exc_tuple is None:
3144 if preprocessing_exc_tuple is None:
3145 cell = transformed_cell
3145 cell = transformed_cell
3146 else:
3146 else:
3147 cell = raw_cell
3147 cell = raw_cell
3148
3148
3149 # Store raw and processed history
3149 # Store raw and processed history
3150 if store_history and raw_cell.strip(" %") != "paste":
3150 if store_history and raw_cell.strip(" %") != "paste":
3151 self.history_manager.store_inputs(self.execution_count, cell, raw_cell)
3151 self.history_manager.store_inputs(self.execution_count, cell, raw_cell)
3152 if not silent:
3152 if not silent:
3153 self.logger.log(cell, raw_cell)
3153 self.logger.log(cell, raw_cell)
3154
3154
3155 # Display the exception if input processing failed.
3155 # Display the exception if input processing failed.
3156 if preprocessing_exc_tuple is not None:
3156 if preprocessing_exc_tuple is not None:
3157 self.showtraceback(preprocessing_exc_tuple)
3157 self.showtraceback(preprocessing_exc_tuple)
3158 if store_history:
3158 if store_history:
3159 self.execution_count += 1
3159 self.execution_count += 1
3160 return error_before_exec(preprocessing_exc_tuple[1])
3160 return error_before_exec(preprocessing_exc_tuple[1])
3161
3161
3162 # Our own compiler remembers the __future__ environment. If we want to
3162 # Our own compiler remembers the __future__ environment. If we want to
3163 # run code with a separate __future__ environment, use the default
3163 # run code with a separate __future__ environment, use the default
3164 # compiler
3164 # compiler
3165 compiler = self.compile if shell_futures else self.compiler_class()
3165 compiler = self.compile if shell_futures else self.compiler_class()
3166
3166
3167 _run_async = False
3167 _run_async = False
3168
3168
3169 with self.builtin_trap:
3169 with self.builtin_trap:
3170 cell_name = compiler.cache(cell, self.execution_count, raw_code=raw_cell)
3170 cell_name = compiler.cache(cell, self.execution_count, raw_code=raw_cell)
3171
3171
3172 with self.display_trap:
3172 with self.display_trap:
3173 # Compile to bytecode
3173 # Compile to bytecode
3174 try:
3174 try:
3175 code_ast = compiler.ast_parse(cell, filename=cell_name)
3175 code_ast = compiler.ast_parse(cell, filename=cell_name)
3176 except self.custom_exceptions as e:
3176 except self.custom_exceptions as e:
3177 etype, value, tb = sys.exc_info()
3177 etype, value, tb = sys.exc_info()
3178 self.CustomTB(etype, value, tb)
3178 self.CustomTB(etype, value, tb)
3179 return error_before_exec(e)
3179 return error_before_exec(e)
3180 except IndentationError as e:
3180 except IndentationError as e:
3181 self.showindentationerror()
3181 self.showindentationerror()
3182 return error_before_exec(e)
3182 return error_before_exec(e)
3183 except (OverflowError, SyntaxError, ValueError, TypeError,
3183 except (OverflowError, SyntaxError, ValueError, TypeError,
3184 MemoryError) as e:
3184 MemoryError) as e:
3185 self.showsyntaxerror()
3185 self.showsyntaxerror()
3186 return error_before_exec(e)
3186 return error_before_exec(e)
3187
3187
3188 # Apply AST transformations
3188 # Apply AST transformations
3189 try:
3189 try:
3190 code_ast = self.transform_ast(code_ast)
3190 code_ast = self.transform_ast(code_ast)
3191 except InputRejected as e:
3191 except InputRejected as e:
3192 self.showtraceback()
3192 self.showtraceback()
3193 return error_before_exec(e)
3193 return error_before_exec(e)
3194
3194
3195 # Give the displayhook a reference to our ExecutionResult so it
3195 # Give the displayhook a reference to our ExecutionResult so it
3196 # can fill in the output value.
3196 # can fill in the output value.
3197 self.displayhook.exec_result = result
3197 self.displayhook.exec_result = result
3198
3198
3199 # Execute the user code
3199 # Execute the user code
3200 interactivity = "none" if silent else self.ast_node_interactivity
3200 interactivity = "none" if silent else self.ast_node_interactivity
3201
3201
3202 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,
3202 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,
3203 interactivity=interactivity, compiler=compiler, result=result)
3203 interactivity=interactivity, compiler=compiler, result=result)
3204
3204
3205 self.last_execution_succeeded = not has_raised
3205 self.last_execution_succeeded = not has_raised
3206 self.last_execution_result = result
3206 self.last_execution_result = result
3207
3207
3208 # Reset this so later displayed values do not modify the
3208 # Reset this so later displayed values do not modify the
3209 # ExecutionResult
3209 # ExecutionResult
3210 self.displayhook.exec_result = None
3210 self.displayhook.exec_result = None
3211
3211
3212 if store_history:
3212 if store_history:
3213 # Write output to the database. Does nothing unless
3213 # Write output to the database. Does nothing unless
3214 # history output logging is enabled.
3214 # history output logging is enabled.
3215 self.history_manager.store_output(self.execution_count)
3215 self.history_manager.store_output(self.execution_count)
3216 # Each cell is a *single* input, regardless of how many lines it has
3216 # Each cell is a *single* input, regardless of how many lines it has
3217 self.execution_count += 1
3217 self.execution_count += 1
3218
3218
3219 return result
3219 return result
3220
3220
3221 def transform_cell(self, raw_cell):
3221 def transform_cell(self, raw_cell):
3222 """Transform an input cell before parsing it.
3222 """Transform an input cell before parsing it.
3223
3223
3224 Static transformations, implemented in IPython.core.inputtransformer2,
3224 Static transformations, implemented in IPython.core.inputtransformer2,
3225 deal with things like ``%magic`` and ``!system`` commands.
3225 deal with things like ``%magic`` and ``!system`` commands.
3226 These run on all input.
3226 These run on all input.
3227 Dynamic transformations, for things like unescaped magics and the exit
3227 Dynamic transformations, for things like unescaped magics and the exit
3228 autocall, depend on the state of the interpreter.
3228 autocall, depend on the state of the interpreter.
3229 These only apply to single line inputs.
3229 These only apply to single line inputs.
3230
3230
3231 These string-based transformations are followed by AST transformations;
3231 These string-based transformations are followed by AST transformations;
3232 see :meth:`transform_ast`.
3232 see :meth:`transform_ast`.
3233 """
3233 """
3234 # Static input transformations
3234 # Static input transformations
3235 cell = self.input_transformer_manager.transform_cell(raw_cell)
3235 cell = self.input_transformer_manager.transform_cell(raw_cell)
3236
3236
3237 if len(cell.splitlines()) == 1:
3237 if len(cell.splitlines()) == 1:
3238 # Dynamic transformations - only applied for single line commands
3238 # Dynamic transformations - only applied for single line commands
3239 with self.builtin_trap:
3239 with self.builtin_trap:
3240 # use prefilter_lines to handle trailing newlines
3240 # use prefilter_lines to handle trailing newlines
3241 # restore trailing newline for ast.parse
3241 # restore trailing newline for ast.parse
3242 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
3242 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
3243
3243
3244 lines = cell.splitlines(keepends=True)
3244 lines = cell.splitlines(keepends=True)
3245 for transform in self.input_transformers_post:
3245 for transform in self.input_transformers_post:
3246 lines = transform(lines)
3246 lines = transform(lines)
3247 cell = ''.join(lines)
3247 cell = ''.join(lines)
3248
3248
3249 return cell
3249 return cell
3250
3250
3251 def transform_ast(self, node):
3251 def transform_ast(self, node):
3252 """Apply the AST transformations from self.ast_transformers
3252 """Apply the AST transformations from self.ast_transformers
3253
3253
3254 Parameters
3254 Parameters
3255 ----------
3255 ----------
3256 node : ast.Node
3256 node : ast.Node
3257 The root node to be transformed. Typically called with the ast.Module
3257 The root node to be transformed. Typically called with the ast.Module
3258 produced by parsing user input.
3258 produced by parsing user input.
3259
3259
3260 Returns
3260 Returns
3261 -------
3261 -------
3262 An ast.Node corresponding to the node it was called with. Note that it
3262 An ast.Node corresponding to the node it was called with. Note that it
3263 may also modify the passed object, so don't rely on references to the
3263 may also modify the passed object, so don't rely on references to the
3264 original AST.
3264 original AST.
3265 """
3265 """
3266 for transformer in self.ast_transformers:
3266 for transformer in self.ast_transformers:
3267 try:
3267 try:
3268 node = transformer.visit(node)
3268 node = transformer.visit(node)
3269 except InputRejected:
3269 except InputRejected:
3270 # User-supplied AST transformers can reject an input by raising
3270 # User-supplied AST transformers can reject an input by raising
3271 # an InputRejected. Short-circuit in this case so that we
3271 # an InputRejected. Short-circuit in this case so that we
3272 # don't unregister the transform.
3272 # don't unregister the transform.
3273 raise
3273 raise
3274 except Exception:
3274 except Exception:
3275 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
3275 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
3276 self.ast_transformers.remove(transformer)
3276 self.ast_transformers.remove(transformer)
3277
3277
3278 if self.ast_transformers:
3278 if self.ast_transformers:
3279 ast.fix_missing_locations(node)
3279 ast.fix_missing_locations(node)
3280 return node
3280 return node
3281
3281
3282 async def run_ast_nodes(
3282 async def run_ast_nodes(
3283 self,
3283 self,
3284 nodelist: ListType[stmt],
3284 nodelist: ListType[stmt],
3285 cell_name: str,
3285 cell_name: str,
3286 interactivity="last_expr",
3286 interactivity="last_expr",
3287 compiler=compile,
3287 compiler=compile,
3288 result=None,
3288 result=None,
3289 ):
3289 ):
3290 """Run a sequence of AST nodes. The execution mode depends on the
3290 """Run a sequence of AST nodes. The execution mode depends on the
3291 interactivity parameter.
3291 interactivity parameter.
3292
3292
3293 Parameters
3293 Parameters
3294 ----------
3294 ----------
3295 nodelist : list
3295 nodelist : list
3296 A sequence of AST nodes to run.
3296 A sequence of AST nodes to run.
3297 cell_name : str
3297 cell_name : str
3298 Will be passed to the compiler as the filename of the cell. Typically
3298 Will be passed to the compiler as the filename of the cell. Typically
3299 the value returned by ip.compile.cache(cell).
3299 the value returned by ip.compile.cache(cell).
3300 interactivity : str
3300 interactivity : str
3301 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
3301 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
3302 specifying which nodes should be run interactively (displaying output
3302 specifying which nodes should be run interactively (displaying output
3303 from expressions). 'last_expr' will run the last node interactively
3303 from expressions). 'last_expr' will run the last node interactively
3304 only if it is an expression (i.e. expressions in loops or other blocks
3304 only if it is an expression (i.e. expressions in loops or other blocks
3305 are not displayed) 'last_expr_or_assign' will run the last expression
3305 are not displayed) 'last_expr_or_assign' will run the last expression
3306 or the last assignment. Other values for this parameter will raise a
3306 or the last assignment. Other values for this parameter will raise a
3307 ValueError.
3307 ValueError.
3308
3308
3309 compiler : callable
3309 compiler : callable
3310 A function with the same interface as the built-in compile(), to turn
3310 A function with the same interface as the built-in compile(), to turn
3311 the AST nodes into code objects. Default is the built-in compile().
3311 the AST nodes into code objects. Default is the built-in compile().
3312 result : ExecutionResult, optional
3312 result : ExecutionResult, optional
3313 An object to store exceptions that occur during execution.
3313 An object to store exceptions that occur during execution.
3314
3314
3315 Returns
3315 Returns
3316 -------
3316 -------
3317 True if an exception occurred while running code, False if it finished
3317 True if an exception occurred while running code, False if it finished
3318 running.
3318 running.
3319 """
3319 """
3320 if not nodelist:
3320 if not nodelist:
3321 return
3321 return
3322
3322
3323
3323
3324 if interactivity == 'last_expr_or_assign':
3324 if interactivity == 'last_expr_or_assign':
3325 if isinstance(nodelist[-1], _assign_nodes):
3325 if isinstance(nodelist[-1], _assign_nodes):
3326 asg = nodelist[-1]
3326 asg = nodelist[-1]
3327 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
3327 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
3328 target = asg.targets[0]
3328 target = asg.targets[0]
3329 elif isinstance(asg, _single_targets_nodes):
3329 elif isinstance(asg, _single_targets_nodes):
3330 target = asg.target
3330 target = asg.target
3331 else:
3331 else:
3332 target = None
3332 target = None
3333 if isinstance(target, ast.Name):
3333 if isinstance(target, ast.Name):
3334 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
3334 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
3335 ast.fix_missing_locations(nnode)
3335 ast.fix_missing_locations(nnode)
3336 nodelist.append(nnode)
3336 nodelist.append(nnode)
3337 interactivity = 'last_expr'
3337 interactivity = 'last_expr'
3338
3338
3339 _async = False
3339 _async = False
3340 if interactivity == 'last_expr':
3340 if interactivity == 'last_expr':
3341 if isinstance(nodelist[-1], ast.Expr):
3341 if isinstance(nodelist[-1], ast.Expr):
3342 interactivity = "last"
3342 interactivity = "last"
3343 else:
3343 else:
3344 interactivity = "none"
3344 interactivity = "none"
3345
3345
3346 if interactivity == 'none':
3346 if interactivity == 'none':
3347 to_run_exec, to_run_interactive = nodelist, []
3347 to_run_exec, to_run_interactive = nodelist, []
3348 elif interactivity == 'last':
3348 elif interactivity == 'last':
3349 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
3349 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
3350 elif interactivity == 'all':
3350 elif interactivity == 'all':
3351 to_run_exec, to_run_interactive = [], nodelist
3351 to_run_exec, to_run_interactive = [], nodelist
3352 else:
3352 else:
3353 raise ValueError("Interactivity was %r" % interactivity)
3353 raise ValueError("Interactivity was %r" % interactivity)
3354
3354
3355 try:
3355 try:
3356
3356
3357 def compare(code):
3357 def compare(code):
3358 is_async = inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE
3358 is_async = inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE
3359 return is_async
3359 return is_async
3360
3360
3361 # refactor that to just change the mod constructor.
3361 # refactor that to just change the mod constructor.
3362 to_run = []
3362 to_run = []
3363 for node in to_run_exec:
3363 for node in to_run_exec:
3364 to_run.append((node, "exec"))
3364 to_run.append((node, "exec"))
3365
3365
3366 for node in to_run_interactive:
3366 for node in to_run_interactive:
3367 to_run.append((node, "single"))
3367 to_run.append((node, "single"))
3368
3368
3369 for node, mode in to_run:
3369 for node, mode in to_run:
3370 if mode == "exec":
3370 if mode == "exec":
3371 mod = Module([node], [])
3371 mod = Module([node], [])
3372 elif mode == "single":
3372 elif mode == "single":
3373 mod = ast.Interactive([node])
3373 mod = ast.Interactive([node])
3374 with compiler.extra_flags(
3374 with compiler.extra_flags(
3375 getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x0)
3375 getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x0)
3376 if self.autoawait
3376 if self.autoawait
3377 else 0x0
3377 else 0x0
3378 ):
3378 ):
3379 code = compiler(mod, cell_name, mode)
3379 code = compiler(mod, cell_name, mode)
3380 asy = compare(code)
3380 asy = compare(code)
3381 if await self.run_code(code, result, async_=asy):
3381 if await self.run_code(code, result, async_=asy):
3382 return True
3382 return True
3383
3383
3384 # Flush softspace
3384 # Flush softspace
3385 if softspace(sys.stdout, 0):
3385 if softspace(sys.stdout, 0):
3386 print()
3386 print()
3387
3387
3388 except:
3388 except:
3389 # It's possible to have exceptions raised here, typically by
3389 # It's possible to have exceptions raised here, typically by
3390 # compilation of odd code (such as a naked 'return' outside a
3390 # compilation of odd code (such as a naked 'return' outside a
3391 # function) that did parse but isn't valid. Typically the exception
3391 # function) that did parse but isn't valid. Typically the exception
3392 # is a SyntaxError, but it's safest just to catch anything and show
3392 # is a SyntaxError, but it's safest just to catch anything and show
3393 # the user a traceback.
3393 # the user a traceback.
3394
3394
3395 # We do only one try/except outside the loop to minimize the impact
3395 # We do only one try/except outside the loop to minimize the impact
3396 # on runtime, and also because if any node in the node list is
3396 # on runtime, and also because if any node in the node list is
3397 # broken, we should stop execution completely.
3397 # broken, we should stop execution completely.
3398 if result:
3398 if result:
3399 result.error_before_exec = sys.exc_info()[1]
3399 result.error_before_exec = sys.exc_info()[1]
3400 self.showtraceback()
3400 self.showtraceback()
3401 return True
3401 return True
3402
3402
3403 return False
3403 return False
3404
3404
3405 async def run_code(self, code_obj, result=None, *, async_=False):
3405 async def run_code(self, code_obj, result=None, *, async_=False):
3406 """Execute a code object.
3406 """Execute a code object.
3407
3407
3408 When an exception occurs, self.showtraceback() is called to display a
3408 When an exception occurs, self.showtraceback() is called to display a
3409 traceback.
3409 traceback.
3410
3410
3411 Parameters
3411 Parameters
3412 ----------
3412 ----------
3413 code_obj : code object
3413 code_obj : code object
3414 A compiled code object, to be executed
3414 A compiled code object, to be executed
3415 result : ExecutionResult, optional
3415 result : ExecutionResult, optional
3416 An object to store exceptions that occur during execution.
3416 An object to store exceptions that occur during execution.
3417 async_ : Bool (Experimental)
3417 async_ : Bool (Experimental)
3418 Attempt to run top-level asynchronous code in a default loop.
3418 Attempt to run top-level asynchronous code in a default loop.
3419
3419
3420 Returns
3420 Returns
3421 -------
3421 -------
3422 False : successful execution.
3422 False : successful execution.
3423 True : an error occurred.
3423 True : an error occurred.
3424 """
3424 """
3425 # special value to say that anything above is IPython and should be
3425 # special value to say that anything above is IPython and should be
3426 # hidden.
3426 # hidden.
3427 __tracebackhide__ = "__ipython_bottom__"
3427 __tracebackhide__ = "__ipython_bottom__"
3428 # Set our own excepthook in case the user code tries to call it
3428 # Set our own excepthook in case the user code tries to call it
3429 # directly, so that the IPython crash handler doesn't get triggered
3429 # directly, so that the IPython crash handler doesn't get triggered
3430 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
3430 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
3431
3431
3432 # we save the original sys.excepthook in the instance, in case config
3432 # we save the original sys.excepthook in the instance, in case config
3433 # code (such as magics) needs access to it.
3433 # code (such as magics) needs access to it.
3434 self.sys_excepthook = old_excepthook
3434 self.sys_excepthook = old_excepthook
3435 outflag = True # happens in more places, so it's easier as default
3435 outflag = True # happens in more places, so it's easier as default
3436 try:
3436 try:
3437 try:
3437 try:
3438 if async_:
3438 if async_:
3439 await eval(code_obj, self.user_global_ns, self.user_ns)
3439 await eval(code_obj, self.user_global_ns, self.user_ns)
3440 else:
3440 else:
3441 exec(code_obj, self.user_global_ns, self.user_ns)
3441 exec(code_obj, self.user_global_ns, self.user_ns)
3442 finally:
3442 finally:
3443 # Reset our crash handler in place
3443 # Reset our crash handler in place
3444 sys.excepthook = old_excepthook
3444 sys.excepthook = old_excepthook
3445 except SystemExit as e:
3445 except SystemExit as e:
3446 if result is not None:
3446 if result is not None:
3447 result.error_in_exec = e
3447 result.error_in_exec = e
3448 self.showtraceback(exception_only=True)
3448 self.showtraceback(exception_only=True)
3449 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
3449 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
3450 except bdb.BdbQuit:
3450 except bdb.BdbQuit:
3451 etype, value, tb = sys.exc_info()
3451 etype, value, tb = sys.exc_info()
3452 if result is not None:
3452 if result is not None:
3453 result.error_in_exec = value
3453 result.error_in_exec = value
3454 # the BdbQuit stops here
3454 # the BdbQuit stops here
3455 except self.custom_exceptions:
3455 except self.custom_exceptions:
3456 etype, value, tb = sys.exc_info()
3456 etype, value, tb = sys.exc_info()
3457 if result is not None:
3457 if result is not None:
3458 result.error_in_exec = value
3458 result.error_in_exec = value
3459 self.CustomTB(etype, value, tb)
3459 self.CustomTB(etype, value, tb)
3460 except:
3460 except:
3461 if result is not None:
3461 if result is not None:
3462 result.error_in_exec = sys.exc_info()[1]
3462 result.error_in_exec = sys.exc_info()[1]
3463 self.showtraceback(running_compiled_code=True)
3463 self.showtraceback(running_compiled_code=True)
3464 else:
3464 else:
3465 outflag = False
3465 outflag = False
3466 return outflag
3466 return outflag
3467
3467
3468 # For backwards compatibility
3468 # For backwards compatibility
3469 runcode = run_code
3469 runcode = run_code
3470
3470
3471 def check_complete(self, code: str) -> Tuple[str, str]:
3471 def check_complete(self, code: str) -> Tuple[str, str]:
3472 """Return whether a block of code is ready to execute, or should be continued
3472 """Return whether a block of code is ready to execute, or should be continued
3473
3473
3474 Parameters
3474 Parameters
3475 ----------
3475 ----------
3476 code : string
3476 code : string
3477 Python input code, which can be multiline.
3477 Python input code, which can be multiline.
3478
3478
3479 Returns
3479 Returns
3480 -------
3480 -------
3481 status : str
3481 status : str
3482 One of 'complete', 'incomplete', or 'invalid' if source is not a
3482 One of 'complete', 'incomplete', or 'invalid' if source is not a
3483 prefix of valid code.
3483 prefix of valid code.
3484 indent : str
3484 indent : str
3485 When status is 'incomplete', this is some whitespace to insert on
3485 When status is 'incomplete', this is some whitespace to insert on
3486 the next line of the prompt.
3486 the next line of the prompt.
3487 """
3487 """
3488 status, nspaces = self.input_transformer_manager.check_complete(code)
3488 status, nspaces = self.input_transformer_manager.check_complete(code)
3489 return status, ' ' * (nspaces or 0)
3489 return status, ' ' * (nspaces or 0)
3490
3490
3491 #-------------------------------------------------------------------------
3491 #-------------------------------------------------------------------------
3492 # Things related to GUI support and pylab
3492 # Things related to GUI support and pylab
3493 #-------------------------------------------------------------------------
3493 #-------------------------------------------------------------------------
3494
3494
3495 active_eventloop = None
3495 active_eventloop = None
3496
3496
3497 def enable_gui(self, gui=None):
3497 def enable_gui(self, gui=None):
3498 raise NotImplementedError('Implement enable_gui in a subclass')
3498 raise NotImplementedError('Implement enable_gui in a subclass')
3499
3499
3500 def enable_matplotlib(self, gui=None):
3500 def enable_matplotlib(self, gui=None):
3501 """Enable interactive matplotlib and inline figure support.
3501 """Enable interactive matplotlib and inline figure support.
3502
3502
3503 This takes the following steps:
3503 This takes the following steps:
3504
3504
3505 1. select the appropriate eventloop and matplotlib backend
3505 1. select the appropriate eventloop and matplotlib backend
3506 2. set up matplotlib for interactive use with that backend
3506 2. set up matplotlib for interactive use with that backend
3507 3. configure formatters for inline figure display
3507 3. configure formatters for inline figure display
3508 4. enable the selected gui eventloop
3508 4. enable the selected gui eventloop
3509
3509
3510 Parameters
3510 Parameters
3511 ----------
3511 ----------
3512 gui : optional, string
3512 gui : optional, string
3513 If given, dictates the choice of matplotlib GUI backend to use
3513 If given, dictates the choice of matplotlib GUI backend to use
3514 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3514 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3515 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3515 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3516 matplotlib (as dictated by the matplotlib build-time options plus the
3516 matplotlib (as dictated by the matplotlib build-time options plus the
3517 user's matplotlibrc configuration file). Note that not all backends
3517 user's matplotlibrc configuration file). Note that not all backends
3518 make sense in all contexts, for example a terminal ipython can't
3518 make sense in all contexts, for example a terminal ipython can't
3519 display figures inline.
3519 display figures inline.
3520 """
3520 """
3521 from matplotlib_inline.backend_inline import configure_inline_support
3521 from matplotlib_inline.backend_inline import configure_inline_support
3522
3522
3523 from IPython.core import pylabtools as pt
3523 from IPython.core import pylabtools as pt
3524 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3524 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3525
3525
3526 if gui != 'inline':
3526 if gui != 'inline':
3527 # If we have our first gui selection, store it
3527 # If we have our first gui selection, store it
3528 if self.pylab_gui_select is None:
3528 if self.pylab_gui_select is None:
3529 self.pylab_gui_select = gui
3529 self.pylab_gui_select = gui
3530 # Otherwise if they are different
3530 # Otherwise if they are different
3531 elif gui != self.pylab_gui_select:
3531 elif gui != self.pylab_gui_select:
3532 print('Warning: Cannot change to a different GUI toolkit: %s.'
3532 print('Warning: Cannot change to a different GUI toolkit: %s.'
3533 ' Using %s instead.' % (gui, self.pylab_gui_select))
3533 ' Using %s instead.' % (gui, self.pylab_gui_select))
3534 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3534 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3535
3535
3536 pt.activate_matplotlib(backend)
3536 pt.activate_matplotlib(backend)
3537 configure_inline_support(self, backend)
3537 configure_inline_support(self, backend)
3538
3538
3539 # Now we must activate the gui pylab wants to use, and fix %run to take
3539 # Now we must activate the gui pylab wants to use, and fix %run to take
3540 # plot updates into account
3540 # plot updates into account
3541 self.enable_gui(gui)
3541 self.enable_gui(gui)
3542 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3542 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3543 pt.mpl_runner(self.safe_execfile)
3543 pt.mpl_runner(self.safe_execfile)
3544
3544
3545 return gui, backend
3545 return gui, backend
3546
3546
3547 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3547 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3548 """Activate pylab support at runtime.
3548 """Activate pylab support at runtime.
3549
3549
3550 This turns on support for matplotlib, preloads into the interactive
3550 This turns on support for matplotlib, preloads into the interactive
3551 namespace all of numpy and pylab, and configures IPython to correctly
3551 namespace all of numpy and pylab, and configures IPython to correctly
3552 interact with the GUI event loop. The GUI backend to be used can be
3552 interact with the GUI event loop. The GUI backend to be used can be
3553 optionally selected with the optional ``gui`` argument.
3553 optionally selected with the optional ``gui`` argument.
3554
3554
3555 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3555 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3556
3556
3557 Parameters
3557 Parameters
3558 ----------
3558 ----------
3559 gui : optional, string
3559 gui : optional, string
3560 If given, dictates the choice of matplotlib GUI backend to use
3560 If given, dictates the choice of matplotlib GUI backend to use
3561 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3561 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3562 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3562 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3563 matplotlib (as dictated by the matplotlib build-time options plus the
3563 matplotlib (as dictated by the matplotlib build-time options plus the
3564 user's matplotlibrc configuration file). Note that not all backends
3564 user's matplotlibrc configuration file). Note that not all backends
3565 make sense in all contexts, for example a terminal ipython can't
3565 make sense in all contexts, for example a terminal ipython can't
3566 display figures inline.
3566 display figures inline.
3567 import_all : optional, bool, default: True
3567 import_all : optional, bool, default: True
3568 Whether to do `from numpy import *` and `from pylab import *`
3568 Whether to do `from numpy import *` and `from pylab import *`
3569 in addition to module imports.
3569 in addition to module imports.
3570 welcome_message : deprecated
3570 welcome_message : deprecated
3571 This argument is ignored, no welcome message will be displayed.
3571 This argument is ignored, no welcome message will be displayed.
3572 """
3572 """
3573 from IPython.core.pylabtools import import_pylab
3573 from IPython.core.pylabtools import import_pylab
3574
3574
3575 gui, backend = self.enable_matplotlib(gui)
3575 gui, backend = self.enable_matplotlib(gui)
3576
3576
3577 # We want to prevent the loading of pylab to pollute the user's
3577 # We want to prevent the loading of pylab to pollute the user's
3578 # namespace as shown by the %who* magics, so we execute the activation
3578 # namespace as shown by the %who* magics, so we execute the activation
3579 # code in an empty namespace, and we update *both* user_ns and
3579 # code in an empty namespace, and we update *both* user_ns and
3580 # user_ns_hidden with this information.
3580 # user_ns_hidden with this information.
3581 ns = {}
3581 ns = {}
3582 import_pylab(ns, import_all)
3582 import_pylab(ns, import_all)
3583 # warn about clobbered names
3583 # warn about clobbered names
3584 ignored = {"__builtins__"}
3584 ignored = {"__builtins__"}
3585 both = set(ns).intersection(self.user_ns).difference(ignored)
3585 both = set(ns).intersection(self.user_ns).difference(ignored)
3586 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3586 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3587 self.user_ns.update(ns)
3587 self.user_ns.update(ns)
3588 self.user_ns_hidden.update(ns)
3588 self.user_ns_hidden.update(ns)
3589 return gui, backend, clobbered
3589 return gui, backend, clobbered
3590
3590
3591 #-------------------------------------------------------------------------
3591 #-------------------------------------------------------------------------
3592 # Utilities
3592 # Utilities
3593 #-------------------------------------------------------------------------
3593 #-------------------------------------------------------------------------
3594
3594
3595 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3595 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3596 """Expand python variables in a string.
3596 """Expand python variables in a string.
3597
3597
3598 The depth argument indicates how many frames above the caller should
3598 The depth argument indicates how many frames above the caller should
3599 be walked to look for the local namespace where to expand variables.
3599 be walked to look for the local namespace where to expand variables.
3600
3600
3601 The global namespace for expansion is always the user's interactive
3601 The global namespace for expansion is always the user's interactive
3602 namespace.
3602 namespace.
3603 """
3603 """
3604 ns = self.user_ns.copy()
3604 ns = self.user_ns.copy()
3605 try:
3605 try:
3606 frame = sys._getframe(depth+1)
3606 frame = sys._getframe(depth+1)
3607 except ValueError:
3607 except ValueError:
3608 # This is thrown if there aren't that many frames on the stack,
3608 # This is thrown if there aren't that many frames on the stack,
3609 # e.g. if a script called run_line_magic() directly.
3609 # e.g. if a script called run_line_magic() directly.
3610 pass
3610 pass
3611 else:
3611 else:
3612 ns.update(frame.f_locals)
3612 ns.update(frame.f_locals)
3613
3613
3614 try:
3614 try:
3615 # We have to use .vformat() here, because 'self' is a valid and common
3615 # We have to use .vformat() here, because 'self' is a valid and common
3616 # name, and expanding **ns for .format() would make it collide with
3616 # name, and expanding **ns for .format() would make it collide with
3617 # the 'self' argument of the method.
3617 # the 'self' argument of the method.
3618 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3618 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3619 except Exception:
3619 except Exception:
3620 # if formatter couldn't format, just let it go untransformed
3620 # if formatter couldn't format, just let it go untransformed
3621 pass
3621 pass
3622 return cmd
3622 return cmd
3623
3623
3624 def mktempfile(self, data=None, prefix='ipython_edit_'):
3624 def mktempfile(self, data=None, prefix='ipython_edit_'):
3625 """Make a new tempfile and return its filename.
3625 """Make a new tempfile and return its filename.
3626
3626
3627 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3627 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3628 but it registers the created filename internally so ipython cleans it up
3628 but it registers the created filename internally so ipython cleans it up
3629 at exit time.
3629 at exit time.
3630
3630
3631 Optional inputs:
3631 Optional inputs:
3632
3632
3633 - data(None): if data is given, it gets written out to the temp file
3633 - data(None): if data is given, it gets written out to the temp file
3634 immediately, and the file is closed again."""
3634 immediately, and the file is closed again."""
3635
3635
3636 dir_path = Path(tempfile.mkdtemp(prefix=prefix))
3636 dir_path = Path(tempfile.mkdtemp(prefix=prefix))
3637 self.tempdirs.append(dir_path)
3637 self.tempdirs.append(dir_path)
3638
3638
3639 handle, filename = tempfile.mkstemp(".py", prefix, dir=str(dir_path))
3639 handle, filename = tempfile.mkstemp(".py", prefix, dir=str(dir_path))
3640 os.close(handle) # On Windows, there can only be one open handle on a file
3640 os.close(handle) # On Windows, there can only be one open handle on a file
3641
3641
3642 file_path = Path(filename)
3642 file_path = Path(filename)
3643 self.tempfiles.append(file_path)
3643 self.tempfiles.append(file_path)
3644
3644
3645 if data:
3645 if data:
3646 file_path.write_text(data, encoding="utf-8")
3646 file_path.write_text(data, encoding="utf-8")
3647 return filename
3647 return filename
3648
3648
3649 def ask_yes_no(self, prompt, default=None, interrupt=None):
3649 def ask_yes_no(self, prompt, default=None, interrupt=None):
3650 if self.quiet:
3650 if self.quiet:
3651 return True
3651 return True
3652 return ask_yes_no(prompt,default,interrupt)
3652 return ask_yes_no(prompt,default,interrupt)
3653
3653
3654 def show_usage(self):
3654 def show_usage(self):
3655 """Show a usage message"""
3655 """Show a usage message"""
3656 page.page(IPython.core.usage.interactive_usage)
3656 page.page(IPython.core.usage.interactive_usage)
3657
3657
3658 def extract_input_lines(self, range_str, raw=False):
3658 def extract_input_lines(self, range_str, raw=False):
3659 """Return as a string a set of input history slices.
3659 """Return as a string a set of input history slices.
3660
3660
3661 Parameters
3661 Parameters
3662 ----------
3662 ----------
3663 range_str : str
3663 range_str : str
3664 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3664 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3665 since this function is for use by magic functions which get their
3665 since this function is for use by magic functions which get their
3666 arguments as strings. The number before the / is the session
3666 arguments as strings. The number before the / is the session
3667 number: ~n goes n back from the current session.
3667 number: ~n goes n back from the current session.
3668
3668
3669 If empty string is given, returns history of current session
3669 If empty string is given, returns history of current session
3670 without the last input.
3670 without the last input.
3671
3671
3672 raw : bool, optional
3672 raw : bool, optional
3673 By default, the processed input is used. If this is true, the raw
3673 By default, the processed input is used. If this is true, the raw
3674 input history is used instead.
3674 input history is used instead.
3675
3675
3676 Notes
3676 Notes
3677 -----
3677 -----
3678 Slices can be described with two notations:
3678 Slices can be described with two notations:
3679
3679
3680 * ``N:M`` -> standard python form, means including items N...(M-1).
3680 * ``N:M`` -> standard python form, means including items N...(M-1).
3681 * ``N-M`` -> include items N..M (closed endpoint).
3681 * ``N-M`` -> include items N..M (closed endpoint).
3682 """
3682 """
3683 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3683 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3684 text = "\n".join(x for _, _, x in lines)
3684 text = "\n".join(x for _, _, x in lines)
3685
3685
3686 # Skip the last line, as it's probably the magic that called this
3686 # Skip the last line, as it's probably the magic that called this
3687 if not range_str:
3687 if not range_str:
3688 if "\n" not in text:
3688 if "\n" not in text:
3689 text = ""
3689 text = ""
3690 else:
3690 else:
3691 text = text[: text.rfind("\n")]
3691 text = text[: text.rfind("\n")]
3692
3692
3693 return text
3693 return text
3694
3694
3695 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3695 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3696 """Get a code string from history, file, url, or a string or macro.
3696 """Get a code string from history, file, url, or a string or macro.
3697
3697
3698 This is mainly used by magic functions.
3698 This is mainly used by magic functions.
3699
3699
3700 Parameters
3700 Parameters
3701 ----------
3701 ----------
3702 target : str
3702 target : str
3703 A string specifying code to retrieve. This will be tried respectively
3703 A string specifying code to retrieve. This will be tried respectively
3704 as: ranges of input history (see %history for syntax), url,
3704 as: ranges of input history (see %history for syntax), url,
3705 corresponding .py file, filename, or an expression evaluating to a
3705 corresponding .py file, filename, or an expression evaluating to a
3706 string or Macro in the user namespace.
3706 string or Macro in the user namespace.
3707
3707
3708 If empty string is given, returns complete history of current
3708 If empty string is given, returns complete history of current
3709 session, without the last line.
3709 session, without the last line.
3710
3710
3711 raw : bool
3711 raw : bool
3712 If true (default), retrieve raw history. Has no effect on the other
3712 If true (default), retrieve raw history. Has no effect on the other
3713 retrieval mechanisms.
3713 retrieval mechanisms.
3714
3714
3715 py_only : bool (default False)
3715 py_only : bool (default False)
3716 Only try to fetch python code, do not try alternative methods to decode file
3716 Only try to fetch python code, do not try alternative methods to decode file
3717 if unicode fails.
3717 if unicode fails.
3718
3718
3719 Returns
3719 Returns
3720 -------
3720 -------
3721 A string of code.
3721 A string of code.
3722 ValueError is raised if nothing is found, and TypeError if it evaluates
3722 ValueError is raised if nothing is found, and TypeError if it evaluates
3723 to an object of another type. In each case, .args[0] is a printable
3723 to an object of another type. In each case, .args[0] is a printable
3724 message.
3724 message.
3725 """
3725 """
3726 code = self.extract_input_lines(target, raw=raw) # Grab history
3726 code = self.extract_input_lines(target, raw=raw) # Grab history
3727 if code:
3727 if code:
3728 return code
3728 return code
3729 try:
3729 try:
3730 if target.startswith(('http://', 'https://')):
3730 if target.startswith(('http://', 'https://')):
3731 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3731 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3732 except UnicodeDecodeError as e:
3732 except UnicodeDecodeError as e:
3733 if not py_only :
3733 if not py_only :
3734 # Deferred import
3734 # Deferred import
3735 from urllib.request import urlopen
3735 from urllib.request import urlopen
3736 response = urlopen(target)
3736 response = urlopen(target)
3737 return response.read().decode('latin1')
3737 return response.read().decode('latin1')
3738 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3738 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3739
3739
3740 potential_target = [target]
3740 potential_target = [target]
3741 try :
3741 try :
3742 potential_target.insert(0,get_py_filename(target))
3742 potential_target.insert(0,get_py_filename(target))
3743 except IOError:
3743 except IOError:
3744 pass
3744 pass
3745
3745
3746 for tgt in potential_target :
3746 for tgt in potential_target :
3747 if os.path.isfile(tgt): # Read file
3747 if os.path.isfile(tgt): # Read file
3748 try :
3748 try :
3749 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3749 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3750 except UnicodeDecodeError as e:
3750 except UnicodeDecodeError as e:
3751 if not py_only :
3751 if not py_only :
3752 with io_open(tgt,'r', encoding='latin1') as f :
3752 with io_open(tgt,'r', encoding='latin1') as f :
3753 return f.read()
3753 return f.read()
3754 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3754 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3755 elif os.path.isdir(os.path.expanduser(tgt)):
3755 elif os.path.isdir(os.path.expanduser(tgt)):
3756 raise ValueError("'%s' is a directory, not a regular file." % target)
3756 raise ValueError("'%s' is a directory, not a regular file." % target)
3757
3757
3758 if search_ns:
3758 if search_ns:
3759 # Inspect namespace to load object source
3759 # Inspect namespace to load object source
3760 object_info = self.object_inspect(target, detail_level=1)
3760 object_info = self.object_inspect(target, detail_level=1)
3761 if object_info['found'] and object_info['source']:
3761 if object_info['found'] and object_info['source']:
3762 return object_info['source']
3762 return object_info['source']
3763
3763
3764 try: # User namespace
3764 try: # User namespace
3765 codeobj = eval(target, self.user_ns)
3765 codeobj = eval(target, self.user_ns)
3766 except Exception as e:
3766 except Exception as e:
3767 raise ValueError(("'%s' was not found in history, as a file, url, "
3767 raise ValueError(("'%s' was not found in history, as a file, url, "
3768 "nor in the user namespace.") % target) from e
3768 "nor in the user namespace.") % target) from e
3769
3769
3770 if isinstance(codeobj, str):
3770 if isinstance(codeobj, str):
3771 return codeobj
3771 return codeobj
3772 elif isinstance(codeobj, Macro):
3772 elif isinstance(codeobj, Macro):
3773 return codeobj.value
3773 return codeobj.value
3774
3774
3775 raise TypeError("%s is neither a string nor a macro." % target,
3775 raise TypeError("%s is neither a string nor a macro." % target,
3776 codeobj)
3776 codeobj)
3777
3777
3778 def _atexit_once(self):
3778 def _atexit_once(self):
3779 """
3779 """
3780 At exist operation that need to be called at most once.
3780 At exist operation that need to be called at most once.
3781 Second call to this function per instance will do nothing.
3781 Second call to this function per instance will do nothing.
3782 """
3782 """
3783
3783
3784 if not getattr(self, "_atexit_once_called", False):
3784 if not getattr(self, "_atexit_once_called", False):
3785 self._atexit_once_called = True
3785 self._atexit_once_called = True
3786 # Clear all user namespaces to release all references cleanly.
3786 # Clear all user namespaces to release all references cleanly.
3787 self.reset(new_session=False)
3787 self.reset(new_session=False)
3788 # Close the history session (this stores the end time and line count)
3788 # Close the history session (this stores the end time and line count)
3789 # this must be *before* the tempfile cleanup, in case of temporary
3789 # this must be *before* the tempfile cleanup, in case of temporary
3790 # history db
3790 # history db
3791 self.history_manager.end_session()
3791 self.history_manager.end_session()
3792 self.history_manager = None
3792 self.history_manager = None
3793
3793
3794 #-------------------------------------------------------------------------
3794 #-------------------------------------------------------------------------
3795 # Things related to IPython exiting
3795 # Things related to IPython exiting
3796 #-------------------------------------------------------------------------
3796 #-------------------------------------------------------------------------
3797 def atexit_operations(self):
3797 def atexit_operations(self):
3798 """This will be executed at the time of exit.
3798 """This will be executed at the time of exit.
3799
3799
3800 Cleanup operations and saving of persistent data that is done
3800 Cleanup operations and saving of persistent data that is done
3801 unconditionally by IPython should be performed here.
3801 unconditionally by IPython should be performed here.
3802
3802
3803 For things that may depend on startup flags or platform specifics (such
3803 For things that may depend on startup flags or platform specifics (such
3804 as having readline or not), register a separate atexit function in the
3804 as having readline or not), register a separate atexit function in the
3805 code that has the appropriate information, rather than trying to
3805 code that has the appropriate information, rather than trying to
3806 clutter
3806 clutter
3807 """
3807 """
3808 self._atexit_once()
3808 self._atexit_once()
3809
3809
3810 # Cleanup all tempfiles and folders left around
3810 # Cleanup all tempfiles and folders left around
3811 for tfile in self.tempfiles:
3811 for tfile in self.tempfiles:
3812 try:
3812 try:
3813 tfile.unlink()
3813 tfile.unlink()
3814 self.tempfiles.remove(tfile)
3814 self.tempfiles.remove(tfile)
3815 except FileNotFoundError:
3815 except FileNotFoundError:
3816 pass
3816 pass
3817 del self.tempfiles
3817 del self.tempfiles
3818 for tdir in self.tempdirs:
3818 for tdir in self.tempdirs:
3819 try:
3819 try:
3820 tdir.rmdir()
3820 tdir.rmdir()
3821 self.tempdirs.remove(tdir)
3821 self.tempdirs.remove(tdir)
3822 except FileNotFoundError:
3822 except FileNotFoundError:
3823 pass
3823 pass
3824 del self.tempdirs
3824 del self.tempdirs
3825
3825
3826 # Restore user's cursor
3826 # Restore user's cursor
3827 if hasattr(self, "editing_mode") and self.editing_mode == "vi":
3827 if hasattr(self, "editing_mode") and self.editing_mode == "vi":
3828 sys.stdout.write("\x1b[0 q")
3828 sys.stdout.write("\x1b[0 q")
3829 sys.stdout.flush()
3829 sys.stdout.flush()
3830
3830
3831 def cleanup(self):
3831 def cleanup(self):
3832 self.restore_sys_module_state()
3832 self.restore_sys_module_state()
3833
3833
3834
3834
3835 # Overridden in terminal subclass to change prompts
3835 # Overridden in terminal subclass to change prompts
3836 def switch_doctest_mode(self, mode):
3836 def switch_doctest_mode(self, mode):
3837 pass
3837 pass
3838
3838
3839
3839
3840 class InteractiveShellABC(metaclass=abc.ABCMeta):
3840 class InteractiveShellABC(metaclass=abc.ABCMeta):
3841 """An abstract base class for InteractiveShell."""
3841 """An abstract base class for InteractiveShell."""
3842
3842
3843 InteractiveShellABC.register(InteractiveShell)
3843 InteractiveShellABC.register(InteractiveShell)
@@ -1,746 +1,755 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """Magic functions for InteractiveShell.
2 """Magic functions for InteractiveShell.
3 """
3 """
4
4
5 #-----------------------------------------------------------------------------
5 #-----------------------------------------------------------------------------
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001 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 ..utils.ipstruct import Struct
23 from ..utils.ipstruct import Struct
24 from ..utils.process import arg_split
24 from ..utils.process import arg_split
25 from ..utils.text import dedent
25 from ..utils.text import dedent
26 from traitlets import Bool, Dict, Instance, observe
26 from traitlets import Bool, Dict, Instance, observe
27 from logging import error
27 from logging import error
28
28
29 #-----------------------------------------------------------------------------
29 #-----------------------------------------------------------------------------
30 # Globals
30 # Globals
31 #-----------------------------------------------------------------------------
31 #-----------------------------------------------------------------------------
32
32
33 # A dict we'll use for each class that has magics, used as temporary storage to
33 # A dict we'll use for each class that has magics, used as temporary storage to
34 # pass information between the @line/cell_magic method decorators and the
34 # pass information between the @line/cell_magic method decorators and the
35 # @magics_class class decorator, because the method decorators have no
35 # @magics_class class decorator, because the method decorators have no
36 # access to the class when they run. See for more details:
36 # access to the class when they run. See for more details:
37 # http://stackoverflow.com/questions/2366713/can-a-python-decorator-of-an-instance-method-access-the-class
37 # http://stackoverflow.com/questions/2366713/can-a-python-decorator-of-an-instance-method-access-the-class
38
38
39 magics = dict(line={}, cell={})
39 magics = dict(line={}, cell={})
40
40
41 magic_kinds = ('line', 'cell')
41 magic_kinds = ('line', 'cell')
42 magic_spec = ('line', 'cell', 'line_cell')
42 magic_spec = ('line', 'cell', 'line_cell')
43 magic_escapes = dict(line=ESC_MAGIC, cell=ESC_MAGIC2)
43 magic_escapes = dict(line=ESC_MAGIC, cell=ESC_MAGIC2)
44
44
45 #-----------------------------------------------------------------------------
45 #-----------------------------------------------------------------------------
46 # Utility classes and functions
46 # Utility classes and functions
47 #-----------------------------------------------------------------------------
47 #-----------------------------------------------------------------------------
48
48
49 class Bunch: pass
49 class Bunch: pass
50
50
51
51
52 def on_off(tag):
52 def on_off(tag):
53 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
53 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
54 return ['OFF','ON'][tag]
54 return ['OFF','ON'][tag]
55
55
56
56
57 def compress_dhist(dh):
57 def compress_dhist(dh):
58 """Compress a directory history into a new one with at most 20 entries.
58 """Compress a directory history into a new one with at most 20 entries.
59
59
60 Return a new list made from the first and last 10 elements of dhist after
60 Return a new list made from the first and last 10 elements of dhist after
61 removal of duplicates.
61 removal of duplicates.
62 """
62 """
63 head, tail = dh[:-10], dh[-10:]
63 head, tail = dh[:-10], dh[-10:]
64
64
65 newhead = []
65 newhead = []
66 done = set()
66 done = set()
67 for h in head:
67 for h in head:
68 if h in done:
68 if h in done:
69 continue
69 continue
70 newhead.append(h)
70 newhead.append(h)
71 done.add(h)
71 done.add(h)
72
72
73 return newhead + tail
73 return newhead + tail
74
74
75
75
76 def needs_local_scope(func):
76 def needs_local_scope(func):
77 """Decorator to mark magic functions which need to local scope to run."""
77 """Decorator to mark magic functions which need to local scope to run."""
78 func.needs_local_scope = True
78 func.needs_local_scope = True
79 return func
79 return func
80
80
81 #-----------------------------------------------------------------------------
81 #-----------------------------------------------------------------------------
82 # Class and method decorators for registering magics
82 # Class and method decorators for registering magics
83 #-----------------------------------------------------------------------------
83 #-----------------------------------------------------------------------------
84
84
85 def magics_class(cls):
85 def magics_class(cls):
86 """Class decorator for all subclasses of the main Magics class.
86 """Class decorator for all subclasses of the main Magics class.
87
87
88 Any class that subclasses Magics *must* also apply this decorator, to
88 Any class that subclasses Magics *must* also apply this decorator, to
89 ensure that all the methods that have been decorated as line/cell magics
89 ensure that all the methods that have been decorated as line/cell magics
90 get correctly registered in the class instance. This is necessary because
90 get correctly registered in the class instance. This is necessary because
91 when method decorators run, the class does not exist yet, so they
91 when method decorators run, the class does not exist yet, so they
92 temporarily store their information into a module global. Application of
92 temporarily store their information into a module global. Application of
93 this class decorator copies that global data to the class instance and
93 this class decorator copies that global data to the class instance and
94 clears the global.
94 clears the global.
95
95
96 Obviously, this mechanism is not thread-safe, which means that the
96 Obviously, this mechanism is not thread-safe, which means that the
97 *creation* of subclasses of Magic should only be done in a single-thread
97 *creation* of subclasses of Magic should only be done in a single-thread
98 context. Instantiation of the classes has no restrictions. Given that
98 context. Instantiation of the classes has no restrictions. Given that
99 these classes are typically created at IPython startup time and before user
99 these classes are typically created at IPython startup time and before user
100 application code becomes active, in practice this should not pose any
100 application code becomes active, in practice this should not pose any
101 problems.
101 problems.
102 """
102 """
103 cls.registered = True
103 cls.registered = True
104 cls.magics = dict(line = magics['line'],
104 cls.magics = dict(line = magics['line'],
105 cell = magics['cell'])
105 cell = magics['cell'])
106 magics['line'] = {}
106 magics['line'] = {}
107 magics['cell'] = {}
107 magics['cell'] = {}
108 return cls
108 return cls
109
109
110
110
111 def record_magic(dct, magic_kind, magic_name, func):
111 def record_magic(dct, magic_kind, magic_name, func):
112 """Utility function to store a function as a magic of a specific kind.
112 """Utility function to store a function as a magic of a specific kind.
113
113
114 Parameters
114 Parameters
115 ----------
115 ----------
116 dct : dict
116 dct : dict
117 A dictionary with 'line' and 'cell' subdicts.
117 A dictionary with 'line' and 'cell' subdicts.
118 magic_kind : str
118 magic_kind : str
119 Kind of magic to be stored.
119 Kind of magic to be stored.
120 magic_name : str
120 magic_name : str
121 Key to store the magic as.
121 Key to store the magic as.
122 func : function
122 func : function
123 Callable object to store.
123 Callable object to store.
124 """
124 """
125 if magic_kind == 'line_cell':
125 if magic_kind == 'line_cell':
126 dct['line'][magic_name] = dct['cell'][magic_name] = func
126 dct['line'][magic_name] = dct['cell'][magic_name] = func
127 else:
127 else:
128 dct[magic_kind][magic_name] = func
128 dct[magic_kind][magic_name] = func
129
129
130
130
131 def validate_type(magic_kind):
131 def validate_type(magic_kind):
132 """Ensure that the given magic_kind is valid.
132 """Ensure that the given magic_kind is valid.
133
133
134 Check that the given magic_kind is one of the accepted spec types (stored
134 Check that the given magic_kind is one of the accepted spec types (stored
135 in the global `magic_spec`), raise ValueError otherwise.
135 in the global `magic_spec`), raise ValueError otherwise.
136 """
136 """
137 if magic_kind not in magic_spec:
137 if magic_kind not in magic_spec:
138 raise ValueError('magic_kind must be one of %s, %s given' %
138 raise ValueError('magic_kind must be one of %s, %s given' %
139 magic_kinds, magic_kind)
139 magic_kinds, magic_kind)
140
140
141
141
142 # The docstrings for the decorator below will be fairly similar for the two
142 # The docstrings for the decorator below will be fairly similar for the two
143 # types (method and function), so we generate them here once and reuse the
143 # types (method and function), so we generate them here once and reuse the
144 # templates below.
144 # templates below.
145 _docstring_template = \
145 _docstring_template = \
146 """Decorate the given {0} as {1} magic.
146 """Decorate the given {0} as {1} magic.
147
147
148 The decorator can be used with or without arguments, as follows.
148 The decorator can be used with or without arguments, as follows.
149
149
150 i) without arguments: it will create a {1} magic named as the {0} being
150 i) without arguments: it will create a {1} magic named as the {0} being
151 decorated::
151 decorated::
152
152
153 @deco
153 @deco
154 def foo(...)
154 def foo(...)
155
155
156 will create a {1} magic named `foo`.
156 will create a {1} magic named `foo`.
157
157
158 ii) with one string argument: which will be used as the actual name of the
158 ii) with one string argument: which will be used as the actual name of the
159 resulting magic::
159 resulting magic::
160
160
161 @deco('bar')
161 @deco('bar')
162 def foo(...)
162 def foo(...)
163
163
164 will create a {1} magic named `bar`.
164 will create a {1} magic named `bar`.
165
165
166 To register a class magic use ``Interactiveshell.register_magic(class or instance)``.
166 To register a class magic use ``Interactiveshell.register_magic(class or instance)``.
167 """
167 """
168
168
169 # These two are decorator factories. While they are conceptually very similar,
169 # These two are decorator factories. While they are conceptually very similar,
170 # there are enough differences in the details that it's simpler to have them
170 # there are enough differences in the details that it's simpler to have them
171 # written as completely standalone functions rather than trying to share code
171 # written as completely standalone functions rather than trying to share code
172 # and make a single one with convoluted logic.
172 # and make a single one with convoluted logic.
173
173
174 def _method_magic_marker(magic_kind):
174 def _method_magic_marker(magic_kind):
175 """Decorator factory for methods in Magics subclasses.
175 """Decorator factory for methods in Magics subclasses.
176 """
176 """
177
177
178 validate_type(magic_kind)
178 validate_type(magic_kind)
179
179
180 # This is a closure to capture the magic_kind. We could also use a class,
180 # This is a closure to capture the magic_kind. We could also use a class,
181 # but it's overkill for just that one bit of state.
181 # but it's overkill for just that one bit of state.
182 def magic_deco(arg):
182 def magic_deco(arg):
183 if callable(arg):
183 if callable(arg):
184 # "Naked" decorator call (just @foo, no args)
184 # "Naked" decorator call (just @foo, no args)
185 func = arg
185 func = arg
186 name = func.__name__
186 name = func.__name__
187 retval = arg
187 retval = arg
188 record_magic(magics, magic_kind, name, name)
188 record_magic(magics, magic_kind, name, name)
189 elif isinstance(arg, str):
189 elif isinstance(arg, str):
190 # Decorator called with arguments (@foo('bar'))
190 # Decorator called with arguments (@foo('bar'))
191 name = arg
191 name = arg
192 def mark(func, *a, **kw):
192 def mark(func, *a, **kw):
193 record_magic(magics, magic_kind, name, func.__name__)
193 record_magic(magics, magic_kind, name, func.__name__)
194 return func
194 return func
195 retval = mark
195 retval = mark
196 else:
196 else:
197 raise TypeError("Decorator can only be called with "
197 raise TypeError("Decorator can only be called with "
198 "string or function")
198 "string or function")
199 return retval
199 return retval
200
200
201 # Ensure the resulting decorator has a usable docstring
201 # Ensure the resulting decorator has a usable docstring
202 magic_deco.__doc__ = _docstring_template.format('method', magic_kind)
202 magic_deco.__doc__ = _docstring_template.format('method', magic_kind)
203 return magic_deco
203 return magic_deco
204
204
205
205
206 def _function_magic_marker(magic_kind):
206 def _function_magic_marker(magic_kind):
207 """Decorator factory for standalone functions.
207 """Decorator factory for standalone functions.
208 """
208 """
209 validate_type(magic_kind)
209 validate_type(magic_kind)
210
210
211 # This is a closure to capture the magic_kind. We could also use a class,
211 # This is a closure to capture the magic_kind. We could also use a class,
212 # but it's overkill for just that one bit of state.
212 # but it's overkill for just that one bit of state.
213 def magic_deco(arg):
213 def magic_deco(arg):
214 # Find get_ipython() in the caller's namespace
214 # Find get_ipython() in the caller's namespace
215 caller = sys._getframe(1)
215 caller = sys._getframe(1)
216 for ns in ['f_locals', 'f_globals', 'f_builtins']:
216 for ns in ['f_locals', 'f_globals', 'f_builtins']:
217 get_ipython = getattr(caller, ns).get('get_ipython')
217 get_ipython = getattr(caller, ns).get('get_ipython')
218 if get_ipython is not None:
218 if get_ipython is not None:
219 break
219 break
220 else:
220 else:
221 raise NameError('Decorator can only run in context where '
221 raise NameError('Decorator can only run in context where '
222 '`get_ipython` exists')
222 '`get_ipython` exists')
223
223
224 ip = get_ipython()
224 ip = get_ipython()
225
225
226 if callable(arg):
226 if callable(arg):
227 # "Naked" decorator call (just @foo, no args)
227 # "Naked" decorator call (just @foo, no args)
228 func = arg
228 func = arg
229 name = func.__name__
229 name = func.__name__
230 ip.register_magic_function(func, magic_kind, name)
230 ip.register_magic_function(func, magic_kind, name)
231 retval = arg
231 retval = arg
232 elif isinstance(arg, str):
232 elif isinstance(arg, str):
233 # Decorator called with arguments (@foo('bar'))
233 # Decorator called with arguments (@foo('bar'))
234 name = arg
234 name = arg
235 def mark(func, *a, **kw):
235 def mark(func, *a, **kw):
236 ip.register_magic_function(func, magic_kind, name)
236 ip.register_magic_function(func, magic_kind, name)
237 return func
237 return func
238 retval = mark
238 retval = mark
239 else:
239 else:
240 raise TypeError("Decorator can only be called with "
240 raise TypeError("Decorator can only be called with "
241 "string or function")
241 "string or function")
242 return retval
242 return retval
243
243
244 # Ensure the resulting decorator has a usable docstring
244 # Ensure the resulting decorator has a usable docstring
245 ds = _docstring_template.format('function', magic_kind)
245 ds = _docstring_template.format('function', magic_kind)
246
246
247 ds += dedent("""
247 ds += dedent("""
248 Note: this decorator can only be used in a context where IPython is already
248 Note: this decorator can only be used in a context where IPython is already
249 active, so that the `get_ipython()` call succeeds. You can therefore use
249 active, so that the `get_ipython()` call succeeds. You can therefore use
250 it in your startup files loaded after IPython initializes, but *not* in the
250 it in your startup files loaded after IPython initializes, but *not* in the
251 IPython configuration file itself, which is executed before IPython is
251 IPython configuration file itself, which is executed before IPython is
252 fully up and running. Any file located in the `startup` subdirectory of
252 fully up and running. Any file located in the `startup` subdirectory of
253 your configuration profile will be OK in this sense.
253 your configuration profile will be OK in this sense.
254 """)
254 """)
255
255
256 magic_deco.__doc__ = ds
256 magic_deco.__doc__ = ds
257 return magic_deco
257 return magic_deco
258
258
259
259
260 MAGIC_NO_VAR_EXPAND_ATTR = '_ipython_magic_no_var_expand'
260 MAGIC_NO_VAR_EXPAND_ATTR = '_ipython_magic_no_var_expand'
261
261 MAGIC_OUTPUT_CAN_BE_DISABLED = '_ipython_magic_output_can_be_disabled'
262
262
263 def no_var_expand(magic_func):
263 def no_var_expand(magic_func):
264 """Mark a magic function as not needing variable expansion
264 """Mark a magic function as not needing variable expansion
265
265
266 By default, IPython interprets `{a}` or `$a` in the line passed to magics
266 By default, IPython interprets `{a}` or `$a` in the line passed to magics
267 as variables that should be interpolated from the interactive namespace
267 as variables that should be interpolated from the interactive namespace
268 before passing the line to the magic function.
268 before passing the line to the magic function.
269 This is not always desirable, e.g. when the magic executes Python code
269 This is not always desirable, e.g. when the magic executes Python code
270 (%timeit, %time, etc.).
270 (%timeit, %time, etc.).
271 Decorate magics with `@no_var_expand` to opt-out of variable expansion.
271 Decorate magics with `@no_var_expand` to opt-out of variable expansion.
272
272
273 .. versionadded:: 7.3
273 .. versionadded:: 7.3
274 """
274 """
275 setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
275 setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
276 return magic_func
276 return magic_func
277
277
278 def output_can_be_disabled(magic_func):
279 """Mark a magic function so its output may be disabled.
280
281 The output is disabled if the Python expression used as a parameter of
282 the magic ends in a semicolon, not counting a Python comment that can
283 follows it.
284 """
285 setattr(magic_func, MAGIC_OUTPUT_CAN_BE_DISABLED, True)
286 return magic_func
278
287
279 # Create the actual decorators for public use
288 # Create the actual decorators for public use
280
289
281 # These three are used to decorate methods in class definitions
290 # These three are used to decorate methods in class definitions
282 line_magic = _method_magic_marker('line')
291 line_magic = _method_magic_marker('line')
283 cell_magic = _method_magic_marker('cell')
292 cell_magic = _method_magic_marker('cell')
284 line_cell_magic = _method_magic_marker('line_cell')
293 line_cell_magic = _method_magic_marker('line_cell')
285
294
286 # These three decorate standalone functions and perform the decoration
295 # These three decorate standalone functions and perform the decoration
287 # immediately. They can only run where get_ipython() works
296 # immediately. They can only run where get_ipython() works
288 register_line_magic = _function_magic_marker('line')
297 register_line_magic = _function_magic_marker('line')
289 register_cell_magic = _function_magic_marker('cell')
298 register_cell_magic = _function_magic_marker('cell')
290 register_line_cell_magic = _function_magic_marker('line_cell')
299 register_line_cell_magic = _function_magic_marker('line_cell')
291
300
292 #-----------------------------------------------------------------------------
301 #-----------------------------------------------------------------------------
293 # Core Magic classes
302 # Core Magic classes
294 #-----------------------------------------------------------------------------
303 #-----------------------------------------------------------------------------
295
304
296 class MagicsManager(Configurable):
305 class MagicsManager(Configurable):
297 """Object that handles all magic-related functionality for IPython.
306 """Object that handles all magic-related functionality for IPython.
298 """
307 """
299 # Non-configurable class attributes
308 # Non-configurable class attributes
300
309
301 # A two-level dict, first keyed by magic type, then by magic function, and
310 # A two-level dict, first keyed by magic type, then by magic function, and
302 # holding the actual callable object as value. This is the dict used for
311 # holding the actual callable object as value. This is the dict used for
303 # magic function dispatch
312 # magic function dispatch
304 magics = Dict()
313 magics = Dict()
305 lazy_magics = Dict(
314 lazy_magics = Dict(
306 help="""
315 help="""
307 Mapping from magic names to modules to load.
316 Mapping from magic names to modules to load.
308
317
309 This can be used in IPython/IPykernel configuration to declare lazy magics
318 This can be used in IPython/IPykernel configuration to declare lazy magics
310 that will only be imported/registered on first use.
319 that will only be imported/registered on first use.
311
320
312 For example::
321 For example::
313
322
314 c.MagicsManager.lazy_magics = {
323 c.MagicsManager.lazy_magics = {
315 "my_magic": "slow.to.import",
324 "my_magic": "slow.to.import",
316 "my_other_magic": "also.slow",
325 "my_other_magic": "also.slow",
317 }
326 }
318
327
319 On first invocation of `%my_magic`, `%%my_magic`, `%%my_other_magic` or
328 On first invocation of `%my_magic`, `%%my_magic`, `%%my_other_magic` or
320 `%%my_other_magic`, the corresponding module will be loaded as an ipython
329 `%%my_other_magic`, the corresponding module will be loaded as an ipython
321 extensions as if you had previously done `%load_ext ipython`.
330 extensions as if you had previously done `%load_ext ipython`.
322
331
323 Magics names should be without percent(s) as magics can be both cell
332 Magics names should be without percent(s) as magics can be both cell
324 and line magics.
333 and line magics.
325
334
326 Lazy loading happen relatively late in execution process, and
335 Lazy loading happen relatively late in execution process, and
327 complex extensions that manipulate Python/IPython internal state or global state
336 complex extensions that manipulate Python/IPython internal state or global state
328 might not support lazy loading.
337 might not support lazy loading.
329 """
338 """
330 ).tag(
339 ).tag(
331 config=True,
340 config=True,
332 )
341 )
333
342
334 # A registry of the original objects that we've been given holding magics.
343 # A registry of the original objects that we've been given holding magics.
335 registry = Dict()
344 registry = Dict()
336
345
337 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
346 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
338
347
339 auto_magic = Bool(True, help=
348 auto_magic = Bool(True, help=
340 "Automatically call line magics without requiring explicit % prefix"
349 "Automatically call line magics without requiring explicit % prefix"
341 ).tag(config=True)
350 ).tag(config=True)
342 @observe('auto_magic')
351 @observe('auto_magic')
343 def _auto_magic_changed(self, change):
352 def _auto_magic_changed(self, change):
344 self.shell.automagic = change['new']
353 self.shell.automagic = change['new']
345
354
346 _auto_status = [
355 _auto_status = [
347 'Automagic is OFF, % prefix IS needed for line magics.',
356 'Automagic is OFF, % prefix IS needed for line magics.',
348 'Automagic is ON, % prefix IS NOT needed for line magics.']
357 'Automagic is ON, % prefix IS NOT needed for line magics.']
349
358
350 user_magics = Instance('IPython.core.magics.UserMagics', allow_none=True)
359 user_magics = Instance('IPython.core.magics.UserMagics', allow_none=True)
351
360
352 def __init__(self, shell=None, config=None, user_magics=None, **traits):
361 def __init__(self, shell=None, config=None, user_magics=None, **traits):
353
362
354 super(MagicsManager, self).__init__(shell=shell, config=config,
363 super(MagicsManager, self).__init__(shell=shell, config=config,
355 user_magics=user_magics, **traits)
364 user_magics=user_magics, **traits)
356 self.magics = dict(line={}, cell={})
365 self.magics = dict(line={}, cell={})
357 # Let's add the user_magics to the registry for uniformity, so *all*
366 # Let's add the user_magics to the registry for uniformity, so *all*
358 # registered magic containers can be found there.
367 # registered magic containers can be found there.
359 self.registry[user_magics.__class__.__name__] = user_magics
368 self.registry[user_magics.__class__.__name__] = user_magics
360
369
361 def auto_status(self):
370 def auto_status(self):
362 """Return descriptive string with automagic status."""
371 """Return descriptive string with automagic status."""
363 return self._auto_status[self.auto_magic]
372 return self._auto_status[self.auto_magic]
364
373
365 def lsmagic(self):
374 def lsmagic(self):
366 """Return a dict of currently available magic functions.
375 """Return a dict of currently available magic functions.
367
376
368 The return dict has the keys 'line' and 'cell', corresponding to the
377 The return dict has the keys 'line' and 'cell', corresponding to the
369 two types of magics we support. Each value is a list of names.
378 two types of magics we support. Each value is a list of names.
370 """
379 """
371 return self.magics
380 return self.magics
372
381
373 def lsmagic_docs(self, brief=False, missing=''):
382 def lsmagic_docs(self, brief=False, missing=''):
374 """Return dict of documentation of magic functions.
383 """Return dict of documentation of magic functions.
375
384
376 The return dict has the keys 'line' and 'cell', corresponding to the
385 The return dict has the keys 'line' and 'cell', corresponding to the
377 two types of magics we support. Each value is a dict keyed by magic
386 two types of magics we support. Each value is a dict keyed by magic
378 name whose value is the function docstring. If a docstring is
387 name whose value is the function docstring. If a docstring is
379 unavailable, the value of `missing` is used instead.
388 unavailable, the value of `missing` is used instead.
380
389
381 If brief is True, only the first line of each docstring will be returned.
390 If brief is True, only the first line of each docstring will be returned.
382 """
391 """
383 docs = {}
392 docs = {}
384 for m_type in self.magics:
393 for m_type in self.magics:
385 m_docs = {}
394 m_docs = {}
386 for m_name, m_func in self.magics[m_type].items():
395 for m_name, m_func in self.magics[m_type].items():
387 if m_func.__doc__:
396 if m_func.__doc__:
388 if brief:
397 if brief:
389 m_docs[m_name] = m_func.__doc__.split('\n', 1)[0]
398 m_docs[m_name] = m_func.__doc__.split('\n', 1)[0]
390 else:
399 else:
391 m_docs[m_name] = m_func.__doc__.rstrip()
400 m_docs[m_name] = m_func.__doc__.rstrip()
392 else:
401 else:
393 m_docs[m_name] = missing
402 m_docs[m_name] = missing
394 docs[m_type] = m_docs
403 docs[m_type] = m_docs
395 return docs
404 return docs
396
405
397 def register_lazy(self, name: str, fully_qualified_name: str):
406 def register_lazy(self, name: str, fully_qualified_name: str):
398 """
407 """
399 Lazily register a magic via an extension.
408 Lazily register a magic via an extension.
400
409
401
410
402 Parameters
411 Parameters
403 ----------
412 ----------
404 name : str
413 name : str
405 Name of the magic you wish to register.
414 Name of the magic you wish to register.
406 fully_qualified_name :
415 fully_qualified_name :
407 Fully qualified name of the module/submodule that should be loaded
416 Fully qualified name of the module/submodule that should be loaded
408 as an extensions when the magic is first called.
417 as an extensions when the magic is first called.
409 It is assumed that loading this extensions will register the given
418 It is assumed that loading this extensions will register the given
410 magic.
419 magic.
411 """
420 """
412
421
413 self.lazy_magics[name] = fully_qualified_name
422 self.lazy_magics[name] = fully_qualified_name
414
423
415 def register(self, *magic_objects):
424 def register(self, *magic_objects):
416 """Register one or more instances of Magics.
425 """Register one or more instances of Magics.
417
426
418 Take one or more classes or instances of classes that subclass the main
427 Take one or more classes or instances of classes that subclass the main
419 `core.Magic` class, and register them with IPython to use the magic
428 `core.Magic` class, and register them with IPython to use the magic
420 functions they provide. The registration process will then ensure that
429 functions they provide. The registration process will then ensure that
421 any methods that have decorated to provide line and/or cell magics will
430 any methods that have decorated to provide line and/or cell magics will
422 be recognized with the `%x`/`%%x` syntax as a line/cell magic
431 be recognized with the `%x`/`%%x` syntax as a line/cell magic
423 respectively.
432 respectively.
424
433
425 If classes are given, they will be instantiated with the default
434 If classes are given, they will be instantiated with the default
426 constructor. If your classes need a custom constructor, you should
435 constructor. If your classes need a custom constructor, you should
427 instanitate them first and pass the instance.
436 instanitate them first and pass the instance.
428
437
429 The provided arguments can be an arbitrary mix of classes and instances.
438 The provided arguments can be an arbitrary mix of classes and instances.
430
439
431 Parameters
440 Parameters
432 ----------
441 ----------
433 *magic_objects : one or more classes or instances
442 *magic_objects : one or more classes or instances
434 """
443 """
435 # Start by validating them to ensure they have all had their magic
444 # Start by validating them to ensure they have all had their magic
436 # methods registered at the instance level
445 # methods registered at the instance level
437 for m in magic_objects:
446 for m in magic_objects:
438 if not m.registered:
447 if not m.registered:
439 raise ValueError("Class of magics %r was constructed without "
448 raise ValueError("Class of magics %r was constructed without "
440 "the @register_magics class decorator")
449 "the @register_magics class decorator")
441 if isinstance(m, type):
450 if isinstance(m, type):
442 # If we're given an uninstantiated class
451 # If we're given an uninstantiated class
443 m = m(shell=self.shell)
452 m = m(shell=self.shell)
444
453
445 # Now that we have an instance, we can register it and update the
454 # Now that we have an instance, we can register it and update the
446 # table of callables
455 # table of callables
447 self.registry[m.__class__.__name__] = m
456 self.registry[m.__class__.__name__] = m
448 for mtype in magic_kinds:
457 for mtype in magic_kinds:
449 self.magics[mtype].update(m.magics[mtype])
458 self.magics[mtype].update(m.magics[mtype])
450
459
451 def register_function(self, func, magic_kind='line', magic_name=None):
460 def register_function(self, func, magic_kind='line', magic_name=None):
452 """Expose a standalone function as magic function for IPython.
461 """Expose a standalone function as magic function for IPython.
453
462
454 This will create an IPython magic (line, cell or both) from a
463 This will create an IPython magic (line, cell or both) from a
455 standalone function. The functions should have the following
464 standalone function. The functions should have the following
456 signatures:
465 signatures:
457
466
458 * For line magics: `def f(line)`
467 * For line magics: `def f(line)`
459 * For cell magics: `def f(line, cell)`
468 * For cell magics: `def f(line, cell)`
460 * For a function that does both: `def f(line, cell=None)`
469 * For a function that does both: `def f(line, cell=None)`
461
470
462 In the latter case, the function will be called with `cell==None` when
471 In the latter case, the function will be called with `cell==None` when
463 invoked as `%f`, and with cell as a string when invoked as `%%f`.
472 invoked as `%f`, and with cell as a string when invoked as `%%f`.
464
473
465 Parameters
474 Parameters
466 ----------
475 ----------
467 func : callable
476 func : callable
468 Function to be registered as a magic.
477 Function to be registered as a magic.
469 magic_kind : str
478 magic_kind : str
470 Kind of magic, one of 'line', 'cell' or 'line_cell'
479 Kind of magic, one of 'line', 'cell' or 'line_cell'
471 magic_name : optional str
480 magic_name : optional str
472 If given, the name the magic will have in the IPython namespace. By
481 If given, the name the magic will have in the IPython namespace. By
473 default, the name of the function itself is used.
482 default, the name of the function itself is used.
474 """
483 """
475
484
476 # Create the new method in the user_magics and register it in the
485 # Create the new method in the user_magics and register it in the
477 # global table
486 # global table
478 validate_type(magic_kind)
487 validate_type(magic_kind)
479 magic_name = func.__name__ if magic_name is None else magic_name
488 magic_name = func.__name__ if magic_name is None else magic_name
480 setattr(self.user_magics, magic_name, func)
489 setattr(self.user_magics, magic_name, func)
481 record_magic(self.magics, magic_kind, magic_name, func)
490 record_magic(self.magics, magic_kind, magic_name, func)
482
491
483 def register_alias(self, alias_name, magic_name, magic_kind='line', magic_params=None):
492 def register_alias(self, alias_name, magic_name, magic_kind='line', magic_params=None):
484 """Register an alias to a magic function.
493 """Register an alias to a magic function.
485
494
486 The alias is an instance of :class:`MagicAlias`, which holds the
495 The alias is an instance of :class:`MagicAlias`, which holds the
487 name and kind of the magic it should call. Binding is done at
496 name and kind of the magic it should call. Binding is done at
488 call time, so if the underlying magic function is changed the alias
497 call time, so if the underlying magic function is changed the alias
489 will call the new function.
498 will call the new function.
490
499
491 Parameters
500 Parameters
492 ----------
501 ----------
493 alias_name : str
502 alias_name : str
494 The name of the magic to be registered.
503 The name of the magic to be registered.
495 magic_name : str
504 magic_name : str
496 The name of an existing magic.
505 The name of an existing magic.
497 magic_kind : str
506 magic_kind : str
498 Kind of magic, one of 'line' or 'cell'
507 Kind of magic, one of 'line' or 'cell'
499 """
508 """
500
509
501 # `validate_type` is too permissive, as it allows 'line_cell'
510 # `validate_type` is too permissive, as it allows 'line_cell'
502 # which we do not handle.
511 # which we do not handle.
503 if magic_kind not in magic_kinds:
512 if magic_kind not in magic_kinds:
504 raise ValueError('magic_kind must be one of %s, %s given' %
513 raise ValueError('magic_kind must be one of %s, %s given' %
505 magic_kinds, magic_kind)
514 magic_kinds, magic_kind)
506
515
507 alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
516 alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
508 setattr(self.user_magics, alias_name, alias)
517 setattr(self.user_magics, alias_name, alias)
509 record_magic(self.magics, magic_kind, alias_name, alias)
518 record_magic(self.magics, magic_kind, alias_name, alias)
510
519
511 # Key base class that provides the central functionality for magics.
520 # Key base class that provides the central functionality for magics.
512
521
513
522
514 class Magics(Configurable):
523 class Magics(Configurable):
515 """Base class for implementing magic functions.
524 """Base class for implementing magic functions.
516
525
517 Shell functions which can be reached as %function_name. All magic
526 Shell functions which can be reached as %function_name. All magic
518 functions should accept a string, which they can parse for their own
527 functions should accept a string, which they can parse for their own
519 needs. This can make some functions easier to type, eg `%cd ../`
528 needs. This can make some functions easier to type, eg `%cd ../`
520 vs. `%cd("../")`
529 vs. `%cd("../")`
521
530
522 Classes providing magic functions need to subclass this class, and they
531 Classes providing magic functions need to subclass this class, and they
523 MUST:
532 MUST:
524
533
525 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
534 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
526 individual methods as magic functions, AND
535 individual methods as magic functions, AND
527
536
528 - Use the class decorator `@magics_class` to ensure that the magic
537 - Use the class decorator `@magics_class` to ensure that the magic
529 methods are properly registered at the instance level upon instance
538 methods are properly registered at the instance level upon instance
530 initialization.
539 initialization.
531
540
532 See :mod:`magic_functions` for examples of actual implementation classes.
541 See :mod:`magic_functions` for examples of actual implementation classes.
533 """
542 """
534 # Dict holding all command-line options for each magic.
543 # Dict holding all command-line options for each magic.
535 options_table = None
544 options_table = None
536 # Dict for the mapping of magic names to methods, set by class decorator
545 # Dict for the mapping of magic names to methods, set by class decorator
537 magics = None
546 magics = None
538 # Flag to check that the class decorator was properly applied
547 # Flag to check that the class decorator was properly applied
539 registered = False
548 registered = False
540 # Instance of IPython shell
549 # Instance of IPython shell
541 shell = None
550 shell = None
542
551
543 def __init__(self, shell=None, **kwargs):
552 def __init__(self, shell=None, **kwargs):
544 if not(self.__class__.registered):
553 if not(self.__class__.registered):
545 raise ValueError('Magics subclass without registration - '
554 raise ValueError('Magics subclass without registration - '
546 'did you forget to apply @magics_class?')
555 'did you forget to apply @magics_class?')
547 if shell is not None:
556 if shell is not None:
548 if hasattr(shell, 'configurables'):
557 if hasattr(shell, 'configurables'):
549 shell.configurables.append(self)
558 shell.configurables.append(self)
550 if hasattr(shell, 'config'):
559 if hasattr(shell, 'config'):
551 kwargs.setdefault('parent', shell)
560 kwargs.setdefault('parent', shell)
552
561
553 self.shell = shell
562 self.shell = shell
554 self.options_table = {}
563 self.options_table = {}
555 # The method decorators are run when the instance doesn't exist yet, so
564 # The method decorators are run when the instance doesn't exist yet, so
556 # they can only record the names of the methods they are supposed to
565 # they can only record the names of the methods they are supposed to
557 # grab. Only now, that the instance exists, can we create the proper
566 # grab. Only now, that the instance exists, can we create the proper
558 # mapping to bound methods. So we read the info off the original names
567 # mapping to bound methods. So we read the info off the original names
559 # table and replace each method name by the actual bound method.
568 # table and replace each method name by the actual bound method.
560 # But we mustn't clobber the *class* mapping, in case of multiple instances.
569 # But we mustn't clobber the *class* mapping, in case of multiple instances.
561 class_magics = self.magics
570 class_magics = self.magics
562 self.magics = {}
571 self.magics = {}
563 for mtype in magic_kinds:
572 for mtype in magic_kinds:
564 tab = self.magics[mtype] = {}
573 tab = self.magics[mtype] = {}
565 cls_tab = class_magics[mtype]
574 cls_tab = class_magics[mtype]
566 for magic_name, meth_name in cls_tab.items():
575 for magic_name, meth_name in cls_tab.items():
567 if isinstance(meth_name, str):
576 if isinstance(meth_name, str):
568 # it's a method name, grab it
577 # it's a method name, grab it
569 tab[magic_name] = getattr(self, meth_name)
578 tab[magic_name] = getattr(self, meth_name)
570 else:
579 else:
571 # it's the real thing
580 # it's the real thing
572 tab[magic_name] = meth_name
581 tab[magic_name] = meth_name
573 # Configurable **needs** to be initiated at the end or the config
582 # Configurable **needs** to be initiated at the end or the config
574 # magics get screwed up.
583 # magics get screwed up.
575 super(Magics, self).__init__(**kwargs)
584 super(Magics, self).__init__(**kwargs)
576
585
577 def arg_err(self,func):
586 def arg_err(self,func):
578 """Print docstring if incorrect arguments were passed"""
587 """Print docstring if incorrect arguments were passed"""
579 print('Error in arguments:')
588 print('Error in arguments:')
580 print(oinspect.getdoc(func))
589 print(oinspect.getdoc(func))
581
590
582 def format_latex(self, strng):
591 def format_latex(self, strng):
583 """Format a string for latex inclusion."""
592 """Format a string for latex inclusion."""
584
593
585 # Characters that need to be escaped for latex:
594 # Characters that need to be escaped for latex:
586 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
595 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
587 # Magic command names as headers:
596 # Magic command names as headers:
588 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
597 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
589 re.MULTILINE)
598 re.MULTILINE)
590 # Magic commands
599 # Magic commands
591 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
600 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
592 re.MULTILINE)
601 re.MULTILINE)
593 # Paragraph continue
602 # Paragraph continue
594 par_re = re.compile(r'\\$',re.MULTILINE)
603 par_re = re.compile(r'\\$',re.MULTILINE)
595
604
596 # The "\n" symbol
605 # The "\n" symbol
597 newline_re = re.compile(r'\\n')
606 newline_re = re.compile(r'\\n')
598
607
599 # Now build the string for output:
608 # Now build the string for output:
600 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
609 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
601 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
610 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
602 strng)
611 strng)
603 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
612 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
604 strng = par_re.sub(r'\\\\',strng)
613 strng = par_re.sub(r'\\\\',strng)
605 strng = escape_re.sub(r'\\\1',strng)
614 strng = escape_re.sub(r'\\\1',strng)
606 strng = newline_re.sub(r'\\textbackslash{}n',strng)
615 strng = newline_re.sub(r'\\textbackslash{}n',strng)
607 return strng
616 return strng
608
617
609 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
618 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
610 """Parse options passed to an argument string.
619 """Parse options passed to an argument string.
611
620
612 The interface is similar to that of :func:`getopt.getopt`, but it
621 The interface is similar to that of :func:`getopt.getopt`, but it
613 returns a :class:`~IPython.utils.struct.Struct` with the options as keys
622 returns a :class:`~IPython.utils.struct.Struct` with the options as keys
614 and the stripped argument string still as a string.
623 and the stripped argument string still as a string.
615
624
616 arg_str is quoted as a true sys.argv vector by using shlex.split.
625 arg_str is quoted as a true sys.argv vector by using shlex.split.
617 This allows us to easily expand variables, glob files, quote
626 This allows us to easily expand variables, glob files, quote
618 arguments, etc.
627 arguments, etc.
619
628
620 Parameters
629 Parameters
621 ----------
630 ----------
622 arg_str : str
631 arg_str : str
623 The arguments to parse.
632 The arguments to parse.
624 opt_str : str
633 opt_str : str
625 The options specification.
634 The options specification.
626 mode : str, default 'string'
635 mode : str, default 'string'
627 If given as 'list', the argument string is returned as a list (split
636 If given as 'list', the argument string is returned as a list (split
628 on whitespace) instead of a string.
637 on whitespace) instead of a string.
629 list_all : bool, default False
638 list_all : bool, default False
630 Put all option values in lists. Normally only options
639 Put all option values in lists. Normally only options
631 appearing more than once are put in a list.
640 appearing more than once are put in a list.
632 posix : bool, default True
641 posix : bool, default True
633 Whether to split the input line in POSIX mode or not, as per the
642 Whether to split the input line in POSIX mode or not, as per the
634 conventions outlined in the :mod:`shlex` module from the standard
643 conventions outlined in the :mod:`shlex` module from the standard
635 library.
644 library.
636 """
645 """
637
646
638 # inject default options at the beginning of the input line
647 # inject default options at the beginning of the input line
639 caller = sys._getframe(1).f_code.co_name
648 caller = sys._getframe(1).f_code.co_name
640 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
649 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
641
650
642 mode = kw.get('mode','string')
651 mode = kw.get('mode','string')
643 if mode not in ['string','list']:
652 if mode not in ['string','list']:
644 raise ValueError('incorrect mode given: %s' % mode)
653 raise ValueError('incorrect mode given: %s' % mode)
645 # Get options
654 # Get options
646 list_all = kw.get('list_all',0)
655 list_all = kw.get('list_all',0)
647 posix = kw.get('posix', os.name == 'posix')
656 posix = kw.get('posix', os.name == 'posix')
648 strict = kw.get('strict', True)
657 strict = kw.get('strict', True)
649
658
650 preserve_non_opts = kw.get("preserve_non_opts", False)
659 preserve_non_opts = kw.get("preserve_non_opts", False)
651 remainder_arg_str = arg_str
660 remainder_arg_str = arg_str
652
661
653 # Check if we have more than one argument to warrant extra processing:
662 # Check if we have more than one argument to warrant extra processing:
654 odict = {} # Dictionary with options
663 odict = {} # Dictionary with options
655 args = arg_str.split()
664 args = arg_str.split()
656 if len(args) >= 1:
665 if len(args) >= 1:
657 # If the list of inputs only has 0 or 1 thing in it, there's no
666 # If the list of inputs only has 0 or 1 thing in it, there's no
658 # need to look for options
667 # need to look for options
659 argv = arg_split(arg_str, posix, strict)
668 argv = arg_split(arg_str, posix, strict)
660 # Do regular option processing
669 # Do regular option processing
661 try:
670 try:
662 opts,args = getopt(argv, opt_str, long_opts)
671 opts,args = getopt(argv, opt_str, long_opts)
663 except GetoptError as e:
672 except GetoptError as e:
664 raise UsageError(
673 raise UsageError(
665 '%s ( allowed: "%s" %s)' % (e.msg, opt_str, " ".join(long_opts))
674 '%s ( allowed: "%s" %s)' % (e.msg, opt_str, " ".join(long_opts))
666 ) from e
675 ) from e
667 for o, a in opts:
676 for o, a in opts:
668 if mode == "string" and preserve_non_opts:
677 if mode == "string" and preserve_non_opts:
669 # remove option-parts from the original args-string and preserve remaining-part.
678 # remove option-parts from the original args-string and preserve remaining-part.
670 # This relies on the arg_split(...) and getopt(...)'s impl spec, that the parsed options are
679 # This relies on the arg_split(...) and getopt(...)'s impl spec, that the parsed options are
671 # returned in the original order.
680 # returned in the original order.
672 remainder_arg_str = remainder_arg_str.replace(o, "", 1).replace(
681 remainder_arg_str = remainder_arg_str.replace(o, "", 1).replace(
673 a, "", 1
682 a, "", 1
674 )
683 )
675 if o.startswith("--"):
684 if o.startswith("--"):
676 o = o[2:]
685 o = o[2:]
677 else:
686 else:
678 o = o[1:]
687 o = o[1:]
679 try:
688 try:
680 odict[o].append(a)
689 odict[o].append(a)
681 except AttributeError:
690 except AttributeError:
682 odict[o] = [odict[o],a]
691 odict[o] = [odict[o],a]
683 except KeyError:
692 except KeyError:
684 if list_all:
693 if list_all:
685 odict[o] = [a]
694 odict[o] = [a]
686 else:
695 else:
687 odict[o] = a
696 odict[o] = a
688
697
689 # Prepare opts,args for return
698 # Prepare opts,args for return
690 opts = Struct(odict)
699 opts = Struct(odict)
691 if mode == 'string':
700 if mode == 'string':
692 if preserve_non_opts:
701 if preserve_non_opts:
693 args = remainder_arg_str.lstrip()
702 args = remainder_arg_str.lstrip()
694 else:
703 else:
695 args = " ".join(args)
704 args = " ".join(args)
696
705
697 return opts,args
706 return opts,args
698
707
699 def default_option(self, fn, optstr):
708 def default_option(self, fn, optstr):
700 """Make an entry in the options_table for fn, with value optstr"""
709 """Make an entry in the options_table for fn, with value optstr"""
701
710
702 if fn not in self.lsmagic():
711 if fn not in self.lsmagic():
703 error("%s is not a magic function" % fn)
712 error("%s is not a magic function" % fn)
704 self.options_table[fn] = optstr
713 self.options_table[fn] = optstr
705
714
706
715
707 class MagicAlias(object):
716 class MagicAlias(object):
708 """An alias to another magic function.
717 """An alias to another magic function.
709
718
710 An alias is determined by its magic name and magic kind. Lookup
719 An alias is determined by its magic name and magic kind. Lookup
711 is done at call time, so if the underlying magic changes the alias
720 is done at call time, so if the underlying magic changes the alias
712 will call the new function.
721 will call the new function.
713
722
714 Use the :meth:`MagicsManager.register_alias` method or the
723 Use the :meth:`MagicsManager.register_alias` method or the
715 `%alias_magic` magic function to create and register a new alias.
724 `%alias_magic` magic function to create and register a new alias.
716 """
725 """
717 def __init__(self, shell, magic_name, magic_kind, magic_params=None):
726 def __init__(self, shell, magic_name, magic_kind, magic_params=None):
718 self.shell = shell
727 self.shell = shell
719 self.magic_name = magic_name
728 self.magic_name = magic_name
720 self.magic_params = magic_params
729 self.magic_params = magic_params
721 self.magic_kind = magic_kind
730 self.magic_kind = magic_kind
722
731
723 self.pretty_target = '%s%s' % (magic_escapes[self.magic_kind], self.magic_name)
732 self.pretty_target = '%s%s' % (magic_escapes[self.magic_kind], self.magic_name)
724 self.__doc__ = "Alias for `%s`." % self.pretty_target
733 self.__doc__ = "Alias for `%s`." % self.pretty_target
725
734
726 self._in_call = False
735 self._in_call = False
727
736
728 def __call__(self, *args, **kwargs):
737 def __call__(self, *args, **kwargs):
729 """Call the magic alias."""
738 """Call the magic alias."""
730 fn = self.shell.find_magic(self.magic_name, self.magic_kind)
739 fn = self.shell.find_magic(self.magic_name, self.magic_kind)
731 if fn is None:
740 if fn is None:
732 raise UsageError("Magic `%s` not found." % self.pretty_target)
741 raise UsageError("Magic `%s` not found." % self.pretty_target)
733
742
734 # Protect against infinite recursion.
743 # Protect against infinite recursion.
735 if self._in_call:
744 if self._in_call:
736 raise UsageError("Infinite recursion detected; "
745 raise UsageError("Infinite recursion detected; "
737 "magic aliases cannot call themselves.")
746 "magic aliases cannot call themselves.")
738 self._in_call = True
747 self._in_call = True
739 try:
748 try:
740 if self.magic_params:
749 if self.magic_params:
741 args_list = list(args)
750 args_list = list(args)
742 args_list[0] = self.magic_params + " " + args[0]
751 args_list[0] = self.magic_params + " " + args[0]
743 args = tuple(args_list)
752 args = tuple(args_list)
744 return fn(*args, **kwargs)
753 return fn(*args, **kwargs)
745 finally:
754 finally:
746 self._in_call = False
755 self._in_call = False
@@ -1,1510 +1,1512 b''
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 cProfile as profile
11 import cProfile as profile
12 import gc
12 import gc
13 import itertools
13 import itertools
14 import math
14 import math
15 import os
15 import os
16 import pstats
16 import pstats
17 import re
17 import re
18 import shlex
18 import shlex
19 import sys
19 import sys
20 import time
20 import time
21 import timeit
21 import timeit
22 from ast import Module
22 from ast import Module
23 from io import StringIO
23 from io import StringIO
24 from logging import error
24 from logging import error
25 from pathlib import Path
25 from pathlib import Path
26 from pdb import Restart
26 from pdb import Restart
27 from warnings import warn
27 from warnings import warn
28
28
29 from IPython.core import magic_arguments, oinspect, page
29 from IPython.core import magic_arguments, oinspect, page
30 from IPython.core.error import UsageError
30 from IPython.core.error import UsageError
31 from IPython.core.macro import Macro
31 from IPython.core.macro import Macro
32 from IPython.core.magic import (
32 from IPython.core.magic import (
33 Magics,
33 Magics,
34 cell_magic,
34 cell_magic,
35 line_cell_magic,
35 line_cell_magic,
36 line_magic,
36 line_magic,
37 magics_class,
37 magics_class,
38 needs_local_scope,
38 needs_local_scope,
39 no_var_expand,
39 no_var_expand,
40 output_can_be_disabled,
40 on_off,
41 on_off,
41 )
42 )
42 from IPython.testing.skipdoctest import skip_doctest
43 from IPython.testing.skipdoctest import skip_doctest
43 from IPython.utils.capture import capture_output
44 from IPython.utils.capture import capture_output
44 from IPython.utils.contexts import preserve_keys
45 from IPython.utils.contexts import preserve_keys
45 from IPython.utils.ipstruct import Struct
46 from IPython.utils.ipstruct import Struct
46 from IPython.utils.module_paths import find_mod
47 from IPython.utils.module_paths import find_mod
47 from IPython.utils.path import get_py_filename, shellglob
48 from IPython.utils.path import get_py_filename, shellglob
48 from IPython.utils.timing import clock, clock2
49 from IPython.utils.timing import clock, clock2
49
50
50 #-----------------------------------------------------------------------------
51 #-----------------------------------------------------------------------------
51 # Magic implementation classes
52 # Magic implementation classes
52 #-----------------------------------------------------------------------------
53 #-----------------------------------------------------------------------------
53
54
54
55
55 class TimeitResult(object):
56 class TimeitResult(object):
56 """
57 """
57 Object returned by the timeit magic with info about the run.
58 Object returned by the timeit magic with info about the run.
58
59
59 Contains the following attributes :
60 Contains the following attributes :
60
61
61 loops: (int) number of loops done per measurement
62 loops: (int) number of loops done per measurement
62 repeat: (int) number of times the measurement has been repeated
63 repeat: (int) number of times the measurement has been repeated
63 best: (float) best execution time / number
64 best: (float) best execution time / number
64 all_runs: (list of float) execution time of each run (in s)
65 all_runs: (list of float) execution time of each run (in s)
65 compile_time: (float) time of statement compilation (s)
66 compile_time: (float) time of statement compilation (s)
66
67
67 """
68 """
68 def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
69 def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
69 self.loops = loops
70 self.loops = loops
70 self.repeat = repeat
71 self.repeat = repeat
71 self.best = best
72 self.best = best
72 self.worst = worst
73 self.worst = worst
73 self.all_runs = all_runs
74 self.all_runs = all_runs
74 self.compile_time = compile_time
75 self.compile_time = compile_time
75 self._precision = precision
76 self._precision = precision
76 self.timings = [ dt / self.loops for dt in all_runs]
77 self.timings = [ dt / self.loops for dt in all_runs]
77
78
78 @property
79 @property
79 def average(self):
80 def average(self):
80 return math.fsum(self.timings) / len(self.timings)
81 return math.fsum(self.timings) / len(self.timings)
81
82
82 @property
83 @property
83 def stdev(self):
84 def stdev(self):
84 mean = self.average
85 mean = self.average
85 return (math.fsum([(x - mean) ** 2 for x in self.timings]) / len(self.timings)) ** 0.5
86 return (math.fsum([(x - mean) ** 2 for x in self.timings]) / len(self.timings)) ** 0.5
86
87
87 def __str__(self):
88 def __str__(self):
88 pm = '+-'
89 pm = '+-'
89 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
90 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
90 try:
91 try:
91 u'\xb1'.encode(sys.stdout.encoding)
92 u'\xb1'.encode(sys.stdout.encoding)
92 pm = u'\xb1'
93 pm = u'\xb1'
93 except:
94 except:
94 pass
95 pass
95 return "{mean} {pm} {std} per loop (mean {pm} std. dev. of {runs} run{run_plural}, {loops:,} loop{loop_plural} each)".format(
96 return "{mean} {pm} {std} per loop (mean {pm} std. dev. of {runs} run{run_plural}, {loops:,} loop{loop_plural} each)".format(
96 pm=pm,
97 pm=pm,
97 runs=self.repeat,
98 runs=self.repeat,
98 loops=self.loops,
99 loops=self.loops,
99 loop_plural="" if self.loops == 1 else "s",
100 loop_plural="" if self.loops == 1 else "s",
100 run_plural="" if self.repeat == 1 else "s",
101 run_plural="" if self.repeat == 1 else "s",
101 mean=_format_time(self.average, self._precision),
102 mean=_format_time(self.average, self._precision),
102 std=_format_time(self.stdev, self._precision),
103 std=_format_time(self.stdev, self._precision),
103 )
104 )
104
105
105 def _repr_pretty_(self, p , cycle):
106 def _repr_pretty_(self, p , cycle):
106 unic = self.__str__()
107 unic = self.__str__()
107 p.text(u'<TimeitResult : '+unic+u'>')
108 p.text(u'<TimeitResult : '+unic+u'>')
108
109
109
110
110 class TimeitTemplateFiller(ast.NodeTransformer):
111 class TimeitTemplateFiller(ast.NodeTransformer):
111 """Fill in the AST template for timing execution.
112 """Fill in the AST template for timing execution.
112
113
113 This is quite closely tied to the template definition, which is in
114 This is quite closely tied to the template definition, which is in
114 :meth:`ExecutionMagics.timeit`.
115 :meth:`ExecutionMagics.timeit`.
115 """
116 """
116 def __init__(self, ast_setup, ast_stmt):
117 def __init__(self, ast_setup, ast_stmt):
117 self.ast_setup = ast_setup
118 self.ast_setup = ast_setup
118 self.ast_stmt = ast_stmt
119 self.ast_stmt = ast_stmt
119
120
120 def visit_FunctionDef(self, node):
121 def visit_FunctionDef(self, node):
121 "Fill in the setup statement"
122 "Fill in the setup statement"
122 self.generic_visit(node)
123 self.generic_visit(node)
123 if node.name == "inner":
124 if node.name == "inner":
124 node.body[:1] = self.ast_setup.body
125 node.body[:1] = self.ast_setup.body
125
126
126 return node
127 return node
127
128
128 def visit_For(self, node):
129 def visit_For(self, node):
129 "Fill in the statement to be timed"
130 "Fill in the statement to be timed"
130 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
131 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
131 node.body = self.ast_stmt.body
132 node.body = self.ast_stmt.body
132 return node
133 return node
133
134
134
135
135 class Timer(timeit.Timer):
136 class Timer(timeit.Timer):
136 """Timer class that explicitly uses self.inner
137 """Timer class that explicitly uses self.inner
137
138
138 which is an undocumented implementation detail of CPython,
139 which is an undocumented implementation detail of CPython,
139 not shared by PyPy.
140 not shared by PyPy.
140 """
141 """
141 # Timer.timeit copied from CPython 3.4.2
142 # Timer.timeit copied from CPython 3.4.2
142 def timeit(self, number=timeit.default_number):
143 def timeit(self, number=timeit.default_number):
143 """Time 'number' executions of the main statement.
144 """Time 'number' executions of the main statement.
144
145
145 To be precise, this executes the setup statement once, and
146 To be precise, this executes the setup statement once, and
146 then returns the time it takes to execute the main statement
147 then returns the time it takes to execute the main statement
147 a number of times, as a float measured in seconds. The
148 a number of times, as a float measured in seconds. The
148 argument is the number of times through the loop, defaulting
149 argument is the number of times through the loop, defaulting
149 to one million. The main statement, the setup statement and
150 to one million. The main statement, the setup statement and
150 the timer function to be used are passed to the constructor.
151 the timer function to be used are passed to the constructor.
151 """
152 """
152 it = itertools.repeat(None, number)
153 it = itertools.repeat(None, number)
153 gcold = gc.isenabled()
154 gcold = gc.isenabled()
154 gc.disable()
155 gc.disable()
155 try:
156 try:
156 timing = self.inner(it, self.timer)
157 timing = self.inner(it, self.timer)
157 finally:
158 finally:
158 if gcold:
159 if gcold:
159 gc.enable()
160 gc.enable()
160 return timing
161 return timing
161
162
162
163
163 @magics_class
164 @magics_class
164 class ExecutionMagics(Magics):
165 class ExecutionMagics(Magics):
165 """Magics related to code execution, debugging, profiling, etc.
166 """Magics related to code execution, debugging, profiling, etc.
166
167
167 """
168 """
168
169
169 def __init__(self, shell):
170 def __init__(self, shell):
170 super(ExecutionMagics, self).__init__(shell)
171 super(ExecutionMagics, self).__init__(shell)
171 # Default execution function used to actually run user code.
172 # Default execution function used to actually run user code.
172 self.default_runner = None
173 self.default_runner = None
173
174
174 @skip_doctest
175 @skip_doctest
175 @no_var_expand
176 @no_var_expand
176 @line_cell_magic
177 @line_cell_magic
177 def prun(self, parameter_s='', cell=None):
178 def prun(self, parameter_s='', cell=None):
178
179
179 """Run a statement through the python code profiler.
180 """Run a statement through the python code profiler.
180
181
181 Usage, in line mode:
182 Usage, in line mode:
182 %prun [options] statement
183 %prun [options] statement
183
184
184 Usage, in cell mode:
185 Usage, in cell mode:
185 %%prun [options] [statement]
186 %%prun [options] [statement]
186 code...
187 code...
187 code...
188 code...
188
189
189 In cell mode, the additional code lines are appended to the (possibly
190 In cell mode, the additional code lines are appended to the (possibly
190 empty) statement in the first line. Cell mode allows you to easily
191 empty) statement in the first line. Cell mode allows you to easily
191 profile multiline blocks without having to put them in a separate
192 profile multiline blocks without having to put them in a separate
192 function.
193 function.
193
194
194 The given statement (which doesn't require quote marks) is run via the
195 The given statement (which doesn't require quote marks) is run via the
195 python profiler in a manner similar to the profile.run() function.
196 python profiler in a manner similar to the profile.run() function.
196 Namespaces are internally managed to work correctly; profile.run
197 Namespaces are internally managed to work correctly; profile.run
197 cannot be used in IPython because it makes certain assumptions about
198 cannot be used in IPython because it makes certain assumptions about
198 namespaces which do not hold under IPython.
199 namespaces which do not hold under IPython.
199
200
200 Options:
201 Options:
201
202
202 -l <limit>
203 -l <limit>
203 you can place restrictions on what or how much of the
204 you can place restrictions on what or how much of the
204 profile gets printed. The limit value can be:
205 profile gets printed. The limit value can be:
205
206
206 * A string: only information for function names containing this string
207 * A string: only information for function names containing this string
207 is printed.
208 is printed.
208
209
209 * An integer: only these many lines are printed.
210 * An integer: only these many lines are printed.
210
211
211 * A float (between 0 and 1): this fraction of the report is printed
212 * A float (between 0 and 1): this fraction of the report is printed
212 (for example, use a limit of 0.4 to see the topmost 40% only).
213 (for example, use a limit of 0.4 to see the topmost 40% only).
213
214
214 You can combine several limits with repeated use of the option. For
215 You can combine several limits with repeated use of the option. For
215 example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
216 example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
216 information about class constructors.
217 information about class constructors.
217
218
218 -r
219 -r
219 return the pstats.Stats object generated by the profiling. This
220 return the pstats.Stats object generated by the profiling. This
220 object has all the information about the profile in it, and you can
221 object has all the information about the profile in it, and you can
221 later use it for further analysis or in other functions.
222 later use it for further analysis or in other functions.
222
223
223 -s <key>
224 -s <key>
224 sort profile by given key. You can provide more than one key
225 sort profile by given key. You can provide more than one key
225 by using the option several times: '-s key1 -s key2 -s key3...'. The
226 by using the option several times: '-s key1 -s key2 -s key3...'. The
226 default sorting key is 'time'.
227 default sorting key is 'time'.
227
228
228 The following is copied verbatim from the profile documentation
229 The following is copied verbatim from the profile documentation
229 referenced below:
230 referenced below:
230
231
231 When more than one key is provided, additional keys are used as
232 When more than one key is provided, additional keys are used as
232 secondary criteria when the there is equality in all keys selected
233 secondary criteria when the there is equality in all keys selected
233 before them.
234 before them.
234
235
235 Abbreviations can be used for any key names, as long as the
236 Abbreviations can be used for any key names, as long as the
236 abbreviation is unambiguous. The following are the keys currently
237 abbreviation is unambiguous. The following are the keys currently
237 defined:
238 defined:
238
239
239 ============ =====================
240 ============ =====================
240 Valid Arg Meaning
241 Valid Arg Meaning
241 ============ =====================
242 ============ =====================
242 "calls" call count
243 "calls" call count
243 "cumulative" cumulative time
244 "cumulative" cumulative time
244 "file" file name
245 "file" file name
245 "module" file name
246 "module" file name
246 "pcalls" primitive call count
247 "pcalls" primitive call count
247 "line" line number
248 "line" line number
248 "name" function name
249 "name" function name
249 "nfl" name/file/line
250 "nfl" name/file/line
250 "stdname" standard name
251 "stdname" standard name
251 "time" internal time
252 "time" internal time
252 ============ =====================
253 ============ =====================
253
254
254 Note that all sorts on statistics are in descending order (placing
255 Note that all sorts on statistics are in descending order (placing
255 most time consuming items first), where as name, file, and line number
256 most time consuming items first), where as name, file, and line number
256 searches are in ascending order (i.e., alphabetical). The subtle
257 searches are in ascending order (i.e., alphabetical). The subtle
257 distinction between "nfl" and "stdname" is that the standard name is a
258 distinction between "nfl" and "stdname" is that the standard name is a
258 sort of the name as printed, which means that the embedded line
259 sort of the name as printed, which means that the embedded line
259 numbers get compared in an odd way. For example, lines 3, 20, and 40
260 numbers get compared in an odd way. For example, lines 3, 20, and 40
260 would (if the file names were the same) appear in the string order
261 would (if the file names were the same) appear in the string order
261 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
262 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
262 line numbers. In fact, sort_stats("nfl") is the same as
263 line numbers. In fact, sort_stats("nfl") is the same as
263 sort_stats("name", "file", "line").
264 sort_stats("name", "file", "line").
264
265
265 -T <filename>
266 -T <filename>
266 save profile results as shown on screen to a text
267 save profile results as shown on screen to a text
267 file. The profile is still shown on screen.
268 file. The profile is still shown on screen.
268
269
269 -D <filename>
270 -D <filename>
270 save (via dump_stats) profile statistics to given
271 save (via dump_stats) profile statistics to given
271 filename. This data is in a format understood by the pstats module, and
272 filename. This data is in a format understood by the pstats module, and
272 is generated by a call to the dump_stats() method of profile
273 is generated by a call to the dump_stats() method of profile
273 objects. The profile is still shown on screen.
274 objects. The profile is still shown on screen.
274
275
275 -q
276 -q
276 suppress output to the pager. Best used with -T and/or -D above.
277 suppress output to the pager. Best used with -T and/or -D above.
277
278
278 If you want to run complete programs under the profiler's control, use
279 If you want to run complete programs under the profiler's control, use
279 ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
280 ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
280 contains profiler specific options as described here.
281 contains profiler specific options as described here.
281
282
282 You can read the complete documentation for the profile module with::
283 You can read the complete documentation for the profile module with::
283
284
284 In [1]: import profile; profile.help()
285 In [1]: import profile; profile.help()
285
286
286 .. versionchanged:: 7.3
287 .. versionchanged:: 7.3
287 User variables are no longer expanded,
288 User variables are no longer expanded,
288 the magic line is always left unmodified.
289 the magic line is always left unmodified.
289
290
290 """
291 """
291 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
292 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
292 list_all=True, posix=False)
293 list_all=True, posix=False)
293 if cell is not None:
294 if cell is not None:
294 arg_str += '\n' + cell
295 arg_str += '\n' + cell
295 arg_str = self.shell.transform_cell(arg_str)
296 arg_str = self.shell.transform_cell(arg_str)
296 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
297 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
297
298
298 def _run_with_profiler(self, code, opts, namespace):
299 def _run_with_profiler(self, code, opts, namespace):
299 """
300 """
300 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
301 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
301
302
302 Parameters
303 Parameters
303 ----------
304 ----------
304 code : str
305 code : str
305 Code to be executed.
306 Code to be executed.
306 opts : Struct
307 opts : Struct
307 Options parsed by `self.parse_options`.
308 Options parsed by `self.parse_options`.
308 namespace : dict
309 namespace : dict
309 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
310 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
310
311
311 """
312 """
312
313
313 # Fill default values for unspecified options:
314 # Fill default values for unspecified options:
314 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
315 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
315
316
316 prof = profile.Profile()
317 prof = profile.Profile()
317 try:
318 try:
318 prof = prof.runctx(code, namespace, namespace)
319 prof = prof.runctx(code, namespace, namespace)
319 sys_exit = ''
320 sys_exit = ''
320 except SystemExit:
321 except SystemExit:
321 sys_exit = """*** SystemExit exception caught in code being profiled."""
322 sys_exit = """*** SystemExit exception caught in code being profiled."""
322
323
323 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
324 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
324
325
325 lims = opts.l
326 lims = opts.l
326 if lims:
327 if lims:
327 lims = [] # rebuild lims with ints/floats/strings
328 lims = [] # rebuild lims with ints/floats/strings
328 for lim in opts.l:
329 for lim in opts.l:
329 try:
330 try:
330 lims.append(int(lim))
331 lims.append(int(lim))
331 except ValueError:
332 except ValueError:
332 try:
333 try:
333 lims.append(float(lim))
334 lims.append(float(lim))
334 except ValueError:
335 except ValueError:
335 lims.append(lim)
336 lims.append(lim)
336
337
337 # Trap output.
338 # Trap output.
338 stdout_trap = StringIO()
339 stdout_trap = StringIO()
339 stats_stream = stats.stream
340 stats_stream = stats.stream
340 try:
341 try:
341 stats.stream = stdout_trap
342 stats.stream = stdout_trap
342 stats.print_stats(*lims)
343 stats.print_stats(*lims)
343 finally:
344 finally:
344 stats.stream = stats_stream
345 stats.stream = stats_stream
345
346
346 output = stdout_trap.getvalue()
347 output = stdout_trap.getvalue()
347 output = output.rstrip()
348 output = output.rstrip()
348
349
349 if 'q' not in opts:
350 if 'q' not in opts:
350 page.page(output)
351 page.page(output)
351 print(sys_exit, end=' ')
352 print(sys_exit, end=' ')
352
353
353 dump_file = opts.D[0]
354 dump_file = opts.D[0]
354 text_file = opts.T[0]
355 text_file = opts.T[0]
355 if dump_file:
356 if dump_file:
356 prof.dump_stats(dump_file)
357 prof.dump_stats(dump_file)
357 print(
358 print(
358 f"\n*** Profile stats marshalled to file {repr(dump_file)}.{sys_exit}"
359 f"\n*** Profile stats marshalled to file {repr(dump_file)}.{sys_exit}"
359 )
360 )
360 if text_file:
361 if text_file:
361 pfile = Path(text_file)
362 pfile = Path(text_file)
362 pfile.touch(exist_ok=True)
363 pfile.touch(exist_ok=True)
363 pfile.write_text(output, encoding="utf-8")
364 pfile.write_text(output, encoding="utf-8")
364
365
365 print(
366 print(
366 f"\n*** Profile printout saved to text file {repr(text_file)}.{sys_exit}"
367 f"\n*** Profile printout saved to text file {repr(text_file)}.{sys_exit}"
367 )
368 )
368
369
369 if 'r' in opts:
370 if 'r' in opts:
370 return stats
371 return stats
371
372
372 return None
373 return None
373
374
374 @line_magic
375 @line_magic
375 def pdb(self, parameter_s=''):
376 def pdb(self, parameter_s=''):
376 """Control the automatic calling of the pdb interactive debugger.
377 """Control the automatic calling of the pdb interactive debugger.
377
378
378 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
379 argument it works as a toggle.
380 argument it works as a toggle.
380
381
381 When an exception is triggered, IPython can optionally call the
382 When an exception is triggered, IPython can optionally call the
382 interactive pdb debugger after the traceback printout. %pdb toggles
383 interactive pdb debugger after the traceback printout. %pdb toggles
383 this feature on and off.
384 this feature on and off.
384
385
385 The initial state of this feature is set in your configuration
386 The initial state of this feature is set in your configuration
386 file (the option is ``InteractiveShell.pdb``).
387 file (the option is ``InteractiveShell.pdb``).
387
388
388 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,
389 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
390 the %debug magic."""
391 the %debug magic."""
391
392
392 par = parameter_s.strip().lower()
393 par = parameter_s.strip().lower()
393
394
394 if par:
395 if par:
395 try:
396 try:
396 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
397 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
397 except KeyError:
398 except KeyError:
398 print ('Incorrect argument. Use on/1, off/0, '
399 print ('Incorrect argument. Use on/1, off/0, '
399 'or nothing for a toggle.')
400 'or nothing for a toggle.')
400 return
401 return
401 else:
402 else:
402 # toggle
403 # toggle
403 new_pdb = not self.shell.call_pdb
404 new_pdb = not self.shell.call_pdb
404
405
405 # set on the shell
406 # set on the shell
406 self.shell.call_pdb = new_pdb
407 self.shell.call_pdb = new_pdb
407 print('Automatic pdb calling has been turned',on_off(new_pdb))
408 print('Automatic pdb calling has been turned',on_off(new_pdb))
408
409
409 @magic_arguments.magic_arguments()
410 @magic_arguments.magic_arguments()
410 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
411 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
411 help="""
412 help="""
412 Set break point at LINE in FILE.
413 Set break point at LINE in FILE.
413 """
414 """
414 )
415 )
415 @magic_arguments.argument('statement', nargs='*',
416 @magic_arguments.argument('statement', nargs='*',
416 help="""
417 help="""
417 Code to run in debugger.
418 Code to run in debugger.
418 You can omit this in cell magic mode.
419 You can omit this in cell magic mode.
419 """
420 """
420 )
421 )
421 @no_var_expand
422 @no_var_expand
422 @line_cell_magic
423 @line_cell_magic
423 def debug(self, line='', cell=None):
424 def debug(self, line='', cell=None):
424 """Activate the interactive debugger.
425 """Activate the interactive debugger.
425
426
426 This magic command support two ways of activating debugger.
427 This magic command support two ways of activating debugger.
427 One is to activate debugger before executing code. This way, you
428 One is to activate debugger before executing code. This way, you
428 can set a break point, to step through the code from the point.
429 can set a break point, to step through the code from the point.
429 You can use this mode by giving statements to execute and optionally
430 You can use this mode by giving statements to execute and optionally
430 a breakpoint.
431 a breakpoint.
431
432
432 The other one is to activate debugger in post-mortem mode. You can
433 The other one is to activate debugger in post-mortem mode. You can
433 activate this mode simply running %debug without any argument.
434 activate this mode simply running %debug without any argument.
434 If an exception has just occurred, this lets you inspect its stack
435 If an exception has just occurred, this lets you inspect its stack
435 frames interactively. Note that this will always work only on the last
436 frames interactively. Note that this will always work only on the last
436 traceback that occurred, so you must call this quickly after an
437 traceback that occurred, so you must call this quickly after an
437 exception that you wish to inspect has fired, because if another one
438 exception that you wish to inspect has fired, because if another one
438 occurs, it clobbers the previous one.
439 occurs, it clobbers the previous one.
439
440
440 If you want IPython to automatically do this on every exception, see
441 If you want IPython to automatically do this on every exception, see
441 the %pdb magic for more details.
442 the %pdb magic for more details.
442
443
443 .. versionchanged:: 7.3
444 .. versionchanged:: 7.3
444 When running code, user variables are no longer expanded,
445 When running code, user variables are no longer expanded,
445 the magic line is always left unmodified.
446 the magic line is always left unmodified.
446
447
447 """
448 """
448 args = magic_arguments.parse_argstring(self.debug, line)
449 args = magic_arguments.parse_argstring(self.debug, line)
449
450
450 if not (args.breakpoint or args.statement or cell):
451 if not (args.breakpoint or args.statement or cell):
451 self._debug_post_mortem()
452 self._debug_post_mortem()
452 elif not (args.breakpoint or cell):
453 elif not (args.breakpoint or cell):
453 # If there is no breakpoints, the line is just code to execute
454 # If there is no breakpoints, the line is just code to execute
454 self._debug_exec(line, None)
455 self._debug_exec(line, None)
455 else:
456 else:
456 # Here we try to reconstruct the code from the output of
457 # Here we try to reconstruct the code from the output of
457 # parse_argstring. This might not work if the code has spaces
458 # parse_argstring. This might not work if the code has spaces
458 # For example this fails for `print("a b")`
459 # For example this fails for `print("a b")`
459 code = "\n".join(args.statement)
460 code = "\n".join(args.statement)
460 if cell:
461 if cell:
461 code += "\n" + cell
462 code += "\n" + cell
462 self._debug_exec(code, args.breakpoint)
463 self._debug_exec(code, args.breakpoint)
463
464
464 def _debug_post_mortem(self):
465 def _debug_post_mortem(self):
465 self.shell.debugger(force=True)
466 self.shell.debugger(force=True)
466
467
467 def _debug_exec(self, code, breakpoint):
468 def _debug_exec(self, code, breakpoint):
468 if breakpoint:
469 if breakpoint:
469 (filename, bp_line) = breakpoint.rsplit(':', 1)
470 (filename, bp_line) = breakpoint.rsplit(':', 1)
470 bp_line = int(bp_line)
471 bp_line = int(bp_line)
471 else:
472 else:
472 (filename, bp_line) = (None, None)
473 (filename, bp_line) = (None, None)
473 self._run_with_debugger(code, self.shell.user_ns, filename, bp_line)
474 self._run_with_debugger(code, self.shell.user_ns, filename, bp_line)
474
475
475 @line_magic
476 @line_magic
476 def tb(self, s):
477 def tb(self, s):
477 """Print the last traceback.
478 """Print the last traceback.
478
479
479 Optionally, specify an exception reporting mode, tuning the
480 Optionally, specify an exception reporting mode, tuning the
480 verbosity of the traceback. By default the currently-active exception
481 verbosity of the traceback. By default the currently-active exception
481 mode is used. See %xmode for changing exception reporting modes.
482 mode is used. See %xmode for changing exception reporting modes.
482
483
483 Valid modes: Plain, Context, Verbose, and Minimal.
484 Valid modes: Plain, Context, Verbose, and Minimal.
484 """
485 """
485 interactive_tb = self.shell.InteractiveTB
486 interactive_tb = self.shell.InteractiveTB
486 if s:
487 if s:
487 # Switch exception reporting mode for this one call.
488 # Switch exception reporting mode for this one call.
488 # Ensure it is switched back.
489 # Ensure it is switched back.
489 def xmode_switch_err(name):
490 def xmode_switch_err(name):
490 warn('Error changing %s exception modes.\n%s' %
491 warn('Error changing %s exception modes.\n%s' %
491 (name,sys.exc_info()[1]))
492 (name,sys.exc_info()[1]))
492
493
493 new_mode = s.strip().capitalize()
494 new_mode = s.strip().capitalize()
494 original_mode = interactive_tb.mode
495 original_mode = interactive_tb.mode
495 try:
496 try:
496 try:
497 try:
497 interactive_tb.set_mode(mode=new_mode)
498 interactive_tb.set_mode(mode=new_mode)
498 except Exception:
499 except Exception:
499 xmode_switch_err('user')
500 xmode_switch_err('user')
500 else:
501 else:
501 self.shell.showtraceback()
502 self.shell.showtraceback()
502 finally:
503 finally:
503 interactive_tb.set_mode(mode=original_mode)
504 interactive_tb.set_mode(mode=original_mode)
504 else:
505 else:
505 self.shell.showtraceback()
506 self.shell.showtraceback()
506
507
507 @skip_doctest
508 @skip_doctest
508 @line_magic
509 @line_magic
509 def run(self, parameter_s='', runner=None,
510 def run(self, parameter_s='', runner=None,
510 file_finder=get_py_filename):
511 file_finder=get_py_filename):
511 """Run the named file inside IPython as a program.
512 """Run the named file inside IPython as a program.
512
513
513 Usage::
514 Usage::
514
515
515 %run [-n -i -e -G]
516 %run [-n -i -e -G]
516 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
517 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
517 ( -m mod | filename ) [args]
518 ( -m mod | filename ) [args]
518
519
519 The filename argument should be either a pure Python script (with
520 The filename argument should be either a pure Python script (with
520 extension ``.py``), or a file with custom IPython syntax (such as
521 extension ``.py``), or a file with custom IPython syntax (such as
521 magics). If the latter, the file can be either a script with ``.ipy``
522 magics). If the latter, the file can be either a script with ``.ipy``
522 extension, or a Jupyter notebook with ``.ipynb`` extension. When running
523 extension, or a Jupyter notebook with ``.ipynb`` extension. When running
523 a Jupyter notebook, the output from print statements and other
524 a Jupyter notebook, the output from print statements and other
524 displayed objects will appear in the terminal (even matplotlib figures
525 displayed objects will appear in the terminal (even matplotlib figures
525 will open, if a terminal-compliant backend is being used). Note that,
526 will open, if a terminal-compliant backend is being used). Note that,
526 at the system command line, the ``jupyter run`` command offers similar
527 at the system command line, the ``jupyter run`` command offers similar
527 functionality for executing notebooks (albeit currently with some
528 functionality for executing notebooks (albeit currently with some
528 differences in supported options).
529 differences in supported options).
529
530
530 Parameters after the filename are passed as command-line arguments to
531 Parameters after the filename are passed as command-line arguments to
531 the program (put in sys.argv). Then, control returns to IPython's
532 the program (put in sys.argv). Then, control returns to IPython's
532 prompt.
533 prompt.
533
534
534 This is similar to running at a system prompt ``python file args``,
535 This is similar to running at a system prompt ``python file args``,
535 but with the advantage of giving you IPython's tracebacks, and of
536 but with the advantage of giving you IPython's tracebacks, and of
536 loading all variables into your interactive namespace for further use
537 loading all variables into your interactive namespace for further use
537 (unless -p is used, see below).
538 (unless -p is used, see below).
538
539
539 The file is executed in a namespace initially consisting only of
540 The file is executed in a namespace initially consisting only of
540 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
541 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
541 sees its environment as if it were being run as a stand-alone program
542 sees its environment as if it were being run as a stand-alone program
542 (except for sharing global objects such as previously imported
543 (except for sharing global objects such as previously imported
543 modules). But after execution, the IPython interactive namespace gets
544 modules). But after execution, the IPython interactive namespace gets
544 updated with all variables defined in the program (except for __name__
545 updated with all variables defined in the program (except for __name__
545 and sys.argv). This allows for very convenient loading of code for
546 and sys.argv). This allows for very convenient loading of code for
546 interactive work, while giving each program a 'clean sheet' to run in.
547 interactive work, while giving each program a 'clean sheet' to run in.
547
548
548 Arguments are expanded using shell-like glob match. Patterns
549 Arguments are expanded using shell-like glob match. Patterns
549 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
550 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
550 tilde '~' will be expanded into user's home directory. Unlike
551 tilde '~' will be expanded into user's home directory. Unlike
551 real shells, quotation does not suppress expansions. Use
552 real shells, quotation does not suppress expansions. Use
552 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
553 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
553 To completely disable these expansions, you can use -G flag.
554 To completely disable these expansions, you can use -G flag.
554
555
555 On Windows systems, the use of single quotes `'` when specifying
556 On Windows systems, the use of single quotes `'` when specifying
556 a file is not supported. Use double quotes `"`.
557 a file is not supported. Use double quotes `"`.
557
558
558 Options:
559 Options:
559
560
560 -n
561 -n
561 __name__ is NOT set to '__main__', but to the running file's name
562 __name__ is NOT set to '__main__', but to the running file's name
562 without extension (as python does under import). This allows running
563 without extension (as python does under import). This allows running
563 scripts and reloading the definitions in them without calling code
564 scripts and reloading the definitions in them without calling code
564 protected by an ``if __name__ == "__main__"`` clause.
565 protected by an ``if __name__ == "__main__"`` clause.
565
566
566 -i
567 -i
567 run the file in IPython's namespace instead of an empty one. This
568 run the file in IPython's namespace instead of an empty one. This
568 is useful if you are experimenting with code written in a text editor
569 is useful if you are experimenting with code written in a text editor
569 which depends on variables defined interactively.
570 which depends on variables defined interactively.
570
571
571 -e
572 -e
572 ignore sys.exit() calls or SystemExit exceptions in the script
573 ignore sys.exit() calls or SystemExit exceptions in the script
573 being run. This is particularly useful if IPython is being used to
574 being run. This is particularly useful if IPython is being used to
574 run unittests, which always exit with a sys.exit() call. In such
575 run unittests, which always exit with a sys.exit() call. In such
575 cases you are interested in the output of the test results, not in
576 cases you are interested in the output of the test results, not in
576 seeing a traceback of the unittest module.
577 seeing a traceback of the unittest module.
577
578
578 -t
579 -t
579 print timing information at the end of the run. IPython will give
580 print timing information at the end of the run. IPython will give
580 you an estimated CPU time consumption for your script, which under
581 you an estimated CPU time consumption for your script, which under
581 Unix uses the resource module to avoid the wraparound problems of
582 Unix uses the resource module to avoid the wraparound problems of
582 time.clock(). Under Unix, an estimate of time spent on system tasks
583 time.clock(). Under Unix, an estimate of time spent on system tasks
583 is also given (for Windows platforms this is reported as 0.0).
584 is also given (for Windows platforms this is reported as 0.0).
584
585
585 If -t is given, an additional ``-N<N>`` option can be given, where <N>
586 If -t is given, an additional ``-N<N>`` option can be given, where <N>
586 must be an integer indicating how many times you want the script to
587 must be an integer indicating how many times you want the script to
587 run. The final timing report will include total and per run results.
588 run. The final timing report will include total and per run results.
588
589
589 For example (testing the script uniq_stable.py)::
590 For example (testing the script uniq_stable.py)::
590
591
591 In [1]: run -t uniq_stable
592 In [1]: run -t uniq_stable
592
593
593 IPython CPU timings (estimated):
594 IPython CPU timings (estimated):
594 User : 0.19597 s.
595 User : 0.19597 s.
595 System: 0.0 s.
596 System: 0.0 s.
596
597
597 In [2]: run -t -N5 uniq_stable
598 In [2]: run -t -N5 uniq_stable
598
599
599 IPython CPU timings (estimated):
600 IPython CPU timings (estimated):
600 Total runs performed: 5
601 Total runs performed: 5
601 Times : Total Per run
602 Times : Total Per run
602 User : 0.910862 s, 0.1821724 s.
603 User : 0.910862 s, 0.1821724 s.
603 System: 0.0 s, 0.0 s.
604 System: 0.0 s, 0.0 s.
604
605
605 -d
606 -d
606 run your program under the control of pdb, the Python debugger.
607 run your program under the control of pdb, the Python debugger.
607 This allows you to execute your program step by step, watch variables,
608 This allows you to execute your program step by step, watch variables,
608 etc. Internally, what IPython does is similar to calling::
609 etc. Internally, what IPython does is similar to calling::
609
610
610 pdb.run('execfile("YOURFILENAME")')
611 pdb.run('execfile("YOURFILENAME")')
611
612
612 with a breakpoint set on line 1 of your file. You can change the line
613 with a breakpoint set on line 1 of your file. You can change the line
613 number for this automatic breakpoint to be <N> by using the -bN option
614 number for this automatic breakpoint to be <N> by using the -bN option
614 (where N must be an integer). For example::
615 (where N must be an integer). For example::
615
616
616 %run -d -b40 myscript
617 %run -d -b40 myscript
617
618
618 will set the first breakpoint at line 40 in myscript.py. Note that
619 will set the first breakpoint at line 40 in myscript.py. Note that
619 the first breakpoint must be set on a line which actually does
620 the first breakpoint must be set on a line which actually does
620 something (not a comment or docstring) for it to stop execution.
621 something (not a comment or docstring) for it to stop execution.
621
622
622 Or you can specify a breakpoint in a different file::
623 Or you can specify a breakpoint in a different file::
623
624
624 %run -d -b myotherfile.py:20 myscript
625 %run -d -b myotherfile.py:20 myscript
625
626
626 When the pdb debugger starts, you will see a (Pdb) prompt. You must
627 When the pdb debugger starts, you will see a (Pdb) prompt. You must
627 first enter 'c' (without quotes) to start execution up to the first
628 first enter 'c' (without quotes) to start execution up to the first
628 breakpoint.
629 breakpoint.
629
630
630 Entering 'help' gives information about the use of the debugger. You
631 Entering 'help' gives information about the use of the debugger. You
631 can easily see pdb's full documentation with "import pdb;pdb.help()"
632 can easily see pdb's full documentation with "import pdb;pdb.help()"
632 at a prompt.
633 at a prompt.
633
634
634 -p
635 -p
635 run program under the control of the Python profiler module (which
636 run program under the control of the Python profiler module (which
636 prints a detailed report of execution times, function calls, etc).
637 prints a detailed report of execution times, function calls, etc).
637
638
638 You can pass other options after -p which affect the behavior of the
639 You can pass other options after -p which affect the behavior of the
639 profiler itself. See the docs for %prun for details.
640 profiler itself. See the docs for %prun for details.
640
641
641 In this mode, the program's variables do NOT propagate back to the
642 In this mode, the program's variables do NOT propagate back to the
642 IPython interactive namespace (because they remain in the namespace
643 IPython interactive namespace (because they remain in the namespace
643 where the profiler executes them).
644 where the profiler executes them).
644
645
645 Internally this triggers a call to %prun, see its documentation for
646 Internally this triggers a call to %prun, see its documentation for
646 details on the options available specifically for profiling.
647 details on the options available specifically for profiling.
647
648
648 There is one special usage for which the text above doesn't apply:
649 There is one special usage for which the text above doesn't apply:
649 if the filename ends with .ipy[nb], the file is run as ipython script,
650 if the filename ends with .ipy[nb], the file is run as ipython script,
650 just as if the commands were written on IPython prompt.
651 just as if the commands were written on IPython prompt.
651
652
652 -m
653 -m
653 specify module name to load instead of script path. Similar to
654 specify module name to load instead of script path. Similar to
654 the -m option for the python interpreter. Use this option last if you
655 the -m option for the python interpreter. Use this option last if you
655 want to combine with other %run options. Unlike the python interpreter
656 want to combine with other %run options. Unlike the python interpreter
656 only source modules are allowed no .pyc or .pyo files.
657 only source modules are allowed no .pyc or .pyo files.
657 For example::
658 For example::
658
659
659 %run -m example
660 %run -m example
660
661
661 will run the example module.
662 will run the example module.
662
663
663 -G
664 -G
664 disable shell-like glob expansion of arguments.
665 disable shell-like glob expansion of arguments.
665
666
666 """
667 """
667
668
668 # Logic to handle issue #3664
669 # Logic to handle issue #3664
669 # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
670 # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
670 if '-m' in parameter_s and '--' not in parameter_s:
671 if '-m' in parameter_s and '--' not in parameter_s:
671 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
672 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
672 for idx, arg in enumerate(argv):
673 for idx, arg in enumerate(argv):
673 if arg and arg.startswith('-') and arg != '-':
674 if arg and arg.startswith('-') and arg != '-':
674 if arg == '-m':
675 if arg == '-m':
675 argv.insert(idx + 2, '--')
676 argv.insert(idx + 2, '--')
676 break
677 break
677 else:
678 else:
678 # Positional arg, break
679 # Positional arg, break
679 break
680 break
680 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
681 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
681
682
682 # get arguments and set sys.argv for program to be run.
683 # get arguments and set sys.argv for program to be run.
683 opts, arg_lst = self.parse_options(parameter_s,
684 opts, arg_lst = self.parse_options(parameter_s,
684 'nidtN:b:pD:l:rs:T:em:G',
685 'nidtN:b:pD:l:rs:T:em:G',
685 mode='list', list_all=1)
686 mode='list', list_all=1)
686 if "m" in opts:
687 if "m" in opts:
687 modulename = opts["m"][0]
688 modulename = opts["m"][0]
688 modpath = find_mod(modulename)
689 modpath = find_mod(modulename)
689 if modpath is None:
690 if modpath is None:
690 msg = '%r is not a valid modulename on sys.path'%modulename
691 msg = '%r is not a valid modulename on sys.path'%modulename
691 raise Exception(msg)
692 raise Exception(msg)
692 arg_lst = [modpath] + arg_lst
693 arg_lst = [modpath] + arg_lst
693 try:
694 try:
694 fpath = None # initialize to make sure fpath is in scope later
695 fpath = None # initialize to make sure fpath is in scope later
695 fpath = arg_lst[0]
696 fpath = arg_lst[0]
696 filename = file_finder(fpath)
697 filename = file_finder(fpath)
697 except IndexError as e:
698 except IndexError as e:
698 msg = 'you must provide at least a filename.'
699 msg = 'you must provide at least a filename.'
699 raise Exception(msg) from e
700 raise Exception(msg) from e
700 except IOError as e:
701 except IOError as e:
701 try:
702 try:
702 msg = str(e)
703 msg = str(e)
703 except UnicodeError:
704 except UnicodeError:
704 msg = e.message
705 msg = e.message
705 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
706 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
706 warn('For Windows, use double quotes to wrap a filename: %run "mypath\\myfile.py"')
707 warn('For Windows, use double quotes to wrap a filename: %run "mypath\\myfile.py"')
707 raise Exception(msg) from e
708 raise Exception(msg) from e
708 except TypeError:
709 except TypeError:
709 if fpath in sys.meta_path:
710 if fpath in sys.meta_path:
710 filename = ""
711 filename = ""
711 else:
712 else:
712 raise
713 raise
713
714
714 if filename.lower().endswith(('.ipy', '.ipynb')):
715 if filename.lower().endswith(('.ipy', '.ipynb')):
715 with preserve_keys(self.shell.user_ns, '__file__'):
716 with preserve_keys(self.shell.user_ns, '__file__'):
716 self.shell.user_ns['__file__'] = filename
717 self.shell.user_ns['__file__'] = filename
717 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
718 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
718 return
719 return
719
720
720 # Control the response to exit() calls made by the script being run
721 # Control the response to exit() calls made by the script being run
721 exit_ignore = 'e' in opts
722 exit_ignore = 'e' in opts
722
723
723 # Make sure that the running script gets a proper sys.argv as if it
724 # Make sure that the running script gets a proper sys.argv as if it
724 # were run from a system shell.
725 # were run from a system shell.
725 save_argv = sys.argv # save it for later restoring
726 save_argv = sys.argv # save it for later restoring
726
727
727 if 'G' in opts:
728 if 'G' in opts:
728 args = arg_lst[1:]
729 args = arg_lst[1:]
729 else:
730 else:
730 # tilde and glob expansion
731 # tilde and glob expansion
731 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
732 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
732
733
733 sys.argv = [filename] + args # put in the proper filename
734 sys.argv = [filename] + args # put in the proper filename
734
735
735 if 'n' in opts:
736 if 'n' in opts:
736 name = Path(filename).stem
737 name = Path(filename).stem
737 else:
738 else:
738 name = '__main__'
739 name = '__main__'
739
740
740 if 'i' in opts:
741 if 'i' in opts:
741 # Run in user's interactive namespace
742 # Run in user's interactive namespace
742 prog_ns = self.shell.user_ns
743 prog_ns = self.shell.user_ns
743 __name__save = self.shell.user_ns['__name__']
744 __name__save = self.shell.user_ns['__name__']
744 prog_ns['__name__'] = name
745 prog_ns['__name__'] = name
745 main_mod = self.shell.user_module
746 main_mod = self.shell.user_module
746
747
747 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
748 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
748 # set the __file__ global in the script's namespace
749 # set the __file__ global in the script's namespace
749 # TK: Is this necessary in interactive mode?
750 # TK: Is this necessary in interactive mode?
750 prog_ns['__file__'] = filename
751 prog_ns['__file__'] = filename
751 else:
752 else:
752 # Run in a fresh, empty namespace
753 # Run in a fresh, empty namespace
753
754
754 # The shell MUST hold a reference to prog_ns so after %run
755 # The shell MUST hold a reference to prog_ns so after %run
755 # exits, the python deletion mechanism doesn't zero it out
756 # exits, the python deletion mechanism doesn't zero it out
756 # (leaving dangling references). See interactiveshell for details
757 # (leaving dangling references). See interactiveshell for details
757 main_mod = self.shell.new_main_mod(filename, name)
758 main_mod = self.shell.new_main_mod(filename, name)
758 prog_ns = main_mod.__dict__
759 prog_ns = main_mod.__dict__
759
760
760 # pickle fix. See interactiveshell for an explanation. But we need to
761 # pickle fix. See interactiveshell for an explanation. But we need to
761 # make sure that, if we overwrite __main__, we replace it at the end
762 # make sure that, if we overwrite __main__, we replace it at the end
762 main_mod_name = prog_ns['__name__']
763 main_mod_name = prog_ns['__name__']
763
764
764 if main_mod_name == '__main__':
765 if main_mod_name == '__main__':
765 restore_main = sys.modules['__main__']
766 restore_main = sys.modules['__main__']
766 else:
767 else:
767 restore_main = False
768 restore_main = False
768
769
769 # This needs to be undone at the end to prevent holding references to
770 # This needs to be undone at the end to prevent holding references to
770 # every single object ever created.
771 # every single object ever created.
771 sys.modules[main_mod_name] = main_mod
772 sys.modules[main_mod_name] = main_mod
772
773
773 if 'p' in opts or 'd' in opts:
774 if 'p' in opts or 'd' in opts:
774 if 'm' in opts:
775 if 'm' in opts:
775 code = 'run_module(modulename, prog_ns)'
776 code = 'run_module(modulename, prog_ns)'
776 code_ns = {
777 code_ns = {
777 'run_module': self.shell.safe_run_module,
778 'run_module': self.shell.safe_run_module,
778 'prog_ns': prog_ns,
779 'prog_ns': prog_ns,
779 'modulename': modulename,
780 'modulename': modulename,
780 }
781 }
781 else:
782 else:
782 if 'd' in opts:
783 if 'd' in opts:
783 # allow exceptions to raise in debug mode
784 # allow exceptions to raise in debug mode
784 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
785 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
785 else:
786 else:
786 code = 'execfile(filename, prog_ns)'
787 code = 'execfile(filename, prog_ns)'
787 code_ns = {
788 code_ns = {
788 'execfile': self.shell.safe_execfile,
789 'execfile': self.shell.safe_execfile,
789 'prog_ns': prog_ns,
790 'prog_ns': prog_ns,
790 'filename': get_py_filename(filename),
791 'filename': get_py_filename(filename),
791 }
792 }
792
793
793 try:
794 try:
794 stats = None
795 stats = None
795 if 'p' in opts:
796 if 'p' in opts:
796 stats = self._run_with_profiler(code, opts, code_ns)
797 stats = self._run_with_profiler(code, opts, code_ns)
797 else:
798 else:
798 if 'd' in opts:
799 if 'd' in opts:
799 bp_file, bp_line = parse_breakpoint(
800 bp_file, bp_line = parse_breakpoint(
800 opts.get('b', ['1'])[0], filename)
801 opts.get('b', ['1'])[0], filename)
801 self._run_with_debugger(
802 self._run_with_debugger(
802 code, code_ns, filename, bp_line, bp_file)
803 code, code_ns, filename, bp_line, bp_file)
803 else:
804 else:
804 if 'm' in opts:
805 if 'm' in opts:
805 def run():
806 def run():
806 self.shell.safe_run_module(modulename, prog_ns)
807 self.shell.safe_run_module(modulename, prog_ns)
807 else:
808 else:
808 if runner is None:
809 if runner is None:
809 runner = self.default_runner
810 runner = self.default_runner
810 if runner is None:
811 if runner is None:
811 runner = self.shell.safe_execfile
812 runner = self.shell.safe_execfile
812
813
813 def run():
814 def run():
814 runner(filename, prog_ns, prog_ns,
815 runner(filename, prog_ns, prog_ns,
815 exit_ignore=exit_ignore)
816 exit_ignore=exit_ignore)
816
817
817 if 't' in opts:
818 if 't' in opts:
818 # timed execution
819 # timed execution
819 try:
820 try:
820 nruns = int(opts['N'][0])
821 nruns = int(opts['N'][0])
821 if nruns < 1:
822 if nruns < 1:
822 error('Number of runs must be >=1')
823 error('Number of runs must be >=1')
823 return
824 return
824 except (KeyError):
825 except (KeyError):
825 nruns = 1
826 nruns = 1
826 self._run_with_timing(run, nruns)
827 self._run_with_timing(run, nruns)
827 else:
828 else:
828 # regular execution
829 # regular execution
829 run()
830 run()
830
831
831 if 'i' in opts:
832 if 'i' in opts:
832 self.shell.user_ns['__name__'] = __name__save
833 self.shell.user_ns['__name__'] = __name__save
833 else:
834 else:
834 # update IPython interactive namespace
835 # update IPython interactive namespace
835
836
836 # Some forms of read errors on the file may mean the
837 # Some forms of read errors on the file may mean the
837 # __name__ key was never set; using pop we don't have to
838 # __name__ key was never set; using pop we don't have to
838 # worry about a possible KeyError.
839 # worry about a possible KeyError.
839 prog_ns.pop('__name__', None)
840 prog_ns.pop('__name__', None)
840
841
841 with preserve_keys(self.shell.user_ns, '__file__'):
842 with preserve_keys(self.shell.user_ns, '__file__'):
842 self.shell.user_ns.update(prog_ns)
843 self.shell.user_ns.update(prog_ns)
843 finally:
844 finally:
844 # It's a bit of a mystery why, but __builtins__ can change from
845 # It's a bit of a mystery why, but __builtins__ can change from
845 # being a module to becoming a dict missing some key data after
846 # being a module to becoming a dict missing some key data after
846 # %run. As best I can see, this is NOT something IPython is doing
847 # %run. As best I can see, this is NOT something IPython is doing
847 # at all, and similar problems have been reported before:
848 # at all, and similar problems have been reported before:
848 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
849 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
849 # Since this seems to be done by the interpreter itself, the best
850 # Since this seems to be done by the interpreter itself, the best
850 # we can do is to at least restore __builtins__ for the user on
851 # we can do is to at least restore __builtins__ for the user on
851 # exit.
852 # exit.
852 self.shell.user_ns['__builtins__'] = builtin_mod
853 self.shell.user_ns['__builtins__'] = builtin_mod
853
854
854 # Ensure key global structures are restored
855 # Ensure key global structures are restored
855 sys.argv = save_argv
856 sys.argv = save_argv
856 if restore_main:
857 if restore_main:
857 sys.modules['__main__'] = restore_main
858 sys.modules['__main__'] = restore_main
858 if '__mp_main__' in sys.modules:
859 if '__mp_main__' in sys.modules:
859 sys.modules['__mp_main__'] = restore_main
860 sys.modules['__mp_main__'] = restore_main
860 else:
861 else:
861 # Remove from sys.modules the reference to main_mod we'd
862 # Remove from sys.modules the reference to main_mod we'd
862 # added. Otherwise it will trap references to objects
863 # added. Otherwise it will trap references to objects
863 # contained therein.
864 # contained therein.
864 del sys.modules[main_mod_name]
865 del sys.modules[main_mod_name]
865
866
866 return stats
867 return stats
867
868
868 def _run_with_debugger(self, code, code_ns, filename=None,
869 def _run_with_debugger(self, code, code_ns, filename=None,
869 bp_line=None, bp_file=None):
870 bp_line=None, bp_file=None):
870 """
871 """
871 Run `code` in debugger with a break point.
872 Run `code` in debugger with a break point.
872
873
873 Parameters
874 Parameters
874 ----------
875 ----------
875 code : str
876 code : str
876 Code to execute.
877 Code to execute.
877 code_ns : dict
878 code_ns : dict
878 A namespace in which `code` is executed.
879 A namespace in which `code` is executed.
879 filename : str
880 filename : str
880 `code` is ran as if it is in `filename`.
881 `code` is ran as if it is in `filename`.
881 bp_line : int, optional
882 bp_line : int, optional
882 Line number of the break point.
883 Line number of the break point.
883 bp_file : str, optional
884 bp_file : str, optional
884 Path to the file in which break point is specified.
885 Path to the file in which break point is specified.
885 `filename` is used if not given.
886 `filename` is used if not given.
886
887
887 Raises
888 Raises
888 ------
889 ------
889 UsageError
890 UsageError
890 If the break point given by `bp_line` is not valid.
891 If the break point given by `bp_line` is not valid.
891
892
892 """
893 """
893 deb = self.shell.InteractiveTB.pdb
894 deb = self.shell.InteractiveTB.pdb
894 if not deb:
895 if not deb:
895 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
896 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
896 deb = self.shell.InteractiveTB.pdb
897 deb = self.shell.InteractiveTB.pdb
897
898
898 # deb.checkline() fails if deb.curframe exists but is None; it can
899 # deb.checkline() fails if deb.curframe exists but is None; it can
899 # handle it not existing. https://github.com/ipython/ipython/issues/10028
900 # handle it not existing. https://github.com/ipython/ipython/issues/10028
900 if hasattr(deb, 'curframe'):
901 if hasattr(deb, 'curframe'):
901 del deb.curframe
902 del deb.curframe
902
903
903 # reset Breakpoint state, which is moronically kept
904 # reset Breakpoint state, which is moronically kept
904 # in a class
905 # in a class
905 bdb.Breakpoint.next = 1
906 bdb.Breakpoint.next = 1
906 bdb.Breakpoint.bplist = {}
907 bdb.Breakpoint.bplist = {}
907 bdb.Breakpoint.bpbynumber = [None]
908 bdb.Breakpoint.bpbynumber = [None]
908 deb.clear_all_breaks()
909 deb.clear_all_breaks()
909 if bp_line is not None:
910 if bp_line is not None:
910 # Set an initial breakpoint to stop execution
911 # Set an initial breakpoint to stop execution
911 maxtries = 10
912 maxtries = 10
912 bp_file = bp_file or filename
913 bp_file = bp_file or filename
913 checkline = deb.checkline(bp_file, bp_line)
914 checkline = deb.checkline(bp_file, bp_line)
914 if not checkline:
915 if not checkline:
915 for bp in range(bp_line + 1, bp_line + maxtries + 1):
916 for bp in range(bp_line + 1, bp_line + maxtries + 1):
916 if deb.checkline(bp_file, bp):
917 if deb.checkline(bp_file, bp):
917 break
918 break
918 else:
919 else:
919 msg = ("\nI failed to find a valid line to set "
920 msg = ("\nI failed to find a valid line to set "
920 "a breakpoint\n"
921 "a breakpoint\n"
921 "after trying up to line: %s.\n"
922 "after trying up to line: %s.\n"
922 "Please set a valid breakpoint manually "
923 "Please set a valid breakpoint manually "
923 "with the -b option." % bp)
924 "with the -b option." % bp)
924 raise UsageError(msg)
925 raise UsageError(msg)
925 # if we find a good linenumber, set the breakpoint
926 # if we find a good linenumber, set the breakpoint
926 deb.do_break('%s:%s' % (bp_file, bp_line))
927 deb.do_break('%s:%s' % (bp_file, bp_line))
927
928
928 if filename:
929 if filename:
929 # Mimic Pdb._runscript(...)
930 # Mimic Pdb._runscript(...)
930 deb._wait_for_mainpyfile = True
931 deb._wait_for_mainpyfile = True
931 deb.mainpyfile = deb.canonic(filename)
932 deb.mainpyfile = deb.canonic(filename)
932
933
933 # Start file run
934 # Start file run
934 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
935 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
935 try:
936 try:
936 if filename:
937 if filename:
937 # save filename so it can be used by methods on the deb object
938 # save filename so it can be used by methods on the deb object
938 deb._exec_filename = filename
939 deb._exec_filename = filename
939 while True:
940 while True:
940 try:
941 try:
941 trace = sys.gettrace()
942 trace = sys.gettrace()
942 deb.run(code, code_ns)
943 deb.run(code, code_ns)
943 except Restart:
944 except Restart:
944 print("Restarting")
945 print("Restarting")
945 if filename:
946 if filename:
946 deb._wait_for_mainpyfile = True
947 deb._wait_for_mainpyfile = True
947 deb.mainpyfile = deb.canonic(filename)
948 deb.mainpyfile = deb.canonic(filename)
948 continue
949 continue
949 else:
950 else:
950 break
951 break
951 finally:
952 finally:
952 sys.settrace(trace)
953 sys.settrace(trace)
953
954
954
955
955 except:
956 except:
956 etype, value, tb = sys.exc_info()
957 etype, value, tb = sys.exc_info()
957 # Skip three frames in the traceback: the %run one,
958 # Skip three frames in the traceback: the %run one,
958 # one inside bdb.py, and the command-line typed by the
959 # one inside bdb.py, and the command-line typed by the
959 # user (run by exec in pdb itself).
960 # user (run by exec in pdb itself).
960 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
961 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
961
962
962 @staticmethod
963 @staticmethod
963 def _run_with_timing(run, nruns):
964 def _run_with_timing(run, nruns):
964 """
965 """
965 Run function `run` and print timing information.
966 Run function `run` and print timing information.
966
967
967 Parameters
968 Parameters
968 ----------
969 ----------
969 run : callable
970 run : callable
970 Any callable object which takes no argument.
971 Any callable object which takes no argument.
971 nruns : int
972 nruns : int
972 Number of times to execute `run`.
973 Number of times to execute `run`.
973
974
974 """
975 """
975 twall0 = time.perf_counter()
976 twall0 = time.perf_counter()
976 if nruns == 1:
977 if nruns == 1:
977 t0 = clock2()
978 t0 = clock2()
978 run()
979 run()
979 t1 = clock2()
980 t1 = clock2()
980 t_usr = t1[0] - t0[0]
981 t_usr = t1[0] - t0[0]
981 t_sys = t1[1] - t0[1]
982 t_sys = t1[1] - t0[1]
982 print("\nIPython CPU timings (estimated):")
983 print("\nIPython CPU timings (estimated):")
983 print(" User : %10.2f s." % t_usr)
984 print(" User : %10.2f s." % t_usr)
984 print(" System : %10.2f s." % t_sys)
985 print(" System : %10.2f s." % t_sys)
985 else:
986 else:
986 runs = range(nruns)
987 runs = range(nruns)
987 t0 = clock2()
988 t0 = clock2()
988 for nr in runs:
989 for nr in runs:
989 run()
990 run()
990 t1 = clock2()
991 t1 = clock2()
991 t_usr = t1[0] - t0[0]
992 t_usr = t1[0] - t0[0]
992 t_sys = t1[1] - t0[1]
993 t_sys = t1[1] - t0[1]
993 print("\nIPython CPU timings (estimated):")
994 print("\nIPython CPU timings (estimated):")
994 print("Total runs performed:", nruns)
995 print("Total runs performed:", nruns)
995 print(" Times : %10s %10s" % ('Total', 'Per run'))
996 print(" Times : %10s %10s" % ('Total', 'Per run'))
996 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
997 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
997 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
998 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
998 twall1 = time.perf_counter()
999 twall1 = time.perf_counter()
999 print("Wall time: %10.2f s." % (twall1 - twall0))
1000 print("Wall time: %10.2f s." % (twall1 - twall0))
1000
1001
1001 @skip_doctest
1002 @skip_doctest
1002 @no_var_expand
1003 @no_var_expand
1003 @line_cell_magic
1004 @line_cell_magic
1004 @needs_local_scope
1005 @needs_local_scope
1005 def timeit(self, line='', cell=None, local_ns=None):
1006 def timeit(self, line='', cell=None, local_ns=None):
1006 """Time execution of a Python statement or expression
1007 """Time execution of a Python statement or expression
1007
1008
1008 Usage, in line mode:
1009 Usage, in line mode:
1009 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
1010 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
1010 or in cell mode:
1011 or in cell mode:
1011 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
1012 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
1012 code
1013 code
1013 code...
1014 code...
1014
1015
1015 Time execution of a Python statement or expression using the timeit
1016 Time execution of a Python statement or expression using the timeit
1016 module. This function can be used both as a line and cell magic:
1017 module. This function can be used both as a line and cell magic:
1017
1018
1018 - In line mode you can time a single-line statement (though multiple
1019 - In line mode you can time a single-line statement (though multiple
1019 ones can be chained with using semicolons).
1020 ones can be chained with using semicolons).
1020
1021
1021 - In cell mode, the statement in the first line is used as setup code
1022 - In cell mode, the statement in the first line is used as setup code
1022 (executed but not timed) and the body of the cell is timed. The cell
1023 (executed but not timed) and the body of the cell is timed. The cell
1023 body has access to any variables created in the setup code.
1024 body has access to any variables created in the setup code.
1024
1025
1025 Options:
1026 Options:
1026 -n<N>: execute the given statement <N> times in a loop. If <N> is not
1027 -n<N>: execute the given statement <N> times in a loop. If <N> is not
1027 provided, <N> is determined so as to get sufficient accuracy.
1028 provided, <N> is determined so as to get sufficient accuracy.
1028
1029
1029 -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
1030 -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
1030 best result.
1031 best result.
1031 Default: 7
1032 Default: 7
1032
1033
1033 -t: use time.time to measure the time, which is the default on Unix.
1034 -t: use time.time to measure the time, which is the default on Unix.
1034 This function measures wall time.
1035 This function measures wall time.
1035
1036
1036 -c: use time.clock to measure the time, which is the default on
1037 -c: use time.clock to measure the time, which is the default on
1037 Windows and measures wall time. On Unix, resource.getrusage is used
1038 Windows and measures wall time. On Unix, resource.getrusage is used
1038 instead and returns the CPU user time.
1039 instead and returns the CPU user time.
1039
1040
1040 -p<P>: use a precision of <P> digits to display the timing result.
1041 -p<P>: use a precision of <P> digits to display the timing result.
1041 Default: 3
1042 Default: 3
1042
1043
1043 -q: Quiet, do not print result.
1044 -q: Quiet, do not print result.
1044
1045
1045 -o: return a TimeitResult that can be stored in a variable to inspect
1046 -o: return a TimeitResult that can be stored in a variable to inspect
1046 the result in more details.
1047 the result in more details.
1047
1048
1048 .. versionchanged:: 7.3
1049 .. versionchanged:: 7.3
1049 User variables are no longer expanded,
1050 User variables are no longer expanded,
1050 the magic line is always left unmodified.
1051 the magic line is always left unmodified.
1051
1052
1052 Examples
1053 Examples
1053 --------
1054 --------
1054 ::
1055 ::
1055
1056
1056 In [1]: %timeit pass
1057 In [1]: %timeit pass
1057 8.26 ns Β± 0.12 ns per loop (mean Β± std. dev. of 7 runs, 100000000 loops each)
1058 8.26 ns Β± 0.12 ns per loop (mean Β± std. dev. of 7 runs, 100000000 loops each)
1058
1059
1059 In [2]: u = None
1060 In [2]: u = None
1060
1061
1061 In [3]: %timeit u is None
1062 In [3]: %timeit u is None
1062 29.9 ns Β± 0.643 ns per loop (mean Β± std. dev. of 7 runs, 10000000 loops each)
1063 29.9 ns Β± 0.643 ns per loop (mean Β± std. dev. of 7 runs, 10000000 loops each)
1063
1064
1064 In [4]: %timeit -r 4 u == None
1065 In [4]: %timeit -r 4 u == None
1065
1066
1066 In [5]: import time
1067 In [5]: import time
1067
1068
1068 In [6]: %timeit -n1 time.sleep(2)
1069 In [6]: %timeit -n1 time.sleep(2)
1069
1070
1070 The times reported by %timeit will be slightly higher than those
1071 The times reported by %timeit will be slightly higher than those
1071 reported by the timeit.py script when variables are accessed. This is
1072 reported by the timeit.py script when variables are accessed. This is
1072 due to the fact that %timeit executes the statement in the namespace
1073 due to the fact that %timeit executes the statement in the namespace
1073 of the shell, compared with timeit.py, which uses a single setup
1074 of the shell, compared with timeit.py, which uses a single setup
1074 statement to import function or create variables. Generally, the bias
1075 statement to import function or create variables. Generally, the bias
1075 does not matter as long as results from timeit.py are not mixed with
1076 does not matter as long as results from timeit.py are not mixed with
1076 those from %timeit."""
1077 those from %timeit."""
1077
1078
1078 opts, stmt = self.parse_options(
1079 opts, stmt = self.parse_options(
1079 line, "n:r:tcp:qo", posix=False, strict=False, preserve_non_opts=True
1080 line, "n:r:tcp:qo", posix=False, strict=False, preserve_non_opts=True
1080 )
1081 )
1081 if stmt == "" and cell is None:
1082 if stmt == "" and cell is None:
1082 return
1083 return
1083
1084
1084 timefunc = timeit.default_timer
1085 timefunc = timeit.default_timer
1085 number = int(getattr(opts, "n", 0))
1086 number = int(getattr(opts, "n", 0))
1086 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1087 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1087 repeat = int(getattr(opts, "r", default_repeat))
1088 repeat = int(getattr(opts, "r", default_repeat))
1088 precision = int(getattr(opts, "p", 3))
1089 precision = int(getattr(opts, "p", 3))
1089 quiet = 'q' in opts
1090 quiet = 'q' in opts
1090 return_result = 'o' in opts
1091 return_result = 'o' in opts
1091 if hasattr(opts, "t"):
1092 if hasattr(opts, "t"):
1092 timefunc = time.time
1093 timefunc = time.time
1093 if hasattr(opts, "c"):
1094 if hasattr(opts, "c"):
1094 timefunc = clock
1095 timefunc = clock
1095
1096
1096 timer = Timer(timer=timefunc)
1097 timer = Timer(timer=timefunc)
1097 # this code has tight coupling to the inner workings of timeit.Timer,
1098 # this code has tight coupling to the inner workings of timeit.Timer,
1098 # but is there a better way to achieve that the code stmt has access
1099 # but is there a better way to achieve that the code stmt has access
1099 # to the shell namespace?
1100 # to the shell namespace?
1100 transform = self.shell.transform_cell
1101 transform = self.shell.transform_cell
1101
1102
1102 if cell is None:
1103 if cell is None:
1103 # called as line magic
1104 # called as line magic
1104 ast_setup = self.shell.compile.ast_parse("pass")
1105 ast_setup = self.shell.compile.ast_parse("pass")
1105 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1106 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1106 else:
1107 else:
1107 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1108 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1108 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1109 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1109
1110
1110 ast_setup = self.shell.transform_ast(ast_setup)
1111 ast_setup = self.shell.transform_ast(ast_setup)
1111 ast_stmt = self.shell.transform_ast(ast_stmt)
1112 ast_stmt = self.shell.transform_ast(ast_stmt)
1112
1113
1113 # Check that these compile to valid Python code *outside* the timer func
1114 # Check that these compile to valid Python code *outside* the timer func
1114 # Invalid code may become valid when put inside the function & loop,
1115 # Invalid code may become valid when put inside the function & loop,
1115 # which messes up error messages.
1116 # which messes up error messages.
1116 # https://github.com/ipython/ipython/issues/10636
1117 # https://github.com/ipython/ipython/issues/10636
1117 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1118 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1118 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1119 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1119
1120
1120 # This codestring is taken from timeit.template - we fill it in as an
1121 # This codestring is taken from timeit.template - we fill it in as an
1121 # AST, so that we can apply our AST transformations to the user code
1122 # AST, so that we can apply our AST transformations to the user code
1122 # without affecting the timing code.
1123 # without affecting the timing code.
1123 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1124 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1124 ' setup\n'
1125 ' setup\n'
1125 ' _t0 = _timer()\n'
1126 ' _t0 = _timer()\n'
1126 ' for _i in _it:\n'
1127 ' for _i in _it:\n'
1127 ' stmt\n'
1128 ' stmt\n'
1128 ' _t1 = _timer()\n'
1129 ' _t1 = _timer()\n'
1129 ' return _t1 - _t0\n')
1130 ' return _t1 - _t0\n')
1130
1131
1131 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1132 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1132 timeit_ast = ast.fix_missing_locations(timeit_ast)
1133 timeit_ast = ast.fix_missing_locations(timeit_ast)
1133
1134
1134 # Track compilation time so it can be reported if too long
1135 # Track compilation time so it can be reported if too long
1135 # Minimum time above which compilation time will be reported
1136 # Minimum time above which compilation time will be reported
1136 tc_min = 0.1
1137 tc_min = 0.1
1137
1138
1138 t0 = clock()
1139 t0 = clock()
1139 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1140 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1140 tc = clock()-t0
1141 tc = clock()-t0
1141
1142
1142 ns = {}
1143 ns = {}
1143 glob = self.shell.user_ns
1144 glob = self.shell.user_ns
1144 # handles global vars with same name as local vars. We store them in conflict_globs.
1145 # handles global vars with same name as local vars. We store them in conflict_globs.
1145 conflict_globs = {}
1146 conflict_globs = {}
1146 if local_ns and cell is None:
1147 if local_ns and cell is None:
1147 for var_name, var_val in glob.items():
1148 for var_name, var_val in glob.items():
1148 if var_name in local_ns:
1149 if var_name in local_ns:
1149 conflict_globs[var_name] = var_val
1150 conflict_globs[var_name] = var_val
1150 glob.update(local_ns)
1151 glob.update(local_ns)
1151
1152
1152 exec(code, glob, ns)
1153 exec(code, glob, ns)
1153 timer.inner = ns["inner"]
1154 timer.inner = ns["inner"]
1154
1155
1155 # This is used to check if there is a huge difference between the
1156 # This is used to check if there is a huge difference between the
1156 # best and worst timings.
1157 # best and worst timings.
1157 # Issue: https://github.com/ipython/ipython/issues/6471
1158 # Issue: https://github.com/ipython/ipython/issues/6471
1158 if number == 0:
1159 if number == 0:
1159 # determine number so that 0.2 <= total time < 2.0
1160 # determine number so that 0.2 <= total time < 2.0
1160 for index in range(0, 10):
1161 for index in range(0, 10):
1161 number = 10 ** index
1162 number = 10 ** index
1162 time_number = timer.timeit(number)
1163 time_number = timer.timeit(number)
1163 if time_number >= 0.2:
1164 if time_number >= 0.2:
1164 break
1165 break
1165
1166
1166 all_runs = timer.repeat(repeat, number)
1167 all_runs = timer.repeat(repeat, number)
1167 best = min(all_runs) / number
1168 best = min(all_runs) / number
1168 worst = max(all_runs) / number
1169 worst = max(all_runs) / number
1169 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1170 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1170
1171
1171 # Restore global vars from conflict_globs
1172 # Restore global vars from conflict_globs
1172 if conflict_globs:
1173 if conflict_globs:
1173 glob.update(conflict_globs)
1174 glob.update(conflict_globs)
1174
1175
1175 if not quiet :
1176 if not quiet :
1176 # Check best timing is greater than zero to avoid a
1177 # Check best timing is greater than zero to avoid a
1177 # ZeroDivisionError.
1178 # ZeroDivisionError.
1178 # In cases where the slowest timing is lesser than a microsecond
1179 # In cases where the slowest timing is lesser than a microsecond
1179 # we assume that it does not really matter if the fastest
1180 # we assume that it does not really matter if the fastest
1180 # timing is 4 times faster than the slowest timing or not.
1181 # timing is 4 times faster than the slowest timing or not.
1181 if worst > 4 * best and best > 0 and worst > 1e-6:
1182 if worst > 4 * best and best > 0 and worst > 1e-6:
1182 print("The slowest run took %0.2f times longer than the "
1183 print("The slowest run took %0.2f times longer than the "
1183 "fastest. This could mean that an intermediate result "
1184 "fastest. This could mean that an intermediate result "
1184 "is being cached." % (worst / best))
1185 "is being cached." % (worst / best))
1185
1186
1186 print( timeit_result )
1187 print( timeit_result )
1187
1188
1188 if tc > tc_min:
1189 if tc > tc_min:
1189 print("Compiler time: %.2f s" % tc)
1190 print("Compiler time: %.2f s" % tc)
1190 if return_result:
1191 if return_result:
1191 return timeit_result
1192 return timeit_result
1192
1193
1193 @skip_doctest
1194 @skip_doctest
1194 @no_var_expand
1195 @no_var_expand
1195 @needs_local_scope
1196 @needs_local_scope
1196 @line_cell_magic
1197 @line_cell_magic
1198 @output_can_be_disabled
1197 def time(self,line='', cell=None, local_ns=None):
1199 def time(self,line='', cell=None, local_ns=None):
1198 """Time execution of a Python statement or expression.
1200 """Time execution of a Python statement or expression.
1199
1201
1200 The CPU and wall clock times are printed, and the value of the
1202 The CPU and wall clock times are printed, and the value of the
1201 expression (if any) is returned. Note that under Win32, system time
1203 expression (if any) is returned. Note that under Win32, system time
1202 is always reported as 0, since it can not be measured.
1204 is always reported as 0, since it can not be measured.
1203
1205
1204 This function can be used both as a line and cell magic:
1206 This function can be used both as a line and cell magic:
1205
1207
1206 - In line mode you can time a single-line statement (though multiple
1208 - In line mode you can time a single-line statement (though multiple
1207 ones can be chained with using semicolons).
1209 ones can be chained with using semicolons).
1208
1210
1209 - In cell mode, you can time the cell body (a directly
1211 - In cell mode, you can time the cell body (a directly
1210 following statement raises an error).
1212 following statement raises an error).
1211
1213
1212 This function provides very basic timing functionality. Use the timeit
1214 This function provides very basic timing functionality. Use the timeit
1213 magic for more control over the measurement.
1215 magic for more control over the measurement.
1214
1216
1215 .. versionchanged:: 7.3
1217 .. versionchanged:: 7.3
1216 User variables are no longer expanded,
1218 User variables are no longer expanded,
1217 the magic line is always left unmodified.
1219 the magic line is always left unmodified.
1218
1220
1219 Examples
1221 Examples
1220 --------
1222 --------
1221 ::
1223 ::
1222
1224
1223 In [1]: %time 2**128
1225 In [1]: %time 2**128
1224 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1226 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1225 Wall time: 0.00
1227 Wall time: 0.00
1226 Out[1]: 340282366920938463463374607431768211456L
1228 Out[1]: 340282366920938463463374607431768211456L
1227
1229
1228 In [2]: n = 1000000
1230 In [2]: n = 1000000
1229
1231
1230 In [3]: %time sum(range(n))
1232 In [3]: %time sum(range(n))
1231 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1233 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1232 Wall time: 1.37
1234 Wall time: 1.37
1233 Out[3]: 499999500000L
1235 Out[3]: 499999500000L
1234
1236
1235 In [4]: %time print 'hello world'
1237 In [4]: %time print 'hello world'
1236 hello world
1238 hello world
1237 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1239 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1238 Wall time: 0.00
1240 Wall time: 0.00
1239
1241
1240 .. note::
1242 .. note::
1241 The time needed by Python to compile the given expression will be
1243 The time needed by Python to compile the given expression will be
1242 reported if it is more than 0.1s.
1244 reported if it is more than 0.1s.
1243
1245
1244 In the example below, the actual exponentiation is done by Python
1246 In the example below, the actual exponentiation is done by Python
1245 at compilation time, so while the expression can take a noticeable
1247 at compilation time, so while the expression can take a noticeable
1246 amount of time to compute, that time is purely due to the
1248 amount of time to compute, that time is purely due to the
1247 compilation::
1249 compilation::
1248
1250
1249 In [5]: %time 3**9999;
1251 In [5]: %time 3**9999;
1250 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1252 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1251 Wall time: 0.00 s
1253 Wall time: 0.00 s
1252
1254
1253 In [6]: %time 3**999999;
1255 In [6]: %time 3**999999;
1254 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1256 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1255 Wall time: 0.00 s
1257 Wall time: 0.00 s
1256 Compiler : 0.78 s
1258 Compiler : 0.78 s
1257 """
1259 """
1258 # fail immediately if the given expression can't be compiled
1260 # fail immediately if the given expression can't be compiled
1259
1261
1260 if line and cell:
1262 if line and cell:
1261 raise UsageError("Can't use statement directly after '%%time'!")
1263 raise UsageError("Can't use statement directly after '%%time'!")
1262
1264
1263 if cell:
1265 if cell:
1264 expr = self.shell.transform_cell(cell)
1266 expr = self.shell.transform_cell(cell)
1265 else:
1267 else:
1266 expr = self.shell.transform_cell(line)
1268 expr = self.shell.transform_cell(line)
1267
1269
1268 # Minimum time above which parse time will be reported
1270 # Minimum time above which parse time will be reported
1269 tp_min = 0.1
1271 tp_min = 0.1
1270
1272
1271 t0 = clock()
1273 t0 = clock()
1272 expr_ast = self.shell.compile.ast_parse(expr)
1274 expr_ast = self.shell.compile.ast_parse(expr)
1273 tp = clock()-t0
1275 tp = clock()-t0
1274
1276
1275 # Apply AST transformations
1277 # Apply AST transformations
1276 expr_ast = self.shell.transform_ast(expr_ast)
1278 expr_ast = self.shell.transform_ast(expr_ast)
1277
1279
1278 # Minimum time above which compilation time will be reported
1280 # Minimum time above which compilation time will be reported
1279 tc_min = 0.1
1281 tc_min = 0.1
1280
1282
1281 expr_val=None
1283 expr_val=None
1282 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1284 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1283 mode = 'eval'
1285 mode = 'eval'
1284 source = '<timed eval>'
1286 source = '<timed eval>'
1285 expr_ast = ast.Expression(expr_ast.body[0].value)
1287 expr_ast = ast.Expression(expr_ast.body[0].value)
1286 else:
1288 else:
1287 mode = 'exec'
1289 mode = 'exec'
1288 source = '<timed exec>'
1290 source = '<timed exec>'
1289 # multi-line %%time case
1291 # multi-line %%time case
1290 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1292 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1291 expr_val= expr_ast.body[-1]
1293 expr_val= expr_ast.body[-1]
1292 expr_ast = expr_ast.body[:-1]
1294 expr_ast = expr_ast.body[:-1]
1293 expr_ast = Module(expr_ast, [])
1295 expr_ast = Module(expr_ast, [])
1294 expr_val = ast.Expression(expr_val.value)
1296 expr_val = ast.Expression(expr_val.value)
1295
1297
1296 t0 = clock()
1298 t0 = clock()
1297 code = self.shell.compile(expr_ast, source, mode)
1299 code = self.shell.compile(expr_ast, source, mode)
1298 tc = clock()-t0
1300 tc = clock()-t0
1299
1301
1300 # skew measurement as little as possible
1302 # skew measurement as little as possible
1301 glob = self.shell.user_ns
1303 glob = self.shell.user_ns
1302 wtime = time.time
1304 wtime = time.time
1303 # time execution
1305 # time execution
1304 wall_st = wtime()
1306 wall_st = wtime()
1305 if mode=='eval':
1307 if mode=='eval':
1306 st = clock2()
1308 st = clock2()
1307 try:
1309 try:
1308 out = eval(code, glob, local_ns)
1310 out = eval(code, glob, local_ns)
1309 except:
1311 except:
1310 self.shell.showtraceback()
1312 self.shell.showtraceback()
1311 return
1313 return
1312 end = clock2()
1314 end = clock2()
1313 else:
1315 else:
1314 st = clock2()
1316 st = clock2()
1315 try:
1317 try:
1316 exec(code, glob, local_ns)
1318 exec(code, glob, local_ns)
1317 out=None
1319 out=None
1318 # multi-line %%time case
1320 # multi-line %%time case
1319 if expr_val is not None:
1321 if expr_val is not None:
1320 code_2 = self.shell.compile(expr_val, source, 'eval')
1322 code_2 = self.shell.compile(expr_val, source, 'eval')
1321 out = eval(code_2, glob, local_ns)
1323 out = eval(code_2, glob, local_ns)
1322 except:
1324 except:
1323 self.shell.showtraceback()
1325 self.shell.showtraceback()
1324 return
1326 return
1325 end = clock2()
1327 end = clock2()
1326
1328
1327 wall_end = wtime()
1329 wall_end = wtime()
1328 # Compute actual times and report
1330 # Compute actual times and report
1329 wall_time = wall_end - wall_st
1331 wall_time = wall_end - wall_st
1330 cpu_user = end[0] - st[0]
1332 cpu_user = end[0] - st[0]
1331 cpu_sys = end[1] - st[1]
1333 cpu_sys = end[1] - st[1]
1332 cpu_tot = cpu_user + cpu_sys
1334 cpu_tot = cpu_user + cpu_sys
1333 # On windows cpu_sys is always zero, so only total is displayed
1335 # On windows cpu_sys is always zero, so only total is displayed
1334 if sys.platform != "win32":
1336 if sys.platform != "win32":
1335 print(
1337 print(
1336 f"CPU times: user {_format_time(cpu_user)}, sys: {_format_time(cpu_sys)}, total: {_format_time(cpu_tot)}"
1338 f"CPU times: user {_format_time(cpu_user)}, sys: {_format_time(cpu_sys)}, total: {_format_time(cpu_tot)}"
1337 )
1339 )
1338 else:
1340 else:
1339 print(f"CPU times: total: {_format_time(cpu_tot)}")
1341 print(f"CPU times: total: {_format_time(cpu_tot)}")
1340 print(f"Wall time: {_format_time(wall_time)}")
1342 print(f"Wall time: {_format_time(wall_time)}")
1341 if tc > tc_min:
1343 if tc > tc_min:
1342 print(f"Compiler : {_format_time(tc)}")
1344 print(f"Compiler : {_format_time(tc)}")
1343 if tp > tp_min:
1345 if tp > tp_min:
1344 print(f"Parser : {_format_time(tp)}")
1346 print(f"Parser : {_format_time(tp)}")
1345 return out
1347 return out
1346
1348
1347 @skip_doctest
1349 @skip_doctest
1348 @line_magic
1350 @line_magic
1349 def macro(self, parameter_s=''):
1351 def macro(self, parameter_s=''):
1350 """Define a macro for future re-execution. It accepts ranges of history,
1352 """Define a macro for future re-execution. It accepts ranges of history,
1351 filenames or string objects.
1353 filenames or string objects.
1352
1354
1353 Usage:\\
1355 Usage:\\
1354 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1356 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1355
1357
1356 Options:
1358 Options:
1357
1359
1358 -r: use 'raw' input. By default, the 'processed' history is used,
1360 -r: use 'raw' input. By default, the 'processed' history is used,
1359 so that magics are loaded in their transformed version to valid
1361 so that magics are loaded in their transformed version to valid
1360 Python. If this option is given, the raw input as typed at the
1362 Python. If this option is given, the raw input as typed at the
1361 command line is used instead.
1363 command line is used instead.
1362
1364
1363 -q: quiet macro definition. By default, a tag line is printed
1365 -q: quiet macro definition. By default, a tag line is printed
1364 to indicate the macro has been created, and then the contents of
1366 to indicate the macro has been created, and then the contents of
1365 the macro are printed. If this option is given, then no printout
1367 the macro are printed. If this option is given, then no printout
1366 is produced once the macro is created.
1368 is produced once the macro is created.
1367
1369
1368 This will define a global variable called `name` which is a string
1370 This will define a global variable called `name` which is a string
1369 made of joining the slices and lines you specify (n1,n2,... numbers
1371 made of joining the slices and lines you specify (n1,n2,... numbers
1370 above) from your input history into a single string. This variable
1372 above) from your input history into a single string. This variable
1371 acts like an automatic function which re-executes those lines as if
1373 acts like an automatic function which re-executes those lines as if
1372 you had typed them. You just type 'name' at the prompt and the code
1374 you had typed them. You just type 'name' at the prompt and the code
1373 executes.
1375 executes.
1374
1376
1375 The syntax for indicating input ranges is described in %history.
1377 The syntax for indicating input ranges is described in %history.
1376
1378
1377 Note: as a 'hidden' feature, you can also use traditional python slice
1379 Note: as a 'hidden' feature, you can also use traditional python slice
1378 notation, where N:M means numbers N through M-1.
1380 notation, where N:M means numbers N through M-1.
1379
1381
1380 For example, if your history contains (print using %hist -n )::
1382 For example, if your history contains (print using %hist -n )::
1381
1383
1382 44: x=1
1384 44: x=1
1383 45: y=3
1385 45: y=3
1384 46: z=x+y
1386 46: z=x+y
1385 47: print x
1387 47: print x
1386 48: a=5
1388 48: a=5
1387 49: print 'x',x,'y',y
1389 49: print 'x',x,'y',y
1388
1390
1389 you can create a macro with lines 44 through 47 (included) and line 49
1391 you can create a macro with lines 44 through 47 (included) and line 49
1390 called my_macro with::
1392 called my_macro with::
1391
1393
1392 In [55]: %macro my_macro 44-47 49
1394 In [55]: %macro my_macro 44-47 49
1393
1395
1394 Now, typing `my_macro` (without quotes) will re-execute all this code
1396 Now, typing `my_macro` (without quotes) will re-execute all this code
1395 in one pass.
1397 in one pass.
1396
1398
1397 You don't need to give the line-numbers in order, and any given line
1399 You don't need to give the line-numbers in order, and any given line
1398 number can appear multiple times. You can assemble macros with any
1400 number can appear multiple times. You can assemble macros with any
1399 lines from your input history in any order.
1401 lines from your input history in any order.
1400
1402
1401 The macro is a simple object which holds its value in an attribute,
1403 The macro is a simple object which holds its value in an attribute,
1402 but IPython's display system checks for macros and executes them as
1404 but IPython's display system checks for macros and executes them as
1403 code instead of printing them when you type their name.
1405 code instead of printing them when you type their name.
1404
1406
1405 You can view a macro's contents by explicitly printing it with::
1407 You can view a macro's contents by explicitly printing it with::
1406
1408
1407 print macro_name
1409 print macro_name
1408
1410
1409 """
1411 """
1410 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1412 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1411 if not args: # List existing macros
1413 if not args: # List existing macros
1412 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1414 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1413 if len(args) == 1:
1415 if len(args) == 1:
1414 raise UsageError(
1416 raise UsageError(
1415 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1417 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1416 name, codefrom = args[0], " ".join(args[1:])
1418 name, codefrom = args[0], " ".join(args[1:])
1417
1419
1418 #print 'rng',ranges # dbg
1420 #print 'rng',ranges # dbg
1419 try:
1421 try:
1420 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1422 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1421 except (ValueError, TypeError) as e:
1423 except (ValueError, TypeError) as e:
1422 print(e.args[0])
1424 print(e.args[0])
1423 return
1425 return
1424 macro = Macro(lines)
1426 macro = Macro(lines)
1425 self.shell.define_macro(name, macro)
1427 self.shell.define_macro(name, macro)
1426 if not ( 'q' in opts) :
1428 if not ( 'q' in opts) :
1427 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1429 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1428 print('=== Macro contents: ===')
1430 print('=== Macro contents: ===')
1429 print(macro, end=' ')
1431 print(macro, end=' ')
1430
1432
1431 @magic_arguments.magic_arguments()
1433 @magic_arguments.magic_arguments()
1432 @magic_arguments.argument('output', type=str, default='', nargs='?',
1434 @magic_arguments.argument('output', type=str, default='', nargs='?',
1433 help="""The name of the variable in which to store output.
1435 help="""The name of the variable in which to store output.
1434 This is a utils.io.CapturedIO object with stdout/err attributes
1436 This is a utils.io.CapturedIO object with stdout/err attributes
1435 for the text of the captured output.
1437 for the text of the captured output.
1436
1438
1437 CapturedOutput also has a show() method for displaying the output,
1439 CapturedOutput also has a show() method for displaying the output,
1438 and __call__ as well, so you can use that to quickly display the
1440 and __call__ as well, so you can use that to quickly display the
1439 output.
1441 output.
1440
1442
1441 If unspecified, captured output is discarded.
1443 If unspecified, captured output is discarded.
1442 """
1444 """
1443 )
1445 )
1444 @magic_arguments.argument('--no-stderr', action="store_true",
1446 @magic_arguments.argument('--no-stderr', action="store_true",
1445 help="""Don't capture stderr."""
1447 help="""Don't capture stderr."""
1446 )
1448 )
1447 @magic_arguments.argument('--no-stdout', action="store_true",
1449 @magic_arguments.argument('--no-stdout', action="store_true",
1448 help="""Don't capture stdout."""
1450 help="""Don't capture stdout."""
1449 )
1451 )
1450 @magic_arguments.argument('--no-display', action="store_true",
1452 @magic_arguments.argument('--no-display', action="store_true",
1451 help="""Don't capture IPython's rich display."""
1453 help="""Don't capture IPython's rich display."""
1452 )
1454 )
1453 @cell_magic
1455 @cell_magic
1454 def capture(self, line, cell):
1456 def capture(self, line, cell):
1455 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1457 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1456 args = magic_arguments.parse_argstring(self.capture, line)
1458 args = magic_arguments.parse_argstring(self.capture, line)
1457 out = not args.no_stdout
1459 out = not args.no_stdout
1458 err = not args.no_stderr
1460 err = not args.no_stderr
1459 disp = not args.no_display
1461 disp = not args.no_display
1460 with capture_output(out, err, disp) as io:
1462 with capture_output(out, err, disp) as io:
1461 self.shell.run_cell(cell)
1463 self.shell.run_cell(cell)
1462 if args.output:
1464 if args.output:
1463 self.shell.user_ns[args.output] = io
1465 self.shell.user_ns[args.output] = io
1464
1466
1465 def parse_breakpoint(text, current_file):
1467 def parse_breakpoint(text, current_file):
1466 '''Returns (file, line) for file:line and (current_file, line) for line'''
1468 '''Returns (file, line) for file:line and (current_file, line) for line'''
1467 colon = text.find(':')
1469 colon = text.find(':')
1468 if colon == -1:
1470 if colon == -1:
1469 return current_file, int(text)
1471 return current_file, int(text)
1470 else:
1472 else:
1471 return text[:colon], int(text[colon+1:])
1473 return text[:colon], int(text[colon+1:])
1472
1474
1473 def _format_time(timespan, precision=3):
1475 def _format_time(timespan, precision=3):
1474 """Formats the timespan in a human readable form"""
1476 """Formats the timespan in a human readable form"""
1475
1477
1476 if timespan >= 60.0:
1478 if timespan >= 60.0:
1477 # we have more than a minute, format that in a human readable form
1479 # we have more than a minute, format that in a human readable form
1478 # Idea from http://snipplr.com/view/5713/
1480 # Idea from http://snipplr.com/view/5713/
1479 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1481 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1480 time = []
1482 time = []
1481 leftover = timespan
1483 leftover = timespan
1482 for suffix, length in parts:
1484 for suffix, length in parts:
1483 value = int(leftover / length)
1485 value = int(leftover / length)
1484 if value > 0:
1486 if value > 0:
1485 leftover = leftover % length
1487 leftover = leftover % length
1486 time.append(u'%s%s' % (str(value), suffix))
1488 time.append(u'%s%s' % (str(value), suffix))
1487 if leftover < 1:
1489 if leftover < 1:
1488 break
1490 break
1489 return " ".join(time)
1491 return " ".join(time)
1490
1492
1491
1493
1492 # Unfortunately the unicode 'micro' symbol can cause problems in
1494 # Unfortunately the unicode 'micro' symbol can cause problems in
1493 # certain terminals.
1495 # certain terminals.
1494 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1496 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1495 # Try to prevent crashes by being more secure than it needs to
1497 # Try to prevent crashes by being more secure than it needs to
1496 # E.g. eclipse is able to print a Β΅, but has no sys.stdout.encoding set.
1498 # E.g. eclipse is able to print a Β΅, but has no sys.stdout.encoding set.
1497 units = [u"s", u"ms",u'us',"ns"] # the save value
1499 units = [u"s", u"ms",u'us',"ns"] # the save value
1498 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1500 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1499 try:
1501 try:
1500 u'\xb5'.encode(sys.stdout.encoding)
1502 u'\xb5'.encode(sys.stdout.encoding)
1501 units = [u"s", u"ms",u'\xb5s',"ns"]
1503 units = [u"s", u"ms",u'\xb5s',"ns"]
1502 except:
1504 except:
1503 pass
1505 pass
1504 scaling = [1, 1e3, 1e6, 1e9]
1506 scaling = [1, 1e3, 1e6, 1e9]
1505
1507
1506 if timespan > 0.0:
1508 if timespan > 0.0:
1507 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1509 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1508 else:
1510 else:
1509 order = 3
1511 order = 3
1510 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
1512 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
@@ -1,1471 +1,1486 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Tests for various magic functions."""
2 """Tests for various magic functions."""
3
3
4 import gc
4 import gc
5 import io
5 import io
6 import os
6 import os
7 import re
7 import re
8 import shlex
8 import shlex
9 import sys
9 import sys
10 import warnings
10 import warnings
11 from importlib import invalidate_caches
11 from importlib import invalidate_caches
12 from io import StringIO
12 from io import StringIO
13 from pathlib import Path
13 from pathlib import Path
14 from textwrap import dedent
14 from textwrap import dedent
15 from unittest import TestCase, mock
15 from unittest import TestCase, mock
16
16
17 import pytest
17 import pytest
18
18
19 from IPython import get_ipython
19 from IPython import get_ipython
20 from IPython.core import magic
20 from IPython.core import magic
21 from IPython.core.error import UsageError
21 from IPython.core.error import UsageError
22 from IPython.core.magic import (
22 from IPython.core.magic import (
23 Magics,
23 Magics,
24 cell_magic,
24 cell_magic,
25 line_magic,
25 line_magic,
26 magics_class,
26 magics_class,
27 register_cell_magic,
27 register_cell_magic,
28 register_line_magic,
28 register_line_magic,
29 )
29 )
30 from IPython.core.magics import code, execution, logging, osm, script
30 from IPython.core.magics import code, execution, logging, osm, script
31 from IPython.testing import decorators as dec
31 from IPython.testing import decorators as dec
32 from IPython.testing import tools as tt
32 from IPython.testing import tools as tt
33 from IPython.utils.io import capture_output
33 from IPython.utils.io import capture_output
34 from IPython.utils.process import find_cmd
34 from IPython.utils.process import find_cmd
35 from IPython.utils.tempdir import TemporaryDirectory, TemporaryWorkingDirectory
35 from IPython.utils.tempdir import TemporaryDirectory, TemporaryWorkingDirectory
36 from IPython.utils.syspathcontext import prepended_to_syspath
36 from IPython.utils.syspathcontext import prepended_to_syspath
37
37
38 from .test_debugger import PdbTestInput
38 from .test_debugger import PdbTestInput
39
39
40 from tempfile import NamedTemporaryFile
40 from tempfile import NamedTemporaryFile
41
41
42 @magic.magics_class
42 @magic.magics_class
43 class DummyMagics(magic.Magics): pass
43 class DummyMagics(magic.Magics): pass
44
44
45 def test_extract_code_ranges():
45 def test_extract_code_ranges():
46 instr = "1 3 5-6 7-9 10:15 17: :10 10- -13 :"
46 instr = "1 3 5-6 7-9 10:15 17: :10 10- -13 :"
47 expected = [
47 expected = [
48 (0, 1),
48 (0, 1),
49 (2, 3),
49 (2, 3),
50 (4, 6),
50 (4, 6),
51 (6, 9),
51 (6, 9),
52 (9, 14),
52 (9, 14),
53 (16, None),
53 (16, None),
54 (None, 9),
54 (None, 9),
55 (9, None),
55 (9, None),
56 (None, 13),
56 (None, 13),
57 (None, None),
57 (None, None),
58 ]
58 ]
59 actual = list(code.extract_code_ranges(instr))
59 actual = list(code.extract_code_ranges(instr))
60 assert actual == expected
60 assert actual == expected
61
61
62 def test_extract_symbols():
62 def test_extract_symbols():
63 source = """import foo\na = 10\ndef b():\n return 42\n\n\nclass A: pass\n\n\n"""
63 source = """import foo\na = 10\ndef b():\n return 42\n\n\nclass A: pass\n\n\n"""
64 symbols_args = ["a", "b", "A", "A,b", "A,a", "z"]
64 symbols_args = ["a", "b", "A", "A,b", "A,a", "z"]
65 expected = [([], ['a']),
65 expected = [([], ['a']),
66 (["def b():\n return 42\n"], []),
66 (["def b():\n return 42\n"], []),
67 (["class A: pass\n"], []),
67 (["class A: pass\n"], []),
68 (["class A: pass\n", "def b():\n return 42\n"], []),
68 (["class A: pass\n", "def b():\n return 42\n"], []),
69 (["class A: pass\n"], ['a']),
69 (["class A: pass\n"], ['a']),
70 ([], ['z'])]
70 ([], ['z'])]
71 for symbols, exp in zip(symbols_args, expected):
71 for symbols, exp in zip(symbols_args, expected):
72 assert code.extract_symbols(source, symbols) == exp
72 assert code.extract_symbols(source, symbols) == exp
73
73
74
74
75 def test_extract_symbols_raises_exception_with_non_python_code():
75 def test_extract_symbols_raises_exception_with_non_python_code():
76 source = ("=begin A Ruby program :)=end\n"
76 source = ("=begin A Ruby program :)=end\n"
77 "def hello\n"
77 "def hello\n"
78 "puts 'Hello world'\n"
78 "puts 'Hello world'\n"
79 "end")
79 "end")
80 with pytest.raises(SyntaxError):
80 with pytest.raises(SyntaxError):
81 code.extract_symbols(source, "hello")
81 code.extract_symbols(source, "hello")
82
82
83
83
84 def test_magic_not_found():
84 def test_magic_not_found():
85 # magic not found raises UsageError
85 # magic not found raises UsageError
86 with pytest.raises(UsageError):
86 with pytest.raises(UsageError):
87 _ip.run_line_magic("doesntexist", "")
87 _ip.run_line_magic("doesntexist", "")
88
88
89 # ensure result isn't success when a magic isn't found
89 # ensure result isn't success when a magic isn't found
90 result = _ip.run_cell('%doesntexist')
90 result = _ip.run_cell('%doesntexist')
91 assert isinstance(result.error_in_exec, UsageError)
91 assert isinstance(result.error_in_exec, UsageError)
92
92
93
93
94 def test_cell_magic_not_found():
94 def test_cell_magic_not_found():
95 # magic not found raises UsageError
95 # magic not found raises UsageError
96 with pytest.raises(UsageError):
96 with pytest.raises(UsageError):
97 _ip.run_cell_magic('doesntexist', 'line', 'cell')
97 _ip.run_cell_magic('doesntexist', 'line', 'cell')
98
98
99 # ensure result isn't success when a magic isn't found
99 # ensure result isn't success when a magic isn't found
100 result = _ip.run_cell('%%doesntexist')
100 result = _ip.run_cell('%%doesntexist')
101 assert isinstance(result.error_in_exec, UsageError)
101 assert isinstance(result.error_in_exec, UsageError)
102
102
103
103
104 def test_magic_error_status():
104 def test_magic_error_status():
105 def fail(shell):
105 def fail(shell):
106 1/0
106 1/0
107 _ip.register_magic_function(fail)
107 _ip.register_magic_function(fail)
108 result = _ip.run_cell('%fail')
108 result = _ip.run_cell('%fail')
109 assert isinstance(result.error_in_exec, ZeroDivisionError)
109 assert isinstance(result.error_in_exec, ZeroDivisionError)
110
110
111
111
112 def test_config():
112 def test_config():
113 """ test that config magic does not raise
113 """ test that config magic does not raise
114 can happen if Configurable init is moved too early into
114 can happen if Configurable init is moved too early into
115 Magics.__init__ as then a Config object will be registered as a
115 Magics.__init__ as then a Config object will be registered as a
116 magic.
116 magic.
117 """
117 """
118 ## should not raise.
118 ## should not raise.
119 _ip.run_line_magic("config", "")
119 _ip.run_line_magic("config", "")
120
120
121
121
122 def test_config_available_configs():
122 def test_config_available_configs():
123 """ test that config magic prints available configs in unique and
123 """ test that config magic prints available configs in unique and
124 sorted order. """
124 sorted order. """
125 with capture_output() as captured:
125 with capture_output() as captured:
126 _ip.run_line_magic("config", "")
126 _ip.run_line_magic("config", "")
127
127
128 stdout = captured.stdout
128 stdout = captured.stdout
129 config_classes = stdout.strip().split('\n')[1:]
129 config_classes = stdout.strip().split('\n')[1:]
130 assert config_classes == sorted(set(config_classes))
130 assert config_classes == sorted(set(config_classes))
131
131
132 def test_config_print_class():
132 def test_config_print_class():
133 """ test that config with a classname prints the class's options. """
133 """ test that config with a classname prints the class's options. """
134 with capture_output() as captured:
134 with capture_output() as captured:
135 _ip.run_line_magic("config", "TerminalInteractiveShell")
135 _ip.run_line_magic("config", "TerminalInteractiveShell")
136
136
137 stdout = captured.stdout
137 stdout = captured.stdout
138 assert re.match(
138 assert re.match(
139 "TerminalInteractiveShell.* options", stdout.splitlines()[0]
139 "TerminalInteractiveShell.* options", stdout.splitlines()[0]
140 ), f"{stdout}\n\n1st line of stdout not like 'TerminalInteractiveShell.* options'"
140 ), f"{stdout}\n\n1st line of stdout not like 'TerminalInteractiveShell.* options'"
141
141
142
142
143 def test_rehashx():
143 def test_rehashx():
144 # clear up everything
144 # clear up everything
145 _ip.alias_manager.clear_aliases()
145 _ip.alias_manager.clear_aliases()
146 del _ip.db['syscmdlist']
146 del _ip.db['syscmdlist']
147
147
148 _ip.run_line_magic("rehashx", "")
148 _ip.run_line_magic("rehashx", "")
149 # Practically ALL ipython development systems will have more than 10 aliases
149 # Practically ALL ipython development systems will have more than 10 aliases
150
150
151 assert len(_ip.alias_manager.aliases) > 10
151 assert len(_ip.alias_manager.aliases) > 10
152 for name, cmd in _ip.alias_manager.aliases:
152 for name, cmd in _ip.alias_manager.aliases:
153 # we must strip dots from alias names
153 # we must strip dots from alias names
154 assert "." not in name
154 assert "." not in name
155
155
156 # rehashx must fill up syscmdlist
156 # rehashx must fill up syscmdlist
157 scoms = _ip.db['syscmdlist']
157 scoms = _ip.db['syscmdlist']
158 assert len(scoms) > 10
158 assert len(scoms) > 10
159
159
160
160
161 def test_magic_parse_options():
161 def test_magic_parse_options():
162 """Test that we don't mangle paths when parsing magic options."""
162 """Test that we don't mangle paths when parsing magic options."""
163 ip = get_ipython()
163 ip = get_ipython()
164 path = 'c:\\x'
164 path = 'c:\\x'
165 m = DummyMagics(ip)
165 m = DummyMagics(ip)
166 opts = m.parse_options('-f %s' % path,'f:')[0]
166 opts = m.parse_options('-f %s' % path,'f:')[0]
167 # argv splitting is os-dependent
167 # argv splitting is os-dependent
168 if os.name == 'posix':
168 if os.name == 'posix':
169 expected = 'c:x'
169 expected = 'c:x'
170 else:
170 else:
171 expected = path
171 expected = path
172 assert opts["f"] == expected
172 assert opts["f"] == expected
173
173
174
174
175 def test_magic_parse_long_options():
175 def test_magic_parse_long_options():
176 """Magic.parse_options can handle --foo=bar long options"""
176 """Magic.parse_options can handle --foo=bar long options"""
177 ip = get_ipython()
177 ip = get_ipython()
178 m = DummyMagics(ip)
178 m = DummyMagics(ip)
179 opts, _ = m.parse_options("--foo --bar=bubble", "a", "foo", "bar=")
179 opts, _ = m.parse_options("--foo --bar=bubble", "a", "foo", "bar=")
180 assert "foo" in opts
180 assert "foo" in opts
181 assert "bar" in opts
181 assert "bar" in opts
182 assert opts["bar"] == "bubble"
182 assert opts["bar"] == "bubble"
183
183
184
184
185 def doctest_hist_f():
185 def doctest_hist_f():
186 """Test %hist -f with temporary filename.
186 """Test %hist -f with temporary filename.
187
187
188 In [9]: import tempfile
188 In [9]: import tempfile
189
189
190 In [10]: tfile = tempfile.mktemp('.py','tmp-ipython-')
190 In [10]: tfile = tempfile.mktemp('.py','tmp-ipython-')
191
191
192 In [11]: %hist -nl -f $tfile 3
192 In [11]: %hist -nl -f $tfile 3
193
193
194 In [13]: import os; os.unlink(tfile)
194 In [13]: import os; os.unlink(tfile)
195 """
195 """
196
196
197
197
198 def doctest_hist_op():
198 def doctest_hist_op():
199 """Test %hist -op
199 """Test %hist -op
200
200
201 In [1]: class b(float):
201 In [1]: class b(float):
202 ...: pass
202 ...: pass
203 ...:
203 ...:
204
204
205 In [2]: class s(object):
205 In [2]: class s(object):
206 ...: def __str__(self):
206 ...: def __str__(self):
207 ...: return 's'
207 ...: return 's'
208 ...:
208 ...:
209
209
210 In [3]:
210 In [3]:
211
211
212 In [4]: class r(b):
212 In [4]: class r(b):
213 ...: def __repr__(self):
213 ...: def __repr__(self):
214 ...: return 'r'
214 ...: return 'r'
215 ...:
215 ...:
216
216
217 In [5]: class sr(s,r): pass
217 In [5]: class sr(s,r): pass
218 ...:
218 ...:
219
219
220 In [6]:
220 In [6]:
221
221
222 In [7]: bb=b()
222 In [7]: bb=b()
223
223
224 In [8]: ss=s()
224 In [8]: ss=s()
225
225
226 In [9]: rr=r()
226 In [9]: rr=r()
227
227
228 In [10]: ssrr=sr()
228 In [10]: ssrr=sr()
229
229
230 In [11]: 4.5
230 In [11]: 4.5
231 Out[11]: 4.5
231 Out[11]: 4.5
232
232
233 In [12]: str(ss)
233 In [12]: str(ss)
234 Out[12]: 's'
234 Out[12]: 's'
235
235
236 In [13]:
236 In [13]:
237
237
238 In [14]: %hist -op
238 In [14]: %hist -op
239 >>> class b:
239 >>> class b:
240 ... pass
240 ... pass
241 ...
241 ...
242 >>> class s(b):
242 >>> class s(b):
243 ... def __str__(self):
243 ... def __str__(self):
244 ... return 's'
244 ... return 's'
245 ...
245 ...
246 >>>
246 >>>
247 >>> class r(b):
247 >>> class r(b):
248 ... def __repr__(self):
248 ... def __repr__(self):
249 ... return 'r'
249 ... return 'r'
250 ...
250 ...
251 >>> class sr(s,r): pass
251 >>> class sr(s,r): pass
252 >>>
252 >>>
253 >>> bb=b()
253 >>> bb=b()
254 >>> ss=s()
254 >>> ss=s()
255 >>> rr=r()
255 >>> rr=r()
256 >>> ssrr=sr()
256 >>> ssrr=sr()
257 >>> 4.5
257 >>> 4.5
258 4.5
258 4.5
259 >>> str(ss)
259 >>> str(ss)
260 's'
260 's'
261 >>>
261 >>>
262 """
262 """
263
263
264 def test_hist_pof():
264 def test_hist_pof():
265 ip = get_ipython()
265 ip = get_ipython()
266 ip.run_cell("1+2", store_history=True)
266 ip.run_cell("1+2", store_history=True)
267 #raise Exception(ip.history_manager.session_number)
267 #raise Exception(ip.history_manager.session_number)
268 #raise Exception(list(ip.history_manager._get_range_session()))
268 #raise Exception(list(ip.history_manager._get_range_session()))
269 with TemporaryDirectory() as td:
269 with TemporaryDirectory() as td:
270 tf = os.path.join(td, 'hist.py')
270 tf = os.path.join(td, 'hist.py')
271 ip.run_line_magic('history', '-pof %s' % tf)
271 ip.run_line_magic('history', '-pof %s' % tf)
272 assert os.path.isfile(tf)
272 assert os.path.isfile(tf)
273
273
274
274
275 def test_macro():
275 def test_macro():
276 ip = get_ipython()
276 ip = get_ipython()
277 ip.history_manager.reset() # Clear any existing history.
277 ip.history_manager.reset() # Clear any existing history.
278 cmds = ["a=1", "def b():\n return a**2", "print(a,b())"]
278 cmds = ["a=1", "def b():\n return a**2", "print(a,b())"]
279 for i, cmd in enumerate(cmds, start=1):
279 for i, cmd in enumerate(cmds, start=1):
280 ip.history_manager.store_inputs(i, cmd)
280 ip.history_manager.store_inputs(i, cmd)
281 ip.run_line_magic("macro", "test 1-3")
281 ip.run_line_magic("macro", "test 1-3")
282 assert ip.user_ns["test"].value == "\n".join(cmds) + "\n"
282 assert ip.user_ns["test"].value == "\n".join(cmds) + "\n"
283
283
284 # List macros
284 # List macros
285 assert "test" in ip.run_line_magic("macro", "")
285 assert "test" in ip.run_line_magic("macro", "")
286
286
287
287
288 def test_macro_run():
288 def test_macro_run():
289 """Test that we can run a multi-line macro successfully."""
289 """Test that we can run a multi-line macro successfully."""
290 ip = get_ipython()
290 ip = get_ipython()
291 ip.history_manager.reset()
291 ip.history_manager.reset()
292 cmds = ["a=10", "a+=1", "print(a)", "%macro test 2-3"]
292 cmds = ["a=10", "a+=1", "print(a)", "%macro test 2-3"]
293 for cmd in cmds:
293 for cmd in cmds:
294 ip.run_cell(cmd, store_history=True)
294 ip.run_cell(cmd, store_history=True)
295 assert ip.user_ns["test"].value == "a+=1\nprint(a)\n"
295 assert ip.user_ns["test"].value == "a+=1\nprint(a)\n"
296 with tt.AssertPrints("12"):
296 with tt.AssertPrints("12"):
297 ip.run_cell("test")
297 ip.run_cell("test")
298 with tt.AssertPrints("13"):
298 with tt.AssertPrints("13"):
299 ip.run_cell("test")
299 ip.run_cell("test")
300
300
301
301
302 def test_magic_magic():
302 def test_magic_magic():
303 """Test %magic"""
303 """Test %magic"""
304 ip = get_ipython()
304 ip = get_ipython()
305 with capture_output() as captured:
305 with capture_output() as captured:
306 ip.run_line_magic("magic", "")
306 ip.run_line_magic("magic", "")
307
307
308 stdout = captured.stdout
308 stdout = captured.stdout
309 assert "%magic" in stdout
309 assert "%magic" in stdout
310 assert "IPython" in stdout
310 assert "IPython" in stdout
311 assert "Available" in stdout
311 assert "Available" in stdout
312
312
313
313
314 @dec.skipif_not_numpy
314 @dec.skipif_not_numpy
315 def test_numpy_reset_array_undec():
315 def test_numpy_reset_array_undec():
316 "Test '%reset array' functionality"
316 "Test '%reset array' functionality"
317 _ip.ex("import numpy as np")
317 _ip.ex("import numpy as np")
318 _ip.ex("a = np.empty(2)")
318 _ip.ex("a = np.empty(2)")
319 assert "a" in _ip.user_ns
319 assert "a" in _ip.user_ns
320 _ip.run_line_magic("reset", "-f array")
320 _ip.run_line_magic("reset", "-f array")
321 assert "a" not in _ip.user_ns
321 assert "a" not in _ip.user_ns
322
322
323
323
324 def test_reset_out():
324 def test_reset_out():
325 "Test '%reset out' magic"
325 "Test '%reset out' magic"
326 _ip.run_cell("parrot = 'dead'", store_history=True)
326 _ip.run_cell("parrot = 'dead'", store_history=True)
327 # test '%reset -f out', make an Out prompt
327 # test '%reset -f out', make an Out prompt
328 _ip.run_cell("parrot", store_history=True)
328 _ip.run_cell("parrot", store_history=True)
329 assert "dead" in [_ip.user_ns[x] for x in ("_", "__", "___")]
329 assert "dead" in [_ip.user_ns[x] for x in ("_", "__", "___")]
330 _ip.run_line_magic("reset", "-f out")
330 _ip.run_line_magic("reset", "-f out")
331 assert "dead" not in [_ip.user_ns[x] for x in ("_", "__", "___")]
331 assert "dead" not in [_ip.user_ns[x] for x in ("_", "__", "___")]
332 assert len(_ip.user_ns["Out"]) == 0
332 assert len(_ip.user_ns["Out"]) == 0
333
333
334
334
335 def test_reset_in():
335 def test_reset_in():
336 "Test '%reset in' magic"
336 "Test '%reset in' magic"
337 # test '%reset -f in'
337 # test '%reset -f in'
338 _ip.run_cell("parrot", store_history=True)
338 _ip.run_cell("parrot", store_history=True)
339 assert "parrot" in [_ip.user_ns[x] for x in ("_i", "_ii", "_iii")]
339 assert "parrot" in [_ip.user_ns[x] for x in ("_i", "_ii", "_iii")]
340 _ip.run_line_magic("reset", "-f in")
340 _ip.run_line_magic("reset", "-f in")
341 assert "parrot" not in [_ip.user_ns[x] for x in ("_i", "_ii", "_iii")]
341 assert "parrot" not in [_ip.user_ns[x] for x in ("_i", "_ii", "_iii")]
342 assert len(set(_ip.user_ns["In"])) == 1
342 assert len(set(_ip.user_ns["In"])) == 1
343
343
344
344
345 def test_reset_dhist():
345 def test_reset_dhist():
346 "Test '%reset dhist' magic"
346 "Test '%reset dhist' magic"
347 _ip.run_cell("tmp = [d for d in _dh]") # copy before clearing
347 _ip.run_cell("tmp = [d for d in _dh]") # copy before clearing
348 _ip.run_line_magic("cd", os.path.dirname(pytest.__file__))
348 _ip.run_line_magic("cd", os.path.dirname(pytest.__file__))
349 _ip.run_line_magic("cd", "-")
349 _ip.run_line_magic("cd", "-")
350 assert len(_ip.user_ns["_dh"]) > 0
350 assert len(_ip.user_ns["_dh"]) > 0
351 _ip.run_line_magic("reset", "-f dhist")
351 _ip.run_line_magic("reset", "-f dhist")
352 assert len(_ip.user_ns["_dh"]) == 0
352 assert len(_ip.user_ns["_dh"]) == 0
353 _ip.run_cell("_dh = [d for d in tmp]") # restore
353 _ip.run_cell("_dh = [d for d in tmp]") # restore
354
354
355
355
356 def test_reset_in_length():
356 def test_reset_in_length():
357 "Test that '%reset in' preserves In[] length"
357 "Test that '%reset in' preserves In[] length"
358 _ip.run_cell("print 'foo'")
358 _ip.run_cell("print 'foo'")
359 _ip.run_cell("reset -f in")
359 _ip.run_cell("reset -f in")
360 assert len(_ip.user_ns["In"]) == _ip.displayhook.prompt_count + 1
360 assert len(_ip.user_ns["In"]) == _ip.displayhook.prompt_count + 1
361
361
362
362
363 class TestResetErrors(TestCase):
363 class TestResetErrors(TestCase):
364
364
365 def test_reset_redefine(self):
365 def test_reset_redefine(self):
366
366
367 @magics_class
367 @magics_class
368 class KernelMagics(Magics):
368 class KernelMagics(Magics):
369 @line_magic
369 @line_magic
370 def less(self, shell): pass
370 def less(self, shell): pass
371
371
372 _ip.register_magics(KernelMagics)
372 _ip.register_magics(KernelMagics)
373
373
374 with self.assertLogs() as cm:
374 with self.assertLogs() as cm:
375 # hack, we want to just capture logs, but assertLogs fails if not
375 # hack, we want to just capture logs, but assertLogs fails if not
376 # logs get produce.
376 # logs get produce.
377 # so log one things we ignore.
377 # so log one things we ignore.
378 import logging as log_mod
378 import logging as log_mod
379 log = log_mod.getLogger()
379 log = log_mod.getLogger()
380 log.info('Nothing')
380 log.info('Nothing')
381 # end hack.
381 # end hack.
382 _ip.run_cell("reset -f")
382 _ip.run_cell("reset -f")
383
383
384 assert len(cm.output) == 1
384 assert len(cm.output) == 1
385 for out in cm.output:
385 for out in cm.output:
386 assert "Invalid alias" not in out
386 assert "Invalid alias" not in out
387
387
388 def test_tb_syntaxerror():
388 def test_tb_syntaxerror():
389 """test %tb after a SyntaxError"""
389 """test %tb after a SyntaxError"""
390 ip = get_ipython()
390 ip = get_ipython()
391 ip.run_cell("for")
391 ip.run_cell("for")
392
392
393 # trap and validate stdout
393 # trap and validate stdout
394 save_stdout = sys.stdout
394 save_stdout = sys.stdout
395 try:
395 try:
396 sys.stdout = StringIO()
396 sys.stdout = StringIO()
397 ip.run_cell("%tb")
397 ip.run_cell("%tb")
398 out = sys.stdout.getvalue()
398 out = sys.stdout.getvalue()
399 finally:
399 finally:
400 sys.stdout = save_stdout
400 sys.stdout = save_stdout
401 # trim output, and only check the last line
401 # trim output, and only check the last line
402 last_line = out.rstrip().splitlines()[-1].strip()
402 last_line = out.rstrip().splitlines()[-1].strip()
403 assert last_line == "SyntaxError: invalid syntax"
403 assert last_line == "SyntaxError: invalid syntax"
404
404
405
405
406 def test_time():
406 def test_time():
407 ip = get_ipython()
407 ip = get_ipython()
408
408
409 with tt.AssertPrints("Wall time: "):
409 with tt.AssertPrints("Wall time: "):
410 ip.run_cell("%time None")
410 ip.run_cell("%time None")
411
411
412 ip.run_cell("def f(kmjy):\n"
412 ip.run_cell("def f(kmjy):\n"
413 " %time print (2*kmjy)")
413 " %time print (2*kmjy)")
414
414
415 with tt.AssertPrints("Wall time: "):
415 with tt.AssertPrints("Wall time: "):
416 with tt.AssertPrints("hihi", suppress=False):
416 with tt.AssertPrints("hihi", suppress=False):
417 ip.run_cell("f('hi')")
417 ip.run_cell("f('hi')")
418
418
419
419
420 # ';' at the end of %time prevents instruction value to be printed.
420 # ';' at the end of %time prevents instruction value to be printed.
421 # This tests fix for #13837.
421 # This tests fix for #13837.
422 def test_time_no_outputwith_semicolon():
422 def test_time_no_output_with_semicolon():
423 ip = get_ipython()
423 ip = get_ipython()
424
424
425 with tt.AssertPrints(" 123456"):
425 with tt.AssertPrints(" 123456"):
426 with tt.AssertPrints("Wall time: ", suppress=False):
426 with tt.AssertPrints("Wall time: ", suppress=False):
427 with tt.AssertPrints("CPU times: ", suppress=False):
427 with tt.AssertPrints("CPU times: ", suppress=False):
428 ip.run_cell("%time 123000+456")
428 ip.run_cell("%time 123000+456")
429
429
430 with tt.AssertNotPrints(" 123456"):
430 with tt.AssertNotPrints(" 123456"):
431 with tt.AssertPrints("Wall time: ", suppress=False):
431 with tt.AssertPrints("Wall time: ", suppress=False):
432 with tt.AssertPrints("CPU times: ", suppress=False):
432 with tt.AssertPrints("CPU times: ", suppress=False):
433 ip.run_cell("%time 123000+456;")
433 ip.run_cell("%time 123000+456;")
434
434
435 with tt.AssertPrints(" 123456"):
436 with tt.AssertPrints("Wall time: ", suppress=False):
437 with tt.AssertPrints("CPU times: ", suppress=False):
438 ip.run_cell("%time 123000+456 # Comment")
439
440 with tt.AssertNotPrints(" 123456"):
441 with tt.AssertPrints("Wall time: ", suppress=False):
442 with tt.AssertPrints("CPU times: ", suppress=False):
443 ip.run_cell("%time 123000+456; # Comment")
444
445 with tt.AssertPrints(" 123456"):
446 with tt.AssertPrints("Wall time: ", suppress=False):
447 with tt.AssertPrints("CPU times: ", suppress=False):
448 ip.run_cell("%time 123000+456 # ;Comment")
449
435
450
436 def test_time_last_not_expression():
451 def test_time_last_not_expression():
437 ip.run_cell("%%time\n"
452 ip.run_cell("%%time\n"
438 "var_1 = 1\n"
453 "var_1 = 1\n"
439 "var_2 = 2\n")
454 "var_2 = 2\n")
440 assert ip.user_ns['var_1'] == 1
455 assert ip.user_ns['var_1'] == 1
441 del ip.user_ns['var_1']
456 del ip.user_ns['var_1']
442 assert ip.user_ns['var_2'] == 2
457 assert ip.user_ns['var_2'] == 2
443 del ip.user_ns['var_2']
458 del ip.user_ns['var_2']
444
459
445
460
446 @dec.skip_win32
461 @dec.skip_win32
447 def test_time2():
462 def test_time2():
448 ip = get_ipython()
463 ip = get_ipython()
449
464
450 with tt.AssertPrints("CPU times: user "):
465 with tt.AssertPrints("CPU times: user "):
451 ip.run_cell("%time None")
466 ip.run_cell("%time None")
452
467
453 def test_time3():
468 def test_time3():
454 """Erroneous magic function calls, issue gh-3334"""
469 """Erroneous magic function calls, issue gh-3334"""
455 ip = get_ipython()
470 ip = get_ipython()
456 ip.user_ns.pop('run', None)
471 ip.user_ns.pop('run', None)
457
472
458 with tt.AssertNotPrints("not found", channel='stderr'):
473 with tt.AssertNotPrints("not found", channel='stderr'):
459 ip.run_cell("%%time\n"
474 ip.run_cell("%%time\n"
460 "run = 0\n"
475 "run = 0\n"
461 "run += 1")
476 "run += 1")
462
477
463 def test_multiline_time():
478 def test_multiline_time():
464 """Make sure last statement from time return a value."""
479 """Make sure last statement from time return a value."""
465 ip = get_ipython()
480 ip = get_ipython()
466 ip.user_ns.pop('run', None)
481 ip.user_ns.pop('run', None)
467
482
468 ip.run_cell(
483 ip.run_cell(
469 dedent(
484 dedent(
470 """\
485 """\
471 %%time
486 %%time
472 a = "ho"
487 a = "ho"
473 b = "hey"
488 b = "hey"
474 a+b
489 a+b
475 """
490 """
476 )
491 )
477 )
492 )
478 assert ip.user_ns_hidden["_"] == "hohey"
493 assert ip.user_ns_hidden["_"] == "hohey"
479
494
480
495
481 def test_time_local_ns():
496 def test_time_local_ns():
482 """
497 """
483 Test that local_ns is actually global_ns when running a cell magic
498 Test that local_ns is actually global_ns when running a cell magic
484 """
499 """
485 ip = get_ipython()
500 ip = get_ipython()
486 ip.run_cell("%%time\n" "myvar = 1")
501 ip.run_cell("%%time\n" "myvar = 1")
487 assert ip.user_ns["myvar"] == 1
502 assert ip.user_ns["myvar"] == 1
488 del ip.user_ns["myvar"]
503 del ip.user_ns["myvar"]
489
504
490
505
491 def test_doctest_mode():
506 def test_doctest_mode():
492 "Toggle doctest_mode twice, it should be a no-op and run without error"
507 "Toggle doctest_mode twice, it should be a no-op and run without error"
493 _ip.run_line_magic("doctest_mode", "")
508 _ip.run_line_magic("doctest_mode", "")
494 _ip.run_line_magic("doctest_mode", "")
509 _ip.run_line_magic("doctest_mode", "")
495
510
496
511
497 def test_parse_options():
512 def test_parse_options():
498 """Tests for basic options parsing in magics."""
513 """Tests for basic options parsing in magics."""
499 # These are only the most minimal of tests, more should be added later. At
514 # These are only the most minimal of tests, more should be added later. At
500 # the very least we check that basic text/unicode calls work OK.
515 # the very least we check that basic text/unicode calls work OK.
501 m = DummyMagics(_ip)
516 m = DummyMagics(_ip)
502 assert m.parse_options("foo", "")[1] == "foo"
517 assert m.parse_options("foo", "")[1] == "foo"
503 assert m.parse_options("foo", "")[1] == "foo"
518 assert m.parse_options("foo", "")[1] == "foo"
504
519
505
520
506 def test_parse_options_preserve_non_option_string():
521 def test_parse_options_preserve_non_option_string():
507 """Test to assert preservation of non-option part of magic-block, while parsing magic options."""
522 """Test to assert preservation of non-option part of magic-block, while parsing magic options."""
508 m = DummyMagics(_ip)
523 m = DummyMagics(_ip)
509 opts, stmt = m.parse_options(
524 opts, stmt = m.parse_options(
510 " -n1 -r 13 _ = 314 + foo", "n:r:", preserve_non_opts=True
525 " -n1 -r 13 _ = 314 + foo", "n:r:", preserve_non_opts=True
511 )
526 )
512 assert opts == {"n": "1", "r": "13"}
527 assert opts == {"n": "1", "r": "13"}
513 assert stmt == "_ = 314 + foo"
528 assert stmt == "_ = 314 + foo"
514
529
515
530
516 def test_run_magic_preserve_code_block():
531 def test_run_magic_preserve_code_block():
517 """Test to assert preservation of non-option part of magic-block, while running magic."""
532 """Test to assert preservation of non-option part of magic-block, while running magic."""
518 _ip.user_ns["spaces"] = []
533 _ip.user_ns["spaces"] = []
519 _ip.run_line_magic(
534 _ip.run_line_magic(
520 "timeit", "-n1 -r1 spaces.append([s.count(' ') for s in ['document']])"
535 "timeit", "-n1 -r1 spaces.append([s.count(' ') for s in ['document']])"
521 )
536 )
522 assert _ip.user_ns["spaces"] == [[0]]
537 assert _ip.user_ns["spaces"] == [[0]]
523
538
524
539
525 def test_dirops():
540 def test_dirops():
526 """Test various directory handling operations."""
541 """Test various directory handling operations."""
527 # curpath = lambda :os.path.splitdrive(os.getcwd())[1].replace('\\','/')
542 # curpath = lambda :os.path.splitdrive(os.getcwd())[1].replace('\\','/')
528 curpath = os.getcwd
543 curpath = os.getcwd
529 startdir = os.getcwd()
544 startdir = os.getcwd()
530 ipdir = os.path.realpath(_ip.ipython_dir)
545 ipdir = os.path.realpath(_ip.ipython_dir)
531 try:
546 try:
532 _ip.run_line_magic("cd", '"%s"' % ipdir)
547 _ip.run_line_magic("cd", '"%s"' % ipdir)
533 assert curpath() == ipdir
548 assert curpath() == ipdir
534 _ip.run_line_magic("cd", "-")
549 _ip.run_line_magic("cd", "-")
535 assert curpath() == startdir
550 assert curpath() == startdir
536 _ip.run_line_magic("pushd", '"%s"' % ipdir)
551 _ip.run_line_magic("pushd", '"%s"' % ipdir)
537 assert curpath() == ipdir
552 assert curpath() == ipdir
538 _ip.run_line_magic("popd", "")
553 _ip.run_line_magic("popd", "")
539 assert curpath() == startdir
554 assert curpath() == startdir
540 finally:
555 finally:
541 os.chdir(startdir)
556 os.chdir(startdir)
542
557
543
558
544 def test_cd_force_quiet():
559 def test_cd_force_quiet():
545 """Test OSMagics.cd_force_quiet option"""
560 """Test OSMagics.cd_force_quiet option"""
546 _ip.config.OSMagics.cd_force_quiet = True
561 _ip.config.OSMagics.cd_force_quiet = True
547 osmagics = osm.OSMagics(shell=_ip)
562 osmagics = osm.OSMagics(shell=_ip)
548
563
549 startdir = os.getcwd()
564 startdir = os.getcwd()
550 ipdir = os.path.realpath(_ip.ipython_dir)
565 ipdir = os.path.realpath(_ip.ipython_dir)
551
566
552 try:
567 try:
553 with tt.AssertNotPrints(ipdir):
568 with tt.AssertNotPrints(ipdir):
554 osmagics.cd('"%s"' % ipdir)
569 osmagics.cd('"%s"' % ipdir)
555 with tt.AssertNotPrints(startdir):
570 with tt.AssertNotPrints(startdir):
556 osmagics.cd('-')
571 osmagics.cd('-')
557 finally:
572 finally:
558 os.chdir(startdir)
573 os.chdir(startdir)
559
574
560
575
561 def test_xmode():
576 def test_xmode():
562 # Calling xmode three times should be a no-op
577 # Calling xmode three times should be a no-op
563 xmode = _ip.InteractiveTB.mode
578 xmode = _ip.InteractiveTB.mode
564 for i in range(4):
579 for i in range(4):
565 _ip.run_line_magic("xmode", "")
580 _ip.run_line_magic("xmode", "")
566 assert _ip.InteractiveTB.mode == xmode
581 assert _ip.InteractiveTB.mode == xmode
567
582
568 def test_reset_hard():
583 def test_reset_hard():
569 monitor = []
584 monitor = []
570 class A(object):
585 class A(object):
571 def __del__(self):
586 def __del__(self):
572 monitor.append(1)
587 monitor.append(1)
573 def __repr__(self):
588 def __repr__(self):
574 return "<A instance>"
589 return "<A instance>"
575
590
576 _ip.user_ns["a"] = A()
591 _ip.user_ns["a"] = A()
577 _ip.run_cell("a")
592 _ip.run_cell("a")
578
593
579 assert monitor == []
594 assert monitor == []
580 _ip.run_line_magic("reset", "-f")
595 _ip.run_line_magic("reset", "-f")
581 assert monitor == [1]
596 assert monitor == [1]
582
597
583 class TestXdel(tt.TempFileMixin):
598 class TestXdel(tt.TempFileMixin):
584 def test_xdel(self):
599 def test_xdel(self):
585 """Test that references from %run are cleared by xdel."""
600 """Test that references from %run are cleared by xdel."""
586 src = ("class A(object):\n"
601 src = ("class A(object):\n"
587 " monitor = []\n"
602 " monitor = []\n"
588 " def __del__(self):\n"
603 " def __del__(self):\n"
589 " self.monitor.append(1)\n"
604 " self.monitor.append(1)\n"
590 "a = A()\n")
605 "a = A()\n")
591 self.mktmp(src)
606 self.mktmp(src)
592 # %run creates some hidden references...
607 # %run creates some hidden references...
593 _ip.run_line_magic("run", "%s" % self.fname)
608 _ip.run_line_magic("run", "%s" % self.fname)
594 # ... as does the displayhook.
609 # ... as does the displayhook.
595 _ip.run_cell("a")
610 _ip.run_cell("a")
596
611
597 monitor = _ip.user_ns["A"].monitor
612 monitor = _ip.user_ns["A"].monitor
598 assert monitor == []
613 assert monitor == []
599
614
600 _ip.run_line_magic("xdel", "a")
615 _ip.run_line_magic("xdel", "a")
601
616
602 # Check that a's __del__ method has been called.
617 # Check that a's __del__ method has been called.
603 gc.collect(0)
618 gc.collect(0)
604 assert monitor == [1]
619 assert monitor == [1]
605
620
606 def doctest_who():
621 def doctest_who():
607 """doctest for %who
622 """doctest for %who
608
623
609 In [1]: %reset -sf
624 In [1]: %reset -sf
610
625
611 In [2]: alpha = 123
626 In [2]: alpha = 123
612
627
613 In [3]: beta = 'beta'
628 In [3]: beta = 'beta'
614
629
615 In [4]: %who int
630 In [4]: %who int
616 alpha
631 alpha
617
632
618 In [5]: %who str
633 In [5]: %who str
619 beta
634 beta
620
635
621 In [6]: %whos
636 In [6]: %whos
622 Variable Type Data/Info
637 Variable Type Data/Info
623 ----------------------------
638 ----------------------------
624 alpha int 123
639 alpha int 123
625 beta str beta
640 beta str beta
626
641
627 In [7]: %who_ls
642 In [7]: %who_ls
628 Out[7]: ['alpha', 'beta']
643 Out[7]: ['alpha', 'beta']
629 """
644 """
630
645
631 def test_whos():
646 def test_whos():
632 """Check that whos is protected against objects where repr() fails."""
647 """Check that whos is protected against objects where repr() fails."""
633 class A(object):
648 class A(object):
634 def __repr__(self):
649 def __repr__(self):
635 raise Exception()
650 raise Exception()
636 _ip.user_ns['a'] = A()
651 _ip.user_ns['a'] = A()
637 _ip.run_line_magic("whos", "")
652 _ip.run_line_magic("whos", "")
638
653
639 def doctest_precision():
654 def doctest_precision():
640 """doctest for %precision
655 """doctest for %precision
641
656
642 In [1]: f = get_ipython().display_formatter.formatters['text/plain']
657 In [1]: f = get_ipython().display_formatter.formatters['text/plain']
643
658
644 In [2]: %precision 5
659 In [2]: %precision 5
645 Out[2]: '%.5f'
660 Out[2]: '%.5f'
646
661
647 In [3]: f.float_format
662 In [3]: f.float_format
648 Out[3]: '%.5f'
663 Out[3]: '%.5f'
649
664
650 In [4]: %precision %e
665 In [4]: %precision %e
651 Out[4]: '%e'
666 Out[4]: '%e'
652
667
653 In [5]: f(3.1415927)
668 In [5]: f(3.1415927)
654 Out[5]: '3.141593e+00'
669 Out[5]: '3.141593e+00'
655 """
670 """
656
671
657 def test_debug_magic():
672 def test_debug_magic():
658 """Test debugging a small code with %debug
673 """Test debugging a small code with %debug
659
674
660 In [1]: with PdbTestInput(['c']):
675 In [1]: with PdbTestInput(['c']):
661 ...: %debug print("a b") #doctest: +ELLIPSIS
676 ...: %debug print("a b") #doctest: +ELLIPSIS
662 ...:
677 ...:
663 ...
678 ...
664 ipdb> c
679 ipdb> c
665 a b
680 a b
666 In [2]:
681 In [2]:
667 """
682 """
668
683
669 def test_psearch():
684 def test_psearch():
670 with tt.AssertPrints("dict.fromkeys"):
685 with tt.AssertPrints("dict.fromkeys"):
671 _ip.run_cell("dict.fr*?")
686 _ip.run_cell("dict.fr*?")
672 with tt.AssertPrints("Ο€.is_integer"):
687 with tt.AssertPrints("Ο€.is_integer"):
673 _ip.run_cell("Ο€ = 3.14;\nΟ€.is_integ*?")
688 _ip.run_cell("Ο€ = 3.14;\nΟ€.is_integ*?")
674
689
675 def test_timeit_shlex():
690 def test_timeit_shlex():
676 """test shlex issues with timeit (#1109)"""
691 """test shlex issues with timeit (#1109)"""
677 _ip.ex("def f(*a,**kw): pass")
692 _ip.ex("def f(*a,**kw): pass")
678 _ip.run_line_magic("timeit", '-n1 "this is a bug".count(" ")')
693 _ip.run_line_magic("timeit", '-n1 "this is a bug".count(" ")')
679 _ip.run_line_magic("timeit", '-r1 -n1 f(" ", 1)')
694 _ip.run_line_magic("timeit", '-r1 -n1 f(" ", 1)')
680 _ip.run_line_magic("timeit", '-r1 -n1 f(" ", 1, " ", 2, " ")')
695 _ip.run_line_magic("timeit", '-r1 -n1 f(" ", 1, " ", 2, " ")')
681 _ip.run_line_magic("timeit", '-r1 -n1 ("a " + "b")')
696 _ip.run_line_magic("timeit", '-r1 -n1 ("a " + "b")')
682 _ip.run_line_magic("timeit", '-r1 -n1 f("a " + "b")')
697 _ip.run_line_magic("timeit", '-r1 -n1 f("a " + "b")')
683 _ip.run_line_magic("timeit", '-r1 -n1 f("a " + "b ")')
698 _ip.run_line_magic("timeit", '-r1 -n1 f("a " + "b ")')
684
699
685
700
686 def test_timeit_special_syntax():
701 def test_timeit_special_syntax():
687 "Test %%timeit with IPython special syntax"
702 "Test %%timeit with IPython special syntax"
688 @register_line_magic
703 @register_line_magic
689 def lmagic(line):
704 def lmagic(line):
690 ip = get_ipython()
705 ip = get_ipython()
691 ip.user_ns['lmagic_out'] = line
706 ip.user_ns['lmagic_out'] = line
692
707
693 # line mode test
708 # line mode test
694 _ip.run_line_magic("timeit", "-n1 -r1 %lmagic my line")
709 _ip.run_line_magic("timeit", "-n1 -r1 %lmagic my line")
695 assert _ip.user_ns["lmagic_out"] == "my line"
710 assert _ip.user_ns["lmagic_out"] == "my line"
696 # cell mode test
711 # cell mode test
697 _ip.run_cell_magic("timeit", "-n1 -r1", "%lmagic my line2")
712 _ip.run_cell_magic("timeit", "-n1 -r1", "%lmagic my line2")
698 assert _ip.user_ns["lmagic_out"] == "my line2"
713 assert _ip.user_ns["lmagic_out"] == "my line2"
699
714
700
715
701 def test_timeit_return():
716 def test_timeit_return():
702 """
717 """
703 test whether timeit -o return object
718 test whether timeit -o return object
704 """
719 """
705
720
706 res = _ip.run_line_magic('timeit','-n10 -r10 -o 1')
721 res = _ip.run_line_magic('timeit','-n10 -r10 -o 1')
707 assert(res is not None)
722 assert(res is not None)
708
723
709 def test_timeit_quiet():
724 def test_timeit_quiet():
710 """
725 """
711 test quiet option of timeit magic
726 test quiet option of timeit magic
712 """
727 """
713 with tt.AssertNotPrints("loops"):
728 with tt.AssertNotPrints("loops"):
714 _ip.run_cell("%timeit -n1 -r1 -q 1")
729 _ip.run_cell("%timeit -n1 -r1 -q 1")
715
730
716 def test_timeit_return_quiet():
731 def test_timeit_return_quiet():
717 with tt.AssertNotPrints("loops"):
732 with tt.AssertNotPrints("loops"):
718 res = _ip.run_line_magic('timeit', '-n1 -r1 -q -o 1')
733 res = _ip.run_line_magic('timeit', '-n1 -r1 -q -o 1')
719 assert (res is not None)
734 assert (res is not None)
720
735
721 def test_timeit_invalid_return():
736 def test_timeit_invalid_return():
722 with pytest.raises(SyntaxError):
737 with pytest.raises(SyntaxError):
723 _ip.run_line_magic('timeit', 'return')
738 _ip.run_line_magic('timeit', 'return')
724
739
725 @dec.skipif(execution.profile is None)
740 @dec.skipif(execution.profile is None)
726 def test_prun_special_syntax():
741 def test_prun_special_syntax():
727 "Test %%prun with IPython special syntax"
742 "Test %%prun with IPython special syntax"
728 @register_line_magic
743 @register_line_magic
729 def lmagic(line):
744 def lmagic(line):
730 ip = get_ipython()
745 ip = get_ipython()
731 ip.user_ns['lmagic_out'] = line
746 ip.user_ns['lmagic_out'] = line
732
747
733 # line mode test
748 # line mode test
734 _ip.run_line_magic("prun", "-q %lmagic my line")
749 _ip.run_line_magic("prun", "-q %lmagic my line")
735 assert _ip.user_ns["lmagic_out"] == "my line"
750 assert _ip.user_ns["lmagic_out"] == "my line"
736 # cell mode test
751 # cell mode test
737 _ip.run_cell_magic("prun", "-q", "%lmagic my line2")
752 _ip.run_cell_magic("prun", "-q", "%lmagic my line2")
738 assert _ip.user_ns["lmagic_out"] == "my line2"
753 assert _ip.user_ns["lmagic_out"] == "my line2"
739
754
740
755
741 @dec.skipif(execution.profile is None)
756 @dec.skipif(execution.profile is None)
742 def test_prun_quotes():
757 def test_prun_quotes():
743 "Test that prun does not clobber string escapes (GH #1302)"
758 "Test that prun does not clobber string escapes (GH #1302)"
744 _ip.magic(r"prun -q x = '\t'")
759 _ip.magic(r"prun -q x = '\t'")
745 assert _ip.user_ns["x"] == "\t"
760 assert _ip.user_ns["x"] == "\t"
746
761
747
762
748 def test_extension():
763 def test_extension():
749 # Debugging information for failures of this test
764 # Debugging information for failures of this test
750 print('sys.path:')
765 print('sys.path:')
751 for p in sys.path:
766 for p in sys.path:
752 print(' ', p)
767 print(' ', p)
753 print('CWD', os.getcwd())
768 print('CWD', os.getcwd())
754
769
755 pytest.raises(ImportError, _ip.magic, "load_ext daft_extension")
770 pytest.raises(ImportError, _ip.magic, "load_ext daft_extension")
756 daft_path = os.path.join(os.path.dirname(__file__), "daft_extension")
771 daft_path = os.path.join(os.path.dirname(__file__), "daft_extension")
757 sys.path.insert(0, daft_path)
772 sys.path.insert(0, daft_path)
758 try:
773 try:
759 _ip.user_ns.pop('arq', None)
774 _ip.user_ns.pop('arq', None)
760 invalidate_caches() # Clear import caches
775 invalidate_caches() # Clear import caches
761 _ip.run_line_magic("load_ext", "daft_extension")
776 _ip.run_line_magic("load_ext", "daft_extension")
762 assert _ip.user_ns["arq"] == 185
777 assert _ip.user_ns["arq"] == 185
763 _ip.run_line_magic("unload_ext", "daft_extension")
778 _ip.run_line_magic("unload_ext", "daft_extension")
764 assert 'arq' not in _ip.user_ns
779 assert 'arq' not in _ip.user_ns
765 finally:
780 finally:
766 sys.path.remove(daft_path)
781 sys.path.remove(daft_path)
767
782
768
783
769 def test_notebook_export_json():
784 def test_notebook_export_json():
770 pytest.importorskip("nbformat")
785 pytest.importorskip("nbformat")
771 _ip = get_ipython()
786 _ip = get_ipython()
772 _ip.history_manager.reset() # Clear any existing history.
787 _ip.history_manager.reset() # Clear any existing history.
773 cmds = ["a=1", "def b():\n return a**2", "print('noΓ«l, Γ©tΓ©', b())"]
788 cmds = ["a=1", "def b():\n return a**2", "print('noΓ«l, Γ©tΓ©', b())"]
774 for i, cmd in enumerate(cmds, start=1):
789 for i, cmd in enumerate(cmds, start=1):
775 _ip.history_manager.store_inputs(i, cmd)
790 _ip.history_manager.store_inputs(i, cmd)
776 with TemporaryDirectory() as td:
791 with TemporaryDirectory() as td:
777 outfile = os.path.join(td, "nb.ipynb")
792 outfile = os.path.join(td, "nb.ipynb")
778 _ip.run_line_magic("notebook", "%s" % outfile)
793 _ip.run_line_magic("notebook", "%s" % outfile)
779
794
780
795
781 class TestEnv(TestCase):
796 class TestEnv(TestCase):
782
797
783 def test_env(self):
798 def test_env(self):
784 env = _ip.run_line_magic("env", "")
799 env = _ip.run_line_magic("env", "")
785 self.assertTrue(isinstance(env, dict))
800 self.assertTrue(isinstance(env, dict))
786
801
787 def test_env_secret(self):
802 def test_env_secret(self):
788 env = _ip.run_line_magic("env", "")
803 env = _ip.run_line_magic("env", "")
789 hidden = "<hidden>"
804 hidden = "<hidden>"
790 with mock.patch.dict(
805 with mock.patch.dict(
791 os.environ,
806 os.environ,
792 {
807 {
793 "API_KEY": "abc123",
808 "API_KEY": "abc123",
794 "SECRET_THING": "ssshhh",
809 "SECRET_THING": "ssshhh",
795 "JUPYTER_TOKEN": "",
810 "JUPYTER_TOKEN": "",
796 "VAR": "abc"
811 "VAR": "abc"
797 }
812 }
798 ):
813 ):
799 env = _ip.run_line_magic("env", "")
814 env = _ip.run_line_magic("env", "")
800 assert env["API_KEY"] == hidden
815 assert env["API_KEY"] == hidden
801 assert env["SECRET_THING"] == hidden
816 assert env["SECRET_THING"] == hidden
802 assert env["JUPYTER_TOKEN"] == hidden
817 assert env["JUPYTER_TOKEN"] == hidden
803 assert env["VAR"] == "abc"
818 assert env["VAR"] == "abc"
804
819
805 def test_env_get_set_simple(self):
820 def test_env_get_set_simple(self):
806 env = _ip.run_line_magic("env", "var val1")
821 env = _ip.run_line_magic("env", "var val1")
807 self.assertEqual(env, None)
822 self.assertEqual(env, None)
808 self.assertEqual(os.environ["var"], "val1")
823 self.assertEqual(os.environ["var"], "val1")
809 self.assertEqual(_ip.run_line_magic("env", "var"), "val1")
824 self.assertEqual(_ip.run_line_magic("env", "var"), "val1")
810 env = _ip.run_line_magic("env", "var=val2")
825 env = _ip.run_line_magic("env", "var=val2")
811 self.assertEqual(env, None)
826 self.assertEqual(env, None)
812 self.assertEqual(os.environ['var'], 'val2')
827 self.assertEqual(os.environ['var'], 'val2')
813
828
814 def test_env_get_set_complex(self):
829 def test_env_get_set_complex(self):
815 env = _ip.run_line_magic("env", "var 'val1 '' 'val2")
830 env = _ip.run_line_magic("env", "var 'val1 '' 'val2")
816 self.assertEqual(env, None)
831 self.assertEqual(env, None)
817 self.assertEqual(os.environ['var'], "'val1 '' 'val2")
832 self.assertEqual(os.environ['var'], "'val1 '' 'val2")
818 self.assertEqual(_ip.run_line_magic("env", "var"), "'val1 '' 'val2")
833 self.assertEqual(_ip.run_line_magic("env", "var"), "'val1 '' 'val2")
819 env = _ip.run_line_magic("env", 'var=val2 val3="val4')
834 env = _ip.run_line_magic("env", 'var=val2 val3="val4')
820 self.assertEqual(env, None)
835 self.assertEqual(env, None)
821 self.assertEqual(os.environ['var'], 'val2 val3="val4')
836 self.assertEqual(os.environ['var'], 'val2 val3="val4')
822
837
823 def test_env_set_bad_input(self):
838 def test_env_set_bad_input(self):
824 self.assertRaises(UsageError, lambda: _ip.run_line_magic("set_env", "var"))
839 self.assertRaises(UsageError, lambda: _ip.run_line_magic("set_env", "var"))
825
840
826 def test_env_set_whitespace(self):
841 def test_env_set_whitespace(self):
827 self.assertRaises(UsageError, lambda: _ip.run_line_magic("env", "var A=B"))
842 self.assertRaises(UsageError, lambda: _ip.run_line_magic("env", "var A=B"))
828
843
829
844
830 class CellMagicTestCase(TestCase):
845 class CellMagicTestCase(TestCase):
831
846
832 def check_ident(self, magic):
847 def check_ident(self, magic):
833 # Manually called, we get the result
848 # Manually called, we get the result
834 out = _ip.run_cell_magic(magic, "a", "b")
849 out = _ip.run_cell_magic(magic, "a", "b")
835 assert out == ("a", "b")
850 assert out == ("a", "b")
836 # Via run_cell, it goes into the user's namespace via displayhook
851 # Via run_cell, it goes into the user's namespace via displayhook
837 _ip.run_cell("%%" + magic + " c\nd\n")
852 _ip.run_cell("%%" + magic + " c\nd\n")
838 assert _ip.user_ns["_"] == ("c", "d\n")
853 assert _ip.user_ns["_"] == ("c", "d\n")
839
854
840 def test_cell_magic_func_deco(self):
855 def test_cell_magic_func_deco(self):
841 "Cell magic using simple decorator"
856 "Cell magic using simple decorator"
842 @register_cell_magic
857 @register_cell_magic
843 def cellm(line, cell):
858 def cellm(line, cell):
844 return line, cell
859 return line, cell
845
860
846 self.check_ident('cellm')
861 self.check_ident('cellm')
847
862
848 def test_cell_magic_reg(self):
863 def test_cell_magic_reg(self):
849 "Cell magic manually registered"
864 "Cell magic manually registered"
850 def cellm(line, cell):
865 def cellm(line, cell):
851 return line, cell
866 return line, cell
852
867
853 _ip.register_magic_function(cellm, 'cell', 'cellm2')
868 _ip.register_magic_function(cellm, 'cell', 'cellm2')
854 self.check_ident('cellm2')
869 self.check_ident('cellm2')
855
870
856 def test_cell_magic_class(self):
871 def test_cell_magic_class(self):
857 "Cell magics declared via a class"
872 "Cell magics declared via a class"
858 @magics_class
873 @magics_class
859 class MyMagics(Magics):
874 class MyMagics(Magics):
860
875
861 @cell_magic
876 @cell_magic
862 def cellm3(self, line, cell):
877 def cellm3(self, line, cell):
863 return line, cell
878 return line, cell
864
879
865 _ip.register_magics(MyMagics)
880 _ip.register_magics(MyMagics)
866 self.check_ident('cellm3')
881 self.check_ident('cellm3')
867
882
868 def test_cell_magic_class2(self):
883 def test_cell_magic_class2(self):
869 "Cell magics declared via a class, #2"
884 "Cell magics declared via a class, #2"
870 @magics_class
885 @magics_class
871 class MyMagics2(Magics):
886 class MyMagics2(Magics):
872
887
873 @cell_magic('cellm4')
888 @cell_magic('cellm4')
874 def cellm33(self, line, cell):
889 def cellm33(self, line, cell):
875 return line, cell
890 return line, cell
876
891
877 _ip.register_magics(MyMagics2)
892 _ip.register_magics(MyMagics2)
878 self.check_ident('cellm4')
893 self.check_ident('cellm4')
879 # Check that nothing is registered as 'cellm33'
894 # Check that nothing is registered as 'cellm33'
880 c33 = _ip.find_cell_magic('cellm33')
895 c33 = _ip.find_cell_magic('cellm33')
881 assert c33 == None
896 assert c33 == None
882
897
883 def test_file():
898 def test_file():
884 """Basic %%writefile"""
899 """Basic %%writefile"""
885 ip = get_ipython()
900 ip = get_ipython()
886 with TemporaryDirectory() as td:
901 with TemporaryDirectory() as td:
887 fname = os.path.join(td, "file1")
902 fname = os.path.join(td, "file1")
888 ip.run_cell_magic(
903 ip.run_cell_magic(
889 "writefile",
904 "writefile",
890 fname,
905 fname,
891 "\n".join(
906 "\n".join(
892 [
907 [
893 "line1",
908 "line1",
894 "line2",
909 "line2",
895 ]
910 ]
896 ),
911 ),
897 )
912 )
898 s = Path(fname).read_text(encoding="utf-8")
913 s = Path(fname).read_text(encoding="utf-8")
899 assert "line1\n" in s
914 assert "line1\n" in s
900 assert "line2" in s
915 assert "line2" in s
901
916
902
917
903 @dec.skip_win32
918 @dec.skip_win32
904 def test_file_single_quote():
919 def test_file_single_quote():
905 """Basic %%writefile with embedded single quotes"""
920 """Basic %%writefile with embedded single quotes"""
906 ip = get_ipython()
921 ip = get_ipython()
907 with TemporaryDirectory() as td:
922 with TemporaryDirectory() as td:
908 fname = os.path.join(td, "'file1'")
923 fname = os.path.join(td, "'file1'")
909 ip.run_cell_magic(
924 ip.run_cell_magic(
910 "writefile",
925 "writefile",
911 fname,
926 fname,
912 "\n".join(
927 "\n".join(
913 [
928 [
914 "line1",
929 "line1",
915 "line2",
930 "line2",
916 ]
931 ]
917 ),
932 ),
918 )
933 )
919 s = Path(fname).read_text(encoding="utf-8")
934 s = Path(fname).read_text(encoding="utf-8")
920 assert "line1\n" in s
935 assert "line1\n" in s
921 assert "line2" in s
936 assert "line2" in s
922
937
923
938
924 @dec.skip_win32
939 @dec.skip_win32
925 def test_file_double_quote():
940 def test_file_double_quote():
926 """Basic %%writefile with embedded double quotes"""
941 """Basic %%writefile with embedded double quotes"""
927 ip = get_ipython()
942 ip = get_ipython()
928 with TemporaryDirectory() as td:
943 with TemporaryDirectory() as td:
929 fname = os.path.join(td, '"file1"')
944 fname = os.path.join(td, '"file1"')
930 ip.run_cell_magic(
945 ip.run_cell_magic(
931 "writefile",
946 "writefile",
932 fname,
947 fname,
933 "\n".join(
948 "\n".join(
934 [
949 [
935 "line1",
950 "line1",
936 "line2",
951 "line2",
937 ]
952 ]
938 ),
953 ),
939 )
954 )
940 s = Path(fname).read_text(encoding="utf-8")
955 s = Path(fname).read_text(encoding="utf-8")
941 assert "line1\n" in s
956 assert "line1\n" in s
942 assert "line2" in s
957 assert "line2" in s
943
958
944
959
945 def test_file_var_expand():
960 def test_file_var_expand():
946 """%%writefile $filename"""
961 """%%writefile $filename"""
947 ip = get_ipython()
962 ip = get_ipython()
948 with TemporaryDirectory() as td:
963 with TemporaryDirectory() as td:
949 fname = os.path.join(td, "file1")
964 fname = os.path.join(td, "file1")
950 ip.user_ns["filename"] = fname
965 ip.user_ns["filename"] = fname
951 ip.run_cell_magic(
966 ip.run_cell_magic(
952 "writefile",
967 "writefile",
953 "$filename",
968 "$filename",
954 "\n".join(
969 "\n".join(
955 [
970 [
956 "line1",
971 "line1",
957 "line2",
972 "line2",
958 ]
973 ]
959 ),
974 ),
960 )
975 )
961 s = Path(fname).read_text(encoding="utf-8")
976 s = Path(fname).read_text(encoding="utf-8")
962 assert "line1\n" in s
977 assert "line1\n" in s
963 assert "line2" in s
978 assert "line2" in s
964
979
965
980
966 def test_file_unicode():
981 def test_file_unicode():
967 """%%writefile with unicode cell"""
982 """%%writefile with unicode cell"""
968 ip = get_ipython()
983 ip = get_ipython()
969 with TemporaryDirectory() as td:
984 with TemporaryDirectory() as td:
970 fname = os.path.join(td, 'file1')
985 fname = os.path.join(td, 'file1')
971 ip.run_cell_magic("writefile", fname, u'\n'.join([
986 ip.run_cell_magic("writefile", fname, u'\n'.join([
972 u'linΓ©1',
987 u'linΓ©1',
973 u'linΓ©2',
988 u'linΓ©2',
974 ]))
989 ]))
975 with io.open(fname, encoding='utf-8') as f:
990 with io.open(fname, encoding='utf-8') as f:
976 s = f.read()
991 s = f.read()
977 assert "linΓ©1\n" in s
992 assert "linΓ©1\n" in s
978 assert "linΓ©2" in s
993 assert "linΓ©2" in s
979
994
980
995
981 def test_file_amend():
996 def test_file_amend():
982 """%%writefile -a amends files"""
997 """%%writefile -a amends files"""
983 ip = get_ipython()
998 ip = get_ipython()
984 with TemporaryDirectory() as td:
999 with TemporaryDirectory() as td:
985 fname = os.path.join(td, "file2")
1000 fname = os.path.join(td, "file2")
986 ip.run_cell_magic(
1001 ip.run_cell_magic(
987 "writefile",
1002 "writefile",
988 fname,
1003 fname,
989 "\n".join(
1004 "\n".join(
990 [
1005 [
991 "line1",
1006 "line1",
992 "line2",
1007 "line2",
993 ]
1008 ]
994 ),
1009 ),
995 )
1010 )
996 ip.run_cell_magic(
1011 ip.run_cell_magic(
997 "writefile",
1012 "writefile",
998 "-a %s" % fname,
1013 "-a %s" % fname,
999 "\n".join(
1014 "\n".join(
1000 [
1015 [
1001 "line3",
1016 "line3",
1002 "line4",
1017 "line4",
1003 ]
1018 ]
1004 ),
1019 ),
1005 )
1020 )
1006 s = Path(fname).read_text(encoding="utf-8")
1021 s = Path(fname).read_text(encoding="utf-8")
1007 assert "line1\n" in s
1022 assert "line1\n" in s
1008 assert "line3\n" in s
1023 assert "line3\n" in s
1009
1024
1010
1025
1011 def test_file_spaces():
1026 def test_file_spaces():
1012 """%%file with spaces in filename"""
1027 """%%file with spaces in filename"""
1013 ip = get_ipython()
1028 ip = get_ipython()
1014 with TemporaryWorkingDirectory() as td:
1029 with TemporaryWorkingDirectory() as td:
1015 fname = "file name"
1030 fname = "file name"
1016 ip.run_cell_magic(
1031 ip.run_cell_magic(
1017 "file",
1032 "file",
1018 '"%s"' % fname,
1033 '"%s"' % fname,
1019 "\n".join(
1034 "\n".join(
1020 [
1035 [
1021 "line1",
1036 "line1",
1022 "line2",
1037 "line2",
1023 ]
1038 ]
1024 ),
1039 ),
1025 )
1040 )
1026 s = Path(fname).read_text(encoding="utf-8")
1041 s = Path(fname).read_text(encoding="utf-8")
1027 assert "line1\n" in s
1042 assert "line1\n" in s
1028 assert "line2" in s
1043 assert "line2" in s
1029
1044
1030
1045
1031 def test_script_config():
1046 def test_script_config():
1032 ip = get_ipython()
1047 ip = get_ipython()
1033 ip.config.ScriptMagics.script_magics = ['whoda']
1048 ip.config.ScriptMagics.script_magics = ['whoda']
1034 sm = script.ScriptMagics(shell=ip)
1049 sm = script.ScriptMagics(shell=ip)
1035 assert "whoda" in sm.magics["cell"]
1050 assert "whoda" in sm.magics["cell"]
1036
1051
1037
1052
1038 def test_script_out():
1053 def test_script_out():
1039 ip = get_ipython()
1054 ip = get_ipython()
1040 ip.run_cell_magic("script", f"--out output {sys.executable}", "print('hi')")
1055 ip.run_cell_magic("script", f"--out output {sys.executable}", "print('hi')")
1041 assert ip.user_ns["output"].strip() == "hi"
1056 assert ip.user_ns["output"].strip() == "hi"
1042
1057
1043
1058
1044 def test_script_err():
1059 def test_script_err():
1045 ip = get_ipython()
1060 ip = get_ipython()
1046 ip.run_cell_magic(
1061 ip.run_cell_magic(
1047 "script",
1062 "script",
1048 f"--err error {sys.executable}",
1063 f"--err error {sys.executable}",
1049 "import sys; print('hello', file=sys.stderr)",
1064 "import sys; print('hello', file=sys.stderr)",
1050 )
1065 )
1051 assert ip.user_ns["error"].strip() == "hello"
1066 assert ip.user_ns["error"].strip() == "hello"
1052
1067
1053
1068
1054 def test_script_out_err():
1069 def test_script_out_err():
1055
1070
1056 ip = get_ipython()
1071 ip = get_ipython()
1057 ip.run_cell_magic(
1072 ip.run_cell_magic(
1058 "script",
1073 "script",
1059 f"--out output --err error {sys.executable}",
1074 f"--out output --err error {sys.executable}",
1060 "\n".join(
1075 "\n".join(
1061 [
1076 [
1062 "import sys",
1077 "import sys",
1063 "print('hi')",
1078 "print('hi')",
1064 "print('hello', file=sys.stderr)",
1079 "print('hello', file=sys.stderr)",
1065 ]
1080 ]
1066 ),
1081 ),
1067 )
1082 )
1068 assert ip.user_ns["output"].strip() == "hi"
1083 assert ip.user_ns["output"].strip() == "hi"
1069 assert ip.user_ns["error"].strip() == "hello"
1084 assert ip.user_ns["error"].strip() == "hello"
1070
1085
1071
1086
1072 async def test_script_bg_out():
1087 async def test_script_bg_out():
1073 ip = get_ipython()
1088 ip = get_ipython()
1074 ip.run_cell_magic("script", f"--bg --out output {sys.executable}", "print('hi')")
1089 ip.run_cell_magic("script", f"--bg --out output {sys.executable}", "print('hi')")
1075 assert (await ip.user_ns["output"].read()).strip() == b"hi"
1090 assert (await ip.user_ns["output"].read()).strip() == b"hi"
1076 assert ip.user_ns["output"].at_eof()
1091 assert ip.user_ns["output"].at_eof()
1077
1092
1078
1093
1079 async def test_script_bg_err():
1094 async def test_script_bg_err():
1080 ip = get_ipython()
1095 ip = get_ipython()
1081 ip.run_cell_magic(
1096 ip.run_cell_magic(
1082 "script",
1097 "script",
1083 f"--bg --err error {sys.executable}",
1098 f"--bg --err error {sys.executable}",
1084 "import sys; print('hello', file=sys.stderr)",
1099 "import sys; print('hello', file=sys.stderr)",
1085 )
1100 )
1086 assert (await ip.user_ns["error"].read()).strip() == b"hello"
1101 assert (await ip.user_ns["error"].read()).strip() == b"hello"
1087 assert ip.user_ns["error"].at_eof()
1102 assert ip.user_ns["error"].at_eof()
1088
1103
1089
1104
1090 async def test_script_bg_out_err():
1105 async def test_script_bg_out_err():
1091 ip = get_ipython()
1106 ip = get_ipython()
1092 ip.run_cell_magic(
1107 ip.run_cell_magic(
1093 "script",
1108 "script",
1094 f"--bg --out output --err error {sys.executable}",
1109 f"--bg --out output --err error {sys.executable}",
1095 "\n".join(
1110 "\n".join(
1096 [
1111 [
1097 "import sys",
1112 "import sys",
1098 "print('hi')",
1113 "print('hi')",
1099 "print('hello', file=sys.stderr)",
1114 "print('hello', file=sys.stderr)",
1100 ]
1115 ]
1101 ),
1116 ),
1102 )
1117 )
1103 assert (await ip.user_ns["output"].read()).strip() == b"hi"
1118 assert (await ip.user_ns["output"].read()).strip() == b"hi"
1104 assert (await ip.user_ns["error"].read()).strip() == b"hello"
1119 assert (await ip.user_ns["error"].read()).strip() == b"hello"
1105 assert ip.user_ns["output"].at_eof()
1120 assert ip.user_ns["output"].at_eof()
1106 assert ip.user_ns["error"].at_eof()
1121 assert ip.user_ns["error"].at_eof()
1107
1122
1108
1123
1109 async def test_script_bg_proc():
1124 async def test_script_bg_proc():
1110 ip = get_ipython()
1125 ip = get_ipython()
1111 ip.run_cell_magic(
1126 ip.run_cell_magic(
1112 "script",
1127 "script",
1113 f"--bg --out output --proc p {sys.executable}",
1128 f"--bg --out output --proc p {sys.executable}",
1114 "\n".join(
1129 "\n".join(
1115 [
1130 [
1116 "import sys",
1131 "import sys",
1117 "print('hi')",
1132 "print('hi')",
1118 "print('hello', file=sys.stderr)",
1133 "print('hello', file=sys.stderr)",
1119 ]
1134 ]
1120 ),
1135 ),
1121 )
1136 )
1122 p = ip.user_ns["p"]
1137 p = ip.user_ns["p"]
1123 await p.wait()
1138 await p.wait()
1124 assert p.returncode == 0
1139 assert p.returncode == 0
1125 assert (await p.stdout.read()).strip() == b"hi"
1140 assert (await p.stdout.read()).strip() == b"hi"
1126 # not captured, so empty
1141 # not captured, so empty
1127 assert (await p.stderr.read()) == b""
1142 assert (await p.stderr.read()) == b""
1128 assert p.stdout.at_eof()
1143 assert p.stdout.at_eof()
1129 assert p.stderr.at_eof()
1144 assert p.stderr.at_eof()
1130
1145
1131
1146
1132 def test_script_defaults():
1147 def test_script_defaults():
1133 ip = get_ipython()
1148 ip = get_ipython()
1134 for cmd in ['sh', 'bash', 'perl', 'ruby']:
1149 for cmd in ['sh', 'bash', 'perl', 'ruby']:
1135 try:
1150 try:
1136 find_cmd(cmd)
1151 find_cmd(cmd)
1137 except Exception:
1152 except Exception:
1138 pass
1153 pass
1139 else:
1154 else:
1140 assert cmd in ip.magics_manager.magics["cell"]
1155 assert cmd in ip.magics_manager.magics["cell"]
1141
1156
1142
1157
1143 @magics_class
1158 @magics_class
1144 class FooFoo(Magics):
1159 class FooFoo(Magics):
1145 """class with both %foo and %%foo magics"""
1160 """class with both %foo and %%foo magics"""
1146 @line_magic('foo')
1161 @line_magic('foo')
1147 def line_foo(self, line):
1162 def line_foo(self, line):
1148 "I am line foo"
1163 "I am line foo"
1149 pass
1164 pass
1150
1165
1151 @cell_magic("foo")
1166 @cell_magic("foo")
1152 def cell_foo(self, line, cell):
1167 def cell_foo(self, line, cell):
1153 "I am cell foo, not line foo"
1168 "I am cell foo, not line foo"
1154 pass
1169 pass
1155
1170
1156 def test_line_cell_info():
1171 def test_line_cell_info():
1157 """%%foo and %foo magics are distinguishable to inspect"""
1172 """%%foo and %foo magics are distinguishable to inspect"""
1158 ip = get_ipython()
1173 ip = get_ipython()
1159 ip.magics_manager.register(FooFoo)
1174 ip.magics_manager.register(FooFoo)
1160 oinfo = ip.object_inspect("foo")
1175 oinfo = ip.object_inspect("foo")
1161 assert oinfo["found"] is True
1176 assert oinfo["found"] is True
1162 assert oinfo["ismagic"] is True
1177 assert oinfo["ismagic"] is True
1163
1178
1164 oinfo = ip.object_inspect("%%foo")
1179 oinfo = ip.object_inspect("%%foo")
1165 assert oinfo["found"] is True
1180 assert oinfo["found"] is True
1166 assert oinfo["ismagic"] is True
1181 assert oinfo["ismagic"] is True
1167 assert oinfo["docstring"] == FooFoo.cell_foo.__doc__
1182 assert oinfo["docstring"] == FooFoo.cell_foo.__doc__
1168
1183
1169 oinfo = ip.object_inspect("%foo")
1184 oinfo = ip.object_inspect("%foo")
1170 assert oinfo["found"] is True
1185 assert oinfo["found"] is True
1171 assert oinfo["ismagic"] is True
1186 assert oinfo["ismagic"] is True
1172 assert oinfo["docstring"] == FooFoo.line_foo.__doc__
1187 assert oinfo["docstring"] == FooFoo.line_foo.__doc__
1173
1188
1174
1189
1175 def test_multiple_magics():
1190 def test_multiple_magics():
1176 ip = get_ipython()
1191 ip = get_ipython()
1177 foo1 = FooFoo(ip)
1192 foo1 = FooFoo(ip)
1178 foo2 = FooFoo(ip)
1193 foo2 = FooFoo(ip)
1179 mm = ip.magics_manager
1194 mm = ip.magics_manager
1180 mm.register(foo1)
1195 mm.register(foo1)
1181 assert mm.magics["line"]["foo"].__self__ is foo1
1196 assert mm.magics["line"]["foo"].__self__ is foo1
1182 mm.register(foo2)
1197 mm.register(foo2)
1183 assert mm.magics["line"]["foo"].__self__ is foo2
1198 assert mm.magics["line"]["foo"].__self__ is foo2
1184
1199
1185
1200
1186 def test_alias_magic():
1201 def test_alias_magic():
1187 """Test %alias_magic."""
1202 """Test %alias_magic."""
1188 ip = get_ipython()
1203 ip = get_ipython()
1189 mm = ip.magics_manager
1204 mm = ip.magics_manager
1190
1205
1191 # Basic operation: both cell and line magics are created, if possible.
1206 # Basic operation: both cell and line magics are created, if possible.
1192 ip.run_line_magic("alias_magic", "timeit_alias timeit")
1207 ip.run_line_magic("alias_magic", "timeit_alias timeit")
1193 assert "timeit_alias" in mm.magics["line"]
1208 assert "timeit_alias" in mm.magics["line"]
1194 assert "timeit_alias" in mm.magics["cell"]
1209 assert "timeit_alias" in mm.magics["cell"]
1195
1210
1196 # --cell is specified, line magic not created.
1211 # --cell is specified, line magic not created.
1197 ip.run_line_magic("alias_magic", "--cell timeit_cell_alias timeit")
1212 ip.run_line_magic("alias_magic", "--cell timeit_cell_alias timeit")
1198 assert "timeit_cell_alias" not in mm.magics["line"]
1213 assert "timeit_cell_alias" not in mm.magics["line"]
1199 assert "timeit_cell_alias" in mm.magics["cell"]
1214 assert "timeit_cell_alias" in mm.magics["cell"]
1200
1215
1201 # Test that line alias is created successfully.
1216 # Test that line alias is created successfully.
1202 ip.run_line_magic("alias_magic", "--line env_alias env")
1217 ip.run_line_magic("alias_magic", "--line env_alias env")
1203 assert ip.run_line_magic("env", "") == ip.run_line_magic("env_alias", "")
1218 assert ip.run_line_magic("env", "") == ip.run_line_magic("env_alias", "")
1204
1219
1205 # Test that line alias with parameters passed in is created successfully.
1220 # Test that line alias with parameters passed in is created successfully.
1206 ip.run_line_magic(
1221 ip.run_line_magic(
1207 "alias_magic", "--line history_alias history --params " + shlex.quote("3")
1222 "alias_magic", "--line history_alias history --params " + shlex.quote("3")
1208 )
1223 )
1209 assert "history_alias" in mm.magics["line"]
1224 assert "history_alias" in mm.magics["line"]
1210
1225
1211
1226
1212 def test_save():
1227 def test_save():
1213 """Test %save."""
1228 """Test %save."""
1214 ip = get_ipython()
1229 ip = get_ipython()
1215 ip.history_manager.reset() # Clear any existing history.
1230 ip.history_manager.reset() # Clear any existing history.
1216 cmds = ["a=1", "def b():\n return a**2", "print(a, b())"]
1231 cmds = ["a=1", "def b():\n return a**2", "print(a, b())"]
1217 for i, cmd in enumerate(cmds, start=1):
1232 for i, cmd in enumerate(cmds, start=1):
1218 ip.history_manager.store_inputs(i, cmd)
1233 ip.history_manager.store_inputs(i, cmd)
1219 with TemporaryDirectory() as tmpdir:
1234 with TemporaryDirectory() as tmpdir:
1220 file = os.path.join(tmpdir, "testsave.py")
1235 file = os.path.join(tmpdir, "testsave.py")
1221 ip.run_line_magic("save", "%s 1-10" % file)
1236 ip.run_line_magic("save", "%s 1-10" % file)
1222 content = Path(file).read_text(encoding="utf-8")
1237 content = Path(file).read_text(encoding="utf-8")
1223 assert content.count(cmds[0]) == 1
1238 assert content.count(cmds[0]) == 1
1224 assert "coding: utf-8" in content
1239 assert "coding: utf-8" in content
1225 ip.run_line_magic("save", "-a %s 1-10" % file)
1240 ip.run_line_magic("save", "-a %s 1-10" % file)
1226 content = Path(file).read_text(encoding="utf-8")
1241 content = Path(file).read_text(encoding="utf-8")
1227 assert content.count(cmds[0]) == 2
1242 assert content.count(cmds[0]) == 2
1228 assert "coding: utf-8" in content
1243 assert "coding: utf-8" in content
1229
1244
1230
1245
1231 def test_save_with_no_args():
1246 def test_save_with_no_args():
1232 ip = get_ipython()
1247 ip = get_ipython()
1233 ip.history_manager.reset() # Clear any existing history.
1248 ip.history_manager.reset() # Clear any existing history.
1234 cmds = ["a=1", "def b():\n return a**2", "print(a, b())", "%save"]
1249 cmds = ["a=1", "def b():\n return a**2", "print(a, b())", "%save"]
1235 for i, cmd in enumerate(cmds, start=1):
1250 for i, cmd in enumerate(cmds, start=1):
1236 ip.history_manager.store_inputs(i, cmd)
1251 ip.history_manager.store_inputs(i, cmd)
1237
1252
1238 with TemporaryDirectory() as tmpdir:
1253 with TemporaryDirectory() as tmpdir:
1239 path = os.path.join(tmpdir, "testsave.py")
1254 path = os.path.join(tmpdir, "testsave.py")
1240 ip.run_line_magic("save", path)
1255 ip.run_line_magic("save", path)
1241 content = Path(path).read_text(encoding="utf-8")
1256 content = Path(path).read_text(encoding="utf-8")
1242 expected_content = dedent(
1257 expected_content = dedent(
1243 """\
1258 """\
1244 # coding: utf-8
1259 # coding: utf-8
1245 a=1
1260 a=1
1246 def b():
1261 def b():
1247 return a**2
1262 return a**2
1248 print(a, b())
1263 print(a, b())
1249 """
1264 """
1250 )
1265 )
1251 assert content == expected_content
1266 assert content == expected_content
1252
1267
1253
1268
1254 def test_store():
1269 def test_store():
1255 """Test %store."""
1270 """Test %store."""
1256 ip = get_ipython()
1271 ip = get_ipython()
1257 ip.run_line_magic('load_ext', 'storemagic')
1272 ip.run_line_magic('load_ext', 'storemagic')
1258
1273
1259 # make sure the storage is empty
1274 # make sure the storage is empty
1260 ip.run_line_magic("store", "-z")
1275 ip.run_line_magic("store", "-z")
1261 ip.user_ns["var"] = 42
1276 ip.user_ns["var"] = 42
1262 ip.run_line_magic("store", "var")
1277 ip.run_line_magic("store", "var")
1263 ip.user_ns["var"] = 39
1278 ip.user_ns["var"] = 39
1264 ip.run_line_magic("store", "-r")
1279 ip.run_line_magic("store", "-r")
1265 assert ip.user_ns["var"] == 42
1280 assert ip.user_ns["var"] == 42
1266
1281
1267 ip.run_line_magic("store", "-d var")
1282 ip.run_line_magic("store", "-d var")
1268 ip.user_ns["var"] = 39
1283 ip.user_ns["var"] = 39
1269 ip.run_line_magic("store", "-r")
1284 ip.run_line_magic("store", "-r")
1270 assert ip.user_ns["var"] == 39
1285 assert ip.user_ns["var"] == 39
1271
1286
1272
1287
1273 def _run_edit_test(arg_s, exp_filename=None,
1288 def _run_edit_test(arg_s, exp_filename=None,
1274 exp_lineno=-1,
1289 exp_lineno=-1,
1275 exp_contents=None,
1290 exp_contents=None,
1276 exp_is_temp=None):
1291 exp_is_temp=None):
1277 ip = get_ipython()
1292 ip = get_ipython()
1278 M = code.CodeMagics(ip)
1293 M = code.CodeMagics(ip)
1279 last_call = ['','']
1294 last_call = ['','']
1280 opts,args = M.parse_options(arg_s,'prxn:')
1295 opts,args = M.parse_options(arg_s,'prxn:')
1281 filename, lineno, is_temp = M._find_edit_target(ip, args, opts, last_call)
1296 filename, lineno, is_temp = M._find_edit_target(ip, args, opts, last_call)
1282
1297
1283 if exp_filename is not None:
1298 if exp_filename is not None:
1284 assert exp_filename == filename
1299 assert exp_filename == filename
1285 if exp_contents is not None:
1300 if exp_contents is not None:
1286 with io.open(filename, 'r', encoding='utf-8') as f:
1301 with io.open(filename, 'r', encoding='utf-8') as f:
1287 contents = f.read()
1302 contents = f.read()
1288 assert exp_contents == contents
1303 assert exp_contents == contents
1289 if exp_lineno != -1:
1304 if exp_lineno != -1:
1290 assert exp_lineno == lineno
1305 assert exp_lineno == lineno
1291 if exp_is_temp is not None:
1306 if exp_is_temp is not None:
1292 assert exp_is_temp == is_temp
1307 assert exp_is_temp == is_temp
1293
1308
1294
1309
1295 def test_edit_interactive():
1310 def test_edit_interactive():
1296 """%edit on interactively defined objects"""
1311 """%edit on interactively defined objects"""
1297 ip = get_ipython()
1312 ip = get_ipython()
1298 n = ip.execution_count
1313 n = ip.execution_count
1299 ip.run_cell("def foo(): return 1", store_history=True)
1314 ip.run_cell("def foo(): return 1", store_history=True)
1300
1315
1301 with pytest.raises(code.InteractivelyDefined) as e:
1316 with pytest.raises(code.InteractivelyDefined) as e:
1302 _run_edit_test("foo")
1317 _run_edit_test("foo")
1303 assert e.value.index == n
1318 assert e.value.index == n
1304
1319
1305
1320
1306 def test_edit_cell():
1321 def test_edit_cell():
1307 """%edit [cell id]"""
1322 """%edit [cell id]"""
1308 ip = get_ipython()
1323 ip = get_ipython()
1309
1324
1310 ip.run_cell("def foo(): return 1", store_history=True)
1325 ip.run_cell("def foo(): return 1", store_history=True)
1311
1326
1312 # test
1327 # test
1313 _run_edit_test("1", exp_contents=ip.user_ns['In'][1], exp_is_temp=True)
1328 _run_edit_test("1", exp_contents=ip.user_ns['In'][1], exp_is_temp=True)
1314
1329
1315 def test_edit_fname():
1330 def test_edit_fname():
1316 """%edit file"""
1331 """%edit file"""
1317 # test
1332 # test
1318 _run_edit_test("test file.py", exp_filename="test file.py")
1333 _run_edit_test("test file.py", exp_filename="test file.py")
1319
1334
1320 def test_bookmark():
1335 def test_bookmark():
1321 ip = get_ipython()
1336 ip = get_ipython()
1322 ip.run_line_magic('bookmark', 'bmname')
1337 ip.run_line_magic('bookmark', 'bmname')
1323 with tt.AssertPrints('bmname'):
1338 with tt.AssertPrints('bmname'):
1324 ip.run_line_magic('bookmark', '-l')
1339 ip.run_line_magic('bookmark', '-l')
1325 ip.run_line_magic('bookmark', '-d bmname')
1340 ip.run_line_magic('bookmark', '-d bmname')
1326
1341
1327 def test_ls_magic():
1342 def test_ls_magic():
1328 ip = get_ipython()
1343 ip = get_ipython()
1329 json_formatter = ip.display_formatter.formatters['application/json']
1344 json_formatter = ip.display_formatter.formatters['application/json']
1330 json_formatter.enabled = True
1345 json_formatter.enabled = True
1331 lsmagic = ip.run_line_magic("lsmagic", "")
1346 lsmagic = ip.run_line_magic("lsmagic", "")
1332 with warnings.catch_warnings(record=True) as w:
1347 with warnings.catch_warnings(record=True) as w:
1333 j = json_formatter(lsmagic)
1348 j = json_formatter(lsmagic)
1334 assert sorted(j) == ["cell", "line"]
1349 assert sorted(j) == ["cell", "line"]
1335 assert w == [] # no warnings
1350 assert w == [] # no warnings
1336
1351
1337
1352
1338 def test_strip_initial_indent():
1353 def test_strip_initial_indent():
1339 def sii(s):
1354 def sii(s):
1340 lines = s.splitlines()
1355 lines = s.splitlines()
1341 return '\n'.join(code.strip_initial_indent(lines))
1356 return '\n'.join(code.strip_initial_indent(lines))
1342
1357
1343 assert sii(" a = 1\nb = 2") == "a = 1\nb = 2"
1358 assert sii(" a = 1\nb = 2") == "a = 1\nb = 2"
1344 assert sii(" a\n b\nc") == "a\n b\nc"
1359 assert sii(" a\n b\nc") == "a\n b\nc"
1345 assert sii("a\n b") == "a\n b"
1360 assert sii("a\n b") == "a\n b"
1346
1361
1347 def test_logging_magic_quiet_from_arg():
1362 def test_logging_magic_quiet_from_arg():
1348 _ip.config.LoggingMagics.quiet = False
1363 _ip.config.LoggingMagics.quiet = False
1349 lm = logging.LoggingMagics(shell=_ip)
1364 lm = logging.LoggingMagics(shell=_ip)
1350 with TemporaryDirectory() as td:
1365 with TemporaryDirectory() as td:
1351 try:
1366 try:
1352 with tt.AssertNotPrints(re.compile("Activating.*")):
1367 with tt.AssertNotPrints(re.compile("Activating.*")):
1353 lm.logstart('-q {}'.format(
1368 lm.logstart('-q {}'.format(
1354 os.path.join(td, "quiet_from_arg.log")))
1369 os.path.join(td, "quiet_from_arg.log")))
1355 finally:
1370 finally:
1356 _ip.logger.logstop()
1371 _ip.logger.logstop()
1357
1372
1358 def test_logging_magic_quiet_from_config():
1373 def test_logging_magic_quiet_from_config():
1359 _ip.config.LoggingMagics.quiet = True
1374 _ip.config.LoggingMagics.quiet = True
1360 lm = logging.LoggingMagics(shell=_ip)
1375 lm = logging.LoggingMagics(shell=_ip)
1361 with TemporaryDirectory() as td:
1376 with TemporaryDirectory() as td:
1362 try:
1377 try:
1363 with tt.AssertNotPrints(re.compile("Activating.*")):
1378 with tt.AssertNotPrints(re.compile("Activating.*")):
1364 lm.logstart(os.path.join(td, "quiet_from_config.log"))
1379 lm.logstart(os.path.join(td, "quiet_from_config.log"))
1365 finally:
1380 finally:
1366 _ip.logger.logstop()
1381 _ip.logger.logstop()
1367
1382
1368
1383
1369 def test_logging_magic_not_quiet():
1384 def test_logging_magic_not_quiet():
1370 _ip.config.LoggingMagics.quiet = False
1385 _ip.config.LoggingMagics.quiet = False
1371 lm = logging.LoggingMagics(shell=_ip)
1386 lm = logging.LoggingMagics(shell=_ip)
1372 with TemporaryDirectory() as td:
1387 with TemporaryDirectory() as td:
1373 try:
1388 try:
1374 with tt.AssertPrints(re.compile("Activating.*")):
1389 with tt.AssertPrints(re.compile("Activating.*")):
1375 lm.logstart(os.path.join(td, "not_quiet.log"))
1390 lm.logstart(os.path.join(td, "not_quiet.log"))
1376 finally:
1391 finally:
1377 _ip.logger.logstop()
1392 _ip.logger.logstop()
1378
1393
1379
1394
1380 def test_time_no_var_expand():
1395 def test_time_no_var_expand():
1381 _ip.user_ns["a"] = 5
1396 _ip.user_ns["a"] = 5
1382 _ip.user_ns["b"] = []
1397 _ip.user_ns["b"] = []
1383 _ip.run_line_magic("time", 'b.append("{a}")')
1398 _ip.run_line_magic("time", 'b.append("{a}")')
1384 assert _ip.user_ns["b"] == ["{a}"]
1399 assert _ip.user_ns["b"] == ["{a}"]
1385
1400
1386
1401
1387 # this is slow, put at the end for local testing.
1402 # this is slow, put at the end for local testing.
1388 def test_timeit_arguments():
1403 def test_timeit_arguments():
1389 "Test valid timeit arguments, should not cause SyntaxError (GH #1269)"
1404 "Test valid timeit arguments, should not cause SyntaxError (GH #1269)"
1390 _ip.run_line_magic("timeit", "-n1 -r1 a=('#')")
1405 _ip.run_line_magic("timeit", "-n1 -r1 a=('#')")
1391
1406
1392
1407
1393 MINIMAL_LAZY_MAGIC = """
1408 MINIMAL_LAZY_MAGIC = """
1394 from IPython.core.magic import (
1409 from IPython.core.magic import (
1395 Magics,
1410 Magics,
1396 magics_class,
1411 magics_class,
1397 line_magic,
1412 line_magic,
1398 cell_magic,
1413 cell_magic,
1399 )
1414 )
1400
1415
1401
1416
1402 @magics_class
1417 @magics_class
1403 class LazyMagics(Magics):
1418 class LazyMagics(Magics):
1404 @line_magic
1419 @line_magic
1405 def lazy_line(self, line):
1420 def lazy_line(self, line):
1406 print("Lazy Line")
1421 print("Lazy Line")
1407
1422
1408 @cell_magic
1423 @cell_magic
1409 def lazy_cell(self, line, cell):
1424 def lazy_cell(self, line, cell):
1410 print("Lazy Cell")
1425 print("Lazy Cell")
1411
1426
1412
1427
1413 def load_ipython_extension(ipython):
1428 def load_ipython_extension(ipython):
1414 ipython.register_magics(LazyMagics)
1429 ipython.register_magics(LazyMagics)
1415 """
1430 """
1416
1431
1417
1432
1418 def test_lazy_magics():
1433 def test_lazy_magics():
1419 with pytest.raises(UsageError):
1434 with pytest.raises(UsageError):
1420 ip.run_line_magic("lazy_line", "")
1435 ip.run_line_magic("lazy_line", "")
1421
1436
1422 startdir = os.getcwd()
1437 startdir = os.getcwd()
1423
1438
1424 with TemporaryDirectory() as tmpdir:
1439 with TemporaryDirectory() as tmpdir:
1425 with prepended_to_syspath(tmpdir):
1440 with prepended_to_syspath(tmpdir):
1426 ptempdir = Path(tmpdir)
1441 ptempdir = Path(tmpdir)
1427 tf = ptempdir / "lazy_magic_module.py"
1442 tf = ptempdir / "lazy_magic_module.py"
1428 tf.write_text(MINIMAL_LAZY_MAGIC)
1443 tf.write_text(MINIMAL_LAZY_MAGIC)
1429 ip.magics_manager.register_lazy("lazy_line", Path(tf.name).name[:-3])
1444 ip.magics_manager.register_lazy("lazy_line", Path(tf.name).name[:-3])
1430 with tt.AssertPrints("Lazy Line"):
1445 with tt.AssertPrints("Lazy Line"):
1431 ip.run_line_magic("lazy_line", "")
1446 ip.run_line_magic("lazy_line", "")
1432
1447
1433
1448
1434 TEST_MODULE = """
1449 TEST_MODULE = """
1435 print('Loaded my_tmp')
1450 print('Loaded my_tmp')
1436 if __name__ == "__main__":
1451 if __name__ == "__main__":
1437 print('I just ran a script')
1452 print('I just ran a script')
1438 """
1453 """
1439
1454
1440 def test_run_module_from_import_hook():
1455 def test_run_module_from_import_hook():
1441 "Test that a module can be loaded via an import hook"
1456 "Test that a module can be loaded via an import hook"
1442 with TemporaryDirectory() as tmpdir:
1457 with TemporaryDirectory() as tmpdir:
1443 fullpath = os.path.join(tmpdir, "my_tmp.py")
1458 fullpath = os.path.join(tmpdir, "my_tmp.py")
1444 Path(fullpath).write_text(TEST_MODULE, encoding="utf-8")
1459 Path(fullpath).write_text(TEST_MODULE, encoding="utf-8")
1445
1460
1446 import importlib.abc
1461 import importlib.abc
1447 import importlib.util
1462 import importlib.util
1448
1463
1449 class MyTempImporter(importlib.abc.MetaPathFinder, importlib.abc.SourceLoader):
1464 class MyTempImporter(importlib.abc.MetaPathFinder, importlib.abc.SourceLoader):
1450 def find_spec(self, fullname, path, target=None):
1465 def find_spec(self, fullname, path, target=None):
1451 if fullname == "my_tmp":
1466 if fullname == "my_tmp":
1452 return importlib.util.spec_from_loader(fullname, self)
1467 return importlib.util.spec_from_loader(fullname, self)
1453
1468
1454 def get_filename(self, fullname):
1469 def get_filename(self, fullname):
1455 assert fullname == "my_tmp"
1470 assert fullname == "my_tmp"
1456 return fullpath
1471 return fullpath
1457
1472
1458 def get_data(self, path):
1473 def get_data(self, path):
1459 assert Path(path).samefile(fullpath)
1474 assert Path(path).samefile(fullpath)
1460 return Path(fullpath).read_text(encoding="utf-8")
1475 return Path(fullpath).read_text(encoding="utf-8")
1461
1476
1462 sys.meta_path.insert(0, MyTempImporter())
1477 sys.meta_path.insert(0, MyTempImporter())
1463
1478
1464 with capture_output() as captured:
1479 with capture_output() as captured:
1465 _ip.run_line_magic("run", "-m my_tmp")
1480 _ip.run_line_magic("run", "-m my_tmp")
1466 _ip.run_cell("import my_tmp")
1481 _ip.run_cell("import my_tmp")
1467
1482
1468 output = "Loaded my_tmp\nI just ran a script\nLoaded my_tmp\n"
1483 output = "Loaded my_tmp\nI just ran a script\nLoaded my_tmp\n"
1469 assert output == captured.stdout
1484 assert output == captured.stdout
1470
1485
1471 sys.meta_path.pop(0)
1486 sys.meta_path.pop(0)
General Comments 0
You need to be logged in to leave comments. Login now