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