##// END OF EJS Templates
Terminology: output is silenced, not disabled.
nfgf -
Show More
@@ -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 the output from being displayed
2366 # The code below prevents the output from being displayed
2367 # when using magics with decodator @output_can_be_disabled
2367 # when using magics with decodator @output_can_be_silenced
2368 # when the last Python token in the expression is a ';'.
2368 # when the last Python token in the expression is a ';'.
2369 if getattr(fn, magic.MAGIC_OUTPUT_CAN_BE_DISABLED, False):
2369 if getattr(fn, magic.MAGIC_OUTPUT_CAN_BE_SILENCED, False):
2370 if DisplayHook.semicolon_at_end_of_expression(magic_arg_s):
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,757 +1,757 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 MAGIC_OUTPUT_CAN_BE_DISABLED = "_ipython_magic_output_can_be_disabled"
261 MAGIC_OUTPUT_CAN_BE_SILENCED = "_ipython_magic_output_can_be_silenced"
262
262
263
263
264 def no_var_expand(magic_func):
264 def no_var_expand(magic_func):
265 """Mark a magic function as not needing variable expansion
265 """Mark a magic function as not needing variable expansion
266
266
267 By default, IPython interprets `{a}` or `$a` in the line passed to magics
267 By default, IPython interprets `{a}` or `$a` in the line passed to magics
268 as variables that should be interpolated from the interactive namespace
268 as variables that should be interpolated from the interactive namespace
269 before passing the line to the magic function.
269 before passing the line to the magic function.
270 This is not always desirable, e.g. when the magic executes Python code
270 This is not always desirable, e.g. when the magic executes Python code
271 (%timeit, %time, etc.).
271 (%timeit, %time, etc.).
272 Decorate magics with `@no_var_expand` to opt-out of variable expansion.
272 Decorate magics with `@no_var_expand` to opt-out of variable expansion.
273
273
274 .. versionadded:: 7.3
274 .. versionadded:: 7.3
275 """
275 """
276 setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
276 setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
277 return magic_func
277 return magic_func
278
278
279
279
280 def output_can_be_disabled(magic_func):
280 def output_can_be_silenced(magic_func):
281 """Mark a magic function so its output may be disabled.
281 """Mark a magic function so its output may be silenced.
282
282
283 The output is disabled if the Python expression used as a parameter of
283 The output is silenced if the Python expression used as a parameter of
284 the magic ends in a semicolon, not counting a Python comment that can
284 the magic ends in a semicolon, not counting a Python comment that can
285 follows it.
285 follow it.
286 """
286 """
287 setattr(magic_func, MAGIC_OUTPUT_CAN_BE_DISABLED, True)
287 setattr(magic_func, MAGIC_OUTPUT_CAN_BE_SILENCED, True)
288 return magic_func
288 return magic_func
289
289
290 # Create the actual decorators for public use
290 # Create the actual decorators for public use
291
291
292 # These three are used to decorate methods in class definitions
292 # These three are used to decorate methods in class definitions
293 line_magic = _method_magic_marker('line')
293 line_magic = _method_magic_marker('line')
294 cell_magic = _method_magic_marker('cell')
294 cell_magic = _method_magic_marker('cell')
295 line_cell_magic = _method_magic_marker('line_cell')
295 line_cell_magic = _method_magic_marker('line_cell')
296
296
297 # These three decorate standalone functions and perform the decoration
297 # These three decorate standalone functions and perform the decoration
298 # immediately. They can only run where get_ipython() works
298 # immediately. They can only run where get_ipython() works
299 register_line_magic = _function_magic_marker('line')
299 register_line_magic = _function_magic_marker('line')
300 register_cell_magic = _function_magic_marker('cell')
300 register_cell_magic = _function_magic_marker('cell')
301 register_line_cell_magic = _function_magic_marker('line_cell')
301 register_line_cell_magic = _function_magic_marker('line_cell')
302
302
303 #-----------------------------------------------------------------------------
303 #-----------------------------------------------------------------------------
304 # Core Magic classes
304 # Core Magic classes
305 #-----------------------------------------------------------------------------
305 #-----------------------------------------------------------------------------
306
306
307 class MagicsManager(Configurable):
307 class MagicsManager(Configurable):
308 """Object that handles all magic-related functionality for IPython.
308 """Object that handles all magic-related functionality for IPython.
309 """
309 """
310 # Non-configurable class attributes
310 # Non-configurable class attributes
311
311
312 # A two-level dict, first keyed by magic type, then by magic function, and
312 # A two-level dict, first keyed by magic type, then by magic function, and
313 # holding the actual callable object as value. This is the dict used for
313 # holding the actual callable object as value. This is the dict used for
314 # magic function dispatch
314 # magic function dispatch
315 magics = Dict()
315 magics = Dict()
316 lazy_magics = Dict(
316 lazy_magics = Dict(
317 help="""
317 help="""
318 Mapping from magic names to modules to load.
318 Mapping from magic names to modules to load.
319
319
320 This can be used in IPython/IPykernel configuration to declare lazy magics
320 This can be used in IPython/IPykernel configuration to declare lazy magics
321 that will only be imported/registered on first use.
321 that will only be imported/registered on first use.
322
322
323 For example::
323 For example::
324
324
325 c.MagicsManager.lazy_magics = {
325 c.MagicsManager.lazy_magics = {
326 "my_magic": "slow.to.import",
326 "my_magic": "slow.to.import",
327 "my_other_magic": "also.slow",
327 "my_other_magic": "also.slow",
328 }
328 }
329
329
330 On first invocation of `%my_magic`, `%%my_magic`, `%%my_other_magic` or
330 On first invocation of `%my_magic`, `%%my_magic`, `%%my_other_magic` or
331 `%%my_other_magic`, the corresponding module will be loaded as an ipython
331 `%%my_other_magic`, the corresponding module will be loaded as an ipython
332 extensions as if you had previously done `%load_ext ipython`.
332 extensions as if you had previously done `%load_ext ipython`.
333
333
334 Magics names should be without percent(s) as magics can be both cell
334 Magics names should be without percent(s) as magics can be both cell
335 and line magics.
335 and line magics.
336
336
337 Lazy loading happen relatively late in execution process, and
337 Lazy loading happen relatively late in execution process, and
338 complex extensions that manipulate Python/IPython internal state or global state
338 complex extensions that manipulate Python/IPython internal state or global state
339 might not support lazy loading.
339 might not support lazy loading.
340 """
340 """
341 ).tag(
341 ).tag(
342 config=True,
342 config=True,
343 )
343 )
344
344
345 # A registry of the original objects that we've been given holding magics.
345 # A registry of the original objects that we've been given holding magics.
346 registry = Dict()
346 registry = Dict()
347
347
348 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
348 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
349
349
350 auto_magic = Bool(True, help=
350 auto_magic = Bool(True, help=
351 "Automatically call line magics without requiring explicit % prefix"
351 "Automatically call line magics without requiring explicit % prefix"
352 ).tag(config=True)
352 ).tag(config=True)
353 @observe('auto_magic')
353 @observe('auto_magic')
354 def _auto_magic_changed(self, change):
354 def _auto_magic_changed(self, change):
355 self.shell.automagic = change['new']
355 self.shell.automagic = change['new']
356
356
357 _auto_status = [
357 _auto_status = [
358 'Automagic is OFF, % prefix IS needed for line magics.',
358 'Automagic is OFF, % prefix IS needed for line magics.',
359 'Automagic is ON, % prefix IS NOT needed for line magics.']
359 'Automagic is ON, % prefix IS NOT needed for line magics.']
360
360
361 user_magics = Instance('IPython.core.magics.UserMagics', allow_none=True)
361 user_magics = Instance('IPython.core.magics.UserMagics', allow_none=True)
362
362
363 def __init__(self, shell=None, config=None, user_magics=None, **traits):
363 def __init__(self, shell=None, config=None, user_magics=None, **traits):
364
364
365 super(MagicsManager, self).__init__(shell=shell, config=config,
365 super(MagicsManager, self).__init__(shell=shell, config=config,
366 user_magics=user_magics, **traits)
366 user_magics=user_magics, **traits)
367 self.magics = dict(line={}, cell={})
367 self.magics = dict(line={}, cell={})
368 # Let's add the user_magics to the registry for uniformity, so *all*
368 # Let's add the user_magics to the registry for uniformity, so *all*
369 # registered magic containers can be found there.
369 # registered magic containers can be found there.
370 self.registry[user_magics.__class__.__name__] = user_magics
370 self.registry[user_magics.__class__.__name__] = user_magics
371
371
372 def auto_status(self):
372 def auto_status(self):
373 """Return descriptive string with automagic status."""
373 """Return descriptive string with automagic status."""
374 return self._auto_status[self.auto_magic]
374 return self._auto_status[self.auto_magic]
375
375
376 def lsmagic(self):
376 def lsmagic(self):
377 """Return a dict of currently available magic functions.
377 """Return a dict of currently available magic functions.
378
378
379 The return dict has the keys 'line' and 'cell', corresponding to the
379 The return dict has the keys 'line' and 'cell', corresponding to the
380 two types of magics we support. Each value is a list of names.
380 two types of magics we support. Each value is a list of names.
381 """
381 """
382 return self.magics
382 return self.magics
383
383
384 def lsmagic_docs(self, brief=False, missing=''):
384 def lsmagic_docs(self, brief=False, missing=''):
385 """Return dict of documentation of magic functions.
385 """Return dict of documentation of magic functions.
386
386
387 The return dict has the keys 'line' and 'cell', corresponding to the
387 The return dict has the keys 'line' and 'cell', corresponding to the
388 two types of magics we support. Each value is a dict keyed by magic
388 two types of magics we support. Each value is a dict keyed by magic
389 name whose value is the function docstring. If a docstring is
389 name whose value is the function docstring. If a docstring is
390 unavailable, the value of `missing` is used instead.
390 unavailable, the value of `missing` is used instead.
391
391
392 If brief is True, only the first line of each docstring will be returned.
392 If brief is True, only the first line of each docstring will be returned.
393 """
393 """
394 docs = {}
394 docs = {}
395 for m_type in self.magics:
395 for m_type in self.magics:
396 m_docs = {}
396 m_docs = {}
397 for m_name, m_func in self.magics[m_type].items():
397 for m_name, m_func in self.magics[m_type].items():
398 if m_func.__doc__:
398 if m_func.__doc__:
399 if brief:
399 if brief:
400 m_docs[m_name] = m_func.__doc__.split('\n', 1)[0]
400 m_docs[m_name] = m_func.__doc__.split('\n', 1)[0]
401 else:
401 else:
402 m_docs[m_name] = m_func.__doc__.rstrip()
402 m_docs[m_name] = m_func.__doc__.rstrip()
403 else:
403 else:
404 m_docs[m_name] = missing
404 m_docs[m_name] = missing
405 docs[m_type] = m_docs
405 docs[m_type] = m_docs
406 return docs
406 return docs
407
407
408 def register_lazy(self, name: str, fully_qualified_name: str):
408 def register_lazy(self, name: str, fully_qualified_name: str):
409 """
409 """
410 Lazily register a magic via an extension.
410 Lazily register a magic via an extension.
411
411
412
412
413 Parameters
413 Parameters
414 ----------
414 ----------
415 name : str
415 name : str
416 Name of the magic you wish to register.
416 Name of the magic you wish to register.
417 fully_qualified_name :
417 fully_qualified_name :
418 Fully qualified name of the module/submodule that should be loaded
418 Fully qualified name of the module/submodule that should be loaded
419 as an extensions when the magic is first called.
419 as an extensions when the magic is first called.
420 It is assumed that loading this extensions will register the given
420 It is assumed that loading this extensions will register the given
421 magic.
421 magic.
422 """
422 """
423
423
424 self.lazy_magics[name] = fully_qualified_name
424 self.lazy_magics[name] = fully_qualified_name
425
425
426 def register(self, *magic_objects):
426 def register(self, *magic_objects):
427 """Register one or more instances of Magics.
427 """Register one or more instances of Magics.
428
428
429 Take one or more classes or instances of classes that subclass the main
429 Take one or more classes or instances of classes that subclass the main
430 `core.Magic` class, and register them with IPython to use the magic
430 `core.Magic` class, and register them with IPython to use the magic
431 functions they provide. The registration process will then ensure that
431 functions they provide. The registration process will then ensure that
432 any methods that have decorated to provide line and/or cell magics will
432 any methods that have decorated to provide line and/or cell magics will
433 be recognized with the `%x`/`%%x` syntax as a line/cell magic
433 be recognized with the `%x`/`%%x` syntax as a line/cell magic
434 respectively.
434 respectively.
435
435
436 If classes are given, they will be instantiated with the default
436 If classes are given, they will be instantiated with the default
437 constructor. If your classes need a custom constructor, you should
437 constructor. If your classes need a custom constructor, you should
438 instanitate them first and pass the instance.
438 instanitate them first and pass the instance.
439
439
440 The provided arguments can be an arbitrary mix of classes and instances.
440 The provided arguments can be an arbitrary mix of classes and instances.
441
441
442 Parameters
442 Parameters
443 ----------
443 ----------
444 *magic_objects : one or more classes or instances
444 *magic_objects : one or more classes or instances
445 """
445 """
446 # Start by validating them to ensure they have all had their magic
446 # Start by validating them to ensure they have all had their magic
447 # methods registered at the instance level
447 # methods registered at the instance level
448 for m in magic_objects:
448 for m in magic_objects:
449 if not m.registered:
449 if not m.registered:
450 raise ValueError("Class of magics %r was constructed without "
450 raise ValueError("Class of magics %r was constructed without "
451 "the @register_magics class decorator")
451 "the @register_magics class decorator")
452 if isinstance(m, type):
452 if isinstance(m, type):
453 # If we're given an uninstantiated class
453 # If we're given an uninstantiated class
454 m = m(shell=self.shell)
454 m = m(shell=self.shell)
455
455
456 # Now that we have an instance, we can register it and update the
456 # Now that we have an instance, we can register it and update the
457 # table of callables
457 # table of callables
458 self.registry[m.__class__.__name__] = m
458 self.registry[m.__class__.__name__] = m
459 for mtype in magic_kinds:
459 for mtype in magic_kinds:
460 self.magics[mtype].update(m.magics[mtype])
460 self.magics[mtype].update(m.magics[mtype])
461
461
462 def register_function(self, func, magic_kind='line', magic_name=None):
462 def register_function(self, func, magic_kind='line', magic_name=None):
463 """Expose a standalone function as magic function for IPython.
463 """Expose a standalone function as magic function for IPython.
464
464
465 This will create an IPython magic (line, cell or both) from a
465 This will create an IPython magic (line, cell or both) from a
466 standalone function. The functions should have the following
466 standalone function. The functions should have the following
467 signatures:
467 signatures:
468
468
469 * For line magics: `def f(line)`
469 * For line magics: `def f(line)`
470 * For cell magics: `def f(line, cell)`
470 * For cell magics: `def f(line, cell)`
471 * For a function that does both: `def f(line, cell=None)`
471 * For a function that does both: `def f(line, cell=None)`
472
472
473 In the latter case, the function will be called with `cell==None` when
473 In the latter case, the function will be called with `cell==None` when
474 invoked as `%f`, and with cell as a string when invoked as `%%f`.
474 invoked as `%f`, and with cell as a string when invoked as `%%f`.
475
475
476 Parameters
476 Parameters
477 ----------
477 ----------
478 func : callable
478 func : callable
479 Function to be registered as a magic.
479 Function to be registered as a magic.
480 magic_kind : str
480 magic_kind : str
481 Kind of magic, one of 'line', 'cell' or 'line_cell'
481 Kind of magic, one of 'line', 'cell' or 'line_cell'
482 magic_name : optional str
482 magic_name : optional str
483 If given, the name the magic will have in the IPython namespace. By
483 If given, the name the magic will have in the IPython namespace. By
484 default, the name of the function itself is used.
484 default, the name of the function itself is used.
485 """
485 """
486
486
487 # Create the new method in the user_magics and register it in the
487 # Create the new method in the user_magics and register it in the
488 # global table
488 # global table
489 validate_type(magic_kind)
489 validate_type(magic_kind)
490 magic_name = func.__name__ if magic_name is None else magic_name
490 magic_name = func.__name__ if magic_name is None else magic_name
491 setattr(self.user_magics, magic_name, func)
491 setattr(self.user_magics, magic_name, func)
492 record_magic(self.magics, magic_kind, magic_name, func)
492 record_magic(self.magics, magic_kind, magic_name, func)
493
493
494 def register_alias(self, alias_name, magic_name, magic_kind='line', magic_params=None):
494 def register_alias(self, alias_name, magic_name, magic_kind='line', magic_params=None):
495 """Register an alias to a magic function.
495 """Register an alias to a magic function.
496
496
497 The alias is an instance of :class:`MagicAlias`, which holds the
497 The alias is an instance of :class:`MagicAlias`, which holds the
498 name and kind of the magic it should call. Binding is done at
498 name and kind of the magic it should call. Binding is done at
499 call time, so if the underlying magic function is changed the alias
499 call time, so if the underlying magic function is changed the alias
500 will call the new function.
500 will call the new function.
501
501
502 Parameters
502 Parameters
503 ----------
503 ----------
504 alias_name : str
504 alias_name : str
505 The name of the magic to be registered.
505 The name of the magic to be registered.
506 magic_name : str
506 magic_name : str
507 The name of an existing magic.
507 The name of an existing magic.
508 magic_kind : str
508 magic_kind : str
509 Kind of magic, one of 'line' or 'cell'
509 Kind of magic, one of 'line' or 'cell'
510 """
510 """
511
511
512 # `validate_type` is too permissive, as it allows 'line_cell'
512 # `validate_type` is too permissive, as it allows 'line_cell'
513 # which we do not handle.
513 # which we do not handle.
514 if magic_kind not in magic_kinds:
514 if magic_kind not in magic_kinds:
515 raise ValueError('magic_kind must be one of %s, %s given' %
515 raise ValueError('magic_kind must be one of %s, %s given' %
516 magic_kinds, magic_kind)
516 magic_kinds, magic_kind)
517
517
518 alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
518 alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
519 setattr(self.user_magics, alias_name, alias)
519 setattr(self.user_magics, alias_name, alias)
520 record_magic(self.magics, magic_kind, alias_name, alias)
520 record_magic(self.magics, magic_kind, alias_name, alias)
521
521
522 # Key base class that provides the central functionality for magics.
522 # Key base class that provides the central functionality for magics.
523
523
524
524
525 class Magics(Configurable):
525 class Magics(Configurable):
526 """Base class for implementing magic functions.
526 """Base class for implementing magic functions.
527
527
528 Shell functions which can be reached as %function_name. All magic
528 Shell functions which can be reached as %function_name. All magic
529 functions should accept a string, which they can parse for their own
529 functions should accept a string, which they can parse for their own
530 needs. This can make some functions easier to type, eg `%cd ../`
530 needs. This can make some functions easier to type, eg `%cd ../`
531 vs. `%cd("../")`
531 vs. `%cd("../")`
532
532
533 Classes providing magic functions need to subclass this class, and they
533 Classes providing magic functions need to subclass this class, and they
534 MUST:
534 MUST:
535
535
536 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
536 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
537 individual methods as magic functions, AND
537 individual methods as magic functions, AND
538
538
539 - Use the class decorator `@magics_class` to ensure that the magic
539 - Use the class decorator `@magics_class` to ensure that the magic
540 methods are properly registered at the instance level upon instance
540 methods are properly registered at the instance level upon instance
541 initialization.
541 initialization.
542
542
543 See :mod:`magic_functions` for examples of actual implementation classes.
543 See :mod:`magic_functions` for examples of actual implementation classes.
544 """
544 """
545 # Dict holding all command-line options for each magic.
545 # Dict holding all command-line options for each magic.
546 options_table = None
546 options_table = None
547 # Dict for the mapping of magic names to methods, set by class decorator
547 # Dict for the mapping of magic names to methods, set by class decorator
548 magics = None
548 magics = None
549 # Flag to check that the class decorator was properly applied
549 # Flag to check that the class decorator was properly applied
550 registered = False
550 registered = False
551 # Instance of IPython shell
551 # Instance of IPython shell
552 shell = None
552 shell = None
553
553
554 def __init__(self, shell=None, **kwargs):
554 def __init__(self, shell=None, **kwargs):
555 if not(self.__class__.registered):
555 if not(self.__class__.registered):
556 raise ValueError('Magics subclass without registration - '
556 raise ValueError('Magics subclass without registration - '
557 'did you forget to apply @magics_class?')
557 'did you forget to apply @magics_class?')
558 if shell is not None:
558 if shell is not None:
559 if hasattr(shell, 'configurables'):
559 if hasattr(shell, 'configurables'):
560 shell.configurables.append(self)
560 shell.configurables.append(self)
561 if hasattr(shell, 'config'):
561 if hasattr(shell, 'config'):
562 kwargs.setdefault('parent', shell)
562 kwargs.setdefault('parent', shell)
563
563
564 self.shell = shell
564 self.shell = shell
565 self.options_table = {}
565 self.options_table = {}
566 # The method decorators are run when the instance doesn't exist yet, so
566 # The method decorators are run when the instance doesn't exist yet, so
567 # they can only record the names of the methods they are supposed to
567 # they can only record the names of the methods they are supposed to
568 # grab. Only now, that the instance exists, can we create the proper
568 # grab. Only now, that the instance exists, can we create the proper
569 # mapping to bound methods. So we read the info off the original names
569 # mapping to bound methods. So we read the info off the original names
570 # table and replace each method name by the actual bound method.
570 # table and replace each method name by the actual bound method.
571 # But we mustn't clobber the *class* mapping, in case of multiple instances.
571 # But we mustn't clobber the *class* mapping, in case of multiple instances.
572 class_magics = self.magics
572 class_magics = self.magics
573 self.magics = {}
573 self.magics = {}
574 for mtype in magic_kinds:
574 for mtype in magic_kinds:
575 tab = self.magics[mtype] = {}
575 tab = self.magics[mtype] = {}
576 cls_tab = class_magics[mtype]
576 cls_tab = class_magics[mtype]
577 for magic_name, meth_name in cls_tab.items():
577 for magic_name, meth_name in cls_tab.items():
578 if isinstance(meth_name, str):
578 if isinstance(meth_name, str):
579 # it's a method name, grab it
579 # it's a method name, grab it
580 tab[magic_name] = getattr(self, meth_name)
580 tab[magic_name] = getattr(self, meth_name)
581 else:
581 else:
582 # it's the real thing
582 # it's the real thing
583 tab[magic_name] = meth_name
583 tab[magic_name] = meth_name
584 # Configurable **needs** to be initiated at the end or the config
584 # Configurable **needs** to be initiated at the end or the config
585 # magics get screwed up.
585 # magics get screwed up.
586 super(Magics, self).__init__(**kwargs)
586 super(Magics, self).__init__(**kwargs)
587
587
588 def arg_err(self,func):
588 def arg_err(self,func):
589 """Print docstring if incorrect arguments were passed"""
589 """Print docstring if incorrect arguments were passed"""
590 print('Error in arguments:')
590 print('Error in arguments:')
591 print(oinspect.getdoc(func))
591 print(oinspect.getdoc(func))
592
592
593 def format_latex(self, strng):
593 def format_latex(self, strng):
594 """Format a string for latex inclusion."""
594 """Format a string for latex inclusion."""
595
595
596 # Characters that need to be escaped for latex:
596 # Characters that need to be escaped for latex:
597 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
597 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
598 # Magic command names as headers:
598 # Magic command names as headers:
599 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
599 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
600 re.MULTILINE)
600 re.MULTILINE)
601 # Magic commands
601 # Magic commands
602 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
602 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
603 re.MULTILINE)
603 re.MULTILINE)
604 # Paragraph continue
604 # Paragraph continue
605 par_re = re.compile(r'\\$',re.MULTILINE)
605 par_re = re.compile(r'\\$',re.MULTILINE)
606
606
607 # The "\n" symbol
607 # The "\n" symbol
608 newline_re = re.compile(r'\\n')
608 newline_re = re.compile(r'\\n')
609
609
610 # Now build the string for output:
610 # Now build the string for output:
611 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
611 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
612 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
612 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
613 strng)
613 strng)
614 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
614 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
615 strng = par_re.sub(r'\\\\',strng)
615 strng = par_re.sub(r'\\\\',strng)
616 strng = escape_re.sub(r'\\\1',strng)
616 strng = escape_re.sub(r'\\\1',strng)
617 strng = newline_re.sub(r'\\textbackslash{}n',strng)
617 strng = newline_re.sub(r'\\textbackslash{}n',strng)
618 return strng
618 return strng
619
619
620 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
620 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
621 """Parse options passed to an argument string.
621 """Parse options passed to an argument string.
622
622
623 The interface is similar to that of :func:`getopt.getopt`, but it
623 The interface is similar to that of :func:`getopt.getopt`, but it
624 returns a :class:`~IPython.utils.struct.Struct` with the options as keys
624 returns a :class:`~IPython.utils.struct.Struct` with the options as keys
625 and the stripped argument string still as a string.
625 and the stripped argument string still as a string.
626
626
627 arg_str is quoted as a true sys.argv vector by using shlex.split.
627 arg_str is quoted as a true sys.argv vector by using shlex.split.
628 This allows us to easily expand variables, glob files, quote
628 This allows us to easily expand variables, glob files, quote
629 arguments, etc.
629 arguments, etc.
630
630
631 Parameters
631 Parameters
632 ----------
632 ----------
633 arg_str : str
633 arg_str : str
634 The arguments to parse.
634 The arguments to parse.
635 opt_str : str
635 opt_str : str
636 The options specification.
636 The options specification.
637 mode : str, default 'string'
637 mode : str, default 'string'
638 If given as 'list', the argument string is returned as a list (split
638 If given as 'list', the argument string is returned as a list (split
639 on whitespace) instead of a string.
639 on whitespace) instead of a string.
640 list_all : bool, default False
640 list_all : bool, default False
641 Put all option values in lists. Normally only options
641 Put all option values in lists. Normally only options
642 appearing more than once are put in a list.
642 appearing more than once are put in a list.
643 posix : bool, default True
643 posix : bool, default True
644 Whether to split the input line in POSIX mode or not, as per the
644 Whether to split the input line in POSIX mode or not, as per the
645 conventions outlined in the :mod:`shlex` module from the standard
645 conventions outlined in the :mod:`shlex` module from the standard
646 library.
646 library.
647 """
647 """
648
648
649 # inject default options at the beginning of the input line
649 # inject default options at the beginning of the input line
650 caller = sys._getframe(1).f_code.co_name
650 caller = sys._getframe(1).f_code.co_name
651 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
651 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
652
652
653 mode = kw.get('mode','string')
653 mode = kw.get('mode','string')
654 if mode not in ['string','list']:
654 if mode not in ['string','list']:
655 raise ValueError('incorrect mode given: %s' % mode)
655 raise ValueError('incorrect mode given: %s' % mode)
656 # Get options
656 # Get options
657 list_all = kw.get('list_all',0)
657 list_all = kw.get('list_all',0)
658 posix = kw.get('posix', os.name == 'posix')
658 posix = kw.get('posix', os.name == 'posix')
659 strict = kw.get('strict', True)
659 strict = kw.get('strict', True)
660
660
661 preserve_non_opts = kw.get("preserve_non_opts", False)
661 preserve_non_opts = kw.get("preserve_non_opts", False)
662 remainder_arg_str = arg_str
662 remainder_arg_str = arg_str
663
663
664 # Check if we have more than one argument to warrant extra processing:
664 # Check if we have more than one argument to warrant extra processing:
665 odict = {} # Dictionary with options
665 odict = {} # Dictionary with options
666 args = arg_str.split()
666 args = arg_str.split()
667 if len(args) >= 1:
667 if len(args) >= 1:
668 # If the list of inputs only has 0 or 1 thing in it, there's no
668 # If the list of inputs only has 0 or 1 thing in it, there's no
669 # need to look for options
669 # need to look for options
670 argv = arg_split(arg_str, posix, strict)
670 argv = arg_split(arg_str, posix, strict)
671 # Do regular option processing
671 # Do regular option processing
672 try:
672 try:
673 opts,args = getopt(argv, opt_str, long_opts)
673 opts,args = getopt(argv, opt_str, long_opts)
674 except GetoptError as e:
674 except GetoptError as e:
675 raise UsageError(
675 raise UsageError(
676 '%s ( allowed: "%s" %s)' % (e.msg, opt_str, " ".join(long_opts))
676 '%s ( allowed: "%s" %s)' % (e.msg, opt_str, " ".join(long_opts))
677 ) from e
677 ) from e
678 for o, a in opts:
678 for o, a in opts:
679 if mode == "string" and preserve_non_opts:
679 if mode == "string" and preserve_non_opts:
680 # remove option-parts from the original args-string and preserve remaining-part.
680 # remove option-parts from the original args-string and preserve remaining-part.
681 # This relies on the arg_split(...) and getopt(...)'s impl spec, that the parsed options are
681 # This relies on the arg_split(...) and getopt(...)'s impl spec, that the parsed options are
682 # returned in the original order.
682 # returned in the original order.
683 remainder_arg_str = remainder_arg_str.replace(o, "", 1).replace(
683 remainder_arg_str = remainder_arg_str.replace(o, "", 1).replace(
684 a, "", 1
684 a, "", 1
685 )
685 )
686 if o.startswith("--"):
686 if o.startswith("--"):
687 o = o[2:]
687 o = o[2:]
688 else:
688 else:
689 o = o[1:]
689 o = o[1:]
690 try:
690 try:
691 odict[o].append(a)
691 odict[o].append(a)
692 except AttributeError:
692 except AttributeError:
693 odict[o] = [odict[o],a]
693 odict[o] = [odict[o],a]
694 except KeyError:
694 except KeyError:
695 if list_all:
695 if list_all:
696 odict[o] = [a]
696 odict[o] = [a]
697 else:
697 else:
698 odict[o] = a
698 odict[o] = a
699
699
700 # Prepare opts,args for return
700 # Prepare opts,args for return
701 opts = Struct(odict)
701 opts = Struct(odict)
702 if mode == 'string':
702 if mode == 'string':
703 if preserve_non_opts:
703 if preserve_non_opts:
704 args = remainder_arg_str.lstrip()
704 args = remainder_arg_str.lstrip()
705 else:
705 else:
706 args = " ".join(args)
706 args = " ".join(args)
707
707
708 return opts,args
708 return opts,args
709
709
710 def default_option(self, fn, optstr):
710 def default_option(self, fn, optstr):
711 """Make an entry in the options_table for fn, with value optstr"""
711 """Make an entry in the options_table for fn, with value optstr"""
712
712
713 if fn not in self.lsmagic():
713 if fn not in self.lsmagic():
714 error("%s is not a magic function" % fn)
714 error("%s is not a magic function" % fn)
715 self.options_table[fn] = optstr
715 self.options_table[fn] = optstr
716
716
717
717
718 class MagicAlias(object):
718 class MagicAlias(object):
719 """An alias to another magic function.
719 """An alias to another magic function.
720
720
721 An alias is determined by its magic name and magic kind. Lookup
721 An alias is determined by its magic name and magic kind. Lookup
722 is done at call time, so if the underlying magic changes the alias
722 is done at call time, so if the underlying magic changes the alias
723 will call the new function.
723 will call the new function.
724
724
725 Use the :meth:`MagicsManager.register_alias` method or the
725 Use the :meth:`MagicsManager.register_alias` method or the
726 `%alias_magic` magic function to create and register a new alias.
726 `%alias_magic` magic function to create and register a new alias.
727 """
727 """
728 def __init__(self, shell, magic_name, magic_kind, magic_params=None):
728 def __init__(self, shell, magic_name, magic_kind, magic_params=None):
729 self.shell = shell
729 self.shell = shell
730 self.magic_name = magic_name
730 self.magic_name = magic_name
731 self.magic_params = magic_params
731 self.magic_params = magic_params
732 self.magic_kind = magic_kind
732 self.magic_kind = magic_kind
733
733
734 self.pretty_target = '%s%s' % (magic_escapes[self.magic_kind], self.magic_name)
734 self.pretty_target = '%s%s' % (magic_escapes[self.magic_kind], self.magic_name)
735 self.__doc__ = "Alias for `%s`." % self.pretty_target
735 self.__doc__ = "Alias for `%s`." % self.pretty_target
736
736
737 self._in_call = False
737 self._in_call = False
738
738
739 def __call__(self, *args, **kwargs):
739 def __call__(self, *args, **kwargs):
740 """Call the magic alias."""
740 """Call the magic alias."""
741 fn = self.shell.find_magic(self.magic_name, self.magic_kind)
741 fn = self.shell.find_magic(self.magic_name, self.magic_kind)
742 if fn is None:
742 if fn is None:
743 raise UsageError("Magic `%s` not found." % self.pretty_target)
743 raise UsageError("Magic `%s` not found." % self.pretty_target)
744
744
745 # Protect against infinite recursion.
745 # Protect against infinite recursion.
746 if self._in_call:
746 if self._in_call:
747 raise UsageError("Infinite recursion detected; "
747 raise UsageError("Infinite recursion detected; "
748 "magic aliases cannot call themselves.")
748 "magic aliases cannot call themselves.")
749 self._in_call = True
749 self._in_call = True
750 try:
750 try:
751 if self.magic_params:
751 if self.magic_params:
752 args_list = list(args)
752 args_list = list(args)
753 args_list[0] = self.magic_params + " " + args[0]
753 args_list[0] = self.magic_params + " " + args[0]
754 args = tuple(args_list)
754 args = tuple(args_list)
755 return fn(*args, **kwargs)
755 return fn(*args, **kwargs)
756 finally:
756 finally:
757 self._in_call = False
757 self._in_call = False
@@ -1,1512 +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 output_can_be_silenced,
41 on_off,
41 on_off,
42 )
42 )
43 from IPython.testing.skipdoctest import skip_doctest
43 from IPython.testing.skipdoctest import skip_doctest
44 from IPython.utils.capture import capture_output
44 from IPython.utils.capture import capture_output
45 from IPython.utils.contexts import preserve_keys
45 from IPython.utils.contexts import preserve_keys
46 from IPython.utils.ipstruct import Struct
46 from IPython.utils.ipstruct import Struct
47 from IPython.utils.module_paths import find_mod
47 from IPython.utils.module_paths import find_mod
48 from IPython.utils.path import get_py_filename, shellglob
48 from IPython.utils.path import get_py_filename, shellglob
49 from IPython.utils.timing import clock, clock2
49 from IPython.utils.timing import clock, clock2
50
50
51 #-----------------------------------------------------------------------------
51 #-----------------------------------------------------------------------------
52 # Magic implementation classes
52 # Magic implementation classes
53 #-----------------------------------------------------------------------------
53 #-----------------------------------------------------------------------------
54
54
55
55
56 class TimeitResult(object):
56 class TimeitResult(object):
57 """
57 """
58 Object returned by the timeit magic with info about the run.
58 Object returned by the timeit magic with info about the run.
59
59
60 Contains the following attributes :
60 Contains the following attributes :
61
61
62 loops: (int) number of loops done per measurement
62 loops: (int) number of loops done per measurement
63 repeat: (int) number of times the measurement has been repeated
63 repeat: (int) number of times the measurement has been repeated
64 best: (float) best execution time / number
64 best: (float) best execution time / number
65 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)
66 compile_time: (float) time of statement compilation (s)
66 compile_time: (float) time of statement compilation (s)
67
67
68 """
68 """
69 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):
70 self.loops = loops
70 self.loops = loops
71 self.repeat = repeat
71 self.repeat = repeat
72 self.best = best
72 self.best = best
73 self.worst = worst
73 self.worst = worst
74 self.all_runs = all_runs
74 self.all_runs = all_runs
75 self.compile_time = compile_time
75 self.compile_time = compile_time
76 self._precision = precision
76 self._precision = precision
77 self.timings = [ dt / self.loops for dt in all_runs]
77 self.timings = [ dt / self.loops for dt in all_runs]
78
78
79 @property
79 @property
80 def average(self):
80 def average(self):
81 return math.fsum(self.timings) / len(self.timings)
81 return math.fsum(self.timings) / len(self.timings)
82
82
83 @property
83 @property
84 def stdev(self):
84 def stdev(self):
85 mean = self.average
85 mean = self.average
86 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
87
87
88 def __str__(self):
88 def __str__(self):
89 pm = '+-'
89 pm = '+-'
90 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
90 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
91 try:
91 try:
92 u'\xb1'.encode(sys.stdout.encoding)
92 u'\xb1'.encode(sys.stdout.encoding)
93 pm = u'\xb1'
93 pm = u'\xb1'
94 except:
94 except:
95 pass
95 pass
96 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(
97 pm=pm,
97 pm=pm,
98 runs=self.repeat,
98 runs=self.repeat,
99 loops=self.loops,
99 loops=self.loops,
100 loop_plural="" if self.loops == 1 else "s",
100 loop_plural="" if self.loops == 1 else "s",
101 run_plural="" if self.repeat == 1 else "s",
101 run_plural="" if self.repeat == 1 else "s",
102 mean=_format_time(self.average, self._precision),
102 mean=_format_time(self.average, self._precision),
103 std=_format_time(self.stdev, self._precision),
103 std=_format_time(self.stdev, self._precision),
104 )
104 )
105
105
106 def _repr_pretty_(self, p , cycle):
106 def _repr_pretty_(self, p , cycle):
107 unic = self.__str__()
107 unic = self.__str__()
108 p.text(u'<TimeitResult : '+unic+u'>')
108 p.text(u'<TimeitResult : '+unic+u'>')
109
109
110
110
111 class TimeitTemplateFiller(ast.NodeTransformer):
111 class TimeitTemplateFiller(ast.NodeTransformer):
112 """Fill in the AST template for timing execution.
112 """Fill in the AST template for timing execution.
113
113
114 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
115 :meth:`ExecutionMagics.timeit`.
115 :meth:`ExecutionMagics.timeit`.
116 """
116 """
117 def __init__(self, ast_setup, ast_stmt):
117 def __init__(self, ast_setup, ast_stmt):
118 self.ast_setup = ast_setup
118 self.ast_setup = ast_setup
119 self.ast_stmt = ast_stmt
119 self.ast_stmt = ast_stmt
120
120
121 def visit_FunctionDef(self, node):
121 def visit_FunctionDef(self, node):
122 "Fill in the setup statement"
122 "Fill in the setup statement"
123 self.generic_visit(node)
123 self.generic_visit(node)
124 if node.name == "inner":
124 if node.name == "inner":
125 node.body[:1] = self.ast_setup.body
125 node.body[:1] = self.ast_setup.body
126
126
127 return node
127 return node
128
128
129 def visit_For(self, node):
129 def visit_For(self, node):
130 "Fill in the statement to be timed"
130 "Fill in the statement to be timed"
131 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
131 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
132 node.body = self.ast_stmt.body
132 node.body = self.ast_stmt.body
133 return node
133 return node
134
134
135
135
136 class Timer(timeit.Timer):
136 class Timer(timeit.Timer):
137 """Timer class that explicitly uses self.inner
137 """Timer class that explicitly uses self.inner
138
138
139 which is an undocumented implementation detail of CPython,
139 which is an undocumented implementation detail of CPython,
140 not shared by PyPy.
140 not shared by PyPy.
141 """
141 """
142 # Timer.timeit copied from CPython 3.4.2
142 # Timer.timeit copied from CPython 3.4.2
143 def timeit(self, number=timeit.default_number):
143 def timeit(self, number=timeit.default_number):
144 """Time 'number' executions of the main statement.
144 """Time 'number' executions of the main statement.
145
145
146 To be precise, this executes the setup statement once, and
146 To be precise, this executes the setup statement once, and
147 then returns the time it takes to execute the main statement
147 then returns the time it takes to execute the main statement
148 a number of times, as a float measured in seconds. The
148 a number of times, as a float measured in seconds. The
149 argument is the number of times through the loop, defaulting
149 argument is the number of times through the loop, defaulting
150 to one million. The main statement, the setup statement and
150 to one million. The main statement, the setup statement and
151 the timer function to be used are passed to the constructor.
151 the timer function to be used are passed to the constructor.
152 """
152 """
153 it = itertools.repeat(None, number)
153 it = itertools.repeat(None, number)
154 gcold = gc.isenabled()
154 gcold = gc.isenabled()
155 gc.disable()
155 gc.disable()
156 try:
156 try:
157 timing = self.inner(it, self.timer)
157 timing = self.inner(it, self.timer)
158 finally:
158 finally:
159 if gcold:
159 if gcold:
160 gc.enable()
160 gc.enable()
161 return timing
161 return timing
162
162
163
163
164 @magics_class
164 @magics_class
165 class ExecutionMagics(Magics):
165 class ExecutionMagics(Magics):
166 """Magics related to code execution, debugging, profiling, etc.
166 """Magics related to code execution, debugging, profiling, etc.
167
167
168 """
168 """
169
169
170 def __init__(self, shell):
170 def __init__(self, shell):
171 super(ExecutionMagics, self).__init__(shell)
171 super(ExecutionMagics, self).__init__(shell)
172 # Default execution function used to actually run user code.
172 # Default execution function used to actually run user code.
173 self.default_runner = None
173 self.default_runner = None
174
174
175 @skip_doctest
175 @skip_doctest
176 @no_var_expand
176 @no_var_expand
177 @line_cell_magic
177 @line_cell_magic
178 def prun(self, parameter_s='', cell=None):
178 def prun(self, parameter_s='', cell=None):
179
179
180 """Run a statement through the python code profiler.
180 """Run a statement through the python code profiler.
181
181
182 Usage, in line mode:
182 Usage, in line mode:
183 %prun [options] statement
183 %prun [options] statement
184
184
185 Usage, in cell mode:
185 Usage, in cell mode:
186 %%prun [options] [statement]
186 %%prun [options] [statement]
187 code...
187 code...
188 code...
188 code...
189
189
190 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
191 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
192 profile multiline blocks without having to put them in a separate
192 profile multiline blocks without having to put them in a separate
193 function.
193 function.
194
194
195 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
196 python profiler in a manner similar to the profile.run() function.
196 python profiler in a manner similar to the profile.run() function.
197 Namespaces are internally managed to work correctly; profile.run
197 Namespaces are internally managed to work correctly; profile.run
198 cannot be used in IPython because it makes certain assumptions about
198 cannot be used in IPython because it makes certain assumptions about
199 namespaces which do not hold under IPython.
199 namespaces which do not hold under IPython.
200
200
201 Options:
201 Options:
202
202
203 -l <limit>
203 -l <limit>
204 you can place restrictions on what or how much of the
204 you can place restrictions on what or how much of the
205 profile gets printed. The limit value can be:
205 profile gets printed. The limit value can be:
206
206
207 * A string: only information for function names containing this string
207 * A string: only information for function names containing this string
208 is printed.
208 is printed.
209
209
210 * An integer: only these many lines are printed.
210 * An integer: only these many lines are printed.
211
211
212 * 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
213 (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).
214
214
215 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
216 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
217 information about class constructors.
217 information about class constructors.
218
218
219 -r
219 -r
220 return the pstats.Stats object generated by the profiling. This
220 return the pstats.Stats object generated by the profiling. This
221 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
222 later use it for further analysis or in other functions.
222 later use it for further analysis or in other functions.
223
223
224 -s <key>
224 -s <key>
225 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
226 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
227 default sorting key is 'time'.
227 default sorting key is 'time'.
228
228
229 The following is copied verbatim from the profile documentation
229 The following is copied verbatim from the profile documentation
230 referenced below:
230 referenced below:
231
231
232 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
233 secondary criteria when the there is equality in all keys selected
233 secondary criteria when the there is equality in all keys selected
234 before them.
234 before them.
235
235
236 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
237 abbreviation is unambiguous. The following are the keys currently
237 abbreviation is unambiguous. The following are the keys currently
238 defined:
238 defined:
239
239
240 ============ =====================
240 ============ =====================
241 Valid Arg Meaning
241 Valid Arg Meaning
242 ============ =====================
242 ============ =====================
243 "calls" call count
243 "calls" call count
244 "cumulative" cumulative time
244 "cumulative" cumulative time
245 "file" file name
245 "file" file name
246 "module" file name
246 "module" file name
247 "pcalls" primitive call count
247 "pcalls" primitive call count
248 "line" line number
248 "line" line number
249 "name" function name
249 "name" function name
250 "nfl" name/file/line
250 "nfl" name/file/line
251 "stdname" standard name
251 "stdname" standard name
252 "time" internal time
252 "time" internal time
253 ============ =====================
253 ============ =====================
254
254
255 Note that all sorts on statistics are in descending order (placing
255 Note that all sorts on statistics are in descending order (placing
256 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
257 searches are in ascending order (i.e., alphabetical). The subtle
257 searches are in ascending order (i.e., alphabetical). The subtle
258 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
259 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
260 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
261 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
262 "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
263 line numbers. In fact, sort_stats("nfl") is the same as
263 line numbers. In fact, sort_stats("nfl") is the same as
264 sort_stats("name", "file", "line").
264 sort_stats("name", "file", "line").
265
265
266 -T <filename>
266 -T <filename>
267 save profile results as shown on screen to a text
267 save profile results as shown on screen to a text
268 file. The profile is still shown on screen.
268 file. The profile is still shown on screen.
269
269
270 -D <filename>
270 -D <filename>
271 save (via dump_stats) profile statistics to given
271 save (via dump_stats) profile statistics to given
272 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
273 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
274 objects. The profile is still shown on screen.
274 objects. The profile is still shown on screen.
275
275
276 -q
276 -q
277 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.
278
278
279 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
280 ``%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
281 contains profiler specific options as described here.
281 contains profiler specific options as described here.
282
282
283 You can read the complete documentation for the profile module with::
283 You can read the complete documentation for the profile module with::
284
284
285 In [1]: import profile; profile.help()
285 In [1]: import profile; profile.help()
286
286
287 .. versionchanged:: 7.3
287 .. versionchanged:: 7.3
288 User variables are no longer expanded,
288 User variables are no longer expanded,
289 the magic line is always left unmodified.
289 the magic line is always left unmodified.
290
290
291 """
291 """
292 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',
293 list_all=True, posix=False)
293 list_all=True, posix=False)
294 if cell is not None:
294 if cell is not None:
295 arg_str += '\n' + cell
295 arg_str += '\n' + cell
296 arg_str = self.shell.transform_cell(arg_str)
296 arg_str = self.shell.transform_cell(arg_str)
297 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)
298
298
299 def _run_with_profiler(self, code, opts, namespace):
299 def _run_with_profiler(self, code, opts, namespace):
300 """
300 """
301 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
301 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
302
302
303 Parameters
303 Parameters
304 ----------
304 ----------
305 code : str
305 code : str
306 Code to be executed.
306 Code to be executed.
307 opts : Struct
307 opts : Struct
308 Options parsed by `self.parse_options`.
308 Options parsed by `self.parse_options`.
309 namespace : dict
309 namespace : dict
310 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
310 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
311
311
312 """
312 """
313
313
314 # Fill default values for unspecified options:
314 # Fill default values for unspecified options:
315 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
315 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
316
316
317 prof = profile.Profile()
317 prof = profile.Profile()
318 try:
318 try:
319 prof = prof.runctx(code, namespace, namespace)
319 prof = prof.runctx(code, namespace, namespace)
320 sys_exit = ''
320 sys_exit = ''
321 except SystemExit:
321 except SystemExit:
322 sys_exit = """*** SystemExit exception caught in code being profiled."""
322 sys_exit = """*** SystemExit exception caught in code being profiled."""
323
323
324 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
324 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
325
325
326 lims = opts.l
326 lims = opts.l
327 if lims:
327 if lims:
328 lims = [] # rebuild lims with ints/floats/strings
328 lims = [] # rebuild lims with ints/floats/strings
329 for lim in opts.l:
329 for lim in opts.l:
330 try:
330 try:
331 lims.append(int(lim))
331 lims.append(int(lim))
332 except ValueError:
332 except ValueError:
333 try:
333 try:
334 lims.append(float(lim))
334 lims.append(float(lim))
335 except ValueError:
335 except ValueError:
336 lims.append(lim)
336 lims.append(lim)
337
337
338 # Trap output.
338 # Trap output.
339 stdout_trap = StringIO()
339 stdout_trap = StringIO()
340 stats_stream = stats.stream
340 stats_stream = stats.stream
341 try:
341 try:
342 stats.stream = stdout_trap
342 stats.stream = stdout_trap
343 stats.print_stats(*lims)
343 stats.print_stats(*lims)
344 finally:
344 finally:
345 stats.stream = stats_stream
345 stats.stream = stats_stream
346
346
347 output = stdout_trap.getvalue()
347 output = stdout_trap.getvalue()
348 output = output.rstrip()
348 output = output.rstrip()
349
349
350 if 'q' not in opts:
350 if 'q' not in opts:
351 page.page(output)
351 page.page(output)
352 print(sys_exit, end=' ')
352 print(sys_exit, end=' ')
353
353
354 dump_file = opts.D[0]
354 dump_file = opts.D[0]
355 text_file = opts.T[0]
355 text_file = opts.T[0]
356 if dump_file:
356 if dump_file:
357 prof.dump_stats(dump_file)
357 prof.dump_stats(dump_file)
358 print(
358 print(
359 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}"
360 )
360 )
361 if text_file:
361 if text_file:
362 pfile = Path(text_file)
362 pfile = Path(text_file)
363 pfile.touch(exist_ok=True)
363 pfile.touch(exist_ok=True)
364 pfile.write_text(output, encoding="utf-8")
364 pfile.write_text(output, encoding="utf-8")
365
365
366 print(
366 print(
367 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}"
368 )
368 )
369
369
370 if 'r' in opts:
370 if 'r' in opts:
371 return stats
371 return stats
372
372
373 return None
373 return None
374
374
375 @line_magic
375 @line_magic
376 def pdb(self, parameter_s=''):
376 def pdb(self, parameter_s=''):
377 """Control the automatic calling of the pdb interactive debugger.
377 """Control the automatic calling of the pdb interactive debugger.
378
378
379 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
379 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
380 argument it works as a toggle.
380 argument it works as a toggle.
381
381
382 When an exception is triggered, IPython can optionally call the
382 When an exception is triggered, IPython can optionally call the
383 interactive pdb debugger after the traceback printout. %pdb toggles
383 interactive pdb debugger after the traceback printout. %pdb toggles
384 this feature on and off.
384 this feature on and off.
385
385
386 The initial state of this feature is set in your configuration
386 The initial state of this feature is set in your configuration
387 file (the option is ``InteractiveShell.pdb``).
387 file (the option is ``InteractiveShell.pdb``).
388
388
389 If you want to just activate the debugger AFTER an exception has fired,
389 If you want to just activate the debugger AFTER an exception has fired,
390 without having to type '%pdb on' and rerunning your code, you can use
390 without having to type '%pdb on' and rerunning your code, you can use
391 the %debug magic."""
391 the %debug magic."""
392
392
393 par = parameter_s.strip().lower()
393 par = parameter_s.strip().lower()
394
394
395 if par:
395 if par:
396 try:
396 try:
397 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
397 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
398 except KeyError:
398 except KeyError:
399 print ('Incorrect argument. Use on/1, off/0, '
399 print ('Incorrect argument. Use on/1, off/0, '
400 'or nothing for a toggle.')
400 'or nothing for a toggle.')
401 return
401 return
402 else:
402 else:
403 # toggle
403 # toggle
404 new_pdb = not self.shell.call_pdb
404 new_pdb = not self.shell.call_pdb
405
405
406 # set on the shell
406 # set on the shell
407 self.shell.call_pdb = new_pdb
407 self.shell.call_pdb = new_pdb
408 print('Automatic pdb calling has been turned',on_off(new_pdb))
408 print('Automatic pdb calling has been turned',on_off(new_pdb))
409
409
410 @magic_arguments.magic_arguments()
410 @magic_arguments.magic_arguments()
411 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
411 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
412 help="""
412 help="""
413 Set break point at LINE in FILE.
413 Set break point at LINE in FILE.
414 """
414 """
415 )
415 )
416 @magic_arguments.argument('statement', nargs='*',
416 @magic_arguments.argument('statement', nargs='*',
417 help="""
417 help="""
418 Code to run in debugger.
418 Code to run in debugger.
419 You can omit this in cell magic mode.
419 You can omit this in cell magic mode.
420 """
420 """
421 )
421 )
422 @no_var_expand
422 @no_var_expand
423 @line_cell_magic
423 @line_cell_magic
424 def debug(self, line='', cell=None):
424 def debug(self, line='', cell=None):
425 """Activate the interactive debugger.
425 """Activate the interactive debugger.
426
426
427 This magic command support two ways of activating debugger.
427 This magic command support two ways of activating debugger.
428 One is to activate debugger before executing code. This way, you
428 One is to activate debugger before executing code. This way, you
429 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.
430 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
431 a breakpoint.
431 a breakpoint.
432
432
433 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
434 activate this mode simply running %debug without any argument.
434 activate this mode simply running %debug without any argument.
435 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
436 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
437 traceback that occurred, so you must call this quickly after an
437 traceback that occurred, so you must call this quickly after an
438 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
439 occurs, it clobbers the previous one.
439 occurs, it clobbers the previous one.
440
440
441 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
442 the %pdb magic for more details.
442 the %pdb magic for more details.
443
443
444 .. versionchanged:: 7.3
444 .. versionchanged:: 7.3
445 When running code, user variables are no longer expanded,
445 When running code, user variables are no longer expanded,
446 the magic line is always left unmodified.
446 the magic line is always left unmodified.
447
447
448 """
448 """
449 args = magic_arguments.parse_argstring(self.debug, line)
449 args = magic_arguments.parse_argstring(self.debug, line)
450
450
451 if not (args.breakpoint or args.statement or cell):
451 if not (args.breakpoint or args.statement or cell):
452 self._debug_post_mortem()
452 self._debug_post_mortem()
453 elif not (args.breakpoint or cell):
453 elif not (args.breakpoint or cell):
454 # 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
455 self._debug_exec(line, None)
455 self._debug_exec(line, None)
456 else:
456 else:
457 # Here we try to reconstruct the code from the output of
457 # Here we try to reconstruct the code from the output of
458 # parse_argstring. This might not work if the code has spaces
458 # parse_argstring. This might not work if the code has spaces
459 # For example this fails for `print("a b")`
459 # For example this fails for `print("a b")`
460 code = "\n".join(args.statement)
460 code = "\n".join(args.statement)
461 if cell:
461 if cell:
462 code += "\n" + cell
462 code += "\n" + cell
463 self._debug_exec(code, args.breakpoint)
463 self._debug_exec(code, args.breakpoint)
464
464
465 def _debug_post_mortem(self):
465 def _debug_post_mortem(self):
466 self.shell.debugger(force=True)
466 self.shell.debugger(force=True)
467
467
468 def _debug_exec(self, code, breakpoint):
468 def _debug_exec(self, code, breakpoint):
469 if breakpoint:
469 if breakpoint:
470 (filename, bp_line) = breakpoint.rsplit(':', 1)
470 (filename, bp_line) = breakpoint.rsplit(':', 1)
471 bp_line = int(bp_line)
471 bp_line = int(bp_line)
472 else:
472 else:
473 (filename, bp_line) = (None, None)
473 (filename, bp_line) = (None, None)
474 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)
475
475
476 @line_magic
476 @line_magic
477 def tb(self, s):
477 def tb(self, s):
478 """Print the last traceback.
478 """Print the last traceback.
479
479
480 Optionally, specify an exception reporting mode, tuning the
480 Optionally, specify an exception reporting mode, tuning the
481 verbosity of the traceback. By default the currently-active exception
481 verbosity of the traceback. By default the currently-active exception
482 mode is used. See %xmode for changing exception reporting modes.
482 mode is used. See %xmode for changing exception reporting modes.
483
483
484 Valid modes: Plain, Context, Verbose, and Minimal.
484 Valid modes: Plain, Context, Verbose, and Minimal.
485 """
485 """
486 interactive_tb = self.shell.InteractiveTB
486 interactive_tb = self.shell.InteractiveTB
487 if s:
487 if s:
488 # Switch exception reporting mode for this one call.
488 # Switch exception reporting mode for this one call.
489 # Ensure it is switched back.
489 # Ensure it is switched back.
490 def xmode_switch_err(name):
490 def xmode_switch_err(name):
491 warn('Error changing %s exception modes.\n%s' %
491 warn('Error changing %s exception modes.\n%s' %
492 (name,sys.exc_info()[1]))
492 (name,sys.exc_info()[1]))
493
493
494 new_mode = s.strip().capitalize()
494 new_mode = s.strip().capitalize()
495 original_mode = interactive_tb.mode
495 original_mode = interactive_tb.mode
496 try:
496 try:
497 try:
497 try:
498 interactive_tb.set_mode(mode=new_mode)
498 interactive_tb.set_mode(mode=new_mode)
499 except Exception:
499 except Exception:
500 xmode_switch_err('user')
500 xmode_switch_err('user')
501 else:
501 else:
502 self.shell.showtraceback()
502 self.shell.showtraceback()
503 finally:
503 finally:
504 interactive_tb.set_mode(mode=original_mode)
504 interactive_tb.set_mode(mode=original_mode)
505 else:
505 else:
506 self.shell.showtraceback()
506 self.shell.showtraceback()
507
507
508 @skip_doctest
508 @skip_doctest
509 @line_magic
509 @line_magic
510 def run(self, parameter_s='', runner=None,
510 def run(self, parameter_s='', runner=None,
511 file_finder=get_py_filename):
511 file_finder=get_py_filename):
512 """Run the named file inside IPython as a program.
512 """Run the named file inside IPython as a program.
513
513
514 Usage::
514 Usage::
515
515
516 %run [-n -i -e -G]
516 %run [-n -i -e -G]
517 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
517 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
518 ( -m mod | filename ) [args]
518 ( -m mod | filename ) [args]
519
519
520 The filename argument should be either a pure Python script (with
520 The filename argument should be either a pure Python script (with
521 extension ``.py``), or a file with custom IPython syntax (such as
521 extension ``.py``), or a file with custom IPython syntax (such as
522 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``
523 extension, or a Jupyter notebook with ``.ipynb`` extension. When running
523 extension, or a Jupyter notebook with ``.ipynb`` extension. When running
524 a Jupyter notebook, the output from print statements and other
524 a Jupyter notebook, the output from print statements and other
525 displayed objects will appear in the terminal (even matplotlib figures
525 displayed objects will appear in the terminal (even matplotlib figures
526 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,
527 at the system command line, the ``jupyter run`` command offers similar
527 at the system command line, the ``jupyter run`` command offers similar
528 functionality for executing notebooks (albeit currently with some
528 functionality for executing notebooks (albeit currently with some
529 differences in supported options).
529 differences in supported options).
530
530
531 Parameters after the filename are passed as command-line arguments to
531 Parameters after the filename are passed as command-line arguments to
532 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
533 prompt.
533 prompt.
534
534
535 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``,
536 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
537 loading all variables into your interactive namespace for further use
537 loading all variables into your interactive namespace for further use
538 (unless -p is used, see below).
538 (unless -p is used, see below).
539
539
540 The file is executed in a namespace initially consisting only of
540 The file is executed in a namespace initially consisting only of
541 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
541 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
542 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
543 (except for sharing global objects such as previously imported
543 (except for sharing global objects such as previously imported
544 modules). But after execution, the IPython interactive namespace gets
544 modules). But after execution, the IPython interactive namespace gets
545 updated with all variables defined in the program (except for __name__
545 updated with all variables defined in the program (except for __name__
546 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
547 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.
548
548
549 Arguments are expanded using shell-like glob match. Patterns
549 Arguments are expanded using shell-like glob match. Patterns
550 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
550 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
551 tilde '~' will be expanded into user's home directory. Unlike
551 tilde '~' will be expanded into user's home directory. Unlike
552 real shells, quotation does not suppress expansions. Use
552 real shells, quotation does not suppress expansions. Use
553 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
553 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
554 To completely disable these expansions, you can use -G flag.
554 To completely disable these expansions, you can use -G flag.
555
555
556 On Windows systems, the use of single quotes `'` when specifying
556 On Windows systems, the use of single quotes `'` when specifying
557 a file is not supported. Use double quotes `"`.
557 a file is not supported. Use double quotes `"`.
558
558
559 Options:
559 Options:
560
560
561 -n
561 -n
562 __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
563 without extension (as python does under import). This allows running
563 without extension (as python does under import). This allows running
564 scripts and reloading the definitions in them without calling code
564 scripts and reloading the definitions in them without calling code
565 protected by an ``if __name__ == "__main__"`` clause.
565 protected by an ``if __name__ == "__main__"`` clause.
566
566
567 -i
567 -i
568 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
569 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
570 which depends on variables defined interactively.
570 which depends on variables defined interactively.
571
571
572 -e
572 -e
573 ignore sys.exit() calls or SystemExit exceptions in the script
573 ignore sys.exit() calls or SystemExit exceptions in the script
574 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
575 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
576 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
577 seeing a traceback of the unittest module.
577 seeing a traceback of the unittest module.
578
578
579 -t
579 -t
580 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
581 you an estimated CPU time consumption for your script, which under
581 you an estimated CPU time consumption for your script, which under
582 Unix uses the resource module to avoid the wraparound problems of
582 Unix uses the resource module to avoid the wraparound problems of
583 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
584 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).
585
585
586 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>
587 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
588 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.
589
589
590 For example (testing the script uniq_stable.py)::
590 For example (testing the script uniq_stable.py)::
591
591
592 In [1]: run -t uniq_stable
592 In [1]: run -t uniq_stable
593
593
594 IPython CPU timings (estimated):
594 IPython CPU timings (estimated):
595 User : 0.19597 s.
595 User : 0.19597 s.
596 System: 0.0 s.
596 System: 0.0 s.
597
597
598 In [2]: run -t -N5 uniq_stable
598 In [2]: run -t -N5 uniq_stable
599
599
600 IPython CPU timings (estimated):
600 IPython CPU timings (estimated):
601 Total runs performed: 5
601 Total runs performed: 5
602 Times : Total Per run
602 Times : Total Per run
603 User : 0.910862 s, 0.1821724 s.
603 User : 0.910862 s, 0.1821724 s.
604 System: 0.0 s, 0.0 s.
604 System: 0.0 s, 0.0 s.
605
605
606 -d
606 -d
607 run your program under the control of pdb, the Python debugger.
607 run your program under the control of pdb, the Python debugger.
608 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,
609 etc. Internally, what IPython does is similar to calling::
609 etc. Internally, what IPython does is similar to calling::
610
610
611 pdb.run('execfile("YOURFILENAME")')
611 pdb.run('execfile("YOURFILENAME")')
612
612
613 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
614 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
615 (where N must be an integer). For example::
615 (where N must be an integer). For example::
616
616
617 %run -d -b40 myscript
617 %run -d -b40 myscript
618
618
619 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
620 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
621 something (not a comment or docstring) for it to stop execution.
621 something (not a comment or docstring) for it to stop execution.
622
622
623 Or you can specify a breakpoint in a different file::
623 Or you can specify a breakpoint in a different file::
624
624
625 %run -d -b myotherfile.py:20 myscript
625 %run -d -b myotherfile.py:20 myscript
626
626
627 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
628 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
629 breakpoint.
629 breakpoint.
630
630
631 Entering 'help' gives information about the use of the debugger. You
631 Entering 'help' gives information about the use of the debugger. You
632 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()"
633 at a prompt.
633 at a prompt.
634
634
635 -p
635 -p
636 run program under the control of the Python profiler module (which
636 run program under the control of the Python profiler module (which
637 prints a detailed report of execution times, function calls, etc).
637 prints a detailed report of execution times, function calls, etc).
638
638
639 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
640 profiler itself. See the docs for %prun for details.
640 profiler itself. See the docs for %prun for details.
641
641
642 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
643 IPython interactive namespace (because they remain in the namespace
643 IPython interactive namespace (because they remain in the namespace
644 where the profiler executes them).
644 where the profiler executes them).
645
645
646 Internally this triggers a call to %prun, see its documentation for
646 Internally this triggers a call to %prun, see its documentation for
647 details on the options available specifically for profiling.
647 details on the options available specifically for profiling.
648
648
649 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:
650 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,
651 just as if the commands were written on IPython prompt.
651 just as if the commands were written on IPython prompt.
652
652
653 -m
653 -m
654 specify module name to load instead of script path. Similar to
654 specify module name to load instead of script path. Similar to
655 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
656 want to combine with other %run options. Unlike the python interpreter
656 want to combine with other %run options. Unlike the python interpreter
657 only source modules are allowed no .pyc or .pyo files.
657 only source modules are allowed no .pyc or .pyo files.
658 For example::
658 For example::
659
659
660 %run -m example
660 %run -m example
661
661
662 will run the example module.
662 will run the example module.
663
663
664 -G
664 -G
665 disable shell-like glob expansion of arguments.
665 disable shell-like glob expansion of arguments.
666
666
667 """
667 """
668
668
669 # Logic to handle issue #3664
669 # Logic to handle issue #3664
670 # 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.
671 if '-m' in parameter_s and '--' not in parameter_s:
671 if '-m' in parameter_s and '--' not in parameter_s:
672 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
672 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
673 for idx, arg in enumerate(argv):
673 for idx, arg in enumerate(argv):
674 if arg and arg.startswith('-') and arg != '-':
674 if arg and arg.startswith('-') and arg != '-':
675 if arg == '-m':
675 if arg == '-m':
676 argv.insert(idx + 2, '--')
676 argv.insert(idx + 2, '--')
677 break
677 break
678 else:
678 else:
679 # Positional arg, break
679 # Positional arg, break
680 break
680 break
681 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
681 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
682
682
683 # get arguments and set sys.argv for program to be run.
683 # get arguments and set sys.argv for program to be run.
684 opts, arg_lst = self.parse_options(parameter_s,
684 opts, arg_lst = self.parse_options(parameter_s,
685 'nidtN:b:pD:l:rs:T:em:G',
685 'nidtN:b:pD:l:rs:T:em:G',
686 mode='list', list_all=1)
686 mode='list', list_all=1)
687 if "m" in opts:
687 if "m" in opts:
688 modulename = opts["m"][0]
688 modulename = opts["m"][0]
689 modpath = find_mod(modulename)
689 modpath = find_mod(modulename)
690 if modpath is None:
690 if modpath is None:
691 msg = '%r is not a valid modulename on sys.path'%modulename
691 msg = '%r is not a valid modulename on sys.path'%modulename
692 raise Exception(msg)
692 raise Exception(msg)
693 arg_lst = [modpath] + arg_lst
693 arg_lst = [modpath] + arg_lst
694 try:
694 try:
695 fpath = None # initialize to make sure fpath is in scope later
695 fpath = None # initialize to make sure fpath is in scope later
696 fpath = arg_lst[0]
696 fpath = arg_lst[0]
697 filename = file_finder(fpath)
697 filename = file_finder(fpath)
698 except IndexError as e:
698 except IndexError as e:
699 msg = 'you must provide at least a filename.'
699 msg = 'you must provide at least a filename.'
700 raise Exception(msg) from e
700 raise Exception(msg) from e
701 except IOError as e:
701 except IOError as e:
702 try:
702 try:
703 msg = str(e)
703 msg = str(e)
704 except UnicodeError:
704 except UnicodeError:
705 msg = e.message
705 msg = e.message
706 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
706 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
707 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"')
708 raise Exception(msg) from e
708 raise Exception(msg) from e
709 except TypeError:
709 except TypeError:
710 if fpath in sys.meta_path:
710 if fpath in sys.meta_path:
711 filename = ""
711 filename = ""
712 else:
712 else:
713 raise
713 raise
714
714
715 if filename.lower().endswith(('.ipy', '.ipynb')):
715 if filename.lower().endswith(('.ipy', '.ipynb')):
716 with preserve_keys(self.shell.user_ns, '__file__'):
716 with preserve_keys(self.shell.user_ns, '__file__'):
717 self.shell.user_ns['__file__'] = filename
717 self.shell.user_ns['__file__'] = filename
718 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
718 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
719 return
719 return
720
720
721 # 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
722 exit_ignore = 'e' in opts
722 exit_ignore = 'e' in opts
723
723
724 # 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
725 # were run from a system shell.
725 # were run from a system shell.
726 save_argv = sys.argv # save it for later restoring
726 save_argv = sys.argv # save it for later restoring
727
727
728 if 'G' in opts:
728 if 'G' in opts:
729 args = arg_lst[1:]
729 args = arg_lst[1:]
730 else:
730 else:
731 # tilde and glob expansion
731 # tilde and glob expansion
732 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
732 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
733
733
734 sys.argv = [filename] + args # put in the proper filename
734 sys.argv = [filename] + args # put in the proper filename
735
735
736 if 'n' in opts:
736 if 'n' in opts:
737 name = Path(filename).stem
737 name = Path(filename).stem
738 else:
738 else:
739 name = '__main__'
739 name = '__main__'
740
740
741 if 'i' in opts:
741 if 'i' in opts:
742 # Run in user's interactive namespace
742 # Run in user's interactive namespace
743 prog_ns = self.shell.user_ns
743 prog_ns = self.shell.user_ns
744 __name__save = self.shell.user_ns['__name__']
744 __name__save = self.shell.user_ns['__name__']
745 prog_ns['__name__'] = name
745 prog_ns['__name__'] = name
746 main_mod = self.shell.user_module
746 main_mod = self.shell.user_module
747
747
748 # 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
749 # set the __file__ global in the script's namespace
749 # set the __file__ global in the script's namespace
750 # TK: Is this necessary in interactive mode?
750 # TK: Is this necessary in interactive mode?
751 prog_ns['__file__'] = filename
751 prog_ns['__file__'] = filename
752 else:
752 else:
753 # Run in a fresh, empty namespace
753 # Run in a fresh, empty namespace
754
754
755 # 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
756 # exits, the python deletion mechanism doesn't zero it out
756 # exits, the python deletion mechanism doesn't zero it out
757 # (leaving dangling references). See interactiveshell for details
757 # (leaving dangling references). See interactiveshell for details
758 main_mod = self.shell.new_main_mod(filename, name)
758 main_mod = self.shell.new_main_mod(filename, name)
759 prog_ns = main_mod.__dict__
759 prog_ns = main_mod.__dict__
760
760
761 # pickle fix. See interactiveshell for an explanation. But we need to
761 # pickle fix. See interactiveshell for an explanation. But we need to
762 # 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
763 main_mod_name = prog_ns['__name__']
763 main_mod_name = prog_ns['__name__']
764
764
765 if main_mod_name == '__main__':
765 if main_mod_name == '__main__':
766 restore_main = sys.modules['__main__']
766 restore_main = sys.modules['__main__']
767 else:
767 else:
768 restore_main = False
768 restore_main = False
769
769
770 # 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
771 # every single object ever created.
771 # every single object ever created.
772 sys.modules[main_mod_name] = main_mod
772 sys.modules[main_mod_name] = main_mod
773
773
774 if 'p' in opts or 'd' in opts:
774 if 'p' in opts or 'd' in opts:
775 if 'm' in opts:
775 if 'm' in opts:
776 code = 'run_module(modulename, prog_ns)'
776 code = 'run_module(modulename, prog_ns)'
777 code_ns = {
777 code_ns = {
778 'run_module': self.shell.safe_run_module,
778 'run_module': self.shell.safe_run_module,
779 'prog_ns': prog_ns,
779 'prog_ns': prog_ns,
780 'modulename': modulename,
780 'modulename': modulename,
781 }
781 }
782 else:
782 else:
783 if 'd' in opts:
783 if 'd' in opts:
784 # allow exceptions to raise in debug mode
784 # allow exceptions to raise in debug mode
785 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
785 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
786 else:
786 else:
787 code = 'execfile(filename, prog_ns)'
787 code = 'execfile(filename, prog_ns)'
788 code_ns = {
788 code_ns = {
789 'execfile': self.shell.safe_execfile,
789 'execfile': self.shell.safe_execfile,
790 'prog_ns': prog_ns,
790 'prog_ns': prog_ns,
791 'filename': get_py_filename(filename),
791 'filename': get_py_filename(filename),
792 }
792 }
793
793
794 try:
794 try:
795 stats = None
795 stats = None
796 if 'p' in opts:
796 if 'p' in opts:
797 stats = self._run_with_profiler(code, opts, code_ns)
797 stats = self._run_with_profiler(code, opts, code_ns)
798 else:
798 else:
799 if 'd' in opts:
799 if 'd' in opts:
800 bp_file, bp_line = parse_breakpoint(
800 bp_file, bp_line = parse_breakpoint(
801 opts.get('b', ['1'])[0], filename)
801 opts.get('b', ['1'])[0], filename)
802 self._run_with_debugger(
802 self._run_with_debugger(
803 code, code_ns, filename, bp_line, bp_file)
803 code, code_ns, filename, bp_line, bp_file)
804 else:
804 else:
805 if 'm' in opts:
805 if 'm' in opts:
806 def run():
806 def run():
807 self.shell.safe_run_module(modulename, prog_ns)
807 self.shell.safe_run_module(modulename, prog_ns)
808 else:
808 else:
809 if runner is None:
809 if runner is None:
810 runner = self.default_runner
810 runner = self.default_runner
811 if runner is None:
811 if runner is None:
812 runner = self.shell.safe_execfile
812 runner = self.shell.safe_execfile
813
813
814 def run():
814 def run():
815 runner(filename, prog_ns, prog_ns,
815 runner(filename, prog_ns, prog_ns,
816 exit_ignore=exit_ignore)
816 exit_ignore=exit_ignore)
817
817
818 if 't' in opts:
818 if 't' in opts:
819 # timed execution
819 # timed execution
820 try:
820 try:
821 nruns = int(opts['N'][0])
821 nruns = int(opts['N'][0])
822 if nruns < 1:
822 if nruns < 1:
823 error('Number of runs must be >=1')
823 error('Number of runs must be >=1')
824 return
824 return
825 except (KeyError):
825 except (KeyError):
826 nruns = 1
826 nruns = 1
827 self._run_with_timing(run, nruns)
827 self._run_with_timing(run, nruns)
828 else:
828 else:
829 # regular execution
829 # regular execution
830 run()
830 run()
831
831
832 if 'i' in opts:
832 if 'i' in opts:
833 self.shell.user_ns['__name__'] = __name__save
833 self.shell.user_ns['__name__'] = __name__save
834 else:
834 else:
835 # update IPython interactive namespace
835 # update IPython interactive namespace
836
836
837 # Some forms of read errors on the file may mean the
837 # Some forms of read errors on the file may mean the
838 # __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
839 # worry about a possible KeyError.
839 # worry about a possible KeyError.
840 prog_ns.pop('__name__', None)
840 prog_ns.pop('__name__', None)
841
841
842 with preserve_keys(self.shell.user_ns, '__file__'):
842 with preserve_keys(self.shell.user_ns, '__file__'):
843 self.shell.user_ns.update(prog_ns)
843 self.shell.user_ns.update(prog_ns)
844 finally:
844 finally:
845 # 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
846 # 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
847 # %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
848 # at all, and similar problems have been reported before:
848 # at all, and similar problems have been reported before:
849 # 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
850 # 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
851 # 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
852 # exit.
852 # exit.
853 self.shell.user_ns['__builtins__'] = builtin_mod
853 self.shell.user_ns['__builtins__'] = builtin_mod
854
854
855 # Ensure key global structures are restored
855 # Ensure key global structures are restored
856 sys.argv = save_argv
856 sys.argv = save_argv
857 if restore_main:
857 if restore_main:
858 sys.modules['__main__'] = restore_main
858 sys.modules['__main__'] = restore_main
859 if '__mp_main__' in sys.modules:
859 if '__mp_main__' in sys.modules:
860 sys.modules['__mp_main__'] = restore_main
860 sys.modules['__mp_main__'] = restore_main
861 else:
861 else:
862 # Remove from sys.modules the reference to main_mod we'd
862 # Remove from sys.modules the reference to main_mod we'd
863 # added. Otherwise it will trap references to objects
863 # added. Otherwise it will trap references to objects
864 # contained therein.
864 # contained therein.
865 del sys.modules[main_mod_name]
865 del sys.modules[main_mod_name]
866
866
867 return stats
867 return stats
868
868
869 def _run_with_debugger(self, code, code_ns, filename=None,
869 def _run_with_debugger(self, code, code_ns, filename=None,
870 bp_line=None, bp_file=None):
870 bp_line=None, bp_file=None):
871 """
871 """
872 Run `code` in debugger with a break point.
872 Run `code` in debugger with a break point.
873
873
874 Parameters
874 Parameters
875 ----------
875 ----------
876 code : str
876 code : str
877 Code to execute.
877 Code to execute.
878 code_ns : dict
878 code_ns : dict
879 A namespace in which `code` is executed.
879 A namespace in which `code` is executed.
880 filename : str
880 filename : str
881 `code` is ran as if it is in `filename`.
881 `code` is ran as if it is in `filename`.
882 bp_line : int, optional
882 bp_line : int, optional
883 Line number of the break point.
883 Line number of the break point.
884 bp_file : str, optional
884 bp_file : str, optional
885 Path to the file in which break point is specified.
885 Path to the file in which break point is specified.
886 `filename` is used if not given.
886 `filename` is used if not given.
887
887
888 Raises
888 Raises
889 ------
889 ------
890 UsageError
890 UsageError
891 If the break point given by `bp_line` is not valid.
891 If the break point given by `bp_line` is not valid.
892
892
893 """
893 """
894 deb = self.shell.InteractiveTB.pdb
894 deb = self.shell.InteractiveTB.pdb
895 if not deb:
895 if not deb:
896 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
896 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
897 deb = self.shell.InteractiveTB.pdb
897 deb = self.shell.InteractiveTB.pdb
898
898
899 # 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
900 # handle it not existing. https://github.com/ipython/ipython/issues/10028
900 # handle it not existing. https://github.com/ipython/ipython/issues/10028
901 if hasattr(deb, 'curframe'):
901 if hasattr(deb, 'curframe'):
902 del deb.curframe
902 del deb.curframe
903
903
904 # reset Breakpoint state, which is moronically kept
904 # reset Breakpoint state, which is moronically kept
905 # in a class
905 # in a class
906 bdb.Breakpoint.next = 1
906 bdb.Breakpoint.next = 1
907 bdb.Breakpoint.bplist = {}
907 bdb.Breakpoint.bplist = {}
908 bdb.Breakpoint.bpbynumber = [None]
908 bdb.Breakpoint.bpbynumber = [None]
909 deb.clear_all_breaks()
909 deb.clear_all_breaks()
910 if bp_line is not None:
910 if bp_line is not None:
911 # Set an initial breakpoint to stop execution
911 # Set an initial breakpoint to stop execution
912 maxtries = 10
912 maxtries = 10
913 bp_file = bp_file or filename
913 bp_file = bp_file or filename
914 checkline = deb.checkline(bp_file, bp_line)
914 checkline = deb.checkline(bp_file, bp_line)
915 if not checkline:
915 if not checkline:
916 for bp in range(bp_line + 1, bp_line + maxtries + 1):
916 for bp in range(bp_line + 1, bp_line + maxtries + 1):
917 if deb.checkline(bp_file, bp):
917 if deb.checkline(bp_file, bp):
918 break
918 break
919 else:
919 else:
920 msg = ("\nI failed to find a valid line to set "
920 msg = ("\nI failed to find a valid line to set "
921 "a breakpoint\n"
921 "a breakpoint\n"
922 "after trying up to line: %s.\n"
922 "after trying up to line: %s.\n"
923 "Please set a valid breakpoint manually "
923 "Please set a valid breakpoint manually "
924 "with the -b option." % bp)
924 "with the -b option." % bp)
925 raise UsageError(msg)
925 raise UsageError(msg)
926 # if we find a good linenumber, set the breakpoint
926 # if we find a good linenumber, set the breakpoint
927 deb.do_break('%s:%s' % (bp_file, bp_line))
927 deb.do_break('%s:%s' % (bp_file, bp_line))
928
928
929 if filename:
929 if filename:
930 # Mimic Pdb._runscript(...)
930 # Mimic Pdb._runscript(...)
931 deb._wait_for_mainpyfile = True
931 deb._wait_for_mainpyfile = True
932 deb.mainpyfile = deb.canonic(filename)
932 deb.mainpyfile = deb.canonic(filename)
933
933
934 # Start file run
934 # Start file run
935 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)
936 try:
936 try:
937 if filename:
937 if filename:
938 # 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
939 deb._exec_filename = filename
939 deb._exec_filename = filename
940 while True:
940 while True:
941 try:
941 try:
942 trace = sys.gettrace()
942 trace = sys.gettrace()
943 deb.run(code, code_ns)
943 deb.run(code, code_ns)
944 except Restart:
944 except Restart:
945 print("Restarting")
945 print("Restarting")
946 if filename:
946 if filename:
947 deb._wait_for_mainpyfile = True
947 deb._wait_for_mainpyfile = True
948 deb.mainpyfile = deb.canonic(filename)
948 deb.mainpyfile = deb.canonic(filename)
949 continue
949 continue
950 else:
950 else:
951 break
951 break
952 finally:
952 finally:
953 sys.settrace(trace)
953 sys.settrace(trace)
954
954
955
955
956 except:
956 except:
957 etype, value, tb = sys.exc_info()
957 etype, value, tb = sys.exc_info()
958 # Skip three frames in the traceback: the %run one,
958 # Skip three frames in the traceback: the %run one,
959 # one inside bdb.py, and the command-line typed by the
959 # one inside bdb.py, and the command-line typed by the
960 # user (run by exec in pdb itself).
960 # user (run by exec in pdb itself).
961 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
961 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
962
962
963 @staticmethod
963 @staticmethod
964 def _run_with_timing(run, nruns):
964 def _run_with_timing(run, nruns):
965 """
965 """
966 Run function `run` and print timing information.
966 Run function `run` and print timing information.
967
967
968 Parameters
968 Parameters
969 ----------
969 ----------
970 run : callable
970 run : callable
971 Any callable object which takes no argument.
971 Any callable object which takes no argument.
972 nruns : int
972 nruns : int
973 Number of times to execute `run`.
973 Number of times to execute `run`.
974
974
975 """
975 """
976 twall0 = time.perf_counter()
976 twall0 = time.perf_counter()
977 if nruns == 1:
977 if nruns == 1:
978 t0 = clock2()
978 t0 = clock2()
979 run()
979 run()
980 t1 = clock2()
980 t1 = clock2()
981 t_usr = t1[0] - t0[0]
981 t_usr = t1[0] - t0[0]
982 t_sys = t1[1] - t0[1]
982 t_sys = t1[1] - t0[1]
983 print("\nIPython CPU timings (estimated):")
983 print("\nIPython CPU timings (estimated):")
984 print(" User : %10.2f s." % t_usr)
984 print(" User : %10.2f s." % t_usr)
985 print(" System : %10.2f s." % t_sys)
985 print(" System : %10.2f s." % t_sys)
986 else:
986 else:
987 runs = range(nruns)
987 runs = range(nruns)
988 t0 = clock2()
988 t0 = clock2()
989 for nr in runs:
989 for nr in runs:
990 run()
990 run()
991 t1 = clock2()
991 t1 = clock2()
992 t_usr = t1[0] - t0[0]
992 t_usr = t1[0] - t0[0]
993 t_sys = t1[1] - t0[1]
993 t_sys = t1[1] - t0[1]
994 print("\nIPython CPU timings (estimated):")
994 print("\nIPython CPU timings (estimated):")
995 print("Total runs performed:", nruns)
995 print("Total runs performed:", nruns)
996 print(" Times : %10s %10s" % ('Total', 'Per run'))
996 print(" Times : %10s %10s" % ('Total', 'Per run'))
997 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))
998 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))
999 twall1 = time.perf_counter()
999 twall1 = time.perf_counter()
1000 print("Wall time: %10.2f s." % (twall1 - twall0))
1000 print("Wall time: %10.2f s." % (twall1 - twall0))
1001
1001
1002 @skip_doctest
1002 @skip_doctest
1003 @no_var_expand
1003 @no_var_expand
1004 @line_cell_magic
1004 @line_cell_magic
1005 @needs_local_scope
1005 @needs_local_scope
1006 def timeit(self, line='', cell=None, local_ns=None):
1006 def timeit(self, line='', cell=None, local_ns=None):
1007 """Time execution of a Python statement or expression
1007 """Time execution of a Python statement or expression
1008
1008
1009 Usage, in line mode:
1009 Usage, in line mode:
1010 %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
1011 or in cell mode:
1011 or in cell mode:
1012 %%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
1013 code
1013 code
1014 code...
1014 code...
1015
1015
1016 Time execution of a Python statement or expression using the timeit
1016 Time execution of a Python statement or expression using the timeit
1017 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:
1018
1018
1019 - 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
1020 ones can be chained with using semicolons).
1020 ones can be chained with using semicolons).
1021
1021
1022 - 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
1023 (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
1024 body has access to any variables created in the setup code.
1024 body has access to any variables created in the setup code.
1025
1025
1026 Options:
1026 Options:
1027 -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
1028 provided, <N> is determined so as to get sufficient accuracy.
1028 provided, <N> is determined so as to get sufficient accuracy.
1029
1029
1030 -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
1031 best result.
1031 best result.
1032 Default: 7
1032 Default: 7
1033
1033
1034 -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.
1035 This function measures wall time.
1035 This function measures wall time.
1036
1036
1037 -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
1038 Windows and measures wall time. On Unix, resource.getrusage is used
1038 Windows and measures wall time. On Unix, resource.getrusage is used
1039 instead and returns the CPU user time.
1039 instead and returns the CPU user time.
1040
1040
1041 -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.
1042 Default: 3
1042 Default: 3
1043
1043
1044 -q: Quiet, do not print result.
1044 -q: Quiet, do not print result.
1045
1045
1046 -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
1047 the result in more details.
1047 the result in more details.
1048
1048
1049 .. versionchanged:: 7.3
1049 .. versionchanged:: 7.3
1050 User variables are no longer expanded,
1050 User variables are no longer expanded,
1051 the magic line is always left unmodified.
1051 the magic line is always left unmodified.
1052
1052
1053 Examples
1053 Examples
1054 --------
1054 --------
1055 ::
1055 ::
1056
1056
1057 In [1]: %timeit pass
1057 In [1]: %timeit pass
1058 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)
1059
1059
1060 In [2]: u = None
1060 In [2]: u = None
1061
1061
1062 In [3]: %timeit u is None
1062 In [3]: %timeit u is None
1063 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)
1064
1064
1065 In [4]: %timeit -r 4 u == None
1065 In [4]: %timeit -r 4 u == None
1066
1066
1067 In [5]: import time
1067 In [5]: import time
1068
1068
1069 In [6]: %timeit -n1 time.sleep(2)
1069 In [6]: %timeit -n1 time.sleep(2)
1070
1070
1071 The times reported by %timeit will be slightly higher than those
1071 The times reported by %timeit will be slightly higher than those
1072 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
1073 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
1074 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
1075 statement to import function or create variables. Generally, the bias
1075 statement to import function or create variables. Generally, the bias
1076 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
1077 those from %timeit."""
1077 those from %timeit."""
1078
1078
1079 opts, stmt = self.parse_options(
1079 opts, stmt = self.parse_options(
1080 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
1081 )
1081 )
1082 if stmt == "" and cell is None:
1082 if stmt == "" and cell is None:
1083 return
1083 return
1084
1084
1085 timefunc = timeit.default_timer
1085 timefunc = timeit.default_timer
1086 number = int(getattr(opts, "n", 0))
1086 number = int(getattr(opts, "n", 0))
1087 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
1088 repeat = int(getattr(opts, "r", default_repeat))
1088 repeat = int(getattr(opts, "r", default_repeat))
1089 precision = int(getattr(opts, "p", 3))
1089 precision = int(getattr(opts, "p", 3))
1090 quiet = 'q' in opts
1090 quiet = 'q' in opts
1091 return_result = 'o' in opts
1091 return_result = 'o' in opts
1092 if hasattr(opts, "t"):
1092 if hasattr(opts, "t"):
1093 timefunc = time.time
1093 timefunc = time.time
1094 if hasattr(opts, "c"):
1094 if hasattr(opts, "c"):
1095 timefunc = clock
1095 timefunc = clock
1096
1096
1097 timer = Timer(timer=timefunc)
1097 timer = Timer(timer=timefunc)
1098 # 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,
1099 # 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
1100 # to the shell namespace?
1100 # to the shell namespace?
1101 transform = self.shell.transform_cell
1101 transform = self.shell.transform_cell
1102
1102
1103 if cell is None:
1103 if cell is None:
1104 # called as line magic
1104 # called as line magic
1105 ast_setup = self.shell.compile.ast_parse("pass")
1105 ast_setup = self.shell.compile.ast_parse("pass")
1106 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1106 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1107 else:
1107 else:
1108 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1108 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1109 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1109 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1110
1110
1111 ast_setup = self.shell.transform_ast(ast_setup)
1111 ast_setup = self.shell.transform_ast(ast_setup)
1112 ast_stmt = self.shell.transform_ast(ast_stmt)
1112 ast_stmt = self.shell.transform_ast(ast_stmt)
1113
1113
1114 # 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
1115 # Invalid code may become valid when put inside the function & loop,
1115 # Invalid code may become valid when put inside the function & loop,
1116 # which messes up error messages.
1116 # which messes up error messages.
1117 # https://github.com/ipython/ipython/issues/10636
1117 # https://github.com/ipython/ipython/issues/10636
1118 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1118 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1119 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1119 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1120
1120
1121 # 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
1122 # 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
1123 # without affecting the timing code.
1123 # without affecting the timing code.
1124 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1124 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1125 ' setup\n'
1125 ' setup\n'
1126 ' _t0 = _timer()\n'
1126 ' _t0 = _timer()\n'
1127 ' for _i in _it:\n'
1127 ' for _i in _it:\n'
1128 ' stmt\n'
1128 ' stmt\n'
1129 ' _t1 = _timer()\n'
1129 ' _t1 = _timer()\n'
1130 ' return _t1 - _t0\n')
1130 ' return _t1 - _t0\n')
1131
1131
1132 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1132 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1133 timeit_ast = ast.fix_missing_locations(timeit_ast)
1133 timeit_ast = ast.fix_missing_locations(timeit_ast)
1134
1134
1135 # Track compilation time so it can be reported if too long
1135 # Track compilation time so it can be reported if too long
1136 # Minimum time above which compilation time will be reported
1136 # Minimum time above which compilation time will be reported
1137 tc_min = 0.1
1137 tc_min = 0.1
1138
1138
1139 t0 = clock()
1139 t0 = clock()
1140 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1140 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1141 tc = clock()-t0
1141 tc = clock()-t0
1142
1142
1143 ns = {}
1143 ns = {}
1144 glob = self.shell.user_ns
1144 glob = self.shell.user_ns
1145 # 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.
1146 conflict_globs = {}
1146 conflict_globs = {}
1147 if local_ns and cell is None:
1147 if local_ns and cell is None:
1148 for var_name, var_val in glob.items():
1148 for var_name, var_val in glob.items():
1149 if var_name in local_ns:
1149 if var_name in local_ns:
1150 conflict_globs[var_name] = var_val
1150 conflict_globs[var_name] = var_val
1151 glob.update(local_ns)
1151 glob.update(local_ns)
1152
1152
1153 exec(code, glob, ns)
1153 exec(code, glob, ns)
1154 timer.inner = ns["inner"]
1154 timer.inner = ns["inner"]
1155
1155
1156 # 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
1157 # best and worst timings.
1157 # best and worst timings.
1158 # Issue: https://github.com/ipython/ipython/issues/6471
1158 # Issue: https://github.com/ipython/ipython/issues/6471
1159 if number == 0:
1159 if number == 0:
1160 # determine number so that 0.2 <= total time < 2.0
1160 # determine number so that 0.2 <= total time < 2.0
1161 for index in range(0, 10):
1161 for index in range(0, 10):
1162 number = 10 ** index
1162 number = 10 ** index
1163 time_number = timer.timeit(number)
1163 time_number = timer.timeit(number)
1164 if time_number >= 0.2:
1164 if time_number >= 0.2:
1165 break
1165 break
1166
1166
1167 all_runs = timer.repeat(repeat, number)
1167 all_runs = timer.repeat(repeat, number)
1168 best = min(all_runs) / number
1168 best = min(all_runs) / number
1169 worst = max(all_runs) / number
1169 worst = max(all_runs) / number
1170 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1170 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1171
1171
1172 # Restore global vars from conflict_globs
1172 # Restore global vars from conflict_globs
1173 if conflict_globs:
1173 if conflict_globs:
1174 glob.update(conflict_globs)
1174 glob.update(conflict_globs)
1175
1175
1176 if not quiet :
1176 if not quiet :
1177 # Check best timing is greater than zero to avoid a
1177 # Check best timing is greater than zero to avoid a
1178 # ZeroDivisionError.
1178 # ZeroDivisionError.
1179 # In cases where the slowest timing is lesser than a microsecond
1179 # In cases where the slowest timing is lesser than a microsecond
1180 # we assume that it does not really matter if the fastest
1180 # we assume that it does not really matter if the fastest
1181 # timing is 4 times faster than the slowest timing or not.
1181 # timing is 4 times faster than the slowest timing or not.
1182 if worst > 4 * best and best > 0 and worst > 1e-6:
1182 if worst > 4 * best and best > 0 and worst > 1e-6:
1183 print("The slowest run took %0.2f times longer than the "
1183 print("The slowest run took %0.2f times longer than the "
1184 "fastest. This could mean that an intermediate result "
1184 "fastest. This could mean that an intermediate result "
1185 "is being cached." % (worst / best))
1185 "is being cached." % (worst / best))
1186
1186
1187 print( timeit_result )
1187 print( timeit_result )
1188
1188
1189 if tc > tc_min:
1189 if tc > tc_min:
1190 print("Compiler time: %.2f s" % tc)
1190 print("Compiler time: %.2f s" % tc)
1191 if return_result:
1191 if return_result:
1192 return timeit_result
1192 return timeit_result
1193
1193
1194 @skip_doctest
1194 @skip_doctest
1195 @no_var_expand
1195 @no_var_expand
1196 @needs_local_scope
1196 @needs_local_scope
1197 @line_cell_magic
1197 @line_cell_magic
1198 @output_can_be_disabled
1198 @output_can_be_silenced
1199 def time(self,line='', cell=None, local_ns=None):
1199 def time(self,line='', cell=None, local_ns=None):
1200 """Time execution of a Python statement or expression.
1200 """Time execution of a Python statement or expression.
1201
1201
1202 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
1203 expression (if any) is returned. Note that under Win32, system time
1203 expression (if any) is returned. Note that under Win32, system time
1204 is always reported as 0, since it can not be measured.
1204 is always reported as 0, since it can not be measured.
1205
1205
1206 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:
1207
1207
1208 - 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
1209 ones can be chained with using semicolons).
1209 ones can be chained with using semicolons).
1210
1210
1211 - In cell mode, you can time the cell body (a directly
1211 - In cell mode, you can time the cell body (a directly
1212 following statement raises an error).
1212 following statement raises an error).
1213
1213
1214 This function provides very basic timing functionality. Use the timeit
1214 This function provides very basic timing functionality. Use the timeit
1215 magic for more control over the measurement.
1215 magic for more control over the measurement.
1216
1216
1217 .. versionchanged:: 7.3
1217 .. versionchanged:: 7.3
1218 User variables are no longer expanded,
1218 User variables are no longer expanded,
1219 the magic line is always left unmodified.
1219 the magic line is always left unmodified.
1220
1220
1221 Examples
1221 Examples
1222 --------
1222 --------
1223 ::
1223 ::
1224
1224
1225 In [1]: %time 2**128
1225 In [1]: %time 2**128
1226 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
1227 Wall time: 0.00
1227 Wall time: 0.00
1228 Out[1]: 340282366920938463463374607431768211456L
1228 Out[1]: 340282366920938463463374607431768211456L
1229
1229
1230 In [2]: n = 1000000
1230 In [2]: n = 1000000
1231
1231
1232 In [3]: %time sum(range(n))
1232 In [3]: %time sum(range(n))
1233 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
1234 Wall time: 1.37
1234 Wall time: 1.37
1235 Out[3]: 499999500000L
1235 Out[3]: 499999500000L
1236
1236
1237 In [4]: %time print 'hello world'
1237 In [4]: %time print 'hello world'
1238 hello world
1238 hello world
1239 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
1240 Wall time: 0.00
1240 Wall time: 0.00
1241
1241
1242 .. note::
1242 .. note::
1243 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
1244 reported if it is more than 0.1s.
1244 reported if it is more than 0.1s.
1245
1245
1246 In the example below, the actual exponentiation is done by Python
1246 In the example below, the actual exponentiation is done by Python
1247 at compilation time, so while the expression can take a noticeable
1247 at compilation time, so while the expression can take a noticeable
1248 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
1249 compilation::
1249 compilation::
1250
1250
1251 In [5]: %time 3**9999;
1251 In [5]: %time 3**9999;
1252 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
1253 Wall time: 0.00 s
1253 Wall time: 0.00 s
1254
1254
1255 In [6]: %time 3**999999;
1255 In [6]: %time 3**999999;
1256 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
1257 Wall time: 0.00 s
1257 Wall time: 0.00 s
1258 Compiler : 0.78 s
1258 Compiler : 0.78 s
1259 """
1259 """
1260 # fail immediately if the given expression can't be compiled
1260 # fail immediately if the given expression can't be compiled
1261
1261
1262 if line and cell:
1262 if line and cell:
1263 raise UsageError("Can't use statement directly after '%%time'!")
1263 raise UsageError("Can't use statement directly after '%%time'!")
1264
1264
1265 if cell:
1265 if cell:
1266 expr = self.shell.transform_cell(cell)
1266 expr = self.shell.transform_cell(cell)
1267 else:
1267 else:
1268 expr = self.shell.transform_cell(line)
1268 expr = self.shell.transform_cell(line)
1269
1269
1270 # Minimum time above which parse time will be reported
1270 # Minimum time above which parse time will be reported
1271 tp_min = 0.1
1271 tp_min = 0.1
1272
1272
1273 t0 = clock()
1273 t0 = clock()
1274 expr_ast = self.shell.compile.ast_parse(expr)
1274 expr_ast = self.shell.compile.ast_parse(expr)
1275 tp = clock()-t0
1275 tp = clock()-t0
1276
1276
1277 # Apply AST transformations
1277 # Apply AST transformations
1278 expr_ast = self.shell.transform_ast(expr_ast)
1278 expr_ast = self.shell.transform_ast(expr_ast)
1279
1279
1280 # Minimum time above which compilation time will be reported
1280 # Minimum time above which compilation time will be reported
1281 tc_min = 0.1
1281 tc_min = 0.1
1282
1282
1283 expr_val=None
1283 expr_val=None
1284 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):
1285 mode = 'eval'
1285 mode = 'eval'
1286 source = '<timed eval>'
1286 source = '<timed eval>'
1287 expr_ast = ast.Expression(expr_ast.body[0].value)
1287 expr_ast = ast.Expression(expr_ast.body[0].value)
1288 else:
1288 else:
1289 mode = 'exec'
1289 mode = 'exec'
1290 source = '<timed exec>'
1290 source = '<timed exec>'
1291 # multi-line %%time case
1291 # multi-line %%time case
1292 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):
1293 expr_val= expr_ast.body[-1]
1293 expr_val= expr_ast.body[-1]
1294 expr_ast = expr_ast.body[:-1]
1294 expr_ast = expr_ast.body[:-1]
1295 expr_ast = Module(expr_ast, [])
1295 expr_ast = Module(expr_ast, [])
1296 expr_val = ast.Expression(expr_val.value)
1296 expr_val = ast.Expression(expr_val.value)
1297
1297
1298 t0 = clock()
1298 t0 = clock()
1299 code = self.shell.compile(expr_ast, source, mode)
1299 code = self.shell.compile(expr_ast, source, mode)
1300 tc = clock()-t0
1300 tc = clock()-t0
1301
1301
1302 # skew measurement as little as possible
1302 # skew measurement as little as possible
1303 glob = self.shell.user_ns
1303 glob = self.shell.user_ns
1304 wtime = time.time
1304 wtime = time.time
1305 # time execution
1305 # time execution
1306 wall_st = wtime()
1306 wall_st = wtime()
1307 if mode=='eval':
1307 if mode=='eval':
1308 st = clock2()
1308 st = clock2()
1309 try:
1309 try:
1310 out = eval(code, glob, local_ns)
1310 out = eval(code, glob, local_ns)
1311 except:
1311 except:
1312 self.shell.showtraceback()
1312 self.shell.showtraceback()
1313 return
1313 return
1314 end = clock2()
1314 end = clock2()
1315 else:
1315 else:
1316 st = clock2()
1316 st = clock2()
1317 try:
1317 try:
1318 exec(code, glob, local_ns)
1318 exec(code, glob, local_ns)
1319 out=None
1319 out=None
1320 # multi-line %%time case
1320 # multi-line %%time case
1321 if expr_val is not None:
1321 if expr_val is not None:
1322 code_2 = self.shell.compile(expr_val, source, 'eval')
1322 code_2 = self.shell.compile(expr_val, source, 'eval')
1323 out = eval(code_2, glob, local_ns)
1323 out = eval(code_2, glob, local_ns)
1324 except:
1324 except:
1325 self.shell.showtraceback()
1325 self.shell.showtraceback()
1326 return
1326 return
1327 end = clock2()
1327 end = clock2()
1328
1328
1329 wall_end = wtime()
1329 wall_end = wtime()
1330 # Compute actual times and report
1330 # Compute actual times and report
1331 wall_time = wall_end - wall_st
1331 wall_time = wall_end - wall_st
1332 cpu_user = end[0] - st[0]
1332 cpu_user = end[0] - st[0]
1333 cpu_sys = end[1] - st[1]
1333 cpu_sys = end[1] - st[1]
1334 cpu_tot = cpu_user + cpu_sys
1334 cpu_tot = cpu_user + cpu_sys
1335 # 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
1336 if sys.platform != "win32":
1336 if sys.platform != "win32":
1337 print(
1337 print(
1338 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)}"
1339 )
1339 )
1340 else:
1340 else:
1341 print(f"CPU times: total: {_format_time(cpu_tot)}")
1341 print(f"CPU times: total: {_format_time(cpu_tot)}")
1342 print(f"Wall time: {_format_time(wall_time)}")
1342 print(f"Wall time: {_format_time(wall_time)}")
1343 if tc > tc_min:
1343 if tc > tc_min:
1344 print(f"Compiler : {_format_time(tc)}")
1344 print(f"Compiler : {_format_time(tc)}")
1345 if tp > tp_min:
1345 if tp > tp_min:
1346 print(f"Parser : {_format_time(tp)}")
1346 print(f"Parser : {_format_time(tp)}")
1347 return out
1347 return out
1348
1348
1349 @skip_doctest
1349 @skip_doctest
1350 @line_magic
1350 @line_magic
1351 def macro(self, parameter_s=''):
1351 def macro(self, parameter_s=''):
1352 """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,
1353 filenames or string objects.
1353 filenames or string objects.
1354
1354
1355 Usage:\\
1355 Usage:\\
1356 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1356 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1357
1357
1358 Options:
1358 Options:
1359
1359
1360 -r: use 'raw' input. By default, the 'processed' history is used,
1360 -r: use 'raw' input. By default, the 'processed' history is used,
1361 so that magics are loaded in their transformed version to valid
1361 so that magics are loaded in their transformed version to valid
1362 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
1363 command line is used instead.
1363 command line is used instead.
1364
1364
1365 -q: quiet macro definition. By default, a tag line is printed
1365 -q: quiet macro definition. By default, a tag line is printed
1366 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
1367 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
1368 is produced once the macro is created.
1368 is produced once the macro is created.
1369
1369
1370 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
1371 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
1372 above) from your input history into a single string. This variable
1372 above) from your input history into a single string. This variable
1373 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
1374 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
1375 executes.
1375 executes.
1376
1376
1377 The syntax for indicating input ranges is described in %history.
1377 The syntax for indicating input ranges is described in %history.
1378
1378
1379 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
1380 notation, where N:M means numbers N through M-1.
1380 notation, where N:M means numbers N through M-1.
1381
1381
1382 For example, if your history contains (print using %hist -n )::
1382 For example, if your history contains (print using %hist -n )::
1383
1383
1384 44: x=1
1384 44: x=1
1385 45: y=3
1385 45: y=3
1386 46: z=x+y
1386 46: z=x+y
1387 47: print x
1387 47: print x
1388 48: a=5
1388 48: a=5
1389 49: print 'x',x,'y',y
1389 49: print 'x',x,'y',y
1390
1390
1391 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
1392 called my_macro with::
1392 called my_macro with::
1393
1393
1394 In [55]: %macro my_macro 44-47 49
1394 In [55]: %macro my_macro 44-47 49
1395
1395
1396 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
1397 in one pass.
1397 in one pass.
1398
1398
1399 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
1400 number can appear multiple times. You can assemble macros with any
1400 number can appear multiple times. You can assemble macros with any
1401 lines from your input history in any order.
1401 lines from your input history in any order.
1402
1402
1403 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,
1404 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
1405 code instead of printing them when you type their name.
1405 code instead of printing them when you type their name.
1406
1406
1407 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::
1408
1408
1409 print macro_name
1409 print macro_name
1410
1410
1411 """
1411 """
1412 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1412 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1413 if not args: # List existing macros
1413 if not args: # List existing macros
1414 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))
1415 if len(args) == 1:
1415 if len(args) == 1:
1416 raise UsageError(
1416 raise UsageError(
1417 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1417 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1418 name, codefrom = args[0], " ".join(args[1:])
1418 name, codefrom = args[0], " ".join(args[1:])
1419
1419
1420 #print 'rng',ranges # dbg
1420 #print 'rng',ranges # dbg
1421 try:
1421 try:
1422 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1422 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1423 except (ValueError, TypeError) as e:
1423 except (ValueError, TypeError) as e:
1424 print(e.args[0])
1424 print(e.args[0])
1425 return
1425 return
1426 macro = Macro(lines)
1426 macro = Macro(lines)
1427 self.shell.define_macro(name, macro)
1427 self.shell.define_macro(name, macro)
1428 if not ( 'q' in opts) :
1428 if not ( 'q' in opts) :
1429 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)
1430 print('=== Macro contents: ===')
1430 print('=== Macro contents: ===')
1431 print(macro, end=' ')
1431 print(macro, end=' ')
1432
1432
1433 @magic_arguments.magic_arguments()
1433 @magic_arguments.magic_arguments()
1434 @magic_arguments.argument('output', type=str, default='', nargs='?',
1434 @magic_arguments.argument('output', type=str, default='', nargs='?',
1435 help="""The name of the variable in which to store output.
1435 help="""The name of the variable in which to store output.
1436 This is a utils.io.CapturedIO object with stdout/err attributes
1436 This is a utils.io.CapturedIO object with stdout/err attributes
1437 for the text of the captured output.
1437 for the text of the captured output.
1438
1438
1439 CapturedOutput also has a show() method for displaying the output,
1439 CapturedOutput also has a show() method for displaying the output,
1440 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
1441 output.
1441 output.
1442
1442
1443 If unspecified, captured output is discarded.
1443 If unspecified, captured output is discarded.
1444 """
1444 """
1445 )
1445 )
1446 @magic_arguments.argument('--no-stderr', action="store_true",
1446 @magic_arguments.argument('--no-stderr', action="store_true",
1447 help="""Don't capture stderr."""
1447 help="""Don't capture stderr."""
1448 )
1448 )
1449 @magic_arguments.argument('--no-stdout', action="store_true",
1449 @magic_arguments.argument('--no-stdout', action="store_true",
1450 help="""Don't capture stdout."""
1450 help="""Don't capture stdout."""
1451 )
1451 )
1452 @magic_arguments.argument('--no-display', action="store_true",
1452 @magic_arguments.argument('--no-display', action="store_true",
1453 help="""Don't capture IPython's rich display."""
1453 help="""Don't capture IPython's rich display."""
1454 )
1454 )
1455 @cell_magic
1455 @cell_magic
1456 def capture(self, line, cell):
1456 def capture(self, line, cell):
1457 """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."""
1458 args = magic_arguments.parse_argstring(self.capture, line)
1458 args = magic_arguments.parse_argstring(self.capture, line)
1459 out = not args.no_stdout
1459 out = not args.no_stdout
1460 err = not args.no_stderr
1460 err = not args.no_stderr
1461 disp = not args.no_display
1461 disp = not args.no_display
1462 with capture_output(out, err, disp) as io:
1462 with capture_output(out, err, disp) as io:
1463 self.shell.run_cell(cell)
1463 self.shell.run_cell(cell)
1464 if args.output:
1464 if args.output:
1465 self.shell.user_ns[args.output] = io
1465 self.shell.user_ns[args.output] = io
1466
1466
1467 def parse_breakpoint(text, current_file):
1467 def parse_breakpoint(text, current_file):
1468 '''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'''
1469 colon = text.find(':')
1469 colon = text.find(':')
1470 if colon == -1:
1470 if colon == -1:
1471 return current_file, int(text)
1471 return current_file, int(text)
1472 else:
1472 else:
1473 return text[:colon], int(text[colon+1:])
1473 return text[:colon], int(text[colon+1:])
1474
1474
1475 def _format_time(timespan, precision=3):
1475 def _format_time(timespan, precision=3):
1476 """Formats the timespan in a human readable form"""
1476 """Formats the timespan in a human readable form"""
1477
1477
1478 if timespan >= 60.0:
1478 if timespan >= 60.0:
1479 # 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
1480 # Idea from http://snipplr.com/view/5713/
1480 # Idea from http://snipplr.com/view/5713/
1481 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)]
1482 time = []
1482 time = []
1483 leftover = timespan
1483 leftover = timespan
1484 for suffix, length in parts:
1484 for suffix, length in parts:
1485 value = int(leftover / length)
1485 value = int(leftover / length)
1486 if value > 0:
1486 if value > 0:
1487 leftover = leftover % length
1487 leftover = leftover % length
1488 time.append(u'%s%s' % (str(value), suffix))
1488 time.append(u'%s%s' % (str(value), suffix))
1489 if leftover < 1:
1489 if leftover < 1:
1490 break
1490 break
1491 return " ".join(time)
1491 return " ".join(time)
1492
1492
1493
1493
1494 # Unfortunately the unicode 'micro' symbol can cause problems in
1494 # Unfortunately the unicode 'micro' symbol can cause problems in
1495 # certain terminals.
1495 # certain terminals.
1496 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1496 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1497 # 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
1498 # 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.
1499 units = [u"s", u"ms",u'us',"ns"] # the save value
1499 units = [u"s", u"ms",u'us',"ns"] # the save value
1500 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1500 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1501 try:
1501 try:
1502 u'\xb5'.encode(sys.stdout.encoding)
1502 u'\xb5'.encode(sys.stdout.encoding)
1503 units = [u"s", u"ms",u'\xb5s',"ns"]
1503 units = [u"s", u"ms",u'\xb5s',"ns"]
1504 except:
1504 except:
1505 pass
1505 pass
1506 scaling = [1, 1e3, 1e6, 1e9]
1506 scaling = [1, 1e3, 1e6, 1e9]
1507
1507
1508 if timespan > 0.0:
1508 if timespan > 0.0:
1509 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1509 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1510 else:
1510 else:
1511 order = 3
1511 order = 3
1512 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
1512 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
General Comments 0
You need to be logged in to leave comments. Login now