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