##// END OF EJS Templates
Revert "Fix for symlink resolving"
Matthias Bussonnier -
r27570:d73d0514 revert-13537-fix_...
parent child Browse files
Show More
@@ -1,3737 +1,3734 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 builtins as builtin_mod
17 import builtins as builtin_mod
18 import dis
18 import dis
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, check_linecache_ipython
64 from IPython.core.compilerop import CachingCompiler, check_linecache_ipython
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 @undoc
150 @undoc
151 def softspace(file, newvalue):
151 def softspace(file, newvalue):
152 """Copied from code.py, to remove the dependency"""
152 """Copied from code.py, to remove the dependency"""
153
153
154 oldvalue = 0
154 oldvalue = 0
155 try:
155 try:
156 oldvalue = file.softspace
156 oldvalue = file.softspace
157 except AttributeError:
157 except AttributeError:
158 pass
158 pass
159 try:
159 try:
160 file.softspace = newvalue
160 file.softspace = newvalue
161 except (AttributeError, TypeError):
161 except (AttributeError, TypeError):
162 # "attribute-less object" or "read-only attributes"
162 # "attribute-less object" or "read-only attributes"
163 pass
163 pass
164 return oldvalue
164 return oldvalue
165
165
166 @undoc
166 @undoc
167 def no_op(*a, **kw):
167 def no_op(*a, **kw):
168 pass
168 pass
169
169
170
170
171 class SpaceInInput(Exception): pass
171 class SpaceInInput(Exception): pass
172
172
173
173
174 class SeparateUnicode(Unicode):
174 class SeparateUnicode(Unicode):
175 r"""A Unicode subclass to validate separate_in, separate_out, etc.
175 r"""A Unicode subclass to validate separate_in, separate_out, etc.
176
176
177 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
177 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
178 """
178 """
179
179
180 def validate(self, obj, value):
180 def validate(self, obj, value):
181 if value == '0': value = ''
181 if value == '0': value = ''
182 value = value.replace('\\n','\n')
182 value = value.replace('\\n','\n')
183 return super(SeparateUnicode, self).validate(obj, value)
183 return super(SeparateUnicode, self).validate(obj, value)
184
184
185
185
186 @undoc
186 @undoc
187 class DummyMod(object):
187 class DummyMod(object):
188 """A dummy module used for IPython's interactive module when
188 """A dummy module used for IPython's interactive module when
189 a namespace must be assigned to the module's __dict__."""
189 a namespace must be assigned to the module's __dict__."""
190 __spec__ = None
190 __spec__ = None
191
191
192
192
193 class ExecutionInfo(object):
193 class ExecutionInfo(object):
194 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
194 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
195
195
196 Stores information about what is going to happen.
196 Stores information about what is going to happen.
197 """
197 """
198 raw_cell = None
198 raw_cell = None
199 store_history = False
199 store_history = False
200 silent = False
200 silent = False
201 shell_futures = True
201 shell_futures = True
202
202
203 def __init__(self, raw_cell, store_history, silent, shell_futures):
203 def __init__(self, raw_cell, store_history, silent, shell_futures):
204 self.raw_cell = raw_cell
204 self.raw_cell = raw_cell
205 self.store_history = store_history
205 self.store_history = store_history
206 self.silent = silent
206 self.silent = silent
207 self.shell_futures = shell_futures
207 self.shell_futures = shell_futures
208
208
209 def __repr__(self):
209 def __repr__(self):
210 name = self.__class__.__qualname__
210 name = self.__class__.__qualname__
211 raw_cell = ((self.raw_cell[:50] + '..')
211 raw_cell = ((self.raw_cell[:50] + '..')
212 if len(self.raw_cell) > 50 else self.raw_cell)
212 if len(self.raw_cell) > 50 else self.raw_cell)
213 return '<%s object at %x, raw_cell="%s" store_history=%s silent=%s shell_futures=%s>' %\
213 return '<%s object at %x, raw_cell="%s" store_history=%s silent=%s shell_futures=%s>' %\
214 (name, id(self), raw_cell, self.store_history, self.silent, self.shell_futures)
214 (name, id(self), raw_cell, self.store_history, self.silent, self.shell_futures)
215
215
216
216
217 class ExecutionResult(object):
217 class ExecutionResult(object):
218 """The result of a call to :meth:`InteractiveShell.run_cell`
218 """The result of a call to :meth:`InteractiveShell.run_cell`
219
219
220 Stores information about what took place.
220 Stores information about what took place.
221 """
221 """
222 execution_count = None
222 execution_count = None
223 error_before_exec = None
223 error_before_exec = None
224 error_in_exec: Optional[BaseException] = None
224 error_in_exec: Optional[BaseException] = None
225 info = None
225 info = None
226 result = None
226 result = None
227
227
228 def __init__(self, info):
228 def __init__(self, info):
229 self.info = info
229 self.info = info
230
230
231 @property
231 @property
232 def success(self):
232 def success(self):
233 return (self.error_before_exec is None) and (self.error_in_exec is None)
233 return (self.error_before_exec is None) and (self.error_in_exec is None)
234
234
235 def raise_error(self):
235 def raise_error(self):
236 """Reraises error if `success` is `False`, otherwise does nothing"""
236 """Reraises error if `success` is `False`, otherwise does nothing"""
237 if self.error_before_exec is not None:
237 if self.error_before_exec is not None:
238 raise self.error_before_exec
238 raise self.error_before_exec
239 if self.error_in_exec is not None:
239 if self.error_in_exec is not None:
240 raise self.error_in_exec
240 raise self.error_in_exec
241
241
242 def __repr__(self):
242 def __repr__(self):
243 name = self.__class__.__qualname__
243 name = self.__class__.__qualname__
244 return '<%s object at %x, execution_count=%s error_before_exec=%s error_in_exec=%s info=%s result=%s>' %\
244 return '<%s object at %x, execution_count=%s error_before_exec=%s error_in_exec=%s info=%s result=%s>' %\
245 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))
245 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))
246
246
247
247
248 class InteractiveShell(SingletonConfigurable):
248 class InteractiveShell(SingletonConfigurable):
249 """An enhanced, interactive shell for Python."""
249 """An enhanced, interactive shell for Python."""
250
250
251 _instance = None
251 _instance = None
252
252
253 ast_transformers = List([], help=
253 ast_transformers = List([], help=
254 """
254 """
255 A list of ast.NodeTransformer subclass instances, which will be applied
255 A list of ast.NodeTransformer subclass instances, which will be applied
256 to user input before code is run.
256 to user input before code is run.
257 """
257 """
258 ).tag(config=True)
258 ).tag(config=True)
259
259
260 autocall = Enum((0,1,2), default_value=0, help=
260 autocall = Enum((0,1,2), default_value=0, help=
261 """
261 """
262 Make IPython automatically call any callable object even if you didn't
262 Make IPython automatically call any callable object even if you didn't
263 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
263 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
264 automatically. The value can be '0' to disable the feature, '1' for
264 automatically. The value can be '0' to disable the feature, '1' for
265 'smart' autocall, where it is not applied if there are no more
265 'smart' autocall, where it is not applied if there are no more
266 arguments on the line, and '2' for 'full' autocall, where all callable
266 arguments on the line, and '2' for 'full' autocall, where all callable
267 objects are automatically called (even if no arguments are present).
267 objects are automatically called (even if no arguments are present).
268 """
268 """
269 ).tag(config=True)
269 ).tag(config=True)
270
270
271 autoindent = Bool(True, help=
271 autoindent = Bool(True, help=
272 """
272 """
273 Autoindent IPython code entered interactively.
273 Autoindent IPython code entered interactively.
274 """
274 """
275 ).tag(config=True)
275 ).tag(config=True)
276
276
277 autoawait = Bool(True, help=
277 autoawait = Bool(True, help=
278 """
278 """
279 Automatically run await statement in the top level repl.
279 Automatically run await statement in the top level repl.
280 """
280 """
281 ).tag(config=True)
281 ).tag(config=True)
282
282
283 loop_runner_map ={
283 loop_runner_map ={
284 'asyncio':(_asyncio_runner, True),
284 'asyncio':(_asyncio_runner, True),
285 'curio':(_curio_runner, True),
285 'curio':(_curio_runner, True),
286 'trio':(_trio_runner, True),
286 'trio':(_trio_runner, True),
287 'sync': (_pseudo_sync_runner, False)
287 'sync': (_pseudo_sync_runner, False)
288 }
288 }
289
289
290 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",
290 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",
291 allow_none=True,
291 allow_none=True,
292 help="""Select the loop runner that will be used to execute top-level asynchronous code"""
292 help="""Select the loop runner that will be used to execute top-level asynchronous code"""
293 ).tag(config=True)
293 ).tag(config=True)
294
294
295 @default('loop_runner')
295 @default('loop_runner')
296 def _default_loop_runner(self):
296 def _default_loop_runner(self):
297 return import_item("IPython.core.interactiveshell._asyncio_runner")
297 return import_item("IPython.core.interactiveshell._asyncio_runner")
298
298
299 @validate('loop_runner')
299 @validate('loop_runner')
300 def _import_runner(self, proposal):
300 def _import_runner(self, proposal):
301 if isinstance(proposal.value, str):
301 if isinstance(proposal.value, str):
302 if proposal.value in self.loop_runner_map:
302 if proposal.value in self.loop_runner_map:
303 runner, autoawait = self.loop_runner_map[proposal.value]
303 runner, autoawait = self.loop_runner_map[proposal.value]
304 self.autoawait = autoawait
304 self.autoawait = autoawait
305 return runner
305 return runner
306 runner = import_item(proposal.value)
306 runner = import_item(proposal.value)
307 if not callable(runner):
307 if not callable(runner):
308 raise ValueError('loop_runner must be callable')
308 raise ValueError('loop_runner must be callable')
309 return runner
309 return runner
310 if not callable(proposal.value):
310 if not callable(proposal.value):
311 raise ValueError('loop_runner must be callable')
311 raise ValueError('loop_runner must be callable')
312 return proposal.value
312 return proposal.value
313
313
314 automagic = Bool(True, help=
314 automagic = Bool(True, help=
315 """
315 """
316 Enable magic commands to be called without the leading %.
316 Enable magic commands to be called without the leading %.
317 """
317 """
318 ).tag(config=True)
318 ).tag(config=True)
319
319
320 banner1 = Unicode(default_banner,
320 banner1 = Unicode(default_banner,
321 help="""The part of the banner to be printed before the profile"""
321 help="""The part of the banner to be printed before the profile"""
322 ).tag(config=True)
322 ).tag(config=True)
323 banner2 = Unicode('',
323 banner2 = Unicode('',
324 help="""The part of the banner to be printed after the profile"""
324 help="""The part of the banner to be printed after the profile"""
325 ).tag(config=True)
325 ).tag(config=True)
326
326
327 cache_size = Integer(1000, help=
327 cache_size = Integer(1000, help=
328 """
328 """
329 Set the size of the output cache. The default is 1000, you can
329 Set the size of the output cache. The default is 1000, you can
330 change it permanently in your config file. Setting it to 0 completely
330 change it permanently in your config file. Setting it to 0 completely
331 disables the caching system, and the minimum value accepted is 3 (if
331 disables the caching system, and the minimum value accepted is 3 (if
332 you provide a value less than 3, it is reset to 0 and a warning is
332 you provide a value less than 3, it is reset to 0 and a warning is
333 issued). This limit is defined because otherwise you'll spend more
333 issued). This limit is defined because otherwise you'll spend more
334 time re-flushing a too small cache than working
334 time re-flushing a too small cache than working
335 """
335 """
336 ).tag(config=True)
336 ).tag(config=True)
337 color_info = Bool(True, help=
337 color_info = Bool(True, help=
338 """
338 """
339 Use colors for displaying information about objects. Because this
339 Use colors for displaying information about objects. Because this
340 information is passed through a pager (like 'less'), and some pagers
340 information is passed through a pager (like 'less'), and some pagers
341 get confused with color codes, this capability can be turned off.
341 get confused with color codes, this capability can be turned off.
342 """
342 """
343 ).tag(config=True)
343 ).tag(config=True)
344 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
344 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
345 default_value='Neutral',
345 default_value='Neutral',
346 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
346 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
347 ).tag(config=True)
347 ).tag(config=True)
348 debug = Bool(False).tag(config=True)
348 debug = Bool(False).tag(config=True)
349 disable_failing_post_execute = Bool(False,
349 disable_failing_post_execute = Bool(False,
350 help="Don't call post-execute functions that have failed in the past."
350 help="Don't call post-execute functions that have failed in the past."
351 ).tag(config=True)
351 ).tag(config=True)
352 display_formatter = Instance(DisplayFormatter, allow_none=True)
352 display_formatter = Instance(DisplayFormatter, allow_none=True)
353 displayhook_class = Type(DisplayHook)
353 displayhook_class = Type(DisplayHook)
354 display_pub_class = Type(DisplayPublisher)
354 display_pub_class = Type(DisplayPublisher)
355 compiler_class = Type(CachingCompiler)
355 compiler_class = Type(CachingCompiler)
356
356
357 sphinxify_docstring = Bool(False, help=
357 sphinxify_docstring = Bool(False, help=
358 """
358 """
359 Enables rich html representation of docstrings. (This requires the
359 Enables rich html representation of docstrings. (This requires the
360 docrepr module).
360 docrepr module).
361 """).tag(config=True)
361 """).tag(config=True)
362
362
363 @observe("sphinxify_docstring")
363 @observe("sphinxify_docstring")
364 def _sphinxify_docstring_changed(self, change):
364 def _sphinxify_docstring_changed(self, change):
365 if change['new']:
365 if change['new']:
366 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
366 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
367
367
368 enable_html_pager = Bool(False, help=
368 enable_html_pager = Bool(False, help=
369 """
369 """
370 (Provisional API) enables html representation in mime bundles sent
370 (Provisional API) enables html representation in mime bundles sent
371 to pagers.
371 to pagers.
372 """).tag(config=True)
372 """).tag(config=True)
373
373
374 @observe("enable_html_pager")
374 @observe("enable_html_pager")
375 def _enable_html_pager_changed(self, change):
375 def _enable_html_pager_changed(self, change):
376 if change['new']:
376 if change['new']:
377 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
377 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
378
378
379 data_pub_class = None
379 data_pub_class = None
380
380
381 exit_now = Bool(False)
381 exit_now = Bool(False)
382 exiter = Instance(ExitAutocall)
382 exiter = Instance(ExitAutocall)
383 @default('exiter')
383 @default('exiter')
384 def _exiter_default(self):
384 def _exiter_default(self):
385 return ExitAutocall(self)
385 return ExitAutocall(self)
386 # Monotonically increasing execution counter
386 # Monotonically increasing execution counter
387 execution_count = Integer(1)
387 execution_count = Integer(1)
388 filename = Unicode("<ipython console>")
388 filename = Unicode("<ipython console>")
389 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
389 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
390
390
391 # Used to transform cells before running them, and check whether code is complete
391 # Used to transform cells before running them, and check whether code is complete
392 input_transformer_manager = Instance('IPython.core.inputtransformer2.TransformerManager',
392 input_transformer_manager = Instance('IPython.core.inputtransformer2.TransformerManager',
393 ())
393 ())
394
394
395 @property
395 @property
396 def input_transformers_cleanup(self):
396 def input_transformers_cleanup(self):
397 return self.input_transformer_manager.cleanup_transforms
397 return self.input_transformer_manager.cleanup_transforms
398
398
399 input_transformers_post = List([],
399 input_transformers_post = List([],
400 help="A list of string input transformers, to be applied after IPython's "
400 help="A list of string input transformers, to be applied after IPython's "
401 "own input transformations."
401 "own input transformations."
402 )
402 )
403
403
404 @property
404 @property
405 def input_splitter(self):
405 def input_splitter(self):
406 """Make this available for backward compatibility (pre-7.0 release) with existing code.
406 """Make this available for backward compatibility (pre-7.0 release) with existing code.
407
407
408 For example, ipykernel ipykernel currently uses
408 For example, ipykernel ipykernel currently uses
409 `shell.input_splitter.check_complete`
409 `shell.input_splitter.check_complete`
410 """
410 """
411 from warnings import warn
411 from warnings import warn
412 warn("`input_splitter` is deprecated since IPython 7.0, prefer `input_transformer_manager`.",
412 warn("`input_splitter` is deprecated since IPython 7.0, prefer `input_transformer_manager`.",
413 DeprecationWarning, stacklevel=2
413 DeprecationWarning, stacklevel=2
414 )
414 )
415 return self.input_transformer_manager
415 return self.input_transformer_manager
416
416
417 logstart = Bool(False, help=
417 logstart = Bool(False, help=
418 """
418 """
419 Start logging to the default log file in overwrite mode.
419 Start logging to the default log file in overwrite mode.
420 Use `logappend` to specify a log file to **append** logs to.
420 Use `logappend` to specify a log file to **append** logs to.
421 """
421 """
422 ).tag(config=True)
422 ).tag(config=True)
423 logfile = Unicode('', help=
423 logfile = Unicode('', help=
424 """
424 """
425 The name of the logfile to use.
425 The name of the logfile to use.
426 """
426 """
427 ).tag(config=True)
427 ).tag(config=True)
428 logappend = Unicode('', help=
428 logappend = Unicode('', help=
429 """
429 """
430 Start logging to the given file in append mode.
430 Start logging to the given file in append mode.
431 Use `logfile` to specify a log file to **overwrite** logs to.
431 Use `logfile` to specify a log file to **overwrite** logs to.
432 """
432 """
433 ).tag(config=True)
433 ).tag(config=True)
434 object_info_string_level = Enum((0,1,2), default_value=0,
434 object_info_string_level = Enum((0,1,2), default_value=0,
435 ).tag(config=True)
435 ).tag(config=True)
436 pdb = Bool(False, help=
436 pdb = Bool(False, help=
437 """
437 """
438 Automatically call the pdb debugger after every exception.
438 Automatically call the pdb debugger after every exception.
439 """
439 """
440 ).tag(config=True)
440 ).tag(config=True)
441 display_page = Bool(False,
441 display_page = Bool(False,
442 help="""If True, anything that would be passed to the pager
442 help="""If True, anything that would be passed to the pager
443 will be displayed as regular output instead."""
443 will be displayed as regular output instead."""
444 ).tag(config=True)
444 ).tag(config=True)
445
445
446
446
447 show_rewritten_input = Bool(True,
447 show_rewritten_input = Bool(True,
448 help="Show rewritten input, e.g. for autocall."
448 help="Show rewritten input, e.g. for autocall."
449 ).tag(config=True)
449 ).tag(config=True)
450
450
451 quiet = Bool(False).tag(config=True)
451 quiet = Bool(False).tag(config=True)
452
452
453 history_length = Integer(10000,
453 history_length = Integer(10000,
454 help='Total length of command history'
454 help='Total length of command history'
455 ).tag(config=True)
455 ).tag(config=True)
456
456
457 history_load_length = Integer(1000, help=
457 history_load_length = Integer(1000, help=
458 """
458 """
459 The number of saved history entries to be loaded
459 The number of saved history entries to be loaded
460 into the history buffer at startup.
460 into the history buffer at startup.
461 """
461 """
462 ).tag(config=True)
462 ).tag(config=True)
463
463
464 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
464 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
465 default_value='last_expr',
465 default_value='last_expr',
466 help="""
466 help="""
467 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
467 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
468 which nodes should be run interactively (displaying output from expressions).
468 which nodes should be run interactively (displaying output from expressions).
469 """
469 """
470 ).tag(config=True)
470 ).tag(config=True)
471
471
472 # TODO: this part of prompt management should be moved to the frontends.
472 # TODO: this part of prompt management should be moved to the frontends.
473 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
473 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
474 separate_in = SeparateUnicode('\n').tag(config=True)
474 separate_in = SeparateUnicode('\n').tag(config=True)
475 separate_out = SeparateUnicode('').tag(config=True)
475 separate_out = SeparateUnicode('').tag(config=True)
476 separate_out2 = SeparateUnicode('').tag(config=True)
476 separate_out2 = SeparateUnicode('').tag(config=True)
477 wildcards_case_sensitive = Bool(True).tag(config=True)
477 wildcards_case_sensitive = Bool(True).tag(config=True)
478 xmode = CaselessStrEnum(('Context', 'Plain', 'Verbose', 'Minimal'),
478 xmode = CaselessStrEnum(('Context', 'Plain', 'Verbose', 'Minimal'),
479 default_value='Context',
479 default_value='Context',
480 help="Switch modes for the IPython exception handlers."
480 help="Switch modes for the IPython exception handlers."
481 ).tag(config=True)
481 ).tag(config=True)
482
482
483 # Subcomponents of InteractiveShell
483 # Subcomponents of InteractiveShell
484 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
484 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
485 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
485 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
486 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
486 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
487 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
487 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
488 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
488 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
489 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
489 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
490 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
490 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
491 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
491 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
492
492
493 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
493 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
494 @property
494 @property
495 def profile(self):
495 def profile(self):
496 if self.profile_dir is not None:
496 if self.profile_dir is not None:
497 name = os.path.basename(self.profile_dir.location)
497 name = os.path.basename(self.profile_dir.location)
498 return name.replace('profile_','')
498 return name.replace('profile_','')
499
499
500
500
501 # Private interface
501 # Private interface
502 _post_execute = Dict()
502 _post_execute = Dict()
503
503
504 # Tracks any GUI loop loaded for pylab
504 # Tracks any GUI loop loaded for pylab
505 pylab_gui_select = None
505 pylab_gui_select = None
506
506
507 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
507 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
508
508
509 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
509 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
510
510
511 def __init__(self, ipython_dir=None, profile_dir=None,
511 def __init__(self, ipython_dir=None, profile_dir=None,
512 user_module=None, user_ns=None,
512 user_module=None, user_ns=None,
513 custom_exceptions=((), None), **kwargs):
513 custom_exceptions=((), None), **kwargs):
514 # This is where traits with a config_key argument are updated
514 # This is where traits with a config_key argument are updated
515 # from the values on config.
515 # from the values on config.
516 super(InteractiveShell, self).__init__(**kwargs)
516 super(InteractiveShell, self).__init__(**kwargs)
517 if 'PromptManager' in self.config:
517 if 'PromptManager' in self.config:
518 warn('As of IPython 5.0 `PromptManager` config will have no effect'
518 warn('As of IPython 5.0 `PromptManager` config will have no effect'
519 ' and has been replaced by TerminalInteractiveShell.prompts_class')
519 ' and has been replaced by TerminalInteractiveShell.prompts_class')
520 self.configurables = [self]
520 self.configurables = [self]
521
521
522 # These are relatively independent and stateless
522 # These are relatively independent and stateless
523 self.init_ipython_dir(ipython_dir)
523 self.init_ipython_dir(ipython_dir)
524 self.init_profile_dir(profile_dir)
524 self.init_profile_dir(profile_dir)
525 self.init_instance_attrs()
525 self.init_instance_attrs()
526 self.init_environment()
526 self.init_environment()
527
527
528 # Check if we're in a virtualenv, and set up sys.path.
528 # Check if we're in a virtualenv, and set up sys.path.
529 self.init_virtualenv()
529 self.init_virtualenv()
530
530
531 # Create namespaces (user_ns, user_global_ns, etc.)
531 # Create namespaces (user_ns, user_global_ns, etc.)
532 self.init_create_namespaces(user_module, user_ns)
532 self.init_create_namespaces(user_module, user_ns)
533 # This has to be done after init_create_namespaces because it uses
533 # This has to be done after init_create_namespaces because it uses
534 # something in self.user_ns, but before init_sys_modules, which
534 # something in self.user_ns, but before init_sys_modules, which
535 # is the first thing to modify sys.
535 # is the first thing to modify sys.
536 # TODO: When we override sys.stdout and sys.stderr before this class
536 # TODO: When we override sys.stdout and sys.stderr before this class
537 # is created, we are saving the overridden ones here. Not sure if this
537 # is created, we are saving the overridden ones here. Not sure if this
538 # is what we want to do.
538 # is what we want to do.
539 self.save_sys_module_state()
539 self.save_sys_module_state()
540 self.init_sys_modules()
540 self.init_sys_modules()
541
541
542 # While we're trying to have each part of the code directly access what
542 # While we're trying to have each part of the code directly access what
543 # it needs without keeping redundant references to objects, we have too
543 # it needs without keeping redundant references to objects, we have too
544 # much legacy code that expects ip.db to exist.
544 # much legacy code that expects ip.db to exist.
545 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
545 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
546
546
547 self.init_history()
547 self.init_history()
548 self.init_encoding()
548 self.init_encoding()
549 self.init_prefilter()
549 self.init_prefilter()
550
550
551 self.init_syntax_highlighting()
551 self.init_syntax_highlighting()
552 self.init_hooks()
552 self.init_hooks()
553 self.init_events()
553 self.init_events()
554 self.init_pushd_popd_magic()
554 self.init_pushd_popd_magic()
555 self.init_user_ns()
555 self.init_user_ns()
556 self.init_logger()
556 self.init_logger()
557 self.init_builtins()
557 self.init_builtins()
558
558
559 # The following was in post_config_initialization
559 # The following was in post_config_initialization
560 self.init_inspector()
560 self.init_inspector()
561 self.raw_input_original = input
561 self.raw_input_original = input
562 self.init_completer()
562 self.init_completer()
563 # TODO: init_io() needs to happen before init_traceback handlers
563 # TODO: init_io() needs to happen before init_traceback handlers
564 # because the traceback handlers hardcode the stdout/stderr streams.
564 # because the traceback handlers hardcode the stdout/stderr streams.
565 # This logic in in debugger.Pdb and should eventually be changed.
565 # This logic in in debugger.Pdb and should eventually be changed.
566 self.init_io()
566 self.init_io()
567 self.init_traceback_handlers(custom_exceptions)
567 self.init_traceback_handlers(custom_exceptions)
568 self.init_prompts()
568 self.init_prompts()
569 self.init_display_formatter()
569 self.init_display_formatter()
570 self.init_display_pub()
570 self.init_display_pub()
571 self.init_data_pub()
571 self.init_data_pub()
572 self.init_displayhook()
572 self.init_displayhook()
573 self.init_magics()
573 self.init_magics()
574 self.init_alias()
574 self.init_alias()
575 self.init_logstart()
575 self.init_logstart()
576 self.init_pdb()
576 self.init_pdb()
577 self.init_extension_manager()
577 self.init_extension_manager()
578 self.init_payload()
578 self.init_payload()
579 self.events.trigger('shell_initialized', self)
579 self.events.trigger('shell_initialized', self)
580 atexit.register(self.atexit_operations)
580 atexit.register(self.atexit_operations)
581
581
582 # The trio runner is used for running Trio in the foreground thread. It
582 # The trio runner is used for running Trio in the foreground thread. It
583 # is different from `_trio_runner(async_fn)` in `async_helpers.py`
583 # is different from `_trio_runner(async_fn)` in `async_helpers.py`
584 # which calls `trio.run()` for every cell. This runner runs all cells
584 # which calls `trio.run()` for every cell. This runner runs all cells
585 # inside a single Trio event loop. If used, it is set from
585 # inside a single Trio event loop. If used, it is set from
586 # `ipykernel.kernelapp`.
586 # `ipykernel.kernelapp`.
587 self.trio_runner = None
587 self.trio_runner = None
588
588
589 def get_ipython(self):
589 def get_ipython(self):
590 """Return the currently running IPython instance."""
590 """Return the currently running IPython instance."""
591 return self
591 return self
592
592
593 #-------------------------------------------------------------------------
593 #-------------------------------------------------------------------------
594 # Trait changed handlers
594 # Trait changed handlers
595 #-------------------------------------------------------------------------
595 #-------------------------------------------------------------------------
596 @observe('ipython_dir')
596 @observe('ipython_dir')
597 def _ipython_dir_changed(self, change):
597 def _ipython_dir_changed(self, change):
598 ensure_dir_exists(change['new'])
598 ensure_dir_exists(change['new'])
599
599
600 def set_autoindent(self,value=None):
600 def set_autoindent(self,value=None):
601 """Set the autoindent flag.
601 """Set the autoindent flag.
602
602
603 If called with no arguments, it acts as a toggle."""
603 If called with no arguments, it acts as a toggle."""
604 if value is None:
604 if value is None:
605 self.autoindent = not self.autoindent
605 self.autoindent = not self.autoindent
606 else:
606 else:
607 self.autoindent = value
607 self.autoindent = value
608
608
609 def set_trio_runner(self, tr):
609 def set_trio_runner(self, tr):
610 self.trio_runner = tr
610 self.trio_runner = tr
611
611
612 #-------------------------------------------------------------------------
612 #-------------------------------------------------------------------------
613 # init_* methods called by __init__
613 # init_* methods called by __init__
614 #-------------------------------------------------------------------------
614 #-------------------------------------------------------------------------
615
615
616 def init_ipython_dir(self, ipython_dir):
616 def init_ipython_dir(self, ipython_dir):
617 if ipython_dir is not None:
617 if ipython_dir is not None:
618 self.ipython_dir = ipython_dir
618 self.ipython_dir = ipython_dir
619 return
619 return
620
620
621 self.ipython_dir = get_ipython_dir()
621 self.ipython_dir = get_ipython_dir()
622
622
623 def init_profile_dir(self, profile_dir):
623 def init_profile_dir(self, profile_dir):
624 if profile_dir is not None:
624 if profile_dir is not None:
625 self.profile_dir = profile_dir
625 self.profile_dir = profile_dir
626 return
626 return
627 self.profile_dir = ProfileDir.create_profile_dir_by_name(
627 self.profile_dir = ProfileDir.create_profile_dir_by_name(
628 self.ipython_dir, "default"
628 self.ipython_dir, "default"
629 )
629 )
630
630
631 def init_instance_attrs(self):
631 def init_instance_attrs(self):
632 self.more = False
632 self.more = False
633
633
634 # command compiler
634 # command compiler
635 self.compile = self.compiler_class()
635 self.compile = self.compiler_class()
636
636
637 # Make an empty namespace, which extension writers can rely on both
637 # Make an empty namespace, which extension writers can rely on both
638 # existing and NEVER being used by ipython itself. This gives them a
638 # existing and NEVER being used by ipython itself. This gives them a
639 # convenient location for storing additional information and state
639 # convenient location for storing additional information and state
640 # their extensions may require, without fear of collisions with other
640 # their extensions may require, without fear of collisions with other
641 # ipython names that may develop later.
641 # ipython names that may develop later.
642 self.meta = Struct()
642 self.meta = Struct()
643
643
644 # Temporary files used for various purposes. Deleted at exit.
644 # Temporary files used for various purposes. Deleted at exit.
645 # The files here are stored with Path from Pathlib
645 # The files here are stored with Path from Pathlib
646 self.tempfiles = []
646 self.tempfiles = []
647 self.tempdirs = []
647 self.tempdirs = []
648
648
649 # keep track of where we started running (mainly for crash post-mortem)
649 # keep track of where we started running (mainly for crash post-mortem)
650 # This is not being used anywhere currently.
650 # This is not being used anywhere currently.
651 self.starting_dir = os.getcwd()
651 self.starting_dir = os.getcwd()
652
652
653 # Indentation management
653 # Indentation management
654 self.indent_current_nsp = 0
654 self.indent_current_nsp = 0
655
655
656 # Dict to track post-execution functions that have been registered
656 # Dict to track post-execution functions that have been registered
657 self._post_execute = {}
657 self._post_execute = {}
658
658
659 def init_environment(self):
659 def init_environment(self):
660 """Any changes we need to make to the user's environment."""
660 """Any changes we need to make to the user's environment."""
661 pass
661 pass
662
662
663 def init_encoding(self):
663 def init_encoding(self):
664 # Get system encoding at startup time. Certain terminals (like Emacs
664 # Get system encoding at startup time. Certain terminals (like Emacs
665 # under Win32 have it set to None, and we need to have a known valid
665 # under Win32 have it set to None, and we need to have a known valid
666 # encoding to use in the raw_input() method
666 # encoding to use in the raw_input() method
667 try:
667 try:
668 self.stdin_encoding = sys.stdin.encoding or 'ascii'
668 self.stdin_encoding = sys.stdin.encoding or 'ascii'
669 except AttributeError:
669 except AttributeError:
670 self.stdin_encoding = 'ascii'
670 self.stdin_encoding = 'ascii'
671
671
672
672
673 @observe('colors')
673 @observe('colors')
674 def init_syntax_highlighting(self, changes=None):
674 def init_syntax_highlighting(self, changes=None):
675 # Python source parser/formatter for syntax highlighting
675 # Python source parser/formatter for syntax highlighting
676 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
676 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
677 self.pycolorize = lambda src: pyformat(src,'str')
677 self.pycolorize = lambda src: pyformat(src,'str')
678
678
679 def refresh_style(self):
679 def refresh_style(self):
680 # No-op here, used in subclass
680 # No-op here, used in subclass
681 pass
681 pass
682
682
683 def init_pushd_popd_magic(self):
683 def init_pushd_popd_magic(self):
684 # for pushd/popd management
684 # for pushd/popd management
685 self.home_dir = get_home_dir()
685 self.home_dir = get_home_dir()
686
686
687 self.dir_stack = []
687 self.dir_stack = []
688
688
689 def init_logger(self):
689 def init_logger(self):
690 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
690 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
691 logmode='rotate')
691 logmode='rotate')
692
692
693 def init_logstart(self):
693 def init_logstart(self):
694 """Initialize logging in case it was requested at the command line.
694 """Initialize logging in case it was requested at the command line.
695 """
695 """
696 if self.logappend:
696 if self.logappend:
697 self.magic('logstart %s append' % self.logappend)
697 self.magic('logstart %s append' % self.logappend)
698 elif self.logfile:
698 elif self.logfile:
699 self.magic('logstart %s' % self.logfile)
699 self.magic('logstart %s' % self.logfile)
700 elif self.logstart:
700 elif self.logstart:
701 self.magic('logstart')
701 self.magic('logstart')
702
702
703
703
704 def init_builtins(self):
704 def init_builtins(self):
705 # A single, static flag that we set to True. Its presence indicates
705 # A single, static flag that we set to True. Its presence indicates
706 # that an IPython shell has been created, and we make no attempts at
706 # that an IPython shell has been created, and we make no attempts at
707 # removing on exit or representing the existence of more than one
707 # removing on exit or representing the existence of more than one
708 # IPython at a time.
708 # IPython at a time.
709 builtin_mod.__dict__['__IPYTHON__'] = True
709 builtin_mod.__dict__['__IPYTHON__'] = True
710 builtin_mod.__dict__['display'] = display
710 builtin_mod.__dict__['display'] = display
711
711
712 self.builtin_trap = BuiltinTrap(shell=self)
712 self.builtin_trap = BuiltinTrap(shell=self)
713
713
714 @observe('colors')
714 @observe('colors')
715 def init_inspector(self, changes=None):
715 def init_inspector(self, changes=None):
716 # Object inspector
716 # Object inspector
717 self.inspector = oinspect.Inspector(oinspect.InspectColors,
717 self.inspector = oinspect.Inspector(oinspect.InspectColors,
718 PyColorize.ANSICodeColors,
718 PyColorize.ANSICodeColors,
719 self.colors,
719 self.colors,
720 self.object_info_string_level)
720 self.object_info_string_level)
721
721
722 def init_io(self):
722 def init_io(self):
723 # implemented in subclasses, TerminalInteractiveShell does call
723 # implemented in subclasses, TerminalInteractiveShell does call
724 # colorama.init().
724 # colorama.init().
725 pass
725 pass
726
726
727 def init_prompts(self):
727 def init_prompts(self):
728 # Set system prompts, so that scripts can decide if they are running
728 # Set system prompts, so that scripts can decide if they are running
729 # interactively.
729 # interactively.
730 sys.ps1 = 'In : '
730 sys.ps1 = 'In : '
731 sys.ps2 = '...: '
731 sys.ps2 = '...: '
732 sys.ps3 = 'Out: '
732 sys.ps3 = 'Out: '
733
733
734 def init_display_formatter(self):
734 def init_display_formatter(self):
735 self.display_formatter = DisplayFormatter(parent=self)
735 self.display_formatter = DisplayFormatter(parent=self)
736 self.configurables.append(self.display_formatter)
736 self.configurables.append(self.display_formatter)
737
737
738 def init_display_pub(self):
738 def init_display_pub(self):
739 self.display_pub = self.display_pub_class(parent=self, shell=self)
739 self.display_pub = self.display_pub_class(parent=self, shell=self)
740 self.configurables.append(self.display_pub)
740 self.configurables.append(self.display_pub)
741
741
742 def init_data_pub(self):
742 def init_data_pub(self):
743 if not self.data_pub_class:
743 if not self.data_pub_class:
744 self.data_pub = None
744 self.data_pub = None
745 return
745 return
746 self.data_pub = self.data_pub_class(parent=self)
746 self.data_pub = self.data_pub_class(parent=self)
747 self.configurables.append(self.data_pub)
747 self.configurables.append(self.data_pub)
748
748
749 def init_displayhook(self):
749 def init_displayhook(self):
750 # Initialize displayhook, set in/out prompts and printing system
750 # Initialize displayhook, set in/out prompts and printing system
751 self.displayhook = self.displayhook_class(
751 self.displayhook = self.displayhook_class(
752 parent=self,
752 parent=self,
753 shell=self,
753 shell=self,
754 cache_size=self.cache_size,
754 cache_size=self.cache_size,
755 )
755 )
756 self.configurables.append(self.displayhook)
756 self.configurables.append(self.displayhook)
757 # This is a context manager that installs/revmoes the displayhook at
757 # This is a context manager that installs/revmoes the displayhook at
758 # the appropriate time.
758 # the appropriate time.
759 self.display_trap = DisplayTrap(hook=self.displayhook)
759 self.display_trap = DisplayTrap(hook=self.displayhook)
760
760
761 def init_virtualenv(self):
761 def init_virtualenv(self):
762 """Add the current virtualenv to sys.path so the user can import modules from it.
762 """Add the current virtualenv to sys.path so the user can import modules from it.
763 This isn't perfect: it doesn't use the Python interpreter with which the
763 This isn't perfect: it doesn't use the Python interpreter with which the
764 virtualenv was built, and it ignores the --no-site-packages option. A
764 virtualenv was built, and it ignores the --no-site-packages option. A
765 warning will appear suggesting the user installs IPython in the
765 warning will appear suggesting the user installs IPython in the
766 virtualenv, but for many cases, it probably works well enough.
766 virtualenv, but for many cases, it probably works well enough.
767
767
768 Adapted from code snippets online.
768 Adapted from code snippets online.
769
769
770 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
770 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
771 """
771 """
772 if 'VIRTUAL_ENV' not in os.environ:
772 if 'VIRTUAL_ENV' not in os.environ:
773 # Not in a virtualenv
773 # Not in a virtualenv
774 return
774 return
775 elif os.environ["VIRTUAL_ENV"] == "":
775 elif os.environ["VIRTUAL_ENV"] == "":
776 warn("Virtual env path set to '', please check if this is intended.")
776 warn("Virtual env path set to '', please check if this is intended.")
777 return
777 return
778
778
779 p = Path(sys.executable)
779 p = Path(sys.executable)
780 p_venv = Path(os.environ["VIRTUAL_ENV"])
780 p_venv = Path(os.environ["VIRTUAL_ENV"])
781
781
782 # fallback venv detection:
782 # fallback venv detection:
783 # stdlib venv may symlink sys.executable, so we can't use realpath.
783 # stdlib venv may symlink sys.executable, so we can't use realpath.
784 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
784 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
785 # So we just check every item in the symlink tree (generally <= 3)
785 # So we just check every item in the symlink tree (generally <= 3)
786 paths = [p]
786 paths = [p]
787 while p.is_symlink():
787 while p.is_symlink():
788 new_path = p.readlink()
788 p = Path(os.readlink(p))
789 if not new_path.is_absolute():
789 paths.append(p.resolve())
790 new_path = p.parent / new_path
791 p = new_path
792 paths.append(p)
793
790
794 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
791 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
795 if p_venv.parts[1] == "cygdrive":
792 if p_venv.parts[1] == "cygdrive":
796 drive_name = p_venv.parts[2]
793 drive_name = p_venv.parts[2]
797 p_venv = (drive_name + ":/") / Path(*p_venv.parts[3:])
794 p_venv = (drive_name + ":/") / Path(*p_venv.parts[3:])
798
795
799 if any(p_venv == p.parents[1] for p in paths):
796 if any(p_venv == p.parents[1] for p in paths):
800 # Our exe is inside or has access to the virtualenv, don't need to do anything.
797 # Our exe is inside or has access to the virtualenv, don't need to do anything.
801 return
798 return
802
799
803 if sys.platform == "win32":
800 if sys.platform == "win32":
804 virtual_env = str(Path(os.environ["VIRTUAL_ENV"], "Lib", "site-packages"))
801 virtual_env = str(Path(os.environ["VIRTUAL_ENV"], "Lib", "site-packages"))
805 else:
802 else:
806 virtual_env_path = Path(
803 virtual_env_path = Path(
807 os.environ["VIRTUAL_ENV"], "lib", "python{}.{}", "site-packages"
804 os.environ["VIRTUAL_ENV"], "lib", "python{}.{}", "site-packages"
808 )
805 )
809 p_ver = sys.version_info[:2]
806 p_ver = sys.version_info[:2]
810
807
811 # Predict version from py[thon]-x.x in the $VIRTUAL_ENV
808 # Predict version from py[thon]-x.x in the $VIRTUAL_ENV
812 re_m = re.search(r"\bpy(?:thon)?([23])\.(\d+)\b", os.environ["VIRTUAL_ENV"])
809 re_m = re.search(r"\bpy(?:thon)?([23])\.(\d+)\b", os.environ["VIRTUAL_ENV"])
813 if re_m:
810 if re_m:
814 predicted_path = Path(str(virtual_env_path).format(*re_m.groups()))
811 predicted_path = Path(str(virtual_env_path).format(*re_m.groups()))
815 if predicted_path.exists():
812 if predicted_path.exists():
816 p_ver = re_m.groups()
813 p_ver = re_m.groups()
817
814
818 virtual_env = str(virtual_env_path).format(*p_ver)
815 virtual_env = str(virtual_env_path).format(*p_ver)
819
816
820 warn(
817 warn(
821 "Attempting to work in a virtualenv. If you encounter problems, "
818 "Attempting to work in a virtualenv. If you encounter problems, "
822 "please install IPython inside the virtualenv."
819 "please install IPython inside the virtualenv."
823 )
820 )
824 import site
821 import site
825 sys.path.insert(0, virtual_env)
822 sys.path.insert(0, virtual_env)
826 site.addsitedir(virtual_env)
823 site.addsitedir(virtual_env)
827
824
828 #-------------------------------------------------------------------------
825 #-------------------------------------------------------------------------
829 # Things related to injections into the sys module
826 # Things related to injections into the sys module
830 #-------------------------------------------------------------------------
827 #-------------------------------------------------------------------------
831
828
832 def save_sys_module_state(self):
829 def save_sys_module_state(self):
833 """Save the state of hooks in the sys module.
830 """Save the state of hooks in the sys module.
834
831
835 This has to be called after self.user_module is created.
832 This has to be called after self.user_module is created.
836 """
833 """
837 self._orig_sys_module_state = {'stdin': sys.stdin,
834 self._orig_sys_module_state = {'stdin': sys.stdin,
838 'stdout': sys.stdout,
835 'stdout': sys.stdout,
839 'stderr': sys.stderr,
836 'stderr': sys.stderr,
840 'excepthook': sys.excepthook}
837 'excepthook': sys.excepthook}
841 self._orig_sys_modules_main_name = self.user_module.__name__
838 self._orig_sys_modules_main_name = self.user_module.__name__
842 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
839 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
843
840
844 def restore_sys_module_state(self):
841 def restore_sys_module_state(self):
845 """Restore the state of the sys module."""
842 """Restore the state of the sys module."""
846 try:
843 try:
847 for k, v in self._orig_sys_module_state.items():
844 for k, v in self._orig_sys_module_state.items():
848 setattr(sys, k, v)
845 setattr(sys, k, v)
849 except AttributeError:
846 except AttributeError:
850 pass
847 pass
851 # Reset what what done in self.init_sys_modules
848 # Reset what what done in self.init_sys_modules
852 if self._orig_sys_modules_main_mod is not None:
849 if self._orig_sys_modules_main_mod is not None:
853 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
850 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
854
851
855 #-------------------------------------------------------------------------
852 #-------------------------------------------------------------------------
856 # Things related to the banner
853 # Things related to the banner
857 #-------------------------------------------------------------------------
854 #-------------------------------------------------------------------------
858
855
859 @property
856 @property
860 def banner(self):
857 def banner(self):
861 banner = self.banner1
858 banner = self.banner1
862 if self.profile and self.profile != 'default':
859 if self.profile and self.profile != 'default':
863 banner += '\nIPython profile: %s\n' % self.profile
860 banner += '\nIPython profile: %s\n' % self.profile
864 if self.banner2:
861 if self.banner2:
865 banner += '\n' + self.banner2
862 banner += '\n' + self.banner2
866 return banner
863 return banner
867
864
868 def show_banner(self, banner=None):
865 def show_banner(self, banner=None):
869 if banner is None:
866 if banner is None:
870 banner = self.banner
867 banner = self.banner
871 sys.stdout.write(banner)
868 sys.stdout.write(banner)
872
869
873 #-------------------------------------------------------------------------
870 #-------------------------------------------------------------------------
874 # Things related to hooks
871 # Things related to hooks
875 #-------------------------------------------------------------------------
872 #-------------------------------------------------------------------------
876
873
877 def init_hooks(self):
874 def init_hooks(self):
878 # hooks holds pointers used for user-side customizations
875 # hooks holds pointers used for user-side customizations
879 self.hooks = Struct()
876 self.hooks = Struct()
880
877
881 self.strdispatchers = {}
878 self.strdispatchers = {}
882
879
883 # Set all default hooks, defined in the IPython.hooks module.
880 # Set all default hooks, defined in the IPython.hooks module.
884 hooks = IPython.core.hooks
881 hooks = IPython.core.hooks
885 for hook_name in hooks.__all__:
882 for hook_name in hooks.__all__:
886 # default hooks have priority 100, i.e. low; user hooks should have
883 # default hooks have priority 100, i.e. low; user hooks should have
887 # 0-100 priority
884 # 0-100 priority
888 self.set_hook(hook_name, getattr(hooks, hook_name), 100)
885 self.set_hook(hook_name, getattr(hooks, hook_name), 100)
889
886
890 if self.display_page:
887 if self.display_page:
891 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
888 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
892
889
893 def set_hook(self, name, hook, priority=50, str_key=None, re_key=None):
890 def set_hook(self, name, hook, priority=50, str_key=None, re_key=None):
894 """set_hook(name,hook) -> sets an internal IPython hook.
891 """set_hook(name,hook) -> sets an internal IPython hook.
895
892
896 IPython exposes some of its internal API as user-modifiable hooks. By
893 IPython exposes some of its internal API as user-modifiable hooks. By
897 adding your function to one of these hooks, you can modify IPython's
894 adding your function to one of these hooks, you can modify IPython's
898 behavior to call at runtime your own routines."""
895 behavior to call at runtime your own routines."""
899
896
900 # At some point in the future, this should validate the hook before it
897 # At some point in the future, this should validate the hook before it
901 # accepts it. Probably at least check that the hook takes the number
898 # accepts it. Probably at least check that the hook takes the number
902 # of args it's supposed to.
899 # of args it's supposed to.
903
900
904 f = types.MethodType(hook,self)
901 f = types.MethodType(hook,self)
905
902
906 # check if the hook is for strdispatcher first
903 # check if the hook is for strdispatcher first
907 if str_key is not None:
904 if str_key is not None:
908 sdp = self.strdispatchers.get(name, StrDispatch())
905 sdp = self.strdispatchers.get(name, StrDispatch())
909 sdp.add_s(str_key, f, priority )
906 sdp.add_s(str_key, f, priority )
910 self.strdispatchers[name] = sdp
907 self.strdispatchers[name] = sdp
911 return
908 return
912 if re_key is not None:
909 if re_key is not None:
913 sdp = self.strdispatchers.get(name, StrDispatch())
910 sdp = self.strdispatchers.get(name, StrDispatch())
914 sdp.add_re(re.compile(re_key), f, priority )
911 sdp.add_re(re.compile(re_key), f, priority )
915 self.strdispatchers[name] = sdp
912 self.strdispatchers[name] = sdp
916 return
913 return
917
914
918 dp = getattr(self.hooks, name, None)
915 dp = getattr(self.hooks, name, None)
919 if name not in IPython.core.hooks.__all__:
916 if name not in IPython.core.hooks.__all__:
920 print("Warning! Hook '%s' is not one of %s" % \
917 print("Warning! Hook '%s' is not one of %s" % \
921 (name, IPython.core.hooks.__all__ ))
918 (name, IPython.core.hooks.__all__ ))
922
919
923 if name in IPython.core.hooks.deprecated:
920 if name in IPython.core.hooks.deprecated:
924 alternative = IPython.core.hooks.deprecated[name]
921 alternative = IPython.core.hooks.deprecated[name]
925 raise ValueError(
922 raise ValueError(
926 "Hook {} has been deprecated since IPython 5.0. Use {} instead.".format(
923 "Hook {} has been deprecated since IPython 5.0. Use {} instead.".format(
927 name, alternative
924 name, alternative
928 )
925 )
929 )
926 )
930
927
931 if not dp:
928 if not dp:
932 dp = IPython.core.hooks.CommandChainDispatcher()
929 dp = IPython.core.hooks.CommandChainDispatcher()
933
930
934 try:
931 try:
935 dp.add(f,priority)
932 dp.add(f,priority)
936 except AttributeError:
933 except AttributeError:
937 # it was not commandchain, plain old func - replace
934 # it was not commandchain, plain old func - replace
938 dp = f
935 dp = f
939
936
940 setattr(self.hooks,name, dp)
937 setattr(self.hooks,name, dp)
941
938
942 #-------------------------------------------------------------------------
939 #-------------------------------------------------------------------------
943 # Things related to events
940 # Things related to events
944 #-------------------------------------------------------------------------
941 #-------------------------------------------------------------------------
945
942
946 def init_events(self):
943 def init_events(self):
947 self.events = EventManager(self, available_events)
944 self.events = EventManager(self, available_events)
948
945
949 self.events.register("pre_execute", self._clear_warning_registry)
946 self.events.register("pre_execute", self._clear_warning_registry)
950
947
951 def register_post_execute(self, func):
948 def register_post_execute(self, func):
952 """DEPRECATED: Use ip.events.register('post_run_cell', func)
949 """DEPRECATED: Use ip.events.register('post_run_cell', func)
953
950
954 Register a function for calling after code execution.
951 Register a function for calling after code execution.
955 """
952 """
956 raise ValueError(
953 raise ValueError(
957 "ip.register_post_execute is deprecated since IPython 1.0, use "
954 "ip.register_post_execute is deprecated since IPython 1.0, use "
958 "ip.events.register('post_run_cell', func) instead."
955 "ip.events.register('post_run_cell', func) instead."
959 )
956 )
960
957
961 def _clear_warning_registry(self):
958 def _clear_warning_registry(self):
962 # clear the warning registry, so that different code blocks with
959 # clear the warning registry, so that different code blocks with
963 # overlapping line number ranges don't cause spurious suppression of
960 # overlapping line number ranges don't cause spurious suppression of
964 # warnings (see gh-6611 for details)
961 # warnings (see gh-6611 for details)
965 if "__warningregistry__" in self.user_global_ns:
962 if "__warningregistry__" in self.user_global_ns:
966 del self.user_global_ns["__warningregistry__"]
963 del self.user_global_ns["__warningregistry__"]
967
964
968 #-------------------------------------------------------------------------
965 #-------------------------------------------------------------------------
969 # Things related to the "main" module
966 # Things related to the "main" module
970 #-------------------------------------------------------------------------
967 #-------------------------------------------------------------------------
971
968
972 def new_main_mod(self, filename, modname):
969 def new_main_mod(self, filename, modname):
973 """Return a new 'main' module object for user code execution.
970 """Return a new 'main' module object for user code execution.
974
971
975 ``filename`` should be the path of the script which will be run in the
972 ``filename`` should be the path of the script which will be run in the
976 module. Requests with the same filename will get the same module, with
973 module. Requests with the same filename will get the same module, with
977 its namespace cleared.
974 its namespace cleared.
978
975
979 ``modname`` should be the module name - normally either '__main__' or
976 ``modname`` should be the module name - normally either '__main__' or
980 the basename of the file without the extension.
977 the basename of the file without the extension.
981
978
982 When scripts are executed via %run, we must keep a reference to their
979 When scripts are executed via %run, we must keep a reference to their
983 __main__ module around so that Python doesn't
980 __main__ module around so that Python doesn't
984 clear it, rendering references to module globals useless.
981 clear it, rendering references to module globals useless.
985
982
986 This method keeps said reference in a private dict, keyed by the
983 This method keeps said reference in a private dict, keyed by the
987 absolute path of the script. This way, for multiple executions of the
984 absolute path of the script. This way, for multiple executions of the
988 same script we only keep one copy of the namespace (the last one),
985 same script we only keep one copy of the namespace (the last one),
989 thus preventing memory leaks from old references while allowing the
986 thus preventing memory leaks from old references while allowing the
990 objects from the last execution to be accessible.
987 objects from the last execution to be accessible.
991 """
988 """
992 filename = os.path.abspath(filename)
989 filename = os.path.abspath(filename)
993 try:
990 try:
994 main_mod = self._main_mod_cache[filename]
991 main_mod = self._main_mod_cache[filename]
995 except KeyError:
992 except KeyError:
996 main_mod = self._main_mod_cache[filename] = types.ModuleType(
993 main_mod = self._main_mod_cache[filename] = types.ModuleType(
997 modname,
994 modname,
998 doc="Module created for script run in IPython")
995 doc="Module created for script run in IPython")
999 else:
996 else:
1000 main_mod.__dict__.clear()
997 main_mod.__dict__.clear()
1001 main_mod.__name__ = modname
998 main_mod.__name__ = modname
1002
999
1003 main_mod.__file__ = filename
1000 main_mod.__file__ = filename
1004 # It seems pydoc (and perhaps others) needs any module instance to
1001 # It seems pydoc (and perhaps others) needs any module instance to
1005 # implement a __nonzero__ method
1002 # implement a __nonzero__ method
1006 main_mod.__nonzero__ = lambda : True
1003 main_mod.__nonzero__ = lambda : True
1007
1004
1008 return main_mod
1005 return main_mod
1009
1006
1010 def clear_main_mod_cache(self):
1007 def clear_main_mod_cache(self):
1011 """Clear the cache of main modules.
1008 """Clear the cache of main modules.
1012
1009
1013 Mainly for use by utilities like %reset.
1010 Mainly for use by utilities like %reset.
1014
1011
1015 Examples
1012 Examples
1016 --------
1013 --------
1017 In [15]: import IPython
1014 In [15]: import IPython
1018
1015
1019 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
1016 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
1020
1017
1021 In [17]: len(_ip._main_mod_cache) > 0
1018 In [17]: len(_ip._main_mod_cache) > 0
1022 Out[17]: True
1019 Out[17]: True
1023
1020
1024 In [18]: _ip.clear_main_mod_cache()
1021 In [18]: _ip.clear_main_mod_cache()
1025
1022
1026 In [19]: len(_ip._main_mod_cache) == 0
1023 In [19]: len(_ip._main_mod_cache) == 0
1027 Out[19]: True
1024 Out[19]: True
1028 """
1025 """
1029 self._main_mod_cache.clear()
1026 self._main_mod_cache.clear()
1030
1027
1031 #-------------------------------------------------------------------------
1028 #-------------------------------------------------------------------------
1032 # Things related to debugging
1029 # Things related to debugging
1033 #-------------------------------------------------------------------------
1030 #-------------------------------------------------------------------------
1034
1031
1035 def init_pdb(self):
1032 def init_pdb(self):
1036 # Set calling of pdb on exceptions
1033 # Set calling of pdb on exceptions
1037 # self.call_pdb is a property
1034 # self.call_pdb is a property
1038 self.call_pdb = self.pdb
1035 self.call_pdb = self.pdb
1039
1036
1040 def _get_call_pdb(self):
1037 def _get_call_pdb(self):
1041 return self._call_pdb
1038 return self._call_pdb
1042
1039
1043 def _set_call_pdb(self,val):
1040 def _set_call_pdb(self,val):
1044
1041
1045 if val not in (0,1,False,True):
1042 if val not in (0,1,False,True):
1046 raise ValueError('new call_pdb value must be boolean')
1043 raise ValueError('new call_pdb value must be boolean')
1047
1044
1048 # store value in instance
1045 # store value in instance
1049 self._call_pdb = val
1046 self._call_pdb = val
1050
1047
1051 # notify the actual exception handlers
1048 # notify the actual exception handlers
1052 self.InteractiveTB.call_pdb = val
1049 self.InteractiveTB.call_pdb = val
1053
1050
1054 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1051 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1055 'Control auto-activation of pdb at exceptions')
1052 'Control auto-activation of pdb at exceptions')
1056
1053
1057 def debugger(self,force=False):
1054 def debugger(self,force=False):
1058 """Call the pdb debugger.
1055 """Call the pdb debugger.
1059
1056
1060 Keywords:
1057 Keywords:
1061
1058
1062 - force(False): by default, this routine checks the instance call_pdb
1059 - force(False): by default, this routine checks the instance call_pdb
1063 flag and does not actually invoke the debugger if the flag is false.
1060 flag and does not actually invoke the debugger if the flag is false.
1064 The 'force' option forces the debugger to activate even if the flag
1061 The 'force' option forces the debugger to activate even if the flag
1065 is false.
1062 is false.
1066 """
1063 """
1067
1064
1068 if not (force or self.call_pdb):
1065 if not (force or self.call_pdb):
1069 return
1066 return
1070
1067
1071 if not hasattr(sys,'last_traceback'):
1068 if not hasattr(sys,'last_traceback'):
1072 error('No traceback has been produced, nothing to debug.')
1069 error('No traceback has been produced, nothing to debug.')
1073 return
1070 return
1074
1071
1075 self.InteractiveTB.debugger(force=True)
1072 self.InteractiveTB.debugger(force=True)
1076
1073
1077 #-------------------------------------------------------------------------
1074 #-------------------------------------------------------------------------
1078 # Things related to IPython's various namespaces
1075 # Things related to IPython's various namespaces
1079 #-------------------------------------------------------------------------
1076 #-------------------------------------------------------------------------
1080 default_user_namespaces = True
1077 default_user_namespaces = True
1081
1078
1082 def init_create_namespaces(self, user_module=None, user_ns=None):
1079 def init_create_namespaces(self, user_module=None, user_ns=None):
1083 # Create the namespace where the user will operate. user_ns is
1080 # Create the namespace where the user will operate. user_ns is
1084 # normally the only one used, and it is passed to the exec calls as
1081 # normally the only one used, and it is passed to the exec calls as
1085 # the locals argument. But we do carry a user_global_ns namespace
1082 # the locals argument. But we do carry a user_global_ns namespace
1086 # given as the exec 'globals' argument, This is useful in embedding
1083 # given as the exec 'globals' argument, This is useful in embedding
1087 # situations where the ipython shell opens in a context where the
1084 # situations where the ipython shell opens in a context where the
1088 # distinction between locals and globals is meaningful. For
1085 # distinction between locals and globals is meaningful. For
1089 # non-embedded contexts, it is just the same object as the user_ns dict.
1086 # non-embedded contexts, it is just the same object as the user_ns dict.
1090
1087
1091 # FIXME. For some strange reason, __builtins__ is showing up at user
1088 # FIXME. For some strange reason, __builtins__ is showing up at user
1092 # level as a dict instead of a module. This is a manual fix, but I
1089 # level as a dict instead of a module. This is a manual fix, but I
1093 # should really track down where the problem is coming from. Alex
1090 # should really track down where the problem is coming from. Alex
1094 # Schmolck reported this problem first.
1091 # Schmolck reported this problem first.
1095
1092
1096 # A useful post by Alex Martelli on this topic:
1093 # A useful post by Alex Martelli on this topic:
1097 # Re: inconsistent value from __builtins__
1094 # Re: inconsistent value from __builtins__
1098 # Von: Alex Martelli <aleaxit@yahoo.com>
1095 # Von: Alex Martelli <aleaxit@yahoo.com>
1099 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1096 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1100 # Gruppen: comp.lang.python
1097 # Gruppen: comp.lang.python
1101
1098
1102 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1099 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1103 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1100 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1104 # > <type 'dict'>
1101 # > <type 'dict'>
1105 # > >>> print type(__builtins__)
1102 # > >>> print type(__builtins__)
1106 # > <type 'module'>
1103 # > <type 'module'>
1107 # > Is this difference in return value intentional?
1104 # > Is this difference in return value intentional?
1108
1105
1109 # Well, it's documented that '__builtins__' can be either a dictionary
1106 # Well, it's documented that '__builtins__' can be either a dictionary
1110 # or a module, and it's been that way for a long time. Whether it's
1107 # or a module, and it's been that way for a long time. Whether it's
1111 # intentional (or sensible), I don't know. In any case, the idea is
1108 # intentional (or sensible), I don't know. In any case, the idea is
1112 # that if you need to access the built-in namespace directly, you
1109 # that if you need to access the built-in namespace directly, you
1113 # should start with "import __builtin__" (note, no 's') which will
1110 # should start with "import __builtin__" (note, no 's') which will
1114 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1111 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1115
1112
1116 # These routines return a properly built module and dict as needed by
1113 # These routines return a properly built module and dict as needed by
1117 # the rest of the code, and can also be used by extension writers to
1114 # the rest of the code, and can also be used by extension writers to
1118 # generate properly initialized namespaces.
1115 # generate properly initialized namespaces.
1119 if (user_ns is not None) or (user_module is not None):
1116 if (user_ns is not None) or (user_module is not None):
1120 self.default_user_namespaces = False
1117 self.default_user_namespaces = False
1121 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1118 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1122
1119
1123 # A record of hidden variables we have added to the user namespace, so
1120 # A record of hidden variables we have added to the user namespace, so
1124 # we can list later only variables defined in actual interactive use.
1121 # we can list later only variables defined in actual interactive use.
1125 self.user_ns_hidden = {}
1122 self.user_ns_hidden = {}
1126
1123
1127 # Now that FakeModule produces a real module, we've run into a nasty
1124 # Now that FakeModule produces a real module, we've run into a nasty
1128 # problem: after script execution (via %run), the module where the user
1125 # problem: after script execution (via %run), the module where the user
1129 # code ran is deleted. Now that this object is a true module (needed
1126 # code ran is deleted. Now that this object is a true module (needed
1130 # so doctest and other tools work correctly), the Python module
1127 # so doctest and other tools work correctly), the Python module
1131 # teardown mechanism runs over it, and sets to None every variable
1128 # teardown mechanism runs over it, and sets to None every variable
1132 # present in that module. Top-level references to objects from the
1129 # present in that module. Top-level references to objects from the
1133 # script survive, because the user_ns is updated with them. However,
1130 # script survive, because the user_ns is updated with them. However,
1134 # calling functions defined in the script that use other things from
1131 # calling functions defined in the script that use other things from
1135 # the script will fail, because the function's closure had references
1132 # the script will fail, because the function's closure had references
1136 # to the original objects, which are now all None. So we must protect
1133 # to the original objects, which are now all None. So we must protect
1137 # these modules from deletion by keeping a cache.
1134 # these modules from deletion by keeping a cache.
1138 #
1135 #
1139 # To avoid keeping stale modules around (we only need the one from the
1136 # To avoid keeping stale modules around (we only need the one from the
1140 # last run), we use a dict keyed with the full path to the script, so
1137 # last run), we use a dict keyed with the full path to the script, so
1141 # only the last version of the module is held in the cache. Note,
1138 # only the last version of the module is held in the cache. Note,
1142 # however, that we must cache the module *namespace contents* (their
1139 # however, that we must cache the module *namespace contents* (their
1143 # __dict__). Because if we try to cache the actual modules, old ones
1140 # __dict__). Because if we try to cache the actual modules, old ones
1144 # (uncached) could be destroyed while still holding references (such as
1141 # (uncached) could be destroyed while still holding references (such as
1145 # those held by GUI objects that tend to be long-lived)>
1142 # those held by GUI objects that tend to be long-lived)>
1146 #
1143 #
1147 # The %reset command will flush this cache. See the cache_main_mod()
1144 # The %reset command will flush this cache. See the cache_main_mod()
1148 # and clear_main_mod_cache() methods for details on use.
1145 # and clear_main_mod_cache() methods for details on use.
1149
1146
1150 # This is the cache used for 'main' namespaces
1147 # This is the cache used for 'main' namespaces
1151 self._main_mod_cache = {}
1148 self._main_mod_cache = {}
1152
1149
1153 # A table holding all the namespaces IPython deals with, so that
1150 # A table holding all the namespaces IPython deals with, so that
1154 # introspection facilities can search easily.
1151 # introspection facilities can search easily.
1155 self.ns_table = {'user_global':self.user_module.__dict__,
1152 self.ns_table = {'user_global':self.user_module.__dict__,
1156 'user_local':self.user_ns,
1153 'user_local':self.user_ns,
1157 'builtin':builtin_mod.__dict__
1154 'builtin':builtin_mod.__dict__
1158 }
1155 }
1159
1156
1160 @property
1157 @property
1161 def user_global_ns(self):
1158 def user_global_ns(self):
1162 return self.user_module.__dict__
1159 return self.user_module.__dict__
1163
1160
1164 def prepare_user_module(self, user_module=None, user_ns=None):
1161 def prepare_user_module(self, user_module=None, user_ns=None):
1165 """Prepare the module and namespace in which user code will be run.
1162 """Prepare the module and namespace in which user code will be run.
1166
1163
1167 When IPython is started normally, both parameters are None: a new module
1164 When IPython is started normally, both parameters are None: a new module
1168 is created automatically, and its __dict__ used as the namespace.
1165 is created automatically, and its __dict__ used as the namespace.
1169
1166
1170 If only user_module is provided, its __dict__ is used as the namespace.
1167 If only user_module is provided, its __dict__ is used as the namespace.
1171 If only user_ns is provided, a dummy module is created, and user_ns
1168 If only user_ns is provided, a dummy module is created, and user_ns
1172 becomes the global namespace. If both are provided (as they may be
1169 becomes the global namespace. If both are provided (as they may be
1173 when embedding), user_ns is the local namespace, and user_module
1170 when embedding), user_ns is the local namespace, and user_module
1174 provides the global namespace.
1171 provides the global namespace.
1175
1172
1176 Parameters
1173 Parameters
1177 ----------
1174 ----------
1178 user_module : module, optional
1175 user_module : module, optional
1179 The current user module in which IPython is being run. If None,
1176 The current user module in which IPython is being run. If None,
1180 a clean module will be created.
1177 a clean module will be created.
1181 user_ns : dict, optional
1178 user_ns : dict, optional
1182 A namespace in which to run interactive commands.
1179 A namespace in which to run interactive commands.
1183
1180
1184 Returns
1181 Returns
1185 -------
1182 -------
1186 A tuple of user_module and user_ns, each properly initialised.
1183 A tuple of user_module and user_ns, each properly initialised.
1187 """
1184 """
1188 if user_module is None and user_ns is not None:
1185 if user_module is None and user_ns is not None:
1189 user_ns.setdefault("__name__", "__main__")
1186 user_ns.setdefault("__name__", "__main__")
1190 user_module = DummyMod()
1187 user_module = DummyMod()
1191 user_module.__dict__ = user_ns
1188 user_module.__dict__ = user_ns
1192
1189
1193 if user_module is None:
1190 if user_module is None:
1194 user_module = types.ModuleType("__main__",
1191 user_module = types.ModuleType("__main__",
1195 doc="Automatically created module for IPython interactive environment")
1192 doc="Automatically created module for IPython interactive environment")
1196
1193
1197 # We must ensure that __builtin__ (without the final 's') is always
1194 # We must ensure that __builtin__ (without the final 's') is always
1198 # available and pointing to the __builtin__ *module*. For more details:
1195 # available and pointing to the __builtin__ *module*. For more details:
1199 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1196 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1200 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1197 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1201 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1198 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1202
1199
1203 if user_ns is None:
1200 if user_ns is None:
1204 user_ns = user_module.__dict__
1201 user_ns = user_module.__dict__
1205
1202
1206 return user_module, user_ns
1203 return user_module, user_ns
1207
1204
1208 def init_sys_modules(self):
1205 def init_sys_modules(self):
1209 # We need to insert into sys.modules something that looks like a
1206 # We need to insert into sys.modules something that looks like a
1210 # module but which accesses the IPython namespace, for shelve and
1207 # module but which accesses the IPython namespace, for shelve and
1211 # pickle to work interactively. Normally they rely on getting
1208 # pickle to work interactively. Normally they rely on getting
1212 # everything out of __main__, but for embedding purposes each IPython
1209 # everything out of __main__, but for embedding purposes each IPython
1213 # instance has its own private namespace, so we can't go shoving
1210 # instance has its own private namespace, so we can't go shoving
1214 # everything into __main__.
1211 # everything into __main__.
1215
1212
1216 # note, however, that we should only do this for non-embedded
1213 # note, however, that we should only do this for non-embedded
1217 # ipythons, which really mimic the __main__.__dict__ with their own
1214 # ipythons, which really mimic the __main__.__dict__ with their own
1218 # namespace. Embedded instances, on the other hand, should not do
1215 # namespace. Embedded instances, on the other hand, should not do
1219 # this because they need to manage the user local/global namespaces
1216 # this because they need to manage the user local/global namespaces
1220 # only, but they live within a 'normal' __main__ (meaning, they
1217 # only, but they live within a 'normal' __main__ (meaning, they
1221 # shouldn't overtake the execution environment of the script they're
1218 # shouldn't overtake the execution environment of the script they're
1222 # embedded in).
1219 # embedded in).
1223
1220
1224 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1221 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1225 main_name = self.user_module.__name__
1222 main_name = self.user_module.__name__
1226 sys.modules[main_name] = self.user_module
1223 sys.modules[main_name] = self.user_module
1227
1224
1228 def init_user_ns(self):
1225 def init_user_ns(self):
1229 """Initialize all user-visible namespaces to their minimum defaults.
1226 """Initialize all user-visible namespaces to their minimum defaults.
1230
1227
1231 Certain history lists are also initialized here, as they effectively
1228 Certain history lists are also initialized here, as they effectively
1232 act as user namespaces.
1229 act as user namespaces.
1233
1230
1234 Notes
1231 Notes
1235 -----
1232 -----
1236 All data structures here are only filled in, they are NOT reset by this
1233 All data structures here are only filled in, they are NOT reset by this
1237 method. If they were not empty before, data will simply be added to
1234 method. If they were not empty before, data will simply be added to
1238 them.
1235 them.
1239 """
1236 """
1240 # This function works in two parts: first we put a few things in
1237 # This function works in two parts: first we put a few things in
1241 # user_ns, and we sync that contents into user_ns_hidden so that these
1238 # user_ns, and we sync that contents into user_ns_hidden so that these
1242 # initial variables aren't shown by %who. After the sync, we add the
1239 # initial variables aren't shown by %who. After the sync, we add the
1243 # rest of what we *do* want the user to see with %who even on a new
1240 # rest of what we *do* want the user to see with %who even on a new
1244 # session (probably nothing, so they really only see their own stuff)
1241 # session (probably nothing, so they really only see their own stuff)
1245
1242
1246 # The user dict must *always* have a __builtin__ reference to the
1243 # The user dict must *always* have a __builtin__ reference to the
1247 # Python standard __builtin__ namespace, which must be imported.
1244 # Python standard __builtin__ namespace, which must be imported.
1248 # This is so that certain operations in prompt evaluation can be
1245 # This is so that certain operations in prompt evaluation can be
1249 # reliably executed with builtins. Note that we can NOT use
1246 # reliably executed with builtins. Note that we can NOT use
1250 # __builtins__ (note the 's'), because that can either be a dict or a
1247 # __builtins__ (note the 's'), because that can either be a dict or a
1251 # module, and can even mutate at runtime, depending on the context
1248 # module, and can even mutate at runtime, depending on the context
1252 # (Python makes no guarantees on it). In contrast, __builtin__ is
1249 # (Python makes no guarantees on it). In contrast, __builtin__ is
1253 # always a module object, though it must be explicitly imported.
1250 # always a module object, though it must be explicitly imported.
1254
1251
1255 # For more details:
1252 # For more details:
1256 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1253 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1257 ns = {}
1254 ns = {}
1258
1255
1259 # make global variables for user access to the histories
1256 # make global variables for user access to the histories
1260 ns['_ih'] = self.history_manager.input_hist_parsed
1257 ns['_ih'] = self.history_manager.input_hist_parsed
1261 ns['_oh'] = self.history_manager.output_hist
1258 ns['_oh'] = self.history_manager.output_hist
1262 ns['_dh'] = self.history_manager.dir_hist
1259 ns['_dh'] = self.history_manager.dir_hist
1263
1260
1264 # user aliases to input and output histories. These shouldn't show up
1261 # user aliases to input and output histories. These shouldn't show up
1265 # in %who, as they can have very large reprs.
1262 # in %who, as they can have very large reprs.
1266 ns['In'] = self.history_manager.input_hist_parsed
1263 ns['In'] = self.history_manager.input_hist_parsed
1267 ns['Out'] = self.history_manager.output_hist
1264 ns['Out'] = self.history_manager.output_hist
1268
1265
1269 # Store myself as the public api!!!
1266 # Store myself as the public api!!!
1270 ns['get_ipython'] = self.get_ipython
1267 ns['get_ipython'] = self.get_ipython
1271
1268
1272 ns['exit'] = self.exiter
1269 ns['exit'] = self.exiter
1273 ns['quit'] = self.exiter
1270 ns['quit'] = self.exiter
1274
1271
1275 # Sync what we've added so far to user_ns_hidden so these aren't seen
1272 # Sync what we've added so far to user_ns_hidden so these aren't seen
1276 # by %who
1273 # by %who
1277 self.user_ns_hidden.update(ns)
1274 self.user_ns_hidden.update(ns)
1278
1275
1279 # Anything put into ns now would show up in %who. Think twice before
1276 # Anything put into ns now would show up in %who. Think twice before
1280 # putting anything here, as we really want %who to show the user their
1277 # putting anything here, as we really want %who to show the user their
1281 # stuff, not our variables.
1278 # stuff, not our variables.
1282
1279
1283 # Finally, update the real user's namespace
1280 # Finally, update the real user's namespace
1284 self.user_ns.update(ns)
1281 self.user_ns.update(ns)
1285
1282
1286 @property
1283 @property
1287 def all_ns_refs(self):
1284 def all_ns_refs(self):
1288 """Get a list of references to all the namespace dictionaries in which
1285 """Get a list of references to all the namespace dictionaries in which
1289 IPython might store a user-created object.
1286 IPython might store a user-created object.
1290
1287
1291 Note that this does not include the displayhook, which also caches
1288 Note that this does not include the displayhook, which also caches
1292 objects from the output."""
1289 objects from the output."""
1293 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1290 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1294 [m.__dict__ for m in self._main_mod_cache.values()]
1291 [m.__dict__ for m in self._main_mod_cache.values()]
1295
1292
1296 def reset(self, new_session=True, aggressive=False):
1293 def reset(self, new_session=True, aggressive=False):
1297 """Clear all internal namespaces, and attempt to release references to
1294 """Clear all internal namespaces, and attempt to release references to
1298 user objects.
1295 user objects.
1299
1296
1300 If new_session is True, a new history session will be opened.
1297 If new_session is True, a new history session will be opened.
1301 """
1298 """
1302 # Clear histories
1299 # Clear histories
1303 self.history_manager.reset(new_session)
1300 self.history_manager.reset(new_session)
1304 # Reset counter used to index all histories
1301 # Reset counter used to index all histories
1305 if new_session:
1302 if new_session:
1306 self.execution_count = 1
1303 self.execution_count = 1
1307
1304
1308 # Reset last execution result
1305 # Reset last execution result
1309 self.last_execution_succeeded = True
1306 self.last_execution_succeeded = True
1310 self.last_execution_result = None
1307 self.last_execution_result = None
1311
1308
1312 # Flush cached output items
1309 # Flush cached output items
1313 if self.displayhook.do_full_cache:
1310 if self.displayhook.do_full_cache:
1314 self.displayhook.flush()
1311 self.displayhook.flush()
1315
1312
1316 # The main execution namespaces must be cleared very carefully,
1313 # The main execution namespaces must be cleared very carefully,
1317 # skipping the deletion of the builtin-related keys, because doing so
1314 # skipping the deletion of the builtin-related keys, because doing so
1318 # would cause errors in many object's __del__ methods.
1315 # would cause errors in many object's __del__ methods.
1319 if self.user_ns is not self.user_global_ns:
1316 if self.user_ns is not self.user_global_ns:
1320 self.user_ns.clear()
1317 self.user_ns.clear()
1321 ns = self.user_global_ns
1318 ns = self.user_global_ns
1322 drop_keys = set(ns.keys())
1319 drop_keys = set(ns.keys())
1323 drop_keys.discard('__builtin__')
1320 drop_keys.discard('__builtin__')
1324 drop_keys.discard('__builtins__')
1321 drop_keys.discard('__builtins__')
1325 drop_keys.discard('__name__')
1322 drop_keys.discard('__name__')
1326 for k in drop_keys:
1323 for k in drop_keys:
1327 del ns[k]
1324 del ns[k]
1328
1325
1329 self.user_ns_hidden.clear()
1326 self.user_ns_hidden.clear()
1330
1327
1331 # Restore the user namespaces to minimal usability
1328 # Restore the user namespaces to minimal usability
1332 self.init_user_ns()
1329 self.init_user_ns()
1333 if aggressive and not hasattr(self, "_sys_modules_keys"):
1330 if aggressive and not hasattr(self, "_sys_modules_keys"):
1334 print("Cannot restore sys.module, no snapshot")
1331 print("Cannot restore sys.module, no snapshot")
1335 elif aggressive:
1332 elif aggressive:
1336 print("culling sys module...")
1333 print("culling sys module...")
1337 current_keys = set(sys.modules.keys())
1334 current_keys = set(sys.modules.keys())
1338 for k in current_keys - self._sys_modules_keys:
1335 for k in current_keys - self._sys_modules_keys:
1339 if k.startswith("multiprocessing"):
1336 if k.startswith("multiprocessing"):
1340 continue
1337 continue
1341 del sys.modules[k]
1338 del sys.modules[k]
1342
1339
1343 # Restore the default and user aliases
1340 # Restore the default and user aliases
1344 self.alias_manager.clear_aliases()
1341 self.alias_manager.clear_aliases()
1345 self.alias_manager.init_aliases()
1342 self.alias_manager.init_aliases()
1346
1343
1347 # Now define aliases that only make sense on the terminal, because they
1344 # Now define aliases that only make sense on the terminal, because they
1348 # need direct access to the console in a way that we can't emulate in
1345 # need direct access to the console in a way that we can't emulate in
1349 # GUI or web frontend
1346 # GUI or web frontend
1350 if os.name == 'posix':
1347 if os.name == 'posix':
1351 for cmd in ('clear', 'more', 'less', 'man'):
1348 for cmd in ('clear', 'more', 'less', 'man'):
1352 if cmd not in self.magics_manager.magics['line']:
1349 if cmd not in self.magics_manager.magics['line']:
1353 self.alias_manager.soft_define_alias(cmd, cmd)
1350 self.alias_manager.soft_define_alias(cmd, cmd)
1354
1351
1355 # Flush the private list of module references kept for script
1352 # Flush the private list of module references kept for script
1356 # execution protection
1353 # execution protection
1357 self.clear_main_mod_cache()
1354 self.clear_main_mod_cache()
1358
1355
1359 def del_var(self, varname, by_name=False):
1356 def del_var(self, varname, by_name=False):
1360 """Delete a variable from the various namespaces, so that, as
1357 """Delete a variable from the various namespaces, so that, as
1361 far as possible, we're not keeping any hidden references to it.
1358 far as possible, we're not keeping any hidden references to it.
1362
1359
1363 Parameters
1360 Parameters
1364 ----------
1361 ----------
1365 varname : str
1362 varname : str
1366 The name of the variable to delete.
1363 The name of the variable to delete.
1367 by_name : bool
1364 by_name : bool
1368 If True, delete variables with the given name in each
1365 If True, delete variables with the given name in each
1369 namespace. If False (default), find the variable in the user
1366 namespace. If False (default), find the variable in the user
1370 namespace, and delete references to it.
1367 namespace, and delete references to it.
1371 """
1368 """
1372 if varname in ('__builtin__', '__builtins__'):
1369 if varname in ('__builtin__', '__builtins__'):
1373 raise ValueError("Refusing to delete %s" % varname)
1370 raise ValueError("Refusing to delete %s" % varname)
1374
1371
1375 ns_refs = self.all_ns_refs
1372 ns_refs = self.all_ns_refs
1376
1373
1377 if by_name: # Delete by name
1374 if by_name: # Delete by name
1378 for ns in ns_refs:
1375 for ns in ns_refs:
1379 try:
1376 try:
1380 del ns[varname]
1377 del ns[varname]
1381 except KeyError:
1378 except KeyError:
1382 pass
1379 pass
1383 else: # Delete by object
1380 else: # Delete by object
1384 try:
1381 try:
1385 obj = self.user_ns[varname]
1382 obj = self.user_ns[varname]
1386 except KeyError as e:
1383 except KeyError as e:
1387 raise NameError("name '%s' is not defined" % varname) from e
1384 raise NameError("name '%s' is not defined" % varname) from e
1388 # Also check in output history
1385 # Also check in output history
1389 ns_refs.append(self.history_manager.output_hist)
1386 ns_refs.append(self.history_manager.output_hist)
1390 for ns in ns_refs:
1387 for ns in ns_refs:
1391 to_delete = [n for n, o in ns.items() if o is obj]
1388 to_delete = [n for n, o in ns.items() if o is obj]
1392 for name in to_delete:
1389 for name in to_delete:
1393 del ns[name]
1390 del ns[name]
1394
1391
1395 # Ensure it is removed from the last execution result
1392 # Ensure it is removed from the last execution result
1396 if self.last_execution_result.result is obj:
1393 if self.last_execution_result.result is obj:
1397 self.last_execution_result = None
1394 self.last_execution_result = None
1398
1395
1399 # displayhook keeps extra references, but not in a dictionary
1396 # displayhook keeps extra references, but not in a dictionary
1400 for name in ('_', '__', '___'):
1397 for name in ('_', '__', '___'):
1401 if getattr(self.displayhook, name) is obj:
1398 if getattr(self.displayhook, name) is obj:
1402 setattr(self.displayhook, name, None)
1399 setattr(self.displayhook, name, None)
1403
1400
1404 def reset_selective(self, regex=None):
1401 def reset_selective(self, regex=None):
1405 """Clear selective variables from internal namespaces based on a
1402 """Clear selective variables from internal namespaces based on a
1406 specified regular expression.
1403 specified regular expression.
1407
1404
1408 Parameters
1405 Parameters
1409 ----------
1406 ----------
1410 regex : string or compiled pattern, optional
1407 regex : string or compiled pattern, optional
1411 A regular expression pattern that will be used in searching
1408 A regular expression pattern that will be used in searching
1412 variable names in the users namespaces.
1409 variable names in the users namespaces.
1413 """
1410 """
1414 if regex is not None:
1411 if regex is not None:
1415 try:
1412 try:
1416 m = re.compile(regex)
1413 m = re.compile(regex)
1417 except TypeError as e:
1414 except TypeError as e:
1418 raise TypeError('regex must be a string or compiled pattern') from e
1415 raise TypeError('regex must be a string or compiled pattern') from e
1419 # Search for keys in each namespace that match the given regex
1416 # Search for keys in each namespace that match the given regex
1420 # If a match is found, delete the key/value pair.
1417 # If a match is found, delete the key/value pair.
1421 for ns in self.all_ns_refs:
1418 for ns in self.all_ns_refs:
1422 for var in ns:
1419 for var in ns:
1423 if m.search(var):
1420 if m.search(var):
1424 del ns[var]
1421 del ns[var]
1425
1422
1426 def push(self, variables, interactive=True):
1423 def push(self, variables, interactive=True):
1427 """Inject a group of variables into the IPython user namespace.
1424 """Inject a group of variables into the IPython user namespace.
1428
1425
1429 Parameters
1426 Parameters
1430 ----------
1427 ----------
1431 variables : dict, str or list/tuple of str
1428 variables : dict, str or list/tuple of str
1432 The variables to inject into the user's namespace. If a dict, a
1429 The variables to inject into the user's namespace. If a dict, a
1433 simple update is done. If a str, the string is assumed to have
1430 simple update is done. If a str, the string is assumed to have
1434 variable names separated by spaces. A list/tuple of str can also
1431 variable names separated by spaces. A list/tuple of str can also
1435 be used to give the variable names. If just the variable names are
1432 be used to give the variable names. If just the variable names are
1436 give (list/tuple/str) then the variable values looked up in the
1433 give (list/tuple/str) then the variable values looked up in the
1437 callers frame.
1434 callers frame.
1438 interactive : bool
1435 interactive : bool
1439 If True (default), the variables will be listed with the ``who``
1436 If True (default), the variables will be listed with the ``who``
1440 magic.
1437 magic.
1441 """
1438 """
1442 vdict = None
1439 vdict = None
1443
1440
1444 # We need a dict of name/value pairs to do namespace updates.
1441 # We need a dict of name/value pairs to do namespace updates.
1445 if isinstance(variables, dict):
1442 if isinstance(variables, dict):
1446 vdict = variables
1443 vdict = variables
1447 elif isinstance(variables, (str, list, tuple)):
1444 elif isinstance(variables, (str, list, tuple)):
1448 if isinstance(variables, str):
1445 if isinstance(variables, str):
1449 vlist = variables.split()
1446 vlist = variables.split()
1450 else:
1447 else:
1451 vlist = variables
1448 vlist = variables
1452 vdict = {}
1449 vdict = {}
1453 cf = sys._getframe(1)
1450 cf = sys._getframe(1)
1454 for name in vlist:
1451 for name in vlist:
1455 try:
1452 try:
1456 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1453 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1457 except:
1454 except:
1458 print('Could not get variable %s from %s' %
1455 print('Could not get variable %s from %s' %
1459 (name,cf.f_code.co_name))
1456 (name,cf.f_code.co_name))
1460 else:
1457 else:
1461 raise ValueError('variables must be a dict/str/list/tuple')
1458 raise ValueError('variables must be a dict/str/list/tuple')
1462
1459
1463 # Propagate variables to user namespace
1460 # Propagate variables to user namespace
1464 self.user_ns.update(vdict)
1461 self.user_ns.update(vdict)
1465
1462
1466 # And configure interactive visibility
1463 # And configure interactive visibility
1467 user_ns_hidden = self.user_ns_hidden
1464 user_ns_hidden = self.user_ns_hidden
1468 if interactive:
1465 if interactive:
1469 for name in vdict:
1466 for name in vdict:
1470 user_ns_hidden.pop(name, None)
1467 user_ns_hidden.pop(name, None)
1471 else:
1468 else:
1472 user_ns_hidden.update(vdict)
1469 user_ns_hidden.update(vdict)
1473
1470
1474 def drop_by_id(self, variables):
1471 def drop_by_id(self, variables):
1475 """Remove a dict of variables from the user namespace, if they are the
1472 """Remove a dict of variables from the user namespace, if they are the
1476 same as the values in the dictionary.
1473 same as the values in the dictionary.
1477
1474
1478 This is intended for use by extensions: variables that they've added can
1475 This is intended for use by extensions: variables that they've added can
1479 be taken back out if they are unloaded, without removing any that the
1476 be taken back out if they are unloaded, without removing any that the
1480 user has overwritten.
1477 user has overwritten.
1481
1478
1482 Parameters
1479 Parameters
1483 ----------
1480 ----------
1484 variables : dict
1481 variables : dict
1485 A dictionary mapping object names (as strings) to the objects.
1482 A dictionary mapping object names (as strings) to the objects.
1486 """
1483 """
1487 for name, obj in variables.items():
1484 for name, obj in variables.items():
1488 if name in self.user_ns and self.user_ns[name] is obj:
1485 if name in self.user_ns and self.user_ns[name] is obj:
1489 del self.user_ns[name]
1486 del self.user_ns[name]
1490 self.user_ns_hidden.pop(name, None)
1487 self.user_ns_hidden.pop(name, None)
1491
1488
1492 #-------------------------------------------------------------------------
1489 #-------------------------------------------------------------------------
1493 # Things related to object introspection
1490 # Things related to object introspection
1494 #-------------------------------------------------------------------------
1491 #-------------------------------------------------------------------------
1495
1492
1496 def _ofind(self, oname, namespaces=None):
1493 def _ofind(self, oname, namespaces=None):
1497 """Find an object in the available namespaces.
1494 """Find an object in the available namespaces.
1498
1495
1499 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1496 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1500
1497
1501 Has special code to detect magic functions.
1498 Has special code to detect magic functions.
1502 """
1499 """
1503 oname = oname.strip()
1500 oname = oname.strip()
1504 if not oname.startswith(ESC_MAGIC) and \
1501 if not oname.startswith(ESC_MAGIC) and \
1505 not oname.startswith(ESC_MAGIC2) and \
1502 not oname.startswith(ESC_MAGIC2) and \
1506 not all(a.isidentifier() for a in oname.split(".")):
1503 not all(a.isidentifier() for a in oname.split(".")):
1507 return {'found': False}
1504 return {'found': False}
1508
1505
1509 if namespaces is None:
1506 if namespaces is None:
1510 # Namespaces to search in:
1507 # Namespaces to search in:
1511 # Put them in a list. The order is important so that we
1508 # Put them in a list. The order is important so that we
1512 # find things in the same order that Python finds them.
1509 # find things in the same order that Python finds them.
1513 namespaces = [ ('Interactive', self.user_ns),
1510 namespaces = [ ('Interactive', self.user_ns),
1514 ('Interactive (global)', self.user_global_ns),
1511 ('Interactive (global)', self.user_global_ns),
1515 ('Python builtin', builtin_mod.__dict__),
1512 ('Python builtin', builtin_mod.__dict__),
1516 ]
1513 ]
1517
1514
1518 ismagic = False
1515 ismagic = False
1519 isalias = False
1516 isalias = False
1520 found = False
1517 found = False
1521 ospace = None
1518 ospace = None
1522 parent = None
1519 parent = None
1523 obj = None
1520 obj = None
1524
1521
1525
1522
1526 # Look for the given name by splitting it in parts. If the head is
1523 # Look for the given name by splitting it in parts. If the head is
1527 # found, then we look for all the remaining parts as members, and only
1524 # found, then we look for all the remaining parts as members, and only
1528 # declare success if we can find them all.
1525 # declare success if we can find them all.
1529 oname_parts = oname.split('.')
1526 oname_parts = oname.split('.')
1530 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1527 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1531 for nsname,ns in namespaces:
1528 for nsname,ns in namespaces:
1532 try:
1529 try:
1533 obj = ns[oname_head]
1530 obj = ns[oname_head]
1534 except KeyError:
1531 except KeyError:
1535 continue
1532 continue
1536 else:
1533 else:
1537 for idx, part in enumerate(oname_rest):
1534 for idx, part in enumerate(oname_rest):
1538 try:
1535 try:
1539 parent = obj
1536 parent = obj
1540 # The last part is looked up in a special way to avoid
1537 # The last part is looked up in a special way to avoid
1541 # descriptor invocation as it may raise or have side
1538 # descriptor invocation as it may raise or have side
1542 # effects.
1539 # effects.
1543 if idx == len(oname_rest) - 1:
1540 if idx == len(oname_rest) - 1:
1544 obj = self._getattr_property(obj, part)
1541 obj = self._getattr_property(obj, part)
1545 else:
1542 else:
1546 obj = getattr(obj, part)
1543 obj = getattr(obj, part)
1547 except:
1544 except:
1548 # Blanket except b/c some badly implemented objects
1545 # Blanket except b/c some badly implemented objects
1549 # allow __getattr__ to raise exceptions other than
1546 # allow __getattr__ to raise exceptions other than
1550 # AttributeError, which then crashes IPython.
1547 # AttributeError, which then crashes IPython.
1551 break
1548 break
1552 else:
1549 else:
1553 # If we finish the for loop (no break), we got all members
1550 # If we finish the for loop (no break), we got all members
1554 found = True
1551 found = True
1555 ospace = nsname
1552 ospace = nsname
1556 break # namespace loop
1553 break # namespace loop
1557
1554
1558 # Try to see if it's magic
1555 # Try to see if it's magic
1559 if not found:
1556 if not found:
1560 obj = None
1557 obj = None
1561 if oname.startswith(ESC_MAGIC2):
1558 if oname.startswith(ESC_MAGIC2):
1562 oname = oname.lstrip(ESC_MAGIC2)
1559 oname = oname.lstrip(ESC_MAGIC2)
1563 obj = self.find_cell_magic(oname)
1560 obj = self.find_cell_magic(oname)
1564 elif oname.startswith(ESC_MAGIC):
1561 elif oname.startswith(ESC_MAGIC):
1565 oname = oname.lstrip(ESC_MAGIC)
1562 oname = oname.lstrip(ESC_MAGIC)
1566 obj = self.find_line_magic(oname)
1563 obj = self.find_line_magic(oname)
1567 else:
1564 else:
1568 # search without prefix, so run? will find %run?
1565 # search without prefix, so run? will find %run?
1569 obj = self.find_line_magic(oname)
1566 obj = self.find_line_magic(oname)
1570 if obj is None:
1567 if obj is None:
1571 obj = self.find_cell_magic(oname)
1568 obj = self.find_cell_magic(oname)
1572 if obj is not None:
1569 if obj is not None:
1573 found = True
1570 found = True
1574 ospace = 'IPython internal'
1571 ospace = 'IPython internal'
1575 ismagic = True
1572 ismagic = True
1576 isalias = isinstance(obj, Alias)
1573 isalias = isinstance(obj, Alias)
1577
1574
1578 # Last try: special-case some literals like '', [], {}, etc:
1575 # Last try: special-case some literals like '', [], {}, etc:
1579 if not found and oname_head in ["''",'""','[]','{}','()']:
1576 if not found and oname_head in ["''",'""','[]','{}','()']:
1580 obj = eval(oname_head)
1577 obj = eval(oname_head)
1581 found = True
1578 found = True
1582 ospace = 'Interactive'
1579 ospace = 'Interactive'
1583
1580
1584 return {
1581 return {
1585 'obj':obj,
1582 'obj':obj,
1586 'found':found,
1583 'found':found,
1587 'parent':parent,
1584 'parent':parent,
1588 'ismagic':ismagic,
1585 'ismagic':ismagic,
1589 'isalias':isalias,
1586 'isalias':isalias,
1590 'namespace':ospace
1587 'namespace':ospace
1591 }
1588 }
1592
1589
1593 @staticmethod
1590 @staticmethod
1594 def _getattr_property(obj, attrname):
1591 def _getattr_property(obj, attrname):
1595 """Property-aware getattr to use in object finding.
1592 """Property-aware getattr to use in object finding.
1596
1593
1597 If attrname represents a property, return it unevaluated (in case it has
1594 If attrname represents a property, return it unevaluated (in case it has
1598 side effects or raises an error.
1595 side effects or raises an error.
1599
1596
1600 """
1597 """
1601 if not isinstance(obj, type):
1598 if not isinstance(obj, type):
1602 try:
1599 try:
1603 # `getattr(type(obj), attrname)` is not guaranteed to return
1600 # `getattr(type(obj), attrname)` is not guaranteed to return
1604 # `obj`, but does so for property:
1601 # `obj`, but does so for property:
1605 #
1602 #
1606 # property.__get__(self, None, cls) -> self
1603 # property.__get__(self, None, cls) -> self
1607 #
1604 #
1608 # The universal alternative is to traverse the mro manually
1605 # The universal alternative is to traverse the mro manually
1609 # searching for attrname in class dicts.
1606 # searching for attrname in class dicts.
1610 attr = getattr(type(obj), attrname)
1607 attr = getattr(type(obj), attrname)
1611 except AttributeError:
1608 except AttributeError:
1612 pass
1609 pass
1613 else:
1610 else:
1614 # This relies on the fact that data descriptors (with both
1611 # This relies on the fact that data descriptors (with both
1615 # __get__ & __set__ magic methods) take precedence over
1612 # __get__ & __set__ magic methods) take precedence over
1616 # instance-level attributes:
1613 # instance-level attributes:
1617 #
1614 #
1618 # class A(object):
1615 # class A(object):
1619 # @property
1616 # @property
1620 # def foobar(self): return 123
1617 # def foobar(self): return 123
1621 # a = A()
1618 # a = A()
1622 # a.__dict__['foobar'] = 345
1619 # a.__dict__['foobar'] = 345
1623 # a.foobar # == 123
1620 # a.foobar # == 123
1624 #
1621 #
1625 # So, a property may be returned right away.
1622 # So, a property may be returned right away.
1626 if isinstance(attr, property):
1623 if isinstance(attr, property):
1627 return attr
1624 return attr
1628
1625
1629 # Nothing helped, fall back.
1626 # Nothing helped, fall back.
1630 return getattr(obj, attrname)
1627 return getattr(obj, attrname)
1631
1628
1632 def _object_find(self, oname, namespaces=None):
1629 def _object_find(self, oname, namespaces=None):
1633 """Find an object and return a struct with info about it."""
1630 """Find an object and return a struct with info about it."""
1634 return Struct(self._ofind(oname, namespaces))
1631 return Struct(self._ofind(oname, namespaces))
1635
1632
1636 def _inspect(self, meth, oname, namespaces=None, **kw):
1633 def _inspect(self, meth, oname, namespaces=None, **kw):
1637 """Generic interface to the inspector system.
1634 """Generic interface to the inspector system.
1638
1635
1639 This function is meant to be called by pdef, pdoc & friends.
1636 This function is meant to be called by pdef, pdoc & friends.
1640 """
1637 """
1641 info = self._object_find(oname, namespaces)
1638 info = self._object_find(oname, namespaces)
1642 docformat = (
1639 docformat = (
1643 sphinxify(self.object_inspect(oname)) if self.sphinxify_docstring else None
1640 sphinxify(self.object_inspect(oname)) if self.sphinxify_docstring else None
1644 )
1641 )
1645 if info.found:
1642 if info.found:
1646 pmethod = getattr(self.inspector, meth)
1643 pmethod = getattr(self.inspector, meth)
1647 # TODO: only apply format_screen to the plain/text repr of the mime
1644 # TODO: only apply format_screen to the plain/text repr of the mime
1648 # bundle.
1645 # bundle.
1649 formatter = format_screen if info.ismagic else docformat
1646 formatter = format_screen if info.ismagic else docformat
1650 if meth == 'pdoc':
1647 if meth == 'pdoc':
1651 pmethod(info.obj, oname, formatter)
1648 pmethod(info.obj, oname, formatter)
1652 elif meth == 'pinfo':
1649 elif meth == 'pinfo':
1653 pmethod(
1650 pmethod(
1654 info.obj,
1651 info.obj,
1655 oname,
1652 oname,
1656 formatter,
1653 formatter,
1657 info,
1654 info,
1658 enable_html_pager=self.enable_html_pager,
1655 enable_html_pager=self.enable_html_pager,
1659 **kw,
1656 **kw,
1660 )
1657 )
1661 else:
1658 else:
1662 pmethod(info.obj, oname)
1659 pmethod(info.obj, oname)
1663 else:
1660 else:
1664 print('Object `%s` not found.' % oname)
1661 print('Object `%s` not found.' % oname)
1665 return 'not found' # so callers can take other action
1662 return 'not found' # so callers can take other action
1666
1663
1667 def object_inspect(self, oname, detail_level=0):
1664 def object_inspect(self, oname, detail_level=0):
1668 """Get object info about oname"""
1665 """Get object info about oname"""
1669 with self.builtin_trap:
1666 with self.builtin_trap:
1670 info = self._object_find(oname)
1667 info = self._object_find(oname)
1671 if info.found:
1668 if info.found:
1672 return self.inspector.info(info.obj, oname, info=info,
1669 return self.inspector.info(info.obj, oname, info=info,
1673 detail_level=detail_level
1670 detail_level=detail_level
1674 )
1671 )
1675 else:
1672 else:
1676 return oinspect.object_info(name=oname, found=False)
1673 return oinspect.object_info(name=oname, found=False)
1677
1674
1678 def object_inspect_text(self, oname, detail_level=0):
1675 def object_inspect_text(self, oname, detail_level=0):
1679 """Get object info as formatted text"""
1676 """Get object info as formatted text"""
1680 return self.object_inspect_mime(oname, detail_level)['text/plain']
1677 return self.object_inspect_mime(oname, detail_level)['text/plain']
1681
1678
1682 def object_inspect_mime(self, oname, detail_level=0, omit_sections=()):
1679 def object_inspect_mime(self, oname, detail_level=0, omit_sections=()):
1683 """Get object info as a mimebundle of formatted representations.
1680 """Get object info as a mimebundle of formatted representations.
1684
1681
1685 A mimebundle is a dictionary, keyed by mime-type.
1682 A mimebundle is a dictionary, keyed by mime-type.
1686 It must always have the key `'text/plain'`.
1683 It must always have the key `'text/plain'`.
1687 """
1684 """
1688 with self.builtin_trap:
1685 with self.builtin_trap:
1689 info = self._object_find(oname)
1686 info = self._object_find(oname)
1690 if info.found:
1687 if info.found:
1691 docformat = (
1688 docformat = (
1692 sphinxify(self.object_inspect(oname))
1689 sphinxify(self.object_inspect(oname))
1693 if self.sphinxify_docstring
1690 if self.sphinxify_docstring
1694 else None
1691 else None
1695 )
1692 )
1696 return self.inspector._get_info(
1693 return self.inspector._get_info(
1697 info.obj,
1694 info.obj,
1698 oname,
1695 oname,
1699 info=info,
1696 info=info,
1700 detail_level=detail_level,
1697 detail_level=detail_level,
1701 formatter=docformat,
1698 formatter=docformat,
1702 omit_sections=omit_sections,
1699 omit_sections=omit_sections,
1703 )
1700 )
1704 else:
1701 else:
1705 raise KeyError(oname)
1702 raise KeyError(oname)
1706
1703
1707 #-------------------------------------------------------------------------
1704 #-------------------------------------------------------------------------
1708 # Things related to history management
1705 # Things related to history management
1709 #-------------------------------------------------------------------------
1706 #-------------------------------------------------------------------------
1710
1707
1711 def init_history(self):
1708 def init_history(self):
1712 """Sets up the command history, and starts regular autosaves."""
1709 """Sets up the command history, and starts regular autosaves."""
1713 self.history_manager = HistoryManager(shell=self, parent=self)
1710 self.history_manager = HistoryManager(shell=self, parent=self)
1714 self.configurables.append(self.history_manager)
1711 self.configurables.append(self.history_manager)
1715
1712
1716 #-------------------------------------------------------------------------
1713 #-------------------------------------------------------------------------
1717 # Things related to exception handling and tracebacks (not debugging)
1714 # Things related to exception handling and tracebacks (not debugging)
1718 #-------------------------------------------------------------------------
1715 #-------------------------------------------------------------------------
1719
1716
1720 debugger_cls = InterruptiblePdb
1717 debugger_cls = InterruptiblePdb
1721
1718
1722 def init_traceback_handlers(self, custom_exceptions):
1719 def init_traceback_handlers(self, custom_exceptions):
1723 # Syntax error handler.
1720 # Syntax error handler.
1724 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1721 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1725
1722
1726 # The interactive one is initialized with an offset, meaning we always
1723 # The interactive one is initialized with an offset, meaning we always
1727 # want to remove the topmost item in the traceback, which is our own
1724 # want to remove the topmost item in the traceback, which is our own
1728 # internal code. Valid modes: ['Plain','Context','Verbose','Minimal']
1725 # internal code. Valid modes: ['Plain','Context','Verbose','Minimal']
1729 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1726 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1730 color_scheme='NoColor',
1727 color_scheme='NoColor',
1731 tb_offset = 1,
1728 tb_offset = 1,
1732 check_cache=check_linecache_ipython,
1729 check_cache=check_linecache_ipython,
1733 debugger_cls=self.debugger_cls, parent=self)
1730 debugger_cls=self.debugger_cls, parent=self)
1734
1731
1735 # The instance will store a pointer to the system-wide exception hook,
1732 # The instance will store a pointer to the system-wide exception hook,
1736 # so that runtime code (such as magics) can access it. This is because
1733 # so that runtime code (such as magics) can access it. This is because
1737 # during the read-eval loop, it may get temporarily overwritten.
1734 # during the read-eval loop, it may get temporarily overwritten.
1738 self.sys_excepthook = sys.excepthook
1735 self.sys_excepthook = sys.excepthook
1739
1736
1740 # and add any custom exception handlers the user may have specified
1737 # and add any custom exception handlers the user may have specified
1741 self.set_custom_exc(*custom_exceptions)
1738 self.set_custom_exc(*custom_exceptions)
1742
1739
1743 # Set the exception mode
1740 # Set the exception mode
1744 self.InteractiveTB.set_mode(mode=self.xmode)
1741 self.InteractiveTB.set_mode(mode=self.xmode)
1745
1742
1746 def set_custom_exc(self, exc_tuple, handler):
1743 def set_custom_exc(self, exc_tuple, handler):
1747 """set_custom_exc(exc_tuple, handler)
1744 """set_custom_exc(exc_tuple, handler)
1748
1745
1749 Set a custom exception handler, which will be called if any of the
1746 Set a custom exception handler, which will be called if any of the
1750 exceptions in exc_tuple occur in the mainloop (specifically, in the
1747 exceptions in exc_tuple occur in the mainloop (specifically, in the
1751 run_code() method).
1748 run_code() method).
1752
1749
1753 Parameters
1750 Parameters
1754 ----------
1751 ----------
1755 exc_tuple : tuple of exception classes
1752 exc_tuple : tuple of exception classes
1756 A *tuple* of exception classes, for which to call the defined
1753 A *tuple* of exception classes, for which to call the defined
1757 handler. It is very important that you use a tuple, and NOT A
1754 handler. It is very important that you use a tuple, and NOT A
1758 LIST here, because of the way Python's except statement works. If
1755 LIST here, because of the way Python's except statement works. If
1759 you only want to trap a single exception, use a singleton tuple::
1756 you only want to trap a single exception, use a singleton tuple::
1760
1757
1761 exc_tuple == (MyCustomException,)
1758 exc_tuple == (MyCustomException,)
1762
1759
1763 handler : callable
1760 handler : callable
1764 handler must have the following signature::
1761 handler must have the following signature::
1765
1762
1766 def my_handler(self, etype, value, tb, tb_offset=None):
1763 def my_handler(self, etype, value, tb, tb_offset=None):
1767 ...
1764 ...
1768 return structured_traceback
1765 return structured_traceback
1769
1766
1770 Your handler must return a structured traceback (a list of strings),
1767 Your handler must return a structured traceback (a list of strings),
1771 or None.
1768 or None.
1772
1769
1773 This will be made into an instance method (via types.MethodType)
1770 This will be made into an instance method (via types.MethodType)
1774 of IPython itself, and it will be called if any of the exceptions
1771 of IPython itself, and it will be called if any of the exceptions
1775 listed in the exc_tuple are caught. If the handler is None, an
1772 listed in the exc_tuple are caught. If the handler is None, an
1776 internal basic one is used, which just prints basic info.
1773 internal basic one is used, which just prints basic info.
1777
1774
1778 To protect IPython from crashes, if your handler ever raises an
1775 To protect IPython from crashes, if your handler ever raises an
1779 exception or returns an invalid result, it will be immediately
1776 exception or returns an invalid result, it will be immediately
1780 disabled.
1777 disabled.
1781
1778
1782 Notes
1779 Notes
1783 -----
1780 -----
1784 WARNING: by putting in your own exception handler into IPython's main
1781 WARNING: by putting in your own exception handler into IPython's main
1785 execution loop, you run a very good chance of nasty crashes. This
1782 execution loop, you run a very good chance of nasty crashes. This
1786 facility should only be used if you really know what you are doing.
1783 facility should only be used if you really know what you are doing.
1787 """
1784 """
1788
1785
1789 if not isinstance(exc_tuple, tuple):
1786 if not isinstance(exc_tuple, tuple):
1790 raise TypeError("The custom exceptions must be given as a tuple.")
1787 raise TypeError("The custom exceptions must be given as a tuple.")
1791
1788
1792 def dummy_handler(self, etype, value, tb, tb_offset=None):
1789 def dummy_handler(self, etype, value, tb, tb_offset=None):
1793 print('*** Simple custom exception handler ***')
1790 print('*** Simple custom exception handler ***')
1794 print('Exception type :', etype)
1791 print('Exception type :', etype)
1795 print('Exception value:', value)
1792 print('Exception value:', value)
1796 print('Traceback :', tb)
1793 print('Traceback :', tb)
1797
1794
1798 def validate_stb(stb):
1795 def validate_stb(stb):
1799 """validate structured traceback return type
1796 """validate structured traceback return type
1800
1797
1801 return type of CustomTB *should* be a list of strings, but allow
1798 return type of CustomTB *should* be a list of strings, but allow
1802 single strings or None, which are harmless.
1799 single strings or None, which are harmless.
1803
1800
1804 This function will *always* return a list of strings,
1801 This function will *always* return a list of strings,
1805 and will raise a TypeError if stb is inappropriate.
1802 and will raise a TypeError if stb is inappropriate.
1806 """
1803 """
1807 msg = "CustomTB must return list of strings, not %r" % stb
1804 msg = "CustomTB must return list of strings, not %r" % stb
1808 if stb is None:
1805 if stb is None:
1809 return []
1806 return []
1810 elif isinstance(stb, str):
1807 elif isinstance(stb, str):
1811 return [stb]
1808 return [stb]
1812 elif not isinstance(stb, list):
1809 elif not isinstance(stb, list):
1813 raise TypeError(msg)
1810 raise TypeError(msg)
1814 # it's a list
1811 # it's a list
1815 for line in stb:
1812 for line in stb:
1816 # check every element
1813 # check every element
1817 if not isinstance(line, str):
1814 if not isinstance(line, str):
1818 raise TypeError(msg)
1815 raise TypeError(msg)
1819 return stb
1816 return stb
1820
1817
1821 if handler is None:
1818 if handler is None:
1822 wrapped = dummy_handler
1819 wrapped = dummy_handler
1823 else:
1820 else:
1824 def wrapped(self,etype,value,tb,tb_offset=None):
1821 def wrapped(self,etype,value,tb,tb_offset=None):
1825 """wrap CustomTB handler, to protect IPython from user code
1822 """wrap CustomTB handler, to protect IPython from user code
1826
1823
1827 This makes it harder (but not impossible) for custom exception
1824 This makes it harder (but not impossible) for custom exception
1828 handlers to crash IPython.
1825 handlers to crash IPython.
1829 """
1826 """
1830 try:
1827 try:
1831 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1828 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1832 return validate_stb(stb)
1829 return validate_stb(stb)
1833 except:
1830 except:
1834 # clear custom handler immediately
1831 # clear custom handler immediately
1835 self.set_custom_exc((), None)
1832 self.set_custom_exc((), None)
1836 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1833 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1837 # show the exception in handler first
1834 # show the exception in handler first
1838 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1835 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1839 print(self.InteractiveTB.stb2text(stb))
1836 print(self.InteractiveTB.stb2text(stb))
1840 print("The original exception:")
1837 print("The original exception:")
1841 stb = self.InteractiveTB.structured_traceback(
1838 stb = self.InteractiveTB.structured_traceback(
1842 (etype,value,tb), tb_offset=tb_offset
1839 (etype,value,tb), tb_offset=tb_offset
1843 )
1840 )
1844 return stb
1841 return stb
1845
1842
1846 self.CustomTB = types.MethodType(wrapped,self)
1843 self.CustomTB = types.MethodType(wrapped,self)
1847 self.custom_exceptions = exc_tuple
1844 self.custom_exceptions = exc_tuple
1848
1845
1849 def excepthook(self, etype, value, tb):
1846 def excepthook(self, etype, value, tb):
1850 """One more defense for GUI apps that call sys.excepthook.
1847 """One more defense for GUI apps that call sys.excepthook.
1851
1848
1852 GUI frameworks like wxPython trap exceptions and call
1849 GUI frameworks like wxPython trap exceptions and call
1853 sys.excepthook themselves. I guess this is a feature that
1850 sys.excepthook themselves. I guess this is a feature that
1854 enables them to keep running after exceptions that would
1851 enables them to keep running after exceptions that would
1855 otherwise kill their mainloop. This is a bother for IPython
1852 otherwise kill their mainloop. This is a bother for IPython
1856 which expects to catch all of the program exceptions with a try:
1853 which expects to catch all of the program exceptions with a try:
1857 except: statement.
1854 except: statement.
1858
1855
1859 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1856 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1860 any app directly invokes sys.excepthook, it will look to the user like
1857 any app directly invokes sys.excepthook, it will look to the user like
1861 IPython crashed. In order to work around this, we can disable the
1858 IPython crashed. In order to work around this, we can disable the
1862 CrashHandler and replace it with this excepthook instead, which prints a
1859 CrashHandler and replace it with this excepthook instead, which prints a
1863 regular traceback using our InteractiveTB. In this fashion, apps which
1860 regular traceback using our InteractiveTB. In this fashion, apps which
1864 call sys.excepthook will generate a regular-looking exception from
1861 call sys.excepthook will generate a regular-looking exception from
1865 IPython, and the CrashHandler will only be triggered by real IPython
1862 IPython, and the CrashHandler will only be triggered by real IPython
1866 crashes.
1863 crashes.
1867
1864
1868 This hook should be used sparingly, only in places which are not likely
1865 This hook should be used sparingly, only in places which are not likely
1869 to be true IPython errors.
1866 to be true IPython errors.
1870 """
1867 """
1871 self.showtraceback((etype, value, tb), tb_offset=0)
1868 self.showtraceback((etype, value, tb), tb_offset=0)
1872
1869
1873 def _get_exc_info(self, exc_tuple=None):
1870 def _get_exc_info(self, exc_tuple=None):
1874 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1871 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1875
1872
1876 Ensures sys.last_type,value,traceback hold the exc_info we found,
1873 Ensures sys.last_type,value,traceback hold the exc_info we found,
1877 from whichever source.
1874 from whichever source.
1878
1875
1879 raises ValueError if none of these contain any information
1876 raises ValueError if none of these contain any information
1880 """
1877 """
1881 if exc_tuple is None:
1878 if exc_tuple is None:
1882 etype, value, tb = sys.exc_info()
1879 etype, value, tb = sys.exc_info()
1883 else:
1880 else:
1884 etype, value, tb = exc_tuple
1881 etype, value, tb = exc_tuple
1885
1882
1886 if etype is None:
1883 if etype is None:
1887 if hasattr(sys, 'last_type'):
1884 if hasattr(sys, 'last_type'):
1888 etype, value, tb = sys.last_type, sys.last_value, \
1885 etype, value, tb = sys.last_type, sys.last_value, \
1889 sys.last_traceback
1886 sys.last_traceback
1890
1887
1891 if etype is None:
1888 if etype is None:
1892 raise ValueError("No exception to find")
1889 raise ValueError("No exception to find")
1893
1890
1894 # Now store the exception info in sys.last_type etc.
1891 # Now store the exception info in sys.last_type etc.
1895 # WARNING: these variables are somewhat deprecated and not
1892 # WARNING: these variables are somewhat deprecated and not
1896 # necessarily safe to use in a threaded environment, but tools
1893 # necessarily safe to use in a threaded environment, but tools
1897 # like pdb depend on their existence, so let's set them. If we
1894 # like pdb depend on their existence, so let's set them. If we
1898 # find problems in the field, we'll need to revisit their use.
1895 # find problems in the field, we'll need to revisit their use.
1899 sys.last_type = etype
1896 sys.last_type = etype
1900 sys.last_value = value
1897 sys.last_value = value
1901 sys.last_traceback = tb
1898 sys.last_traceback = tb
1902
1899
1903 return etype, value, tb
1900 return etype, value, tb
1904
1901
1905 def show_usage_error(self, exc):
1902 def show_usage_error(self, exc):
1906 """Show a short message for UsageErrors
1903 """Show a short message for UsageErrors
1907
1904
1908 These are special exceptions that shouldn't show a traceback.
1905 These are special exceptions that shouldn't show a traceback.
1909 """
1906 """
1910 print("UsageError: %s" % exc, file=sys.stderr)
1907 print("UsageError: %s" % exc, file=sys.stderr)
1911
1908
1912 def get_exception_only(self, exc_tuple=None):
1909 def get_exception_only(self, exc_tuple=None):
1913 """
1910 """
1914 Return as a string (ending with a newline) the exception that
1911 Return as a string (ending with a newline) the exception that
1915 just occurred, without any traceback.
1912 just occurred, without any traceback.
1916 """
1913 """
1917 etype, value, tb = self._get_exc_info(exc_tuple)
1914 etype, value, tb = self._get_exc_info(exc_tuple)
1918 msg = traceback.format_exception_only(etype, value)
1915 msg = traceback.format_exception_only(etype, value)
1919 return ''.join(msg)
1916 return ''.join(msg)
1920
1917
1921 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
1918 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
1922 exception_only=False, running_compiled_code=False):
1919 exception_only=False, running_compiled_code=False):
1923 """Display the exception that just occurred.
1920 """Display the exception that just occurred.
1924
1921
1925 If nothing is known about the exception, this is the method which
1922 If nothing is known about the exception, this is the method which
1926 should be used throughout the code for presenting user tracebacks,
1923 should be used throughout the code for presenting user tracebacks,
1927 rather than directly invoking the InteractiveTB object.
1924 rather than directly invoking the InteractiveTB object.
1928
1925
1929 A specific showsyntaxerror() also exists, but this method can take
1926 A specific showsyntaxerror() also exists, but this method can take
1930 care of calling it if needed, so unless you are explicitly catching a
1927 care of calling it if needed, so unless you are explicitly catching a
1931 SyntaxError exception, don't try to analyze the stack manually and
1928 SyntaxError exception, don't try to analyze the stack manually and
1932 simply call this method."""
1929 simply call this method."""
1933
1930
1934 try:
1931 try:
1935 try:
1932 try:
1936 etype, value, tb = self._get_exc_info(exc_tuple)
1933 etype, value, tb = self._get_exc_info(exc_tuple)
1937 except ValueError:
1934 except ValueError:
1938 print('No traceback available to show.', file=sys.stderr)
1935 print('No traceback available to show.', file=sys.stderr)
1939 return
1936 return
1940
1937
1941 if issubclass(etype, SyntaxError):
1938 if issubclass(etype, SyntaxError):
1942 # Though this won't be called by syntax errors in the input
1939 # Though this won't be called by syntax errors in the input
1943 # line, there may be SyntaxError cases with imported code.
1940 # line, there may be SyntaxError cases with imported code.
1944 self.showsyntaxerror(filename, running_compiled_code)
1941 self.showsyntaxerror(filename, running_compiled_code)
1945 elif etype is UsageError:
1942 elif etype is UsageError:
1946 self.show_usage_error(value)
1943 self.show_usage_error(value)
1947 else:
1944 else:
1948 if exception_only:
1945 if exception_only:
1949 stb = ['An exception has occurred, use %tb to see '
1946 stb = ['An exception has occurred, use %tb to see '
1950 'the full traceback.\n']
1947 'the full traceback.\n']
1951 stb.extend(self.InteractiveTB.get_exception_only(etype,
1948 stb.extend(self.InteractiveTB.get_exception_only(etype,
1952 value))
1949 value))
1953 else:
1950 else:
1954 try:
1951 try:
1955 # Exception classes can customise their traceback - we
1952 # Exception classes can customise their traceback - we
1956 # use this in IPython.parallel for exceptions occurring
1953 # use this in IPython.parallel for exceptions occurring
1957 # in the engines. This should return a list of strings.
1954 # in the engines. This should return a list of strings.
1958 stb = value._render_traceback_()
1955 stb = value._render_traceback_()
1959 except Exception:
1956 except Exception:
1960 stb = self.InteractiveTB.structured_traceback(etype,
1957 stb = self.InteractiveTB.structured_traceback(etype,
1961 value, tb, tb_offset=tb_offset)
1958 value, tb, tb_offset=tb_offset)
1962
1959
1963 self._showtraceback(etype, value, stb)
1960 self._showtraceback(etype, value, stb)
1964 if self.call_pdb:
1961 if self.call_pdb:
1965 # drop into debugger
1962 # drop into debugger
1966 self.debugger(force=True)
1963 self.debugger(force=True)
1967 return
1964 return
1968
1965
1969 # Actually show the traceback
1966 # Actually show the traceback
1970 self._showtraceback(etype, value, stb)
1967 self._showtraceback(etype, value, stb)
1971
1968
1972 except KeyboardInterrupt:
1969 except KeyboardInterrupt:
1973 print('\n' + self.get_exception_only(), file=sys.stderr)
1970 print('\n' + self.get_exception_only(), file=sys.stderr)
1974
1971
1975 def _showtraceback(self, etype, evalue, stb: str):
1972 def _showtraceback(self, etype, evalue, stb: str):
1976 """Actually show a traceback.
1973 """Actually show a traceback.
1977
1974
1978 Subclasses may override this method to put the traceback on a different
1975 Subclasses may override this method to put the traceback on a different
1979 place, like a side channel.
1976 place, like a side channel.
1980 """
1977 """
1981 val = self.InteractiveTB.stb2text(stb)
1978 val = self.InteractiveTB.stb2text(stb)
1982 try:
1979 try:
1983 print(val)
1980 print(val)
1984 except UnicodeEncodeError:
1981 except UnicodeEncodeError:
1985 print(val.encode("utf-8", "backslashreplace").decode())
1982 print(val.encode("utf-8", "backslashreplace").decode())
1986
1983
1987 def showsyntaxerror(self, filename=None, running_compiled_code=False):
1984 def showsyntaxerror(self, filename=None, running_compiled_code=False):
1988 """Display the syntax error that just occurred.
1985 """Display the syntax error that just occurred.
1989
1986
1990 This doesn't display a stack trace because there isn't one.
1987 This doesn't display a stack trace because there isn't one.
1991
1988
1992 If a filename is given, it is stuffed in the exception instead
1989 If a filename is given, it is stuffed in the exception instead
1993 of what was there before (because Python's parser always uses
1990 of what was there before (because Python's parser always uses
1994 "<string>" when reading from a string).
1991 "<string>" when reading from a string).
1995
1992
1996 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
1993 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
1997 longer stack trace will be displayed.
1994 longer stack trace will be displayed.
1998 """
1995 """
1999 etype, value, last_traceback = self._get_exc_info()
1996 etype, value, last_traceback = self._get_exc_info()
2000
1997
2001 if filename and issubclass(etype, SyntaxError):
1998 if filename and issubclass(etype, SyntaxError):
2002 try:
1999 try:
2003 value.filename = filename
2000 value.filename = filename
2004 except:
2001 except:
2005 # Not the format we expect; leave it alone
2002 # Not the format we expect; leave it alone
2006 pass
2003 pass
2007
2004
2008 # If the error occurred when executing compiled code, we should provide full stacktrace.
2005 # If the error occurred when executing compiled code, we should provide full stacktrace.
2009 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
2006 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
2010 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
2007 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
2011 self._showtraceback(etype, value, stb)
2008 self._showtraceback(etype, value, stb)
2012
2009
2013 # This is overridden in TerminalInteractiveShell to show a message about
2010 # This is overridden in TerminalInteractiveShell to show a message about
2014 # the %paste magic.
2011 # the %paste magic.
2015 def showindentationerror(self):
2012 def showindentationerror(self):
2016 """Called by _run_cell when there's an IndentationError in code entered
2013 """Called by _run_cell when there's an IndentationError in code entered
2017 at the prompt.
2014 at the prompt.
2018
2015
2019 This is overridden in TerminalInteractiveShell to show a message about
2016 This is overridden in TerminalInteractiveShell to show a message about
2020 the %paste magic."""
2017 the %paste magic."""
2021 self.showsyntaxerror()
2018 self.showsyntaxerror()
2022
2019
2023 @skip_doctest
2020 @skip_doctest
2024 def set_next_input(self, s, replace=False):
2021 def set_next_input(self, s, replace=False):
2025 """ Sets the 'default' input string for the next command line.
2022 """ Sets the 'default' input string for the next command line.
2026
2023
2027 Example::
2024 Example::
2028
2025
2029 In [1]: _ip.set_next_input("Hello Word")
2026 In [1]: _ip.set_next_input("Hello Word")
2030 In [2]: Hello Word_ # cursor is here
2027 In [2]: Hello Word_ # cursor is here
2031 """
2028 """
2032 self.rl_next_input = s
2029 self.rl_next_input = s
2033
2030
2034 def _indent_current_str(self):
2031 def _indent_current_str(self):
2035 """return the current level of indentation as a string"""
2032 """return the current level of indentation as a string"""
2036 return self.input_splitter.get_indent_spaces() * ' '
2033 return self.input_splitter.get_indent_spaces() * ' '
2037
2034
2038 #-------------------------------------------------------------------------
2035 #-------------------------------------------------------------------------
2039 # Things related to text completion
2036 # Things related to text completion
2040 #-------------------------------------------------------------------------
2037 #-------------------------------------------------------------------------
2041
2038
2042 def init_completer(self):
2039 def init_completer(self):
2043 """Initialize the completion machinery.
2040 """Initialize the completion machinery.
2044
2041
2045 This creates completion machinery that can be used by client code,
2042 This creates completion machinery that can be used by client code,
2046 either interactively in-process (typically triggered by the readline
2043 either interactively in-process (typically triggered by the readline
2047 library), programmatically (such as in test suites) or out-of-process
2044 library), programmatically (such as in test suites) or out-of-process
2048 (typically over the network by remote frontends).
2045 (typically over the network by remote frontends).
2049 """
2046 """
2050 from IPython.core.completer import IPCompleter
2047 from IPython.core.completer import IPCompleter
2051 from IPython.core.completerlib import (
2048 from IPython.core.completerlib import (
2052 cd_completer,
2049 cd_completer,
2053 magic_run_completer,
2050 magic_run_completer,
2054 module_completer,
2051 module_completer,
2055 reset_completer,
2052 reset_completer,
2056 )
2053 )
2057
2054
2058 self.Completer = IPCompleter(shell=self,
2055 self.Completer = IPCompleter(shell=self,
2059 namespace=self.user_ns,
2056 namespace=self.user_ns,
2060 global_namespace=self.user_global_ns,
2057 global_namespace=self.user_global_ns,
2061 parent=self,
2058 parent=self,
2062 )
2059 )
2063 self.configurables.append(self.Completer)
2060 self.configurables.append(self.Completer)
2064
2061
2065 # Add custom completers to the basic ones built into IPCompleter
2062 # Add custom completers to the basic ones built into IPCompleter
2066 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
2063 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
2067 self.strdispatchers['complete_command'] = sdisp
2064 self.strdispatchers['complete_command'] = sdisp
2068 self.Completer.custom_completers = sdisp
2065 self.Completer.custom_completers = sdisp
2069
2066
2070 self.set_hook('complete_command', module_completer, str_key = 'import')
2067 self.set_hook('complete_command', module_completer, str_key = 'import')
2071 self.set_hook('complete_command', module_completer, str_key = 'from')
2068 self.set_hook('complete_command', module_completer, str_key = 'from')
2072 self.set_hook('complete_command', module_completer, str_key = '%aimport')
2069 self.set_hook('complete_command', module_completer, str_key = '%aimport')
2073 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
2070 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
2074 self.set_hook('complete_command', cd_completer, str_key = '%cd')
2071 self.set_hook('complete_command', cd_completer, str_key = '%cd')
2075 self.set_hook('complete_command', reset_completer, str_key = '%reset')
2072 self.set_hook('complete_command', reset_completer, str_key = '%reset')
2076
2073
2077 @skip_doctest
2074 @skip_doctest
2078 def complete(self, text, line=None, cursor_pos=None):
2075 def complete(self, text, line=None, cursor_pos=None):
2079 """Return the completed text and a list of completions.
2076 """Return the completed text and a list of completions.
2080
2077
2081 Parameters
2078 Parameters
2082 ----------
2079 ----------
2083 text : string
2080 text : string
2084 A string of text to be completed on. It can be given as empty and
2081 A string of text to be completed on. It can be given as empty and
2085 instead a line/position pair are given. In this case, the
2082 instead a line/position pair are given. In this case, the
2086 completer itself will split the line like readline does.
2083 completer itself will split the line like readline does.
2087 line : string, optional
2084 line : string, optional
2088 The complete line that text is part of.
2085 The complete line that text is part of.
2089 cursor_pos : int, optional
2086 cursor_pos : int, optional
2090 The position of the cursor on the input line.
2087 The position of the cursor on the input line.
2091
2088
2092 Returns
2089 Returns
2093 -------
2090 -------
2094 text : string
2091 text : string
2095 The actual text that was completed.
2092 The actual text that was completed.
2096 matches : list
2093 matches : list
2097 A sorted list with all possible completions.
2094 A sorted list with all possible completions.
2098
2095
2099 Notes
2096 Notes
2100 -----
2097 -----
2101 The optional arguments allow the completion to take more context into
2098 The optional arguments allow the completion to take more context into
2102 account, and are part of the low-level completion API.
2099 account, and are part of the low-level completion API.
2103
2100
2104 This is a wrapper around the completion mechanism, similar to what
2101 This is a wrapper around the completion mechanism, similar to what
2105 readline does at the command line when the TAB key is hit. By
2102 readline does at the command line when the TAB key is hit. By
2106 exposing it as a method, it can be used by other non-readline
2103 exposing it as a method, it can be used by other non-readline
2107 environments (such as GUIs) for text completion.
2104 environments (such as GUIs) for text completion.
2108
2105
2109 Examples
2106 Examples
2110 --------
2107 --------
2111 In [1]: x = 'hello'
2108 In [1]: x = 'hello'
2112
2109
2113 In [2]: _ip.complete('x.l')
2110 In [2]: _ip.complete('x.l')
2114 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2111 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2115 """
2112 """
2116
2113
2117 # Inject names into __builtin__ so we can complete on the added names.
2114 # Inject names into __builtin__ so we can complete on the added names.
2118 with self.builtin_trap:
2115 with self.builtin_trap:
2119 return self.Completer.complete(text, line, cursor_pos)
2116 return self.Completer.complete(text, line, cursor_pos)
2120
2117
2121 def set_custom_completer(self, completer, pos=0) -> None:
2118 def set_custom_completer(self, completer, pos=0) -> None:
2122 """Adds a new custom completer function.
2119 """Adds a new custom completer function.
2123
2120
2124 The position argument (defaults to 0) is the index in the completers
2121 The position argument (defaults to 0) is the index in the completers
2125 list where you want the completer to be inserted.
2122 list where you want the completer to be inserted.
2126
2123
2127 `completer` should have the following signature::
2124 `completer` should have the following signature::
2128
2125
2129 def completion(self: Completer, text: string) -> List[str]:
2126 def completion(self: Completer, text: string) -> List[str]:
2130 raise NotImplementedError
2127 raise NotImplementedError
2131
2128
2132 It will be bound to the current Completer instance and pass some text
2129 It will be bound to the current Completer instance and pass some text
2133 and return a list with current completions to suggest to the user.
2130 and return a list with current completions to suggest to the user.
2134 """
2131 """
2135
2132
2136 newcomp = types.MethodType(completer, self.Completer)
2133 newcomp = types.MethodType(completer, self.Completer)
2137 self.Completer.custom_matchers.insert(pos,newcomp)
2134 self.Completer.custom_matchers.insert(pos,newcomp)
2138
2135
2139 def set_completer_frame(self, frame=None):
2136 def set_completer_frame(self, frame=None):
2140 """Set the frame of the completer."""
2137 """Set the frame of the completer."""
2141 if frame:
2138 if frame:
2142 self.Completer.namespace = frame.f_locals
2139 self.Completer.namespace = frame.f_locals
2143 self.Completer.global_namespace = frame.f_globals
2140 self.Completer.global_namespace = frame.f_globals
2144 else:
2141 else:
2145 self.Completer.namespace = self.user_ns
2142 self.Completer.namespace = self.user_ns
2146 self.Completer.global_namespace = self.user_global_ns
2143 self.Completer.global_namespace = self.user_global_ns
2147
2144
2148 #-------------------------------------------------------------------------
2145 #-------------------------------------------------------------------------
2149 # Things related to magics
2146 # Things related to magics
2150 #-------------------------------------------------------------------------
2147 #-------------------------------------------------------------------------
2151
2148
2152 def init_magics(self):
2149 def init_magics(self):
2153 from IPython.core import magics as m
2150 from IPython.core import magics as m
2154 self.magics_manager = magic.MagicsManager(shell=self,
2151 self.magics_manager = magic.MagicsManager(shell=self,
2155 parent=self,
2152 parent=self,
2156 user_magics=m.UserMagics(self))
2153 user_magics=m.UserMagics(self))
2157 self.configurables.append(self.magics_manager)
2154 self.configurables.append(self.magics_manager)
2158
2155
2159 # Expose as public API from the magics manager
2156 # Expose as public API from the magics manager
2160 self.register_magics = self.magics_manager.register
2157 self.register_magics = self.magics_manager.register
2161
2158
2162 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2159 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2163 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2160 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2164 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2161 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2165 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,
2162 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,
2166 m.PylabMagics, m.ScriptMagics,
2163 m.PylabMagics, m.ScriptMagics,
2167 )
2164 )
2168 self.register_magics(m.AsyncMagics)
2165 self.register_magics(m.AsyncMagics)
2169
2166
2170 # Register Magic Aliases
2167 # Register Magic Aliases
2171 mman = self.magics_manager
2168 mman = self.magics_manager
2172 # FIXME: magic aliases should be defined by the Magics classes
2169 # FIXME: magic aliases should be defined by the Magics classes
2173 # or in MagicsManager, not here
2170 # or in MagicsManager, not here
2174 mman.register_alias('ed', 'edit')
2171 mman.register_alias('ed', 'edit')
2175 mman.register_alias('hist', 'history')
2172 mman.register_alias('hist', 'history')
2176 mman.register_alias('rep', 'recall')
2173 mman.register_alias('rep', 'recall')
2177 mman.register_alias('SVG', 'svg', 'cell')
2174 mman.register_alias('SVG', 'svg', 'cell')
2178 mman.register_alias('HTML', 'html', 'cell')
2175 mman.register_alias('HTML', 'html', 'cell')
2179 mman.register_alias('file', 'writefile', 'cell')
2176 mman.register_alias('file', 'writefile', 'cell')
2180
2177
2181 # FIXME: Move the color initialization to the DisplayHook, which
2178 # FIXME: Move the color initialization to the DisplayHook, which
2182 # should be split into a prompt manager and displayhook. We probably
2179 # should be split into a prompt manager and displayhook. We probably
2183 # even need a centralize colors management object.
2180 # even need a centralize colors management object.
2184 self.run_line_magic('colors', self.colors)
2181 self.run_line_magic('colors', self.colors)
2185
2182
2186 # Defined here so that it's included in the documentation
2183 # Defined here so that it's included in the documentation
2187 @functools.wraps(magic.MagicsManager.register_function)
2184 @functools.wraps(magic.MagicsManager.register_function)
2188 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2185 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2189 self.magics_manager.register_function(
2186 self.magics_manager.register_function(
2190 func, magic_kind=magic_kind, magic_name=magic_name
2187 func, magic_kind=magic_kind, magic_name=magic_name
2191 )
2188 )
2192
2189
2193 def _find_with_lazy_load(self, /, type_, magic_name: str):
2190 def _find_with_lazy_load(self, /, type_, magic_name: str):
2194 """
2191 """
2195 Try to find a magic potentially lazy-loading it.
2192 Try to find a magic potentially lazy-loading it.
2196
2193
2197 Parameters
2194 Parameters
2198 ----------
2195 ----------
2199
2196
2200 type_: "line"|"cell"
2197 type_: "line"|"cell"
2201 the type of magics we are trying to find/lazy load.
2198 the type of magics we are trying to find/lazy load.
2202 magic_name: str
2199 magic_name: str
2203 The name of the magic we are trying to find/lazy load
2200 The name of the magic we are trying to find/lazy load
2204
2201
2205
2202
2206 Note that this may have any side effects
2203 Note that this may have any side effects
2207 """
2204 """
2208 finder = {"line": self.find_line_magic, "cell": self.find_cell_magic}[type_]
2205 finder = {"line": self.find_line_magic, "cell": self.find_cell_magic}[type_]
2209 fn = finder(magic_name)
2206 fn = finder(magic_name)
2210 if fn is not None:
2207 if fn is not None:
2211 return fn
2208 return fn
2212 lazy = self.magics_manager.lazy_magics.get(magic_name)
2209 lazy = self.magics_manager.lazy_magics.get(magic_name)
2213 if lazy is None:
2210 if lazy is None:
2214 return None
2211 return None
2215
2212
2216 self.run_line_magic("load_ext", lazy)
2213 self.run_line_magic("load_ext", lazy)
2217 res = finder(magic_name)
2214 res = finder(magic_name)
2218 return res
2215 return res
2219
2216
2220 def run_line_magic(self, magic_name: str, line, _stack_depth=1):
2217 def run_line_magic(self, magic_name: str, line, _stack_depth=1):
2221 """Execute the given line magic.
2218 """Execute the given line magic.
2222
2219
2223 Parameters
2220 Parameters
2224 ----------
2221 ----------
2225 magic_name : str
2222 magic_name : str
2226 Name of the desired magic function, without '%' prefix.
2223 Name of the desired magic function, without '%' prefix.
2227 line : str
2224 line : str
2228 The rest of the input line as a single string.
2225 The rest of the input line as a single string.
2229 _stack_depth : int
2226 _stack_depth : int
2230 If run_line_magic() is called from magic() then _stack_depth=2.
2227 If run_line_magic() is called from magic() then _stack_depth=2.
2231 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2228 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2232 """
2229 """
2233 fn = self._find_with_lazy_load("line", magic_name)
2230 fn = self._find_with_lazy_load("line", magic_name)
2234 if fn is None:
2231 if fn is None:
2235 lazy = self.magics_manager.lazy_magics.get(magic_name)
2232 lazy = self.magics_manager.lazy_magics.get(magic_name)
2236 if lazy:
2233 if lazy:
2237 self.run_line_magic("load_ext", lazy)
2234 self.run_line_magic("load_ext", lazy)
2238 fn = self.find_line_magic(magic_name)
2235 fn = self.find_line_magic(magic_name)
2239 if fn is None:
2236 if fn is None:
2240 cm = self.find_cell_magic(magic_name)
2237 cm = self.find_cell_magic(magic_name)
2241 etpl = "Line magic function `%%%s` not found%s."
2238 etpl = "Line magic function `%%%s` not found%s."
2242 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2239 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2243 'did you mean that instead?)' % magic_name )
2240 'did you mean that instead?)' % magic_name )
2244 raise UsageError(etpl % (magic_name, extra))
2241 raise UsageError(etpl % (magic_name, extra))
2245 else:
2242 else:
2246 # Note: this is the distance in the stack to the user's frame.
2243 # Note: this is the distance in the stack to the user's frame.
2247 # This will need to be updated if the internal calling logic gets
2244 # This will need to be updated if the internal calling logic gets
2248 # refactored, or else we'll be expanding the wrong variables.
2245 # refactored, or else we'll be expanding the wrong variables.
2249
2246
2250 # Determine stack_depth depending on where run_line_magic() has been called
2247 # Determine stack_depth depending on where run_line_magic() has been called
2251 stack_depth = _stack_depth
2248 stack_depth = _stack_depth
2252 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2249 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2253 # magic has opted out of var_expand
2250 # magic has opted out of var_expand
2254 magic_arg_s = line
2251 magic_arg_s = line
2255 else:
2252 else:
2256 magic_arg_s = self.var_expand(line, stack_depth)
2253 magic_arg_s = self.var_expand(line, stack_depth)
2257 # Put magic args in a list so we can call with f(*a) syntax
2254 # Put magic args in a list so we can call with f(*a) syntax
2258 args = [magic_arg_s]
2255 args = [magic_arg_s]
2259 kwargs = {}
2256 kwargs = {}
2260 # Grab local namespace if we need it:
2257 # Grab local namespace if we need it:
2261 if getattr(fn, "needs_local_scope", False):
2258 if getattr(fn, "needs_local_scope", False):
2262 kwargs['local_ns'] = self.get_local_scope(stack_depth)
2259 kwargs['local_ns'] = self.get_local_scope(stack_depth)
2263 with self.builtin_trap:
2260 with self.builtin_trap:
2264 result = fn(*args, **kwargs)
2261 result = fn(*args, **kwargs)
2265 return result
2262 return result
2266
2263
2267 def get_local_scope(self, stack_depth):
2264 def get_local_scope(self, stack_depth):
2268 """Get local scope at given stack depth.
2265 """Get local scope at given stack depth.
2269
2266
2270 Parameters
2267 Parameters
2271 ----------
2268 ----------
2272 stack_depth : int
2269 stack_depth : int
2273 Depth relative to calling frame
2270 Depth relative to calling frame
2274 """
2271 """
2275 return sys._getframe(stack_depth + 1).f_locals
2272 return sys._getframe(stack_depth + 1).f_locals
2276
2273
2277 def run_cell_magic(self, magic_name, line, cell):
2274 def run_cell_magic(self, magic_name, line, cell):
2278 """Execute the given cell magic.
2275 """Execute the given cell magic.
2279
2276
2280 Parameters
2277 Parameters
2281 ----------
2278 ----------
2282 magic_name : str
2279 magic_name : str
2283 Name of the desired magic function, without '%' prefix.
2280 Name of the desired magic function, without '%' prefix.
2284 line : str
2281 line : str
2285 The rest of the first input line as a single string.
2282 The rest of the first input line as a single string.
2286 cell : str
2283 cell : str
2287 The body of the cell as a (possibly multiline) string.
2284 The body of the cell as a (possibly multiline) string.
2288 """
2285 """
2289 fn = self._find_with_lazy_load("cell", magic_name)
2286 fn = self._find_with_lazy_load("cell", magic_name)
2290 if fn is None:
2287 if fn is None:
2291 lm = self.find_line_magic(magic_name)
2288 lm = self.find_line_magic(magic_name)
2292 etpl = "Cell magic `%%{0}` not found{1}."
2289 etpl = "Cell magic `%%{0}` not found{1}."
2293 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2290 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2294 'did you mean that instead?)'.format(magic_name))
2291 'did you mean that instead?)'.format(magic_name))
2295 raise UsageError(etpl.format(magic_name, extra))
2292 raise UsageError(etpl.format(magic_name, extra))
2296 elif cell == '':
2293 elif cell == '':
2297 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2294 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2298 if self.find_line_magic(magic_name) is not None:
2295 if self.find_line_magic(magic_name) is not None:
2299 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2296 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2300 raise UsageError(message)
2297 raise UsageError(message)
2301 else:
2298 else:
2302 # Note: this is the distance in the stack to the user's frame.
2299 # Note: this is the distance in the stack to the user's frame.
2303 # This will need to be updated if the internal calling logic gets
2300 # This will need to be updated if the internal calling logic gets
2304 # refactored, or else we'll be expanding the wrong variables.
2301 # refactored, or else we'll be expanding the wrong variables.
2305 stack_depth = 2
2302 stack_depth = 2
2306 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2303 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2307 # magic has opted out of var_expand
2304 # magic has opted out of var_expand
2308 magic_arg_s = line
2305 magic_arg_s = line
2309 else:
2306 else:
2310 magic_arg_s = self.var_expand(line, stack_depth)
2307 magic_arg_s = self.var_expand(line, stack_depth)
2311 kwargs = {}
2308 kwargs = {}
2312 if getattr(fn, "needs_local_scope", False):
2309 if getattr(fn, "needs_local_scope", False):
2313 kwargs['local_ns'] = self.user_ns
2310 kwargs['local_ns'] = self.user_ns
2314
2311
2315 with self.builtin_trap:
2312 with self.builtin_trap:
2316 args = (magic_arg_s, cell)
2313 args = (magic_arg_s, cell)
2317 result = fn(*args, **kwargs)
2314 result = fn(*args, **kwargs)
2318 return result
2315 return result
2319
2316
2320 def find_line_magic(self, magic_name):
2317 def find_line_magic(self, magic_name):
2321 """Find and return a line magic by name.
2318 """Find and return a line magic by name.
2322
2319
2323 Returns None if the magic isn't found."""
2320 Returns None if the magic isn't found."""
2324 return self.magics_manager.magics['line'].get(magic_name)
2321 return self.magics_manager.magics['line'].get(magic_name)
2325
2322
2326 def find_cell_magic(self, magic_name):
2323 def find_cell_magic(self, magic_name):
2327 """Find and return a cell magic by name.
2324 """Find and return a cell magic by name.
2328
2325
2329 Returns None if the magic isn't found."""
2326 Returns None if the magic isn't found."""
2330 return self.magics_manager.magics['cell'].get(magic_name)
2327 return self.magics_manager.magics['cell'].get(magic_name)
2331
2328
2332 def find_magic(self, magic_name, magic_kind='line'):
2329 def find_magic(self, magic_name, magic_kind='line'):
2333 """Find and return a magic of the given type by name.
2330 """Find and return a magic of the given type by name.
2334
2331
2335 Returns None if the magic isn't found."""
2332 Returns None if the magic isn't found."""
2336 return self.magics_manager.magics[magic_kind].get(magic_name)
2333 return self.magics_manager.magics[magic_kind].get(magic_name)
2337
2334
2338 def magic(self, arg_s):
2335 def magic(self, arg_s):
2339 """
2336 """
2340 DEPRECATED
2337 DEPRECATED
2341
2338
2342 Deprecated since IPython 0.13 (warning added in
2339 Deprecated since IPython 0.13 (warning added in
2343 8.1), use run_line_magic(magic_name, parameter_s).
2340 8.1), use run_line_magic(magic_name, parameter_s).
2344
2341
2345 Call a magic function by name.
2342 Call a magic function by name.
2346
2343
2347 Input: a string containing the name of the magic function to call and
2344 Input: a string containing the name of the magic function to call and
2348 any additional arguments to be passed to the magic.
2345 any additional arguments to be passed to the magic.
2349
2346
2350 magic('name -opt foo bar') is equivalent to typing at the ipython
2347 magic('name -opt foo bar') is equivalent to typing at the ipython
2351 prompt:
2348 prompt:
2352
2349
2353 In[1]: %name -opt foo bar
2350 In[1]: %name -opt foo bar
2354
2351
2355 To call a magic without arguments, simply use magic('name').
2352 To call a magic without arguments, simply use magic('name').
2356
2353
2357 This provides a proper Python function to call IPython's magics in any
2354 This provides a proper Python function to call IPython's magics in any
2358 valid Python code you can type at the interpreter, including loops and
2355 valid Python code you can type at the interpreter, including loops and
2359 compound statements.
2356 compound statements.
2360 """
2357 """
2361 warnings.warn(
2358 warnings.warn(
2362 "`magic(...)` is deprecated since IPython 0.13 (warning added in "
2359 "`magic(...)` is deprecated since IPython 0.13 (warning added in "
2363 "8.1), use run_line_magic(magic_name, parameter_s).",
2360 "8.1), use run_line_magic(magic_name, parameter_s).",
2364 DeprecationWarning,
2361 DeprecationWarning,
2365 stacklevel=2,
2362 stacklevel=2,
2366 )
2363 )
2367 # TODO: should we issue a loud deprecation warning here?
2364 # TODO: should we issue a loud deprecation warning here?
2368 magic_name, _, magic_arg_s = arg_s.partition(' ')
2365 magic_name, _, magic_arg_s = arg_s.partition(' ')
2369 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2366 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2370 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2367 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2371
2368
2372 #-------------------------------------------------------------------------
2369 #-------------------------------------------------------------------------
2373 # Things related to macros
2370 # Things related to macros
2374 #-------------------------------------------------------------------------
2371 #-------------------------------------------------------------------------
2375
2372
2376 def define_macro(self, name, themacro):
2373 def define_macro(self, name, themacro):
2377 """Define a new macro
2374 """Define a new macro
2378
2375
2379 Parameters
2376 Parameters
2380 ----------
2377 ----------
2381 name : str
2378 name : str
2382 The name of the macro.
2379 The name of the macro.
2383 themacro : str or Macro
2380 themacro : str or Macro
2384 The action to do upon invoking the macro. If a string, a new
2381 The action to do upon invoking the macro. If a string, a new
2385 Macro object is created by passing the string to it.
2382 Macro object is created by passing the string to it.
2386 """
2383 """
2387
2384
2388 from IPython.core import macro
2385 from IPython.core import macro
2389
2386
2390 if isinstance(themacro, str):
2387 if isinstance(themacro, str):
2391 themacro = macro.Macro(themacro)
2388 themacro = macro.Macro(themacro)
2392 if not isinstance(themacro, macro.Macro):
2389 if not isinstance(themacro, macro.Macro):
2393 raise ValueError('A macro must be a string or a Macro instance.')
2390 raise ValueError('A macro must be a string or a Macro instance.')
2394 self.user_ns[name] = themacro
2391 self.user_ns[name] = themacro
2395
2392
2396 #-------------------------------------------------------------------------
2393 #-------------------------------------------------------------------------
2397 # Things related to the running of system commands
2394 # Things related to the running of system commands
2398 #-------------------------------------------------------------------------
2395 #-------------------------------------------------------------------------
2399
2396
2400 def system_piped(self, cmd):
2397 def system_piped(self, cmd):
2401 """Call the given cmd in a subprocess, piping stdout/err
2398 """Call the given cmd in a subprocess, piping stdout/err
2402
2399
2403 Parameters
2400 Parameters
2404 ----------
2401 ----------
2405 cmd : str
2402 cmd : str
2406 Command to execute (can not end in '&', as background processes are
2403 Command to execute (can not end in '&', as background processes are
2407 not supported. Should not be a command that expects input
2404 not supported. Should not be a command that expects input
2408 other than simple text.
2405 other than simple text.
2409 """
2406 """
2410 if cmd.rstrip().endswith('&'):
2407 if cmd.rstrip().endswith('&'):
2411 # this is *far* from a rigorous test
2408 # this is *far* from a rigorous test
2412 # We do not support backgrounding processes because we either use
2409 # We do not support backgrounding processes because we either use
2413 # pexpect or pipes to read from. Users can always just call
2410 # pexpect or pipes to read from. Users can always just call
2414 # os.system() or use ip.system=ip.system_raw
2411 # os.system() or use ip.system=ip.system_raw
2415 # if they really want a background process.
2412 # if they really want a background process.
2416 raise OSError("Background processes not supported.")
2413 raise OSError("Background processes not supported.")
2417
2414
2418 # we explicitly do NOT return the subprocess status code, because
2415 # we explicitly do NOT return the subprocess status code, because
2419 # a non-None value would trigger :func:`sys.displayhook` calls.
2416 # a non-None value would trigger :func:`sys.displayhook` calls.
2420 # Instead, we store the exit_code in user_ns.
2417 # Instead, we store the exit_code in user_ns.
2421 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2418 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2422
2419
2423 def system_raw(self, cmd):
2420 def system_raw(self, cmd):
2424 """Call the given cmd in a subprocess using os.system on Windows or
2421 """Call the given cmd in a subprocess using os.system on Windows or
2425 subprocess.call using the system shell on other platforms.
2422 subprocess.call using the system shell on other platforms.
2426
2423
2427 Parameters
2424 Parameters
2428 ----------
2425 ----------
2429 cmd : str
2426 cmd : str
2430 Command to execute.
2427 Command to execute.
2431 """
2428 """
2432 cmd = self.var_expand(cmd, depth=1)
2429 cmd = self.var_expand(cmd, depth=1)
2433 # warn if there is an IPython magic alternative.
2430 # warn if there is an IPython magic alternative.
2434 main_cmd = cmd.split()[0]
2431 main_cmd = cmd.split()[0]
2435 has_magic_alternatives = ("pip", "conda", "cd")
2432 has_magic_alternatives = ("pip", "conda", "cd")
2436
2433
2437 if main_cmd in has_magic_alternatives:
2434 if main_cmd in has_magic_alternatives:
2438 warnings.warn(
2435 warnings.warn(
2439 (
2436 (
2440 "You executed the system command !{0} which may not work "
2437 "You executed the system command !{0} which may not work "
2441 "as expected. Try the IPython magic %{0} instead."
2438 "as expected. Try the IPython magic %{0} instead."
2442 ).format(main_cmd)
2439 ).format(main_cmd)
2443 )
2440 )
2444
2441
2445 # protect os.system from UNC paths on Windows, which it can't handle:
2442 # protect os.system from UNC paths on Windows, which it can't handle:
2446 if sys.platform == 'win32':
2443 if sys.platform == 'win32':
2447 from IPython.utils._process_win32 import AvoidUNCPath
2444 from IPython.utils._process_win32 import AvoidUNCPath
2448 with AvoidUNCPath() as path:
2445 with AvoidUNCPath() as path:
2449 if path is not None:
2446 if path is not None:
2450 cmd = '"pushd %s &&"%s' % (path, cmd)
2447 cmd = '"pushd %s &&"%s' % (path, cmd)
2451 try:
2448 try:
2452 ec = os.system(cmd)
2449 ec = os.system(cmd)
2453 except KeyboardInterrupt:
2450 except KeyboardInterrupt:
2454 print('\n' + self.get_exception_only(), file=sys.stderr)
2451 print('\n' + self.get_exception_only(), file=sys.stderr)
2455 ec = -2
2452 ec = -2
2456 else:
2453 else:
2457 # For posix the result of the subprocess.call() below is an exit
2454 # For posix the result of the subprocess.call() below is an exit
2458 # code, which by convention is zero for success, positive for
2455 # code, which by convention is zero for success, positive for
2459 # program failure. Exit codes above 128 are reserved for signals,
2456 # program failure. Exit codes above 128 are reserved for signals,
2460 # and the formula for converting a signal to an exit code is usually
2457 # and the formula for converting a signal to an exit code is usually
2461 # signal_number+128. To more easily differentiate between exit
2458 # signal_number+128. To more easily differentiate between exit
2462 # codes and signals, ipython uses negative numbers. For instance
2459 # codes and signals, ipython uses negative numbers. For instance
2463 # since control-c is signal 2 but exit code 130, ipython's
2460 # since control-c is signal 2 but exit code 130, ipython's
2464 # _exit_code variable will read -2. Note that some shells like
2461 # _exit_code variable will read -2. Note that some shells like
2465 # csh and fish don't follow sh/bash conventions for exit codes.
2462 # csh and fish don't follow sh/bash conventions for exit codes.
2466 executable = os.environ.get('SHELL', None)
2463 executable = os.environ.get('SHELL', None)
2467 try:
2464 try:
2468 # Use env shell instead of default /bin/sh
2465 # Use env shell instead of default /bin/sh
2469 ec = subprocess.call(cmd, shell=True, executable=executable)
2466 ec = subprocess.call(cmd, shell=True, executable=executable)
2470 except KeyboardInterrupt:
2467 except KeyboardInterrupt:
2471 # intercept control-C; a long traceback is not useful here
2468 # intercept control-C; a long traceback is not useful here
2472 print('\n' + self.get_exception_only(), file=sys.stderr)
2469 print('\n' + self.get_exception_only(), file=sys.stderr)
2473 ec = 130
2470 ec = 130
2474 if ec > 128:
2471 if ec > 128:
2475 ec = -(ec - 128)
2472 ec = -(ec - 128)
2476
2473
2477 # We explicitly do NOT return the subprocess status code, because
2474 # We explicitly do NOT return the subprocess status code, because
2478 # a non-None value would trigger :func:`sys.displayhook` calls.
2475 # a non-None value would trigger :func:`sys.displayhook` calls.
2479 # Instead, we store the exit_code in user_ns. Note the semantics
2476 # Instead, we store the exit_code in user_ns. Note the semantics
2480 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2477 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2481 # but raising SystemExit(_exit_code) will give status 254!
2478 # but raising SystemExit(_exit_code) will give status 254!
2482 self.user_ns['_exit_code'] = ec
2479 self.user_ns['_exit_code'] = ec
2483
2480
2484 # use piped system by default, because it is better behaved
2481 # use piped system by default, because it is better behaved
2485 system = system_piped
2482 system = system_piped
2486
2483
2487 def getoutput(self, cmd, split=True, depth=0):
2484 def getoutput(self, cmd, split=True, depth=0):
2488 """Get output (possibly including stderr) from a subprocess.
2485 """Get output (possibly including stderr) from a subprocess.
2489
2486
2490 Parameters
2487 Parameters
2491 ----------
2488 ----------
2492 cmd : str
2489 cmd : str
2493 Command to execute (can not end in '&', as background processes are
2490 Command to execute (can not end in '&', as background processes are
2494 not supported.
2491 not supported.
2495 split : bool, optional
2492 split : bool, optional
2496 If True, split the output into an IPython SList. Otherwise, an
2493 If True, split the output into an IPython SList. Otherwise, an
2497 IPython LSString is returned. These are objects similar to normal
2494 IPython LSString is returned. These are objects similar to normal
2498 lists and strings, with a few convenience attributes for easier
2495 lists and strings, with a few convenience attributes for easier
2499 manipulation of line-based output. You can use '?' on them for
2496 manipulation of line-based output. You can use '?' on them for
2500 details.
2497 details.
2501 depth : int, optional
2498 depth : int, optional
2502 How many frames above the caller are the local variables which should
2499 How many frames above the caller are the local variables which should
2503 be expanded in the command string? The default (0) assumes that the
2500 be expanded in the command string? The default (0) assumes that the
2504 expansion variables are in the stack frame calling this function.
2501 expansion variables are in the stack frame calling this function.
2505 """
2502 """
2506 if cmd.rstrip().endswith('&'):
2503 if cmd.rstrip().endswith('&'):
2507 # this is *far* from a rigorous test
2504 # this is *far* from a rigorous test
2508 raise OSError("Background processes not supported.")
2505 raise OSError("Background processes not supported.")
2509 out = getoutput(self.var_expand(cmd, depth=depth+1))
2506 out = getoutput(self.var_expand(cmd, depth=depth+1))
2510 if split:
2507 if split:
2511 out = SList(out.splitlines())
2508 out = SList(out.splitlines())
2512 else:
2509 else:
2513 out = LSString(out)
2510 out = LSString(out)
2514 return out
2511 return out
2515
2512
2516 #-------------------------------------------------------------------------
2513 #-------------------------------------------------------------------------
2517 # Things related to aliases
2514 # Things related to aliases
2518 #-------------------------------------------------------------------------
2515 #-------------------------------------------------------------------------
2519
2516
2520 def init_alias(self):
2517 def init_alias(self):
2521 self.alias_manager = AliasManager(shell=self, parent=self)
2518 self.alias_manager = AliasManager(shell=self, parent=self)
2522 self.configurables.append(self.alias_manager)
2519 self.configurables.append(self.alias_manager)
2523
2520
2524 #-------------------------------------------------------------------------
2521 #-------------------------------------------------------------------------
2525 # Things related to extensions
2522 # Things related to extensions
2526 #-------------------------------------------------------------------------
2523 #-------------------------------------------------------------------------
2527
2524
2528 def init_extension_manager(self):
2525 def init_extension_manager(self):
2529 self.extension_manager = ExtensionManager(shell=self, parent=self)
2526 self.extension_manager = ExtensionManager(shell=self, parent=self)
2530 self.configurables.append(self.extension_manager)
2527 self.configurables.append(self.extension_manager)
2531
2528
2532 #-------------------------------------------------------------------------
2529 #-------------------------------------------------------------------------
2533 # Things related to payloads
2530 # Things related to payloads
2534 #-------------------------------------------------------------------------
2531 #-------------------------------------------------------------------------
2535
2532
2536 def init_payload(self):
2533 def init_payload(self):
2537 self.payload_manager = PayloadManager(parent=self)
2534 self.payload_manager = PayloadManager(parent=self)
2538 self.configurables.append(self.payload_manager)
2535 self.configurables.append(self.payload_manager)
2539
2536
2540 #-------------------------------------------------------------------------
2537 #-------------------------------------------------------------------------
2541 # Things related to the prefilter
2538 # Things related to the prefilter
2542 #-------------------------------------------------------------------------
2539 #-------------------------------------------------------------------------
2543
2540
2544 def init_prefilter(self):
2541 def init_prefilter(self):
2545 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2542 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2546 self.configurables.append(self.prefilter_manager)
2543 self.configurables.append(self.prefilter_manager)
2547 # Ultimately this will be refactored in the new interpreter code, but
2544 # Ultimately this will be refactored in the new interpreter code, but
2548 # for now, we should expose the main prefilter method (there's legacy
2545 # for now, we should expose the main prefilter method (there's legacy
2549 # code out there that may rely on this).
2546 # code out there that may rely on this).
2550 self.prefilter = self.prefilter_manager.prefilter_lines
2547 self.prefilter = self.prefilter_manager.prefilter_lines
2551
2548
2552 def auto_rewrite_input(self, cmd):
2549 def auto_rewrite_input(self, cmd):
2553 """Print to the screen the rewritten form of the user's command.
2550 """Print to the screen the rewritten form of the user's command.
2554
2551
2555 This shows visual feedback by rewriting input lines that cause
2552 This shows visual feedback by rewriting input lines that cause
2556 automatic calling to kick in, like::
2553 automatic calling to kick in, like::
2557
2554
2558 /f x
2555 /f x
2559
2556
2560 into::
2557 into::
2561
2558
2562 ------> f(x)
2559 ------> f(x)
2563
2560
2564 after the user's input prompt. This helps the user understand that the
2561 after the user's input prompt. This helps the user understand that the
2565 input line was transformed automatically by IPython.
2562 input line was transformed automatically by IPython.
2566 """
2563 """
2567 if not self.show_rewritten_input:
2564 if not self.show_rewritten_input:
2568 return
2565 return
2569
2566
2570 # This is overridden in TerminalInteractiveShell to use fancy prompts
2567 # This is overridden in TerminalInteractiveShell to use fancy prompts
2571 print("------> " + cmd)
2568 print("------> " + cmd)
2572
2569
2573 #-------------------------------------------------------------------------
2570 #-------------------------------------------------------------------------
2574 # Things related to extracting values/expressions from kernel and user_ns
2571 # Things related to extracting values/expressions from kernel and user_ns
2575 #-------------------------------------------------------------------------
2572 #-------------------------------------------------------------------------
2576
2573
2577 def _user_obj_error(self):
2574 def _user_obj_error(self):
2578 """return simple exception dict
2575 """return simple exception dict
2579
2576
2580 for use in user_expressions
2577 for use in user_expressions
2581 """
2578 """
2582
2579
2583 etype, evalue, tb = self._get_exc_info()
2580 etype, evalue, tb = self._get_exc_info()
2584 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2581 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2585
2582
2586 exc_info = {
2583 exc_info = {
2587 "status": "error",
2584 "status": "error",
2588 "traceback": stb,
2585 "traceback": stb,
2589 "ename": etype.__name__,
2586 "ename": etype.__name__,
2590 "evalue": py3compat.safe_unicode(evalue),
2587 "evalue": py3compat.safe_unicode(evalue),
2591 }
2588 }
2592
2589
2593 return exc_info
2590 return exc_info
2594
2591
2595 def _format_user_obj(self, obj):
2592 def _format_user_obj(self, obj):
2596 """format a user object to display dict
2593 """format a user object to display dict
2597
2594
2598 for use in user_expressions
2595 for use in user_expressions
2599 """
2596 """
2600
2597
2601 data, md = self.display_formatter.format(obj)
2598 data, md = self.display_formatter.format(obj)
2602 value = {
2599 value = {
2603 'status' : 'ok',
2600 'status' : 'ok',
2604 'data' : data,
2601 'data' : data,
2605 'metadata' : md,
2602 'metadata' : md,
2606 }
2603 }
2607 return value
2604 return value
2608
2605
2609 def user_expressions(self, expressions):
2606 def user_expressions(self, expressions):
2610 """Evaluate a dict of expressions in the user's namespace.
2607 """Evaluate a dict of expressions in the user's namespace.
2611
2608
2612 Parameters
2609 Parameters
2613 ----------
2610 ----------
2614 expressions : dict
2611 expressions : dict
2615 A dict with string keys and string values. The expression values
2612 A dict with string keys and string values. The expression values
2616 should be valid Python expressions, each of which will be evaluated
2613 should be valid Python expressions, each of which will be evaluated
2617 in the user namespace.
2614 in the user namespace.
2618
2615
2619 Returns
2616 Returns
2620 -------
2617 -------
2621 A dict, keyed like the input expressions dict, with the rich mime-typed
2618 A dict, keyed like the input expressions dict, with the rich mime-typed
2622 display_data of each value.
2619 display_data of each value.
2623 """
2620 """
2624 out = {}
2621 out = {}
2625 user_ns = self.user_ns
2622 user_ns = self.user_ns
2626 global_ns = self.user_global_ns
2623 global_ns = self.user_global_ns
2627
2624
2628 for key, expr in expressions.items():
2625 for key, expr in expressions.items():
2629 try:
2626 try:
2630 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2627 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2631 except:
2628 except:
2632 value = self._user_obj_error()
2629 value = self._user_obj_error()
2633 out[key] = value
2630 out[key] = value
2634 return out
2631 return out
2635
2632
2636 #-------------------------------------------------------------------------
2633 #-------------------------------------------------------------------------
2637 # Things related to the running of code
2634 # Things related to the running of code
2638 #-------------------------------------------------------------------------
2635 #-------------------------------------------------------------------------
2639
2636
2640 def ex(self, cmd):
2637 def ex(self, cmd):
2641 """Execute a normal python statement in user namespace."""
2638 """Execute a normal python statement in user namespace."""
2642 with self.builtin_trap:
2639 with self.builtin_trap:
2643 exec(cmd, self.user_global_ns, self.user_ns)
2640 exec(cmd, self.user_global_ns, self.user_ns)
2644
2641
2645 def ev(self, expr):
2642 def ev(self, expr):
2646 """Evaluate python expression expr in user namespace.
2643 """Evaluate python expression expr in user namespace.
2647
2644
2648 Returns the result of evaluation
2645 Returns the result of evaluation
2649 """
2646 """
2650 with self.builtin_trap:
2647 with self.builtin_trap:
2651 return eval(expr, self.user_global_ns, self.user_ns)
2648 return eval(expr, self.user_global_ns, self.user_ns)
2652
2649
2653 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2650 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2654 """A safe version of the builtin execfile().
2651 """A safe version of the builtin execfile().
2655
2652
2656 This version will never throw an exception, but instead print
2653 This version will never throw an exception, but instead print
2657 helpful error messages to the screen. This only works on pure
2654 helpful error messages to the screen. This only works on pure
2658 Python files with the .py extension.
2655 Python files with the .py extension.
2659
2656
2660 Parameters
2657 Parameters
2661 ----------
2658 ----------
2662 fname : string
2659 fname : string
2663 The name of the file to be executed.
2660 The name of the file to be executed.
2664 *where : tuple
2661 *where : tuple
2665 One or two namespaces, passed to execfile() as (globals,locals).
2662 One or two namespaces, passed to execfile() as (globals,locals).
2666 If only one is given, it is passed as both.
2663 If only one is given, it is passed as both.
2667 exit_ignore : bool (False)
2664 exit_ignore : bool (False)
2668 If True, then silence SystemExit for non-zero status (it is always
2665 If True, then silence SystemExit for non-zero status (it is always
2669 silenced for zero status, as it is so common).
2666 silenced for zero status, as it is so common).
2670 raise_exceptions : bool (False)
2667 raise_exceptions : bool (False)
2671 If True raise exceptions everywhere. Meant for testing.
2668 If True raise exceptions everywhere. Meant for testing.
2672 shell_futures : bool (False)
2669 shell_futures : bool (False)
2673 If True, the code will share future statements with the interactive
2670 If True, the code will share future statements with the interactive
2674 shell. It will both be affected by previous __future__ imports, and
2671 shell. It will both be affected by previous __future__ imports, and
2675 any __future__ imports in the code will affect the shell. If False,
2672 any __future__ imports in the code will affect the shell. If False,
2676 __future__ imports are not shared in either direction.
2673 __future__ imports are not shared in either direction.
2677
2674
2678 """
2675 """
2679 fname = Path(fname).expanduser().resolve()
2676 fname = Path(fname).expanduser().resolve()
2680
2677
2681 # Make sure we can open the file
2678 # Make sure we can open the file
2682 try:
2679 try:
2683 with fname.open("rb"):
2680 with fname.open("rb"):
2684 pass
2681 pass
2685 except:
2682 except:
2686 warn('Could not open file <%s> for safe execution.' % fname)
2683 warn('Could not open file <%s> for safe execution.' % fname)
2687 return
2684 return
2688
2685
2689 # Find things also in current directory. This is needed to mimic the
2686 # Find things also in current directory. This is needed to mimic the
2690 # behavior of running a script from the system command line, where
2687 # behavior of running a script from the system command line, where
2691 # Python inserts the script's directory into sys.path
2688 # Python inserts the script's directory into sys.path
2692 dname = str(fname.parent)
2689 dname = str(fname.parent)
2693
2690
2694 with prepended_to_syspath(dname), self.builtin_trap:
2691 with prepended_to_syspath(dname), self.builtin_trap:
2695 try:
2692 try:
2696 glob, loc = (where + (None, ))[:2]
2693 glob, loc = (where + (None, ))[:2]
2697 py3compat.execfile(
2694 py3compat.execfile(
2698 fname, glob, loc,
2695 fname, glob, loc,
2699 self.compile if shell_futures else None)
2696 self.compile if shell_futures else None)
2700 except SystemExit as status:
2697 except SystemExit as status:
2701 # If the call was made with 0 or None exit status (sys.exit(0)
2698 # If the call was made with 0 or None exit status (sys.exit(0)
2702 # or sys.exit() ), don't bother showing a traceback, as both of
2699 # or sys.exit() ), don't bother showing a traceback, as both of
2703 # these are considered normal by the OS:
2700 # these are considered normal by the OS:
2704 # > python -c'import sys;sys.exit(0)'; echo $?
2701 # > python -c'import sys;sys.exit(0)'; echo $?
2705 # 0
2702 # 0
2706 # > python -c'import sys;sys.exit()'; echo $?
2703 # > python -c'import sys;sys.exit()'; echo $?
2707 # 0
2704 # 0
2708 # For other exit status, we show the exception unless
2705 # For other exit status, we show the exception unless
2709 # explicitly silenced, but only in short form.
2706 # explicitly silenced, but only in short form.
2710 if status.code:
2707 if status.code:
2711 if raise_exceptions:
2708 if raise_exceptions:
2712 raise
2709 raise
2713 if not exit_ignore:
2710 if not exit_ignore:
2714 self.showtraceback(exception_only=True)
2711 self.showtraceback(exception_only=True)
2715 except:
2712 except:
2716 if raise_exceptions:
2713 if raise_exceptions:
2717 raise
2714 raise
2718 # tb offset is 2 because we wrap execfile
2715 # tb offset is 2 because we wrap execfile
2719 self.showtraceback(tb_offset=2)
2716 self.showtraceback(tb_offset=2)
2720
2717
2721 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2718 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2722 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2719 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2723
2720
2724 Parameters
2721 Parameters
2725 ----------
2722 ----------
2726 fname : str
2723 fname : str
2727 The name of the file to execute. The filename must have a
2724 The name of the file to execute. The filename must have a
2728 .ipy or .ipynb extension.
2725 .ipy or .ipynb extension.
2729 shell_futures : bool (False)
2726 shell_futures : bool (False)
2730 If True, the code will share future statements with the interactive
2727 If True, the code will share future statements with the interactive
2731 shell. It will both be affected by previous __future__ imports, and
2728 shell. It will both be affected by previous __future__ imports, and
2732 any __future__ imports in the code will affect the shell. If False,
2729 any __future__ imports in the code will affect the shell. If False,
2733 __future__ imports are not shared in either direction.
2730 __future__ imports are not shared in either direction.
2734 raise_exceptions : bool (False)
2731 raise_exceptions : bool (False)
2735 If True raise exceptions everywhere. Meant for testing.
2732 If True raise exceptions everywhere. Meant for testing.
2736 """
2733 """
2737 fname = Path(fname).expanduser().resolve()
2734 fname = Path(fname).expanduser().resolve()
2738
2735
2739 # Make sure we can open the file
2736 # Make sure we can open the file
2740 try:
2737 try:
2741 with fname.open("rb"):
2738 with fname.open("rb"):
2742 pass
2739 pass
2743 except:
2740 except:
2744 warn('Could not open file <%s> for safe execution.' % fname)
2741 warn('Could not open file <%s> for safe execution.' % fname)
2745 return
2742 return
2746
2743
2747 # Find things also in current directory. This is needed to mimic the
2744 # Find things also in current directory. This is needed to mimic the
2748 # behavior of running a script from the system command line, where
2745 # behavior of running a script from the system command line, where
2749 # Python inserts the script's directory into sys.path
2746 # Python inserts the script's directory into sys.path
2750 dname = str(fname.parent)
2747 dname = str(fname.parent)
2751
2748
2752 def get_cells():
2749 def get_cells():
2753 """generator for sequence of code blocks to run"""
2750 """generator for sequence of code blocks to run"""
2754 if fname.suffix == ".ipynb":
2751 if fname.suffix == ".ipynb":
2755 from nbformat import read
2752 from nbformat import read
2756 nb = read(fname, as_version=4)
2753 nb = read(fname, as_version=4)
2757 if not nb.cells:
2754 if not nb.cells:
2758 return
2755 return
2759 for cell in nb.cells:
2756 for cell in nb.cells:
2760 if cell.cell_type == 'code':
2757 if cell.cell_type == 'code':
2761 yield cell.source
2758 yield cell.source
2762 else:
2759 else:
2763 yield fname.read_text(encoding="utf-8")
2760 yield fname.read_text(encoding="utf-8")
2764
2761
2765 with prepended_to_syspath(dname):
2762 with prepended_to_syspath(dname):
2766 try:
2763 try:
2767 for cell in get_cells():
2764 for cell in get_cells():
2768 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2765 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2769 if raise_exceptions:
2766 if raise_exceptions:
2770 result.raise_error()
2767 result.raise_error()
2771 elif not result.success:
2768 elif not result.success:
2772 break
2769 break
2773 except:
2770 except:
2774 if raise_exceptions:
2771 if raise_exceptions:
2775 raise
2772 raise
2776 self.showtraceback()
2773 self.showtraceback()
2777 warn('Unknown failure executing file: <%s>' % fname)
2774 warn('Unknown failure executing file: <%s>' % fname)
2778
2775
2779 def safe_run_module(self, mod_name, where):
2776 def safe_run_module(self, mod_name, where):
2780 """A safe version of runpy.run_module().
2777 """A safe version of runpy.run_module().
2781
2778
2782 This version will never throw an exception, but instead print
2779 This version will never throw an exception, but instead print
2783 helpful error messages to the screen.
2780 helpful error messages to the screen.
2784
2781
2785 `SystemExit` exceptions with status code 0 or None are ignored.
2782 `SystemExit` exceptions with status code 0 or None are ignored.
2786
2783
2787 Parameters
2784 Parameters
2788 ----------
2785 ----------
2789 mod_name : string
2786 mod_name : string
2790 The name of the module to be executed.
2787 The name of the module to be executed.
2791 where : dict
2788 where : dict
2792 The globals namespace.
2789 The globals namespace.
2793 """
2790 """
2794 try:
2791 try:
2795 try:
2792 try:
2796 where.update(
2793 where.update(
2797 runpy.run_module(str(mod_name), run_name="__main__",
2794 runpy.run_module(str(mod_name), run_name="__main__",
2798 alter_sys=True)
2795 alter_sys=True)
2799 )
2796 )
2800 except SystemExit as status:
2797 except SystemExit as status:
2801 if status.code:
2798 if status.code:
2802 raise
2799 raise
2803 except:
2800 except:
2804 self.showtraceback()
2801 self.showtraceback()
2805 warn('Unknown failure executing module: <%s>' % mod_name)
2802 warn('Unknown failure executing module: <%s>' % mod_name)
2806
2803
2807 def run_cell(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2804 def run_cell(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2808 """Run a complete IPython cell.
2805 """Run a complete IPython cell.
2809
2806
2810 Parameters
2807 Parameters
2811 ----------
2808 ----------
2812 raw_cell : str
2809 raw_cell : str
2813 The code (including IPython code such as %magic functions) to run.
2810 The code (including IPython code such as %magic functions) to run.
2814 store_history : bool
2811 store_history : bool
2815 If True, the raw and translated cell will be stored in IPython's
2812 If True, the raw and translated cell will be stored in IPython's
2816 history. For user code calling back into IPython's machinery, this
2813 history. For user code calling back into IPython's machinery, this
2817 should be set to False.
2814 should be set to False.
2818 silent : bool
2815 silent : bool
2819 If True, avoid side-effects, such as implicit displayhooks and
2816 If True, avoid side-effects, such as implicit displayhooks and
2820 and logging. silent=True forces store_history=False.
2817 and logging. silent=True forces store_history=False.
2821 shell_futures : bool
2818 shell_futures : bool
2822 If True, the code will share future statements with the interactive
2819 If True, the code will share future statements with the interactive
2823 shell. It will both be affected by previous __future__ imports, and
2820 shell. It will both be affected by previous __future__ imports, and
2824 any __future__ imports in the code will affect the shell. If False,
2821 any __future__ imports in the code will affect the shell. If False,
2825 __future__ imports are not shared in either direction.
2822 __future__ imports are not shared in either direction.
2826
2823
2827 Returns
2824 Returns
2828 -------
2825 -------
2829 result : :class:`ExecutionResult`
2826 result : :class:`ExecutionResult`
2830 """
2827 """
2831 result = None
2828 result = None
2832 try:
2829 try:
2833 result = self._run_cell(
2830 result = self._run_cell(
2834 raw_cell, store_history, silent, shell_futures)
2831 raw_cell, store_history, silent, shell_futures)
2835 finally:
2832 finally:
2836 self.events.trigger('post_execute')
2833 self.events.trigger('post_execute')
2837 if not silent:
2834 if not silent:
2838 self.events.trigger('post_run_cell', result)
2835 self.events.trigger('post_run_cell', result)
2839 return result
2836 return result
2840
2837
2841 def _run_cell(self, raw_cell:str, store_history:bool, silent:bool, shell_futures:bool) -> ExecutionResult:
2838 def _run_cell(self, raw_cell:str, store_history:bool, silent:bool, shell_futures:bool) -> ExecutionResult:
2842 """Internal method to run a complete IPython cell."""
2839 """Internal method to run a complete IPython cell."""
2843
2840
2844 # we need to avoid calling self.transform_cell multiple time on the same thing
2841 # we need to avoid calling self.transform_cell multiple time on the same thing
2845 # so we need to store some results:
2842 # so we need to store some results:
2846 preprocessing_exc_tuple = None
2843 preprocessing_exc_tuple = None
2847 try:
2844 try:
2848 transformed_cell = self.transform_cell(raw_cell)
2845 transformed_cell = self.transform_cell(raw_cell)
2849 except Exception:
2846 except Exception:
2850 transformed_cell = raw_cell
2847 transformed_cell = raw_cell
2851 preprocessing_exc_tuple = sys.exc_info()
2848 preprocessing_exc_tuple = sys.exc_info()
2852
2849
2853 assert transformed_cell is not None
2850 assert transformed_cell is not None
2854 coro = self.run_cell_async(
2851 coro = self.run_cell_async(
2855 raw_cell,
2852 raw_cell,
2856 store_history=store_history,
2853 store_history=store_history,
2857 silent=silent,
2854 silent=silent,
2858 shell_futures=shell_futures,
2855 shell_futures=shell_futures,
2859 transformed_cell=transformed_cell,
2856 transformed_cell=transformed_cell,
2860 preprocessing_exc_tuple=preprocessing_exc_tuple,
2857 preprocessing_exc_tuple=preprocessing_exc_tuple,
2861 )
2858 )
2862
2859
2863 # run_cell_async is async, but may not actually need an eventloop.
2860 # run_cell_async is async, but may not actually need an eventloop.
2864 # when this is the case, we want to run it using the pseudo_sync_runner
2861 # when this is the case, we want to run it using the pseudo_sync_runner
2865 # so that code can invoke eventloops (for example via the %run , and
2862 # so that code can invoke eventloops (for example via the %run , and
2866 # `%paste` magic.
2863 # `%paste` magic.
2867 if self.trio_runner:
2864 if self.trio_runner:
2868 runner = self.trio_runner
2865 runner = self.trio_runner
2869 elif self.should_run_async(
2866 elif self.should_run_async(
2870 raw_cell,
2867 raw_cell,
2871 transformed_cell=transformed_cell,
2868 transformed_cell=transformed_cell,
2872 preprocessing_exc_tuple=preprocessing_exc_tuple,
2869 preprocessing_exc_tuple=preprocessing_exc_tuple,
2873 ):
2870 ):
2874 runner = self.loop_runner
2871 runner = self.loop_runner
2875 else:
2872 else:
2876 runner = _pseudo_sync_runner
2873 runner = _pseudo_sync_runner
2877
2874
2878 try:
2875 try:
2879 return runner(coro)
2876 return runner(coro)
2880 except BaseException as e:
2877 except BaseException as e:
2881 info = ExecutionInfo(raw_cell, store_history, silent, shell_futures)
2878 info = ExecutionInfo(raw_cell, store_history, silent, shell_futures)
2882 result = ExecutionResult(info)
2879 result = ExecutionResult(info)
2883 result.error_in_exec = e
2880 result.error_in_exec = e
2884 self.showtraceback(running_compiled_code=True)
2881 self.showtraceback(running_compiled_code=True)
2885 return result
2882 return result
2886
2883
2887 def should_run_async(
2884 def should_run_async(
2888 self, raw_cell: str, *, transformed_cell=None, preprocessing_exc_tuple=None
2885 self, raw_cell: str, *, transformed_cell=None, preprocessing_exc_tuple=None
2889 ) -> bool:
2886 ) -> bool:
2890 """Return whether a cell should be run asynchronously via a coroutine runner
2887 """Return whether a cell should be run asynchronously via a coroutine runner
2891
2888
2892 Parameters
2889 Parameters
2893 ----------
2890 ----------
2894 raw_cell : str
2891 raw_cell : str
2895 The code to be executed
2892 The code to be executed
2896
2893
2897 Returns
2894 Returns
2898 -------
2895 -------
2899 result: bool
2896 result: bool
2900 Whether the code needs to be run with a coroutine runner or not
2897 Whether the code needs to be run with a coroutine runner or not
2901 .. versionadded:: 7.0
2898 .. versionadded:: 7.0
2902 """
2899 """
2903 if not self.autoawait:
2900 if not self.autoawait:
2904 return False
2901 return False
2905 if preprocessing_exc_tuple is not None:
2902 if preprocessing_exc_tuple is not None:
2906 return False
2903 return False
2907 assert preprocessing_exc_tuple is None
2904 assert preprocessing_exc_tuple is None
2908 if transformed_cell is None:
2905 if transformed_cell is None:
2909 warnings.warn(
2906 warnings.warn(
2910 "`should_run_async` will not call `transform_cell`"
2907 "`should_run_async` will not call `transform_cell`"
2911 " automatically in the future. Please pass the result to"
2908 " automatically in the future. Please pass the result to"
2912 " `transformed_cell` argument and any exception that happen"
2909 " `transformed_cell` argument and any exception that happen"
2913 " during the"
2910 " during the"
2914 "transform in `preprocessing_exc_tuple` in"
2911 "transform in `preprocessing_exc_tuple` in"
2915 " IPython 7.17 and above.",
2912 " IPython 7.17 and above.",
2916 DeprecationWarning,
2913 DeprecationWarning,
2917 stacklevel=2,
2914 stacklevel=2,
2918 )
2915 )
2919 try:
2916 try:
2920 cell = self.transform_cell(raw_cell)
2917 cell = self.transform_cell(raw_cell)
2921 except Exception:
2918 except Exception:
2922 # any exception during transform will be raised
2919 # any exception during transform will be raised
2923 # prior to execution
2920 # prior to execution
2924 return False
2921 return False
2925 else:
2922 else:
2926 cell = transformed_cell
2923 cell = transformed_cell
2927 return _should_be_async(cell)
2924 return _should_be_async(cell)
2928
2925
2929 async def run_cell_async(
2926 async def run_cell_async(
2930 self,
2927 self,
2931 raw_cell: str,
2928 raw_cell: str,
2932 store_history=False,
2929 store_history=False,
2933 silent=False,
2930 silent=False,
2934 shell_futures=True,
2931 shell_futures=True,
2935 *,
2932 *,
2936 transformed_cell: Optional[str] = None,
2933 transformed_cell: Optional[str] = None,
2937 preprocessing_exc_tuple: Optional[Any] = None
2934 preprocessing_exc_tuple: Optional[Any] = None
2938 ) -> ExecutionResult:
2935 ) -> ExecutionResult:
2939 """Run a complete IPython cell asynchronously.
2936 """Run a complete IPython cell asynchronously.
2940
2937
2941 Parameters
2938 Parameters
2942 ----------
2939 ----------
2943 raw_cell : str
2940 raw_cell : str
2944 The code (including IPython code such as %magic functions) to run.
2941 The code (including IPython code such as %magic functions) to run.
2945 store_history : bool
2942 store_history : bool
2946 If True, the raw and translated cell will be stored in IPython's
2943 If True, the raw and translated cell will be stored in IPython's
2947 history. For user code calling back into IPython's machinery, this
2944 history. For user code calling back into IPython's machinery, this
2948 should be set to False.
2945 should be set to False.
2949 silent : bool
2946 silent : bool
2950 If True, avoid side-effects, such as implicit displayhooks and
2947 If True, avoid side-effects, such as implicit displayhooks and
2951 and logging. silent=True forces store_history=False.
2948 and logging. silent=True forces store_history=False.
2952 shell_futures : bool
2949 shell_futures : bool
2953 If True, the code will share future statements with the interactive
2950 If True, the code will share future statements with the interactive
2954 shell. It will both be affected by previous __future__ imports, and
2951 shell. It will both be affected by previous __future__ imports, and
2955 any __future__ imports in the code will affect the shell. If False,
2952 any __future__ imports in the code will affect the shell. If False,
2956 __future__ imports are not shared in either direction.
2953 __future__ imports are not shared in either direction.
2957 transformed_cell: str
2954 transformed_cell: str
2958 cell that was passed through transformers
2955 cell that was passed through transformers
2959 preprocessing_exc_tuple:
2956 preprocessing_exc_tuple:
2960 trace if the transformation failed.
2957 trace if the transformation failed.
2961
2958
2962 Returns
2959 Returns
2963 -------
2960 -------
2964 result : :class:`ExecutionResult`
2961 result : :class:`ExecutionResult`
2965
2962
2966 .. versionadded:: 7.0
2963 .. versionadded:: 7.0
2967 """
2964 """
2968 info = ExecutionInfo(
2965 info = ExecutionInfo(
2969 raw_cell, store_history, silent, shell_futures)
2966 raw_cell, store_history, silent, shell_futures)
2970 result = ExecutionResult(info)
2967 result = ExecutionResult(info)
2971
2968
2972 if (not raw_cell) or raw_cell.isspace():
2969 if (not raw_cell) or raw_cell.isspace():
2973 self.last_execution_succeeded = True
2970 self.last_execution_succeeded = True
2974 self.last_execution_result = result
2971 self.last_execution_result = result
2975 return result
2972 return result
2976
2973
2977 if silent:
2974 if silent:
2978 store_history = False
2975 store_history = False
2979
2976
2980 if store_history:
2977 if store_history:
2981 result.execution_count = self.execution_count
2978 result.execution_count = self.execution_count
2982
2979
2983 def error_before_exec(value):
2980 def error_before_exec(value):
2984 if store_history:
2981 if store_history:
2985 self.execution_count += 1
2982 self.execution_count += 1
2986 result.error_before_exec = value
2983 result.error_before_exec = value
2987 self.last_execution_succeeded = False
2984 self.last_execution_succeeded = False
2988 self.last_execution_result = result
2985 self.last_execution_result = result
2989 return result
2986 return result
2990
2987
2991 self.events.trigger('pre_execute')
2988 self.events.trigger('pre_execute')
2992 if not silent:
2989 if not silent:
2993 self.events.trigger('pre_run_cell', info)
2990 self.events.trigger('pre_run_cell', info)
2994
2991
2995 if transformed_cell is None:
2992 if transformed_cell is None:
2996 warnings.warn(
2993 warnings.warn(
2997 "`run_cell_async` will not call `transform_cell`"
2994 "`run_cell_async` will not call `transform_cell`"
2998 " automatically in the future. Please pass the result to"
2995 " automatically in the future. Please pass the result to"
2999 " `transformed_cell` argument and any exception that happen"
2996 " `transformed_cell` argument and any exception that happen"
3000 " during the"
2997 " during the"
3001 "transform in `preprocessing_exc_tuple` in"
2998 "transform in `preprocessing_exc_tuple` in"
3002 " IPython 7.17 and above.",
2999 " IPython 7.17 and above.",
3003 DeprecationWarning,
3000 DeprecationWarning,
3004 stacklevel=2,
3001 stacklevel=2,
3005 )
3002 )
3006 # If any of our input transformation (input_transformer_manager or
3003 # If any of our input transformation (input_transformer_manager or
3007 # prefilter_manager) raises an exception, we store it in this variable
3004 # prefilter_manager) raises an exception, we store it in this variable
3008 # so that we can display the error after logging the input and storing
3005 # so that we can display the error after logging the input and storing
3009 # it in the history.
3006 # it in the history.
3010 try:
3007 try:
3011 cell = self.transform_cell(raw_cell)
3008 cell = self.transform_cell(raw_cell)
3012 except Exception:
3009 except Exception:
3013 preprocessing_exc_tuple = sys.exc_info()
3010 preprocessing_exc_tuple = sys.exc_info()
3014 cell = raw_cell # cell has to exist so it can be stored/logged
3011 cell = raw_cell # cell has to exist so it can be stored/logged
3015 else:
3012 else:
3016 preprocessing_exc_tuple = None
3013 preprocessing_exc_tuple = None
3017 else:
3014 else:
3018 if preprocessing_exc_tuple is None:
3015 if preprocessing_exc_tuple is None:
3019 cell = transformed_cell
3016 cell = transformed_cell
3020 else:
3017 else:
3021 cell = raw_cell
3018 cell = raw_cell
3022
3019
3023 # Store raw and processed history
3020 # Store raw and processed history
3024 if store_history:
3021 if store_history:
3025 self.history_manager.store_inputs(self.execution_count,
3022 self.history_manager.store_inputs(self.execution_count,
3026 cell, raw_cell)
3023 cell, raw_cell)
3027 if not silent:
3024 if not silent:
3028 self.logger.log(cell, raw_cell)
3025 self.logger.log(cell, raw_cell)
3029
3026
3030 # Display the exception if input processing failed.
3027 # Display the exception if input processing failed.
3031 if preprocessing_exc_tuple is not None:
3028 if preprocessing_exc_tuple is not None:
3032 self.showtraceback(preprocessing_exc_tuple)
3029 self.showtraceback(preprocessing_exc_tuple)
3033 if store_history:
3030 if store_history:
3034 self.execution_count += 1
3031 self.execution_count += 1
3035 return error_before_exec(preprocessing_exc_tuple[1])
3032 return error_before_exec(preprocessing_exc_tuple[1])
3036
3033
3037 # Our own compiler remembers the __future__ environment. If we want to
3034 # Our own compiler remembers the __future__ environment. If we want to
3038 # run code with a separate __future__ environment, use the default
3035 # run code with a separate __future__ environment, use the default
3039 # compiler
3036 # compiler
3040 compiler = self.compile if shell_futures else self.compiler_class()
3037 compiler = self.compile if shell_futures else self.compiler_class()
3041
3038
3042 _run_async = False
3039 _run_async = False
3043
3040
3044 with self.builtin_trap:
3041 with self.builtin_trap:
3045 cell_name = compiler.cache(cell, self.execution_count, raw_code=raw_cell)
3042 cell_name = compiler.cache(cell, self.execution_count, raw_code=raw_cell)
3046
3043
3047 with self.display_trap:
3044 with self.display_trap:
3048 # Compile to bytecode
3045 # Compile to bytecode
3049 try:
3046 try:
3050 code_ast = compiler.ast_parse(cell, filename=cell_name)
3047 code_ast = compiler.ast_parse(cell, filename=cell_name)
3051 except self.custom_exceptions as e:
3048 except self.custom_exceptions as e:
3052 etype, value, tb = sys.exc_info()
3049 etype, value, tb = sys.exc_info()
3053 self.CustomTB(etype, value, tb)
3050 self.CustomTB(etype, value, tb)
3054 return error_before_exec(e)
3051 return error_before_exec(e)
3055 except IndentationError as e:
3052 except IndentationError as e:
3056 self.showindentationerror()
3053 self.showindentationerror()
3057 return error_before_exec(e)
3054 return error_before_exec(e)
3058 except (OverflowError, SyntaxError, ValueError, TypeError,
3055 except (OverflowError, SyntaxError, ValueError, TypeError,
3059 MemoryError) as e:
3056 MemoryError) as e:
3060 self.showsyntaxerror()
3057 self.showsyntaxerror()
3061 return error_before_exec(e)
3058 return error_before_exec(e)
3062
3059
3063 # Apply AST transformations
3060 # Apply AST transformations
3064 try:
3061 try:
3065 code_ast = self.transform_ast(code_ast)
3062 code_ast = self.transform_ast(code_ast)
3066 except InputRejected as e:
3063 except InputRejected as e:
3067 self.showtraceback()
3064 self.showtraceback()
3068 return error_before_exec(e)
3065 return error_before_exec(e)
3069
3066
3070 # Give the displayhook a reference to our ExecutionResult so it
3067 # Give the displayhook a reference to our ExecutionResult so it
3071 # can fill in the output value.
3068 # can fill in the output value.
3072 self.displayhook.exec_result = result
3069 self.displayhook.exec_result = result
3073
3070
3074 # Execute the user code
3071 # Execute the user code
3075 interactivity = "none" if silent else self.ast_node_interactivity
3072 interactivity = "none" if silent else self.ast_node_interactivity
3076
3073
3077 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,
3074 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,
3078 interactivity=interactivity, compiler=compiler, result=result)
3075 interactivity=interactivity, compiler=compiler, result=result)
3079
3076
3080 self.last_execution_succeeded = not has_raised
3077 self.last_execution_succeeded = not has_raised
3081 self.last_execution_result = result
3078 self.last_execution_result = result
3082
3079
3083 # Reset this so later displayed values do not modify the
3080 # Reset this so later displayed values do not modify the
3084 # ExecutionResult
3081 # ExecutionResult
3085 self.displayhook.exec_result = None
3082 self.displayhook.exec_result = None
3086
3083
3087 if store_history:
3084 if store_history:
3088 # Write output to the database. Does nothing unless
3085 # Write output to the database. Does nothing unless
3089 # history output logging is enabled.
3086 # history output logging is enabled.
3090 self.history_manager.store_output(self.execution_count)
3087 self.history_manager.store_output(self.execution_count)
3091 # Each cell is a *single* input, regardless of how many lines it has
3088 # Each cell is a *single* input, regardless of how many lines it has
3092 self.execution_count += 1
3089 self.execution_count += 1
3093
3090
3094 return result
3091 return result
3095
3092
3096 def transform_cell(self, raw_cell):
3093 def transform_cell(self, raw_cell):
3097 """Transform an input cell before parsing it.
3094 """Transform an input cell before parsing it.
3098
3095
3099 Static transformations, implemented in IPython.core.inputtransformer2,
3096 Static transformations, implemented in IPython.core.inputtransformer2,
3100 deal with things like ``%magic`` and ``!system`` commands.
3097 deal with things like ``%magic`` and ``!system`` commands.
3101 These run on all input.
3098 These run on all input.
3102 Dynamic transformations, for things like unescaped magics and the exit
3099 Dynamic transformations, for things like unescaped magics and the exit
3103 autocall, depend on the state of the interpreter.
3100 autocall, depend on the state of the interpreter.
3104 These only apply to single line inputs.
3101 These only apply to single line inputs.
3105
3102
3106 These string-based transformations are followed by AST transformations;
3103 These string-based transformations are followed by AST transformations;
3107 see :meth:`transform_ast`.
3104 see :meth:`transform_ast`.
3108 """
3105 """
3109 # Static input transformations
3106 # Static input transformations
3110 cell = self.input_transformer_manager.transform_cell(raw_cell)
3107 cell = self.input_transformer_manager.transform_cell(raw_cell)
3111
3108
3112 if len(cell.splitlines()) == 1:
3109 if len(cell.splitlines()) == 1:
3113 # Dynamic transformations - only applied for single line commands
3110 # Dynamic transformations - only applied for single line commands
3114 with self.builtin_trap:
3111 with self.builtin_trap:
3115 # use prefilter_lines to handle trailing newlines
3112 # use prefilter_lines to handle trailing newlines
3116 # restore trailing newline for ast.parse
3113 # restore trailing newline for ast.parse
3117 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
3114 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
3118
3115
3119 lines = cell.splitlines(keepends=True)
3116 lines = cell.splitlines(keepends=True)
3120 for transform in self.input_transformers_post:
3117 for transform in self.input_transformers_post:
3121 lines = transform(lines)
3118 lines = transform(lines)
3122 cell = ''.join(lines)
3119 cell = ''.join(lines)
3123
3120
3124 return cell
3121 return cell
3125
3122
3126 def transform_ast(self, node):
3123 def transform_ast(self, node):
3127 """Apply the AST transformations from self.ast_transformers
3124 """Apply the AST transformations from self.ast_transformers
3128
3125
3129 Parameters
3126 Parameters
3130 ----------
3127 ----------
3131 node : ast.Node
3128 node : ast.Node
3132 The root node to be transformed. Typically called with the ast.Module
3129 The root node to be transformed. Typically called with the ast.Module
3133 produced by parsing user input.
3130 produced by parsing user input.
3134
3131
3135 Returns
3132 Returns
3136 -------
3133 -------
3137 An ast.Node corresponding to the node it was called with. Note that it
3134 An ast.Node corresponding to the node it was called with. Note that it
3138 may also modify the passed object, so don't rely on references to the
3135 may also modify the passed object, so don't rely on references to the
3139 original AST.
3136 original AST.
3140 """
3137 """
3141 for transformer in self.ast_transformers:
3138 for transformer in self.ast_transformers:
3142 try:
3139 try:
3143 node = transformer.visit(node)
3140 node = transformer.visit(node)
3144 except InputRejected:
3141 except InputRejected:
3145 # User-supplied AST transformers can reject an input by raising
3142 # User-supplied AST transformers can reject an input by raising
3146 # an InputRejected. Short-circuit in this case so that we
3143 # an InputRejected. Short-circuit in this case so that we
3147 # don't unregister the transform.
3144 # don't unregister the transform.
3148 raise
3145 raise
3149 except Exception:
3146 except Exception:
3150 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
3147 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
3151 self.ast_transformers.remove(transformer)
3148 self.ast_transformers.remove(transformer)
3152
3149
3153 if self.ast_transformers:
3150 if self.ast_transformers:
3154 ast.fix_missing_locations(node)
3151 ast.fix_missing_locations(node)
3155 return node
3152 return node
3156
3153
3157 def _update_code_co_name(self, code):
3154 def _update_code_co_name(self, code):
3158 """Python 3.10 changed the behaviour so that whenever a code object
3155 """Python 3.10 changed the behaviour so that whenever a code object
3159 is assembled in the compile(ast) the co_firstlineno would be == 1.
3156 is assembled in the compile(ast) the co_firstlineno would be == 1.
3160
3157
3161 This makes pydevd/debugpy think that all cells invoked are the same
3158 This makes pydevd/debugpy think that all cells invoked are the same
3162 since it caches information based on (co_firstlineno, co_name, co_filename).
3159 since it caches information based on (co_firstlineno, co_name, co_filename).
3163
3160
3164 Given that, this function changes the code 'co_name' to be unique
3161 Given that, this function changes the code 'co_name' to be unique
3165 based on the first real lineno of the code (which also has a nice
3162 based on the first real lineno of the code (which also has a nice
3166 side effect of customizing the name so that it's not always <module>).
3163 side effect of customizing the name so that it's not always <module>).
3167
3164
3168 See: https://github.com/ipython/ipykernel/issues/841
3165 See: https://github.com/ipython/ipykernel/issues/841
3169 """
3166 """
3170 if not hasattr(code, "replace"):
3167 if not hasattr(code, "replace"):
3171 # It may not be available on older versions of Python (only
3168 # It may not be available on older versions of Python (only
3172 # available for 3.8 onwards).
3169 # available for 3.8 onwards).
3173 return code
3170 return code
3174 try:
3171 try:
3175 first_real_line = next(dis.findlinestarts(code))[1]
3172 first_real_line = next(dis.findlinestarts(code))[1]
3176 except StopIteration:
3173 except StopIteration:
3177 return code
3174 return code
3178 return code.replace(co_name="<cell line: %s>" % (first_real_line,))
3175 return code.replace(co_name="<cell line: %s>" % (first_real_line,))
3179
3176
3180 async def run_ast_nodes(
3177 async def run_ast_nodes(
3181 self,
3178 self,
3182 nodelist: ListType[stmt],
3179 nodelist: ListType[stmt],
3183 cell_name: str,
3180 cell_name: str,
3184 interactivity="last_expr",
3181 interactivity="last_expr",
3185 compiler=compile,
3182 compiler=compile,
3186 result=None,
3183 result=None,
3187 ):
3184 ):
3188 """Run a sequence of AST nodes. The execution mode depends on the
3185 """Run a sequence of AST nodes. The execution mode depends on the
3189 interactivity parameter.
3186 interactivity parameter.
3190
3187
3191 Parameters
3188 Parameters
3192 ----------
3189 ----------
3193 nodelist : list
3190 nodelist : list
3194 A sequence of AST nodes to run.
3191 A sequence of AST nodes to run.
3195 cell_name : str
3192 cell_name : str
3196 Will be passed to the compiler as the filename of the cell. Typically
3193 Will be passed to the compiler as the filename of the cell. Typically
3197 the value returned by ip.compile.cache(cell).
3194 the value returned by ip.compile.cache(cell).
3198 interactivity : str
3195 interactivity : str
3199 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
3196 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
3200 specifying which nodes should be run interactively (displaying output
3197 specifying which nodes should be run interactively (displaying output
3201 from expressions). 'last_expr' will run the last node interactively
3198 from expressions). 'last_expr' will run the last node interactively
3202 only if it is an expression (i.e. expressions in loops or other blocks
3199 only if it is an expression (i.e. expressions in loops or other blocks
3203 are not displayed) 'last_expr_or_assign' will run the last expression
3200 are not displayed) 'last_expr_or_assign' will run the last expression
3204 or the last assignment. Other values for this parameter will raise a
3201 or the last assignment. Other values for this parameter will raise a
3205 ValueError.
3202 ValueError.
3206
3203
3207 compiler : callable
3204 compiler : callable
3208 A function with the same interface as the built-in compile(), to turn
3205 A function with the same interface as the built-in compile(), to turn
3209 the AST nodes into code objects. Default is the built-in compile().
3206 the AST nodes into code objects. Default is the built-in compile().
3210 result : ExecutionResult, optional
3207 result : ExecutionResult, optional
3211 An object to store exceptions that occur during execution.
3208 An object to store exceptions that occur during execution.
3212
3209
3213 Returns
3210 Returns
3214 -------
3211 -------
3215 True if an exception occurred while running code, False if it finished
3212 True if an exception occurred while running code, False if it finished
3216 running.
3213 running.
3217 """
3214 """
3218 if not nodelist:
3215 if not nodelist:
3219 return
3216 return
3220
3217
3221
3218
3222 if interactivity == 'last_expr_or_assign':
3219 if interactivity == 'last_expr_or_assign':
3223 if isinstance(nodelist[-1], _assign_nodes):
3220 if isinstance(nodelist[-1], _assign_nodes):
3224 asg = nodelist[-1]
3221 asg = nodelist[-1]
3225 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
3222 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
3226 target = asg.targets[0]
3223 target = asg.targets[0]
3227 elif isinstance(asg, _single_targets_nodes):
3224 elif isinstance(asg, _single_targets_nodes):
3228 target = asg.target
3225 target = asg.target
3229 else:
3226 else:
3230 target = None
3227 target = None
3231 if isinstance(target, ast.Name):
3228 if isinstance(target, ast.Name):
3232 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
3229 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
3233 ast.fix_missing_locations(nnode)
3230 ast.fix_missing_locations(nnode)
3234 nodelist.append(nnode)
3231 nodelist.append(nnode)
3235 interactivity = 'last_expr'
3232 interactivity = 'last_expr'
3236
3233
3237 _async = False
3234 _async = False
3238 if interactivity == 'last_expr':
3235 if interactivity == 'last_expr':
3239 if isinstance(nodelist[-1], ast.Expr):
3236 if isinstance(nodelist[-1], ast.Expr):
3240 interactivity = "last"
3237 interactivity = "last"
3241 else:
3238 else:
3242 interactivity = "none"
3239 interactivity = "none"
3243
3240
3244 if interactivity == 'none':
3241 if interactivity == 'none':
3245 to_run_exec, to_run_interactive = nodelist, []
3242 to_run_exec, to_run_interactive = nodelist, []
3246 elif interactivity == 'last':
3243 elif interactivity == 'last':
3247 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
3244 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
3248 elif interactivity == 'all':
3245 elif interactivity == 'all':
3249 to_run_exec, to_run_interactive = [], nodelist
3246 to_run_exec, to_run_interactive = [], nodelist
3250 else:
3247 else:
3251 raise ValueError("Interactivity was %r" % interactivity)
3248 raise ValueError("Interactivity was %r" % interactivity)
3252
3249
3253 try:
3250 try:
3254
3251
3255 def compare(code):
3252 def compare(code):
3256 is_async = inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE
3253 is_async = inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE
3257 return is_async
3254 return is_async
3258
3255
3259 # refactor that to just change the mod constructor.
3256 # refactor that to just change the mod constructor.
3260 to_run = []
3257 to_run = []
3261 for node in to_run_exec:
3258 for node in to_run_exec:
3262 to_run.append((node, "exec"))
3259 to_run.append((node, "exec"))
3263
3260
3264 for node in to_run_interactive:
3261 for node in to_run_interactive:
3265 to_run.append((node, "single"))
3262 to_run.append((node, "single"))
3266
3263
3267 for node, mode in to_run:
3264 for node, mode in to_run:
3268 if mode == "exec":
3265 if mode == "exec":
3269 mod = Module([node], [])
3266 mod = Module([node], [])
3270 elif mode == "single":
3267 elif mode == "single":
3271 mod = ast.Interactive([node])
3268 mod = ast.Interactive([node])
3272 with compiler.extra_flags(
3269 with compiler.extra_flags(
3273 getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x0)
3270 getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x0)
3274 if self.autoawait
3271 if self.autoawait
3275 else 0x0
3272 else 0x0
3276 ):
3273 ):
3277 code = compiler(mod, cell_name, mode)
3274 code = compiler(mod, cell_name, mode)
3278 code = self._update_code_co_name(code)
3275 code = self._update_code_co_name(code)
3279 asy = compare(code)
3276 asy = compare(code)
3280 if await self.run_code(code, result, async_=asy):
3277 if await self.run_code(code, result, async_=asy):
3281 return True
3278 return True
3282
3279
3283 # Flush softspace
3280 # Flush softspace
3284 if softspace(sys.stdout, 0):
3281 if softspace(sys.stdout, 0):
3285 print()
3282 print()
3286
3283
3287 except:
3284 except:
3288 # It's possible to have exceptions raised here, typically by
3285 # It's possible to have exceptions raised here, typically by
3289 # compilation of odd code (such as a naked 'return' outside a
3286 # compilation of odd code (such as a naked 'return' outside a
3290 # function) that did parse but isn't valid. Typically the exception
3287 # function) that did parse but isn't valid. Typically the exception
3291 # is a SyntaxError, but it's safest just to catch anything and show
3288 # is a SyntaxError, but it's safest just to catch anything and show
3292 # the user a traceback.
3289 # the user a traceback.
3293
3290
3294 # We do only one try/except outside the loop to minimize the impact
3291 # We do only one try/except outside the loop to minimize the impact
3295 # on runtime, and also because if any node in the node list is
3292 # on runtime, and also because if any node in the node list is
3296 # broken, we should stop execution completely.
3293 # broken, we should stop execution completely.
3297 if result:
3294 if result:
3298 result.error_before_exec = sys.exc_info()[1]
3295 result.error_before_exec = sys.exc_info()[1]
3299 self.showtraceback()
3296 self.showtraceback()
3300 return True
3297 return True
3301
3298
3302 return False
3299 return False
3303
3300
3304 async def run_code(self, code_obj, result=None, *, async_=False):
3301 async def run_code(self, code_obj, result=None, *, async_=False):
3305 """Execute a code object.
3302 """Execute a code object.
3306
3303
3307 When an exception occurs, self.showtraceback() is called to display a
3304 When an exception occurs, self.showtraceback() is called to display a
3308 traceback.
3305 traceback.
3309
3306
3310 Parameters
3307 Parameters
3311 ----------
3308 ----------
3312 code_obj : code object
3309 code_obj : code object
3313 A compiled code object, to be executed
3310 A compiled code object, to be executed
3314 result : ExecutionResult, optional
3311 result : ExecutionResult, optional
3315 An object to store exceptions that occur during execution.
3312 An object to store exceptions that occur during execution.
3316 async_ : Bool (Experimental)
3313 async_ : Bool (Experimental)
3317 Attempt to run top-level asynchronous code in a default loop.
3314 Attempt to run top-level asynchronous code in a default loop.
3318
3315
3319 Returns
3316 Returns
3320 -------
3317 -------
3321 False : successful execution.
3318 False : successful execution.
3322 True : an error occurred.
3319 True : an error occurred.
3323 """
3320 """
3324 # special value to say that anything above is IPython and should be
3321 # special value to say that anything above is IPython and should be
3325 # hidden.
3322 # hidden.
3326 __tracebackhide__ = "__ipython_bottom__"
3323 __tracebackhide__ = "__ipython_bottom__"
3327 # Set our own excepthook in case the user code tries to call it
3324 # Set our own excepthook in case the user code tries to call it
3328 # directly, so that the IPython crash handler doesn't get triggered
3325 # directly, so that the IPython crash handler doesn't get triggered
3329 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
3326 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
3330
3327
3331 # we save the original sys.excepthook in the instance, in case config
3328 # we save the original sys.excepthook in the instance, in case config
3332 # code (such as magics) needs access to it.
3329 # code (such as magics) needs access to it.
3333 self.sys_excepthook = old_excepthook
3330 self.sys_excepthook = old_excepthook
3334 outflag = True # happens in more places, so it's easier as default
3331 outflag = True # happens in more places, so it's easier as default
3335 try:
3332 try:
3336 try:
3333 try:
3337 if async_:
3334 if async_:
3338 await eval(code_obj, self.user_global_ns, self.user_ns)
3335 await eval(code_obj, self.user_global_ns, self.user_ns)
3339 else:
3336 else:
3340 exec(code_obj, self.user_global_ns, self.user_ns)
3337 exec(code_obj, self.user_global_ns, self.user_ns)
3341 finally:
3338 finally:
3342 # Reset our crash handler in place
3339 # Reset our crash handler in place
3343 sys.excepthook = old_excepthook
3340 sys.excepthook = old_excepthook
3344 except SystemExit as e:
3341 except SystemExit as e:
3345 if result is not None:
3342 if result is not None:
3346 result.error_in_exec = e
3343 result.error_in_exec = e
3347 self.showtraceback(exception_only=True)
3344 self.showtraceback(exception_only=True)
3348 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
3345 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
3349 except self.custom_exceptions:
3346 except self.custom_exceptions:
3350 etype, value, tb = sys.exc_info()
3347 etype, value, tb = sys.exc_info()
3351 if result is not None:
3348 if result is not None:
3352 result.error_in_exec = value
3349 result.error_in_exec = value
3353 self.CustomTB(etype, value, tb)
3350 self.CustomTB(etype, value, tb)
3354 except:
3351 except:
3355 if result is not None:
3352 if result is not None:
3356 result.error_in_exec = sys.exc_info()[1]
3353 result.error_in_exec = sys.exc_info()[1]
3357 self.showtraceback(running_compiled_code=True)
3354 self.showtraceback(running_compiled_code=True)
3358 else:
3355 else:
3359 outflag = False
3356 outflag = False
3360 return outflag
3357 return outflag
3361
3358
3362 # For backwards compatibility
3359 # For backwards compatibility
3363 runcode = run_code
3360 runcode = run_code
3364
3361
3365 def check_complete(self, code: str) -> Tuple[str, str]:
3362 def check_complete(self, code: str) -> Tuple[str, str]:
3366 """Return whether a block of code is ready to execute, or should be continued
3363 """Return whether a block of code is ready to execute, or should be continued
3367
3364
3368 Parameters
3365 Parameters
3369 ----------
3366 ----------
3370 code : string
3367 code : string
3371 Python input code, which can be multiline.
3368 Python input code, which can be multiline.
3372
3369
3373 Returns
3370 Returns
3374 -------
3371 -------
3375 status : str
3372 status : str
3376 One of 'complete', 'incomplete', or 'invalid' if source is not a
3373 One of 'complete', 'incomplete', or 'invalid' if source is not a
3377 prefix of valid code.
3374 prefix of valid code.
3378 indent : str
3375 indent : str
3379 When status is 'incomplete', this is some whitespace to insert on
3376 When status is 'incomplete', this is some whitespace to insert on
3380 the next line of the prompt.
3377 the next line of the prompt.
3381 """
3378 """
3382 status, nspaces = self.input_transformer_manager.check_complete(code)
3379 status, nspaces = self.input_transformer_manager.check_complete(code)
3383 return status, ' ' * (nspaces or 0)
3380 return status, ' ' * (nspaces or 0)
3384
3381
3385 #-------------------------------------------------------------------------
3382 #-------------------------------------------------------------------------
3386 # Things related to GUI support and pylab
3383 # Things related to GUI support and pylab
3387 #-------------------------------------------------------------------------
3384 #-------------------------------------------------------------------------
3388
3385
3389 active_eventloop = None
3386 active_eventloop = None
3390
3387
3391 def enable_gui(self, gui=None):
3388 def enable_gui(self, gui=None):
3392 raise NotImplementedError('Implement enable_gui in a subclass')
3389 raise NotImplementedError('Implement enable_gui in a subclass')
3393
3390
3394 def enable_matplotlib(self, gui=None):
3391 def enable_matplotlib(self, gui=None):
3395 """Enable interactive matplotlib and inline figure support.
3392 """Enable interactive matplotlib and inline figure support.
3396
3393
3397 This takes the following steps:
3394 This takes the following steps:
3398
3395
3399 1. select the appropriate eventloop and matplotlib backend
3396 1. select the appropriate eventloop and matplotlib backend
3400 2. set up matplotlib for interactive use with that backend
3397 2. set up matplotlib for interactive use with that backend
3401 3. configure formatters for inline figure display
3398 3. configure formatters for inline figure display
3402 4. enable the selected gui eventloop
3399 4. enable the selected gui eventloop
3403
3400
3404 Parameters
3401 Parameters
3405 ----------
3402 ----------
3406 gui : optional, string
3403 gui : optional, string
3407 If given, dictates the choice of matplotlib GUI backend to use
3404 If given, dictates the choice of matplotlib GUI backend to use
3408 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3405 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3409 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3406 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3410 matplotlib (as dictated by the matplotlib build-time options plus the
3407 matplotlib (as dictated by the matplotlib build-time options plus the
3411 user's matplotlibrc configuration file). Note that not all backends
3408 user's matplotlibrc configuration file). Note that not all backends
3412 make sense in all contexts, for example a terminal ipython can't
3409 make sense in all contexts, for example a terminal ipython can't
3413 display figures inline.
3410 display figures inline.
3414 """
3411 """
3415 from matplotlib_inline.backend_inline import configure_inline_support
3412 from matplotlib_inline.backend_inline import configure_inline_support
3416
3413
3417 from IPython.core import pylabtools as pt
3414 from IPython.core import pylabtools as pt
3418 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3415 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3419
3416
3420 if gui != 'inline':
3417 if gui != 'inline':
3421 # If we have our first gui selection, store it
3418 # If we have our first gui selection, store it
3422 if self.pylab_gui_select is None:
3419 if self.pylab_gui_select is None:
3423 self.pylab_gui_select = gui
3420 self.pylab_gui_select = gui
3424 # Otherwise if they are different
3421 # Otherwise if they are different
3425 elif gui != self.pylab_gui_select:
3422 elif gui != self.pylab_gui_select:
3426 print('Warning: Cannot change to a different GUI toolkit: %s.'
3423 print('Warning: Cannot change to a different GUI toolkit: %s.'
3427 ' Using %s instead.' % (gui, self.pylab_gui_select))
3424 ' Using %s instead.' % (gui, self.pylab_gui_select))
3428 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3425 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3429
3426
3430 pt.activate_matplotlib(backend)
3427 pt.activate_matplotlib(backend)
3431 configure_inline_support(self, backend)
3428 configure_inline_support(self, backend)
3432
3429
3433 # Now we must activate the gui pylab wants to use, and fix %run to take
3430 # Now we must activate the gui pylab wants to use, and fix %run to take
3434 # plot updates into account
3431 # plot updates into account
3435 self.enable_gui(gui)
3432 self.enable_gui(gui)
3436 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3433 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3437 pt.mpl_runner(self.safe_execfile)
3434 pt.mpl_runner(self.safe_execfile)
3438
3435
3439 return gui, backend
3436 return gui, backend
3440
3437
3441 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3438 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3442 """Activate pylab support at runtime.
3439 """Activate pylab support at runtime.
3443
3440
3444 This turns on support for matplotlib, preloads into the interactive
3441 This turns on support for matplotlib, preloads into the interactive
3445 namespace all of numpy and pylab, and configures IPython to correctly
3442 namespace all of numpy and pylab, and configures IPython to correctly
3446 interact with the GUI event loop. The GUI backend to be used can be
3443 interact with the GUI event loop. The GUI backend to be used can be
3447 optionally selected with the optional ``gui`` argument.
3444 optionally selected with the optional ``gui`` argument.
3448
3445
3449 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3446 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3450
3447
3451 Parameters
3448 Parameters
3452 ----------
3449 ----------
3453 gui : optional, string
3450 gui : optional, string
3454 If given, dictates the choice of matplotlib GUI backend to use
3451 If given, dictates the choice of matplotlib GUI backend to use
3455 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3452 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3456 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3453 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3457 matplotlib (as dictated by the matplotlib build-time options plus the
3454 matplotlib (as dictated by the matplotlib build-time options plus the
3458 user's matplotlibrc configuration file). Note that not all backends
3455 user's matplotlibrc configuration file). Note that not all backends
3459 make sense in all contexts, for example a terminal ipython can't
3456 make sense in all contexts, for example a terminal ipython can't
3460 display figures inline.
3457 display figures inline.
3461 import_all : optional, bool, default: True
3458 import_all : optional, bool, default: True
3462 Whether to do `from numpy import *` and `from pylab import *`
3459 Whether to do `from numpy import *` and `from pylab import *`
3463 in addition to module imports.
3460 in addition to module imports.
3464 welcome_message : deprecated
3461 welcome_message : deprecated
3465 This argument is ignored, no welcome message will be displayed.
3462 This argument is ignored, no welcome message will be displayed.
3466 """
3463 """
3467 from IPython.core.pylabtools import import_pylab
3464 from IPython.core.pylabtools import import_pylab
3468
3465
3469 gui, backend = self.enable_matplotlib(gui)
3466 gui, backend = self.enable_matplotlib(gui)
3470
3467
3471 # We want to prevent the loading of pylab to pollute the user's
3468 # We want to prevent the loading of pylab to pollute the user's
3472 # namespace as shown by the %who* magics, so we execute the activation
3469 # namespace as shown by the %who* magics, so we execute the activation
3473 # code in an empty namespace, and we update *both* user_ns and
3470 # code in an empty namespace, and we update *both* user_ns and
3474 # user_ns_hidden with this information.
3471 # user_ns_hidden with this information.
3475 ns = {}
3472 ns = {}
3476 import_pylab(ns, import_all)
3473 import_pylab(ns, import_all)
3477 # warn about clobbered names
3474 # warn about clobbered names
3478 ignored = {"__builtins__"}
3475 ignored = {"__builtins__"}
3479 both = set(ns).intersection(self.user_ns).difference(ignored)
3476 both = set(ns).intersection(self.user_ns).difference(ignored)
3480 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3477 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3481 self.user_ns.update(ns)
3478 self.user_ns.update(ns)
3482 self.user_ns_hidden.update(ns)
3479 self.user_ns_hidden.update(ns)
3483 return gui, backend, clobbered
3480 return gui, backend, clobbered
3484
3481
3485 #-------------------------------------------------------------------------
3482 #-------------------------------------------------------------------------
3486 # Utilities
3483 # Utilities
3487 #-------------------------------------------------------------------------
3484 #-------------------------------------------------------------------------
3488
3485
3489 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3486 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3490 """Expand python variables in a string.
3487 """Expand python variables in a string.
3491
3488
3492 The depth argument indicates how many frames above the caller should
3489 The depth argument indicates how many frames above the caller should
3493 be walked to look for the local namespace where to expand variables.
3490 be walked to look for the local namespace where to expand variables.
3494
3491
3495 The global namespace for expansion is always the user's interactive
3492 The global namespace for expansion is always the user's interactive
3496 namespace.
3493 namespace.
3497 """
3494 """
3498 ns = self.user_ns.copy()
3495 ns = self.user_ns.copy()
3499 try:
3496 try:
3500 frame = sys._getframe(depth+1)
3497 frame = sys._getframe(depth+1)
3501 except ValueError:
3498 except ValueError:
3502 # This is thrown if there aren't that many frames on the stack,
3499 # This is thrown if there aren't that many frames on the stack,
3503 # e.g. if a script called run_line_magic() directly.
3500 # e.g. if a script called run_line_magic() directly.
3504 pass
3501 pass
3505 else:
3502 else:
3506 ns.update(frame.f_locals)
3503 ns.update(frame.f_locals)
3507
3504
3508 try:
3505 try:
3509 # We have to use .vformat() here, because 'self' is a valid and common
3506 # We have to use .vformat() here, because 'self' is a valid and common
3510 # name, and expanding **ns for .format() would make it collide with
3507 # name, and expanding **ns for .format() would make it collide with
3511 # the 'self' argument of the method.
3508 # the 'self' argument of the method.
3512 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3509 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3513 except Exception:
3510 except Exception:
3514 # if formatter couldn't format, just let it go untransformed
3511 # if formatter couldn't format, just let it go untransformed
3515 pass
3512 pass
3516 return cmd
3513 return cmd
3517
3514
3518 def mktempfile(self, data=None, prefix='ipython_edit_'):
3515 def mktempfile(self, data=None, prefix='ipython_edit_'):
3519 """Make a new tempfile and return its filename.
3516 """Make a new tempfile and return its filename.
3520
3517
3521 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3518 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3522 but it registers the created filename internally so ipython cleans it up
3519 but it registers the created filename internally so ipython cleans it up
3523 at exit time.
3520 at exit time.
3524
3521
3525 Optional inputs:
3522 Optional inputs:
3526
3523
3527 - data(None): if data is given, it gets written out to the temp file
3524 - data(None): if data is given, it gets written out to the temp file
3528 immediately, and the file is closed again."""
3525 immediately, and the file is closed again."""
3529
3526
3530 dir_path = Path(tempfile.mkdtemp(prefix=prefix))
3527 dir_path = Path(tempfile.mkdtemp(prefix=prefix))
3531 self.tempdirs.append(dir_path)
3528 self.tempdirs.append(dir_path)
3532
3529
3533 handle, filename = tempfile.mkstemp(".py", prefix, dir=str(dir_path))
3530 handle, filename = tempfile.mkstemp(".py", prefix, dir=str(dir_path))
3534 os.close(handle) # On Windows, there can only be one open handle on a file
3531 os.close(handle) # On Windows, there can only be one open handle on a file
3535
3532
3536 file_path = Path(filename)
3533 file_path = Path(filename)
3537 self.tempfiles.append(file_path)
3534 self.tempfiles.append(file_path)
3538
3535
3539 if data:
3536 if data:
3540 file_path.write_text(data, encoding="utf-8")
3537 file_path.write_text(data, encoding="utf-8")
3541 return filename
3538 return filename
3542
3539
3543 def ask_yes_no(self, prompt, default=None, interrupt=None):
3540 def ask_yes_no(self, prompt, default=None, interrupt=None):
3544 if self.quiet:
3541 if self.quiet:
3545 return True
3542 return True
3546 return ask_yes_no(prompt,default,interrupt)
3543 return ask_yes_no(prompt,default,interrupt)
3547
3544
3548 def show_usage(self):
3545 def show_usage(self):
3549 """Show a usage message"""
3546 """Show a usage message"""
3550 page.page(IPython.core.usage.interactive_usage)
3547 page.page(IPython.core.usage.interactive_usage)
3551
3548
3552 def extract_input_lines(self, range_str, raw=False):
3549 def extract_input_lines(self, range_str, raw=False):
3553 """Return as a string a set of input history slices.
3550 """Return as a string a set of input history slices.
3554
3551
3555 Parameters
3552 Parameters
3556 ----------
3553 ----------
3557 range_str : str
3554 range_str : str
3558 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3555 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3559 since this function is for use by magic functions which get their
3556 since this function is for use by magic functions which get their
3560 arguments as strings. The number before the / is the session
3557 arguments as strings. The number before the / is the session
3561 number: ~n goes n back from the current session.
3558 number: ~n goes n back from the current session.
3562
3559
3563 If empty string is given, returns history of current session
3560 If empty string is given, returns history of current session
3564 without the last input.
3561 without the last input.
3565
3562
3566 raw : bool, optional
3563 raw : bool, optional
3567 By default, the processed input is used. If this is true, the raw
3564 By default, the processed input is used. If this is true, the raw
3568 input history is used instead.
3565 input history is used instead.
3569
3566
3570 Notes
3567 Notes
3571 -----
3568 -----
3572 Slices can be described with two notations:
3569 Slices can be described with two notations:
3573
3570
3574 * ``N:M`` -> standard python form, means including items N...(M-1).
3571 * ``N:M`` -> standard python form, means including items N...(M-1).
3575 * ``N-M`` -> include items N..M (closed endpoint).
3572 * ``N-M`` -> include items N..M (closed endpoint).
3576 """
3573 """
3577 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3574 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3578 text = "\n".join(x for _, _, x in lines)
3575 text = "\n".join(x for _, _, x in lines)
3579
3576
3580 # Skip the last line, as it's probably the magic that called this
3577 # Skip the last line, as it's probably the magic that called this
3581 if not range_str:
3578 if not range_str:
3582 if "\n" not in text:
3579 if "\n" not in text:
3583 text = ""
3580 text = ""
3584 else:
3581 else:
3585 text = text[: text.rfind("\n")]
3582 text = text[: text.rfind("\n")]
3586
3583
3587 return text
3584 return text
3588
3585
3589 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3586 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3590 """Get a code string from history, file, url, or a string or macro.
3587 """Get a code string from history, file, url, or a string or macro.
3591
3588
3592 This is mainly used by magic functions.
3589 This is mainly used by magic functions.
3593
3590
3594 Parameters
3591 Parameters
3595 ----------
3592 ----------
3596 target : str
3593 target : str
3597 A string specifying code to retrieve. This will be tried respectively
3594 A string specifying code to retrieve. This will be tried respectively
3598 as: ranges of input history (see %history for syntax), url,
3595 as: ranges of input history (see %history for syntax), url,
3599 corresponding .py file, filename, or an expression evaluating to a
3596 corresponding .py file, filename, or an expression evaluating to a
3600 string or Macro in the user namespace.
3597 string or Macro in the user namespace.
3601
3598
3602 If empty string is given, returns complete history of current
3599 If empty string is given, returns complete history of current
3603 session, without the last line.
3600 session, without the last line.
3604
3601
3605 raw : bool
3602 raw : bool
3606 If true (default), retrieve raw history. Has no effect on the other
3603 If true (default), retrieve raw history. Has no effect on the other
3607 retrieval mechanisms.
3604 retrieval mechanisms.
3608
3605
3609 py_only : bool (default False)
3606 py_only : bool (default False)
3610 Only try to fetch python code, do not try alternative methods to decode file
3607 Only try to fetch python code, do not try alternative methods to decode file
3611 if unicode fails.
3608 if unicode fails.
3612
3609
3613 Returns
3610 Returns
3614 -------
3611 -------
3615 A string of code.
3612 A string of code.
3616 ValueError is raised if nothing is found, and TypeError if it evaluates
3613 ValueError is raised if nothing is found, and TypeError if it evaluates
3617 to an object of another type. In each case, .args[0] is a printable
3614 to an object of another type. In each case, .args[0] is a printable
3618 message.
3615 message.
3619 """
3616 """
3620 code = self.extract_input_lines(target, raw=raw) # Grab history
3617 code = self.extract_input_lines(target, raw=raw) # Grab history
3621 if code:
3618 if code:
3622 return code
3619 return code
3623 try:
3620 try:
3624 if target.startswith(('http://', 'https://')):
3621 if target.startswith(('http://', 'https://')):
3625 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3622 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3626 except UnicodeDecodeError as e:
3623 except UnicodeDecodeError as e:
3627 if not py_only :
3624 if not py_only :
3628 # Deferred import
3625 # Deferred import
3629 from urllib.request import urlopen
3626 from urllib.request import urlopen
3630 response = urlopen(target)
3627 response = urlopen(target)
3631 return response.read().decode('latin1')
3628 return response.read().decode('latin1')
3632 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3629 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3633
3630
3634 potential_target = [target]
3631 potential_target = [target]
3635 try :
3632 try :
3636 potential_target.insert(0,get_py_filename(target))
3633 potential_target.insert(0,get_py_filename(target))
3637 except IOError:
3634 except IOError:
3638 pass
3635 pass
3639
3636
3640 for tgt in potential_target :
3637 for tgt in potential_target :
3641 if os.path.isfile(tgt): # Read file
3638 if os.path.isfile(tgt): # Read file
3642 try :
3639 try :
3643 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3640 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3644 except UnicodeDecodeError as e:
3641 except UnicodeDecodeError as e:
3645 if not py_only :
3642 if not py_only :
3646 with io_open(tgt,'r', encoding='latin1') as f :
3643 with io_open(tgt,'r', encoding='latin1') as f :
3647 return f.read()
3644 return f.read()
3648 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3645 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3649 elif os.path.isdir(os.path.expanduser(tgt)):
3646 elif os.path.isdir(os.path.expanduser(tgt)):
3650 raise ValueError("'%s' is a directory, not a regular file." % target)
3647 raise ValueError("'%s' is a directory, not a regular file." % target)
3651
3648
3652 if search_ns:
3649 if search_ns:
3653 # Inspect namespace to load object source
3650 # Inspect namespace to load object source
3654 object_info = self.object_inspect(target, detail_level=1)
3651 object_info = self.object_inspect(target, detail_level=1)
3655 if object_info['found'] and object_info['source']:
3652 if object_info['found'] and object_info['source']:
3656 return object_info['source']
3653 return object_info['source']
3657
3654
3658 try: # User namespace
3655 try: # User namespace
3659 codeobj = eval(target, self.user_ns)
3656 codeobj = eval(target, self.user_ns)
3660 except Exception as e:
3657 except Exception as e:
3661 raise ValueError(("'%s' was not found in history, as a file, url, "
3658 raise ValueError(("'%s' was not found in history, as a file, url, "
3662 "nor in the user namespace.") % target) from e
3659 "nor in the user namespace.") % target) from e
3663
3660
3664 if isinstance(codeobj, str):
3661 if isinstance(codeobj, str):
3665 return codeobj
3662 return codeobj
3666 elif isinstance(codeobj, Macro):
3663 elif isinstance(codeobj, Macro):
3667 return codeobj.value
3664 return codeobj.value
3668
3665
3669 raise TypeError("%s is neither a string nor a macro." % target,
3666 raise TypeError("%s is neither a string nor a macro." % target,
3670 codeobj)
3667 codeobj)
3671
3668
3672 def _atexit_once(self):
3669 def _atexit_once(self):
3673 """
3670 """
3674 At exist operation that need to be called at most once.
3671 At exist operation that need to be called at most once.
3675 Second call to this function per instance will do nothing.
3672 Second call to this function per instance will do nothing.
3676 """
3673 """
3677
3674
3678 if not getattr(self, "_atexit_once_called", False):
3675 if not getattr(self, "_atexit_once_called", False):
3679 self._atexit_once_called = True
3676 self._atexit_once_called = True
3680 # Clear all user namespaces to release all references cleanly.
3677 # Clear all user namespaces to release all references cleanly.
3681 self.reset(new_session=False)
3678 self.reset(new_session=False)
3682 # Close the history session (this stores the end time and line count)
3679 # Close the history session (this stores the end time and line count)
3683 # this must be *before* the tempfile cleanup, in case of temporary
3680 # this must be *before* the tempfile cleanup, in case of temporary
3684 # history db
3681 # history db
3685 self.history_manager.end_session()
3682 self.history_manager.end_session()
3686 self.history_manager = None
3683 self.history_manager = None
3687
3684
3688 #-------------------------------------------------------------------------
3685 #-------------------------------------------------------------------------
3689 # Things related to IPython exiting
3686 # Things related to IPython exiting
3690 #-------------------------------------------------------------------------
3687 #-------------------------------------------------------------------------
3691 def atexit_operations(self):
3688 def atexit_operations(self):
3692 """This will be executed at the time of exit.
3689 """This will be executed at the time of exit.
3693
3690
3694 Cleanup operations and saving of persistent data that is done
3691 Cleanup operations and saving of persistent data that is done
3695 unconditionally by IPython should be performed here.
3692 unconditionally by IPython should be performed here.
3696
3693
3697 For things that may depend on startup flags or platform specifics (such
3694 For things that may depend on startup flags or platform specifics (such
3698 as having readline or not), register a separate atexit function in the
3695 as having readline or not), register a separate atexit function in the
3699 code that has the appropriate information, rather than trying to
3696 code that has the appropriate information, rather than trying to
3700 clutter
3697 clutter
3701 """
3698 """
3702 self._atexit_once()
3699 self._atexit_once()
3703
3700
3704 # Cleanup all tempfiles and folders left around
3701 # Cleanup all tempfiles and folders left around
3705 for tfile in self.tempfiles:
3702 for tfile in self.tempfiles:
3706 try:
3703 try:
3707 tfile.unlink()
3704 tfile.unlink()
3708 self.tempfiles.remove(tfile)
3705 self.tempfiles.remove(tfile)
3709 except FileNotFoundError:
3706 except FileNotFoundError:
3710 pass
3707 pass
3711 del self.tempfiles
3708 del self.tempfiles
3712 for tdir in self.tempdirs:
3709 for tdir in self.tempdirs:
3713 try:
3710 try:
3714 tdir.rmdir()
3711 tdir.rmdir()
3715 self.tempdirs.remove(tdir)
3712 self.tempdirs.remove(tdir)
3716 except FileNotFoundError:
3713 except FileNotFoundError:
3717 pass
3714 pass
3718 del self.tempdirs
3715 del self.tempdirs
3719
3716
3720 # Restore user's cursor
3717 # Restore user's cursor
3721 if hasattr(self, "editing_mode") and self.editing_mode == "vi":
3718 if hasattr(self, "editing_mode") and self.editing_mode == "vi":
3722 sys.stdout.write("\x1b[0 q")
3719 sys.stdout.write("\x1b[0 q")
3723 sys.stdout.flush()
3720 sys.stdout.flush()
3724
3721
3725 def cleanup(self):
3722 def cleanup(self):
3726 self.restore_sys_module_state()
3723 self.restore_sys_module_state()
3727
3724
3728
3725
3729 # Overridden in terminal subclass to change prompts
3726 # Overridden in terminal subclass to change prompts
3730 def switch_doctest_mode(self, mode):
3727 def switch_doctest_mode(self, mode):
3731 pass
3728 pass
3732
3729
3733
3730
3734 class InteractiveShellABC(metaclass=abc.ABCMeta):
3731 class InteractiveShellABC(metaclass=abc.ABCMeta):
3735 """An abstract base class for InteractiveShell."""
3732 """An abstract base class for InteractiveShell."""
3736
3733
3737 InteractiveShellABC.register(InteractiveShell)
3734 InteractiveShellABC.register(InteractiveShell)
General Comments 0
You need to be logged in to leave comments. Login now