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