##// END OF EJS Templates
Prototype async REPL using IPython, take III...
Matthias Bussonnier -
Show More
@@ -0,0 +1,88 b''
1 """
2 Async helper function that are invalid syntax on Python 3.5 and below.
3
4 Known limitation and possible improvement.
5
6 Top level code that contain a return statement (instead of, or in addition to
7 await) will be detected as requiring being wrapped in async calls. This should
8 be prevented as early return will not work.
9 """
10
11
12
13 import ast
14 import sys
15 import inspect
16 from textwrap import dedent, indent
17 from types import CodeType
18
19
20 def _asyncio_runner(coro):
21 """
22 Handler for asyncio autoawait
23 """
24 import asyncio
25 return asyncio.get_event_loop().run_until_complete(coro)
26
27
28 def _curio_runner(coroutine):
29 """
30 handler for curio autoawait
31 """
32 import curio
33 return curio.run(coroutine)
34
35
36 if sys.version_info > (3, 5):
37 # nose refuses to avoid this file and async def is invalidsyntax
38 s = dedent('''
39 def _trio_runner(function):
40 import trio
41 async def loc(coro):
42 """
43 We need the dummy no-op async def to protect from
44 trio's internal. See https://github.com/python-trio/trio/issues/89
45 """
46 return await coro
47 return trio.run(loc, function)
48 ''')
49 exec(s, globals(), locals())
50
51
52 def _asyncify(code: str) -> str:
53 """wrap code in async def definition.
54
55 And setup a bit of context to run it later.
56 """
57 res = dedent("""
58 async def __wrapper__():
59 try:
60 {usercode}
61 finally:
62 locals()
63 """).format(usercode=indent(code, ' ' * 8)[8:])
64 return res
65
66
67 def _should_be_async(cell: str) -> bool:
68 """Detect if a block of code need to be wrapped in an `async def`
69
70 Attempt to parse the block of code, it it compile we're fine.
71 Otherwise we wrap if and try to compile.
72
73 If it works, assume it should be async. Otherwise Return False.
74
75 Not handled yet: If the block of code has a return statement as the top
76 level, it will be seen as async. This is a know limitation.
77 """
78
79 try:
80 ast.parse(cell)
81 return False
82 except SyntaxError:
83 try:
84 ast.parse(_asyncify(cell))
85 except SyntaxError:
86 return False
87 return True
88 return False
@@ -0,0 +1,52 b''
1 """
2 Test for async helpers.
3
4 Should only trigger on python 3.5+ or will have syntax errors.
5 """
6
7 import sys
8 import nose.tools as nt
9 from textwrap import dedent
10 from unittest import TestCase
11
12 ip = get_ipython()
13 iprc = lambda x: ip.run_cell(dedent(x))
14
15 if sys.version_info > (3,5):
16 from IPython.core.async_helpers import _should_be_async
17
18 class AsyncTest(TestCase):
19
20 def test_should_be_async(self):
21 nt.assert_false(_should_be_async("False"))
22 nt.assert_true(_should_be_async("await bar()"))
23 nt.assert_true(_should_be_async("x = await bar()"))
24 nt.assert_false(_should_be_async(dedent("""
25 async def awaitable():
26 pass
27 """)))
28
29 def test_execute(self):
30 iprc("""
31 import asyncio
32 await asyncio.sleep(0.001)
33 """)
34
35 def test_autoawait(self):
36 ip.run_cell('%autoawait False')
37 ip.run_cell('%autoawait True')
38 iprc('''
39 from asyncio import sleep
40 await.sleep(0.1)
41 ''')
42
43 def test_autoawait_curio(self):
44 ip.run_cell('%autoawait curio')
45
46 def test_autoawait_trio(self):
47 ip.run_cell('%autoawait trio')
48
49 def tearDown(self):
50 ip.loop_runner = 'asyncio'
51
52
@@ -0,0 +1,186 b''
1
2 .. autoawait:
3
4 Asynchronous in REPL: Autoawait
5 ===============================
6
7 Starting with IPython 6.0, and when user Python 3.6 and above, IPython offer the
8 ability to run asynchronous code from the REPL. constructs which are
9 :exc:`SyntaxError` s in the Python REPL can be used seamlessly in IPython.
10
11 When a supported libray is used, IPython will automatically `await` Futures
12 and Coroutines in the REPL. This will happen if an :ref:`await <await>` (or `async`) is
13 use at top level scope, or if any structure valid only in `async def
14 <https://docs.python.org/3/reference/compound_stmts.html#async-def>`_ function
15 context are present. For example, the following being a syntax error in the
16 Python REPL::
17
18 Python 3.6.0
19 [GCC 4.2.1]
20 Type "help", "copyright", "credits" or "license" for more information.
21 >>> import aiohttp
22 >>> result = aiohttp.get('https://api.github.com')
23 >>> response = await result
24 File "<stdin>", line 1
25 response = await result
26 ^
27 SyntaxError: invalid syntax
28
29 Should behave as expected in the IPython REPL::
30
31 Python 3.6.0
32 Type 'copyright', 'credits' or 'license' for more information
33 IPython 6.0.0.dev -- An enhanced Interactive Python. Type '?' for help.
34
35 In [1]: import aiohttp
36 ...: result = aiohttp.get('https://api.github.com')
37
38 In [2]: response = await result
39 <pause for a few 100s ms>
40
41 In [3]: await response.json()
42 Out[3]:
43 {'authorizations_url': 'https://api.github.com/authorizations',
44 'code_search_url': 'https://api.github.com/search/code?q={query}...',
45 ...
46 }
47
48
49 You can use the ``c.InteractiveShell.autoawait`` configuration option and set it
50 to :any:`False` to deactivate automatic wrapping of asynchronous code. You can also
51 use the :magic:`%autoawait` magic to toggle the behavior at runtime::
52
53 In [1]: %autoawait False
54
55 In [2]: %autoawait
56 IPython autoawait is `Off`, and set to use `IPython.core.interactiveshell._asyncio_runner`
57
58
59
60 By default IPython will assume integration with Python's provided
61 :mod:`asyncio`, but integration with other libraries is provided. In particular
62 we provide experimental integration with the ``curio`` and ``trio`` library.
63
64 You can switch current integration by using the
65 ``c.InteractiveShell.loop_runner`` option or the ``autoawait <name
66 integration>`` magic.
67
68 For example::
69
70 In [1]: %autoawait trio
71
72 In [2]: import trio
73
74 In [3]: async def child(i):
75 ...: print(" child %s goes to sleep"%i)
76 ...: await trio.sleep(2)
77 ...: print(" child %s wakes up"%i)
78
79 In [4]: print('parent start')
80 ...: async with trio.open_nursery() as n:
81 ...: for i in range(5):
82 ...: n.spawn(child, i)
83 ...: print('parent end')
84 parent start
85 child 2 goes to sleep
86 child 0 goes to sleep
87 child 3 goes to sleep
88 child 1 goes to sleep
89 child 4 goes to sleep
90 <about 2 seconds pause>
91 child 2 wakes up
92 child 1 wakes up
93 child 0 wakes up
94 child 3 wakes up
95 child 4 wakes up
96 parent end
97
98
99 In the above example, ``async with`` at top level scope is a syntax error in
100 Python.
101
102 Using this mode can have unexpected consequences if used in interaction with
103 other features of IPython and various registered extensions. In particular if you
104 are a direct or indirect user of the AST transformers, these may not apply to
105 your code.
106
107 The default loop, or runner does not run in the background, so top level
108 asynchronous code must finish for the REPL to allow you to enter more code. As
109 with usual Python semantic, the awaitables are started only when awaited for the
110 first time. That is to say, in first example, no network request is done between
111 ``In[1]`` and ``In[2]``.
112
113
114 Internals
115 =========
116
117 As running asynchronous code is not supported in interactive REPL as of Python
118 3.6 we have to rely to a number of complex workaround to allow this to happen.
119 It is interesting to understand how this works in order to understand potential
120 bugs, or provide a custom runner.
121
122 Among the many approaches that are at our disposition, we find only one that
123 suited out need. Under the hood we :ct the code object from a async-def function
124 and run it in global namesapace after modifying the ``__code__`` object.::
125
126 async def inner_async():
127 locals().update(**global_namespace)
128 #
129 # here is user code
130 #
131 return last_user_statement
132 codeobj = modify(inner_async.__code__)
133 coroutine = eval(codeobj, user_ns)
134 display(loop_runner(coroutine))
135
136
137
138 The first thing you'll notice is that unlike classical ``exec``, there is only
139 one name space. Second, user code runs in a function scope, and not a module
140 scope.
141
142 On top of the above there are significant modification to the AST of
143 ``function``, and ``loop_runner`` can be arbitrary complex. So there is a
144 significant overhead to this kind of code.
145
146 By default the generated coroutine function will be consumed by Asyncio's
147 ``loop_runner = asyncio.get_evenloop().run_until_complete()`` method. It is
148 though possible to provide your own.
149
150 A loop runner is a *synchronous* function responsible from running a coroutine
151 object.
152
153 The runner is responsible from ensuring that ``coroutine`` run to completion,
154 and should return the result of executing the coroutine. Let's write a
155 runner for ``trio`` that print a message when used as an exercise, ``trio`` is
156 special as it usually prefer to run a function object and make a coroutine by
157 itself, we can get around this limitation by wrapping it in an async-def without
158 parameters and passing this value to ``trio``::
159
160
161 In [1]: import trio
162 ...: from types import CoroutineType
163 ...:
164 ...: def trio_runner(coro:CoroutineType):
165 ...: print('running asynchronous code')
166 ...: async def corowrap(coro):
167 ...: return await coro
168 ...: return trio.run(corowrap, coro)
169
170 We can set it up by passing it to ``%autoawait``::
171
172 In [2]: %autoawait trio_runner
173
174 In [3]: async def async_hello(name):
175 ...: await trio.sleep(1)
176 ...: print(f'Hello {name} world !')
177 ...: await trio.sleep(1)
178
179 In [4]: await async_hello('async')
180 running asynchronous code
181 Hello async world !
182
183
184 Asynchronous programming in python (and in particular in the REPL) is still a
185 relatively young subject. Feel free to contribute improvements to this codebase
186 and give us feedback.
@@ -0,0 +1,55 b''
1 Await REPL
2 ----------
3
4 :ghpull:`10390` introduced the ability to ``await`` Futures and
5 Coroutines in the REPL. For example::
6
7 Python 3.6.0
8 Type 'copyright', 'credits' or 'license' for more information
9 IPython 6.0.0.dev -- An enhanced Interactive Python. Type '?' for help.
10
11 In [1]: import aiohttp
12 ...: result = aiohttp.get('https://api.github.com')
13
14 In [2]: response = await result
15 <pause for a few 100s ms>
16
17 In [3]: await response.json()
18 Out[3]:
19 {'authorizations_url': 'https://api.github.com/authorizations',
20 'code_search_url': 'https://api.github.com/search/code?q={query}{&page,per_page,sort,order}',
21 ...
22 }
23
24
25 Integration is by default with `asyncio`, but other libraries can be configured,
26 like ``curio`` or ``trio``, to improve concurrency in the REPL::
27
28 In [1]: %autoawait trio
29
30 In [2]: import trio
31
32 In [3]: async def child(i):
33 ...: print(" child %s goes to sleep"%i)
34 ...: await trio.sleep(2)
35 ...: print(" child %s wakes up"%i)
36
37 In [4]: print('parent start')
38 ...: async with trio.open_nursery() as n:
39 ...: for i in range(3):
40 ...: n.spawn(child, i)
41 ...: print('parent end')
42 parent start
43 child 2 goes to sleep
44 child 0 goes to sleep
45 child 1 goes to sleep
46 <about 2 seconds pause>
47 child 2 wakes up
48 child 1 wakes up
49 child 0 wakes up
50 parent end
51
52 See :ref:`autoawait` for more information.
53
54
55
@@ -1,3344 +1,3561 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 asyncio
16 import atexit
17 import atexit
17 import builtins as builtin_mod
18 import builtins as builtin_mod
18 import functools
19 import functools
19 import os
20 import os
20 import re
21 import re
21 import runpy
22 import runpy
22 import sys
23 import sys
23 import tempfile
24 import tempfile
24 import traceback
25 import traceback
25 import types
26 import types
26 import subprocess
27 import subprocess
27 import warnings
28 import warnings
28 from io import open as io_open
29 from io import open as io_open
29
30
30 from pickleshare import PickleShareDB
31 from pickleshare import PickleShareDB
31
32
32 from traitlets.config.configurable import SingletonConfigurable
33 from traitlets.config.configurable import SingletonConfigurable
34 from traitlets.utils.importstring import import_item
33 from IPython.core import oinspect
35 from IPython.core import oinspect
34 from IPython.core import magic
36 from IPython.core import magic
35 from IPython.core import page
37 from IPython.core import page
36 from IPython.core import prefilter
38 from IPython.core import prefilter
37 from IPython.core import ultratb
39 from IPython.core import ultratb
38 from IPython.core.alias import Alias, AliasManager
40 from IPython.core.alias import Alias, AliasManager
39 from IPython.core.autocall import ExitAutocall
41 from IPython.core.autocall import ExitAutocall
40 from IPython.core.builtin_trap import BuiltinTrap
42 from IPython.core.builtin_trap import BuiltinTrap
41 from IPython.core.events import EventManager, available_events
43 from IPython.core.events import EventManager, available_events
42 from IPython.core.compilerop import CachingCompiler, check_linecache_ipython
44 from IPython.core.compilerop import CachingCompiler, check_linecache_ipython
43 from IPython.core.debugger import Pdb
45 from IPython.core.debugger import Pdb
44 from IPython.core.display_trap import DisplayTrap
46 from IPython.core.display_trap import DisplayTrap
45 from IPython.core.displayhook import DisplayHook
47 from IPython.core.displayhook import DisplayHook
46 from IPython.core.displaypub import DisplayPublisher
48 from IPython.core.displaypub import DisplayPublisher
47 from IPython.core.error import InputRejected, UsageError
49 from IPython.core.error import InputRejected, UsageError
48 from IPython.core.extensions import ExtensionManager
50 from IPython.core.extensions import ExtensionManager
49 from IPython.core.formatters import DisplayFormatter
51 from IPython.core.formatters import DisplayFormatter
50 from IPython.core.history import HistoryManager
52 from IPython.core.history import HistoryManager
51 from IPython.core.inputsplitter import ESC_MAGIC, ESC_MAGIC2
53 from IPython.core.inputsplitter import ESC_MAGIC, ESC_MAGIC2
52 from IPython.core.logger import Logger
54 from IPython.core.logger import Logger
53 from IPython.core.macro import Macro
55 from IPython.core.macro import Macro
54 from IPython.core.payload import PayloadManager
56 from IPython.core.payload import PayloadManager
55 from IPython.core.prefilter import PrefilterManager
57 from IPython.core.prefilter import PrefilterManager
56 from IPython.core.profiledir import ProfileDir
58 from IPython.core.profiledir import ProfileDir
57 from IPython.core.usage import default_banner
59 from IPython.core.usage import default_banner
58 from IPython.display import display
60 from IPython.display import display
59 from IPython.testing.skipdoctest import skip_doctest
61 from IPython.testing.skipdoctest import skip_doctest
60 from IPython.utils import PyColorize
62 from IPython.utils import PyColorize
61 from IPython.utils import io
63 from IPython.utils import io
62 from IPython.utils import py3compat
64 from IPython.utils import py3compat
63 from IPython.utils import openpy
65 from IPython.utils import openpy
64 from IPython.utils.decorators import undoc
66 from IPython.utils.decorators import undoc
65 from IPython.utils.io import ask_yes_no
67 from IPython.utils.io import ask_yes_no
66 from IPython.utils.ipstruct import Struct
68 from IPython.utils.ipstruct import Struct
67 from IPython.paths import get_ipython_dir
69 from IPython.paths import get_ipython_dir
68 from IPython.utils.path import get_home_dir, get_py_filename, ensure_dir_exists
70 from IPython.utils.path import get_home_dir, get_py_filename, ensure_dir_exists
69 from IPython.utils.process import system, getoutput
71 from IPython.utils.process import system, getoutput
70 from IPython.utils.strdispatch import StrDispatch
72 from IPython.utils.strdispatch import StrDispatch
71 from IPython.utils.syspathcontext import prepended_to_syspath
73 from IPython.utils.syspathcontext import prepended_to_syspath
72 from IPython.utils.text import format_screen, LSString, SList, DollarFormatter
74 from IPython.utils.text import format_screen, LSString, SList, DollarFormatter
73 from IPython.utils.tempdir import TemporaryDirectory
75 from IPython.utils.tempdir import TemporaryDirectory
74 from traitlets import (
76 from traitlets import (
75 Integer, Bool, CaselessStrEnum, Enum, List, Dict, Unicode, Instance, Type,
77 Integer, Bool, CaselessStrEnum, Enum, List, Dict, Unicode, Instance, Type,
76 observe, default,
78 observe, default, validate, Any
77 )
79 )
78 from warnings import warn
80 from warnings import warn
79 from logging import error
81 from logging import error
80 import IPython.core.hooks
82 import IPython.core.hooks
81
83
82 from typing import List as ListType
84 from typing import List as ListType
83 from ast import AST
85 from ast import AST
84
86
85 # NoOpContext is deprecated, but ipykernel imports it from here.
87 # NoOpContext is deprecated, but ipykernel imports it from here.
86 # See https://github.com/ipython/ipykernel/issues/157
88 # See https://github.com/ipython/ipykernel/issues/157
87 from IPython.utils.contexts import NoOpContext
89 from IPython.utils.contexts import NoOpContext
88
90
89 try:
91 try:
90 import docrepr.sphinxify as sphx
92 import docrepr.sphinxify as sphx
91
93
92 def sphinxify(doc):
94 def sphinxify(doc):
93 with TemporaryDirectory() as dirname:
95 with TemporaryDirectory() as dirname:
94 return {
96 return {
95 'text/html': sphx.sphinxify(doc, dirname),
97 'text/html': sphx.sphinxify(doc, dirname),
96 'text/plain': doc
98 'text/plain': doc
97 }
99 }
98 except ImportError:
100 except ImportError:
99 sphinxify = None
101 sphinxify = None
100
102
101
103
102 class ProvisionalWarning(DeprecationWarning):
104 class ProvisionalWarning(DeprecationWarning):
103 """
105 """
104 Warning class for unstable features
106 Warning class for unstable features
105 """
107 """
106 pass
108 pass
107
109
108 if sys.version_info > (3,6):
110 if sys.version_info > (3,6):
109 _assign_nodes = (ast.AugAssign, ast.AnnAssign, ast.Assign)
111 _assign_nodes = (ast.AugAssign, ast.AnnAssign, ast.Assign)
110 _single_targets_nodes = (ast.AugAssign, ast.AnnAssign)
112 _single_targets_nodes = (ast.AugAssign, ast.AnnAssign)
111 else:
113 else:
112 _assign_nodes = (ast.AugAssign, ast.Assign )
114 _assign_nodes = (ast.AugAssign, ast.Assign )
113 _single_targets_nodes = (ast.AugAssign, )
115 _single_targets_nodes = (ast.AugAssign, )
114
116
115 #-----------------------------------------------------------------------------
117 #-----------------------------------------------------------------------------
118 # Await Helpers
119 #-----------------------------------------------------------------------------
120
121 def removed_co_newlocals(function:types.FunctionType) -> types.FunctionType:
122 """Return a function that do not create a new local scope.
123
124 Given a function, create a clone of this function where the co_newlocal flag
125 has been removed, making this function code actually run in the sourounding
126 scope.
127
128 We need this in order to run asynchronous code in user level namespace.
129 """
130 from types import CodeType, FunctionType
131 CO_NEWLOCALS = 0x0002
132 code = function.__code__
133 new_code = CodeType(
134 code.co_argcount,
135 code.co_kwonlyargcount,
136 code.co_nlocals,
137 code.co_stacksize,
138 code.co_flags & ~CO_NEWLOCALS,
139 code.co_code,
140 code.co_consts,
141 code.co_names,
142 code.co_varnames,
143 code.co_filename,
144 code.co_name,
145 code.co_firstlineno,
146 code.co_lnotab,
147 code.co_freevars,
148 code.co_cellvars
149 )
150 return FunctionType(new_code, globals(), function.__name__, function.__defaults__)
151
152
153 if sys.version_info > (3,5):
154 from .async_helpers import (_asyncio_runner, _curio_runner, _trio_runner,
155 _should_be_async, _asyncify
156 )
157 else :
158 _asyncio_runner = _curio_runner = _trio_runner = None
159
160 def _should_be_async(whatever:str)->bool:
161 return False
162
163
164 def _ast_asyncify(cell:str, wrapper_name:str) -> ast.Module:
165 """
166 Parse a cell with top-level await and modify the AST to be able to run it later.
167
168 Parameter
169 ---------
170
171 cell: str
172 The code cell to asyncronify
173 wrapper_name: str
174 The name of the function to be used to wrap the passed `cell`. It is
175 advised to **not** use a python identifier in order to not pollute the
176 global namespace in which the function will be ran.
177
178 Return
179 ------
180
181 A module object AST containing **one** function named `wrapper_name`.
182
183 The given code is wrapped in a async-def function, parsed into an AST, and
184 the resulting function definition AST is modified to return the last
185 expression.
186
187 The last expression or await node is moved into a return statement at the
188 end of the function, and removed from its original location. If the last
189 node is not Expr or Await nothing is done.
190
191 The function `__code__` will need to be later modified (by
192 ``removed_co_newlocals``) in a subsequent step to not create new `locals()`
193 meaning that the local and global scope are the same, ie as if the body of
194 the function was at module level.
195
196 Lastly a call to `locals()` is made just before the last expression of the
197 function, or just after the last assignment or statement to make sure the
198 global dict is updated as python function work with a local fast cache which
199 is updated only on `local()` calls.
200 """
201
202 from ast import Expr, Await, Return
203 tree = ast.parse(_asyncify(cell))
204
205 function_def = tree.body[0]
206 function_def.name = wrapper_name
207 try_block = function_def.body[0]
208 lastexpr = try_block.body[-1]
209 if isinstance(lastexpr, (Expr, Await)):
210 try_block.body[-1] = Return(lastexpr.value)
211 ast.fix_missing_locations(tree)
212 return tree
213 #-----------------------------------------------------------------------------
116 # Globals
214 # Globals
117 #-----------------------------------------------------------------------------
215 #-----------------------------------------------------------------------------
118
216
119 # compiled regexps for autoindent management
217 # compiled regexps for autoindent management
120 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
218 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
121
219
122 #-----------------------------------------------------------------------------
220 #-----------------------------------------------------------------------------
123 # Utilities
221 # Utilities
124 #-----------------------------------------------------------------------------
222 #-----------------------------------------------------------------------------
125
223
126 @undoc
224 @undoc
127 def softspace(file, newvalue):
225 def softspace(file, newvalue):
128 """Copied from code.py, to remove the dependency"""
226 """Copied from code.py, to remove the dependency"""
129
227
130 oldvalue = 0
228 oldvalue = 0
131 try:
229 try:
132 oldvalue = file.softspace
230 oldvalue = file.softspace
133 except AttributeError:
231 except AttributeError:
134 pass
232 pass
135 try:
233 try:
136 file.softspace = newvalue
234 file.softspace = newvalue
137 except (AttributeError, TypeError):
235 except (AttributeError, TypeError):
138 # "attribute-less object" or "read-only attributes"
236 # "attribute-less object" or "read-only attributes"
139 pass
237 pass
140 return oldvalue
238 return oldvalue
141
239
142 @undoc
240 @undoc
143 def no_op(*a, **kw):
241 def no_op(*a, **kw):
144 pass
242 pass
145
243
146
244
147 class SpaceInInput(Exception): pass
245 class SpaceInInput(Exception): pass
148
246
149
247
150 def get_default_colors():
248 def get_default_colors():
151 "DEPRECATED"
249 "DEPRECATED"
152 warn('get_default_color is deprecated since IPython 5.0, and returns `Neutral` on all platforms.',
250 warn('get_default_color is deprecated since IPython 5.0, and returns `Neutral` on all platforms.',
153 DeprecationWarning, stacklevel=2)
251 DeprecationWarning, stacklevel=2)
154 return 'Neutral'
252 return 'Neutral'
155
253
156
254
157 class SeparateUnicode(Unicode):
255 class SeparateUnicode(Unicode):
158 r"""A Unicode subclass to validate separate_in, separate_out, etc.
256 r"""A Unicode subclass to validate separate_in, separate_out, etc.
159
257
160 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
258 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
161 """
259 """
162
260
163 def validate(self, obj, value):
261 def validate(self, obj, value):
164 if value == '0': value = ''
262 if value == '0': value = ''
165 value = value.replace('\\n','\n')
263 value = value.replace('\\n','\n')
166 return super(SeparateUnicode, self).validate(obj, value)
264 return super(SeparateUnicode, self).validate(obj, value)
167
265
168
266
169 @undoc
267 @undoc
170 class DummyMod(object):
268 class DummyMod(object):
171 """A dummy module used for IPython's interactive module when
269 """A dummy module used for IPython's interactive module when
172 a namespace must be assigned to the module's __dict__."""
270 a namespace must be assigned to the module's __dict__."""
173 __spec__ = None
271 __spec__ = None
174
272
175
273
176 class ExecutionInfo(object):
274 class ExecutionInfo(object):
177 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
275 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
178
276
179 Stores information about what is going to happen.
277 Stores information about what is going to happen.
180 """
278 """
181 raw_cell = None
279 raw_cell = None
182 store_history = False
280 store_history = False
183 silent = False
281 silent = False
184 shell_futures = True
282 shell_futures = True
185
283
186 def __init__(self, raw_cell, store_history, silent, shell_futures):
284 def __init__(self, raw_cell, store_history, silent, shell_futures):
187 self.raw_cell = raw_cell
285 self.raw_cell = raw_cell
188 self.store_history = store_history
286 self.store_history = store_history
189 self.silent = silent
287 self.silent = silent
190 self.shell_futures = shell_futures
288 self.shell_futures = shell_futures
191
289
192 def __repr__(self):
290 def __repr__(self):
193 name = self.__class__.__qualname__
291 name = self.__class__.__qualname__
194 raw_cell = ((self.raw_cell[:50] + '..')
292 raw_cell = ((self.raw_cell[:50] + '..')
195 if len(self.raw_cell) > 50 else self.raw_cell)
293 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>' %\
294 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)
295 (name, id(self), raw_cell, self.store_history, self.silent, self.shell_futures)
198
296
199
297
200 class ExecutionResult(object):
298 class ExecutionResult(object):
201 """The result of a call to :meth:`InteractiveShell.run_cell`
299 """The result of a call to :meth:`InteractiveShell.run_cell`
202
300
203 Stores information about what took place.
301 Stores information about what took place.
204 """
302 """
205 execution_count = None
303 execution_count = None
206 error_before_exec = None
304 error_before_exec = None
207 error_in_exec = None
305 error_in_exec = None
208 info = None
306 info = None
209 result = None
307 result = None
210
308
211 def __init__(self, info):
309 def __init__(self, info):
212 self.info = info
310 self.info = info
213
311
214 @property
312 @property
215 def success(self):
313 def success(self):
216 return (self.error_before_exec is None) and (self.error_in_exec is None)
314 return (self.error_before_exec is None) and (self.error_in_exec is None)
217
315
218 def raise_error(self):
316 def raise_error(self):
219 """Reraises error if `success` is `False`, otherwise does nothing"""
317 """Reraises error if `success` is `False`, otherwise does nothing"""
220 if self.error_before_exec is not None:
318 if self.error_before_exec is not None:
221 raise self.error_before_exec
319 raise self.error_before_exec
222 if self.error_in_exec is not None:
320 if self.error_in_exec is not None:
223 raise self.error_in_exec
321 raise self.error_in_exec
224
322
225 def __repr__(self):
323 def __repr__(self):
226 name = self.__class__.__qualname__
324 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>' %\
325 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))
326 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))
229
327
230
328
231 class InteractiveShell(SingletonConfigurable):
329 class InteractiveShell(SingletonConfigurable):
232 """An enhanced, interactive shell for Python."""
330 """An enhanced, interactive shell for Python."""
233
331
234 _instance = None
332 _instance = None
235
333
236 ast_transformers = List([], help=
334 ast_transformers = List([], help=
237 """
335 """
238 A list of ast.NodeTransformer subclass instances, which will be applied
336 A list of ast.NodeTransformer subclass instances, which will be applied
239 to user input before code is run.
337 to user input before code is run.
240 """
338 """
241 ).tag(config=True)
339 ).tag(config=True)
242
340
243 autocall = Enum((0,1,2), default_value=0, help=
341 autocall = Enum((0,1,2), default_value=0, help=
244 """
342 """
245 Make IPython automatically call any callable object even if you didn't
343 Make IPython automatically call any callable object even if you didn't
246 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
344 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
247 automatically. The value can be '0' to disable the feature, '1' for
345 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
346 '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
347 arguments on the line, and '2' for 'full' autocall, where all callable
250 objects are automatically called (even if no arguments are present).
348 objects are automatically called (even if no arguments are present).
251 """
349 """
252 ).tag(config=True)
350 ).tag(config=True)
253 # TODO: remove all autoindent logic and put into frontends.
351 # TODO: remove all autoindent logic and put into frontends.
254 # We can't do this yet because even runlines uses the autoindent.
352 # We can't do this yet because even runlines uses the autoindent.
255 autoindent = Bool(True, help=
353 autoindent = Bool(True, help=
256 """
354 """
257 Autoindent IPython code entered interactively.
355 Autoindent IPython code entered interactively.
258 """
356 """
259 ).tag(config=True)
357 ).tag(config=True)
260
358
359 autoawait = Bool(True, help=
360 """
361 Automatically run await statement in the top level repl.
362 """
363 ).tag(config=True)
364
365 loop_runner_map ={
366 'asyncio':_asyncio_runner,
367 'curio':_curio_runner,
368 'trio':_trio_runner,
369 }
370
371 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",
372 allow_none=True,
373 help="""Select the loop runner that will be used to execute top-level asynchronous code"""
374 ).tag(config=True)
375
376 @default('loop_runner')
377 def _default_loop_runner(self):
378 return import_item("IPython.core.interactiveshell._asyncio_runner")
379
380 @validate('loop_runner')
381 def _import_runner(self, proposal):
382 if isinstance(proposal.value, str):
383 if proposal.value in self.loop_runner_map:
384 return self.loop_runner_map[proposal.value]
385 runner = import_item(proposal.value)
386 if not callable(runner):
387 raise ValueError('loop_runner must be callable')
388 return runner
389 if not callable(proposal.value):
390 raise ValueError('loop_runner must be callable')
391 return proposal.value
392
261 automagic = Bool(True, help=
393 automagic = Bool(True, help=
262 """
394 """
263 Enable magic commands to be called without the leading %.
395 Enable magic commands to be called without the leading %.
264 """
396 """
265 ).tag(config=True)
397 ).tag(config=True)
266
398
267 banner1 = Unicode(default_banner,
399 banner1 = Unicode(default_banner,
268 help="""The part of the banner to be printed before the profile"""
400 help="""The part of the banner to be printed before the profile"""
269 ).tag(config=True)
401 ).tag(config=True)
270 banner2 = Unicode('',
402 banner2 = Unicode('',
271 help="""The part of the banner to be printed after the profile"""
403 help="""The part of the banner to be printed after the profile"""
272 ).tag(config=True)
404 ).tag(config=True)
273
405
274 cache_size = Integer(1000, help=
406 cache_size = Integer(1000, help=
275 """
407 """
276 Set the size of the output cache. The default is 1000, you can
408 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
409 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
410 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
411 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
412 issued). This limit is defined because otherwise you'll spend more
281 time re-flushing a too small cache than working
413 time re-flushing a too small cache than working
282 """
414 """
283 ).tag(config=True)
415 ).tag(config=True)
284 color_info = Bool(True, help=
416 color_info = Bool(True, help=
285 """
417 """
286 Use colors for displaying information about objects. Because this
418 Use colors for displaying information about objects. Because this
287 information is passed through a pager (like 'less'), and some pagers
419 information is passed through a pager (like 'less'), and some pagers
288 get confused with color codes, this capability can be turned off.
420 get confused with color codes, this capability can be turned off.
289 """
421 """
290 ).tag(config=True)
422 ).tag(config=True)
291 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
423 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
292 default_value='Neutral',
424 default_value='Neutral',
293 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
425 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
294 ).tag(config=True)
426 ).tag(config=True)
295 debug = Bool(False).tag(config=True)
427 debug = Bool(False).tag(config=True)
296 disable_failing_post_execute = Bool(False,
428 disable_failing_post_execute = Bool(False,
297 help="Don't call post-execute functions that have failed in the past."
429 help="Don't call post-execute functions that have failed in the past."
298 ).tag(config=True)
430 ).tag(config=True)
299 display_formatter = Instance(DisplayFormatter, allow_none=True)
431 display_formatter = Instance(DisplayFormatter, allow_none=True)
300 displayhook_class = Type(DisplayHook)
432 displayhook_class = Type(DisplayHook)
301 display_pub_class = Type(DisplayPublisher)
433 display_pub_class = Type(DisplayPublisher)
302
434
303 sphinxify_docstring = Bool(False, help=
435 sphinxify_docstring = Bool(False, help=
304 """
436 """
305 Enables rich html representation of docstrings. (This requires the
437 Enables rich html representation of docstrings. (This requires the
306 docrepr module).
438 docrepr module).
307 """).tag(config=True)
439 """).tag(config=True)
308
440
309 @observe("sphinxify_docstring")
441 @observe("sphinxify_docstring")
310 def _sphinxify_docstring_changed(self, change):
442 def _sphinxify_docstring_changed(self, change):
311 if change['new']:
443 if change['new']:
312 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
444 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
313
445
314 enable_html_pager = Bool(False, help=
446 enable_html_pager = Bool(False, help=
315 """
447 """
316 (Provisional API) enables html representation in mime bundles sent
448 (Provisional API) enables html representation in mime bundles sent
317 to pagers.
449 to pagers.
318 """).tag(config=True)
450 """).tag(config=True)
319
451
320 @observe("enable_html_pager")
452 @observe("enable_html_pager")
321 def _enable_html_pager_changed(self, change):
453 def _enable_html_pager_changed(self, change):
322 if change['new']:
454 if change['new']:
323 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
455 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
324
456
325 data_pub_class = None
457 data_pub_class = None
326
458
327 exit_now = Bool(False)
459 exit_now = Bool(False)
328 exiter = Instance(ExitAutocall)
460 exiter = Instance(ExitAutocall)
329 @default('exiter')
461 @default('exiter')
330 def _exiter_default(self):
462 def _exiter_default(self):
331 return ExitAutocall(self)
463 return ExitAutocall(self)
332 # Monotonically increasing execution counter
464 # Monotonically increasing execution counter
333 execution_count = Integer(1)
465 execution_count = Integer(1)
334 filename = Unicode("<ipython console>")
466 filename = Unicode("<ipython console>")
335 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
467 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
336
468
337 # Input splitter, to transform input line by line and detect when a block
469 # Input splitter, to transform input line by line and detect when a block
338 # is ready to be executed.
470 # is ready to be executed.
339 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
471 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
340 (), {'line_input_checker': True})
472 (), {'line_input_checker': True})
341
473
342 # This InputSplitter instance is used to transform completed cells before
474 # This InputSplitter instance is used to transform completed cells before
343 # running them. It allows cell magics to contain blank lines.
475 # running them. It allows cell magics to contain blank lines.
344 input_transformer_manager = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
476 input_transformer_manager = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
345 (), {'line_input_checker': False})
477 (), {'line_input_checker': False})
346
478
347 logstart = Bool(False, help=
479 logstart = Bool(False, help=
348 """
480 """
349 Start logging to the default log file in overwrite mode.
481 Start logging to the default log file in overwrite mode.
350 Use `logappend` to specify a log file to **append** logs to.
482 Use `logappend` to specify a log file to **append** logs to.
351 """
483 """
352 ).tag(config=True)
484 ).tag(config=True)
353 logfile = Unicode('', help=
485 logfile = Unicode('', help=
354 """
486 """
355 The name of the logfile to use.
487 The name of the logfile to use.
356 """
488 """
357 ).tag(config=True)
489 ).tag(config=True)
358 logappend = Unicode('', help=
490 logappend = Unicode('', help=
359 """
491 """
360 Start logging to the given file in append mode.
492 Start logging to the given file in append mode.
361 Use `logfile` to specify a log file to **overwrite** logs to.
493 Use `logfile` to specify a log file to **overwrite** logs to.
362 """
494 """
363 ).tag(config=True)
495 ).tag(config=True)
364 object_info_string_level = Enum((0,1,2), default_value=0,
496 object_info_string_level = Enum((0,1,2), default_value=0,
365 ).tag(config=True)
497 ).tag(config=True)
366 pdb = Bool(False, help=
498 pdb = Bool(False, help=
367 """
499 """
368 Automatically call the pdb debugger after every exception.
500 Automatically call the pdb debugger after every exception.
369 """
501 """
370 ).tag(config=True)
502 ).tag(config=True)
371 display_page = Bool(False,
503 display_page = Bool(False,
372 help="""If True, anything that would be passed to the pager
504 help="""If True, anything that would be passed to the pager
373 will be displayed as regular output instead."""
505 will be displayed as regular output instead."""
374 ).tag(config=True)
506 ).tag(config=True)
375
507
376 # deprecated prompt traits:
508 # deprecated prompt traits:
377
509
378 prompt_in1 = Unicode('In [\\#]: ',
510 prompt_in1 = Unicode('In [\\#]: ',
379 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
511 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
380 ).tag(config=True)
512 ).tag(config=True)
381 prompt_in2 = Unicode(' .\\D.: ',
513 prompt_in2 = Unicode(' .\\D.: ',
382 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
514 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
383 ).tag(config=True)
515 ).tag(config=True)
384 prompt_out = Unicode('Out[\\#]: ',
516 prompt_out = Unicode('Out[\\#]: ',
385 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
517 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
386 ).tag(config=True)
518 ).tag(config=True)
387 prompts_pad_left = Bool(True,
519 prompts_pad_left = Bool(True,
388 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
520 help="Deprecated since IPython 4.0 and ignored since 5.0, set TerminalInteractiveShell.prompts object directly."
389 ).tag(config=True)
521 ).tag(config=True)
390
522
391 @observe('prompt_in1', 'prompt_in2', 'prompt_out', 'prompt_pad_left')
523 @observe('prompt_in1', 'prompt_in2', 'prompt_out', 'prompt_pad_left')
392 def _prompt_trait_changed(self, change):
524 def _prompt_trait_changed(self, change):
393 name = change['name']
525 name = change['name']
394 warn("InteractiveShell.{name} is deprecated since IPython 4.0"
526 warn("InteractiveShell.{name} is deprecated since IPython 4.0"
395 " and ignored since 5.0, set TerminalInteractiveShell.prompts"
527 " and ignored since 5.0, set TerminalInteractiveShell.prompts"
396 " object directly.".format(name=name))
528 " object directly.".format(name=name))
397
529
398 # protect against weird cases where self.config may not exist:
530 # protect against weird cases where self.config may not exist:
399
531
400 show_rewritten_input = Bool(True,
532 show_rewritten_input = Bool(True,
401 help="Show rewritten input, e.g. for autocall."
533 help="Show rewritten input, e.g. for autocall."
402 ).tag(config=True)
534 ).tag(config=True)
403
535
404 quiet = Bool(False).tag(config=True)
536 quiet = Bool(False).tag(config=True)
405
537
406 history_length = Integer(10000,
538 history_length = Integer(10000,
407 help='Total length of command history'
539 help='Total length of command history'
408 ).tag(config=True)
540 ).tag(config=True)
409
541
410 history_load_length = Integer(1000, help=
542 history_load_length = Integer(1000, help=
411 """
543 """
412 The number of saved history entries to be loaded
544 The number of saved history entries to be loaded
413 into the history buffer at startup.
545 into the history buffer at startup.
414 """
546 """
415 ).tag(config=True)
547 ).tag(config=True)
416
548
417 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
549 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
418 default_value='last_expr',
550 default_value='last_expr',
419 help="""
551 help="""
420 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
552 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
421 which nodes should be run interactively (displaying output from expressions).
553 which nodes should be run interactively (displaying output from expressions).
422 """
554 """
423 ).tag(config=True)
555 ).tag(config=True)
424
556
425 # TODO: this part of prompt management should be moved to the frontends.
557 # TODO: this part of prompt management should be moved to the frontends.
426 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
558 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
427 separate_in = SeparateUnicode('\n').tag(config=True)
559 separate_in = SeparateUnicode('\n').tag(config=True)
428 separate_out = SeparateUnicode('').tag(config=True)
560 separate_out = SeparateUnicode('').tag(config=True)
429 separate_out2 = SeparateUnicode('').tag(config=True)
561 separate_out2 = SeparateUnicode('').tag(config=True)
430 wildcards_case_sensitive = Bool(True).tag(config=True)
562 wildcards_case_sensitive = Bool(True).tag(config=True)
431 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
563 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
432 default_value='Context',
564 default_value='Context',
433 help="Switch modes for the IPython exception handlers."
565 help="Switch modes for the IPython exception handlers."
434 ).tag(config=True)
566 ).tag(config=True)
435
567
436 # Subcomponents of InteractiveShell
568 # Subcomponents of InteractiveShell
437 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
569 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
438 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
570 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
439 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
571 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
440 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
572 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
441 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
573 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
442 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
574 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
443 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
575 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
444 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
576 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
445
577
446 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
578 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
447 @property
579 @property
448 def profile(self):
580 def profile(self):
449 if self.profile_dir is not None:
581 if self.profile_dir is not None:
450 name = os.path.basename(self.profile_dir.location)
582 name = os.path.basename(self.profile_dir.location)
451 return name.replace('profile_','')
583 return name.replace('profile_','')
452
584
453
585
454 # Private interface
586 # Private interface
455 _post_execute = Dict()
587 _post_execute = Dict()
456
588
457 # Tracks any GUI loop loaded for pylab
589 # Tracks any GUI loop loaded for pylab
458 pylab_gui_select = None
590 pylab_gui_select = None
459
591
460 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
592 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
461
593
462 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
594 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
463
595
464 def __init__(self, ipython_dir=None, profile_dir=None,
596 def __init__(self, ipython_dir=None, profile_dir=None,
465 user_module=None, user_ns=None,
597 user_module=None, user_ns=None,
466 custom_exceptions=((), None), **kwargs):
598 custom_exceptions=((), None), **kwargs):
467
599
468 # This is where traits with a config_key argument are updated
600 # This is where traits with a config_key argument are updated
469 # from the values on config.
601 # from the values on config.
470 super(InteractiveShell, self).__init__(**kwargs)
602 super(InteractiveShell, self).__init__(**kwargs)
471 if 'PromptManager' in self.config:
603 if 'PromptManager' in self.config:
472 warn('As of IPython 5.0 `PromptManager` config will have no effect'
604 warn('As of IPython 5.0 `PromptManager` config will have no effect'
473 ' and has been replaced by TerminalInteractiveShell.prompts_class')
605 ' and has been replaced by TerminalInteractiveShell.prompts_class')
474 self.configurables = [self]
606 self.configurables = [self]
475
607
476 # These are relatively independent and stateless
608 # These are relatively independent and stateless
477 self.init_ipython_dir(ipython_dir)
609 self.init_ipython_dir(ipython_dir)
478 self.init_profile_dir(profile_dir)
610 self.init_profile_dir(profile_dir)
479 self.init_instance_attrs()
611 self.init_instance_attrs()
480 self.init_environment()
612 self.init_environment()
481
613
482 # Check if we're in a virtualenv, and set up sys.path.
614 # Check if we're in a virtualenv, and set up sys.path.
483 self.init_virtualenv()
615 self.init_virtualenv()
484
616
485 # Create namespaces (user_ns, user_global_ns, etc.)
617 # Create namespaces (user_ns, user_global_ns, etc.)
486 self.init_create_namespaces(user_module, user_ns)
618 self.init_create_namespaces(user_module, user_ns)
487 # This has to be done after init_create_namespaces because it uses
619 # This has to be done after init_create_namespaces because it uses
488 # something in self.user_ns, but before init_sys_modules, which
620 # something in self.user_ns, but before init_sys_modules, which
489 # is the first thing to modify sys.
621 # is the first thing to modify sys.
490 # TODO: When we override sys.stdout and sys.stderr before this class
622 # TODO: When we override sys.stdout and sys.stderr before this class
491 # is created, we are saving the overridden ones here. Not sure if this
623 # is created, we are saving the overridden ones here. Not sure if this
492 # is what we want to do.
624 # is what we want to do.
493 self.save_sys_module_state()
625 self.save_sys_module_state()
494 self.init_sys_modules()
626 self.init_sys_modules()
495
627
496 # While we're trying to have each part of the code directly access what
628 # While we're trying to have each part of the code directly access what
497 # it needs without keeping redundant references to objects, we have too
629 # it needs without keeping redundant references to objects, we have too
498 # much legacy code that expects ip.db to exist.
630 # much legacy code that expects ip.db to exist.
499 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
631 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
500
632
501 self.init_history()
633 self.init_history()
502 self.init_encoding()
634 self.init_encoding()
503 self.init_prefilter()
635 self.init_prefilter()
504
636
505 self.init_syntax_highlighting()
637 self.init_syntax_highlighting()
506 self.init_hooks()
638 self.init_hooks()
507 self.init_events()
639 self.init_events()
508 self.init_pushd_popd_magic()
640 self.init_pushd_popd_magic()
509 self.init_user_ns()
641 self.init_user_ns()
510 self.init_logger()
642 self.init_logger()
511 self.init_builtins()
643 self.init_builtins()
512
644
513 # The following was in post_config_initialization
645 # The following was in post_config_initialization
514 self.init_inspector()
646 self.init_inspector()
515 self.raw_input_original = input
647 self.raw_input_original = input
516 self.init_completer()
648 self.init_completer()
517 # TODO: init_io() needs to happen before init_traceback handlers
649 # TODO: init_io() needs to happen before init_traceback handlers
518 # because the traceback handlers hardcode the stdout/stderr streams.
650 # because the traceback handlers hardcode the stdout/stderr streams.
519 # This logic in in debugger.Pdb and should eventually be changed.
651 # This logic in in debugger.Pdb and should eventually be changed.
520 self.init_io()
652 self.init_io()
521 self.init_traceback_handlers(custom_exceptions)
653 self.init_traceback_handlers(custom_exceptions)
522 self.init_prompts()
654 self.init_prompts()
523 self.init_display_formatter()
655 self.init_display_formatter()
524 self.init_display_pub()
656 self.init_display_pub()
525 self.init_data_pub()
657 self.init_data_pub()
526 self.init_displayhook()
658 self.init_displayhook()
527 self.init_magics()
659 self.init_magics()
528 self.init_alias()
660 self.init_alias()
529 self.init_logstart()
661 self.init_logstart()
530 self.init_pdb()
662 self.init_pdb()
531 self.init_extension_manager()
663 self.init_extension_manager()
532 self.init_payload()
664 self.init_payload()
533 self.init_deprecation_warnings()
665 self.init_deprecation_warnings()
534 self.hooks.late_startup_hook()
666 self.hooks.late_startup_hook()
535 self.events.trigger('shell_initialized', self)
667 self.events.trigger('shell_initialized', self)
536 atexit.register(self.atexit_operations)
668 atexit.register(self.atexit_operations)
537
669
538 def get_ipython(self):
670 def get_ipython(self):
539 """Return the currently running IPython instance."""
671 """Return the currently running IPython instance."""
540 return self
672 return self
541
673
542 #-------------------------------------------------------------------------
674 #-------------------------------------------------------------------------
543 # Trait changed handlers
675 # Trait changed handlers
544 #-------------------------------------------------------------------------
676 #-------------------------------------------------------------------------
545 @observe('ipython_dir')
677 @observe('ipython_dir')
546 def _ipython_dir_changed(self, change):
678 def _ipython_dir_changed(self, change):
547 ensure_dir_exists(change['new'])
679 ensure_dir_exists(change['new'])
548
680
549 def set_autoindent(self,value=None):
681 def set_autoindent(self,value=None):
550 """Set the autoindent flag.
682 """Set the autoindent flag.
551
683
552 If called with no arguments, it acts as a toggle."""
684 If called with no arguments, it acts as a toggle."""
553 if value is None:
685 if value is None:
554 self.autoindent = not self.autoindent
686 self.autoindent = not self.autoindent
555 else:
687 else:
556 self.autoindent = value
688 self.autoindent = value
557
689
558 #-------------------------------------------------------------------------
690 #-------------------------------------------------------------------------
559 # init_* methods called by __init__
691 # init_* methods called by __init__
560 #-------------------------------------------------------------------------
692 #-------------------------------------------------------------------------
561
693
562 def init_ipython_dir(self, ipython_dir):
694 def init_ipython_dir(self, ipython_dir):
563 if ipython_dir is not None:
695 if ipython_dir is not None:
564 self.ipython_dir = ipython_dir
696 self.ipython_dir = ipython_dir
565 return
697 return
566
698
567 self.ipython_dir = get_ipython_dir()
699 self.ipython_dir = get_ipython_dir()
568
700
569 def init_profile_dir(self, profile_dir):
701 def init_profile_dir(self, profile_dir):
570 if profile_dir is not None:
702 if profile_dir is not None:
571 self.profile_dir = profile_dir
703 self.profile_dir = profile_dir
572 return
704 return
573 self.profile_dir =\
705 self.profile_dir =\
574 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
706 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
575
707
576 def init_instance_attrs(self):
708 def init_instance_attrs(self):
577 self.more = False
709 self.more = False
578
710
579 # command compiler
711 # command compiler
580 self.compile = CachingCompiler()
712 self.compile = CachingCompiler()
581
713
582 # Make an empty namespace, which extension writers can rely on both
714 # Make an empty namespace, which extension writers can rely on both
583 # existing and NEVER being used by ipython itself. This gives them a
715 # existing and NEVER being used by ipython itself. This gives them a
584 # convenient location for storing additional information and state
716 # convenient location for storing additional information and state
585 # their extensions may require, without fear of collisions with other
717 # their extensions may require, without fear of collisions with other
586 # ipython names that may develop later.
718 # ipython names that may develop later.
587 self.meta = Struct()
719 self.meta = Struct()
588
720
589 # Temporary files used for various purposes. Deleted at exit.
721 # Temporary files used for various purposes. Deleted at exit.
590 self.tempfiles = []
722 self.tempfiles = []
591 self.tempdirs = []
723 self.tempdirs = []
592
724
593 # keep track of where we started running (mainly for crash post-mortem)
725 # keep track of where we started running (mainly for crash post-mortem)
594 # This is not being used anywhere currently.
726 # This is not being used anywhere currently.
595 self.starting_dir = os.getcwd()
727 self.starting_dir = os.getcwd()
596
728
597 # Indentation management
729 # Indentation management
598 self.indent_current_nsp = 0
730 self.indent_current_nsp = 0
599
731
600 # Dict to track post-execution functions that have been registered
732 # Dict to track post-execution functions that have been registered
601 self._post_execute = {}
733 self._post_execute = {}
602
734
603 def init_environment(self):
735 def init_environment(self):
604 """Any changes we need to make to the user's environment."""
736 """Any changes we need to make to the user's environment."""
605 pass
737 pass
606
738
607 def init_encoding(self):
739 def init_encoding(self):
608 # Get system encoding at startup time. Certain terminals (like Emacs
740 # Get system encoding at startup time. Certain terminals (like Emacs
609 # under Win32 have it set to None, and we need to have a known valid
741 # under Win32 have it set to None, and we need to have a known valid
610 # encoding to use in the raw_input() method
742 # encoding to use in the raw_input() method
611 try:
743 try:
612 self.stdin_encoding = sys.stdin.encoding or 'ascii'
744 self.stdin_encoding = sys.stdin.encoding or 'ascii'
613 except AttributeError:
745 except AttributeError:
614 self.stdin_encoding = 'ascii'
746 self.stdin_encoding = 'ascii'
615
747
616
748
617 @observe('colors')
749 @observe('colors')
618 def init_syntax_highlighting(self, changes=None):
750 def init_syntax_highlighting(self, changes=None):
619 # Python source parser/formatter for syntax highlighting
751 # Python source parser/formatter for syntax highlighting
620 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
752 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
621 self.pycolorize = lambda src: pyformat(src,'str')
753 self.pycolorize = lambda src: pyformat(src,'str')
622
754
623 def refresh_style(self):
755 def refresh_style(self):
624 # No-op here, used in subclass
756 # No-op here, used in subclass
625 pass
757 pass
626
758
627 def init_pushd_popd_magic(self):
759 def init_pushd_popd_magic(self):
628 # for pushd/popd management
760 # for pushd/popd management
629 self.home_dir = get_home_dir()
761 self.home_dir = get_home_dir()
630
762
631 self.dir_stack = []
763 self.dir_stack = []
632
764
633 def init_logger(self):
765 def init_logger(self):
634 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
766 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
635 logmode='rotate')
767 logmode='rotate')
636
768
637 def init_logstart(self):
769 def init_logstart(self):
638 """Initialize logging in case it was requested at the command line.
770 """Initialize logging in case it was requested at the command line.
639 """
771 """
640 if self.logappend:
772 if self.logappend:
641 self.magic('logstart %s append' % self.logappend)
773 self.magic('logstart %s append' % self.logappend)
642 elif self.logfile:
774 elif self.logfile:
643 self.magic('logstart %s' % self.logfile)
775 self.magic('logstart %s' % self.logfile)
644 elif self.logstart:
776 elif self.logstart:
645 self.magic('logstart')
777 self.magic('logstart')
646
778
647 def init_deprecation_warnings(self):
779 def init_deprecation_warnings(self):
648 """
780 """
649 register default filter for deprecation warning.
781 register default filter for deprecation warning.
650
782
651 This will allow deprecation warning of function used interactively to show
783 This will allow deprecation warning of function used interactively to show
652 warning to users, and still hide deprecation warning from libraries import.
784 warning to users, and still hide deprecation warning from libraries import.
653 """
785 """
654 warnings.filterwarnings("default", category=DeprecationWarning, module=self.user_ns.get("__name__"))
786 warnings.filterwarnings("default", category=DeprecationWarning, module=self.user_ns.get("__name__"))
655
787
656 def init_builtins(self):
788 def init_builtins(self):
657 # A single, static flag that we set to True. Its presence indicates
789 # A single, static flag that we set to True. Its presence indicates
658 # that an IPython shell has been created, and we make no attempts at
790 # that an IPython shell has been created, and we make no attempts at
659 # removing on exit or representing the existence of more than one
791 # removing on exit or representing the existence of more than one
660 # IPython at a time.
792 # IPython at a time.
661 builtin_mod.__dict__['__IPYTHON__'] = True
793 builtin_mod.__dict__['__IPYTHON__'] = True
662 builtin_mod.__dict__['display'] = display
794 builtin_mod.__dict__['display'] = display
663
795
664 self.builtin_trap = BuiltinTrap(shell=self)
796 self.builtin_trap = BuiltinTrap(shell=self)
665
797
666 @observe('colors')
798 @observe('colors')
667 def init_inspector(self, changes=None):
799 def init_inspector(self, changes=None):
668 # Object inspector
800 # Object inspector
669 self.inspector = oinspect.Inspector(oinspect.InspectColors,
801 self.inspector = oinspect.Inspector(oinspect.InspectColors,
670 PyColorize.ANSICodeColors,
802 PyColorize.ANSICodeColors,
671 self.colors,
803 self.colors,
672 self.object_info_string_level)
804 self.object_info_string_level)
673
805
674 def init_io(self):
806 def init_io(self):
675 # This will just use sys.stdout and sys.stderr. If you want to
807 # This will just use sys.stdout and sys.stderr. If you want to
676 # override sys.stdout and sys.stderr themselves, you need to do that
808 # override sys.stdout and sys.stderr themselves, you need to do that
677 # *before* instantiating this class, because io holds onto
809 # *before* instantiating this class, because io holds onto
678 # references to the underlying streams.
810 # references to the underlying streams.
679 # io.std* are deprecated, but don't show our own deprecation warnings
811 # io.std* are deprecated, but don't show our own deprecation warnings
680 # during initialization of the deprecated API.
812 # during initialization of the deprecated API.
681 with warnings.catch_warnings():
813 with warnings.catch_warnings():
682 warnings.simplefilter('ignore', DeprecationWarning)
814 warnings.simplefilter('ignore', DeprecationWarning)
683 io.stdout = io.IOStream(sys.stdout)
815 io.stdout = io.IOStream(sys.stdout)
684 io.stderr = io.IOStream(sys.stderr)
816 io.stderr = io.IOStream(sys.stderr)
685
817
686 def init_prompts(self):
818 def init_prompts(self):
687 # Set system prompts, so that scripts can decide if they are running
819 # Set system prompts, so that scripts can decide if they are running
688 # interactively.
820 # interactively.
689 sys.ps1 = 'In : '
821 sys.ps1 = 'In : '
690 sys.ps2 = '...: '
822 sys.ps2 = '...: '
691 sys.ps3 = 'Out: '
823 sys.ps3 = 'Out: '
692
824
693 def init_display_formatter(self):
825 def init_display_formatter(self):
694 self.display_formatter = DisplayFormatter(parent=self)
826 self.display_formatter = DisplayFormatter(parent=self)
695 self.configurables.append(self.display_formatter)
827 self.configurables.append(self.display_formatter)
696
828
697 def init_display_pub(self):
829 def init_display_pub(self):
698 self.display_pub = self.display_pub_class(parent=self)
830 self.display_pub = self.display_pub_class(parent=self)
699 self.configurables.append(self.display_pub)
831 self.configurables.append(self.display_pub)
700
832
701 def init_data_pub(self):
833 def init_data_pub(self):
702 if not self.data_pub_class:
834 if not self.data_pub_class:
703 self.data_pub = None
835 self.data_pub = None
704 return
836 return
705 self.data_pub = self.data_pub_class(parent=self)
837 self.data_pub = self.data_pub_class(parent=self)
706 self.configurables.append(self.data_pub)
838 self.configurables.append(self.data_pub)
707
839
708 def init_displayhook(self):
840 def init_displayhook(self):
709 # Initialize displayhook, set in/out prompts and printing system
841 # Initialize displayhook, set in/out prompts and printing system
710 self.displayhook = self.displayhook_class(
842 self.displayhook = self.displayhook_class(
711 parent=self,
843 parent=self,
712 shell=self,
844 shell=self,
713 cache_size=self.cache_size,
845 cache_size=self.cache_size,
714 )
846 )
715 self.configurables.append(self.displayhook)
847 self.configurables.append(self.displayhook)
716 # This is a context manager that installs/revmoes the displayhook at
848 # This is a context manager that installs/revmoes the displayhook at
717 # the appropriate time.
849 # the appropriate time.
718 self.display_trap = DisplayTrap(hook=self.displayhook)
850 self.display_trap = DisplayTrap(hook=self.displayhook)
719
851
720 def init_virtualenv(self):
852 def init_virtualenv(self):
721 """Add a virtualenv to sys.path so the user can import modules from it.
853 """Add a virtualenv to sys.path so the user can import modules from it.
722 This isn't perfect: it doesn't use the Python interpreter with which the
854 This isn't perfect: it doesn't use the Python interpreter with which the
723 virtualenv was built, and it ignores the --no-site-packages option. A
855 virtualenv was built, and it ignores the --no-site-packages option. A
724 warning will appear suggesting the user installs IPython in the
856 warning will appear suggesting the user installs IPython in the
725 virtualenv, but for many cases, it probably works well enough.
857 virtualenv, but for many cases, it probably works well enough.
726
858
727 Adapted from code snippets online.
859 Adapted from code snippets online.
728
860
729 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
861 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
730 """
862 """
731 if 'VIRTUAL_ENV' not in os.environ:
863 if 'VIRTUAL_ENV' not in os.environ:
732 # Not in a virtualenv
864 # Not in a virtualenv
733 return
865 return
734
866
735 p = os.path.normcase(sys.executable)
867 p = os.path.normcase(sys.executable)
736 p_venv = os.path.normcase(os.environ['VIRTUAL_ENV'])
868 p_venv = os.path.normcase(os.environ['VIRTUAL_ENV'])
737
869
738 # executable path should end like /bin/python or \\scripts\\python.exe
870 # executable path should end like /bin/python or \\scripts\\python.exe
739 p_exe_up2 = os.path.dirname(os.path.dirname(p))
871 p_exe_up2 = os.path.dirname(os.path.dirname(p))
740 if p_exe_up2 and os.path.exists(p_venv) and os.path.samefile(p_exe_up2, p_venv):
872 if p_exe_up2 and os.path.exists(p_venv) and os.path.samefile(p_exe_up2, p_venv):
741 # Our exe is inside the virtualenv, don't need to do anything.
873 # Our exe is inside the virtualenv, don't need to do anything.
742 return
874 return
743
875
744 # fallback venv detection:
876 # fallback venv detection:
745 # stdlib venv may symlink sys.executable, so we can't use realpath.
877 # stdlib venv may symlink sys.executable, so we can't use realpath.
746 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
878 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
747 # So we just check every item in the symlink tree (generally <= 3)
879 # So we just check every item in the symlink tree (generally <= 3)
748 paths = [p]
880 paths = [p]
749 while os.path.islink(p):
881 while os.path.islink(p):
750 p = os.path.normcase(os.path.join(os.path.dirname(p), os.readlink(p)))
882 p = os.path.normcase(os.path.join(os.path.dirname(p), os.readlink(p)))
751 paths.append(p)
883 paths.append(p)
752
884
753 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
885 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
754 if p_venv.startswith('\\cygdrive'):
886 if p_venv.startswith('\\cygdrive'):
755 p_venv = p_venv[11:]
887 p_venv = p_venv[11:]
756 elif len(p_venv) >= 2 and p_venv[1] == ':':
888 elif len(p_venv) >= 2 and p_venv[1] == ':':
757 p_venv = p_venv[2:]
889 p_venv = p_venv[2:]
758
890
759 if any(p_venv in p for p in paths):
891 if any(p_venv in p for p in paths):
760 # Running properly in the virtualenv, don't need to do anything
892 # Running properly in the virtualenv, don't need to do anything
761 return
893 return
762
894
763 warn("Attempting to work in a virtualenv. If you encounter problems, please "
895 warn("Attempting to work in a virtualenv. If you encounter problems, please "
764 "install IPython inside the virtualenv.")
896 "install IPython inside the virtualenv.")
765 if sys.platform == "win32":
897 if sys.platform == "win32":
766 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
898 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
767 else:
899 else:
768 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
900 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
769 'python%d.%d' % sys.version_info[:2], 'site-packages')
901 'python%d.%d' % sys.version_info[:2], 'site-packages')
770
902
771 import site
903 import site
772 sys.path.insert(0, virtual_env)
904 sys.path.insert(0, virtual_env)
773 site.addsitedir(virtual_env)
905 site.addsitedir(virtual_env)
774
906
775 #-------------------------------------------------------------------------
907 #-------------------------------------------------------------------------
776 # Things related to injections into the sys module
908 # Things related to injections into the sys module
777 #-------------------------------------------------------------------------
909 #-------------------------------------------------------------------------
778
910
779 def save_sys_module_state(self):
911 def save_sys_module_state(self):
780 """Save the state of hooks in the sys module.
912 """Save the state of hooks in the sys module.
781
913
782 This has to be called after self.user_module is created.
914 This has to be called after self.user_module is created.
783 """
915 """
784 self._orig_sys_module_state = {'stdin': sys.stdin,
916 self._orig_sys_module_state = {'stdin': sys.stdin,
785 'stdout': sys.stdout,
917 'stdout': sys.stdout,
786 'stderr': sys.stderr,
918 'stderr': sys.stderr,
787 'excepthook': sys.excepthook}
919 'excepthook': sys.excepthook}
788 self._orig_sys_modules_main_name = self.user_module.__name__
920 self._orig_sys_modules_main_name = self.user_module.__name__
789 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
921 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
790
922
791 def restore_sys_module_state(self):
923 def restore_sys_module_state(self):
792 """Restore the state of the sys module."""
924 """Restore the state of the sys module."""
793 try:
925 try:
794 for k, v in self._orig_sys_module_state.items():
926 for k, v in self._orig_sys_module_state.items():
795 setattr(sys, k, v)
927 setattr(sys, k, v)
796 except AttributeError:
928 except AttributeError:
797 pass
929 pass
798 # Reset what what done in self.init_sys_modules
930 # Reset what what done in self.init_sys_modules
799 if self._orig_sys_modules_main_mod is not None:
931 if self._orig_sys_modules_main_mod is not None:
800 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
932 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
801
933
802 #-------------------------------------------------------------------------
934 #-------------------------------------------------------------------------
803 # Things related to the banner
935 # Things related to the banner
804 #-------------------------------------------------------------------------
936 #-------------------------------------------------------------------------
805
937
806 @property
938 @property
807 def banner(self):
939 def banner(self):
808 banner = self.banner1
940 banner = self.banner1
809 if self.profile and self.profile != 'default':
941 if self.profile and self.profile != 'default':
810 banner += '\nIPython profile: %s\n' % self.profile
942 banner += '\nIPython profile: %s\n' % self.profile
811 if self.banner2:
943 if self.banner2:
812 banner += '\n' + self.banner2
944 banner += '\n' + self.banner2
813 return banner
945 return banner
814
946
815 def show_banner(self, banner=None):
947 def show_banner(self, banner=None):
816 if banner is None:
948 if banner is None:
817 banner = self.banner
949 banner = self.banner
818 sys.stdout.write(banner)
950 sys.stdout.write(banner)
819
951
820 #-------------------------------------------------------------------------
952 #-------------------------------------------------------------------------
821 # Things related to hooks
953 # Things related to hooks
822 #-------------------------------------------------------------------------
954 #-------------------------------------------------------------------------
823
955
824 def init_hooks(self):
956 def init_hooks(self):
825 # hooks holds pointers used for user-side customizations
957 # hooks holds pointers used for user-side customizations
826 self.hooks = Struct()
958 self.hooks = Struct()
827
959
828 self.strdispatchers = {}
960 self.strdispatchers = {}
829
961
830 # Set all default hooks, defined in the IPython.hooks module.
962 # Set all default hooks, defined in the IPython.hooks module.
831 hooks = IPython.core.hooks
963 hooks = IPython.core.hooks
832 for hook_name in hooks.__all__:
964 for hook_name in hooks.__all__:
833 # default hooks have priority 100, i.e. low; user hooks should have
965 # default hooks have priority 100, i.e. low; user hooks should have
834 # 0-100 priority
966 # 0-100 priority
835 self.set_hook(hook_name,getattr(hooks,hook_name), 100, _warn_deprecated=False)
967 self.set_hook(hook_name,getattr(hooks,hook_name), 100, _warn_deprecated=False)
836
968
837 if self.display_page:
969 if self.display_page:
838 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
970 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
839
971
840 def set_hook(self,name,hook, priority=50, str_key=None, re_key=None,
972 def set_hook(self,name,hook, priority=50, str_key=None, re_key=None,
841 _warn_deprecated=True):
973 _warn_deprecated=True):
842 """set_hook(name,hook) -> sets an internal IPython hook.
974 """set_hook(name,hook) -> sets an internal IPython hook.
843
975
844 IPython exposes some of its internal API as user-modifiable hooks. By
976 IPython exposes some of its internal API as user-modifiable hooks. By
845 adding your function to one of these hooks, you can modify IPython's
977 adding your function to one of these hooks, you can modify IPython's
846 behavior to call at runtime your own routines."""
978 behavior to call at runtime your own routines."""
847
979
848 # At some point in the future, this should validate the hook before it
980 # At some point in the future, this should validate the hook before it
849 # accepts it. Probably at least check that the hook takes the number
981 # accepts it. Probably at least check that the hook takes the number
850 # of args it's supposed to.
982 # of args it's supposed to.
851
983
852 f = types.MethodType(hook,self)
984 f = types.MethodType(hook,self)
853
985
854 # check if the hook is for strdispatcher first
986 # check if the hook is for strdispatcher first
855 if str_key is not None:
987 if str_key is not None:
856 sdp = self.strdispatchers.get(name, StrDispatch())
988 sdp = self.strdispatchers.get(name, StrDispatch())
857 sdp.add_s(str_key, f, priority )
989 sdp.add_s(str_key, f, priority )
858 self.strdispatchers[name] = sdp
990 self.strdispatchers[name] = sdp
859 return
991 return
860 if re_key is not None:
992 if re_key is not None:
861 sdp = self.strdispatchers.get(name, StrDispatch())
993 sdp = self.strdispatchers.get(name, StrDispatch())
862 sdp.add_re(re.compile(re_key), f, priority )
994 sdp.add_re(re.compile(re_key), f, priority )
863 self.strdispatchers[name] = sdp
995 self.strdispatchers[name] = sdp
864 return
996 return
865
997
866 dp = getattr(self.hooks, name, None)
998 dp = getattr(self.hooks, name, None)
867 if name not in IPython.core.hooks.__all__:
999 if name not in IPython.core.hooks.__all__:
868 print("Warning! Hook '%s' is not one of %s" % \
1000 print("Warning! Hook '%s' is not one of %s" % \
869 (name, IPython.core.hooks.__all__ ))
1001 (name, IPython.core.hooks.__all__ ))
870
1002
871 if _warn_deprecated and (name in IPython.core.hooks.deprecated):
1003 if _warn_deprecated and (name in IPython.core.hooks.deprecated):
872 alternative = IPython.core.hooks.deprecated[name]
1004 alternative = IPython.core.hooks.deprecated[name]
873 warn("Hook {} is deprecated. Use {} instead.".format(name, alternative), stacklevel=2)
1005 warn("Hook {} is deprecated. Use {} instead.".format(name, alternative), stacklevel=2)
874
1006
875 if not dp:
1007 if not dp:
876 dp = IPython.core.hooks.CommandChainDispatcher()
1008 dp = IPython.core.hooks.CommandChainDispatcher()
877
1009
878 try:
1010 try:
879 dp.add(f,priority)
1011 dp.add(f,priority)
880 except AttributeError:
1012 except AttributeError:
881 # it was not commandchain, plain old func - replace
1013 # it was not commandchain, plain old func - replace
882 dp = f
1014 dp = f
883
1015
884 setattr(self.hooks,name, dp)
1016 setattr(self.hooks,name, dp)
885
1017
886 #-------------------------------------------------------------------------
1018 #-------------------------------------------------------------------------
887 # Things related to events
1019 # Things related to events
888 #-------------------------------------------------------------------------
1020 #-------------------------------------------------------------------------
889
1021
890 def init_events(self):
1022 def init_events(self):
891 self.events = EventManager(self, available_events)
1023 self.events = EventManager(self, available_events)
892
1024
893 self.events.register("pre_execute", self._clear_warning_registry)
1025 self.events.register("pre_execute", self._clear_warning_registry)
894
1026
895 def register_post_execute(self, func):
1027 def register_post_execute(self, func):
896 """DEPRECATED: Use ip.events.register('post_run_cell', func)
1028 """DEPRECATED: Use ip.events.register('post_run_cell', func)
897
1029
898 Register a function for calling after code execution.
1030 Register a function for calling after code execution.
899 """
1031 """
900 warn("ip.register_post_execute is deprecated, use "
1032 warn("ip.register_post_execute is deprecated, use "
901 "ip.events.register('post_run_cell', func) instead.", stacklevel=2)
1033 "ip.events.register('post_run_cell', func) instead.", stacklevel=2)
902 self.events.register('post_run_cell', func)
1034 self.events.register('post_run_cell', func)
903
1035
904 def _clear_warning_registry(self):
1036 def _clear_warning_registry(self):
905 # clear the warning registry, so that different code blocks with
1037 # clear the warning registry, so that different code blocks with
906 # overlapping line number ranges don't cause spurious suppression of
1038 # overlapping line number ranges don't cause spurious suppression of
907 # warnings (see gh-6611 for details)
1039 # warnings (see gh-6611 for details)
908 if "__warningregistry__" in self.user_global_ns:
1040 if "__warningregistry__" in self.user_global_ns:
909 del self.user_global_ns["__warningregistry__"]
1041 del self.user_global_ns["__warningregistry__"]
910
1042
911 #-------------------------------------------------------------------------
1043 #-------------------------------------------------------------------------
912 # Things related to the "main" module
1044 # Things related to the "main" module
913 #-------------------------------------------------------------------------
1045 #-------------------------------------------------------------------------
914
1046
915 def new_main_mod(self, filename, modname):
1047 def new_main_mod(self, filename, modname):
916 """Return a new 'main' module object for user code execution.
1048 """Return a new 'main' module object for user code execution.
917
1049
918 ``filename`` should be the path of the script which will be run in the
1050 ``filename`` should be the path of the script which will be run in the
919 module. Requests with the same filename will get the same module, with
1051 module. Requests with the same filename will get the same module, with
920 its namespace cleared.
1052 its namespace cleared.
921
1053
922 ``modname`` should be the module name - normally either '__main__' or
1054 ``modname`` should be the module name - normally either '__main__' or
923 the basename of the file without the extension.
1055 the basename of the file without the extension.
924
1056
925 When scripts are executed via %run, we must keep a reference to their
1057 When scripts are executed via %run, we must keep a reference to their
926 __main__ module around so that Python doesn't
1058 __main__ module around so that Python doesn't
927 clear it, rendering references to module globals useless.
1059 clear it, rendering references to module globals useless.
928
1060
929 This method keeps said reference in a private dict, keyed by the
1061 This method keeps said reference in a private dict, keyed by the
930 absolute path of the script. This way, for multiple executions of the
1062 absolute path of the script. This way, for multiple executions of the
931 same script we only keep one copy of the namespace (the last one),
1063 same script we only keep one copy of the namespace (the last one),
932 thus preventing memory leaks from old references while allowing the
1064 thus preventing memory leaks from old references while allowing the
933 objects from the last execution to be accessible.
1065 objects from the last execution to be accessible.
934 """
1066 """
935 filename = os.path.abspath(filename)
1067 filename = os.path.abspath(filename)
936 try:
1068 try:
937 main_mod = self._main_mod_cache[filename]
1069 main_mod = self._main_mod_cache[filename]
938 except KeyError:
1070 except KeyError:
939 main_mod = self._main_mod_cache[filename] = types.ModuleType(
1071 main_mod = self._main_mod_cache[filename] = types.ModuleType(
940 modname,
1072 modname,
941 doc="Module created for script run in IPython")
1073 doc="Module created for script run in IPython")
942 else:
1074 else:
943 main_mod.__dict__.clear()
1075 main_mod.__dict__.clear()
944 main_mod.__name__ = modname
1076 main_mod.__name__ = modname
945
1077
946 main_mod.__file__ = filename
1078 main_mod.__file__ = filename
947 # It seems pydoc (and perhaps others) needs any module instance to
1079 # It seems pydoc (and perhaps others) needs any module instance to
948 # implement a __nonzero__ method
1080 # implement a __nonzero__ method
949 main_mod.__nonzero__ = lambda : True
1081 main_mod.__nonzero__ = lambda : True
950
1082
951 return main_mod
1083 return main_mod
952
1084
953 def clear_main_mod_cache(self):
1085 def clear_main_mod_cache(self):
954 """Clear the cache of main modules.
1086 """Clear the cache of main modules.
955
1087
956 Mainly for use by utilities like %reset.
1088 Mainly for use by utilities like %reset.
957
1089
958 Examples
1090 Examples
959 --------
1091 --------
960
1092
961 In [15]: import IPython
1093 In [15]: import IPython
962
1094
963 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
1095 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
964
1096
965 In [17]: len(_ip._main_mod_cache) > 0
1097 In [17]: len(_ip._main_mod_cache) > 0
966 Out[17]: True
1098 Out[17]: True
967
1099
968 In [18]: _ip.clear_main_mod_cache()
1100 In [18]: _ip.clear_main_mod_cache()
969
1101
970 In [19]: len(_ip._main_mod_cache) == 0
1102 In [19]: len(_ip._main_mod_cache) == 0
971 Out[19]: True
1103 Out[19]: True
972 """
1104 """
973 self._main_mod_cache.clear()
1105 self._main_mod_cache.clear()
974
1106
975 #-------------------------------------------------------------------------
1107 #-------------------------------------------------------------------------
976 # Things related to debugging
1108 # Things related to debugging
977 #-------------------------------------------------------------------------
1109 #-------------------------------------------------------------------------
978
1110
979 def init_pdb(self):
1111 def init_pdb(self):
980 # Set calling of pdb on exceptions
1112 # Set calling of pdb on exceptions
981 # self.call_pdb is a property
1113 # self.call_pdb is a property
982 self.call_pdb = self.pdb
1114 self.call_pdb = self.pdb
983
1115
984 def _get_call_pdb(self):
1116 def _get_call_pdb(self):
985 return self._call_pdb
1117 return self._call_pdb
986
1118
987 def _set_call_pdb(self,val):
1119 def _set_call_pdb(self,val):
988
1120
989 if val not in (0,1,False,True):
1121 if val not in (0,1,False,True):
990 raise ValueError('new call_pdb value must be boolean')
1122 raise ValueError('new call_pdb value must be boolean')
991
1123
992 # store value in instance
1124 # store value in instance
993 self._call_pdb = val
1125 self._call_pdb = val
994
1126
995 # notify the actual exception handlers
1127 # notify the actual exception handlers
996 self.InteractiveTB.call_pdb = val
1128 self.InteractiveTB.call_pdb = val
997
1129
998 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1130 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
999 'Control auto-activation of pdb at exceptions')
1131 'Control auto-activation of pdb at exceptions')
1000
1132
1001 def debugger(self,force=False):
1133 def debugger(self,force=False):
1002 """Call the pdb debugger.
1134 """Call the pdb debugger.
1003
1135
1004 Keywords:
1136 Keywords:
1005
1137
1006 - force(False): by default, this routine checks the instance call_pdb
1138 - force(False): by default, this routine checks the instance call_pdb
1007 flag and does not actually invoke the debugger if the flag is false.
1139 flag and does not actually invoke the debugger if the flag is false.
1008 The 'force' option forces the debugger to activate even if the flag
1140 The 'force' option forces the debugger to activate even if the flag
1009 is false.
1141 is false.
1010 """
1142 """
1011
1143
1012 if not (force or self.call_pdb):
1144 if not (force or self.call_pdb):
1013 return
1145 return
1014
1146
1015 if not hasattr(sys,'last_traceback'):
1147 if not hasattr(sys,'last_traceback'):
1016 error('No traceback has been produced, nothing to debug.')
1148 error('No traceback has been produced, nothing to debug.')
1017 return
1149 return
1018
1150
1019 self.InteractiveTB.debugger(force=True)
1151 self.InteractiveTB.debugger(force=True)
1020
1152
1021 #-------------------------------------------------------------------------
1153 #-------------------------------------------------------------------------
1022 # Things related to IPython's various namespaces
1154 # Things related to IPython's various namespaces
1023 #-------------------------------------------------------------------------
1155 #-------------------------------------------------------------------------
1024 default_user_namespaces = True
1156 default_user_namespaces = True
1025
1157
1026 def init_create_namespaces(self, user_module=None, user_ns=None):
1158 def init_create_namespaces(self, user_module=None, user_ns=None):
1027 # Create the namespace where the user will operate. user_ns is
1159 # Create the namespace where the user will operate. user_ns is
1028 # normally the only one used, and it is passed to the exec calls as
1160 # normally the only one used, and it is passed to the exec calls as
1029 # the locals argument. But we do carry a user_global_ns namespace
1161 # the locals argument. But we do carry a user_global_ns namespace
1030 # given as the exec 'globals' argument, This is useful in embedding
1162 # given as the exec 'globals' argument, This is useful in embedding
1031 # situations where the ipython shell opens in a context where the
1163 # situations where the ipython shell opens in a context where the
1032 # distinction between locals and globals is meaningful. For
1164 # distinction between locals and globals is meaningful. For
1033 # non-embedded contexts, it is just the same object as the user_ns dict.
1165 # non-embedded contexts, it is just the same object as the user_ns dict.
1034
1166
1035 # FIXME. For some strange reason, __builtins__ is showing up at user
1167 # FIXME. For some strange reason, __builtins__ is showing up at user
1036 # level as a dict instead of a module. This is a manual fix, but I
1168 # level as a dict instead of a module. This is a manual fix, but I
1037 # should really track down where the problem is coming from. Alex
1169 # should really track down where the problem is coming from. Alex
1038 # Schmolck reported this problem first.
1170 # Schmolck reported this problem first.
1039
1171
1040 # A useful post by Alex Martelli on this topic:
1172 # A useful post by Alex Martelli on this topic:
1041 # Re: inconsistent value from __builtins__
1173 # Re: inconsistent value from __builtins__
1042 # Von: Alex Martelli <aleaxit@yahoo.com>
1174 # Von: Alex Martelli <aleaxit@yahoo.com>
1043 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1175 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1044 # Gruppen: comp.lang.python
1176 # Gruppen: comp.lang.python
1045
1177
1046 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1178 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1047 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1179 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1048 # > <type 'dict'>
1180 # > <type 'dict'>
1049 # > >>> print type(__builtins__)
1181 # > >>> print type(__builtins__)
1050 # > <type 'module'>
1182 # > <type 'module'>
1051 # > Is this difference in return value intentional?
1183 # > Is this difference in return value intentional?
1052
1184
1053 # Well, it's documented that '__builtins__' can be either a dictionary
1185 # Well, it's documented that '__builtins__' can be either a dictionary
1054 # or a module, and it's been that way for a long time. Whether it's
1186 # or a module, and it's been that way for a long time. Whether it's
1055 # intentional (or sensible), I don't know. In any case, the idea is
1187 # intentional (or sensible), I don't know. In any case, the idea is
1056 # that if you need to access the built-in namespace directly, you
1188 # that if you need to access the built-in namespace directly, you
1057 # should start with "import __builtin__" (note, no 's') which will
1189 # should start with "import __builtin__" (note, no 's') which will
1058 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1190 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1059
1191
1060 # These routines return a properly built module and dict as needed by
1192 # These routines return a properly built module and dict as needed by
1061 # the rest of the code, and can also be used by extension writers to
1193 # the rest of the code, and can also be used by extension writers to
1062 # generate properly initialized namespaces.
1194 # generate properly initialized namespaces.
1063 if (user_ns is not None) or (user_module is not None):
1195 if (user_ns is not None) or (user_module is not None):
1064 self.default_user_namespaces = False
1196 self.default_user_namespaces = False
1065 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1197 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1066
1198
1067 # A record of hidden variables we have added to the user namespace, so
1199 # A record of hidden variables we have added to the user namespace, so
1068 # we can list later only variables defined in actual interactive use.
1200 # we can list later only variables defined in actual interactive use.
1069 self.user_ns_hidden = {}
1201 self.user_ns_hidden = {}
1070
1202
1071 # Now that FakeModule produces a real module, we've run into a nasty
1203 # Now that FakeModule produces a real module, we've run into a nasty
1072 # problem: after script execution (via %run), the module where the user
1204 # problem: after script execution (via %run), the module where the user
1073 # code ran is deleted. Now that this object is a true module (needed
1205 # code ran is deleted. Now that this object is a true module (needed
1074 # so doctest and other tools work correctly), the Python module
1206 # so doctest and other tools work correctly), the Python module
1075 # teardown mechanism runs over it, and sets to None every variable
1207 # teardown mechanism runs over it, and sets to None every variable
1076 # present in that module. Top-level references to objects from the
1208 # present in that module. Top-level references to objects from the
1077 # script survive, because the user_ns is updated with them. However,
1209 # script survive, because the user_ns is updated with them. However,
1078 # calling functions defined in the script that use other things from
1210 # calling functions defined in the script that use other things from
1079 # the script will fail, because the function's closure had references
1211 # the script will fail, because the function's closure had references
1080 # to the original objects, which are now all None. So we must protect
1212 # to the original objects, which are now all None. So we must protect
1081 # these modules from deletion by keeping a cache.
1213 # these modules from deletion by keeping a cache.
1082 #
1214 #
1083 # To avoid keeping stale modules around (we only need the one from the
1215 # To avoid keeping stale modules around (we only need the one from the
1084 # last run), we use a dict keyed with the full path to the script, so
1216 # last run), we use a dict keyed with the full path to the script, so
1085 # only the last version of the module is held in the cache. Note,
1217 # only the last version of the module is held in the cache. Note,
1086 # however, that we must cache the module *namespace contents* (their
1218 # however, that we must cache the module *namespace contents* (their
1087 # __dict__). Because if we try to cache the actual modules, old ones
1219 # __dict__). Because if we try to cache the actual modules, old ones
1088 # (uncached) could be destroyed while still holding references (such as
1220 # (uncached) could be destroyed while still holding references (such as
1089 # those held by GUI objects that tend to be long-lived)>
1221 # those held by GUI objects that tend to be long-lived)>
1090 #
1222 #
1091 # The %reset command will flush this cache. See the cache_main_mod()
1223 # The %reset command will flush this cache. See the cache_main_mod()
1092 # and clear_main_mod_cache() methods for details on use.
1224 # and clear_main_mod_cache() methods for details on use.
1093
1225
1094 # This is the cache used for 'main' namespaces
1226 # This is the cache used for 'main' namespaces
1095 self._main_mod_cache = {}
1227 self._main_mod_cache = {}
1096
1228
1097 # A table holding all the namespaces IPython deals with, so that
1229 # A table holding all the namespaces IPython deals with, so that
1098 # introspection facilities can search easily.
1230 # introspection facilities can search easily.
1099 self.ns_table = {'user_global':self.user_module.__dict__,
1231 self.ns_table = {'user_global':self.user_module.__dict__,
1100 'user_local':self.user_ns,
1232 'user_local':self.user_ns,
1101 'builtin':builtin_mod.__dict__
1233 'builtin':builtin_mod.__dict__
1102 }
1234 }
1103
1235
1104 @property
1236 @property
1105 def user_global_ns(self):
1237 def user_global_ns(self):
1106 return self.user_module.__dict__
1238 return self.user_module.__dict__
1107
1239
1108 def prepare_user_module(self, user_module=None, user_ns=None):
1240 def prepare_user_module(self, user_module=None, user_ns=None):
1109 """Prepare the module and namespace in which user code will be run.
1241 """Prepare the module and namespace in which user code will be run.
1110
1242
1111 When IPython is started normally, both parameters are None: a new module
1243 When IPython is started normally, both parameters are None: a new module
1112 is created automatically, and its __dict__ used as the namespace.
1244 is created automatically, and its __dict__ used as the namespace.
1113
1245
1114 If only user_module is provided, its __dict__ is used as the namespace.
1246 If only user_module is provided, its __dict__ is used as the namespace.
1115 If only user_ns is provided, a dummy module is created, and user_ns
1247 If only user_ns is provided, a dummy module is created, and user_ns
1116 becomes the global namespace. If both are provided (as they may be
1248 becomes the global namespace. If both are provided (as they may be
1117 when embedding), user_ns is the local namespace, and user_module
1249 when embedding), user_ns is the local namespace, and user_module
1118 provides the global namespace.
1250 provides the global namespace.
1119
1251
1120 Parameters
1252 Parameters
1121 ----------
1253 ----------
1122 user_module : module, optional
1254 user_module : module, optional
1123 The current user module in which IPython is being run. If None,
1255 The current user module in which IPython is being run. If None,
1124 a clean module will be created.
1256 a clean module will be created.
1125 user_ns : dict, optional
1257 user_ns : dict, optional
1126 A namespace in which to run interactive commands.
1258 A namespace in which to run interactive commands.
1127
1259
1128 Returns
1260 Returns
1129 -------
1261 -------
1130 A tuple of user_module and user_ns, each properly initialised.
1262 A tuple of user_module and user_ns, each properly initialised.
1131 """
1263 """
1132 if user_module is None and user_ns is not None:
1264 if user_module is None and user_ns is not None:
1133 user_ns.setdefault("__name__", "__main__")
1265 user_ns.setdefault("__name__", "__main__")
1134 user_module = DummyMod()
1266 user_module = DummyMod()
1135 user_module.__dict__ = user_ns
1267 user_module.__dict__ = user_ns
1136
1268
1137 if user_module is None:
1269 if user_module is None:
1138 user_module = types.ModuleType("__main__",
1270 user_module = types.ModuleType("__main__",
1139 doc="Automatically created module for IPython interactive environment")
1271 doc="Automatically created module for IPython interactive environment")
1140
1272
1141 # We must ensure that __builtin__ (without the final 's') is always
1273 # We must ensure that __builtin__ (without the final 's') is always
1142 # available and pointing to the __builtin__ *module*. For more details:
1274 # available and pointing to the __builtin__ *module*. For more details:
1143 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1275 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1144 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1276 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1145 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1277 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1146
1278
1147 if user_ns is None:
1279 if user_ns is None:
1148 user_ns = user_module.__dict__
1280 user_ns = user_module.__dict__
1149
1281
1150 return user_module, user_ns
1282 return user_module, user_ns
1151
1283
1152 def init_sys_modules(self):
1284 def init_sys_modules(self):
1153 # We need to insert into sys.modules something that looks like a
1285 # We need to insert into sys.modules something that looks like a
1154 # module but which accesses the IPython namespace, for shelve and
1286 # module but which accesses the IPython namespace, for shelve and
1155 # pickle to work interactively. Normally they rely on getting
1287 # pickle to work interactively. Normally they rely on getting
1156 # everything out of __main__, but for embedding purposes each IPython
1288 # everything out of __main__, but for embedding purposes each IPython
1157 # instance has its own private namespace, so we can't go shoving
1289 # instance has its own private namespace, so we can't go shoving
1158 # everything into __main__.
1290 # everything into __main__.
1159
1291
1160 # note, however, that we should only do this for non-embedded
1292 # note, however, that we should only do this for non-embedded
1161 # ipythons, which really mimic the __main__.__dict__ with their own
1293 # ipythons, which really mimic the __main__.__dict__ with their own
1162 # namespace. Embedded instances, on the other hand, should not do
1294 # namespace. Embedded instances, on the other hand, should not do
1163 # this because they need to manage the user local/global namespaces
1295 # this because they need to manage the user local/global namespaces
1164 # only, but they live within a 'normal' __main__ (meaning, they
1296 # only, but they live within a 'normal' __main__ (meaning, they
1165 # shouldn't overtake the execution environment of the script they're
1297 # shouldn't overtake the execution environment of the script they're
1166 # embedded in).
1298 # embedded in).
1167
1299
1168 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1300 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1169 main_name = self.user_module.__name__
1301 main_name = self.user_module.__name__
1170 sys.modules[main_name] = self.user_module
1302 sys.modules[main_name] = self.user_module
1171
1303
1172 def init_user_ns(self):
1304 def init_user_ns(self):
1173 """Initialize all user-visible namespaces to their minimum defaults.
1305 """Initialize all user-visible namespaces to their minimum defaults.
1174
1306
1175 Certain history lists are also initialized here, as they effectively
1307 Certain history lists are also initialized here, as they effectively
1176 act as user namespaces.
1308 act as user namespaces.
1177
1309
1178 Notes
1310 Notes
1179 -----
1311 -----
1180 All data structures here are only filled in, they are NOT reset by this
1312 All data structures here are only filled in, they are NOT reset by this
1181 method. If they were not empty before, data will simply be added to
1313 method. If they were not empty before, data will simply be added to
1182 them.
1314 them.
1183 """
1315 """
1184 # This function works in two parts: first we put a few things in
1316 # This function works in two parts: first we put a few things in
1185 # user_ns, and we sync that contents into user_ns_hidden so that these
1317 # user_ns, and we sync that contents into user_ns_hidden so that these
1186 # initial variables aren't shown by %who. After the sync, we add the
1318 # initial variables aren't shown by %who. After the sync, we add the
1187 # rest of what we *do* want the user to see with %who even on a new
1319 # rest of what we *do* want the user to see with %who even on a new
1188 # session (probably nothing, so they really only see their own stuff)
1320 # session (probably nothing, so they really only see their own stuff)
1189
1321
1190 # The user dict must *always* have a __builtin__ reference to the
1322 # The user dict must *always* have a __builtin__ reference to the
1191 # Python standard __builtin__ namespace, which must be imported.
1323 # Python standard __builtin__ namespace, which must be imported.
1192 # This is so that certain operations in prompt evaluation can be
1324 # This is so that certain operations in prompt evaluation can be
1193 # reliably executed with builtins. Note that we can NOT use
1325 # reliably executed with builtins. Note that we can NOT use
1194 # __builtins__ (note the 's'), because that can either be a dict or a
1326 # __builtins__ (note the 's'), because that can either be a dict or a
1195 # module, and can even mutate at runtime, depending on the context
1327 # module, and can even mutate at runtime, depending on the context
1196 # (Python makes no guarantees on it). In contrast, __builtin__ is
1328 # (Python makes no guarantees on it). In contrast, __builtin__ is
1197 # always a module object, though it must be explicitly imported.
1329 # always a module object, though it must be explicitly imported.
1198
1330
1199 # For more details:
1331 # For more details:
1200 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1332 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1201 ns = {}
1333 ns = {}
1202
1334
1203 # make global variables for user access to the histories
1335 # make global variables for user access to the histories
1204 ns['_ih'] = self.history_manager.input_hist_parsed
1336 ns['_ih'] = self.history_manager.input_hist_parsed
1205 ns['_oh'] = self.history_manager.output_hist
1337 ns['_oh'] = self.history_manager.output_hist
1206 ns['_dh'] = self.history_manager.dir_hist
1338 ns['_dh'] = self.history_manager.dir_hist
1207
1339
1208 # user aliases to input and output histories. These shouldn't show up
1340 # user aliases to input and output histories. These shouldn't show up
1209 # in %who, as they can have very large reprs.
1341 # in %who, as they can have very large reprs.
1210 ns['In'] = self.history_manager.input_hist_parsed
1342 ns['In'] = self.history_manager.input_hist_parsed
1211 ns['Out'] = self.history_manager.output_hist
1343 ns['Out'] = self.history_manager.output_hist
1212
1344
1213 # Store myself as the public api!!!
1345 # Store myself as the public api!!!
1214 ns['get_ipython'] = self.get_ipython
1346 ns['get_ipython'] = self.get_ipython
1215
1347
1216 ns['exit'] = self.exiter
1348 ns['exit'] = self.exiter
1217 ns['quit'] = self.exiter
1349 ns['quit'] = self.exiter
1218
1350
1219 # Sync what we've added so far to user_ns_hidden so these aren't seen
1351 # Sync what we've added so far to user_ns_hidden so these aren't seen
1220 # by %who
1352 # by %who
1221 self.user_ns_hidden.update(ns)
1353 self.user_ns_hidden.update(ns)
1222
1354
1223 # Anything put into ns now would show up in %who. Think twice before
1355 # Anything put into ns now would show up in %who. Think twice before
1224 # putting anything here, as we really want %who to show the user their
1356 # putting anything here, as we really want %who to show the user their
1225 # stuff, not our variables.
1357 # stuff, not our variables.
1226
1358
1227 # Finally, update the real user's namespace
1359 # Finally, update the real user's namespace
1228 self.user_ns.update(ns)
1360 self.user_ns.update(ns)
1229
1361
1230 @property
1362 @property
1231 def all_ns_refs(self):
1363 def all_ns_refs(self):
1232 """Get a list of references to all the namespace dictionaries in which
1364 """Get a list of references to all the namespace dictionaries in which
1233 IPython might store a user-created object.
1365 IPython might store a user-created object.
1234
1366
1235 Note that this does not include the displayhook, which also caches
1367 Note that this does not include the displayhook, which also caches
1236 objects from the output."""
1368 objects from the output."""
1237 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1369 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1238 [m.__dict__ for m in self._main_mod_cache.values()]
1370 [m.__dict__ for m in self._main_mod_cache.values()]
1239
1371
1240 def reset(self, new_session=True):
1372 def reset(self, new_session=True):
1241 """Clear all internal namespaces, and attempt to release references to
1373 """Clear all internal namespaces, and attempt to release references to
1242 user objects.
1374 user objects.
1243
1375
1244 If new_session is True, a new history session will be opened.
1376 If new_session is True, a new history session will be opened.
1245 """
1377 """
1246 # Clear histories
1378 # Clear histories
1247 self.history_manager.reset(new_session)
1379 self.history_manager.reset(new_session)
1248 # Reset counter used to index all histories
1380 # Reset counter used to index all histories
1249 if new_session:
1381 if new_session:
1250 self.execution_count = 1
1382 self.execution_count = 1
1251
1383
1252 # Reset last execution result
1384 # Reset last execution result
1253 self.last_execution_succeeded = True
1385 self.last_execution_succeeded = True
1254 self.last_execution_result = None
1386 self.last_execution_result = None
1255
1387
1256 # Flush cached output items
1388 # Flush cached output items
1257 if self.displayhook.do_full_cache:
1389 if self.displayhook.do_full_cache:
1258 self.displayhook.flush()
1390 self.displayhook.flush()
1259
1391
1260 # The main execution namespaces must be cleared very carefully,
1392 # The main execution namespaces must be cleared very carefully,
1261 # skipping the deletion of the builtin-related keys, because doing so
1393 # skipping the deletion of the builtin-related keys, because doing so
1262 # would cause errors in many object's __del__ methods.
1394 # would cause errors in many object's __del__ methods.
1263 if self.user_ns is not self.user_global_ns:
1395 if self.user_ns is not self.user_global_ns:
1264 self.user_ns.clear()
1396 self.user_ns.clear()
1265 ns = self.user_global_ns
1397 ns = self.user_global_ns
1266 drop_keys = set(ns.keys())
1398 drop_keys = set(ns.keys())
1267 drop_keys.discard('__builtin__')
1399 drop_keys.discard('__builtin__')
1268 drop_keys.discard('__builtins__')
1400 drop_keys.discard('__builtins__')
1269 drop_keys.discard('__name__')
1401 drop_keys.discard('__name__')
1270 for k in drop_keys:
1402 for k in drop_keys:
1271 del ns[k]
1403 del ns[k]
1272
1404
1273 self.user_ns_hidden.clear()
1405 self.user_ns_hidden.clear()
1274
1406
1275 # Restore the user namespaces to minimal usability
1407 # Restore the user namespaces to minimal usability
1276 self.init_user_ns()
1408 self.init_user_ns()
1277
1409
1278 # Restore the default and user aliases
1410 # Restore the default and user aliases
1279 self.alias_manager.clear_aliases()
1411 self.alias_manager.clear_aliases()
1280 self.alias_manager.init_aliases()
1412 self.alias_manager.init_aliases()
1281
1413
1282 # Flush the private list of module references kept for script
1414 # Flush the private list of module references kept for script
1283 # execution protection
1415 # execution protection
1284 self.clear_main_mod_cache()
1416 self.clear_main_mod_cache()
1285
1417
1286 def del_var(self, varname, by_name=False):
1418 def del_var(self, varname, by_name=False):
1287 """Delete a variable from the various namespaces, so that, as
1419 """Delete a variable from the various namespaces, so that, as
1288 far as possible, we're not keeping any hidden references to it.
1420 far as possible, we're not keeping any hidden references to it.
1289
1421
1290 Parameters
1422 Parameters
1291 ----------
1423 ----------
1292 varname : str
1424 varname : str
1293 The name of the variable to delete.
1425 The name of the variable to delete.
1294 by_name : bool
1426 by_name : bool
1295 If True, delete variables with the given name in each
1427 If True, delete variables with the given name in each
1296 namespace. If False (default), find the variable in the user
1428 namespace. If False (default), find the variable in the user
1297 namespace, and delete references to it.
1429 namespace, and delete references to it.
1298 """
1430 """
1299 if varname in ('__builtin__', '__builtins__'):
1431 if varname in ('__builtin__', '__builtins__'):
1300 raise ValueError("Refusing to delete %s" % varname)
1432 raise ValueError("Refusing to delete %s" % varname)
1301
1433
1302 ns_refs = self.all_ns_refs
1434 ns_refs = self.all_ns_refs
1303
1435
1304 if by_name: # Delete by name
1436 if by_name: # Delete by name
1305 for ns in ns_refs:
1437 for ns in ns_refs:
1306 try:
1438 try:
1307 del ns[varname]
1439 del ns[varname]
1308 except KeyError:
1440 except KeyError:
1309 pass
1441 pass
1310 else: # Delete by object
1442 else: # Delete by object
1311 try:
1443 try:
1312 obj = self.user_ns[varname]
1444 obj = self.user_ns[varname]
1313 except KeyError:
1445 except KeyError:
1314 raise NameError("name '%s' is not defined" % varname)
1446 raise NameError("name '%s' is not defined" % varname)
1315 # Also check in output history
1447 # Also check in output history
1316 ns_refs.append(self.history_manager.output_hist)
1448 ns_refs.append(self.history_manager.output_hist)
1317 for ns in ns_refs:
1449 for ns in ns_refs:
1318 to_delete = [n for n, o in ns.items() if o is obj]
1450 to_delete = [n for n, o in ns.items() if o is obj]
1319 for name in to_delete:
1451 for name in to_delete:
1320 del ns[name]
1452 del ns[name]
1321
1453
1322 # Ensure it is removed from the last execution result
1454 # Ensure it is removed from the last execution result
1323 if self.last_execution_result.result is obj:
1455 if self.last_execution_result.result is obj:
1324 self.last_execution_result = None
1456 self.last_execution_result = None
1325
1457
1326 # displayhook keeps extra references, but not in a dictionary
1458 # displayhook keeps extra references, but not in a dictionary
1327 for name in ('_', '__', '___'):
1459 for name in ('_', '__', '___'):
1328 if getattr(self.displayhook, name) is obj:
1460 if getattr(self.displayhook, name) is obj:
1329 setattr(self.displayhook, name, None)
1461 setattr(self.displayhook, name, None)
1330
1462
1331 def reset_selective(self, regex=None):
1463 def reset_selective(self, regex=None):
1332 """Clear selective variables from internal namespaces based on a
1464 """Clear selective variables from internal namespaces based on a
1333 specified regular expression.
1465 specified regular expression.
1334
1466
1335 Parameters
1467 Parameters
1336 ----------
1468 ----------
1337 regex : string or compiled pattern, optional
1469 regex : string or compiled pattern, optional
1338 A regular expression pattern that will be used in searching
1470 A regular expression pattern that will be used in searching
1339 variable names in the users namespaces.
1471 variable names in the users namespaces.
1340 """
1472 """
1341 if regex is not None:
1473 if regex is not None:
1342 try:
1474 try:
1343 m = re.compile(regex)
1475 m = re.compile(regex)
1344 except TypeError:
1476 except TypeError:
1345 raise TypeError('regex must be a string or compiled pattern')
1477 raise TypeError('regex must be a string or compiled pattern')
1346 # Search for keys in each namespace that match the given regex
1478 # Search for keys in each namespace that match the given regex
1347 # If a match is found, delete the key/value pair.
1479 # If a match is found, delete the key/value pair.
1348 for ns in self.all_ns_refs:
1480 for ns in self.all_ns_refs:
1349 for var in ns:
1481 for var in ns:
1350 if m.search(var):
1482 if m.search(var):
1351 del ns[var]
1483 del ns[var]
1352
1484
1353 def push(self, variables, interactive=True):
1485 def push(self, variables, interactive=True):
1354 """Inject a group of variables into the IPython user namespace.
1486 """Inject a group of variables into the IPython user namespace.
1355
1487
1356 Parameters
1488 Parameters
1357 ----------
1489 ----------
1358 variables : dict, str or list/tuple of str
1490 variables : dict, str or list/tuple of str
1359 The variables to inject into the user's namespace. If a dict, a
1491 The variables to inject into the user's namespace. If a dict, a
1360 simple update is done. If a str, the string is assumed to have
1492 simple update is done. If a str, the string is assumed to have
1361 variable names separated by spaces. A list/tuple of str can also
1493 variable names separated by spaces. A list/tuple of str can also
1362 be used to give the variable names. If just the variable names are
1494 be used to give the variable names. If just the variable names are
1363 give (list/tuple/str) then the variable values looked up in the
1495 give (list/tuple/str) then the variable values looked up in the
1364 callers frame.
1496 callers frame.
1365 interactive : bool
1497 interactive : bool
1366 If True (default), the variables will be listed with the ``who``
1498 If True (default), the variables will be listed with the ``who``
1367 magic.
1499 magic.
1368 """
1500 """
1369 vdict = None
1501 vdict = None
1370
1502
1371 # We need a dict of name/value pairs to do namespace updates.
1503 # We need a dict of name/value pairs to do namespace updates.
1372 if isinstance(variables, dict):
1504 if isinstance(variables, dict):
1373 vdict = variables
1505 vdict = variables
1374 elif isinstance(variables, (str, list, tuple)):
1506 elif isinstance(variables, (str, list, tuple)):
1375 if isinstance(variables, str):
1507 if isinstance(variables, str):
1376 vlist = variables.split()
1508 vlist = variables.split()
1377 else:
1509 else:
1378 vlist = variables
1510 vlist = variables
1379 vdict = {}
1511 vdict = {}
1380 cf = sys._getframe(1)
1512 cf = sys._getframe(1)
1381 for name in vlist:
1513 for name in vlist:
1382 try:
1514 try:
1383 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1515 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1384 except:
1516 except:
1385 print('Could not get variable %s from %s' %
1517 print('Could not get variable %s from %s' %
1386 (name,cf.f_code.co_name))
1518 (name,cf.f_code.co_name))
1387 else:
1519 else:
1388 raise ValueError('variables must be a dict/str/list/tuple')
1520 raise ValueError('variables must be a dict/str/list/tuple')
1389
1521
1390 # Propagate variables to user namespace
1522 # Propagate variables to user namespace
1391 self.user_ns.update(vdict)
1523 self.user_ns.update(vdict)
1392
1524
1393 # And configure interactive visibility
1525 # And configure interactive visibility
1394 user_ns_hidden = self.user_ns_hidden
1526 user_ns_hidden = self.user_ns_hidden
1395 if interactive:
1527 if interactive:
1396 for name in vdict:
1528 for name in vdict:
1397 user_ns_hidden.pop(name, None)
1529 user_ns_hidden.pop(name, None)
1398 else:
1530 else:
1399 user_ns_hidden.update(vdict)
1531 user_ns_hidden.update(vdict)
1400
1532
1401 def drop_by_id(self, variables):
1533 def drop_by_id(self, variables):
1402 """Remove a dict of variables from the user namespace, if they are the
1534 """Remove a dict of variables from the user namespace, if they are the
1403 same as the values in the dictionary.
1535 same as the values in the dictionary.
1404
1536
1405 This is intended for use by extensions: variables that they've added can
1537 This is intended for use by extensions: variables that they've added can
1406 be taken back out if they are unloaded, without removing any that the
1538 be taken back out if they are unloaded, without removing any that the
1407 user has overwritten.
1539 user has overwritten.
1408
1540
1409 Parameters
1541 Parameters
1410 ----------
1542 ----------
1411 variables : dict
1543 variables : dict
1412 A dictionary mapping object names (as strings) to the objects.
1544 A dictionary mapping object names (as strings) to the objects.
1413 """
1545 """
1414 for name, obj in variables.items():
1546 for name, obj in variables.items():
1415 if name in self.user_ns and self.user_ns[name] is obj:
1547 if name in self.user_ns and self.user_ns[name] is obj:
1416 del self.user_ns[name]
1548 del self.user_ns[name]
1417 self.user_ns_hidden.pop(name, None)
1549 self.user_ns_hidden.pop(name, None)
1418
1550
1419 #-------------------------------------------------------------------------
1551 #-------------------------------------------------------------------------
1420 # Things related to object introspection
1552 # Things related to object introspection
1421 #-------------------------------------------------------------------------
1553 #-------------------------------------------------------------------------
1422
1554
1423 def _ofind(self, oname, namespaces=None):
1555 def _ofind(self, oname, namespaces=None):
1424 """Find an object in the available namespaces.
1556 """Find an object in the available namespaces.
1425
1557
1426 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1558 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1427
1559
1428 Has special code to detect magic functions.
1560 Has special code to detect magic functions.
1429 """
1561 """
1430 oname = oname.strip()
1562 oname = oname.strip()
1431 if not oname.startswith(ESC_MAGIC) and \
1563 if not oname.startswith(ESC_MAGIC) and \
1432 not oname.startswith(ESC_MAGIC2) and \
1564 not oname.startswith(ESC_MAGIC2) and \
1433 not all(a.isidentifier() for a in oname.split(".")):
1565 not all(a.isidentifier() for a in oname.split(".")):
1434 return {'found': False}
1566 return {'found': False}
1435
1567
1436 if namespaces is None:
1568 if namespaces is None:
1437 # Namespaces to search in:
1569 # Namespaces to search in:
1438 # Put them in a list. The order is important so that we
1570 # Put them in a list. The order is important so that we
1439 # find things in the same order that Python finds them.
1571 # find things in the same order that Python finds them.
1440 namespaces = [ ('Interactive', self.user_ns),
1572 namespaces = [ ('Interactive', self.user_ns),
1441 ('Interactive (global)', self.user_global_ns),
1573 ('Interactive (global)', self.user_global_ns),
1442 ('Python builtin', builtin_mod.__dict__),
1574 ('Python builtin', builtin_mod.__dict__),
1443 ]
1575 ]
1444
1576
1445 ismagic = False
1577 ismagic = False
1446 isalias = False
1578 isalias = False
1447 found = False
1579 found = False
1448 ospace = None
1580 ospace = None
1449 parent = None
1581 parent = None
1450 obj = None
1582 obj = None
1451
1583
1584
1452 # Look for the given name by splitting it in parts. If the head is
1585 # Look for the given name by splitting it in parts. If the head is
1453 # found, then we look for all the remaining parts as members, and only
1586 # found, then we look for all the remaining parts as members, and only
1454 # declare success if we can find them all.
1587 # declare success if we can find them all.
1455 oname_parts = oname.split('.')
1588 oname_parts = oname.split('.')
1456 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1589 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1457 for nsname,ns in namespaces:
1590 for nsname,ns in namespaces:
1458 try:
1591 try:
1459 obj = ns[oname_head]
1592 obj = ns[oname_head]
1460 except KeyError:
1593 except KeyError:
1461 continue
1594 continue
1462 else:
1595 else:
1463 for idx, part in enumerate(oname_rest):
1596 for idx, part in enumerate(oname_rest):
1464 try:
1597 try:
1465 parent = obj
1598 parent = obj
1466 # The last part is looked up in a special way to avoid
1599 # The last part is looked up in a special way to avoid
1467 # descriptor invocation as it may raise or have side
1600 # descriptor invocation as it may raise or have side
1468 # effects.
1601 # effects.
1469 if idx == len(oname_rest) - 1:
1602 if idx == len(oname_rest) - 1:
1470 obj = self._getattr_property(obj, part)
1603 obj = self._getattr_property(obj, part)
1471 else:
1604 else:
1472 obj = getattr(obj, part)
1605 obj = getattr(obj, part)
1473 except:
1606 except:
1474 # Blanket except b/c some badly implemented objects
1607 # Blanket except b/c some badly implemented objects
1475 # allow __getattr__ to raise exceptions other than
1608 # allow __getattr__ to raise exceptions other than
1476 # AttributeError, which then crashes IPython.
1609 # AttributeError, which then crashes IPython.
1477 break
1610 break
1478 else:
1611 else:
1479 # If we finish the for loop (no break), we got all members
1612 # If we finish the for loop (no break), we got all members
1480 found = True
1613 found = True
1481 ospace = nsname
1614 ospace = nsname
1482 break # namespace loop
1615 break # namespace loop
1483
1616
1484 # Try to see if it's magic
1617 # Try to see if it's magic
1485 if not found:
1618 if not found:
1486 obj = None
1619 obj = None
1487 if oname.startswith(ESC_MAGIC2):
1620 if oname.startswith(ESC_MAGIC2):
1488 oname = oname.lstrip(ESC_MAGIC2)
1621 oname = oname.lstrip(ESC_MAGIC2)
1489 obj = self.find_cell_magic(oname)
1622 obj = self.find_cell_magic(oname)
1490 elif oname.startswith(ESC_MAGIC):
1623 elif oname.startswith(ESC_MAGIC):
1491 oname = oname.lstrip(ESC_MAGIC)
1624 oname = oname.lstrip(ESC_MAGIC)
1492 obj = self.find_line_magic(oname)
1625 obj = self.find_line_magic(oname)
1493 else:
1626 else:
1494 # search without prefix, so run? will find %run?
1627 # search without prefix, so run? will find %run?
1495 obj = self.find_line_magic(oname)
1628 obj = self.find_line_magic(oname)
1496 if obj is None:
1629 if obj is None:
1497 obj = self.find_cell_magic(oname)
1630 obj = self.find_cell_magic(oname)
1498 if obj is not None:
1631 if obj is not None:
1499 found = True
1632 found = True
1500 ospace = 'IPython internal'
1633 ospace = 'IPython internal'
1501 ismagic = True
1634 ismagic = True
1502 isalias = isinstance(obj, Alias)
1635 isalias = isinstance(obj, Alias)
1503
1636
1504 # Last try: special-case some literals like '', [], {}, etc:
1637 # Last try: special-case some literals like '', [], {}, etc:
1505 if not found and oname_head in ["''",'""','[]','{}','()']:
1638 if not found and oname_head in ["''",'""','[]','{}','()']:
1506 obj = eval(oname_head)
1639 obj = eval(oname_head)
1507 found = True
1640 found = True
1508 ospace = 'Interactive'
1641 ospace = 'Interactive'
1509
1642
1510 return {
1643 return {
1511 'obj':obj,
1644 'obj':obj,
1512 'found':found,
1645 'found':found,
1513 'parent':parent,
1646 'parent':parent,
1514 'ismagic':ismagic,
1647 'ismagic':ismagic,
1515 'isalias':isalias,
1648 'isalias':isalias,
1516 'namespace':ospace
1649 'namespace':ospace
1517 }
1650 }
1518
1651
1519 @staticmethod
1652 @staticmethod
1520 def _getattr_property(obj, attrname):
1653 def _getattr_property(obj, attrname):
1521 """Property-aware getattr to use in object finding.
1654 """Property-aware getattr to use in object finding.
1522
1655
1523 If attrname represents a property, return it unevaluated (in case it has
1656 If attrname represents a property, return it unevaluated (in case it has
1524 side effects or raises an error.
1657 side effects or raises an error.
1525
1658
1526 """
1659 """
1527 if not isinstance(obj, type):
1660 if not isinstance(obj, type):
1528 try:
1661 try:
1529 # `getattr(type(obj), attrname)` is not guaranteed to return
1662 # `getattr(type(obj), attrname)` is not guaranteed to return
1530 # `obj`, but does so for property:
1663 # `obj`, but does so for property:
1531 #
1664 #
1532 # property.__get__(self, None, cls) -> self
1665 # property.__get__(self, None, cls) -> self
1533 #
1666 #
1534 # The universal alternative is to traverse the mro manually
1667 # The universal alternative is to traverse the mro manually
1535 # searching for attrname in class dicts.
1668 # searching for attrname in class dicts.
1536 attr = getattr(type(obj), attrname)
1669 attr = getattr(type(obj), attrname)
1537 except AttributeError:
1670 except AttributeError:
1538 pass
1671 pass
1539 else:
1672 else:
1540 # This relies on the fact that data descriptors (with both
1673 # This relies on the fact that data descriptors (with both
1541 # __get__ & __set__ magic methods) take precedence over
1674 # __get__ & __set__ magic methods) take precedence over
1542 # instance-level attributes:
1675 # instance-level attributes:
1543 #
1676 #
1544 # class A(object):
1677 # class A(object):
1545 # @property
1678 # @property
1546 # def foobar(self): return 123
1679 # def foobar(self): return 123
1547 # a = A()
1680 # a = A()
1548 # a.__dict__['foobar'] = 345
1681 # a.__dict__['foobar'] = 345
1549 # a.foobar # == 123
1682 # a.foobar # == 123
1550 #
1683 #
1551 # So, a property may be returned right away.
1684 # So, a property may be returned right away.
1552 if isinstance(attr, property):
1685 if isinstance(attr, property):
1553 return attr
1686 return attr
1554
1687
1555 # Nothing helped, fall back.
1688 # Nothing helped, fall back.
1556 return getattr(obj, attrname)
1689 return getattr(obj, attrname)
1557
1690
1558 def _object_find(self, oname, namespaces=None):
1691 def _object_find(self, oname, namespaces=None):
1559 """Find an object and return a struct with info about it."""
1692 """Find an object and return a struct with info about it."""
1560 return Struct(self._ofind(oname, namespaces))
1693 return Struct(self._ofind(oname, namespaces))
1561
1694
1562 def _inspect(self, meth, oname, namespaces=None, **kw):
1695 def _inspect(self, meth, oname, namespaces=None, **kw):
1563 """Generic interface to the inspector system.
1696 """Generic interface to the inspector system.
1564
1697
1565 This function is meant to be called by pdef, pdoc & friends.
1698 This function is meant to be called by pdef, pdoc & friends.
1566 """
1699 """
1567 info = self._object_find(oname, namespaces)
1700 info = self._object_find(oname, namespaces)
1568 docformat = sphinxify if self.sphinxify_docstring else None
1701 docformat = sphinxify if self.sphinxify_docstring else None
1569 if info.found:
1702 if info.found:
1570 pmethod = getattr(self.inspector, meth)
1703 pmethod = getattr(self.inspector, meth)
1571 # TODO: only apply format_screen to the plain/text repr of the mime
1704 # TODO: only apply format_screen to the plain/text repr of the mime
1572 # bundle.
1705 # bundle.
1573 formatter = format_screen if info.ismagic else docformat
1706 formatter = format_screen if info.ismagic else docformat
1574 if meth == 'pdoc':
1707 if meth == 'pdoc':
1575 pmethod(info.obj, oname, formatter)
1708 pmethod(info.obj, oname, formatter)
1576 elif meth == 'pinfo':
1709 elif meth == 'pinfo':
1577 pmethod(info.obj, oname, formatter, info,
1710 pmethod(info.obj, oname, formatter, info,
1578 enable_html_pager=self.enable_html_pager, **kw)
1711 enable_html_pager=self.enable_html_pager, **kw)
1579 else:
1712 else:
1580 pmethod(info.obj, oname)
1713 pmethod(info.obj, oname)
1581 else:
1714 else:
1582 print('Object `%s` not found.' % oname)
1715 print('Object `%s` not found.' % oname)
1583 return 'not found' # so callers can take other action
1716 return 'not found' # so callers can take other action
1584
1717
1585 def object_inspect(self, oname, detail_level=0):
1718 def object_inspect(self, oname, detail_level=0):
1586 """Get object info about oname"""
1719 """Get object info about oname"""
1587 with self.builtin_trap:
1720 with self.builtin_trap:
1588 info = self._object_find(oname)
1721 info = self._object_find(oname)
1589 if info.found:
1722 if info.found:
1590 return self.inspector.info(info.obj, oname, info=info,
1723 return self.inspector.info(info.obj, oname, info=info,
1591 detail_level=detail_level
1724 detail_level=detail_level
1592 )
1725 )
1593 else:
1726 else:
1594 return oinspect.object_info(name=oname, found=False)
1727 return oinspect.object_info(name=oname, found=False)
1595
1728
1596 def object_inspect_text(self, oname, detail_level=0):
1729 def object_inspect_text(self, oname, detail_level=0):
1597 """Get object info as formatted text"""
1730 """Get object info as formatted text"""
1598 return self.object_inspect_mime(oname, detail_level)['text/plain']
1731 return self.object_inspect_mime(oname, detail_level)['text/plain']
1599
1732
1600 def object_inspect_mime(self, oname, detail_level=0):
1733 def object_inspect_mime(self, oname, detail_level=0):
1601 """Get object info as a mimebundle of formatted representations.
1734 """Get object info as a mimebundle of formatted representations.
1602
1735
1603 A mimebundle is a dictionary, keyed by mime-type.
1736 A mimebundle is a dictionary, keyed by mime-type.
1604 It must always have the key `'text/plain'`.
1737 It must always have the key `'text/plain'`.
1605 """
1738 """
1606 with self.builtin_trap:
1739 with self.builtin_trap:
1607 info = self._object_find(oname)
1740 info = self._object_find(oname)
1608 if info.found:
1741 if info.found:
1609 return self.inspector._get_info(info.obj, oname, info=info,
1742 return self.inspector._get_info(info.obj, oname, info=info,
1610 detail_level=detail_level
1743 detail_level=detail_level
1611 )
1744 )
1612 else:
1745 else:
1613 raise KeyError(oname)
1746 raise KeyError(oname)
1614
1747
1615 #-------------------------------------------------------------------------
1748 #-------------------------------------------------------------------------
1616 # Things related to history management
1749 # Things related to history management
1617 #-------------------------------------------------------------------------
1750 #-------------------------------------------------------------------------
1618
1751
1619 def init_history(self):
1752 def init_history(self):
1620 """Sets up the command history, and starts regular autosaves."""
1753 """Sets up the command history, and starts regular autosaves."""
1621 self.history_manager = HistoryManager(shell=self, parent=self)
1754 self.history_manager = HistoryManager(shell=self, parent=self)
1622 self.configurables.append(self.history_manager)
1755 self.configurables.append(self.history_manager)
1623
1756
1624 #-------------------------------------------------------------------------
1757 #-------------------------------------------------------------------------
1625 # Things related to exception handling and tracebacks (not debugging)
1758 # Things related to exception handling and tracebacks (not debugging)
1626 #-------------------------------------------------------------------------
1759 #-------------------------------------------------------------------------
1627
1760
1628 debugger_cls = Pdb
1761 debugger_cls = Pdb
1629
1762
1630 def init_traceback_handlers(self, custom_exceptions):
1763 def init_traceback_handlers(self, custom_exceptions):
1631 # Syntax error handler.
1764 # Syntax error handler.
1632 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1765 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1633
1766
1634 # The interactive one is initialized with an offset, meaning we always
1767 # The interactive one is initialized with an offset, meaning we always
1635 # want to remove the topmost item in the traceback, which is our own
1768 # want to remove the topmost item in the traceback, which is our own
1636 # internal code. Valid modes: ['Plain','Context','Verbose']
1769 # internal code. Valid modes: ['Plain','Context','Verbose']
1637 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1770 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1638 color_scheme='NoColor',
1771 color_scheme='NoColor',
1639 tb_offset = 1,
1772 tb_offset = 1,
1640 check_cache=check_linecache_ipython,
1773 check_cache=check_linecache_ipython,
1641 debugger_cls=self.debugger_cls, parent=self)
1774 debugger_cls=self.debugger_cls, parent=self)
1642
1775
1643 # The instance will store a pointer to the system-wide exception hook,
1776 # The instance will store a pointer to the system-wide exception hook,
1644 # so that runtime code (such as magics) can access it. This is because
1777 # so that runtime code (such as magics) can access it. This is because
1645 # during the read-eval loop, it may get temporarily overwritten.
1778 # during the read-eval loop, it may get temporarily overwritten.
1646 self.sys_excepthook = sys.excepthook
1779 self.sys_excepthook = sys.excepthook
1647
1780
1648 # and add any custom exception handlers the user may have specified
1781 # and add any custom exception handlers the user may have specified
1649 self.set_custom_exc(*custom_exceptions)
1782 self.set_custom_exc(*custom_exceptions)
1650
1783
1651 # Set the exception mode
1784 # Set the exception mode
1652 self.InteractiveTB.set_mode(mode=self.xmode)
1785 self.InteractiveTB.set_mode(mode=self.xmode)
1653
1786
1654 def set_custom_exc(self, exc_tuple, handler):
1787 def set_custom_exc(self, exc_tuple, handler):
1655 """set_custom_exc(exc_tuple, handler)
1788 """set_custom_exc(exc_tuple, handler)
1656
1789
1657 Set a custom exception handler, which will be called if any of the
1790 Set a custom exception handler, which will be called if any of the
1658 exceptions in exc_tuple occur in the mainloop (specifically, in the
1791 exceptions in exc_tuple occur in the mainloop (specifically, in the
1659 run_code() method).
1792 run_code() method).
1660
1793
1661 Parameters
1794 Parameters
1662 ----------
1795 ----------
1663
1796
1664 exc_tuple : tuple of exception classes
1797 exc_tuple : tuple of exception classes
1665 A *tuple* of exception classes, for which to call the defined
1798 A *tuple* of exception classes, for which to call the defined
1666 handler. It is very important that you use a tuple, and NOT A
1799 handler. It is very important that you use a tuple, and NOT A
1667 LIST here, because of the way Python's except statement works. If
1800 LIST here, because of the way Python's except statement works. If
1668 you only want to trap a single exception, use a singleton tuple::
1801 you only want to trap a single exception, use a singleton tuple::
1669
1802
1670 exc_tuple == (MyCustomException,)
1803 exc_tuple == (MyCustomException,)
1671
1804
1672 handler : callable
1805 handler : callable
1673 handler must have the following signature::
1806 handler must have the following signature::
1674
1807
1675 def my_handler(self, etype, value, tb, tb_offset=None):
1808 def my_handler(self, etype, value, tb, tb_offset=None):
1676 ...
1809 ...
1677 return structured_traceback
1810 return structured_traceback
1678
1811
1679 Your handler must return a structured traceback (a list of strings),
1812 Your handler must return a structured traceback (a list of strings),
1680 or None.
1813 or None.
1681
1814
1682 This will be made into an instance method (via types.MethodType)
1815 This will be made into an instance method (via types.MethodType)
1683 of IPython itself, and it will be called if any of the exceptions
1816 of IPython itself, and it will be called if any of the exceptions
1684 listed in the exc_tuple are caught. If the handler is None, an
1817 listed in the exc_tuple are caught. If the handler is None, an
1685 internal basic one is used, which just prints basic info.
1818 internal basic one is used, which just prints basic info.
1686
1819
1687 To protect IPython from crashes, if your handler ever raises an
1820 To protect IPython from crashes, if your handler ever raises an
1688 exception or returns an invalid result, it will be immediately
1821 exception or returns an invalid result, it will be immediately
1689 disabled.
1822 disabled.
1690
1823
1691 WARNING: by putting in your own exception handler into IPython's main
1824 WARNING: by putting in your own exception handler into IPython's main
1692 execution loop, you run a very good chance of nasty crashes. This
1825 execution loop, you run a very good chance of nasty crashes. This
1693 facility should only be used if you really know what you are doing."""
1826 facility should only be used if you really know what you are doing."""
1694 if not isinstance(exc_tuple, tuple):
1827 if not isinstance(exc_tuple, tuple):
1695 raise TypeError("The custom exceptions must be given as a tuple.")
1828 raise TypeError("The custom exceptions must be given as a tuple.")
1696
1829
1697 def dummy_handler(self, etype, value, tb, tb_offset=None):
1830 def dummy_handler(self, etype, value, tb, tb_offset=None):
1698 print('*** Simple custom exception handler ***')
1831 print('*** Simple custom exception handler ***')
1699 print('Exception type :', etype)
1832 print('Exception type :', etype)
1700 print('Exception value:', value)
1833 print('Exception value:', value)
1701 print('Traceback :', tb)
1834 print('Traceback :', tb)
1702
1835
1703 def validate_stb(stb):
1836 def validate_stb(stb):
1704 """validate structured traceback return type
1837 """validate structured traceback return type
1705
1838
1706 return type of CustomTB *should* be a list of strings, but allow
1839 return type of CustomTB *should* be a list of strings, but allow
1707 single strings or None, which are harmless.
1840 single strings or None, which are harmless.
1708
1841
1709 This function will *always* return a list of strings,
1842 This function will *always* return a list of strings,
1710 and will raise a TypeError if stb is inappropriate.
1843 and will raise a TypeError if stb is inappropriate.
1711 """
1844 """
1712 msg = "CustomTB must return list of strings, not %r" % stb
1845 msg = "CustomTB must return list of strings, not %r" % stb
1713 if stb is None:
1846 if stb is None:
1714 return []
1847 return []
1715 elif isinstance(stb, str):
1848 elif isinstance(stb, str):
1716 return [stb]
1849 return [stb]
1717 elif not isinstance(stb, list):
1850 elif not isinstance(stb, list):
1718 raise TypeError(msg)
1851 raise TypeError(msg)
1719 # it's a list
1852 # it's a list
1720 for line in stb:
1853 for line in stb:
1721 # check every element
1854 # check every element
1722 if not isinstance(line, str):
1855 if not isinstance(line, str):
1723 raise TypeError(msg)
1856 raise TypeError(msg)
1724 return stb
1857 return stb
1725
1858
1726 if handler is None:
1859 if handler is None:
1727 wrapped = dummy_handler
1860 wrapped = dummy_handler
1728 else:
1861 else:
1729 def wrapped(self,etype,value,tb,tb_offset=None):
1862 def wrapped(self,etype,value,tb,tb_offset=None):
1730 """wrap CustomTB handler, to protect IPython from user code
1863 """wrap CustomTB handler, to protect IPython from user code
1731
1864
1732 This makes it harder (but not impossible) for custom exception
1865 This makes it harder (but not impossible) for custom exception
1733 handlers to crash IPython.
1866 handlers to crash IPython.
1734 """
1867 """
1735 try:
1868 try:
1736 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1869 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1737 return validate_stb(stb)
1870 return validate_stb(stb)
1738 except:
1871 except:
1739 # clear custom handler immediately
1872 # clear custom handler immediately
1740 self.set_custom_exc((), None)
1873 self.set_custom_exc((), None)
1741 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1874 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1742 # show the exception in handler first
1875 # show the exception in handler first
1743 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1876 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1744 print(self.InteractiveTB.stb2text(stb))
1877 print(self.InteractiveTB.stb2text(stb))
1745 print("The original exception:")
1878 print("The original exception:")
1746 stb = self.InteractiveTB.structured_traceback(
1879 stb = self.InteractiveTB.structured_traceback(
1747 (etype,value,tb), tb_offset=tb_offset
1880 (etype,value,tb), tb_offset=tb_offset
1748 )
1881 )
1749 return stb
1882 return stb
1750
1883
1751 self.CustomTB = types.MethodType(wrapped,self)
1884 self.CustomTB = types.MethodType(wrapped,self)
1752 self.custom_exceptions = exc_tuple
1885 self.custom_exceptions = exc_tuple
1753
1886
1754 def excepthook(self, etype, value, tb):
1887 def excepthook(self, etype, value, tb):
1755 """One more defense for GUI apps that call sys.excepthook.
1888 """One more defense for GUI apps that call sys.excepthook.
1756
1889
1757 GUI frameworks like wxPython trap exceptions and call
1890 GUI frameworks like wxPython trap exceptions and call
1758 sys.excepthook themselves. I guess this is a feature that
1891 sys.excepthook themselves. I guess this is a feature that
1759 enables them to keep running after exceptions that would
1892 enables them to keep running after exceptions that would
1760 otherwise kill their mainloop. This is a bother for IPython
1893 otherwise kill their mainloop. This is a bother for IPython
1761 which excepts to catch all of the program exceptions with a try:
1894 which excepts to catch all of the program exceptions with a try:
1762 except: statement.
1895 except: statement.
1763
1896
1764 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1897 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1765 any app directly invokes sys.excepthook, it will look to the user like
1898 any app directly invokes sys.excepthook, it will look to the user like
1766 IPython crashed. In order to work around this, we can disable the
1899 IPython crashed. In order to work around this, we can disable the
1767 CrashHandler and replace it with this excepthook instead, which prints a
1900 CrashHandler and replace it with this excepthook instead, which prints a
1768 regular traceback using our InteractiveTB. In this fashion, apps which
1901 regular traceback using our InteractiveTB. In this fashion, apps which
1769 call sys.excepthook will generate a regular-looking exception from
1902 call sys.excepthook will generate a regular-looking exception from
1770 IPython, and the CrashHandler will only be triggered by real IPython
1903 IPython, and the CrashHandler will only be triggered by real IPython
1771 crashes.
1904 crashes.
1772
1905
1773 This hook should be used sparingly, only in places which are not likely
1906 This hook should be used sparingly, only in places which are not likely
1774 to be true IPython errors.
1907 to be true IPython errors.
1775 """
1908 """
1776 self.showtraceback((etype, value, tb), tb_offset=0)
1909 self.showtraceback((etype, value, tb), tb_offset=0)
1777
1910
1778 def _get_exc_info(self, exc_tuple=None):
1911 def _get_exc_info(self, exc_tuple=None):
1779 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1912 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1780
1913
1781 Ensures sys.last_type,value,traceback hold the exc_info we found,
1914 Ensures sys.last_type,value,traceback hold the exc_info we found,
1782 from whichever source.
1915 from whichever source.
1783
1916
1784 raises ValueError if none of these contain any information
1917 raises ValueError if none of these contain any information
1785 """
1918 """
1786 if exc_tuple is None:
1919 if exc_tuple is None:
1787 etype, value, tb = sys.exc_info()
1920 etype, value, tb = sys.exc_info()
1788 else:
1921 else:
1789 etype, value, tb = exc_tuple
1922 etype, value, tb = exc_tuple
1790
1923
1791 if etype is None:
1924 if etype is None:
1792 if hasattr(sys, 'last_type'):
1925 if hasattr(sys, 'last_type'):
1793 etype, value, tb = sys.last_type, sys.last_value, \
1926 etype, value, tb = sys.last_type, sys.last_value, \
1794 sys.last_traceback
1927 sys.last_traceback
1795
1928
1796 if etype is None:
1929 if etype is None:
1797 raise ValueError("No exception to find")
1930 raise ValueError("No exception to find")
1798
1931
1799 # Now store the exception info in sys.last_type etc.
1932 # Now store the exception info in sys.last_type etc.
1800 # WARNING: these variables are somewhat deprecated and not
1933 # WARNING: these variables are somewhat deprecated and not
1801 # necessarily safe to use in a threaded environment, but tools
1934 # necessarily safe to use in a threaded environment, but tools
1802 # like pdb depend on their existence, so let's set them. If we
1935 # like pdb depend on their existence, so let's set them. If we
1803 # find problems in the field, we'll need to revisit their use.
1936 # find problems in the field, we'll need to revisit their use.
1804 sys.last_type = etype
1937 sys.last_type = etype
1805 sys.last_value = value
1938 sys.last_value = value
1806 sys.last_traceback = tb
1939 sys.last_traceback = tb
1807
1940
1808 return etype, value, tb
1941 return etype, value, tb
1809
1942
1810 def show_usage_error(self, exc):
1943 def show_usage_error(self, exc):
1811 """Show a short message for UsageErrors
1944 """Show a short message for UsageErrors
1812
1945
1813 These are special exceptions that shouldn't show a traceback.
1946 These are special exceptions that shouldn't show a traceback.
1814 """
1947 """
1815 print("UsageError: %s" % exc, file=sys.stderr)
1948 print("UsageError: %s" % exc, file=sys.stderr)
1816
1949
1817 def get_exception_only(self, exc_tuple=None):
1950 def get_exception_only(self, exc_tuple=None):
1818 """
1951 """
1819 Return as a string (ending with a newline) the exception that
1952 Return as a string (ending with a newline) the exception that
1820 just occurred, without any traceback.
1953 just occurred, without any traceback.
1821 """
1954 """
1822 etype, value, tb = self._get_exc_info(exc_tuple)
1955 etype, value, tb = self._get_exc_info(exc_tuple)
1823 msg = traceback.format_exception_only(etype, value)
1956 msg = traceback.format_exception_only(etype, value)
1824 return ''.join(msg)
1957 return ''.join(msg)
1825
1958
1826 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
1959 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
1827 exception_only=False, running_compiled_code=False):
1960 exception_only=False, running_compiled_code=False):
1828 """Display the exception that just occurred.
1961 """Display the exception that just occurred.
1829
1962
1830 If nothing is known about the exception, this is the method which
1963 If nothing is known about the exception, this is the method which
1831 should be used throughout the code for presenting user tracebacks,
1964 should be used throughout the code for presenting user tracebacks,
1832 rather than directly invoking the InteractiveTB object.
1965 rather than directly invoking the InteractiveTB object.
1833
1966
1834 A specific showsyntaxerror() also exists, but this method can take
1967 A specific showsyntaxerror() also exists, but this method can take
1835 care of calling it if needed, so unless you are explicitly catching a
1968 care of calling it if needed, so unless you are explicitly catching a
1836 SyntaxError exception, don't try to analyze the stack manually and
1969 SyntaxError exception, don't try to analyze the stack manually and
1837 simply call this method."""
1970 simply call this method."""
1838
1971
1839 try:
1972 try:
1840 try:
1973 try:
1841 etype, value, tb = self._get_exc_info(exc_tuple)
1974 etype, value, tb = self._get_exc_info(exc_tuple)
1842 except ValueError:
1975 except ValueError:
1843 print('No traceback available to show.', file=sys.stderr)
1976 print('No traceback available to show.', file=sys.stderr)
1844 return
1977 return
1845
1978
1846 if issubclass(etype, SyntaxError):
1979 if issubclass(etype, SyntaxError):
1847 # Though this won't be called by syntax errors in the input
1980 # Though this won't be called by syntax errors in the input
1848 # line, there may be SyntaxError cases with imported code.
1981 # line, there may be SyntaxError cases with imported code.
1849 self.showsyntaxerror(filename, running_compiled_code)
1982 self.showsyntaxerror(filename, running_compiled_code)
1850 elif etype is UsageError:
1983 elif etype is UsageError:
1851 self.show_usage_error(value)
1984 self.show_usage_error(value)
1852 else:
1985 else:
1853 if exception_only:
1986 if exception_only:
1854 stb = ['An exception has occurred, use %tb to see '
1987 stb = ['An exception has occurred, use %tb to see '
1855 'the full traceback.\n']
1988 'the full traceback.\n']
1856 stb.extend(self.InteractiveTB.get_exception_only(etype,
1989 stb.extend(self.InteractiveTB.get_exception_only(etype,
1857 value))
1990 value))
1858 else:
1991 else:
1859 try:
1992 try:
1860 # Exception classes can customise their traceback - we
1993 # Exception classes can customise their traceback - we
1861 # use this in IPython.parallel for exceptions occurring
1994 # use this in IPython.parallel for exceptions occurring
1862 # in the engines. This should return a list of strings.
1995 # in the engines. This should return a list of strings.
1863 stb = value._render_traceback_()
1996 stb = value._render_traceback_()
1864 except Exception:
1997 except Exception:
1865 stb = self.InteractiveTB.structured_traceback(etype,
1998 stb = self.InteractiveTB.structured_traceback(etype,
1866 value, tb, tb_offset=tb_offset)
1999 value, tb, tb_offset=tb_offset)
1867
2000
1868 self._showtraceback(etype, value, stb)
2001 self._showtraceback(etype, value, stb)
1869 if self.call_pdb:
2002 if self.call_pdb:
1870 # drop into debugger
2003 # drop into debugger
1871 self.debugger(force=True)
2004 self.debugger(force=True)
1872 return
2005 return
1873
2006
1874 # Actually show the traceback
2007 # Actually show the traceback
1875 self._showtraceback(etype, value, stb)
2008 self._showtraceback(etype, value, stb)
1876
2009
1877 except KeyboardInterrupt:
2010 except KeyboardInterrupt:
1878 print('\n' + self.get_exception_only(), file=sys.stderr)
2011 print('\n' + self.get_exception_only(), file=sys.stderr)
1879
2012
1880 def _showtraceback(self, etype, evalue, stb):
2013 def _showtraceback(self, etype, evalue, stb):
1881 """Actually show a traceback.
2014 """Actually show a traceback.
1882
2015
1883 Subclasses may override this method to put the traceback on a different
2016 Subclasses may override this method to put the traceback on a different
1884 place, like a side channel.
2017 place, like a side channel.
1885 """
2018 """
1886 print(self.InteractiveTB.stb2text(stb))
2019 print(self.InteractiveTB.stb2text(stb))
1887
2020
1888 def showsyntaxerror(self, filename=None, running_compiled_code=False):
2021 def showsyntaxerror(self, filename=None, running_compiled_code=False):
1889 """Display the syntax error that just occurred.
2022 """Display the syntax error that just occurred.
1890
2023
1891 This doesn't display a stack trace because there isn't one.
2024 This doesn't display a stack trace because there isn't one.
1892
2025
1893 If a filename is given, it is stuffed in the exception instead
2026 If a filename is given, it is stuffed in the exception instead
1894 of what was there before (because Python's parser always uses
2027 of what was there before (because Python's parser always uses
1895 "<string>" when reading from a string).
2028 "<string>" when reading from a string).
1896
2029
1897 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
2030 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
1898 longer stack trace will be displayed.
2031 longer stack trace will be displayed.
1899 """
2032 """
1900 etype, value, last_traceback = self._get_exc_info()
2033 etype, value, last_traceback = self._get_exc_info()
1901
2034
1902 if filename and issubclass(etype, SyntaxError):
2035 if filename and issubclass(etype, SyntaxError):
1903 try:
2036 try:
1904 value.filename = filename
2037 value.filename = filename
1905 except:
2038 except:
1906 # Not the format we expect; leave it alone
2039 # Not the format we expect; leave it alone
1907 pass
2040 pass
1908
2041
1909 # If the error occurred when executing compiled code, we should provide full stacktrace.
2042 # If the error occurred when executing compiled code, we should provide full stacktrace.
1910 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
2043 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
1911 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
2044 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
1912 self._showtraceback(etype, value, stb)
2045 self._showtraceback(etype, value, stb)
1913
2046
1914 # This is overridden in TerminalInteractiveShell to show a message about
2047 # This is overridden in TerminalInteractiveShell to show a message about
1915 # the %paste magic.
2048 # the %paste magic.
1916 def showindentationerror(self):
2049 def showindentationerror(self):
1917 """Called by _run_cell when there's an IndentationError in code entered
2050 """Called by _run_cell when there's an IndentationError in code entered
1918 at the prompt.
2051 at the prompt.
1919
2052
1920 This is overridden in TerminalInteractiveShell to show a message about
2053 This is overridden in TerminalInteractiveShell to show a message about
1921 the %paste magic."""
2054 the %paste magic."""
1922 self.showsyntaxerror()
2055 self.showsyntaxerror()
1923
2056
1924 #-------------------------------------------------------------------------
2057 #-------------------------------------------------------------------------
1925 # Things related to readline
2058 # Things related to readline
1926 #-------------------------------------------------------------------------
2059 #-------------------------------------------------------------------------
1927
2060
1928 def init_readline(self):
2061 def init_readline(self):
1929 """DEPRECATED
2062 """DEPRECATED
1930
2063
1931 Moved to terminal subclass, here only to simplify the init logic."""
2064 Moved to terminal subclass, here only to simplify the init logic."""
1932 # Set a number of methods that depend on readline to be no-op
2065 # Set a number of methods that depend on readline to be no-op
1933 warnings.warn('`init_readline` is no-op since IPython 5.0 and is Deprecated',
2066 warnings.warn('`init_readline` is no-op since IPython 5.0 and is Deprecated',
1934 DeprecationWarning, stacklevel=2)
2067 DeprecationWarning, stacklevel=2)
1935 self.set_custom_completer = no_op
2068 self.set_custom_completer = no_op
1936
2069
1937 @skip_doctest
2070 @skip_doctest
1938 def set_next_input(self, s, replace=False):
2071 def set_next_input(self, s, replace=False):
1939 """ Sets the 'default' input string for the next command line.
2072 """ Sets the 'default' input string for the next command line.
1940
2073
1941 Example::
2074 Example::
1942
2075
1943 In [1]: _ip.set_next_input("Hello Word")
2076 In [1]: _ip.set_next_input("Hello Word")
1944 In [2]: Hello Word_ # cursor is here
2077 In [2]: Hello Word_ # cursor is here
1945 """
2078 """
1946 self.rl_next_input = s
2079 self.rl_next_input = s
1947
2080
1948 def _indent_current_str(self):
2081 def _indent_current_str(self):
1949 """return the current level of indentation as a string"""
2082 """return the current level of indentation as a string"""
1950 return self.input_splitter.get_indent_spaces() * ' '
2083 return self.input_splitter.get_indent_spaces() * ' '
1951
2084
1952 #-------------------------------------------------------------------------
2085 #-------------------------------------------------------------------------
1953 # Things related to text completion
2086 # Things related to text completion
1954 #-------------------------------------------------------------------------
2087 #-------------------------------------------------------------------------
1955
2088
1956 def init_completer(self):
2089 def init_completer(self):
1957 """Initialize the completion machinery.
2090 """Initialize the completion machinery.
1958
2091
1959 This creates completion machinery that can be used by client code,
2092 This creates completion machinery that can be used by client code,
1960 either interactively in-process (typically triggered by the readline
2093 either interactively in-process (typically triggered by the readline
1961 library), programmatically (such as in test suites) or out-of-process
2094 library), programmatically (such as in test suites) or out-of-process
1962 (typically over the network by remote frontends).
2095 (typically over the network by remote frontends).
1963 """
2096 """
1964 from IPython.core.completer import IPCompleter
2097 from IPython.core.completer import IPCompleter
1965 from IPython.core.completerlib import (module_completer,
2098 from IPython.core.completerlib import (module_completer,
1966 magic_run_completer, cd_completer, reset_completer)
2099 magic_run_completer, cd_completer, reset_completer)
1967
2100
1968 self.Completer = IPCompleter(shell=self,
2101 self.Completer = IPCompleter(shell=self,
1969 namespace=self.user_ns,
2102 namespace=self.user_ns,
1970 global_namespace=self.user_global_ns,
2103 global_namespace=self.user_global_ns,
1971 parent=self,
2104 parent=self,
1972 )
2105 )
1973 self.configurables.append(self.Completer)
2106 self.configurables.append(self.Completer)
1974
2107
1975 # Add custom completers to the basic ones built into IPCompleter
2108 # Add custom completers to the basic ones built into IPCompleter
1976 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
2109 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1977 self.strdispatchers['complete_command'] = sdisp
2110 self.strdispatchers['complete_command'] = sdisp
1978 self.Completer.custom_completers = sdisp
2111 self.Completer.custom_completers = sdisp
1979
2112
1980 self.set_hook('complete_command', module_completer, str_key = 'import')
2113 self.set_hook('complete_command', module_completer, str_key = 'import')
1981 self.set_hook('complete_command', module_completer, str_key = 'from')
2114 self.set_hook('complete_command', module_completer, str_key = 'from')
1982 self.set_hook('complete_command', module_completer, str_key = '%aimport')
2115 self.set_hook('complete_command', module_completer, str_key = '%aimport')
1983 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
2116 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1984 self.set_hook('complete_command', cd_completer, str_key = '%cd')
2117 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1985 self.set_hook('complete_command', reset_completer, str_key = '%reset')
2118 self.set_hook('complete_command', reset_completer, str_key = '%reset')
1986
2119
1987
1988 @skip_doctest
2120 @skip_doctest
1989 def complete(self, text, line=None, cursor_pos=None):
2121 def complete(self, text, line=None, cursor_pos=None):
1990 """Return the completed text and a list of completions.
2122 """Return the completed text and a list of completions.
1991
2123
1992 Parameters
2124 Parameters
1993 ----------
2125 ----------
1994
2126
1995 text : string
2127 text : string
1996 A string of text to be completed on. It can be given as empty and
2128 A string of text to be completed on. It can be given as empty and
1997 instead a line/position pair are given. In this case, the
2129 instead a line/position pair are given. In this case, the
1998 completer itself will split the line like readline does.
2130 completer itself will split the line like readline does.
1999
2131
2000 line : string, optional
2132 line : string, optional
2001 The complete line that text is part of.
2133 The complete line that text is part of.
2002
2134
2003 cursor_pos : int, optional
2135 cursor_pos : int, optional
2004 The position of the cursor on the input line.
2136 The position of the cursor on the input line.
2005
2137
2006 Returns
2138 Returns
2007 -------
2139 -------
2008 text : string
2140 text : string
2009 The actual text that was completed.
2141 The actual text that was completed.
2010
2142
2011 matches : list
2143 matches : list
2012 A sorted list with all possible completions.
2144 A sorted list with all possible completions.
2013
2145
2014 The optional arguments allow the completion to take more context into
2146 The optional arguments allow the completion to take more context into
2015 account, and are part of the low-level completion API.
2147 account, and are part of the low-level completion API.
2016
2148
2017 This is a wrapper around the completion mechanism, similar to what
2149 This is a wrapper around the completion mechanism, similar to what
2018 readline does at the command line when the TAB key is hit. By
2150 readline does at the command line when the TAB key is hit. By
2019 exposing it as a method, it can be used by other non-readline
2151 exposing it as a method, it can be used by other non-readline
2020 environments (such as GUIs) for text completion.
2152 environments (such as GUIs) for text completion.
2021
2153
2022 Simple usage example:
2154 Simple usage example:
2023
2155
2024 In [1]: x = 'hello'
2156 In [1]: x = 'hello'
2025
2157
2026 In [2]: _ip.complete('x.l')
2158 In [2]: _ip.complete('x.l')
2027 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2159 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2028 """
2160 """
2029
2161
2030 # Inject names into __builtin__ so we can complete on the added names.
2162 # Inject names into __builtin__ so we can complete on the added names.
2031 with self.builtin_trap:
2163 with self.builtin_trap:
2032 return self.Completer.complete(text, line, cursor_pos)
2164 return self.Completer.complete(text, line, cursor_pos)
2033
2165
2034 def set_custom_completer(self, completer, pos=0):
2166 def set_custom_completer(self, completer, pos=0):
2035 """Adds a new custom completer function.
2167 """Adds a new custom completer function.
2036
2168
2037 The position argument (defaults to 0) is the index in the completers
2169 The position argument (defaults to 0) is the index in the completers
2038 list where you want the completer to be inserted."""
2170 list where you want the completer to be inserted."""
2039
2171
2040 newcomp = types.MethodType(completer,self.Completer)
2172 newcomp = types.MethodType(completer,self.Completer)
2041 self.Completer.matchers.insert(pos,newcomp)
2173 self.Completer.matchers.insert(pos,newcomp)
2042
2174
2043 def set_completer_frame(self, frame=None):
2175 def set_completer_frame(self, frame=None):
2044 """Set the frame of the completer."""
2176 """Set the frame of the completer."""
2045 if frame:
2177 if frame:
2046 self.Completer.namespace = frame.f_locals
2178 self.Completer.namespace = frame.f_locals
2047 self.Completer.global_namespace = frame.f_globals
2179 self.Completer.global_namespace = frame.f_globals
2048 else:
2180 else:
2049 self.Completer.namespace = self.user_ns
2181 self.Completer.namespace = self.user_ns
2050 self.Completer.global_namespace = self.user_global_ns
2182 self.Completer.global_namespace = self.user_global_ns
2051
2183
2052 #-------------------------------------------------------------------------
2184 #-------------------------------------------------------------------------
2053 # Things related to magics
2185 # Things related to magics
2054 #-------------------------------------------------------------------------
2186 #-------------------------------------------------------------------------
2055
2187
2056 def init_magics(self):
2188 def init_magics(self):
2057 from IPython.core import magics as m
2189 from IPython.core import magics as m
2058 self.magics_manager = magic.MagicsManager(shell=self,
2190 self.magics_manager = magic.MagicsManager(shell=self,
2059 parent=self,
2191 parent=self,
2060 user_magics=m.UserMagics(self))
2192 user_magics=m.UserMagics(self))
2061 self.configurables.append(self.magics_manager)
2193 self.configurables.append(self.magics_manager)
2062
2194
2063 # Expose as public API from the magics manager
2195 # Expose as public API from the magics manager
2064 self.register_magics = self.magics_manager.register
2196 self.register_magics = self.magics_manager.register
2065
2197
2066 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2198 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2067 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2199 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2068 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2200 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2069 m.NamespaceMagics, m.OSMagics, m.PylabMagics, m.ScriptMagics,
2201 m.NamespaceMagics, m.OSMagics, m.PylabMagics, m.ScriptMagics,
2070 )
2202 )
2071
2203
2072 # Register Magic Aliases
2204 # Register Magic Aliases
2073 mman = self.magics_manager
2205 mman = self.magics_manager
2074 # FIXME: magic aliases should be defined by the Magics classes
2206 # FIXME: magic aliases should be defined by the Magics classes
2075 # or in MagicsManager, not here
2207 # or in MagicsManager, not here
2076 mman.register_alias('ed', 'edit')
2208 mman.register_alias('ed', 'edit')
2077 mman.register_alias('hist', 'history')
2209 mman.register_alias('hist', 'history')
2078 mman.register_alias('rep', 'recall')
2210 mman.register_alias('rep', 'recall')
2079 mman.register_alias('SVG', 'svg', 'cell')
2211 mman.register_alias('SVG', 'svg', 'cell')
2080 mman.register_alias('HTML', 'html', 'cell')
2212 mman.register_alias('HTML', 'html', 'cell')
2081 mman.register_alias('file', 'writefile', 'cell')
2213 mman.register_alias('file', 'writefile', 'cell')
2082
2214
2083 # FIXME: Move the color initialization to the DisplayHook, which
2215 # FIXME: Move the color initialization to the DisplayHook, which
2084 # should be split into a prompt manager and displayhook. We probably
2216 # should be split into a prompt manager and displayhook. We probably
2085 # even need a centralize colors management object.
2217 # even need a centralize colors management object.
2086 self.run_line_magic('colors', self.colors)
2218 self.run_line_magic('colors', self.colors)
2087
2219
2088 # Defined here so that it's included in the documentation
2220 # Defined here so that it's included in the documentation
2089 @functools.wraps(magic.MagicsManager.register_function)
2221 @functools.wraps(magic.MagicsManager.register_function)
2090 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2222 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2091 self.magics_manager.register_function(func,
2223 self.magics_manager.register_function(func,
2092 magic_kind=magic_kind, magic_name=magic_name)
2224 magic_kind=magic_kind, magic_name=magic_name)
2093
2225
2094 def run_line_magic(self, magic_name, line, _stack_depth=1):
2226 def run_line_magic(self, magic_name, line, _stack_depth=1):
2095 """Execute the given line magic.
2227 """Execute the given line magic.
2096
2228
2097 Parameters
2229 Parameters
2098 ----------
2230 ----------
2099 magic_name : str
2231 magic_name : str
2100 Name of the desired magic function, without '%' prefix.
2232 Name of the desired magic function, without '%' prefix.
2101
2233
2102 line : str
2234 line : str
2103 The rest of the input line as a single string.
2235 The rest of the input line as a single string.
2104
2236
2105 _stack_depth : int
2237 _stack_depth : int
2106 If run_line_magic() is called from magic() then _stack_depth=2.
2238 If run_line_magic() is called from magic() then _stack_depth=2.
2107 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2239 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2108 """
2240 """
2109 fn = self.find_line_magic(magic_name)
2241 fn = self.find_line_magic(magic_name)
2110 if fn is None:
2242 if fn is None:
2111 cm = self.find_cell_magic(magic_name)
2243 cm = self.find_cell_magic(magic_name)
2112 etpl = "Line magic function `%%%s` not found%s."
2244 etpl = "Line magic function `%%%s` not found%s."
2113 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2245 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2114 'did you mean that instead?)' % magic_name )
2246 'did you mean that instead?)' % magic_name )
2115 raise UsageError(etpl % (magic_name, extra))
2247 raise UsageError(etpl % (magic_name, extra))
2116 else:
2248 else:
2117 # Note: this is the distance in the stack to the user's frame.
2249 # Note: this is the distance in the stack to the user's frame.
2118 # This will need to be updated if the internal calling logic gets
2250 # This will need to be updated if the internal calling logic gets
2119 # refactored, or else we'll be expanding the wrong variables.
2251 # refactored, or else we'll be expanding the wrong variables.
2120
2252
2121 # Determine stack_depth depending on where run_line_magic() has been called
2253 # Determine stack_depth depending on where run_line_magic() has been called
2122 stack_depth = _stack_depth
2254 stack_depth = _stack_depth
2123 magic_arg_s = self.var_expand(line, stack_depth)
2255 magic_arg_s = self.var_expand(line, stack_depth)
2124 # Put magic args in a list so we can call with f(*a) syntax
2256 # Put magic args in a list so we can call with f(*a) syntax
2125 args = [magic_arg_s]
2257 args = [magic_arg_s]
2126 kwargs = {}
2258 kwargs = {}
2127 # Grab local namespace if we need it:
2259 # Grab local namespace if we need it:
2128 if getattr(fn, "needs_local_scope", False):
2260 if getattr(fn, "needs_local_scope", False):
2129 kwargs['local_ns'] = sys._getframe(stack_depth).f_locals
2261 kwargs['local_ns'] = sys._getframe(stack_depth).f_locals
2130 with self.builtin_trap:
2262 with self.builtin_trap:
2131 result = fn(*args,**kwargs)
2263 result = fn(*args,**kwargs)
2132 return result
2264 return result
2133
2265
2134 def run_cell_magic(self, magic_name, line, cell):
2266 def run_cell_magic(self, magic_name, line, cell):
2135 """Execute the given cell magic.
2267 """Execute the given cell magic.
2136
2268
2137 Parameters
2269 Parameters
2138 ----------
2270 ----------
2139 magic_name : str
2271 magic_name : str
2140 Name of the desired magic function, without '%' prefix.
2272 Name of the desired magic function, without '%' prefix.
2141
2273
2142 line : str
2274 line : str
2143 The rest of the first input line as a single string.
2275 The rest of the first input line as a single string.
2144
2276
2145 cell : str
2277 cell : str
2146 The body of the cell as a (possibly multiline) string.
2278 The body of the cell as a (possibly multiline) string.
2147 """
2279 """
2148 fn = self.find_cell_magic(magic_name)
2280 fn = self.find_cell_magic(magic_name)
2149 if fn is None:
2281 if fn is None:
2150 lm = self.find_line_magic(magic_name)
2282 lm = self.find_line_magic(magic_name)
2151 etpl = "Cell magic `%%{0}` not found{1}."
2283 etpl = "Cell magic `%%{0}` not found{1}."
2152 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2284 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2153 'did you mean that instead?)'.format(magic_name))
2285 'did you mean that instead?)'.format(magic_name))
2154 raise UsageError(etpl.format(magic_name, extra))
2286 raise UsageError(etpl.format(magic_name, extra))
2155 elif cell == '':
2287 elif cell == '':
2156 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2288 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2157 if self.find_line_magic(magic_name) is not None:
2289 if self.find_line_magic(magic_name) is not None:
2158 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2290 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2159 raise UsageError(message)
2291 raise UsageError(message)
2160 else:
2292 else:
2161 # Note: this is the distance in the stack to the user's frame.
2293 # Note: this is the distance in the stack to the user's frame.
2162 # This will need to be updated if the internal calling logic gets
2294 # This will need to be updated if the internal calling logic gets
2163 # refactored, or else we'll be expanding the wrong variables.
2295 # refactored, or else we'll be expanding the wrong variables.
2164 stack_depth = 2
2296 stack_depth = 2
2165 magic_arg_s = self.var_expand(line, stack_depth)
2297 magic_arg_s = self.var_expand(line, stack_depth)
2166 with self.builtin_trap:
2298 with self.builtin_trap:
2167 result = fn(magic_arg_s, cell)
2299 result = fn(magic_arg_s, cell)
2168 return result
2300 return result
2169
2301
2170 def find_line_magic(self, magic_name):
2302 def find_line_magic(self, magic_name):
2171 """Find and return a line magic by name.
2303 """Find and return a line magic by name.
2172
2304
2173 Returns None if the magic isn't found."""
2305 Returns None if the magic isn't found."""
2174 return self.magics_manager.magics['line'].get(magic_name)
2306 return self.magics_manager.magics['line'].get(magic_name)
2175
2307
2176 def find_cell_magic(self, magic_name):
2308 def find_cell_magic(self, magic_name):
2177 """Find and return a cell magic by name.
2309 """Find and return a cell magic by name.
2178
2310
2179 Returns None if the magic isn't found."""
2311 Returns None if the magic isn't found."""
2180 return self.magics_manager.magics['cell'].get(magic_name)
2312 return self.magics_manager.magics['cell'].get(magic_name)
2181
2313
2182 def find_magic(self, magic_name, magic_kind='line'):
2314 def find_magic(self, magic_name, magic_kind='line'):
2183 """Find and return a magic of the given type by name.
2315 """Find and return a magic of the given type by name.
2184
2316
2185 Returns None if the magic isn't found."""
2317 Returns None if the magic isn't found."""
2186 return self.magics_manager.magics[magic_kind].get(magic_name)
2318 return self.magics_manager.magics[magic_kind].get(magic_name)
2187
2319
2188 def magic(self, arg_s):
2320 def magic(self, arg_s):
2189 """DEPRECATED. Use run_line_magic() instead.
2321 """DEPRECATED. Use run_line_magic() instead.
2190
2322
2191 Call a magic function by name.
2323 Call a magic function by name.
2192
2324
2193 Input: a string containing the name of the magic function to call and
2325 Input: a string containing the name of the magic function to call and
2194 any additional arguments to be passed to the magic.
2326 any additional arguments to be passed to the magic.
2195
2327
2196 magic('name -opt foo bar') is equivalent to typing at the ipython
2328 magic('name -opt foo bar') is equivalent to typing at the ipython
2197 prompt:
2329 prompt:
2198
2330
2199 In[1]: %name -opt foo bar
2331 In[1]: %name -opt foo bar
2200
2332
2201 To call a magic without arguments, simply use magic('name').
2333 To call a magic without arguments, simply use magic('name').
2202
2334
2203 This provides a proper Python function to call IPython's magics in any
2335 This provides a proper Python function to call IPython's magics in any
2204 valid Python code you can type at the interpreter, including loops and
2336 valid Python code you can type at the interpreter, including loops and
2205 compound statements.
2337 compound statements.
2206 """
2338 """
2207 # TODO: should we issue a loud deprecation warning here?
2339 # TODO: should we issue a loud deprecation warning here?
2208 magic_name, _, magic_arg_s = arg_s.partition(' ')
2340 magic_name, _, magic_arg_s = arg_s.partition(' ')
2209 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2341 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2210 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2342 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2211
2343
2212 #-------------------------------------------------------------------------
2344 #-------------------------------------------------------------------------
2213 # Things related to macros
2345 # Things related to macros
2214 #-------------------------------------------------------------------------
2346 #-------------------------------------------------------------------------
2215
2347
2216 def define_macro(self, name, themacro):
2348 def define_macro(self, name, themacro):
2217 """Define a new macro
2349 """Define a new macro
2218
2350
2219 Parameters
2351 Parameters
2220 ----------
2352 ----------
2221 name : str
2353 name : str
2222 The name of the macro.
2354 The name of the macro.
2223 themacro : str or Macro
2355 themacro : str or Macro
2224 The action to do upon invoking the macro. If a string, a new
2356 The action to do upon invoking the macro. If a string, a new
2225 Macro object is created by passing the string to it.
2357 Macro object is created by passing the string to it.
2226 """
2358 """
2227
2359
2228 from IPython.core import macro
2360 from IPython.core import macro
2229
2361
2230 if isinstance(themacro, str):
2362 if isinstance(themacro, str):
2231 themacro = macro.Macro(themacro)
2363 themacro = macro.Macro(themacro)
2232 if not isinstance(themacro, macro.Macro):
2364 if not isinstance(themacro, macro.Macro):
2233 raise ValueError('A macro must be a string or a Macro instance.')
2365 raise ValueError('A macro must be a string or a Macro instance.')
2234 self.user_ns[name] = themacro
2366 self.user_ns[name] = themacro
2235
2367
2236 #-------------------------------------------------------------------------
2368 #-------------------------------------------------------------------------
2237 # Things related to the running of system commands
2369 # Things related to the running of system commands
2238 #-------------------------------------------------------------------------
2370 #-------------------------------------------------------------------------
2239
2371
2240 def system_piped(self, cmd):
2372 def system_piped(self, cmd):
2241 """Call the given cmd in a subprocess, piping stdout/err
2373 """Call the given cmd in a subprocess, piping stdout/err
2242
2374
2243 Parameters
2375 Parameters
2244 ----------
2376 ----------
2245 cmd : str
2377 cmd : str
2246 Command to execute (can not end in '&', as background processes are
2378 Command to execute (can not end in '&', as background processes are
2247 not supported. Should not be a command that expects input
2379 not supported. Should not be a command that expects input
2248 other than simple text.
2380 other than simple text.
2249 """
2381 """
2250 if cmd.rstrip().endswith('&'):
2382 if cmd.rstrip().endswith('&'):
2251 # this is *far* from a rigorous test
2383 # this is *far* from a rigorous test
2252 # We do not support backgrounding processes because we either use
2384 # We do not support backgrounding processes because we either use
2253 # pexpect or pipes to read from. Users can always just call
2385 # pexpect or pipes to read from. Users can always just call
2254 # os.system() or use ip.system=ip.system_raw
2386 # os.system() or use ip.system=ip.system_raw
2255 # if they really want a background process.
2387 # if they really want a background process.
2256 raise OSError("Background processes not supported.")
2388 raise OSError("Background processes not supported.")
2257
2389
2258 # we explicitly do NOT return the subprocess status code, because
2390 # we explicitly do NOT return the subprocess status code, because
2259 # a non-None value would trigger :func:`sys.displayhook` calls.
2391 # a non-None value would trigger :func:`sys.displayhook` calls.
2260 # Instead, we store the exit_code in user_ns.
2392 # Instead, we store the exit_code in user_ns.
2261 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2393 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2262
2394
2263 def system_raw(self, cmd):
2395 def system_raw(self, cmd):
2264 """Call the given cmd in a subprocess using os.system on Windows or
2396 """Call the given cmd in a subprocess using os.system on Windows or
2265 subprocess.call using the system shell on other platforms.
2397 subprocess.call using the system shell on other platforms.
2266
2398
2267 Parameters
2399 Parameters
2268 ----------
2400 ----------
2269 cmd : str
2401 cmd : str
2270 Command to execute.
2402 Command to execute.
2271 """
2403 """
2272 cmd = self.var_expand(cmd, depth=1)
2404 cmd = self.var_expand(cmd, depth=1)
2273 # protect os.system from UNC paths on Windows, which it can't handle:
2405 # protect os.system from UNC paths on Windows, which it can't handle:
2274 if sys.platform == 'win32':
2406 if sys.platform == 'win32':
2275 from IPython.utils._process_win32 import AvoidUNCPath
2407 from IPython.utils._process_win32 import AvoidUNCPath
2276 with AvoidUNCPath() as path:
2408 with AvoidUNCPath() as path:
2277 if path is not None:
2409 if path is not None:
2278 cmd = '"pushd %s &&"%s' % (path, cmd)
2410 cmd = '"pushd %s &&"%s' % (path, cmd)
2279 try:
2411 try:
2280 ec = os.system(cmd)
2412 ec = os.system(cmd)
2281 except KeyboardInterrupt:
2413 except KeyboardInterrupt:
2282 print('\n' + self.get_exception_only(), file=sys.stderr)
2414 print('\n' + self.get_exception_only(), file=sys.stderr)
2283 ec = -2
2415 ec = -2
2284 else:
2416 else:
2285 # For posix the result of the subprocess.call() below is an exit
2417 # For posix the result of the subprocess.call() below is an exit
2286 # code, which by convention is zero for success, positive for
2418 # code, which by convention is zero for success, positive for
2287 # program failure. Exit codes above 128 are reserved for signals,
2419 # program failure. Exit codes above 128 are reserved for signals,
2288 # and the formula for converting a signal to an exit code is usually
2420 # and the formula for converting a signal to an exit code is usually
2289 # signal_number+128. To more easily differentiate between exit
2421 # signal_number+128. To more easily differentiate between exit
2290 # codes and signals, ipython uses negative numbers. For instance
2422 # codes and signals, ipython uses negative numbers. For instance
2291 # since control-c is signal 2 but exit code 130, ipython's
2423 # since control-c is signal 2 but exit code 130, ipython's
2292 # _exit_code variable will read -2. Note that some shells like
2424 # _exit_code variable will read -2. Note that some shells like
2293 # csh and fish don't follow sh/bash conventions for exit codes.
2425 # csh and fish don't follow sh/bash conventions for exit codes.
2294 executable = os.environ.get('SHELL', None)
2426 executable = os.environ.get('SHELL', None)
2295 try:
2427 try:
2296 # Use env shell instead of default /bin/sh
2428 # Use env shell instead of default /bin/sh
2297 ec = subprocess.call(cmd, shell=True, executable=executable)
2429 ec = subprocess.call(cmd, shell=True, executable=executable)
2298 except KeyboardInterrupt:
2430 except KeyboardInterrupt:
2299 # intercept control-C; a long traceback is not useful here
2431 # intercept control-C; a long traceback is not useful here
2300 print('\n' + self.get_exception_only(), file=sys.stderr)
2432 print('\n' + self.get_exception_only(), file=sys.stderr)
2301 ec = 130
2433 ec = 130
2302 if ec > 128:
2434 if ec > 128:
2303 ec = -(ec - 128)
2435 ec = -(ec - 128)
2304
2436
2305 # We explicitly do NOT return the subprocess status code, because
2437 # We explicitly do NOT return the subprocess status code, because
2306 # a non-None value would trigger :func:`sys.displayhook` calls.
2438 # a non-None value would trigger :func:`sys.displayhook` calls.
2307 # Instead, we store the exit_code in user_ns. Note the semantics
2439 # Instead, we store the exit_code in user_ns. Note the semantics
2308 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2440 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2309 # but raising SystemExit(_exit_code) will give status 254!
2441 # but raising SystemExit(_exit_code) will give status 254!
2310 self.user_ns['_exit_code'] = ec
2442 self.user_ns['_exit_code'] = ec
2311
2443
2312 # use piped system by default, because it is better behaved
2444 # use piped system by default, because it is better behaved
2313 system = system_piped
2445 system = system_piped
2314
2446
2315 def getoutput(self, cmd, split=True, depth=0):
2447 def getoutput(self, cmd, split=True, depth=0):
2316 """Get output (possibly including stderr) from a subprocess.
2448 """Get output (possibly including stderr) from a subprocess.
2317
2449
2318 Parameters
2450 Parameters
2319 ----------
2451 ----------
2320 cmd : str
2452 cmd : str
2321 Command to execute (can not end in '&', as background processes are
2453 Command to execute (can not end in '&', as background processes are
2322 not supported.
2454 not supported.
2323 split : bool, optional
2455 split : bool, optional
2324 If True, split the output into an IPython SList. Otherwise, an
2456 If True, split the output into an IPython SList. Otherwise, an
2325 IPython LSString is returned. These are objects similar to normal
2457 IPython LSString is returned. These are objects similar to normal
2326 lists and strings, with a few convenience attributes for easier
2458 lists and strings, with a few convenience attributes for easier
2327 manipulation of line-based output. You can use '?' on them for
2459 manipulation of line-based output. You can use '?' on them for
2328 details.
2460 details.
2329 depth : int, optional
2461 depth : int, optional
2330 How many frames above the caller are the local variables which should
2462 How many frames above the caller are the local variables which should
2331 be expanded in the command string? The default (0) assumes that the
2463 be expanded in the command string? The default (0) assumes that the
2332 expansion variables are in the stack frame calling this function.
2464 expansion variables are in the stack frame calling this function.
2333 """
2465 """
2334 if cmd.rstrip().endswith('&'):
2466 if cmd.rstrip().endswith('&'):
2335 # this is *far* from a rigorous test
2467 # this is *far* from a rigorous test
2336 raise OSError("Background processes not supported.")
2468 raise OSError("Background processes not supported.")
2337 out = getoutput(self.var_expand(cmd, depth=depth+1))
2469 out = getoutput(self.var_expand(cmd, depth=depth+1))
2338 if split:
2470 if split:
2339 out = SList(out.splitlines())
2471 out = SList(out.splitlines())
2340 else:
2472 else:
2341 out = LSString(out)
2473 out = LSString(out)
2342 return out
2474 return out
2343
2475
2344 #-------------------------------------------------------------------------
2476 #-------------------------------------------------------------------------
2345 # Things related to aliases
2477 # Things related to aliases
2346 #-------------------------------------------------------------------------
2478 #-------------------------------------------------------------------------
2347
2479
2348 def init_alias(self):
2480 def init_alias(self):
2349 self.alias_manager = AliasManager(shell=self, parent=self)
2481 self.alias_manager = AliasManager(shell=self, parent=self)
2350 self.configurables.append(self.alias_manager)
2482 self.configurables.append(self.alias_manager)
2351
2483
2352 #-------------------------------------------------------------------------
2484 #-------------------------------------------------------------------------
2353 # Things related to extensions
2485 # Things related to extensions
2354 #-------------------------------------------------------------------------
2486 #-------------------------------------------------------------------------
2355
2487
2356 def init_extension_manager(self):
2488 def init_extension_manager(self):
2357 self.extension_manager = ExtensionManager(shell=self, parent=self)
2489 self.extension_manager = ExtensionManager(shell=self, parent=self)
2358 self.configurables.append(self.extension_manager)
2490 self.configurables.append(self.extension_manager)
2359
2491
2360 #-------------------------------------------------------------------------
2492 #-------------------------------------------------------------------------
2361 # Things related to payloads
2493 # Things related to payloads
2362 #-------------------------------------------------------------------------
2494 #-------------------------------------------------------------------------
2363
2495
2364 def init_payload(self):
2496 def init_payload(self):
2365 self.payload_manager = PayloadManager(parent=self)
2497 self.payload_manager = PayloadManager(parent=self)
2366 self.configurables.append(self.payload_manager)
2498 self.configurables.append(self.payload_manager)
2367
2499
2368 #-------------------------------------------------------------------------
2500 #-------------------------------------------------------------------------
2369 # Things related to the prefilter
2501 # Things related to the prefilter
2370 #-------------------------------------------------------------------------
2502 #-------------------------------------------------------------------------
2371
2503
2372 def init_prefilter(self):
2504 def init_prefilter(self):
2373 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2505 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2374 self.configurables.append(self.prefilter_manager)
2506 self.configurables.append(self.prefilter_manager)
2375 # Ultimately this will be refactored in the new interpreter code, but
2507 # Ultimately this will be refactored in the new interpreter code, but
2376 # for now, we should expose the main prefilter method (there's legacy
2508 # for now, we should expose the main prefilter method (there's legacy
2377 # code out there that may rely on this).
2509 # code out there that may rely on this).
2378 self.prefilter = self.prefilter_manager.prefilter_lines
2510 self.prefilter = self.prefilter_manager.prefilter_lines
2379
2511
2380 def auto_rewrite_input(self, cmd):
2512 def auto_rewrite_input(self, cmd):
2381 """Print to the screen the rewritten form of the user's command.
2513 """Print to the screen the rewritten form of the user's command.
2382
2514
2383 This shows visual feedback by rewriting input lines that cause
2515 This shows visual feedback by rewriting input lines that cause
2384 automatic calling to kick in, like::
2516 automatic calling to kick in, like::
2385
2517
2386 /f x
2518 /f x
2387
2519
2388 into::
2520 into::
2389
2521
2390 ------> f(x)
2522 ------> f(x)
2391
2523
2392 after the user's input prompt. This helps the user understand that the
2524 after the user's input prompt. This helps the user understand that the
2393 input line was transformed automatically by IPython.
2525 input line was transformed automatically by IPython.
2394 """
2526 """
2395 if not self.show_rewritten_input:
2527 if not self.show_rewritten_input:
2396 return
2528 return
2397
2529
2398 # This is overridden in TerminalInteractiveShell to use fancy prompts
2530 # This is overridden in TerminalInteractiveShell to use fancy prompts
2399 print("------> " + cmd)
2531 print("------> " + cmd)
2400
2532
2401 #-------------------------------------------------------------------------
2533 #-------------------------------------------------------------------------
2402 # Things related to extracting values/expressions from kernel and user_ns
2534 # Things related to extracting values/expressions from kernel and user_ns
2403 #-------------------------------------------------------------------------
2535 #-------------------------------------------------------------------------
2404
2536
2405 def _user_obj_error(self):
2537 def _user_obj_error(self):
2406 """return simple exception dict
2538 """return simple exception dict
2407
2539
2408 for use in user_expressions
2540 for use in user_expressions
2409 """
2541 """
2410
2542
2411 etype, evalue, tb = self._get_exc_info()
2543 etype, evalue, tb = self._get_exc_info()
2412 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2544 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2413
2545
2414 exc_info = {
2546 exc_info = {
2415 u'status' : 'error',
2547 u'status' : 'error',
2416 u'traceback' : stb,
2548 u'traceback' : stb,
2417 u'ename' : etype.__name__,
2549 u'ename' : etype.__name__,
2418 u'evalue' : py3compat.safe_unicode(evalue),
2550 u'evalue' : py3compat.safe_unicode(evalue),
2419 }
2551 }
2420
2552
2421 return exc_info
2553 return exc_info
2422
2554
2423 def _format_user_obj(self, obj):
2555 def _format_user_obj(self, obj):
2424 """format a user object to display dict
2556 """format a user object to display dict
2425
2557
2426 for use in user_expressions
2558 for use in user_expressions
2427 """
2559 """
2428
2560
2429 data, md = self.display_formatter.format(obj)
2561 data, md = self.display_formatter.format(obj)
2430 value = {
2562 value = {
2431 'status' : 'ok',
2563 'status' : 'ok',
2432 'data' : data,
2564 'data' : data,
2433 'metadata' : md,
2565 'metadata' : md,
2434 }
2566 }
2435 return value
2567 return value
2436
2568
2437 def user_expressions(self, expressions):
2569 def user_expressions(self, expressions):
2438 """Evaluate a dict of expressions in the user's namespace.
2570 """Evaluate a dict of expressions in the user's namespace.
2439
2571
2440 Parameters
2572 Parameters
2441 ----------
2573 ----------
2442 expressions : dict
2574 expressions : dict
2443 A dict with string keys and string values. The expression values
2575 A dict with string keys and string values. The expression values
2444 should be valid Python expressions, each of which will be evaluated
2576 should be valid Python expressions, each of which will be evaluated
2445 in the user namespace.
2577 in the user namespace.
2446
2578
2447 Returns
2579 Returns
2448 -------
2580 -------
2449 A dict, keyed like the input expressions dict, with the rich mime-typed
2581 A dict, keyed like the input expressions dict, with the rich mime-typed
2450 display_data of each value.
2582 display_data of each value.
2451 """
2583 """
2452 out = {}
2584 out = {}
2453 user_ns = self.user_ns
2585 user_ns = self.user_ns
2454 global_ns = self.user_global_ns
2586 global_ns = self.user_global_ns
2455
2587
2456 for key, expr in expressions.items():
2588 for key, expr in expressions.items():
2457 try:
2589 try:
2458 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2590 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2459 except:
2591 except:
2460 value = self._user_obj_error()
2592 value = self._user_obj_error()
2461 out[key] = value
2593 out[key] = value
2462 return out
2594 return out
2463
2595
2464 #-------------------------------------------------------------------------
2596 #-------------------------------------------------------------------------
2465 # Things related to the running of code
2597 # Things related to the running of code
2466 #-------------------------------------------------------------------------
2598 #-------------------------------------------------------------------------
2467
2599
2468 def ex(self, cmd):
2600 def ex(self, cmd):
2469 """Execute a normal python statement in user namespace."""
2601 """Execute a normal python statement in user namespace."""
2470 with self.builtin_trap:
2602 with self.builtin_trap:
2471 exec(cmd, self.user_global_ns, self.user_ns)
2603 exec(cmd, self.user_global_ns, self.user_ns)
2472
2604
2473 def ev(self, expr):
2605 def ev(self, expr):
2474 """Evaluate python expression expr in user namespace.
2606 """Evaluate python expression expr in user namespace.
2475
2607
2476 Returns the result of evaluation
2608 Returns the result of evaluation
2477 """
2609 """
2478 with self.builtin_trap:
2610 with self.builtin_trap:
2479 return eval(expr, self.user_global_ns, self.user_ns)
2611 return eval(expr, self.user_global_ns, self.user_ns)
2480
2612
2481 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2613 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2482 """A safe version of the builtin execfile().
2614 """A safe version of the builtin execfile().
2483
2615
2484 This version will never throw an exception, but instead print
2616 This version will never throw an exception, but instead print
2485 helpful error messages to the screen. This only works on pure
2617 helpful error messages to the screen. This only works on pure
2486 Python files with the .py extension.
2618 Python files with the .py extension.
2487
2619
2488 Parameters
2620 Parameters
2489 ----------
2621 ----------
2490 fname : string
2622 fname : string
2491 The name of the file to be executed.
2623 The name of the file to be executed.
2492 where : tuple
2624 where : tuple
2493 One or two namespaces, passed to execfile() as (globals,locals).
2625 One or two namespaces, passed to execfile() as (globals,locals).
2494 If only one is given, it is passed as both.
2626 If only one is given, it is passed as both.
2495 exit_ignore : bool (False)
2627 exit_ignore : bool (False)
2496 If True, then silence SystemExit for non-zero status (it is always
2628 If True, then silence SystemExit for non-zero status (it is always
2497 silenced for zero status, as it is so common).
2629 silenced for zero status, as it is so common).
2498 raise_exceptions : bool (False)
2630 raise_exceptions : bool (False)
2499 If True raise exceptions everywhere. Meant for testing.
2631 If True raise exceptions everywhere. Meant for testing.
2500 shell_futures : bool (False)
2632 shell_futures : bool (False)
2501 If True, the code will share future statements with the interactive
2633 If True, the code will share future statements with the interactive
2502 shell. It will both be affected by previous __future__ imports, and
2634 shell. It will both be affected by previous __future__ imports, and
2503 any __future__ imports in the code will affect the shell. If False,
2635 any __future__ imports in the code will affect the shell. If False,
2504 __future__ imports are not shared in either direction.
2636 __future__ imports are not shared in either direction.
2505
2637
2506 """
2638 """
2507 fname = os.path.abspath(os.path.expanduser(fname))
2639 fname = os.path.abspath(os.path.expanduser(fname))
2508
2640
2509 # Make sure we can open the file
2641 # Make sure we can open the file
2510 try:
2642 try:
2511 with open(fname):
2643 with open(fname):
2512 pass
2644 pass
2513 except:
2645 except:
2514 warn('Could not open file <%s> for safe execution.' % fname)
2646 warn('Could not open file <%s> for safe execution.' % fname)
2515 return
2647 return
2516
2648
2517 # Find things also in current directory. This is needed to mimic the
2649 # Find things also in current directory. This is needed to mimic the
2518 # behavior of running a script from the system command line, where
2650 # behavior of running a script from the system command line, where
2519 # Python inserts the script's directory into sys.path
2651 # Python inserts the script's directory into sys.path
2520 dname = os.path.dirname(fname)
2652 dname = os.path.dirname(fname)
2521
2653
2522 with prepended_to_syspath(dname), self.builtin_trap:
2654 with prepended_to_syspath(dname), self.builtin_trap:
2523 try:
2655 try:
2524 glob, loc = (where + (None, ))[:2]
2656 glob, loc = (where + (None, ))[:2]
2525 py3compat.execfile(
2657 py3compat.execfile(
2526 fname, glob, loc,
2658 fname, glob, loc,
2527 self.compile if shell_futures else None)
2659 self.compile if shell_futures else None)
2528 except SystemExit as status:
2660 except SystemExit as status:
2529 # If the call was made with 0 or None exit status (sys.exit(0)
2661 # If the call was made with 0 or None exit status (sys.exit(0)
2530 # or sys.exit() ), don't bother showing a traceback, as both of
2662 # or sys.exit() ), don't bother showing a traceback, as both of
2531 # these are considered normal by the OS:
2663 # these are considered normal by the OS:
2532 # > python -c'import sys;sys.exit(0)'; echo $?
2664 # > python -c'import sys;sys.exit(0)'; echo $?
2533 # 0
2665 # 0
2534 # > python -c'import sys;sys.exit()'; echo $?
2666 # > python -c'import sys;sys.exit()'; echo $?
2535 # 0
2667 # 0
2536 # For other exit status, we show the exception unless
2668 # For other exit status, we show the exception unless
2537 # explicitly silenced, but only in short form.
2669 # explicitly silenced, but only in short form.
2538 if status.code:
2670 if status.code:
2539 if raise_exceptions:
2671 if raise_exceptions:
2540 raise
2672 raise
2541 if not exit_ignore:
2673 if not exit_ignore:
2542 self.showtraceback(exception_only=True)
2674 self.showtraceback(exception_only=True)
2543 except:
2675 except:
2544 if raise_exceptions:
2676 if raise_exceptions:
2545 raise
2677 raise
2546 # tb offset is 2 because we wrap execfile
2678 # tb offset is 2 because we wrap execfile
2547 self.showtraceback(tb_offset=2)
2679 self.showtraceback(tb_offset=2)
2548
2680
2549 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2681 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2550 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2682 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2551
2683
2552 Parameters
2684 Parameters
2553 ----------
2685 ----------
2554 fname : str
2686 fname : str
2555 The name of the file to execute. The filename must have a
2687 The name of the file to execute. The filename must have a
2556 .ipy or .ipynb extension.
2688 .ipy or .ipynb extension.
2557 shell_futures : bool (False)
2689 shell_futures : bool (False)
2558 If True, the code will share future statements with the interactive
2690 If True, the code will share future statements with the interactive
2559 shell. It will both be affected by previous __future__ imports, and
2691 shell. It will both be affected by previous __future__ imports, and
2560 any __future__ imports in the code will affect the shell. If False,
2692 any __future__ imports in the code will affect the shell. If False,
2561 __future__ imports are not shared in either direction.
2693 __future__ imports are not shared in either direction.
2562 raise_exceptions : bool (False)
2694 raise_exceptions : bool (False)
2563 If True raise exceptions everywhere. Meant for testing.
2695 If True raise exceptions everywhere. Meant for testing.
2564 """
2696 """
2565 fname = os.path.abspath(os.path.expanduser(fname))
2697 fname = os.path.abspath(os.path.expanduser(fname))
2566
2698
2567 # Make sure we can open the file
2699 # Make sure we can open the file
2568 try:
2700 try:
2569 with open(fname):
2701 with open(fname):
2570 pass
2702 pass
2571 except:
2703 except:
2572 warn('Could not open file <%s> for safe execution.' % fname)
2704 warn('Could not open file <%s> for safe execution.' % fname)
2573 return
2705 return
2574
2706
2575 # Find things also in current directory. This is needed to mimic the
2707 # Find things also in current directory. This is needed to mimic the
2576 # behavior of running a script from the system command line, where
2708 # behavior of running a script from the system command line, where
2577 # Python inserts the script's directory into sys.path
2709 # Python inserts the script's directory into sys.path
2578 dname = os.path.dirname(fname)
2710 dname = os.path.dirname(fname)
2579
2711
2580 def get_cells():
2712 def get_cells():
2581 """generator for sequence of code blocks to run"""
2713 """generator for sequence of code blocks to run"""
2582 if fname.endswith('.ipynb'):
2714 if fname.endswith('.ipynb'):
2583 from nbformat import read
2715 from nbformat import read
2584 nb = read(fname, as_version=4)
2716 nb = read(fname, as_version=4)
2585 if not nb.cells:
2717 if not nb.cells:
2586 return
2718 return
2587 for cell in nb.cells:
2719 for cell in nb.cells:
2588 if cell.cell_type == 'code':
2720 if cell.cell_type == 'code':
2589 yield cell.source
2721 yield cell.source
2590 else:
2722 else:
2591 with open(fname) as f:
2723 with open(fname) as f:
2592 yield f.read()
2724 yield f.read()
2593
2725
2594 with prepended_to_syspath(dname):
2726 with prepended_to_syspath(dname):
2595 try:
2727 try:
2596 for cell in get_cells():
2728 for cell in get_cells():
2597 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2729 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2598 if raise_exceptions:
2730 if raise_exceptions:
2599 result.raise_error()
2731 result.raise_error()
2600 elif not result.success:
2732 elif not result.success:
2601 break
2733 break
2602 except:
2734 except:
2603 if raise_exceptions:
2735 if raise_exceptions:
2604 raise
2736 raise
2605 self.showtraceback()
2737 self.showtraceback()
2606 warn('Unknown failure executing file: <%s>' % fname)
2738 warn('Unknown failure executing file: <%s>' % fname)
2607
2739
2608 def safe_run_module(self, mod_name, where):
2740 def safe_run_module(self, mod_name, where):
2609 """A safe version of runpy.run_module().
2741 """A safe version of runpy.run_module().
2610
2742
2611 This version will never throw an exception, but instead print
2743 This version will never throw an exception, but instead print
2612 helpful error messages to the screen.
2744 helpful error messages to the screen.
2613
2745
2614 `SystemExit` exceptions with status code 0 or None are ignored.
2746 `SystemExit` exceptions with status code 0 or None are ignored.
2615
2747
2616 Parameters
2748 Parameters
2617 ----------
2749 ----------
2618 mod_name : string
2750 mod_name : string
2619 The name of the module to be executed.
2751 The name of the module to be executed.
2620 where : dict
2752 where : dict
2621 The globals namespace.
2753 The globals namespace.
2622 """
2754 """
2623 try:
2755 try:
2624 try:
2756 try:
2625 where.update(
2757 where.update(
2626 runpy.run_module(str(mod_name), run_name="__main__",
2758 runpy.run_module(str(mod_name), run_name="__main__",
2627 alter_sys=True)
2759 alter_sys=True)
2628 )
2760 )
2629 except SystemExit as status:
2761 except SystemExit as status:
2630 if status.code:
2762 if status.code:
2631 raise
2763 raise
2632 except:
2764 except:
2633 self.showtraceback()
2765 self.showtraceback()
2634 warn('Unknown failure executing module: <%s>' % mod_name)
2766 warn('Unknown failure executing module: <%s>' % mod_name)
2635
2767
2636 def run_cell(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2768 def run_cell(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2637 """Run a complete IPython cell.
2769 """Run a complete IPython cell.
2638
2770
2639 Parameters
2771 Parameters
2640 ----------
2772 ----------
2641 raw_cell : str
2773 raw_cell : str
2642 The code (including IPython code such as %magic functions) to run.
2774 The code (including IPython code such as %magic functions) to run.
2643 store_history : bool
2775 store_history : bool
2644 If True, the raw and translated cell will be stored in IPython's
2776 If True, the raw and translated cell will be stored in IPython's
2645 history. For user code calling back into IPython's machinery, this
2777 history. For user code calling back into IPython's machinery, this
2646 should be set to False.
2778 should be set to False.
2647 silent : bool
2779 silent : bool
2648 If True, avoid side-effects, such as implicit displayhooks and
2780 If True, avoid side-effects, such as implicit displayhooks and
2649 and logging. silent=True forces store_history=False.
2781 and logging. silent=True forces store_history=False.
2650 shell_futures : bool
2782 shell_futures : bool
2651 If True, the code will share future statements with the interactive
2783 If True, the code will share future statements with the interactive
2652 shell. It will both be affected by previous __future__ imports, and
2784 shell. It will both be affected by previous __future__ imports, and
2653 any __future__ imports in the code will affect the shell. If False,
2785 any __future__ imports in the code will affect the shell. If False,
2654 __future__ imports are not shared in either direction.
2786 __future__ imports are not shared in either direction.
2655
2787
2656 Returns
2788 Returns
2657 -------
2789 -------
2658 result : :class:`ExecutionResult`
2790 result : :class:`ExecutionResult`
2659 """
2791 """
2660 try:
2792 try:
2661 result = self._run_cell(
2793 result = self._run_cell(
2662 raw_cell, store_history, silent, shell_futures)
2794 raw_cell, store_history, silent, shell_futures)
2663 finally:
2795 finally:
2664 self.events.trigger('post_execute')
2796 self.events.trigger('post_execute')
2665 if not silent:
2797 if not silent:
2666 self.events.trigger('post_run_cell', result)
2798 self.events.trigger('post_run_cell', result)
2667 return result
2799 return result
2668
2800
2669 def _run_cell(self, raw_cell, store_history, silent, shell_futures):
2801 def _run_cell(self, raw_cell, store_history, silent, shell_futures):
2670 """Internal method to run a complete IPython cell.
2802 """Internal method to run a complete IPython cell."""
2803 return self.loop_runner(
2804 self.run_cell_async(
2805 raw_cell,
2806 store_history=store_history,
2807 silent=silent,
2808 shell_futures=shell_futures,
2809 )
2810 )
2811
2812 @asyncio.coroutine
2813 def run_cell_async(self, raw_cell, store_history=False, silent=False, shell_futures=True):
2814 """Run a complete IPython cell asynchronously.
2671
2815
2672 Parameters
2816 Parameters
2673 ----------
2817 ----------
2674 raw_cell : str
2818 raw_cell : str
2819 The code (including IPython code such as %magic functions) to run.
2675 store_history : bool
2820 store_history : bool
2821 If True, the raw and translated cell will be stored in IPython's
2822 history. For user code calling back into IPython's machinery, this
2823 should be set to False.
2676 silent : bool
2824 silent : bool
2825 If True, avoid side-effects, such as implicit displayhooks and
2826 and logging. silent=True forces store_history=False.
2677 shell_futures : bool
2827 shell_futures : bool
2828 If True, the code will share future statements with the interactive
2829 shell. It will both be affected by previous __future__ imports, and
2830 any __future__ imports in the code will affect the shell. If False,
2831 __future__ imports are not shared in either direction.
2678
2832
2679 Returns
2833 Returns
2680 -------
2834 -------
2681 result : :class:`ExecutionResult`
2835 result : :class:`ExecutionResult`
2682 """
2836 """
2683 info = ExecutionInfo(
2837 info = ExecutionInfo(
2684 raw_cell, store_history, silent, shell_futures)
2838 raw_cell, store_history, silent, shell_futures)
2685 result = ExecutionResult(info)
2839 result = ExecutionResult(info)
2686
2840
2687 if (not raw_cell) or raw_cell.isspace():
2841 if (not raw_cell) or raw_cell.isspace():
2688 self.last_execution_succeeded = True
2842 self.last_execution_succeeded = True
2689 self.last_execution_result = result
2843 self.last_execution_result = result
2690 return result
2844 return result
2691
2845
2692 if silent:
2846 if silent:
2693 store_history = False
2847 store_history = False
2694
2848
2695 if store_history:
2849 if store_history:
2696 result.execution_count = self.execution_count
2850 result.execution_count = self.execution_count
2697
2851
2698 def error_before_exec(value):
2852 def error_before_exec(value):
2699 if store_history:
2853 if store_history:
2700 self.execution_count += 1
2854 self.execution_count += 1
2701 result.error_before_exec = value
2855 result.error_before_exec = value
2702 self.last_execution_succeeded = False
2856 self.last_execution_succeeded = False
2703 self.last_execution_result = result
2857 self.last_execution_result = result
2704 return result
2858 return result
2705
2859
2706 self.events.trigger('pre_execute')
2860 self.events.trigger('pre_execute')
2707 if not silent:
2861 if not silent:
2708 self.events.trigger('pre_run_cell', info)
2862 self.events.trigger('pre_run_cell', info)
2709
2863
2710 # If any of our input transformation (input_transformer_manager or
2864 # If any of our input transformation (input_transformer_manager or
2711 # prefilter_manager) raises an exception, we store it in this variable
2865 # prefilter_manager) raises an exception, we store it in this variable
2712 # so that we can display the error after logging the input and storing
2866 # so that we can display the error after logging the input and storing
2713 # it in the history.
2867 # it in the history.
2714 preprocessing_exc_tuple = None
2868 preprocessing_exc_tuple = None
2715 try:
2869 try:
2716 # Static input transformations
2870 # Static input transformations
2717 cell = self.input_transformer_manager.transform_cell(raw_cell)
2871 cell = self.input_transformer_manager.transform_cell(raw_cell)
2718 except SyntaxError:
2872 except SyntaxError:
2719 preprocessing_exc_tuple = sys.exc_info()
2873 preprocessing_exc_tuple = sys.exc_info()
2720 cell = raw_cell # cell has to exist so it can be stored/logged
2874 cell = raw_cell # cell has to exist so it can be stored/logged
2721 else:
2875 else:
2722 if len(cell.splitlines()) == 1:
2876 if len(cell.splitlines()) == 1:
2723 # Dynamic transformations - only applied for single line commands
2877 # Dynamic transformations - only applied for single line commands
2724 with self.builtin_trap:
2878 with self.builtin_trap:
2725 try:
2879 try:
2726 # use prefilter_lines to handle trailing newlines
2880 # use prefilter_lines to handle trailing newlines
2727 # restore trailing newline for ast.parse
2881 # restore trailing newline for ast.parse
2728 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2882 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2729 except Exception:
2883 except Exception:
2730 # don't allow prefilter errors to crash IPython
2884 # don't allow prefilter errors to crash IPython
2731 preprocessing_exc_tuple = sys.exc_info()
2885 preprocessing_exc_tuple = sys.exc_info()
2732
2886
2733 # Store raw and processed history
2887 # Store raw and processed history
2734 if store_history:
2888 if store_history:
2735 self.history_manager.store_inputs(self.execution_count,
2889 self.history_manager.store_inputs(self.execution_count,
2736 cell, raw_cell)
2890 cell, raw_cell)
2737 if not silent:
2891 if not silent:
2738 self.logger.log(cell, raw_cell)
2892 self.logger.log(cell, raw_cell)
2739
2893
2740 # Display the exception if input processing failed.
2894 # Display the exception if input processing failed.
2741 if preprocessing_exc_tuple is not None:
2895 if preprocessing_exc_tuple is not None:
2742 self.showtraceback(preprocessing_exc_tuple)
2896 self.showtraceback(preprocessing_exc_tuple)
2743 if store_history:
2897 if store_history:
2744 self.execution_count += 1
2898 self.execution_count += 1
2745 return error_before_exec(preprocessing_exc_tuple[2])
2899 return error_before_exec(preprocessing_exc_tuple[2])
2746
2900
2747 # Our own compiler remembers the __future__ environment. If we want to
2901 # Our own compiler remembers the __future__ environment. If we want to
2748 # run code with a separate __future__ environment, use the default
2902 # run code with a separate __future__ environment, use the default
2749 # compiler
2903 # compiler
2750 compiler = self.compile if shell_futures else CachingCompiler()
2904 compiler = self.compile if shell_futures else CachingCompiler()
2751
2905
2906 _run_async = False
2907
2752 with self.builtin_trap:
2908 with self.builtin_trap:
2753 cell_name = self.compile.cache(cell, self.execution_count)
2909 cell_name = self.compile.cache(cell, self.execution_count)
2754
2910
2755 with self.display_trap:
2911 with self.display_trap:
2756 # Compile to bytecode
2912 # Compile to bytecode
2757 try:
2913 try:
2758 code_ast = compiler.ast_parse(cell, filename=cell_name)
2914 if self.autoawait and _should_be_async(cell):
2915 # the code AST below will not be user code: we wrap it
2916 # in an `async def`. This will likely make some AST
2917 # transformer below miss some transform opportunity and
2918 # introduce a small coupling to run_code (in which we
2919 # bake some assumptions of what _ast_asyncify returns.
2920 # they are ways around (like grafting part of the ast
2921 # later:
2922 # - Here, return code_ast.body[0].body[1:-1], as well
2923 # as last expression in return statement which is
2924 # the user code part.
2925 # - Let it go through the AST transformers, and graft
2926 # - it back after the AST transform
2927 # But that seem unreasonable, at least while we
2928 # do not need it.
2929 code_ast = _ast_asyncify(cell, 'async-def-wrapper')
2930 _run_async = True
2931 else:
2932 code_ast = compiler.ast_parse(cell, filename=cell_name)
2759 except self.custom_exceptions as e:
2933 except self.custom_exceptions as e:
2760 etype, value, tb = sys.exc_info()
2934 etype, value, tb = sys.exc_info()
2761 self.CustomTB(etype, value, tb)
2935 self.CustomTB(etype, value, tb)
2762 return error_before_exec(e)
2936 return error_before_exec(e)
2763 except IndentationError as e:
2937 except IndentationError as e:
2764 self.showindentationerror()
2938 self.showindentationerror()
2765 return error_before_exec(e)
2939 return error_before_exec(e)
2766 except (OverflowError, SyntaxError, ValueError, TypeError,
2940 except (OverflowError, SyntaxError, ValueError, TypeError,
2767 MemoryError) as e:
2941 MemoryError) as e:
2768 self.showsyntaxerror()
2942 self.showsyntaxerror()
2769 return error_before_exec(e)
2943 return error_before_exec(e)
2770
2944
2771 # Apply AST transformations
2945 # Apply AST transformations
2772 try:
2946 try:
2773 code_ast = self.transform_ast(code_ast)
2947 code_ast = self.transform_ast(code_ast)
2774 except InputRejected as e:
2948 except InputRejected as e:
2775 self.showtraceback()
2949 self.showtraceback()
2776 return error_before_exec(e)
2950 return error_before_exec(e)
2777
2951
2778 # Give the displayhook a reference to our ExecutionResult so it
2952 # Give the displayhook a reference to our ExecutionResult so it
2779 # can fill in the output value.
2953 # can fill in the output value.
2780 self.displayhook.exec_result = result
2954 self.displayhook.exec_result = result
2781
2955
2782 # Execute the user code
2956 # Execute the user code
2783 interactivity = 'none' if silent else self.ast_node_interactivity
2957 interactivity = "none" if silent else self.ast_node_interactivity
2784 has_raised = self.run_ast_nodes(code_ast.body, cell_name,
2958 if _run_async:
2785 interactivity=interactivity, compiler=compiler, result=result)
2959 interactivity = 'async'
2960 has_raised = yield from self.run_ast_nodes(code_ast.body, cell_name,
2961 interactivity=interactivity, compiler=compiler, result=result)
2786
2962
2787 self.last_execution_succeeded = not has_raised
2963 self.last_execution_succeeded = not has_raised
2788 self.last_execution_result = result
2964 self.last_execution_result = result
2789
2965
2790 # Reset this so later displayed values do not modify the
2966 # Reset this so later displayed values do not modify the
2791 # ExecutionResult
2967 # ExecutionResult
2792 self.displayhook.exec_result = None
2968 self.displayhook.exec_result = None
2793
2969
2794 if store_history:
2970 if store_history:
2795 # Write output to the database. Does nothing unless
2971 # Write output to the database. Does nothing unless
2796 # history output logging is enabled.
2972 # history output logging is enabled.
2797 self.history_manager.store_output(self.execution_count)
2973 self.history_manager.store_output(self.execution_count)
2798 # Each cell is a *single* input, regardless of how many lines it has
2974 # Each cell is a *single* input, regardless of how many lines it has
2799 self.execution_count += 1
2975 self.execution_count += 1
2800
2976
2801 return result
2977 return result
2802
2978
2803 def transform_ast(self, node):
2979 def transform_ast(self, node):
2804 """Apply the AST transformations from self.ast_transformers
2980 """Apply the AST transformations from self.ast_transformers
2805
2981
2806 Parameters
2982 Parameters
2807 ----------
2983 ----------
2808 node : ast.Node
2984 node : ast.Node
2809 The root node to be transformed. Typically called with the ast.Module
2985 The root node to be transformed. Typically called with the ast.Module
2810 produced by parsing user input.
2986 produced by parsing user input.
2811
2987
2812 Returns
2988 Returns
2813 -------
2989 -------
2814 An ast.Node corresponding to the node it was called with. Note that it
2990 An ast.Node corresponding to the node it was called with. Note that it
2815 may also modify the passed object, so don't rely on references to the
2991 may also modify the passed object, so don't rely on references to the
2816 original AST.
2992 original AST.
2817 """
2993 """
2818 for transformer in self.ast_transformers:
2994 for transformer in self.ast_transformers:
2819 try:
2995 try:
2820 node = transformer.visit(node)
2996 node = transformer.visit(node)
2821 except InputRejected:
2997 except InputRejected:
2822 # User-supplied AST transformers can reject an input by raising
2998 # User-supplied AST transformers can reject an input by raising
2823 # an InputRejected. Short-circuit in this case so that we
2999 # an InputRejected. Short-circuit in this case so that we
2824 # don't unregister the transform.
3000 # don't unregister the transform.
2825 raise
3001 raise
2826 except Exception:
3002 except Exception:
2827 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
3003 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
2828 self.ast_transformers.remove(transformer)
3004 self.ast_transformers.remove(transformer)
2829
3005
2830 if self.ast_transformers:
3006 if self.ast_transformers:
2831 ast.fix_missing_locations(node)
3007 ast.fix_missing_locations(node)
2832 return node
3008 return node
2833
2834
3009
3010 @asyncio.coroutine
2835 def run_ast_nodes(self, nodelist:ListType[AST], cell_name:str, interactivity='last_expr',
3011 def run_ast_nodes(self, nodelist:ListType[AST], cell_name:str, interactivity='last_expr',
2836 compiler=compile, result=None):
3012 compiler=compile, result=None):
2837 """Run a sequence of AST nodes. The execution mode depends on the
3013 """Run a sequence of AST nodes. The execution mode depends on the
2838 interactivity parameter.
3014 interactivity parameter.
2839
3015
2840 Parameters
3016 Parameters
2841 ----------
3017 ----------
2842 nodelist : list
3018 nodelist : list
2843 A sequence of AST nodes to run.
3019 A sequence of AST nodes to run.
2844 cell_name : str
3020 cell_name : str
2845 Will be passed to the compiler as the filename of the cell. Typically
3021 Will be passed to the compiler as the filename of the cell. Typically
2846 the value returned by ip.compile.cache(cell).
3022 the value returned by ip.compile.cache(cell).
2847 interactivity : str
3023 interactivity : str
2848 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
3024 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
2849 specifying which nodes should be run interactively (displaying output
3025 specifying which nodes should be run interactively (displaying output
2850 from expressions). 'last_expr' will run the last node interactively
3026 from expressions). 'last_expr' will run the last node interactively
2851 only if it is an expression (i.e. expressions in loops or other blocks
3027 only if it is an expression (i.e. expressions in loops or other blocks
2852 are not displayed) 'last_expr_or_assign' will run the last expression
3028 are not displayed) 'last_expr_or_assign' will run the last expression
2853 or the last assignment. Other values for this parameter will raise a
3029 or the last assignment. Other values for this parameter will raise a
2854 ValueError.
3030 ValueError.
3031
3032 Experimental value: 'async' Will try to run top level interactive
3033 async/await code in default runner, this will not respect the
3034 interactivty setting and will only run the last node if it is an
3035 expression.
3036
2855 compiler : callable
3037 compiler : callable
2856 A function with the same interface as the built-in compile(), to turn
3038 A function with the same interface as the built-in compile(), to turn
2857 the AST nodes into code objects. Default is the built-in compile().
3039 the AST nodes into code objects. Default is the built-in compile().
2858 result : ExecutionResult, optional
3040 result : ExecutionResult, optional
2859 An object to store exceptions that occur during execution.
3041 An object to store exceptions that occur during execution.
2860
3042
2861 Returns
3043 Returns
2862 -------
3044 -------
2863 True if an exception occurred while running code, False if it finished
3045 True if an exception occurred while running code, False if it finished
2864 running.
3046 running.
2865 """
3047 """
2866 if not nodelist:
3048 if not nodelist:
2867 return
3049 return
2868 if interactivity == 'last_expr_or_assign':
3050 if interactivity == 'last_expr_or_assign':
2869 if isinstance(nodelist[-1], _assign_nodes):
3051 if isinstance(nodelist[-1], _assign_nodes):
2870 asg = nodelist[-1]
3052 asg = nodelist[-1]
2871 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
3053 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
2872 target = asg.targets[0]
3054 target = asg.targets[0]
2873 elif isinstance(asg, _single_targets_nodes):
3055 elif isinstance(asg, _single_targets_nodes):
2874 target = asg.target
3056 target = asg.target
2875 else:
3057 else:
2876 target = None
3058 target = None
2877 if isinstance(target, ast.Name):
3059 if isinstance(target, ast.Name):
2878 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
3060 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
2879 ast.fix_missing_locations(nnode)
3061 ast.fix_missing_locations(nnode)
2880 nodelist.append(nnode)
3062 nodelist.append(nnode)
2881 interactivity = 'last_expr'
3063 interactivity = 'last_expr'
2882
3064
3065 _async = False
2883 if interactivity == 'last_expr':
3066 if interactivity == 'last_expr':
2884 if isinstance(nodelist[-1], ast.Expr):
3067 if isinstance(nodelist[-1], ast.Expr):
2885 interactivity = "last"
3068 interactivity = "last"
2886 else:
3069 else:
2887 interactivity = "none"
3070 interactivity = "none"
2888
3071
2889 if interactivity == 'none':
3072 if interactivity == 'none':
2890 to_run_exec, to_run_interactive = nodelist, []
3073 to_run_exec, to_run_interactive = nodelist, []
2891 elif interactivity == 'last':
3074 elif interactivity == 'last':
2892 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
3075 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2893 elif interactivity == 'all':
3076 elif interactivity == 'all':
2894 to_run_exec, to_run_interactive = [], nodelist
3077 to_run_exec, to_run_interactive = [], nodelist
3078 elif interactivity == 'async':
3079 _async = True
2895 else:
3080 else:
2896 raise ValueError("Interactivity was %r" % interactivity)
3081 raise ValueError("Interactivity was %r" % interactivity)
2897 try:
3082 try:
2898 for i, node in enumerate(to_run_exec):
3083 if _async:
2899 mod = ast.Module([node])
3084 # If interactivity is async the semantics of run_code are
2900 code = compiler(mod, cell_name, "exec")
3085 # completely different Skip usual machinery.
2901 if self.run_code(code, result):
3086 mod = ast.Module(nodelist)
2902 return True
3087 async_wrapper_code = compiler(mod, 'cell_name', 'exec')
2903
3088 exec(async_wrapper_code, self.user_global_ns, self.user_ns)
2904 for i, node in enumerate(to_run_interactive):
3089 async_code = removed_co_newlocals(self.user_ns.pop('async-def-wrapper')).__code__
2905 mod = ast.Interactive([node])
3090 if (yield from self.run_code(async_code, result, async_=True)):
2906 code = compiler(mod, cell_name, "single")
2907 if self.run_code(code, result):
2908 return True
3091 return True
3092 else:
3093 for i, node in enumerate(to_run_exec):
3094 mod = ast.Module([node])
3095 code = compiler(mod, cell_name, "exec")
3096 if (yield from self.run_code(code, result)):
3097 return True
3098
3099 for i, node in enumerate(to_run_interactive):
3100 mod = ast.Interactive([node])
3101 code = compiler(mod, cell_name, "single")
3102 if (yield from self.run_code(code, result)):
3103 return True
2909
3104
2910 # Flush softspace
3105 # Flush softspace
2911 if softspace(sys.stdout, 0):
3106 if softspace(sys.stdout, 0):
2912 print()
3107 print()
2913
3108
2914 except:
3109 except:
2915 # It's possible to have exceptions raised here, typically by
3110 # It's possible to have exceptions raised here, typically by
2916 # compilation of odd code (such as a naked 'return' outside a
3111 # compilation of odd code (such as a naked 'return' outside a
2917 # function) that did parse but isn't valid. Typically the exception
3112 # function) that did parse but isn't valid. Typically the exception
2918 # is a SyntaxError, but it's safest just to catch anything and show
3113 # is a SyntaxError, but it's safest just to catch anything and show
2919 # the user a traceback.
3114 # the user a traceback.
2920
3115
2921 # We do only one try/except outside the loop to minimize the impact
3116 # We do only one try/except outside the loop to minimize the impact
2922 # on runtime, and also because if any node in the node list is
3117 # on runtime, and also because if any node in the node list is
2923 # broken, we should stop execution completely.
3118 # broken, we should stop execution completely.
2924 if result:
3119 if result:
2925 result.error_before_exec = sys.exc_info()[1]
3120 result.error_before_exec = sys.exc_info()[1]
2926 self.showtraceback()
3121 self.showtraceback()
2927 return True
3122 return True
2928
3123
2929 return False
3124 return False
2930
3125
2931 def run_code(self, code_obj, result=None):
3126 def _async_exec(self, code_obj: types.CodeType, user_ns: dict):
3127 """
3128 Evaluate an asynchronous code object using a code runner
3129
3130 Fake asynchronous execution of code_object in a namespace via a proxy namespace.
3131
3132 Returns coroutine object, which can be executed via async loop runner
3133
3134 WARNING: The semantics of `async_exec` are quite different from `exec`,
3135 in particular you can only pass a single namespace. It also return a
3136 handle to the value of the last things returned by code_object.
3137 """
3138
3139 return eval(code_obj, user_ns)
3140
3141 @asyncio.coroutine
3142 def run_code(self, code_obj, result=None, *, async_=False):
2932 """Execute a code object.
3143 """Execute a code object.
2933
3144
2934 When an exception occurs, self.showtraceback() is called to display a
3145 When an exception occurs, self.showtraceback() is called to display a
2935 traceback.
3146 traceback.
2936
3147
2937 Parameters
3148 Parameters
2938 ----------
3149 ----------
2939 code_obj : code object
3150 code_obj : code object
2940 A compiled code object, to be executed
3151 A compiled code object, to be executed
2941 result : ExecutionResult, optional
3152 result : ExecutionResult, optional
2942 An object to store exceptions that occur during execution.
3153 An object to store exceptions that occur during execution.
3154 async_ : Bool (Experimental)
3155 Attempt to run top-level asynchronous code in a default loop.
2943
3156
2944 Returns
3157 Returns
2945 -------
3158 -------
2946 False : successful execution.
3159 False : successful execution.
2947 True : an error occurred.
3160 True : an error occurred.
2948 """
3161 """
2949 # Set our own excepthook in case the user code tries to call it
3162 # Set our own excepthook in case the user code tries to call it
2950 # directly, so that the IPython crash handler doesn't get triggered
3163 # directly, so that the IPython crash handler doesn't get triggered
2951 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
3164 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
2952
3165
2953 # we save the original sys.excepthook in the instance, in case config
3166 # we save the original sys.excepthook in the instance, in case config
2954 # code (such as magics) needs access to it.
3167 # code (such as magics) needs access to it.
2955 self.sys_excepthook = old_excepthook
3168 self.sys_excepthook = old_excepthook
2956 outflag = True # happens in more places, so it's easier as default
3169 outflag = True # happens in more places, so it's easier as default
2957 try:
3170 try:
2958 try:
3171 try:
2959 self.hooks.pre_run_code_hook()
3172 self.hooks.pre_run_code_hook()
2960 #rprint('Running code', repr(code_obj)) # dbg
3173 if async_:
2961 exec(code_obj, self.user_global_ns, self.user_ns)
3174 last_expr = (yield from self._async_exec(code_obj, self.user_ns))
3175 code = compile('last_expr', 'fake', "single")
3176 exec(code, {'last_expr': last_expr})
3177 else:
3178 exec(code_obj, self.user_global_ns, self.user_ns)
2962 finally:
3179 finally:
2963 # Reset our crash handler in place
3180 # Reset our crash handler in place
2964 sys.excepthook = old_excepthook
3181 sys.excepthook = old_excepthook
2965 except SystemExit as e:
3182 except SystemExit as e:
2966 if result is not None:
3183 if result is not None:
2967 result.error_in_exec = e
3184 result.error_in_exec = e
2968 self.showtraceback(exception_only=True)
3185 self.showtraceback(exception_only=True)
2969 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
3186 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
2970 except self.custom_exceptions:
3187 except self.custom_exceptions:
2971 etype, value, tb = sys.exc_info()
3188 etype, value, tb = sys.exc_info()
2972 if result is not None:
3189 if result is not None:
2973 result.error_in_exec = value
3190 result.error_in_exec = value
2974 self.CustomTB(etype, value, tb)
3191 self.CustomTB(etype, value, tb)
2975 except:
3192 except:
2976 if result is not None:
3193 if result is not None:
2977 result.error_in_exec = sys.exc_info()[1]
3194 result.error_in_exec = sys.exc_info()[1]
2978 self.showtraceback(running_compiled_code=True)
3195 self.showtraceback(running_compiled_code=True)
2979 else:
3196 else:
2980 outflag = False
3197 outflag = False
2981 return outflag
3198 return outflag
2982
3199
2983 # For backwards compatibility
3200 # For backwards compatibility
2984 runcode = run_code
3201 runcode = run_code
2985
3202
2986 def check_complete(self, code):
3203 def check_complete(self, code):
2987 """Return whether a block of code is ready to execute, or should be continued
3204 """Return whether a block of code is ready to execute, or should be continued
2988
3205
2989 Parameters
3206 Parameters
2990 ----------
3207 ----------
2991 source : string
3208 source : string
2992 Python input code, which can be multiline.
3209 Python input code, which can be multiline.
2993
3210
2994 Returns
3211 Returns
2995 -------
3212 -------
2996 status : str
3213 status : str
2997 One of 'complete', 'incomplete', or 'invalid' if source is not a
3214 One of 'complete', 'incomplete', or 'invalid' if source is not a
2998 prefix of valid code.
3215 prefix of valid code.
2999 indent : str
3216 indent : str
3000 When status is 'incomplete', this is some whitespace to insert on
3217 When status is 'incomplete', this is some whitespace to insert on
3001 the next line of the prompt.
3218 the next line of the prompt.
3002 """
3219 """
3003 status, nspaces = self.input_splitter.check_complete(code)
3220 status, nspaces = self.input_splitter.check_complete(code)
3004 return status, ' ' * (nspaces or 0)
3221 return status, ' ' * (nspaces or 0)
3005
3222
3006 #-------------------------------------------------------------------------
3223 #-------------------------------------------------------------------------
3007 # Things related to GUI support and pylab
3224 # Things related to GUI support and pylab
3008 #-------------------------------------------------------------------------
3225 #-------------------------------------------------------------------------
3009
3226
3010 active_eventloop = None
3227 active_eventloop = None
3011
3228
3012 def enable_gui(self, gui=None):
3229 def enable_gui(self, gui=None):
3013 raise NotImplementedError('Implement enable_gui in a subclass')
3230 raise NotImplementedError('Implement enable_gui in a subclass')
3014
3231
3015 def enable_matplotlib(self, gui=None):
3232 def enable_matplotlib(self, gui=None):
3016 """Enable interactive matplotlib and inline figure support.
3233 """Enable interactive matplotlib and inline figure support.
3017
3234
3018 This takes the following steps:
3235 This takes the following steps:
3019
3236
3020 1. select the appropriate eventloop and matplotlib backend
3237 1. select the appropriate eventloop and matplotlib backend
3021 2. set up matplotlib for interactive use with that backend
3238 2. set up matplotlib for interactive use with that backend
3022 3. configure formatters for inline figure display
3239 3. configure formatters for inline figure display
3023 4. enable the selected gui eventloop
3240 4. enable the selected gui eventloop
3024
3241
3025 Parameters
3242 Parameters
3026 ----------
3243 ----------
3027 gui : optional, string
3244 gui : optional, string
3028 If given, dictates the choice of matplotlib GUI backend to use
3245 If given, dictates the choice of matplotlib GUI backend to use
3029 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3246 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3030 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3247 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3031 matplotlib (as dictated by the matplotlib build-time options plus the
3248 matplotlib (as dictated by the matplotlib build-time options plus the
3032 user's matplotlibrc configuration file). Note that not all backends
3249 user's matplotlibrc configuration file). Note that not all backends
3033 make sense in all contexts, for example a terminal ipython can't
3250 make sense in all contexts, for example a terminal ipython can't
3034 display figures inline.
3251 display figures inline.
3035 """
3252 """
3036 from IPython.core import pylabtools as pt
3253 from IPython.core import pylabtools as pt
3037 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3254 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3038
3255
3039 if gui != 'inline':
3256 if gui != 'inline':
3040 # If we have our first gui selection, store it
3257 # If we have our first gui selection, store it
3041 if self.pylab_gui_select is None:
3258 if self.pylab_gui_select is None:
3042 self.pylab_gui_select = gui
3259 self.pylab_gui_select = gui
3043 # Otherwise if they are different
3260 # Otherwise if they are different
3044 elif gui != self.pylab_gui_select:
3261 elif gui != self.pylab_gui_select:
3045 print('Warning: Cannot change to a different GUI toolkit: %s.'
3262 print('Warning: Cannot change to a different GUI toolkit: %s.'
3046 ' Using %s instead.' % (gui, self.pylab_gui_select))
3263 ' Using %s instead.' % (gui, self.pylab_gui_select))
3047 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3264 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3048
3265
3049 pt.activate_matplotlib(backend)
3266 pt.activate_matplotlib(backend)
3050 pt.configure_inline_support(self, backend)
3267 pt.configure_inline_support(self, backend)
3051
3268
3052 # Now we must activate the gui pylab wants to use, and fix %run to take
3269 # Now we must activate the gui pylab wants to use, and fix %run to take
3053 # plot updates into account
3270 # plot updates into account
3054 self.enable_gui(gui)
3271 self.enable_gui(gui)
3055 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3272 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3056 pt.mpl_runner(self.safe_execfile)
3273 pt.mpl_runner(self.safe_execfile)
3057
3274
3058 return gui, backend
3275 return gui, backend
3059
3276
3060 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3277 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3061 """Activate pylab support at runtime.
3278 """Activate pylab support at runtime.
3062
3279
3063 This turns on support for matplotlib, preloads into the interactive
3280 This turns on support for matplotlib, preloads into the interactive
3064 namespace all of numpy and pylab, and configures IPython to correctly
3281 namespace all of numpy and pylab, and configures IPython to correctly
3065 interact with the GUI event loop. The GUI backend to be used can be
3282 interact with the GUI event loop. The GUI backend to be used can be
3066 optionally selected with the optional ``gui`` argument.
3283 optionally selected with the optional ``gui`` argument.
3067
3284
3068 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3285 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3069
3286
3070 Parameters
3287 Parameters
3071 ----------
3288 ----------
3072 gui : optional, string
3289 gui : optional, string
3073 If given, dictates the choice of matplotlib GUI backend to use
3290 If given, dictates the choice of matplotlib GUI backend to use
3074 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3291 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3075 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3292 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3076 matplotlib (as dictated by the matplotlib build-time options plus the
3293 matplotlib (as dictated by the matplotlib build-time options plus the
3077 user's matplotlibrc configuration file). Note that not all backends
3294 user's matplotlibrc configuration file). Note that not all backends
3078 make sense in all contexts, for example a terminal ipython can't
3295 make sense in all contexts, for example a terminal ipython can't
3079 display figures inline.
3296 display figures inline.
3080 import_all : optional, bool, default: True
3297 import_all : optional, bool, default: True
3081 Whether to do `from numpy import *` and `from pylab import *`
3298 Whether to do `from numpy import *` and `from pylab import *`
3082 in addition to module imports.
3299 in addition to module imports.
3083 welcome_message : deprecated
3300 welcome_message : deprecated
3084 This argument is ignored, no welcome message will be displayed.
3301 This argument is ignored, no welcome message will be displayed.
3085 """
3302 """
3086 from IPython.core.pylabtools import import_pylab
3303 from IPython.core.pylabtools import import_pylab
3087
3304
3088 gui, backend = self.enable_matplotlib(gui)
3305 gui, backend = self.enable_matplotlib(gui)
3089
3306
3090 # We want to prevent the loading of pylab to pollute the user's
3307 # We want to prevent the loading of pylab to pollute the user's
3091 # namespace as shown by the %who* magics, so we execute the activation
3308 # namespace as shown by the %who* magics, so we execute the activation
3092 # code in an empty namespace, and we update *both* user_ns and
3309 # code in an empty namespace, and we update *both* user_ns and
3093 # user_ns_hidden with this information.
3310 # user_ns_hidden with this information.
3094 ns = {}
3311 ns = {}
3095 import_pylab(ns, import_all)
3312 import_pylab(ns, import_all)
3096 # warn about clobbered names
3313 # warn about clobbered names
3097 ignored = {"__builtins__"}
3314 ignored = {"__builtins__"}
3098 both = set(ns).intersection(self.user_ns).difference(ignored)
3315 both = set(ns).intersection(self.user_ns).difference(ignored)
3099 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3316 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3100 self.user_ns.update(ns)
3317 self.user_ns.update(ns)
3101 self.user_ns_hidden.update(ns)
3318 self.user_ns_hidden.update(ns)
3102 return gui, backend, clobbered
3319 return gui, backend, clobbered
3103
3320
3104 #-------------------------------------------------------------------------
3321 #-------------------------------------------------------------------------
3105 # Utilities
3322 # Utilities
3106 #-------------------------------------------------------------------------
3323 #-------------------------------------------------------------------------
3107
3324
3108 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3325 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3109 """Expand python variables in a string.
3326 """Expand python variables in a string.
3110
3327
3111 The depth argument indicates how many frames above the caller should
3328 The depth argument indicates how many frames above the caller should
3112 be walked to look for the local namespace where to expand variables.
3329 be walked to look for the local namespace where to expand variables.
3113
3330
3114 The global namespace for expansion is always the user's interactive
3331 The global namespace for expansion is always the user's interactive
3115 namespace.
3332 namespace.
3116 """
3333 """
3117 ns = self.user_ns.copy()
3334 ns = self.user_ns.copy()
3118 try:
3335 try:
3119 frame = sys._getframe(depth+1)
3336 frame = sys._getframe(depth+1)
3120 except ValueError:
3337 except ValueError:
3121 # This is thrown if there aren't that many frames on the stack,
3338 # This is thrown if there aren't that many frames on the stack,
3122 # e.g. if a script called run_line_magic() directly.
3339 # e.g. if a script called run_line_magic() directly.
3123 pass
3340 pass
3124 else:
3341 else:
3125 ns.update(frame.f_locals)
3342 ns.update(frame.f_locals)
3126
3343
3127 try:
3344 try:
3128 # We have to use .vformat() here, because 'self' is a valid and common
3345 # We have to use .vformat() here, because 'self' is a valid and common
3129 # name, and expanding **ns for .format() would make it collide with
3346 # name, and expanding **ns for .format() would make it collide with
3130 # the 'self' argument of the method.
3347 # the 'self' argument of the method.
3131 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3348 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3132 except Exception:
3349 except Exception:
3133 # if formatter couldn't format, just let it go untransformed
3350 # if formatter couldn't format, just let it go untransformed
3134 pass
3351 pass
3135 return cmd
3352 return cmd
3136
3353
3137 def mktempfile(self, data=None, prefix='ipython_edit_'):
3354 def mktempfile(self, data=None, prefix='ipython_edit_'):
3138 """Make a new tempfile and return its filename.
3355 """Make a new tempfile and return its filename.
3139
3356
3140 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3357 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3141 but it registers the created filename internally so ipython cleans it up
3358 but it registers the created filename internally so ipython cleans it up
3142 at exit time.
3359 at exit time.
3143
3360
3144 Optional inputs:
3361 Optional inputs:
3145
3362
3146 - data(None): if data is given, it gets written out to the temp file
3363 - data(None): if data is given, it gets written out to the temp file
3147 immediately, and the file is closed again."""
3364 immediately, and the file is closed again."""
3148
3365
3149 dirname = tempfile.mkdtemp(prefix=prefix)
3366 dirname = tempfile.mkdtemp(prefix=prefix)
3150 self.tempdirs.append(dirname)
3367 self.tempdirs.append(dirname)
3151
3368
3152 handle, filename = tempfile.mkstemp('.py', prefix, dir=dirname)
3369 handle, filename = tempfile.mkstemp('.py', prefix, dir=dirname)
3153 os.close(handle) # On Windows, there can only be one open handle on a file
3370 os.close(handle) # On Windows, there can only be one open handle on a file
3154 self.tempfiles.append(filename)
3371 self.tempfiles.append(filename)
3155
3372
3156 if data:
3373 if data:
3157 tmp_file = open(filename,'w')
3374 tmp_file = open(filename,'w')
3158 tmp_file.write(data)
3375 tmp_file.write(data)
3159 tmp_file.close()
3376 tmp_file.close()
3160 return filename
3377 return filename
3161
3378
3162 @undoc
3379 @undoc
3163 def write(self,data):
3380 def write(self,data):
3164 """DEPRECATED: Write a string to the default output"""
3381 """DEPRECATED: Write a string to the default output"""
3165 warn('InteractiveShell.write() is deprecated, use sys.stdout instead',
3382 warn('InteractiveShell.write() is deprecated, use sys.stdout instead',
3166 DeprecationWarning, stacklevel=2)
3383 DeprecationWarning, stacklevel=2)
3167 sys.stdout.write(data)
3384 sys.stdout.write(data)
3168
3385
3169 @undoc
3386 @undoc
3170 def write_err(self,data):
3387 def write_err(self,data):
3171 """DEPRECATED: Write a string to the default error output"""
3388 """DEPRECATED: Write a string to the default error output"""
3172 warn('InteractiveShell.write_err() is deprecated, use sys.stderr instead',
3389 warn('InteractiveShell.write_err() is deprecated, use sys.stderr instead',
3173 DeprecationWarning, stacklevel=2)
3390 DeprecationWarning, stacklevel=2)
3174 sys.stderr.write(data)
3391 sys.stderr.write(data)
3175
3392
3176 def ask_yes_no(self, prompt, default=None, interrupt=None):
3393 def ask_yes_no(self, prompt, default=None, interrupt=None):
3177 if self.quiet:
3394 if self.quiet:
3178 return True
3395 return True
3179 return ask_yes_no(prompt,default,interrupt)
3396 return ask_yes_no(prompt,default,interrupt)
3180
3397
3181 def show_usage(self):
3398 def show_usage(self):
3182 """Show a usage message"""
3399 """Show a usage message"""
3183 page.page(IPython.core.usage.interactive_usage)
3400 page.page(IPython.core.usage.interactive_usage)
3184
3401
3185 def extract_input_lines(self, range_str, raw=False):
3402 def extract_input_lines(self, range_str, raw=False):
3186 """Return as a string a set of input history slices.
3403 """Return as a string a set of input history slices.
3187
3404
3188 Parameters
3405 Parameters
3189 ----------
3406 ----------
3190 range_str : string
3407 range_str : string
3191 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3408 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3192 since this function is for use by magic functions which get their
3409 since this function is for use by magic functions which get their
3193 arguments as strings. The number before the / is the session
3410 arguments as strings. The number before the / is the session
3194 number: ~n goes n back from the current session.
3411 number: ~n goes n back from the current session.
3195
3412
3196 raw : bool, optional
3413 raw : bool, optional
3197 By default, the processed input is used. If this is true, the raw
3414 By default, the processed input is used. If this is true, the raw
3198 input history is used instead.
3415 input history is used instead.
3199
3416
3200 Notes
3417 Notes
3201 -----
3418 -----
3202
3419
3203 Slices can be described with two notations:
3420 Slices can be described with two notations:
3204
3421
3205 * ``N:M`` -> standard python form, means including items N...(M-1).
3422 * ``N:M`` -> standard python form, means including items N...(M-1).
3206 * ``N-M`` -> include items N..M (closed endpoint).
3423 * ``N-M`` -> include items N..M (closed endpoint).
3207 """
3424 """
3208 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3425 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3209 return "\n".join(x for _, _, x in lines)
3426 return "\n".join(x for _, _, x in lines)
3210
3427
3211 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3428 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3212 """Get a code string from history, file, url, or a string or macro.
3429 """Get a code string from history, file, url, or a string or macro.
3213
3430
3214 This is mainly used by magic functions.
3431 This is mainly used by magic functions.
3215
3432
3216 Parameters
3433 Parameters
3217 ----------
3434 ----------
3218
3435
3219 target : str
3436 target : str
3220
3437
3221 A string specifying code to retrieve. This will be tried respectively
3438 A string specifying code to retrieve. This will be tried respectively
3222 as: ranges of input history (see %history for syntax), url,
3439 as: ranges of input history (see %history for syntax), url,
3223 corresponding .py file, filename, or an expression evaluating to a
3440 corresponding .py file, filename, or an expression evaluating to a
3224 string or Macro in the user namespace.
3441 string or Macro in the user namespace.
3225
3442
3226 raw : bool
3443 raw : bool
3227 If true (default), retrieve raw history. Has no effect on the other
3444 If true (default), retrieve raw history. Has no effect on the other
3228 retrieval mechanisms.
3445 retrieval mechanisms.
3229
3446
3230 py_only : bool (default False)
3447 py_only : bool (default False)
3231 Only try to fetch python code, do not try alternative methods to decode file
3448 Only try to fetch python code, do not try alternative methods to decode file
3232 if unicode fails.
3449 if unicode fails.
3233
3450
3234 Returns
3451 Returns
3235 -------
3452 -------
3236 A string of code.
3453 A string of code.
3237
3454
3238 ValueError is raised if nothing is found, and TypeError if it evaluates
3455 ValueError is raised if nothing is found, and TypeError if it evaluates
3239 to an object of another type. In each case, .args[0] is a printable
3456 to an object of another type. In each case, .args[0] is a printable
3240 message.
3457 message.
3241 """
3458 """
3242 code = self.extract_input_lines(target, raw=raw) # Grab history
3459 code = self.extract_input_lines(target, raw=raw) # Grab history
3243 if code:
3460 if code:
3244 return code
3461 return code
3245 try:
3462 try:
3246 if target.startswith(('http://', 'https://')):
3463 if target.startswith(('http://', 'https://')):
3247 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3464 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3248 except UnicodeDecodeError:
3465 except UnicodeDecodeError:
3249 if not py_only :
3466 if not py_only :
3250 # Deferred import
3467 # Deferred import
3251 from urllib.request import urlopen
3468 from urllib.request import urlopen
3252 response = urlopen(target)
3469 response = urlopen(target)
3253 return response.read().decode('latin1')
3470 return response.read().decode('latin1')
3254 raise ValueError(("'%s' seem to be unreadable.") % target)
3471 raise ValueError(("'%s' seem to be unreadable.") % target)
3255
3472
3256 potential_target = [target]
3473 potential_target = [target]
3257 try :
3474 try :
3258 potential_target.insert(0,get_py_filename(target))
3475 potential_target.insert(0,get_py_filename(target))
3259 except IOError:
3476 except IOError:
3260 pass
3477 pass
3261
3478
3262 for tgt in potential_target :
3479 for tgt in potential_target :
3263 if os.path.isfile(tgt): # Read file
3480 if os.path.isfile(tgt): # Read file
3264 try :
3481 try :
3265 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3482 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3266 except UnicodeDecodeError :
3483 except UnicodeDecodeError :
3267 if not py_only :
3484 if not py_only :
3268 with io_open(tgt,'r', encoding='latin1') as f :
3485 with io_open(tgt,'r', encoding='latin1') as f :
3269 return f.read()
3486 return f.read()
3270 raise ValueError(("'%s' seem to be unreadable.") % target)
3487 raise ValueError(("'%s' seem to be unreadable.") % target)
3271 elif os.path.isdir(os.path.expanduser(tgt)):
3488 elif os.path.isdir(os.path.expanduser(tgt)):
3272 raise ValueError("'%s' is a directory, not a regular file." % target)
3489 raise ValueError("'%s' is a directory, not a regular file." % target)
3273
3490
3274 if search_ns:
3491 if search_ns:
3275 # Inspect namespace to load object source
3492 # Inspect namespace to load object source
3276 object_info = self.object_inspect(target, detail_level=1)
3493 object_info = self.object_inspect(target, detail_level=1)
3277 if object_info['found'] and object_info['source']:
3494 if object_info['found'] and object_info['source']:
3278 return object_info['source']
3495 return object_info['source']
3279
3496
3280 try: # User namespace
3497 try: # User namespace
3281 codeobj = eval(target, self.user_ns)
3498 codeobj = eval(target, self.user_ns)
3282 except Exception:
3499 except Exception:
3283 raise ValueError(("'%s' was not found in history, as a file, url, "
3500 raise ValueError(("'%s' was not found in history, as a file, url, "
3284 "nor in the user namespace.") % target)
3501 "nor in the user namespace.") % target)
3285
3502
3286 if isinstance(codeobj, str):
3503 if isinstance(codeobj, str):
3287 return codeobj
3504 return codeobj
3288 elif isinstance(codeobj, Macro):
3505 elif isinstance(codeobj, Macro):
3289 return codeobj.value
3506 return codeobj.value
3290
3507
3291 raise TypeError("%s is neither a string nor a macro." % target,
3508 raise TypeError("%s is neither a string nor a macro." % target,
3292 codeobj)
3509 codeobj)
3293
3510
3294 #-------------------------------------------------------------------------
3511 #-------------------------------------------------------------------------
3295 # Things related to IPython exiting
3512 # Things related to IPython exiting
3296 #-------------------------------------------------------------------------
3513 #-------------------------------------------------------------------------
3297 def atexit_operations(self):
3514 def atexit_operations(self):
3298 """This will be executed at the time of exit.
3515 """This will be executed at the time of exit.
3299
3516
3300 Cleanup operations and saving of persistent data that is done
3517 Cleanup operations and saving of persistent data that is done
3301 unconditionally by IPython should be performed here.
3518 unconditionally by IPython should be performed here.
3302
3519
3303 For things that may depend on startup flags or platform specifics (such
3520 For things that may depend on startup flags or platform specifics (such
3304 as having readline or not), register a separate atexit function in the
3521 as having readline or not), register a separate atexit function in the
3305 code that has the appropriate information, rather than trying to
3522 code that has the appropriate information, rather than trying to
3306 clutter
3523 clutter
3307 """
3524 """
3308 # Close the history session (this stores the end time and line count)
3525 # Close the history session (this stores the end time and line count)
3309 # this must be *before* the tempfile cleanup, in case of temporary
3526 # this must be *before* the tempfile cleanup, in case of temporary
3310 # history db
3527 # history db
3311 self.history_manager.end_session()
3528 self.history_manager.end_session()
3312
3529
3313 # Cleanup all tempfiles and folders left around
3530 # Cleanup all tempfiles and folders left around
3314 for tfile in self.tempfiles:
3531 for tfile in self.tempfiles:
3315 try:
3532 try:
3316 os.unlink(tfile)
3533 os.unlink(tfile)
3317 except OSError:
3534 except OSError:
3318 pass
3535 pass
3319
3536
3320 for tdir in self.tempdirs:
3537 for tdir in self.tempdirs:
3321 try:
3538 try:
3322 os.rmdir(tdir)
3539 os.rmdir(tdir)
3323 except OSError:
3540 except OSError:
3324 pass
3541 pass
3325
3542
3326 # Clear all user namespaces to release all references cleanly.
3543 # Clear all user namespaces to release all references cleanly.
3327 self.reset(new_session=False)
3544 self.reset(new_session=False)
3328
3545
3329 # Run user hooks
3546 # Run user hooks
3330 self.hooks.shutdown_hook()
3547 self.hooks.shutdown_hook()
3331
3548
3332 def cleanup(self):
3549 def cleanup(self):
3333 self.restore_sys_module_state()
3550 self.restore_sys_module_state()
3334
3551
3335
3552
3336 # Overridden in terminal subclass to change prompts
3553 # Overridden in terminal subclass to change prompts
3337 def switch_doctest_mode(self, mode):
3554 def switch_doctest_mode(self, mode):
3338 pass
3555 pass
3339
3556
3340
3557
3341 class InteractiveShellABC(metaclass=abc.ABCMeta):
3558 class InteractiveShellABC(metaclass=abc.ABCMeta):
3342 """An abstract base class for InteractiveShell."""
3559 """An abstract base class for InteractiveShell."""
3343
3560
3344 InteractiveShellABC.register(InteractiveShell)
3561 InteractiveShellABC.register(InteractiveShell)
@@ -1,599 +1,658 b''
1 """Implementation of basic magic functions."""
1 """Implementation of basic magic functions."""
2
2
3
3
4 import argparse
4 import argparse
5 import textwrap
5 from logging import error
6 import io
6 import io
7 import sys
8 from pprint import pformat
7 from pprint import pformat
8 import textwrap
9 import sys
10 from warnings import warn
9
11
12 from traitlets.utils.importstring import import_item
10 from IPython.core import magic_arguments, page
13 from IPython.core import magic_arguments, page
11 from IPython.core.error import UsageError
14 from IPython.core.error import UsageError
12 from IPython.core.magic import Magics, magics_class, line_magic, magic_escapes
15 from IPython.core.magic import Magics, magics_class, line_magic, magic_escapes
13 from IPython.utils.text import format_screen, dedent, indent
16 from IPython.utils.text import format_screen, dedent, indent
14 from IPython.testing.skipdoctest import skip_doctest
17 from IPython.testing.skipdoctest import skip_doctest
15 from IPython.utils.ipstruct import Struct
18 from IPython.utils.ipstruct import Struct
16 from warnings import warn
17 from logging import error
18
19
19
20
20 class MagicsDisplay(object):
21 class MagicsDisplay(object):
21 def __init__(self, magics_manager, ignore=None):
22 def __init__(self, magics_manager, ignore=None):
22 self.ignore = ignore if ignore else []
23 self.ignore = ignore if ignore else []
23 self.magics_manager = magics_manager
24 self.magics_manager = magics_manager
24
25
25 def _lsmagic(self):
26 def _lsmagic(self):
26 """The main implementation of the %lsmagic"""
27 """The main implementation of the %lsmagic"""
27 mesc = magic_escapes['line']
28 mesc = magic_escapes['line']
28 cesc = magic_escapes['cell']
29 cesc = magic_escapes['cell']
29 mman = self.magics_manager
30 mman = self.magics_manager
30 magics = mman.lsmagic()
31 magics = mman.lsmagic()
31 out = ['Available line magics:',
32 out = ['Available line magics:',
32 mesc + (' '+mesc).join(sorted([m for m,v in magics['line'].items() if (v not in self.ignore)])),
33 mesc + (' '+mesc).join(sorted([m for m,v in magics['line'].items() if (v not in self.ignore)])),
33 '',
34 '',
34 'Available cell magics:',
35 'Available cell magics:',
35 cesc + (' '+cesc).join(sorted([m for m,v in magics['cell'].items() if (v not in self.ignore)])),
36 cesc + (' '+cesc).join(sorted([m for m,v in magics['cell'].items() if (v not in self.ignore)])),
36 '',
37 '',
37 mman.auto_status()]
38 mman.auto_status()]
38 return '\n'.join(out)
39 return '\n'.join(out)
39
40
40 def _repr_pretty_(self, p, cycle):
41 def _repr_pretty_(self, p, cycle):
41 p.text(self._lsmagic())
42 p.text(self._lsmagic())
42
43
43 def __str__(self):
44 def __str__(self):
44 return self._lsmagic()
45 return self._lsmagic()
45
46
46 def _jsonable(self):
47 def _jsonable(self):
47 """turn magics dict into jsonable dict of the same structure
48 """turn magics dict into jsonable dict of the same structure
48
49
49 replaces object instances with their class names as strings
50 replaces object instances with their class names as strings
50 """
51 """
51 magic_dict = {}
52 magic_dict = {}
52 mman = self.magics_manager
53 mman = self.magics_manager
53 magics = mman.lsmagic()
54 magics = mman.lsmagic()
54 for key, subdict in magics.items():
55 for key, subdict in magics.items():
55 d = {}
56 d = {}
56 magic_dict[key] = d
57 magic_dict[key] = d
57 for name, obj in subdict.items():
58 for name, obj in subdict.items():
58 try:
59 try:
59 classname = obj.__self__.__class__.__name__
60 classname = obj.__self__.__class__.__name__
60 except AttributeError:
61 except AttributeError:
61 classname = 'Other'
62 classname = 'Other'
62
63
63 d[name] = classname
64 d[name] = classname
64 return magic_dict
65 return magic_dict
65
66
66 def _repr_json_(self):
67 def _repr_json_(self):
67 return self._jsonable()
68 return self._jsonable()
68
69
69
70
70 @magics_class
71 @magics_class
71 class BasicMagics(Magics):
72 class BasicMagics(Magics):
72 """Magics that provide central IPython functionality.
73 """Magics that provide central IPython functionality.
73
74
74 These are various magics that don't fit into specific categories but that
75 These are various magics that don't fit into specific categories but that
75 are all part of the base 'IPython experience'."""
76 are all part of the base 'IPython experience'."""
76
77
77 @magic_arguments.magic_arguments()
78 @magic_arguments.magic_arguments()
78 @magic_arguments.argument(
79 @magic_arguments.argument(
79 '-l', '--line', action='store_true',
80 '-l', '--line', action='store_true',
80 help="""Create a line magic alias."""
81 help="""Create a line magic alias."""
81 )
82 )
82 @magic_arguments.argument(
83 @magic_arguments.argument(
83 '-c', '--cell', action='store_true',
84 '-c', '--cell', action='store_true',
84 help="""Create a cell magic alias."""
85 help="""Create a cell magic alias."""
85 )
86 )
86 @magic_arguments.argument(
87 @magic_arguments.argument(
87 'name',
88 'name',
88 help="""Name of the magic to be created."""
89 help="""Name of the magic to be created."""
89 )
90 )
90 @magic_arguments.argument(
91 @magic_arguments.argument(
91 'target',
92 'target',
92 help="""Name of the existing line or cell magic."""
93 help="""Name of the existing line or cell magic."""
93 )
94 )
94 @magic_arguments.argument(
95 @magic_arguments.argument(
95 '-p', '--params', default=None,
96 '-p', '--params', default=None,
96 help="""Parameters passed to the magic function."""
97 help="""Parameters passed to the magic function."""
97 )
98 )
98 @line_magic
99 @line_magic
99 def alias_magic(self, line=''):
100 def alias_magic(self, line=''):
100 """Create an alias for an existing line or cell magic.
101 """Create an alias for an existing line or cell magic.
101
102
102 Examples
103 Examples
103 --------
104 --------
104 ::
105 ::
105
106
106 In [1]: %alias_magic t timeit
107 In [1]: %alias_magic t timeit
107 Created `%t` as an alias for `%timeit`.
108 Created `%t` as an alias for `%timeit`.
108 Created `%%t` as an alias for `%%timeit`.
109 Created `%%t` as an alias for `%%timeit`.
109
110
110 In [2]: %t -n1 pass
111 In [2]: %t -n1 pass
111 1 loops, best of 3: 954 ns per loop
112 1 loops, best of 3: 954 ns per loop
112
113
113 In [3]: %%t -n1
114 In [3]: %%t -n1
114 ...: pass
115 ...: pass
115 ...:
116 ...:
116 1 loops, best of 3: 954 ns per loop
117 1 loops, best of 3: 954 ns per loop
117
118
118 In [4]: %alias_magic --cell whereami pwd
119 In [4]: %alias_magic --cell whereami pwd
119 UsageError: Cell magic function `%%pwd` not found.
120 UsageError: Cell magic function `%%pwd` not found.
120 In [5]: %alias_magic --line whereami pwd
121 In [5]: %alias_magic --line whereami pwd
121 Created `%whereami` as an alias for `%pwd`.
122 Created `%whereami` as an alias for `%pwd`.
122
123
123 In [6]: %whereami
124 In [6]: %whereami
124 Out[6]: u'/home/testuser'
125 Out[6]: u'/home/testuser'
125
126
126 In [7]: %alias_magic h history -p "-l 30" --line
127 In [7]: %alias_magic h history -p "-l 30" --line
127 Created `%h` as an alias for `%history -l 30`.
128 Created `%h` as an alias for `%history -l 30`.
128 """
129 """
129
130
130 args = magic_arguments.parse_argstring(self.alias_magic, line)
131 args = magic_arguments.parse_argstring(self.alias_magic, line)
131 shell = self.shell
132 shell = self.shell
132 mman = self.shell.magics_manager
133 mman = self.shell.magics_manager
133 escs = ''.join(magic_escapes.values())
134 escs = ''.join(magic_escapes.values())
134
135
135 target = args.target.lstrip(escs)
136 target = args.target.lstrip(escs)
136 name = args.name.lstrip(escs)
137 name = args.name.lstrip(escs)
137
138
138 params = args.params
139 params = args.params
139 if (params and
140 if (params and
140 ((params.startswith('"') and params.endswith('"'))
141 ((params.startswith('"') and params.endswith('"'))
141 or (params.startswith("'") and params.endswith("'")))):
142 or (params.startswith("'") and params.endswith("'")))):
142 params = params[1:-1]
143 params = params[1:-1]
143
144
144 # Find the requested magics.
145 # Find the requested magics.
145 m_line = shell.find_magic(target, 'line')
146 m_line = shell.find_magic(target, 'line')
146 m_cell = shell.find_magic(target, 'cell')
147 m_cell = shell.find_magic(target, 'cell')
147 if args.line and m_line is None:
148 if args.line and m_line is None:
148 raise UsageError('Line magic function `%s%s` not found.' %
149 raise UsageError('Line magic function `%s%s` not found.' %
149 (magic_escapes['line'], target))
150 (magic_escapes['line'], target))
150 if args.cell and m_cell is None:
151 if args.cell and m_cell is None:
151 raise UsageError('Cell magic function `%s%s` not found.' %
152 raise UsageError('Cell magic function `%s%s` not found.' %
152 (magic_escapes['cell'], target))
153 (magic_escapes['cell'], target))
153
154
154 # If --line and --cell are not specified, default to the ones
155 # If --line and --cell are not specified, default to the ones
155 # that are available.
156 # that are available.
156 if not args.line and not args.cell:
157 if not args.line and not args.cell:
157 if not m_line and not m_cell:
158 if not m_line and not m_cell:
158 raise UsageError(
159 raise UsageError(
159 'No line or cell magic with name `%s` found.' % target
160 'No line or cell magic with name `%s` found.' % target
160 )
161 )
161 args.line = bool(m_line)
162 args.line = bool(m_line)
162 args.cell = bool(m_cell)
163 args.cell = bool(m_cell)
163
164
164 params_str = "" if params is None else " " + params
165 params_str = "" if params is None else " " + params
165
166
166 if args.line:
167 if args.line:
167 mman.register_alias(name, target, 'line', params)
168 mman.register_alias(name, target, 'line', params)
168 print('Created `%s%s` as an alias for `%s%s%s`.' % (
169 print('Created `%s%s` as an alias for `%s%s%s`.' % (
169 magic_escapes['line'], name,
170 magic_escapes['line'], name,
170 magic_escapes['line'], target, params_str))
171 magic_escapes['line'], target, params_str))
171
172
172 if args.cell:
173 if args.cell:
173 mman.register_alias(name, target, 'cell', params)
174 mman.register_alias(name, target, 'cell', params)
174 print('Created `%s%s` as an alias for `%s%s%s`.' % (
175 print('Created `%s%s` as an alias for `%s%s%s`.' % (
175 magic_escapes['cell'], name,
176 magic_escapes['cell'], name,
176 magic_escapes['cell'], target, params_str))
177 magic_escapes['cell'], target, params_str))
177
178
178 @line_magic
179 @line_magic
179 def lsmagic(self, parameter_s=''):
180 def lsmagic(self, parameter_s=''):
180 """List currently available magic functions."""
181 """List currently available magic functions."""
181 return MagicsDisplay(self.shell.magics_manager, ignore=[self.pip])
182 return MagicsDisplay(self.shell.magics_manager, ignore=[self.pip])
182
183
183 def _magic_docs(self, brief=False, rest=False):
184 def _magic_docs(self, brief=False, rest=False):
184 """Return docstrings from magic functions."""
185 """Return docstrings from magic functions."""
185 mman = self.shell.magics_manager
186 mman = self.shell.magics_manager
186 docs = mman.lsmagic_docs(brief, missing='No documentation')
187 docs = mman.lsmagic_docs(brief, missing='No documentation')
187
188
188 if rest:
189 if rest:
189 format_string = '**%s%s**::\n\n%s\n\n'
190 format_string = '**%s%s**::\n\n%s\n\n'
190 else:
191 else:
191 format_string = '%s%s:\n%s\n'
192 format_string = '%s%s:\n%s\n'
192
193
193 return ''.join(
194 return ''.join(
194 [format_string % (magic_escapes['line'], fname,
195 [format_string % (magic_escapes['line'], fname,
195 indent(dedent(fndoc)))
196 indent(dedent(fndoc)))
196 for fname, fndoc in sorted(docs['line'].items())]
197 for fname, fndoc in sorted(docs['line'].items())]
197 +
198 +
198 [format_string % (magic_escapes['cell'], fname,
199 [format_string % (magic_escapes['cell'], fname,
199 indent(dedent(fndoc)))
200 indent(dedent(fndoc)))
200 for fname, fndoc in sorted(docs['cell'].items())]
201 for fname, fndoc in sorted(docs['cell'].items())]
201 )
202 )
202
203
203 @line_magic
204 @line_magic
204 def magic(self, parameter_s=''):
205 def magic(self, parameter_s=''):
205 """Print information about the magic function system.
206 """Print information about the magic function system.
206
207
207 Supported formats: -latex, -brief, -rest
208 Supported formats: -latex, -brief, -rest
208 """
209 """
209
210
210 mode = ''
211 mode = ''
211 try:
212 try:
212 mode = parameter_s.split()[0][1:]
213 mode = parameter_s.split()[0][1:]
213 except IndexError:
214 except IndexError:
214 pass
215 pass
215
216
216 brief = (mode == 'brief')
217 brief = (mode == 'brief')
217 rest = (mode == 'rest')
218 rest = (mode == 'rest')
218 magic_docs = self._magic_docs(brief, rest)
219 magic_docs = self._magic_docs(brief, rest)
219
220
220 if mode == 'latex':
221 if mode == 'latex':
221 print(self.format_latex(magic_docs))
222 print(self.format_latex(magic_docs))
222 return
223 return
223 else:
224 else:
224 magic_docs = format_screen(magic_docs)
225 magic_docs = format_screen(magic_docs)
225
226
226 out = ["""
227 out = ["""
227 IPython's 'magic' functions
228 IPython's 'magic' functions
228 ===========================
229 ===========================
229
230
230 The magic function system provides a series of functions which allow you to
231 The magic function system provides a series of functions which allow you to
231 control the behavior of IPython itself, plus a lot of system-type
232 control the behavior of IPython itself, plus a lot of system-type
232 features. There are two kinds of magics, line-oriented and cell-oriented.
233 features. There are two kinds of magics, line-oriented and cell-oriented.
233
234
234 Line magics are prefixed with the % character and work much like OS
235 Line magics are prefixed with the % character and work much like OS
235 command-line calls: they get as an argument the rest of the line, where
236 command-line calls: they get as an argument the rest of the line, where
236 arguments are passed without parentheses or quotes. For example, this will
237 arguments are passed without parentheses or quotes. For example, this will
237 time the given statement::
238 time the given statement::
238
239
239 %timeit range(1000)
240 %timeit range(1000)
240
241
241 Cell magics are prefixed with a double %%, and they are functions that get as
242 Cell magics are prefixed with a double %%, and they are functions that get as
242 an argument not only the rest of the line, but also the lines below it in a
243 an argument not only the rest of the line, but also the lines below it in a
243 separate argument. These magics are called with two arguments: the rest of the
244 separate argument. These magics are called with two arguments: the rest of the
244 call line and the body of the cell, consisting of the lines below the first.
245 call line and the body of the cell, consisting of the lines below the first.
245 For example::
246 For example::
246
247
247 %%timeit x = numpy.random.randn((100, 100))
248 %%timeit x = numpy.random.randn((100, 100))
248 numpy.linalg.svd(x)
249 numpy.linalg.svd(x)
249
250
250 will time the execution of the numpy svd routine, running the assignment of x
251 will time the execution of the numpy svd routine, running the assignment of x
251 as part of the setup phase, which is not timed.
252 as part of the setup phase, which is not timed.
252
253
253 In a line-oriented client (the terminal or Qt console IPython), starting a new
254 In a line-oriented client (the terminal or Qt console IPython), starting a new
254 input with %% will automatically enter cell mode, and IPython will continue
255 input with %% will automatically enter cell mode, and IPython will continue
255 reading input until a blank line is given. In the notebook, simply type the
256 reading input until a blank line is given. In the notebook, simply type the
256 whole cell as one entity, but keep in mind that the %% escape can only be at
257 whole cell as one entity, but keep in mind that the %% escape can only be at
257 the very start of the cell.
258 the very start of the cell.
258
259
259 NOTE: If you have 'automagic' enabled (via the command line option or with the
260 NOTE: If you have 'automagic' enabled (via the command line option or with the
260 %automagic function), you don't need to type in the % explicitly for line
261 %automagic function), you don't need to type in the % explicitly for line
261 magics; cell magics always require an explicit '%%' escape. By default,
262 magics; cell magics always require an explicit '%%' escape. By default,
262 IPython ships with automagic on, so you should only rarely need the % escape.
263 IPython ships with automagic on, so you should only rarely need the % escape.
263
264
264 Example: typing '%cd mydir' (without the quotes) changes your working directory
265 Example: typing '%cd mydir' (without the quotes) changes your working directory
265 to 'mydir', if it exists.
266 to 'mydir', if it exists.
266
267
267 For a list of the available magic functions, use %lsmagic. For a description
268 For a list of the available magic functions, use %lsmagic. For a description
268 of any of them, type %magic_name?, e.g. '%cd?'.
269 of any of them, type %magic_name?, e.g. '%cd?'.
269
270
270 Currently the magic system has the following functions:""",
271 Currently the magic system has the following functions:""",
271 magic_docs,
272 magic_docs,
272 "Summary of magic functions (from %slsmagic):" % magic_escapes['line'],
273 "Summary of magic functions (from %slsmagic):" % magic_escapes['line'],
273 str(self.lsmagic()),
274 str(self.lsmagic()),
274 ]
275 ]
275 page.page('\n'.join(out))
276 page.page('\n'.join(out))
276
277
277
278
278 @line_magic
279 @line_magic
279 def page(self, parameter_s=''):
280 def page(self, parameter_s=''):
280 """Pretty print the object and display it through a pager.
281 """Pretty print the object and display it through a pager.
281
282
282 %page [options] OBJECT
283 %page [options] OBJECT
283
284
284 If no object is given, use _ (last output).
285 If no object is given, use _ (last output).
285
286
286 Options:
287 Options:
287
288
288 -r: page str(object), don't pretty-print it."""
289 -r: page str(object), don't pretty-print it."""
289
290
290 # After a function contributed by Olivier Aubert, slightly modified.
291 # After a function contributed by Olivier Aubert, slightly modified.
291
292
292 # Process options/args
293 # Process options/args
293 opts, args = self.parse_options(parameter_s, 'r')
294 opts, args = self.parse_options(parameter_s, 'r')
294 raw = 'r' in opts
295 raw = 'r' in opts
295
296
296 oname = args and args or '_'
297 oname = args and args or '_'
297 info = self.shell._ofind(oname)
298 info = self.shell._ofind(oname)
298 if info['found']:
299 if info['found']:
299 txt = (raw and str or pformat)( info['obj'] )
300 txt = (raw and str or pformat)( info['obj'] )
300 page.page(txt)
301 page.page(txt)
301 else:
302 else:
302 print('Object `%s` not found' % oname)
303 print('Object `%s` not found' % oname)
303
304
304 @line_magic
305 @line_magic
305 def pprint(self, parameter_s=''):
306 def pprint(self, parameter_s=''):
306 """Toggle pretty printing on/off."""
307 """Toggle pretty printing on/off."""
307 ptformatter = self.shell.display_formatter.formatters['text/plain']
308 ptformatter = self.shell.display_formatter.formatters['text/plain']
308 ptformatter.pprint = bool(1 - ptformatter.pprint)
309 ptformatter.pprint = bool(1 - ptformatter.pprint)
309 print('Pretty printing has been turned',
310 print('Pretty printing has been turned',
310 ['OFF','ON'][ptformatter.pprint])
311 ['OFF','ON'][ptformatter.pprint])
311
312
312 @line_magic
313 @line_magic
313 def colors(self, parameter_s=''):
314 def colors(self, parameter_s=''):
314 """Switch color scheme for prompts, info system and exception handlers.
315 """Switch color scheme for prompts, info system and exception handlers.
315
316
316 Currently implemented schemes: NoColor, Linux, LightBG.
317 Currently implemented schemes: NoColor, Linux, LightBG.
317
318
318 Color scheme names are not case-sensitive.
319 Color scheme names are not case-sensitive.
319
320
320 Examples
321 Examples
321 --------
322 --------
322 To get a plain black and white terminal::
323 To get a plain black and white terminal::
323
324
324 %colors nocolor
325 %colors nocolor
325 """
326 """
326 def color_switch_err(name):
327 def color_switch_err(name):
327 warn('Error changing %s color schemes.\n%s' %
328 warn('Error changing %s color schemes.\n%s' %
328 (name, sys.exc_info()[1]), stacklevel=2)
329 (name, sys.exc_info()[1]), stacklevel=2)
329
330
330
331
331 new_scheme = parameter_s.strip()
332 new_scheme = parameter_s.strip()
332 if not new_scheme:
333 if not new_scheme:
333 raise UsageError(
334 raise UsageError(
334 "%colors: you must specify a color scheme. See '%colors?'")
335 "%colors: you must specify a color scheme. See '%colors?'")
335 # local shortcut
336 # local shortcut
336 shell = self.shell
337 shell = self.shell
337
338
338 # Set shell colour scheme
339 # Set shell colour scheme
339 try:
340 try:
340 shell.colors = new_scheme
341 shell.colors = new_scheme
341 shell.refresh_style()
342 shell.refresh_style()
342 except:
343 except:
343 color_switch_err('shell')
344 color_switch_err('shell')
344
345
345 # Set exception colors
346 # Set exception colors
346 try:
347 try:
347 shell.InteractiveTB.set_colors(scheme = new_scheme)
348 shell.InteractiveTB.set_colors(scheme = new_scheme)
348 shell.SyntaxTB.set_colors(scheme = new_scheme)
349 shell.SyntaxTB.set_colors(scheme = new_scheme)
349 except:
350 except:
350 color_switch_err('exception')
351 color_switch_err('exception')
351
352
352 # Set info (for 'object?') colors
353 # Set info (for 'object?') colors
353 if shell.color_info:
354 if shell.color_info:
354 try:
355 try:
355 shell.inspector.set_active_scheme(new_scheme)
356 shell.inspector.set_active_scheme(new_scheme)
356 except:
357 except:
357 color_switch_err('object inspector')
358 color_switch_err('object inspector')
358 else:
359 else:
359 shell.inspector.set_active_scheme('NoColor')
360 shell.inspector.set_active_scheme('NoColor')
360
361
361 @line_magic
362 @line_magic
362 def xmode(self, parameter_s=''):
363 def xmode(self, parameter_s=''):
363 """Switch modes for the exception handlers.
364 """Switch modes for the exception handlers.
364
365
365 Valid modes: Plain, Context and Verbose.
366 Valid modes: Plain, Context and Verbose.
366
367
367 If called without arguments, acts as a toggle."""
368 If called without arguments, acts as a toggle."""
368
369
369 def xmode_switch_err(name):
370 def xmode_switch_err(name):
370 warn('Error changing %s exception modes.\n%s' %
371 warn('Error changing %s exception modes.\n%s' %
371 (name,sys.exc_info()[1]))
372 (name,sys.exc_info()[1]))
372
373
373 shell = self.shell
374 shell = self.shell
374 new_mode = parameter_s.strip().capitalize()
375 new_mode = parameter_s.strip().capitalize()
375 try:
376 try:
376 shell.InteractiveTB.set_mode(mode=new_mode)
377 shell.InteractiveTB.set_mode(mode=new_mode)
377 print('Exception reporting mode:',shell.InteractiveTB.mode)
378 print('Exception reporting mode:',shell.InteractiveTB.mode)
378 except:
379 except:
379 xmode_switch_err('user')
380 xmode_switch_err('user')
380
381
381 @line_magic
382 @line_magic
383 def autoawait(self, parameter_s):
384 """
385 Allow to change the status of the autoawait option.
386
387 This allow you to set a specific asynchronous code runner.
388
389 If no value is passed, print the currently used asynchronous integration
390 and whether it is activated.
391
392 It can take a number of value evaluated in the following order:
393
394 - False/false/off deactivate autoawait integration
395 - True/true/on activate autoawait integration using configured default
396 loop
397 - asyncio/curio/trio activate autoawait integration and use integration
398 with said library.
399
400 If the passed parameter does not match any of the above and is a python
401 identifier, get said object from user namespace and set it as the
402 runner, and activate autoawait.
403
404 If the object is a fully qualified object name, attempt to import it and
405 set it as the runner, and activate autoawait."""
406
407 param = parameter_s.strip()
408 d = {True: "on", False: "off"}
409
410 if not param:
411 print("IPython autoawait is `{}`, and set to use `{}`".format(
412 d[self.shell.autoawait],
413 self.shell.loop_runner
414 ))
415 return None
416
417 if param.lower() in ('false', 'off'):
418 self.shell.autoawait = False
419 return None
420 if param.lower() in ('true', 'on'):
421 self.shell.autoawait = True
422 return None
423
424 if param in self.shell.loop_runner_map:
425 self.shell.loop_runner = param
426 self.shell.autoawait = True
427 return None
428
429 if param in self.shell.user_ns :
430 self.shell.loop_runner = self.shell.user_ns[param]
431 self.shell.autoawait = True
432 return None
433
434 runner = import_item(param)
435
436 self.shell.loop_runner = runner
437 self.shell.autoawait = True
438
439
440 @line_magic
382 def pip(self, args=''):
441 def pip(self, args=''):
383 """
442 """
384 Intercept usage of ``pip`` in IPython and direct user to run command outside of IPython.
443 Intercept usage of ``pip`` in IPython and direct user to run command outside of IPython.
385 """
444 """
386 print(textwrap.dedent('''
445 print(textwrap.dedent('''
387 The following command must be run outside of the IPython shell:
446 The following command must be run outside of the IPython shell:
388
447
389 $ pip {args}
448 $ pip {args}
390
449
391 The Python package manager (pip) can only be used from outside of IPython.
450 The Python package manager (pip) can only be used from outside of IPython.
392 Please reissue the `pip` command in a separate terminal or command prompt.
451 Please reissue the `pip` command in a separate terminal or command prompt.
393
452
394 See the Python documentation for more information on how to install packages:
453 See the Python documentation for more information on how to install packages:
395
454
396 https://docs.python.org/3/installing/'''.format(args=args)))
455 https://docs.python.org/3/installing/'''.format(args=args)))
397
456
398 @line_magic
457 @line_magic
399 def quickref(self, arg):
458 def quickref(self, arg):
400 """ Show a quick reference sheet """
459 """ Show a quick reference sheet """
401 from IPython.core.usage import quick_reference
460 from IPython.core.usage import quick_reference
402 qr = quick_reference + self._magic_docs(brief=True)
461 qr = quick_reference + self._magic_docs(brief=True)
403 page.page(qr)
462 page.page(qr)
404
463
405 @line_magic
464 @line_magic
406 def doctest_mode(self, parameter_s=''):
465 def doctest_mode(self, parameter_s=''):
407 """Toggle doctest mode on and off.
466 """Toggle doctest mode on and off.
408
467
409 This mode is intended to make IPython behave as much as possible like a
468 This mode is intended to make IPython behave as much as possible like a
410 plain Python shell, from the perspective of how its prompts, exceptions
469 plain Python shell, from the perspective of how its prompts, exceptions
411 and output look. This makes it easy to copy and paste parts of a
470 and output look. This makes it easy to copy and paste parts of a
412 session into doctests. It does so by:
471 session into doctests. It does so by:
413
472
414 - Changing the prompts to the classic ``>>>`` ones.
473 - Changing the prompts to the classic ``>>>`` ones.
415 - Changing the exception reporting mode to 'Plain'.
474 - Changing the exception reporting mode to 'Plain'.
416 - Disabling pretty-printing of output.
475 - Disabling pretty-printing of output.
417
476
418 Note that IPython also supports the pasting of code snippets that have
477 Note that IPython also supports the pasting of code snippets that have
419 leading '>>>' and '...' prompts in them. This means that you can paste
478 leading '>>>' and '...' prompts in them. This means that you can paste
420 doctests from files or docstrings (even if they have leading
479 doctests from files or docstrings (even if they have leading
421 whitespace), and the code will execute correctly. You can then use
480 whitespace), and the code will execute correctly. You can then use
422 '%history -t' to see the translated history; this will give you the
481 '%history -t' to see the translated history; this will give you the
423 input after removal of all the leading prompts and whitespace, which
482 input after removal of all the leading prompts and whitespace, which
424 can be pasted back into an editor.
483 can be pasted back into an editor.
425
484
426 With these features, you can switch into this mode easily whenever you
485 With these features, you can switch into this mode easily whenever you
427 need to do testing and changes to doctests, without having to leave
486 need to do testing and changes to doctests, without having to leave
428 your existing IPython session.
487 your existing IPython session.
429 """
488 """
430
489
431 # Shorthands
490 # Shorthands
432 shell = self.shell
491 shell = self.shell
433 meta = shell.meta
492 meta = shell.meta
434 disp_formatter = self.shell.display_formatter
493 disp_formatter = self.shell.display_formatter
435 ptformatter = disp_formatter.formatters['text/plain']
494 ptformatter = disp_formatter.formatters['text/plain']
436 # dstore is a data store kept in the instance metadata bag to track any
495 # dstore is a data store kept in the instance metadata bag to track any
437 # changes we make, so we can undo them later.
496 # changes we make, so we can undo them later.
438 dstore = meta.setdefault('doctest_mode',Struct())
497 dstore = meta.setdefault('doctest_mode',Struct())
439 save_dstore = dstore.setdefault
498 save_dstore = dstore.setdefault
440
499
441 # save a few values we'll need to recover later
500 # save a few values we'll need to recover later
442 mode = save_dstore('mode',False)
501 mode = save_dstore('mode',False)
443 save_dstore('rc_pprint',ptformatter.pprint)
502 save_dstore('rc_pprint',ptformatter.pprint)
444 save_dstore('xmode',shell.InteractiveTB.mode)
503 save_dstore('xmode',shell.InteractiveTB.mode)
445 save_dstore('rc_separate_out',shell.separate_out)
504 save_dstore('rc_separate_out',shell.separate_out)
446 save_dstore('rc_separate_out2',shell.separate_out2)
505 save_dstore('rc_separate_out2',shell.separate_out2)
447 save_dstore('rc_separate_in',shell.separate_in)
506 save_dstore('rc_separate_in',shell.separate_in)
448 save_dstore('rc_active_types',disp_formatter.active_types)
507 save_dstore('rc_active_types',disp_formatter.active_types)
449
508
450 if not mode:
509 if not mode:
451 # turn on
510 # turn on
452
511
453 # Prompt separators like plain python
512 # Prompt separators like plain python
454 shell.separate_in = ''
513 shell.separate_in = ''
455 shell.separate_out = ''
514 shell.separate_out = ''
456 shell.separate_out2 = ''
515 shell.separate_out2 = ''
457
516
458
517
459 ptformatter.pprint = False
518 ptformatter.pprint = False
460 disp_formatter.active_types = ['text/plain']
519 disp_formatter.active_types = ['text/plain']
461
520
462 shell.magic('xmode Plain')
521 shell.magic('xmode Plain')
463 else:
522 else:
464 # turn off
523 # turn off
465 shell.separate_in = dstore.rc_separate_in
524 shell.separate_in = dstore.rc_separate_in
466
525
467 shell.separate_out = dstore.rc_separate_out
526 shell.separate_out = dstore.rc_separate_out
468 shell.separate_out2 = dstore.rc_separate_out2
527 shell.separate_out2 = dstore.rc_separate_out2
469
528
470 ptformatter.pprint = dstore.rc_pprint
529 ptformatter.pprint = dstore.rc_pprint
471 disp_formatter.active_types = dstore.rc_active_types
530 disp_formatter.active_types = dstore.rc_active_types
472
531
473 shell.magic('xmode ' + dstore.xmode)
532 shell.magic('xmode ' + dstore.xmode)
474
533
475 # mode here is the state before we switch; switch_doctest_mode takes
534 # mode here is the state before we switch; switch_doctest_mode takes
476 # the mode we're switching to.
535 # the mode we're switching to.
477 shell.switch_doctest_mode(not mode)
536 shell.switch_doctest_mode(not mode)
478
537
479 # Store new mode and inform
538 # Store new mode and inform
480 dstore.mode = bool(not mode)
539 dstore.mode = bool(not mode)
481 mode_label = ['OFF','ON'][dstore.mode]
540 mode_label = ['OFF','ON'][dstore.mode]
482 print('Doctest mode is:', mode_label)
541 print('Doctest mode is:', mode_label)
483
542
484 @line_magic
543 @line_magic
485 def gui(self, parameter_s=''):
544 def gui(self, parameter_s=''):
486 """Enable or disable IPython GUI event loop integration.
545 """Enable or disable IPython GUI event loop integration.
487
546
488 %gui [GUINAME]
547 %gui [GUINAME]
489
548
490 This magic replaces IPython's threaded shells that were activated
549 This magic replaces IPython's threaded shells that were activated
491 using the (pylab/wthread/etc.) command line flags. GUI toolkits
550 using the (pylab/wthread/etc.) command line flags. GUI toolkits
492 can now be enabled at runtime and keyboard
551 can now be enabled at runtime and keyboard
493 interrupts should work without any problems. The following toolkits
552 interrupts should work without any problems. The following toolkits
494 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
553 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
495
554
496 %gui wx # enable wxPython event loop integration
555 %gui wx # enable wxPython event loop integration
497 %gui qt4|qt # enable PyQt4 event loop integration
556 %gui qt4|qt # enable PyQt4 event loop integration
498 %gui qt5 # enable PyQt5 event loop integration
557 %gui qt5 # enable PyQt5 event loop integration
499 %gui gtk # enable PyGTK event loop integration
558 %gui gtk # enable PyGTK event loop integration
500 %gui gtk3 # enable Gtk3 event loop integration
559 %gui gtk3 # enable Gtk3 event loop integration
501 %gui tk # enable Tk event loop integration
560 %gui tk # enable Tk event loop integration
502 %gui osx # enable Cocoa event loop integration
561 %gui osx # enable Cocoa event loop integration
503 # (requires %matplotlib 1.1)
562 # (requires %matplotlib 1.1)
504 %gui # disable all event loop integration
563 %gui # disable all event loop integration
505
564
506 WARNING: after any of these has been called you can simply create
565 WARNING: after any of these has been called you can simply create
507 an application object, but DO NOT start the event loop yourself, as
566 an application object, but DO NOT start the event loop yourself, as
508 we have already handled that.
567 we have already handled that.
509 """
568 """
510 opts, arg = self.parse_options(parameter_s, '')
569 opts, arg = self.parse_options(parameter_s, '')
511 if arg=='': arg = None
570 if arg=='': arg = None
512 try:
571 try:
513 return self.shell.enable_gui(arg)
572 return self.shell.enable_gui(arg)
514 except Exception as e:
573 except Exception as e:
515 # print simple error message, rather than traceback if we can't
574 # print simple error message, rather than traceback if we can't
516 # hook up the GUI
575 # hook up the GUI
517 error(str(e))
576 error(str(e))
518
577
519 @skip_doctest
578 @skip_doctest
520 @line_magic
579 @line_magic
521 def precision(self, s=''):
580 def precision(self, s=''):
522 """Set floating point precision for pretty printing.
581 """Set floating point precision for pretty printing.
523
582
524 Can set either integer precision or a format string.
583 Can set either integer precision or a format string.
525
584
526 If numpy has been imported and precision is an int,
585 If numpy has been imported and precision is an int,
527 numpy display precision will also be set, via ``numpy.set_printoptions``.
586 numpy display precision will also be set, via ``numpy.set_printoptions``.
528
587
529 If no argument is given, defaults will be restored.
588 If no argument is given, defaults will be restored.
530
589
531 Examples
590 Examples
532 --------
591 --------
533 ::
592 ::
534
593
535 In [1]: from math import pi
594 In [1]: from math import pi
536
595
537 In [2]: %precision 3
596 In [2]: %precision 3
538 Out[2]: u'%.3f'
597 Out[2]: u'%.3f'
539
598
540 In [3]: pi
599 In [3]: pi
541 Out[3]: 3.142
600 Out[3]: 3.142
542
601
543 In [4]: %precision %i
602 In [4]: %precision %i
544 Out[4]: u'%i'
603 Out[4]: u'%i'
545
604
546 In [5]: pi
605 In [5]: pi
547 Out[5]: 3
606 Out[5]: 3
548
607
549 In [6]: %precision %e
608 In [6]: %precision %e
550 Out[6]: u'%e'
609 Out[6]: u'%e'
551
610
552 In [7]: pi**10
611 In [7]: pi**10
553 Out[7]: 9.364805e+04
612 Out[7]: 9.364805e+04
554
613
555 In [8]: %precision
614 In [8]: %precision
556 Out[8]: u'%r'
615 Out[8]: u'%r'
557
616
558 In [9]: pi**10
617 In [9]: pi**10
559 Out[9]: 93648.047476082982
618 Out[9]: 93648.047476082982
560 """
619 """
561 ptformatter = self.shell.display_formatter.formatters['text/plain']
620 ptformatter = self.shell.display_formatter.formatters['text/plain']
562 ptformatter.float_precision = s
621 ptformatter.float_precision = s
563 return ptformatter.float_format
622 return ptformatter.float_format
564
623
565 @magic_arguments.magic_arguments()
624 @magic_arguments.magic_arguments()
566 @magic_arguments.argument(
625 @magic_arguments.argument(
567 '-e', '--export', action='store_true', default=False,
626 '-e', '--export', action='store_true', default=False,
568 help=argparse.SUPPRESS
627 help=argparse.SUPPRESS
569 )
628 )
570 @magic_arguments.argument(
629 @magic_arguments.argument(
571 'filename', type=str,
630 'filename', type=str,
572 help='Notebook name or filename'
631 help='Notebook name or filename'
573 )
632 )
574 @line_magic
633 @line_magic
575 def notebook(self, s):
634 def notebook(self, s):
576 """Export and convert IPython notebooks.
635 """Export and convert IPython notebooks.
577
636
578 This function can export the current IPython history to a notebook file.
637 This function can export the current IPython history to a notebook file.
579 For example, to export the history to "foo.ipynb" do "%notebook foo.ipynb".
638 For example, to export the history to "foo.ipynb" do "%notebook foo.ipynb".
580
639
581 The -e or --export flag is deprecated in IPython 5.2, and will be
640 The -e or --export flag is deprecated in IPython 5.2, and will be
582 removed in the future.
641 removed in the future.
583 """
642 """
584 args = magic_arguments.parse_argstring(self.notebook, s)
643 args = magic_arguments.parse_argstring(self.notebook, s)
585
644
586 from nbformat import write, v4
645 from nbformat import write, v4
587
646
588 cells = []
647 cells = []
589 hist = list(self.shell.history_manager.get_range())
648 hist = list(self.shell.history_manager.get_range())
590 if(len(hist)<=1):
649 if(len(hist)<=1):
591 raise ValueError('History is empty, cannot export')
650 raise ValueError('History is empty, cannot export')
592 for session, execution_count, source in hist[:-1]:
651 for session, execution_count, source in hist[:-1]:
593 cells.append(v4.new_code_cell(
652 cells.append(v4.new_code_cell(
594 execution_count=execution_count,
653 execution_count=execution_count,
595 source=source
654 source=source
596 ))
655 ))
597 nb = v4.new_notebook(cells=cells)
656 nb = v4.new_notebook(cells=cells)
598 with io.open(args.filename, 'w', encoding='utf-8') as f:
657 with io.open(args.filename, 'w', encoding='utf-8') as f:
599 write(nb, f, version=4)
658 write(nb, f, version=4)
@@ -1,396 +1,417 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """
2 """
3 An embedded IPython shell.
3 An embedded IPython shell.
4 """
4 """
5 # Copyright (c) IPython Development Team.
5 # Copyright (c) IPython Development Team.
6 # Distributed under the terms of the Modified BSD License.
6 # Distributed under the terms of the Modified BSD License.
7
7
8
8
9 import sys
9 import sys
10 import warnings
10 import warnings
11
11
12 from IPython.core import ultratb, compilerop
12 from IPython.core import ultratb, compilerop
13 from IPython.core import magic_arguments
13 from IPython.core import magic_arguments
14 from IPython.core.magic import Magics, magics_class, line_magic
14 from IPython.core.magic import Magics, magics_class, line_magic
15 from IPython.core.interactiveshell import DummyMod, InteractiveShell
15 from IPython.core.interactiveshell import DummyMod, InteractiveShell
16 from IPython.terminal.interactiveshell import TerminalInteractiveShell
16 from IPython.terminal.interactiveshell import TerminalInteractiveShell
17 from IPython.terminal.ipapp import load_default_config
17 from IPython.terminal.ipapp import load_default_config
18
18
19 from traitlets import Bool, CBool, Unicode
19 from traitlets import Bool, CBool, Unicode
20 from IPython.utils.io import ask_yes_no
20 from IPython.utils.io import ask_yes_no
21
21
22 from contextlib import contextmanager
23
24 _sentinel = object()
25 @contextmanager
26 def new_context():
27 import trio._core._run as tcr
28 old_runner = getattr(tcr.GLOBAL_RUN_CONTEXT, 'runner', _sentinel)
29 old_task = getattr(tcr.GLOBAL_RUN_CONTEXT, 'task', None)
30 if old_runner is not _sentinel:
31 del tcr.GLOBAL_RUN_CONTEXT.runner
32 tcr.GLOBAL_RUN_CONTEXT.task = None
33 yield
34 if old_runner is not _sentinel:
35 tcr.GLOBAL_RUN_CONTEXT.runner = old_runner
36 tcr.GLOBAL_RUN_CONTEXT.task = old_task
37
38
22 class KillEmbedded(Exception):pass
39 class KillEmbedded(Exception):pass
23
40
24 # kept for backward compatibility as IPython 6 was released with
41 # kept for backward compatibility as IPython 6 was released with
25 # the typo. See https://github.com/ipython/ipython/pull/10706
42 # the typo. See https://github.com/ipython/ipython/pull/10706
26 KillEmbeded = KillEmbedded
43 KillEmbeded = KillEmbedded
27
44
28 # This is an additional magic that is exposed in embedded shells.
45 # This is an additional magic that is exposed in embedded shells.
29 @magics_class
46 @magics_class
30 class EmbeddedMagics(Magics):
47 class EmbeddedMagics(Magics):
31
48
32 @line_magic
49 @line_magic
33 @magic_arguments.magic_arguments()
50 @magic_arguments.magic_arguments()
34 @magic_arguments.argument('-i', '--instance', action='store_true',
51 @magic_arguments.argument('-i', '--instance', action='store_true',
35 help='Kill instance instead of call location')
52 help='Kill instance instead of call location')
36 @magic_arguments.argument('-x', '--exit', action='store_true',
53 @magic_arguments.argument('-x', '--exit', action='store_true',
37 help='Also exit the current session')
54 help='Also exit the current session')
38 @magic_arguments.argument('-y', '--yes', action='store_true',
55 @magic_arguments.argument('-y', '--yes', action='store_true',
39 help='Do not ask confirmation')
56 help='Do not ask confirmation')
40 def kill_embedded(self, parameter_s=''):
57 def kill_embedded(self, parameter_s=''):
41 """%kill_embedded : deactivate for good the current embedded IPython
58 """%kill_embedded : deactivate for good the current embedded IPython
42
59
43 This function (after asking for confirmation) sets an internal flag so
60 This function (after asking for confirmation) sets an internal flag so
44 that an embedded IPython will never activate again for the given call
61 that an embedded IPython will never activate again for the given call
45 location. This is useful to permanently disable a shell that is being
62 location. This is useful to permanently disable a shell that is being
46 called inside a loop: once you've figured out what you needed from it,
63 called inside a loop: once you've figured out what you needed from it,
47 you may then kill it and the program will then continue to run without
64 you may then kill it and the program will then continue to run without
48 the interactive shell interfering again.
65 the interactive shell interfering again.
49
66
50
67
51 Kill Instance Option:
68 Kill Instance Option:
52
69
53 If for some reasons you need to kill the location where the instance
70 If for some reasons you need to kill the location where the instance
54 is created and not called, for example if you create a single
71 is created and not called, for example if you create a single
55 instance in one place and debug in many locations, you can use the
72 instance in one place and debug in many locations, you can use the
56 ``--instance`` option to kill this specific instance. Like for the
73 ``--instance`` option to kill this specific instance. Like for the
57 ``call location`` killing an "instance" should work even if it is
74 ``call location`` killing an "instance" should work even if it is
58 recreated within a loop.
75 recreated within a loop.
59
76
60 .. note::
77 .. note::
61
78
62 This was the default behavior before IPython 5.2
79 This was the default behavior before IPython 5.2
63
80
64 """
81 """
65
82
66 args = magic_arguments.parse_argstring(self.kill_embedded, parameter_s)
83 args = magic_arguments.parse_argstring(self.kill_embedded, parameter_s)
67 print(args)
84 print(args)
68 if args.instance:
85 if args.instance:
69 # let no ask
86 # let no ask
70 if not args.yes:
87 if not args.yes:
71 kill = ask_yes_no(
88 kill = ask_yes_no(
72 "Are you sure you want to kill this embedded instance? [y/N] ", 'n')
89 "Are you sure you want to kill this embedded instance? [y/N] ", 'n')
73 else:
90 else:
74 kill = True
91 kill = True
75 if kill:
92 if kill:
76 self.shell._disable_init_location()
93 self.shell._disable_init_location()
77 print("This embedded IPython instance will not reactivate anymore "
94 print("This embedded IPython instance will not reactivate anymore "
78 "once you exit.")
95 "once you exit.")
79 else:
96 else:
80 if not args.yes:
97 if not args.yes:
81 kill = ask_yes_no(
98 kill = ask_yes_no(
82 "Are you sure you want to kill this embedded call_location? [y/N] ", 'n')
99 "Are you sure you want to kill this embedded call_location? [y/N] ", 'n')
83 else:
100 else:
84 kill = True
101 kill = True
85 if kill:
102 if kill:
86 self.shell.embedded_active = False
103 self.shell.embedded_active = False
87 print("This embedded IPython call location will not reactivate anymore "
104 print("This embedded IPython call location will not reactivate anymore "
88 "once you exit.")
105 "once you exit.")
89
106
90 if args.exit:
107 if args.exit:
91 # Ask-exit does not really ask, it just set internals flags to exit
108 # Ask-exit does not really ask, it just set internals flags to exit
92 # on next loop.
109 # on next loop.
93 self.shell.ask_exit()
110 self.shell.ask_exit()
94
111
95
112
96 @line_magic
113 @line_magic
97 def exit_raise(self, parameter_s=''):
114 def exit_raise(self, parameter_s=''):
98 """%exit_raise Make the current embedded kernel exit and raise and exception.
115 """%exit_raise Make the current embedded kernel exit and raise and exception.
99
116
100 This function sets an internal flag so that an embedded IPython will
117 This function sets an internal flag so that an embedded IPython will
101 raise a `IPython.terminal.embed.KillEmbedded` Exception on exit, and then exit the current I. This is
118 raise a `IPython.terminal.embed.KillEmbedded` Exception on exit, and then exit the current I. This is
102 useful to permanently exit a loop that create IPython embed instance.
119 useful to permanently exit a loop that create IPython embed instance.
103 """
120 """
104
121
105 self.shell.should_raise = True
122 self.shell.should_raise = True
106 self.shell.ask_exit()
123 self.shell.ask_exit()
107
124
108
125
109
126
110 class InteractiveShellEmbed(TerminalInteractiveShell):
127 class InteractiveShellEmbed(TerminalInteractiveShell):
111
128
112 dummy_mode = Bool(False)
129 dummy_mode = Bool(False)
113 exit_msg = Unicode('')
130 exit_msg = Unicode('')
114 embedded = CBool(True)
131 embedded = CBool(True)
115 should_raise = CBool(False)
132 should_raise = CBool(False)
116 # Like the base class display_banner is not configurable, but here it
133 # Like the base class display_banner is not configurable, but here it
117 # is True by default.
134 # is True by default.
118 display_banner = CBool(True)
135 display_banner = CBool(True)
119 exit_msg = Unicode()
136 exit_msg = Unicode()
120
137
121 # When embedding, by default we don't change the terminal title
138 # When embedding, by default we don't change the terminal title
122 term_title = Bool(False,
139 term_title = Bool(False,
123 help="Automatically set the terminal title"
140 help="Automatically set the terminal title"
124 ).tag(config=True)
141 ).tag(config=True)
125
142
126 _inactive_locations = set()
143 _inactive_locations = set()
127
144
128 @property
145 @property
129 def embedded_active(self):
146 def embedded_active(self):
130 return (self._call_location_id not in InteractiveShellEmbed._inactive_locations)\
147 return (self._call_location_id not in InteractiveShellEmbed._inactive_locations)\
131 and (self._init_location_id not in InteractiveShellEmbed._inactive_locations)
148 and (self._init_location_id not in InteractiveShellEmbed._inactive_locations)
132
149
133 def _disable_init_location(self):
150 def _disable_init_location(self):
134 """Disable the current Instance creation location"""
151 """Disable the current Instance creation location"""
135 InteractiveShellEmbed._inactive_locations.add(self._init_location_id)
152 InteractiveShellEmbed._inactive_locations.add(self._init_location_id)
136
153
137 @embedded_active.setter
154 @embedded_active.setter
138 def embedded_active(self, value):
155 def embedded_active(self, value):
139 if value:
156 if value:
140 InteractiveShellEmbed._inactive_locations.discard(
157 InteractiveShellEmbed._inactive_locations.discard(
141 self._call_location_id)
158 self._call_location_id)
142 InteractiveShellEmbed._inactive_locations.discard(
159 InteractiveShellEmbed._inactive_locations.discard(
143 self._init_location_id)
160 self._init_location_id)
144 else:
161 else:
145 InteractiveShellEmbed._inactive_locations.add(
162 InteractiveShellEmbed._inactive_locations.add(
146 self._call_location_id)
163 self._call_location_id)
147
164
148 def __init__(self, **kw):
165 def __init__(self, **kw):
149 if kw.get('user_global_ns', None) is not None:
166 if kw.get('user_global_ns', None) is not None:
150 raise DeprecationWarning(
167 raise DeprecationWarning(
151 "Key word argument `user_global_ns` has been replaced by `user_module` since IPython 4.0.")
168 "Key word argument `user_global_ns` has been replaced by `user_module` since IPython 4.0.")
152
169
153 clid = kw.pop('_init_location_id', None)
170 clid = kw.pop('_init_location_id', None)
154 if not clid:
171 if not clid:
155 frame = sys._getframe(1)
172 frame = sys._getframe(1)
156 clid = '%s:%s' % (frame.f_code.co_filename, frame.f_lineno)
173 clid = '%s:%s' % (frame.f_code.co_filename, frame.f_lineno)
157 self._init_location_id = clid
174 self._init_location_id = clid
158
175
159 super(InteractiveShellEmbed,self).__init__(**kw)
176 super(InteractiveShellEmbed,self).__init__(**kw)
160
177
161 # don't use the ipython crash handler so that user exceptions aren't
178 # don't use the ipython crash handler so that user exceptions aren't
162 # trapped
179 # trapped
163 sys.excepthook = ultratb.FormattedTB(color_scheme=self.colors,
180 sys.excepthook = ultratb.FormattedTB(color_scheme=self.colors,
164 mode=self.xmode,
181 mode=self.xmode,
165 call_pdb=self.pdb)
182 call_pdb=self.pdb)
166
183
167 def init_sys_modules(self):
184 def init_sys_modules(self):
168 """
185 """
169 Explicitly overwrite :mod:`IPython.core.interactiveshell` to do nothing.
186 Explicitly overwrite :mod:`IPython.core.interactiveshell` to do nothing.
170 """
187 """
171 pass
188 pass
172
189
173 def init_magics(self):
190 def init_magics(self):
174 super(InteractiveShellEmbed, self).init_magics()
191 super(InteractiveShellEmbed, self).init_magics()
175 self.register_magics(EmbeddedMagics)
192 self.register_magics(EmbeddedMagics)
176
193
177 def __call__(self, header='', local_ns=None, module=None, dummy=None,
194 def __call__(self, header='', local_ns=None, module=None, dummy=None,
178 stack_depth=1, global_ns=None, compile_flags=None, **kw):
195 stack_depth=1, global_ns=None, compile_flags=None, **kw):
179 """Activate the interactive interpreter.
196 """Activate the interactive interpreter.
180
197
181 __call__(self,header='',local_ns=None,module=None,dummy=None) -> Start
198 __call__(self,header='',local_ns=None,module=None,dummy=None) -> Start
182 the interpreter shell with the given local and global namespaces, and
199 the interpreter shell with the given local and global namespaces, and
183 optionally print a header string at startup.
200 optionally print a header string at startup.
184
201
185 The shell can be globally activated/deactivated using the
202 The shell can be globally activated/deactivated using the
186 dummy_mode attribute. This allows you to turn off a shell used
203 dummy_mode attribute. This allows you to turn off a shell used
187 for debugging globally.
204 for debugging globally.
188
205
189 However, *each* time you call the shell you can override the current
206 However, *each* time you call the shell you can override the current
190 state of dummy_mode with the optional keyword parameter 'dummy'. For
207 state of dummy_mode with the optional keyword parameter 'dummy'. For
191 example, if you set dummy mode on with IPShell.dummy_mode = True, you
208 example, if you set dummy mode on with IPShell.dummy_mode = True, you
192 can still have a specific call work by making it as IPShell(dummy=False).
209 can still have a specific call work by making it as IPShell(dummy=False).
193 """
210 """
194
211
195 # we are called, set the underlying interactiveshell not to exit.
212 # we are called, set the underlying interactiveshell not to exit.
196 self.keep_running = True
213 self.keep_running = True
197
214
198 # If the user has turned it off, go away
215 # If the user has turned it off, go away
199 clid = kw.pop('_call_location_id', None)
216 clid = kw.pop('_call_location_id', None)
200 if not clid:
217 if not clid:
201 frame = sys._getframe(1)
218 frame = sys._getframe(1)
202 clid = '%s:%s' % (frame.f_code.co_filename, frame.f_lineno)
219 clid = '%s:%s' % (frame.f_code.co_filename, frame.f_lineno)
203 self._call_location_id = clid
220 self._call_location_id = clid
204
221
205 if not self.embedded_active:
222 if not self.embedded_active:
206 return
223 return
207
224
208 # Normal exits from interactive mode set this flag, so the shell can't
225 # Normal exits from interactive mode set this flag, so the shell can't
209 # re-enter (it checks this variable at the start of interactive mode).
226 # re-enter (it checks this variable at the start of interactive mode).
210 self.exit_now = False
227 self.exit_now = False
211
228
212 # Allow the dummy parameter to override the global __dummy_mode
229 # Allow the dummy parameter to override the global __dummy_mode
213 if dummy or (dummy != 0 and self.dummy_mode):
230 if dummy or (dummy != 0 and self.dummy_mode):
214 return
231 return
215
232
216 # self.banner is auto computed
233 # self.banner is auto computed
217 if header:
234 if header:
218 self.old_banner2 = self.banner2
235 self.old_banner2 = self.banner2
219 self.banner2 = self.banner2 + '\n' + header + '\n'
236 self.banner2 = self.banner2 + '\n' + header + '\n'
220 else:
237 else:
221 self.old_banner2 = ''
238 self.old_banner2 = ''
222
239
223 if self.display_banner:
240 if self.display_banner:
224 self.show_banner()
241 self.show_banner()
225
242
226 # Call the embedding code with a stack depth of 1 so it can skip over
243 # Call the embedding code with a stack depth of 1 so it can skip over
227 # our call and get the original caller's namespaces.
244 # our call and get the original caller's namespaces.
228 self.mainloop(local_ns, module, stack_depth=stack_depth,
245 self.mainloop(local_ns, module, stack_depth=stack_depth,
229 global_ns=global_ns, compile_flags=compile_flags)
246 global_ns=global_ns, compile_flags=compile_flags)
230
247
231 self.banner2 = self.old_banner2
248 self.banner2 = self.old_banner2
232
249
233 if self.exit_msg is not None:
250 if self.exit_msg is not None:
234 print(self.exit_msg)
251 print(self.exit_msg)
235
252
236 if self.should_raise:
253 if self.should_raise:
237 raise KillEmbedded('Embedded IPython raising error, as user requested.')
254 raise KillEmbedded('Embedded IPython raising error, as user requested.')
238
255
239
256
240 def mainloop(self, local_ns=None, module=None, stack_depth=0,
257 def mainloop(self, local_ns=None, module=None, stack_depth=0,
241 display_banner=None, global_ns=None, compile_flags=None):
258 display_banner=None, global_ns=None, compile_flags=None):
242 """Embeds IPython into a running python program.
259 """Embeds IPython into a running python program.
243
260
244 Parameters
261 Parameters
245 ----------
262 ----------
246
263
247 local_ns, module
264 local_ns, module
248 Working local namespace (a dict) and module (a module or similar
265 Working local namespace (a dict) and module (a module or similar
249 object). If given as None, they are automatically taken from the scope
266 object). If given as None, they are automatically taken from the scope
250 where the shell was called, so that program variables become visible.
267 where the shell was called, so that program variables become visible.
251
268
252 stack_depth : int
269 stack_depth : int
253 How many levels in the stack to go to looking for namespaces (when
270 How many levels in the stack to go to looking for namespaces (when
254 local_ns or module is None). This allows an intermediate caller to
271 local_ns or module is None). This allows an intermediate caller to
255 make sure that this function gets the namespace from the intended
272 make sure that this function gets the namespace from the intended
256 level in the stack. By default (0) it will get its locals and globals
273 level in the stack. By default (0) it will get its locals and globals
257 from the immediate caller.
274 from the immediate caller.
258
275
259 compile_flags
276 compile_flags
260 A bit field identifying the __future__ features
277 A bit field identifying the __future__ features
261 that are enabled, as passed to the builtin :func:`compile` function.
278 that are enabled, as passed to the builtin :func:`compile` function.
262 If given as None, they are automatically taken from the scope where
279 If given as None, they are automatically taken from the scope where
263 the shell was called.
280 the shell was called.
264
281
265 """
282 """
266
283
267 if (global_ns is not None) and (module is None):
284 if (global_ns is not None) and (module is None):
268 raise DeprecationWarning("'global_ns' keyword argument is deprecated, and has been removed in IPython 5.0 use `module` keyword argument instead.")
285 raise DeprecationWarning("'global_ns' keyword argument is deprecated, and has been removed in IPython 5.0 use `module` keyword argument instead.")
269
286
270 if (display_banner is not None):
287 if (display_banner is not None):
271 warnings.warn("The display_banner parameter is deprecated since IPython 4.0", DeprecationWarning)
288 warnings.warn("The display_banner parameter is deprecated since IPython 4.0", DeprecationWarning)
272
289
273 # Get locals and globals from caller
290 # Get locals and globals from caller
274 if ((local_ns is None or module is None or compile_flags is None)
291 if ((local_ns is None or module is None or compile_flags is None)
275 and self.default_user_namespaces):
292 and self.default_user_namespaces):
276 call_frame = sys._getframe(stack_depth).f_back
293 call_frame = sys._getframe(stack_depth).f_back
277
294
278 if local_ns is None:
295 if local_ns is None:
279 local_ns = call_frame.f_locals
296 local_ns = call_frame.f_locals
280 if module is None:
297 if module is None:
281 global_ns = call_frame.f_globals
298 global_ns = call_frame.f_globals
282 try:
299 try:
283 module = sys.modules[global_ns['__name__']]
300 module = sys.modules[global_ns['__name__']]
284 except KeyError:
301 except KeyError:
285 warnings.warn("Failed to get module %s" % \
302 warnings.warn("Failed to get module %s" % \
286 global_ns.get('__name__', 'unknown module')
303 global_ns.get('__name__', 'unknown module')
287 )
304 )
288 module = DummyMod()
305 module = DummyMod()
289 module.__dict__ = global_ns
306 module.__dict__ = global_ns
290 if compile_flags is None:
307 if compile_flags is None:
291 compile_flags = (call_frame.f_code.co_flags &
308 compile_flags = (call_frame.f_code.co_flags &
292 compilerop.PyCF_MASK)
309 compilerop.PyCF_MASK)
293
310
294 # Save original namespace and module so we can restore them after
311 # Save original namespace and module so we can restore them after
295 # embedding; otherwise the shell doesn't shut down correctly.
312 # embedding; otherwise the shell doesn't shut down correctly.
296 orig_user_module = self.user_module
313 orig_user_module = self.user_module
297 orig_user_ns = self.user_ns
314 orig_user_ns = self.user_ns
298 orig_compile_flags = self.compile.flags
315 orig_compile_flags = self.compile.flags
299
316
300 # Update namespaces and fire up interpreter
317 # Update namespaces and fire up interpreter
301
318
302 # The global one is easy, we can just throw it in
319 # The global one is easy, we can just throw it in
303 if module is not None:
320 if module is not None:
304 self.user_module = module
321 self.user_module = module
305
322
306 # But the user/local one is tricky: ipython needs it to store internal
323 # But the user/local one is tricky: ipython needs it to store internal
307 # data, but we also need the locals. We'll throw our hidden variables
324 # data, but we also need the locals. We'll throw our hidden variables
308 # like _ih and get_ipython() into the local namespace, but delete them
325 # like _ih and get_ipython() into the local namespace, but delete them
309 # later.
326 # later.
310 if local_ns is not None:
327 if local_ns is not None:
311 reentrant_local_ns = {k: v for (k, v) in local_ns.items() if k not in self.user_ns_hidden.keys()}
328 reentrant_local_ns = {k: v for (k, v) in local_ns.items() if k not in self.user_ns_hidden.keys()}
312 self.user_ns = reentrant_local_ns
329 self.user_ns = reentrant_local_ns
313 self.init_user_ns()
330 self.init_user_ns()
314
331
315 # Compiler flags
332 # Compiler flags
316 if compile_flags is not None:
333 if compile_flags is not None:
317 self.compile.flags = compile_flags
334 self.compile.flags = compile_flags
318
335
319 # make sure the tab-completer has the correct frame information, so it
336 # make sure the tab-completer has the correct frame information, so it
320 # actually completes using the frame's locals/globals
337 # actually completes using the frame's locals/globals
321 self.set_completer_frame()
338 self.set_completer_frame()
322
339
323 with self.builtin_trap, self.display_trap:
340 with self.builtin_trap, self.display_trap:
324 self.interact()
341 self.interact()
325
342
326 # now, purge out the local namespace of IPython's hidden variables.
343 # now, purge out the local namespace of IPython's hidden variables.
327 if local_ns is not None:
344 if local_ns is not None:
328 local_ns.update({k: v for (k, v) in self.user_ns.items() if k not in self.user_ns_hidden.keys()})
345 local_ns.update({k: v for (k, v) in self.user_ns.items() if k not in self.user_ns_hidden.keys()})
329
346
330
347
331 # Restore original namespace so shell can shut down when we exit.
348 # Restore original namespace so shell can shut down when we exit.
332 self.user_module = orig_user_module
349 self.user_module = orig_user_module
333 self.user_ns = orig_user_ns
350 self.user_ns = orig_user_ns
334 self.compile.flags = orig_compile_flags
351 self.compile.flags = orig_compile_flags
335
352
336
353
337 def embed(**kwargs):
354 def embed(**kwargs):
338 """Call this to embed IPython at the current point in your program.
355 """Call this to embed IPython at the current point in your program.
339
356
340 The first invocation of this will create an :class:`InteractiveShellEmbed`
357 The first invocation of this will create an :class:`InteractiveShellEmbed`
341 instance and then call it. Consecutive calls just call the already
358 instance and then call it. Consecutive calls just call the already
342 created instance.
359 created instance.
343
360
344 If you don't want the kernel to initialize the namespace
361 If you don't want the kernel to initialize the namespace
345 from the scope of the surrounding function,
362 from the scope of the surrounding function,
346 and/or you want to load full IPython configuration,
363 and/or you want to load full IPython configuration,
347 you probably want `IPython.start_ipython()` instead.
364 you probably want `IPython.start_ipython()` instead.
348
365
349 Here is a simple example::
366 Here is a simple example::
350
367
351 from IPython import embed
368 from IPython import embed
352 a = 10
369 a = 10
353 b = 20
370 b = 20
354 embed(header='First time')
371 embed(header='First time')
355 c = 30
372 c = 30
356 d = 40
373 d = 40
357 embed()
374 embed()
358
375
359 Full customization can be done by passing a :class:`Config` in as the
376 Full customization can be done by passing a :class:`Config` in as the
360 config argument.
377 config argument.
361 """
378 """
362 config = kwargs.get('config')
379 config = kwargs.get('config')
363 header = kwargs.pop('header', u'')
380 header = kwargs.pop('header', u'')
364 compile_flags = kwargs.pop('compile_flags', None)
381 compile_flags = kwargs.pop('compile_flags', None)
365 if config is None:
382 if config is None:
366 config = load_default_config()
383 config = load_default_config()
367 config.InteractiveShellEmbed = config.TerminalInteractiveShell
384 config.InteractiveShellEmbed = config.TerminalInteractiveShell
368 kwargs['config'] = config
385 kwargs['config'] = config
386 using = kwargs.get('using', 'trio')
387 if using :
388 kwargs['config'].update({'TerminalInteractiveShell':{'loop_runner':using, 'colors':'NoColor'}})
369 #save ps1/ps2 if defined
389 #save ps1/ps2 if defined
370 ps1 = None
390 ps1 = None
371 ps2 = None
391 ps2 = None
372 try:
392 try:
373 ps1 = sys.ps1
393 ps1 = sys.ps1
374 ps2 = sys.ps2
394 ps2 = sys.ps2
375 except AttributeError:
395 except AttributeError:
376 pass
396 pass
377 #save previous instance
397 #save previous instance
378 saved_shell_instance = InteractiveShell._instance
398 saved_shell_instance = InteractiveShell._instance
379 if saved_shell_instance is not None:
399 if saved_shell_instance is not None:
380 cls = type(saved_shell_instance)
400 cls = type(saved_shell_instance)
381 cls.clear_instance()
401 cls.clear_instance()
382 frame = sys._getframe(1)
402 frame = sys._getframe(1)
383 shell = InteractiveShellEmbed.instance(_init_location_id='%s:%s' % (
403 with new_context():
384 frame.f_code.co_filename, frame.f_lineno), **kwargs)
404 shell = InteractiveShellEmbed.instance(_init_location_id='%s:%s' % (
385 shell(header=header, stack_depth=2, compile_flags=compile_flags,
405 frame.f_code.co_filename, frame.f_lineno), **kwargs)
386 _call_location_id='%s:%s' % (frame.f_code.co_filename, frame.f_lineno))
406 shell(header=header, stack_depth=2, compile_flags=compile_flags,
387 InteractiveShellEmbed.clear_instance()
407 _call_location_id='%s:%s' % (frame.f_code.co_filename, frame.f_lineno))
408 InteractiveShellEmbed.clear_instance()
388 #restore previous instance
409 #restore previous instance
389 if saved_shell_instance is not None:
410 if saved_shell_instance is not None:
390 cls = type(saved_shell_instance)
411 cls = type(saved_shell_instance)
391 cls.clear_instance()
412 cls.clear_instance()
392 for subclass in cls._walk_mro():
413 for subclass in cls._walk_mro():
393 subclass._instance = saved_shell_instance
414 subclass._instance = saved_shell_instance
394 if ps1 is not None:
415 if ps1 is not None:
395 sys.ps1 = ps1
416 sys.ps1 = ps1
396 sys.ps2 = ps2
417 sys.ps2 = ps2
@@ -1,132 +1,135 b''
1 """Test embedding of IPython"""
1 """Test embedding of IPython"""
2
2
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Copyright (C) 2013 The IPython Development Team
4 # Copyright (C) 2013 The IPython Development Team
5 #
5 #
6 # Distributed under the terms of the BSD License. The full license is in
6 # Distributed under the terms of the BSD License. The full license is in
7 # the file COPYING, distributed as part of this software.
7 # the file COPYING, distributed as part of this software.
8 #-----------------------------------------------------------------------------
8 #-----------------------------------------------------------------------------
9
9
10 #-----------------------------------------------------------------------------
10 #-----------------------------------------------------------------------------
11 # Imports
11 # Imports
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13
13
14 import os
14 import os
15 import subprocess
15 import subprocess
16 import sys
16 import sys
17 import nose.tools as nt
17 import nose.tools as nt
18 from IPython.utils.tempdir import NamedFileInTemporaryDirectory
18 from IPython.utils.tempdir import NamedFileInTemporaryDirectory
19 from IPython.testing.decorators import skip_win32
19 from IPython.testing.decorators import skip_win32
20
20
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22 # Tests
22 # Tests
23 #-----------------------------------------------------------------------------
23 #-----------------------------------------------------------------------------
24
24
25
25
26 _sample_embed = b"""
26 _sample_embed = b"""
27 import IPython
27 import IPython
28
28
29 a = 3
29 a = 3
30 b = 14
30 b = 14
31 print(a, '.', b)
31 print(a, '.', b)
32
32
33 IPython.embed()
33 IPython.embed()
34
34
35 print('bye!')
35 print('bye!')
36 """
36 """
37
37
38 _exit = b"exit\r"
38 _exit = b"exit\r"
39
39
40 def test_ipython_embed():
40 def test_ipython_embed():
41 """test that `IPython.embed()` works"""
41 """test that `IPython.embed()` works"""
42 with NamedFileInTemporaryDirectory('file_with_embed.py') as f:
42 with NamedFileInTemporaryDirectory('file_with_embed.py') as f:
43 f.write(_sample_embed)
43 f.write(_sample_embed)
44 f.flush()
44 f.flush()
45 f.close() # otherwise msft won't be able to read the file
45 f.close() # otherwise msft won't be able to read the file
46
46
47 # run `python file_with_embed.py`
47 # run `python file_with_embed.py`
48 cmd = [sys.executable, f.name]
48 cmd = [sys.executable, f.name]
49 env = os.environ.copy()
49 env = os.environ.copy()
50 env['IPY_TEST_SIMPLE_PROMPT'] = '1'
50 env['IPY_TEST_SIMPLE_PROMPT'] = '1'
51
51
52 p = subprocess.Popen(cmd, env=env, stdin=subprocess.PIPE,
52 p = subprocess.Popen(cmd, env=env, stdin=subprocess.PIPE,
53 stdout=subprocess.PIPE, stderr=subprocess.PIPE)
53 stdout=subprocess.PIPE, stderr=subprocess.PIPE)
54 out, err = p.communicate(_exit)
54 out, err = p.communicate(_exit)
55 std = out.decode('UTF-8')
55 std = out.decode('UTF-8')
56
56
57 nt.assert_equal(p.returncode, 0)
57 nt.assert_equal(p.returncode, 0)
58 nt.assert_in('3 . 14', std)
58 nt.assert_in('3 . 14', std)
59 if os.name != 'nt':
59 if os.name != 'nt':
60 # TODO: Fix up our different stdout references, see issue gh-14
60 # TODO: Fix up our different stdout references, see issue gh-14
61 nt.assert_in('IPython', std)
61 nt.assert_in('IPython', std)
62 nt.assert_in('bye!', std)
62 nt.assert_in('bye!', std)
63
63
64 @skip_win32
64 @skip_win32
65 def test_nest_embed():
65 def test_nest_embed():
66 """test that `IPython.embed()` is nestable"""
66 """test that `IPython.embed()` is nestable"""
67 import pexpect
67 import pexpect
68 ipy_prompt = r']:' #ansi color codes give problems matching beyond this
68 ipy_prompt = r']:' #ansi color codes give problems matching beyond this
69 env = os.environ.copy()
69 env = os.environ.copy()
70 env['IPY_TEST_SIMPLE_PROMPT'] = '1'
70 env['IPY_TEST_SIMPLE_PROMPT'] = '1'
71
71
72
72
73 child = pexpect.spawn(sys.executable, ['-m', 'IPython', '--colors=nocolor'],
73 child = pexpect.spawn(sys.executable, ['-m', 'IPython', '--colors=nocolor'],
74 env=env)
74 env=env)
75 child.timeout = 5
75 child.expect(ipy_prompt)
76 child.expect(ipy_prompt)
76 child.sendline("import IPython")
77 child.sendline("import IPython")
77 child.expect(ipy_prompt)
78 child.expect(ipy_prompt)
78 child.sendline("ip0 = get_ipython()")
79 child.sendline("ip0 = get_ipython()")
79 #enter first nested embed
80 #enter first nested embed
80 child.sendline("IPython.embed()")
81 child.sendline("IPython.embed()")
81 #skip the banner until we get to a prompt
82 #skip the banner until we get to a prompt
82 try:
83 try:
83 prompted = -1
84 prompted = -1
84 while prompted != 0:
85 while prompted != 0:
85 prompted = child.expect([ipy_prompt, '\r\n'])
86 prompted = child.expect([ipy_prompt, '\r\n'])
86 except pexpect.TIMEOUT as e:
87 except pexpect.TIMEOUT as e:
87 print(e)
88 print(e)
88 #child.interact()
89 #child.interact()
89 child.sendline("embed1 = get_ipython()"); child.expect(ipy_prompt)
90 child.sendline("embed1 = get_ipython()")
91 child.expect(ipy_prompt)
90 child.sendline("print('true' if embed1 is not ip0 else 'false')")
92 child.sendline("print('true' if embed1 is not ip0 else 'false')")
91 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
93 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
92 child.expect(ipy_prompt)
94 child.expect(ipy_prompt)
93 child.sendline("print('true' if IPython.get_ipython() is embed1 else 'false')")
95 child.sendline("print('true' if IPython.get_ipython() is embed1 else 'false')")
94 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
96 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
95 child.expect(ipy_prompt)
97 child.expect(ipy_prompt)
96 #enter second nested embed
98 #enter second nested embed
97 child.sendline("IPython.embed()")
99 child.sendline("IPython.embed()")
98 #skip the banner until we get to a prompt
100 #skip the banner until we get to a prompt
99 try:
101 try:
100 prompted = -1
102 prompted = -1
101 while prompted != 0:
103 while prompted != 0:
102 prompted = child.expect([ipy_prompt, '\r\n'])
104 prompted = child.expect([ipy_prompt, '\r\n'])
103 except pexpect.TIMEOUT as e:
105 except pexpect.TIMEOUT as e:
104 print(e)
106 print(e)
105 #child.interact()
107 #child.interact()
106 child.sendline("embed2 = get_ipython()"); child.expect(ipy_prompt)
108 child.sendline("embed2 = get_ipython()")
109 child.expect(ipy_prompt)
107 child.sendline("print('true' if embed2 is not embed1 else 'false')")
110 child.sendline("print('true' if embed2 is not embed1 else 'false')")
108 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
111 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
109 child.expect(ipy_prompt)
112 child.expect(ipy_prompt)
110 child.sendline("print('true' if embed2 is IPython.get_ipython() else 'false')")
113 child.sendline("print('true' if embed2 is IPython.get_ipython() else 'false')")
111 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
114 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
112 child.expect(ipy_prompt)
115 child.expect(ipy_prompt)
113 child.sendline('exit')
116 child.sendline('exit')
114 #back at first embed
117 #back at first embed
115 child.expect(ipy_prompt)
118 child.expect(ipy_prompt)
116 child.sendline("print('true' if get_ipython() is embed1 else 'false')")
119 child.sendline("print('true' if get_ipython() is embed1 else 'false')")
117 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
120 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
118 child.expect(ipy_prompt)
121 child.expect(ipy_prompt)
119 child.sendline("print('true' if IPython.get_ipython() is embed1 else 'false')")
122 child.sendline("print('true' if IPython.get_ipython() is embed1 else 'false')")
120 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
123 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
121 child.expect(ipy_prompt)
124 child.expect(ipy_prompt)
122 child.sendline('exit')
125 child.sendline('exit')
123 #back at launching scope
126 #back at launching scope
124 child.expect(ipy_prompt)
127 child.expect(ipy_prompt)
125 child.sendline("print('true' if get_ipython() is ip0 else 'false')")
128 child.sendline("print('true' if get_ipython() is ip0 else 'false')")
126 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
129 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
127 child.expect(ipy_prompt)
130 child.expect(ipy_prompt)
128 child.sendline("print('true' if IPython.get_ipython() is ip0 else 'false')")
131 child.sendline("print('true' if IPython.get_ipython() is ip0 else 'false')")
129 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
132 assert(child.expect(['true\r\n', 'false\r\n']) == 0)
130 child.expect(ipy_prompt)
133 child.expect(ipy_prompt)
131 child.sendline('exit')
134 child.sendline('exit')
132 child.close()
135 child.close()
@@ -1,298 +1,299 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 #
2 #
3 # IPython documentation build configuration file.
3 # IPython documentation build configuration file.
4
4
5 # NOTE: This file has been edited manually from the auto-generated one from
5 # NOTE: This file has been edited manually from the auto-generated one from
6 # sphinx. Do NOT delete and re-generate. If any changes from sphinx are
6 # sphinx. Do NOT delete and re-generate. If any changes from sphinx are
7 # needed, generate a scratch one and merge by hand any new fields needed.
7 # needed, generate a scratch one and merge by hand any new fields needed.
8
8
9 #
9 #
10 # This file is execfile()d with the current directory set to its containing dir.
10 # This file is execfile()d with the current directory set to its containing dir.
11 #
11 #
12 # The contents of this file are pickled, so don't put values in the namespace
12 # The contents of this file are pickled, so don't put values in the namespace
13 # that aren't pickleable (module imports are okay, they're removed automatically).
13 # that aren't pickleable (module imports are okay, they're removed automatically).
14 #
14 #
15 # All configuration values have a default value; values that are commented out
15 # All configuration values have a default value; values that are commented out
16 # serve to show the default value.
16 # serve to show the default value.
17
17
18 import sys, os
18 import sys, os
19
19
20 # http://read-the-docs.readthedocs.io/en/latest/faq.html
20 # http://read-the-docs.readthedocs.io/en/latest/faq.html
21 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
21 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
22
22
23 if ON_RTD:
23 if ON_RTD:
24 tags.add('rtd')
24 tags.add('rtd')
25
25
26 # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
26 # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
27 for name in ('config', 'api', 'magics', 'shortcuts'):
27 for name in ('config', 'api', 'magics', 'shortcuts'):
28 fname = 'autogen_{}.py'.format(name)
28 fname = 'autogen_{}.py'.format(name)
29 fpath = os.path.abspath(os.path.join('..', fname))
29 fpath = os.path.abspath(os.path.join('..', fname))
30 with open(fpath) as f:
30 with open(fpath) as f:
31 exec(compile(f.read(), fname, 'exec'), {
31 exec(compile(f.read(), fname, 'exec'), {
32 '__file__': fpath,
32 '__file__': fpath,
33 '__name__': '__main__',
33 '__name__': '__main__',
34 })
34 })
35 else:
35 else:
36 import sphinx_rtd_theme
36 import sphinx_rtd_theme
37 html_theme = "sphinx_rtd_theme"
37 html_theme = "sphinx_rtd_theme"
38 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
38 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
39
39
40 # If your extensions are in another directory, add it here. If the directory
40 # If your extensions are in another directory, add it here. If the directory
41 # is relative to the documentation root, use os.path.abspath to make it
41 # is relative to the documentation root, use os.path.abspath to make it
42 # absolute, like shown here.
42 # absolute, like shown here.
43 sys.path.insert(0, os.path.abspath('../sphinxext'))
43 sys.path.insert(0, os.path.abspath('../sphinxext'))
44
44
45 # We load the ipython release info into a dict by explicit execution
45 # We load the ipython release info into a dict by explicit execution
46 iprelease = {}
46 iprelease = {}
47 exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease)
47 exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease)
48
48
49 # General configuration
49 # General configuration
50 # ---------------------
50 # ---------------------
51
51
52 # Add any Sphinx extension module names here, as strings. They can be extensions
52 # Add any Sphinx extension module names here, as strings. They can be extensions
53 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
53 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
54 extensions = [
54 extensions = [
55 'sphinx.ext.autodoc',
55 'sphinx.ext.autodoc',
56 'sphinx.ext.autosummary',
56 'sphinx.ext.autosummary',
57 'sphinx.ext.doctest',
57 'sphinx.ext.doctest',
58 'sphinx.ext.inheritance_diagram',
58 'sphinx.ext.inheritance_diagram',
59 'sphinx.ext.intersphinx',
59 'sphinx.ext.intersphinx',
60 'sphinx.ext.graphviz',
60 'sphinx.ext.graphviz',
61 'IPython.sphinxext.ipython_console_highlighting',
61 'IPython.sphinxext.ipython_console_highlighting',
62 'IPython.sphinxext.ipython_directive',
62 'IPython.sphinxext.ipython_directive',
63 'sphinx.ext.napoleon', # to preprocess docstrings
63 'sphinx.ext.napoleon', # to preprocess docstrings
64 'github', # for easy GitHub links
64 'github', # for easy GitHub links
65 'magics',
65 'magics',
66 'configtraits',
66 'configtraits',
67 ]
67 ]
68
68
69 if ON_RTD:
69 if ON_RTD:
70 # Remove extensions not currently supported on RTD
70 # Remove extensions not currently supported on RTD
71 extensions.remove('IPython.sphinxext.ipython_directive')
71 extensions.remove('IPython.sphinxext.ipython_directive')
72 extensions.remove('IPython.sphinxext.ipython_console_highlighting')
72 extensions.remove('IPython.sphinxext.ipython_console_highlighting')
73
73
74 # Add any paths that contain templates here, relative to this directory.
74 # Add any paths that contain templates here, relative to this directory.
75 templates_path = ['_templates']
75 templates_path = ['_templates']
76
76
77 # The suffix of source filenames.
77 # The suffix of source filenames.
78 source_suffix = '.rst'
78 source_suffix = '.rst'
79
79
80 rst_prolog = ''
80 rst_prolog = ''
81
81
82 def is_stable(extra):
82 def is_stable(extra):
83 for ext in {'dev', 'b', 'rc'}:
83 for ext in {'dev', 'b', 'rc'}:
84 if ext in extra:
84 if ext in extra:
85 return False
85 return False
86 return True
86 return True
87
87
88 if is_stable(iprelease['_version_extra']):
88 if is_stable(iprelease['_version_extra']):
89 tags.add('ipystable')
89 tags.add('ipystable')
90 else:
90 else:
91 tags.add('ipydev')
91 tags.add('ipydev')
92 rst_prolog += """
92 rst_prolog += """
93 .. warning::
93 .. warning::
94
94
95 This documentation covers a development version of IPython. The development
95 This documentation covers a development version of IPython. The development
96 version may differ significantly from the latest stable release.
96 version may differ significantly from the latest stable release.
97 """
97 """
98
98
99 rst_prolog += """
99 rst_prolog += """
100 .. important::
100 .. important::
101
101
102 This documentation covers IPython versions 6.0 and higher. Beginning with
102 This documentation covers IPython versions 6.0 and higher. Beginning with
103 version 6.0, IPython stopped supporting compatibility with Python versions
103 version 6.0, IPython stopped supporting compatibility with Python versions
104 lower than 3.3 including all versions of Python 2.7.
104 lower than 3.3 including all versions of Python 2.7.
105
105
106 If you are looking for an IPython version compatible with Python 2.7,
106 If you are looking for an IPython version compatible with Python 2.7,
107 please use the IPython 5.x LTS release and refer to its documentation (LTS
107 please use the IPython 5.x LTS release and refer to its documentation (LTS
108 is the long term support release).
108 is the long term support release).
109
109
110 """
110 """
111
111
112 # The master toctree document.
112 # The master toctree document.
113 master_doc = 'index'
113 master_doc = 'index'
114
114
115 # General substitutions.
115 # General substitutions.
116 project = 'IPython'
116 project = 'IPython'
117 copyright = 'The IPython Development Team'
117 copyright = 'The IPython Development Team'
118
118
119 # ghissue config
119 # ghissue config
120 github_project_url = "https://github.com/ipython/ipython"
120 github_project_url = "https://github.com/ipython/ipython"
121
121
122 # numpydoc config
122 # numpydoc config
123 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
123 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
124 numpydoc_class_members_toctree = False
124 numpydoc_class_members_toctree = False
125
125
126 # The default replacements for |version| and |release|, also used in various
126 # The default replacements for |version| and |release|, also used in various
127 # other places throughout the built documents.
127 # other places throughout the built documents.
128 #
128 #
129 # The full version, including alpha/beta/rc tags.
129 # The full version, including alpha/beta/rc tags.
130 release = "%s" % iprelease['version']
130 release = "%s" % iprelease['version']
131 # Just the X.Y.Z part, no '-dev'
131 # Just the X.Y.Z part, no '-dev'
132 version = iprelease['version'].split('-', 1)[0]
132 version = iprelease['version'].split('-', 1)[0]
133
133
134
134
135 # There are two options for replacing |today|: either, you set today to some
135 # There are two options for replacing |today|: either, you set today to some
136 # non-false value, then it is used:
136 # non-false value, then it is used:
137 #today = ''
137 #today = ''
138 # Else, today_fmt is used as the format for a strftime call.
138 # Else, today_fmt is used as the format for a strftime call.
139 today_fmt = '%B %d, %Y'
139 today_fmt = '%B %d, %Y'
140
140
141 # List of documents that shouldn't be included in the build.
141 # List of documents that shouldn't be included in the build.
142 #unused_docs = []
142 #unused_docs = []
143
143
144 # Exclude these glob-style patterns when looking for source files. They are
144 # Exclude these glob-style patterns when looking for source files. They are
145 # relative to the source/ directory.
145 # relative to the source/ directory.
146 exclude_patterns = ['whatsnew/pr']
146 exclude_patterns = ['whatsnew/pr/antigravity-feature.*',
147 'whatsnew/pr/incompat-switching-to-perl.*']
147
148
148
149
149 # If true, '()' will be appended to :func: etc. cross-reference text.
150 # If true, '()' will be appended to :func: etc. cross-reference text.
150 #add_function_parentheses = True
151 #add_function_parentheses = True
151
152
152 # If true, the current module name will be prepended to all description
153 # If true, the current module name will be prepended to all description
153 # unit titles (such as .. function::).
154 # unit titles (such as .. function::).
154 #add_module_names = True
155 #add_module_names = True
155
156
156 # If true, sectionauthor and moduleauthor directives will be shown in the
157 # If true, sectionauthor and moduleauthor directives will be shown in the
157 # output. They are ignored by default.
158 # output. They are ignored by default.
158 #show_authors = False
159 #show_authors = False
159
160
160 # The name of the Pygments (syntax highlighting) style to use.
161 # The name of the Pygments (syntax highlighting) style to use.
161 pygments_style = 'sphinx'
162 pygments_style = 'sphinx'
162
163
163 # Set the default role so we can use `foo` instead of ``foo``
164 # Set the default role so we can use `foo` instead of ``foo``
164 default_role = 'literal'
165 default_role = 'literal'
165
166
166 # Options for HTML output
167 # Options for HTML output
167 # -----------------------
168 # -----------------------
168
169
169 # The style sheet to use for HTML and HTML Help pages. A file of that name
170 # The style sheet to use for HTML and HTML Help pages. A file of that name
170 # must exist either in Sphinx' static/ path, or in one of the custom paths
171 # must exist either in Sphinx' static/ path, or in one of the custom paths
171 # given in html_static_path.
172 # given in html_static_path.
172 # html_style = 'default.css'
173 # html_style = 'default.css'
173
174
174
175
175 # The name for this set of Sphinx documents. If None, it defaults to
176 # The name for this set of Sphinx documents. If None, it defaults to
176 # "<project> v<release> documentation".
177 # "<project> v<release> documentation".
177 #html_title = None
178 #html_title = None
178
179
179 # The name of an image file (within the static path) to place at the top of
180 # The name of an image file (within the static path) to place at the top of
180 # the sidebar.
181 # the sidebar.
181 #html_logo = None
182 #html_logo = None
182
183
183 # Add any paths that contain custom static files (such as style sheets) here,
184 # Add any paths that contain custom static files (such as style sheets) here,
184 # relative to this directory. They are copied after the builtin static files,
185 # relative to this directory. They are copied after the builtin static files,
185 # so a file named "default.css" will overwrite the builtin "default.css".
186 # so a file named "default.css" will overwrite the builtin "default.css".
186 html_static_path = ['_static']
187 html_static_path = ['_static']
187
188
188 # Favicon needs the directory name
189 # Favicon needs the directory name
189 html_favicon = '_static/favicon.ico'
190 html_favicon = '_static/favicon.ico'
190 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
191 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
191 # using the given strftime format.
192 # using the given strftime format.
192 html_last_updated_fmt = '%b %d, %Y'
193 html_last_updated_fmt = '%b %d, %Y'
193
194
194 # If true, SmartyPants will be used to convert quotes and dashes to
195 # If true, SmartyPants will be used to convert quotes and dashes to
195 # typographically correct entities.
196 # typographically correct entities.
196 #html_use_smartypants = True
197 #html_use_smartypants = True
197
198
198 # Custom sidebar templates, maps document names to template names.
199 # Custom sidebar templates, maps document names to template names.
199 #html_sidebars = {}
200 #html_sidebars = {}
200
201
201 # Additional templates that should be rendered to pages, maps page names to
202 # Additional templates that should be rendered to pages, maps page names to
202 # template names.
203 # template names.
203 html_additional_pages = {
204 html_additional_pages = {
204 'interactive/htmlnotebook': 'notebook_redirect.html',
205 'interactive/htmlnotebook': 'notebook_redirect.html',
205 'interactive/notebook': 'notebook_redirect.html',
206 'interactive/notebook': 'notebook_redirect.html',
206 'interactive/nbconvert': 'notebook_redirect.html',
207 'interactive/nbconvert': 'notebook_redirect.html',
207 'interactive/public_server': 'notebook_redirect.html',
208 'interactive/public_server': 'notebook_redirect.html',
208 }
209 }
209
210
210 # If false, no module index is generated.
211 # If false, no module index is generated.
211 #html_use_modindex = True
212 #html_use_modindex = True
212
213
213 # If true, the reST sources are included in the HTML build as _sources/<name>.
214 # If true, the reST sources are included in the HTML build as _sources/<name>.
214 #html_copy_source = True
215 #html_copy_source = True
215
216
216 # If true, an OpenSearch description file will be output, and all pages will
217 # If true, an OpenSearch description file will be output, and all pages will
217 # contain a <link> tag referring to it. The value of this option must be the
218 # contain a <link> tag referring to it. The value of this option must be the
218 # base URL from which the finished HTML is served.
219 # base URL from which the finished HTML is served.
219 #html_use_opensearch = ''
220 #html_use_opensearch = ''
220
221
221 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
222 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
222 #html_file_suffix = ''
223 #html_file_suffix = ''
223
224
224 # Output file base name for HTML help builder.
225 # Output file base name for HTML help builder.
225 htmlhelp_basename = 'ipythondoc'
226 htmlhelp_basename = 'ipythondoc'
226
227
227 intersphinx_mapping = {'python': ('https://docs.python.org/3/', None),
228 intersphinx_mapping = {'python': ('https://docs.python.org/3/', None),
228 'rpy2': ('https://rpy2.readthedocs.io/en/version_2.8.x/', None),
229 'rpy2': ('https://rpy2.readthedocs.io/en/version_2.8.x/', None),
229 'traitlets': ('https://traitlets.readthedocs.io/en/latest/', None),
230 'traitlets': ('https://traitlets.readthedocs.io/en/latest/', None),
230 'jupyterclient': ('https://jupyter-client.readthedocs.io/en/latest/', None),
231 'jupyterclient': ('https://jupyter-client.readthedocs.io/en/latest/', None),
231 'ipyparallel': ('https://ipyparallel.readthedocs.io/en/latest/', None),
232 'ipyparallel': ('https://ipyparallel.readthedocs.io/en/latest/', None),
232 'jupyter': ('https://jupyter.readthedocs.io/en/latest/', None),
233 'jupyter': ('https://jupyter.readthedocs.io/en/latest/', None),
233 'jedi': ('https://jedi.readthedocs.io/en/latest/', None),
234 'jedi': ('https://jedi.readthedocs.io/en/latest/', None),
234 'traitlets': ('https://traitlets.readthedocs.io/en/latest/', None),
235 'traitlets': ('https://traitlets.readthedocs.io/en/latest/', None),
235 'ipykernel': ('https://ipykernel.readthedocs.io/en/latest/', None),
236 'ipykernel': ('https://ipykernel.readthedocs.io/en/latest/', None),
236 'prompt_toolkit' : ('https://python-prompt-toolkit.readthedocs.io/en/stable/', None),
237 'prompt_toolkit' : ('https://python-prompt-toolkit.readthedocs.io/en/stable/', None),
237 'ipywidgets': ('https://ipywidgets.readthedocs.io/en/stable/', None),
238 'ipywidgets': ('https://ipywidgets.readthedocs.io/en/stable/', None),
238 'ipyparallel': ('https://ipyparallel.readthedocs.io/en/stable/', None)
239 'ipyparallel': ('https://ipyparallel.readthedocs.io/en/stable/', None)
239 }
240 }
240
241
241 # Options for LaTeX output
242 # Options for LaTeX output
242 # ------------------------
243 # ------------------------
243
244
244 # The paper size ('letter' or 'a4').
245 # The paper size ('letter' or 'a4').
245 latex_paper_size = 'letter'
246 latex_paper_size = 'letter'
246
247
247 # The font size ('10pt', '11pt' or '12pt').
248 # The font size ('10pt', '11pt' or '12pt').
248 latex_font_size = '11pt'
249 latex_font_size = '11pt'
249
250
250 # Grouping the document tree into LaTeX files. List of tuples
251 # Grouping the document tree into LaTeX files. List of tuples
251 # (source start file, target name, title, author, document class [howto/manual]).
252 # (source start file, target name, title, author, document class [howto/manual]).
252
253
253 latex_documents = [
254 latex_documents = [
254 ('index', 'ipython.tex', 'IPython Documentation',
255 ('index', 'ipython.tex', 'IPython Documentation',
255 u"""The IPython Development Team""", 'manual', True),
256 u"""The IPython Development Team""", 'manual', True),
256 ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
257 ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
257 'Using IPython on Windows HPC Server 2008',
258 'Using IPython on Windows HPC Server 2008',
258 u"Brian E. Granger", 'manual', True)
259 u"Brian E. Granger", 'manual', True)
259 ]
260 ]
260
261
261 # The name of an image file (relative to this directory) to place at the top of
262 # The name of an image file (relative to this directory) to place at the top of
262 # the title page.
263 # the title page.
263 #latex_logo = None
264 #latex_logo = None
264
265
265 # For "manual" documents, if this is true, then toplevel headings are parts,
266 # For "manual" documents, if this is true, then toplevel headings are parts,
266 # not chapters.
267 # not chapters.
267 #latex_use_parts = False
268 #latex_use_parts = False
268
269
269 # Additional stuff for the LaTeX preamble.
270 # Additional stuff for the LaTeX preamble.
270 #latex_preamble = ''
271 #latex_preamble = ''
271
272
272 # Documents to append as an appendix to all manuals.
273 # Documents to append as an appendix to all manuals.
273 #latex_appendices = []
274 #latex_appendices = []
274
275
275 # If false, no module index is generated.
276 # If false, no module index is generated.
276 latex_use_modindex = True
277 latex_use_modindex = True
277
278
278
279
279 # Options for texinfo output
280 # Options for texinfo output
280 # --------------------------
281 # --------------------------
281
282
282 texinfo_documents = [
283 texinfo_documents = [
283 (master_doc, 'ipython', 'IPython Documentation',
284 (master_doc, 'ipython', 'IPython Documentation',
284 'The IPython Development Team',
285 'The IPython Development Team',
285 'IPython',
286 'IPython',
286 'IPython Documentation',
287 'IPython Documentation',
287 'Programming',
288 'Programming',
288 1),
289 1),
289 ]
290 ]
290
291
291 modindex_common_prefix = ['IPython.']
292 modindex_common_prefix = ['IPython.']
292
293
293
294
294 # Cleanup
295 # Cleanup
295 # -------
296 # -------
296 # delete release info to avoid pickling errors from sphinx
297 # delete release info to avoid pickling errors from sphinx
297
298
298 del iprelease
299 del iprelease
@@ -1,31 +1,32 b''
1 ========
1 ========
2 Tutorial
2 Tutorial
3 ========
3 ========
4
4
5 This section of IPython documentation will walk you through most of the IPython
5 This section of IPython documentation will walk you through most of the IPython
6 functionality. You do not need to have any deep knowledge of Python to read this
6 functionality. You do not need to have any deep knowledge of Python to read this
7 tutorial, though some sections might make slightly more sense if you have already
7 tutorial, though some sections might make slightly more sense if you have already
8 done some work in the classic Python REPL.
8 done some work in the classic Python REPL.
9
9
10 .. note::
10 .. note::
11
11
12 Some part of this documentation are more than a decade old so might be out
12 Some part of this documentation are more than a decade old so might be out
13 of date, we welcome any report of inaccuracy, and Pull Requests that make
13 of date, we welcome any report of inaccuracy, and Pull Requests that make
14 that up to date.
14 that up to date.
15
15
16 .. toctree::
16 .. toctree::
17 :maxdepth: 2
17 :maxdepth: 2
18 :hidden:
18 :hidden:
19
19
20 tutorial
20 tutorial
21 plotting
21 plotting
22 reference
22 reference
23 shell
23 shell
24 autoawait
24 tips
25 tips
25 python-ipython-diff
26 python-ipython-diff
26 magics
27 magics
27
28
28 .. seealso::
29 .. seealso::
29
30
30 `A Qt Console for Jupyter <https://jupyter.org/qtconsole/>`__
31 `A Qt Console for Jupyter <https://jupyter.org/qtconsole/>`__
31 `The Jupyter Notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`__
32 `The Jupyter Notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`__
@@ -1,21 +1,150 b''
1 =====================
1 =====================
2 Development version
2 Development version
3 =====================
3 =====================
4
4
5 This document describes in-flight development work.
5 This document describes in-flight development work.
6
6
7 .. warning::
7 .. warning::
8
8
9 Please do not edit this file by hand (doing so will likely cause merge
9 Please do not edit this file by hand (doing so will likely cause merge
10 conflicts for other Pull Requests). Instead, create a new file in the
10 conflicts for other Pull Requests). Instead, create a new file in the
11 `docs/source/whatsnew/pr` folder
11 `docs/source/whatsnew/pr` folder
12
12
13
13
14 Released .... ...., 2017
15
16
17 Need to be updated:
18
19 .. toctree::
20 :maxdepth: 2
21 :glob:
22
23 pr/*
24
25 IPython 6 feature a major improvement in the completion machinery which is now
26 capable of completing non-executed code. It is also the first version of IPython
27 to stop compatibility with Python 2, which is still supported on the bugfix only
28 5.x branch. Read below to have a non-exhaustive list of new features.
29
30 Make sure you have pip > 9.0 before upgrading.
31 You should be able to update by using:
32
33 .. code::
34
35 pip install ipython --upgrade
36
37 New completion API and Interface
38 --------------------------------
39
40 The completer Completion API has seen an overhaul, and the new completer have
41 plenty of improvement both from the end users of terminal IPython or for
42 consumers of the API.
43
44 This new API is capable of pulling completions from :any:`jedi`, thus allowing
45 type inference on non-executed code. If :any:`jedi` is installed completion like
46 the following are now becoming possible without code evaluation:
47
48 >>> data = ['Number of users', 123_456]
49 ... data[0].<tab>
50
51 That is to say, IPython is now capable of inferring that `data[0]` is a string,
52 and will suggest completions like `.capitalize`. The completion power of IPython
53 will increase with new Jedi releases, and a number of bugs and more completions
54 are already available on development version of :any:`jedi` if you are curious.
55
56 With the help of prompt toolkit, types of completions can be shown in the
57 completer interface:
58
59 .. image:: ../_images/jedi_type_inference_60.png
60 :alt: Jedi showing ability to do type inference
61 :align: center
62 :width: 400px
63 :target: ../_images/jedi_type_inference_60.png
64
65 The appearance of the completer is controlled by the
66 ``c.TerminalInteractiveShell.display_completions`` option that will show the
67 type differently depending on the value among ``'column'``, ``'multicolumn'``
68 and ``'readlinelike'``
69
70 The use of Jedi also full fill a number of request and fix a number of bugs
71 like case insensitive completion, completion after division operator: See
72 :ghpull:`10182`.
73
74 Extra patches and updates will be needed to the :mod:`ipykernel` package for
75 this feature to be available to other clients like jupyter Notebook, Lab,
76 Nteract, Hydrogen...
77
78 The use of Jedi can is barely noticeable on recent enough machines, but can be
79 feel on older ones, in cases were Jedi behavior need to be adjusted, the amount
80 of time given to Jedi to compute type inference can be adjusted with
81 ``c.IPCompleter.jedi_compute_type_timeout``, with object whose type were not
82 inferred will be shown as ``<unknown>``. Jedi can also be completely deactivated
83 by using the ``c.Completer.use_jedi=False`` option.
84
85
86 The old ``Completer.complete()`` API is waiting deprecation and should be
87 replaced replaced by ``Completer.completions()`` in a near future. Feedback on
88 the current state of the API and suggestions welcome.
89
90 Python 3 only codebase
91 ----------------------
92
93 One of the large challenges in IPython 6.0 has been the adoption of a pure
94 Python 3 code base, which lead us to great length to upstream patches in pip,
95 pypi and warehouse to make sure Python 2 system still upgrade to the latest
96 compatible Python version compatible.
97
98 We remind our Python 2 users that IPython 5 is still compatible with Python 2.7,
99 still maintained and get regular releases. Using pip 9+, upgrading IPython will
100 automatically upgrade to the latest version compatible with your system.
101
102 .. warning::
103
104 If you are on a system using an older verison of pip on Python 2, pip may
105 still install IPython 6.0 on your system, and IPython will refuse to start.
106 You can fix this by ugrading pip, and reinstalling ipython, or forcing pip to
107 install an earlier version: ``pip install 'ipython<6'``
108
109 The ability to use only Python 3 on the code base of IPython has bring a number
110 of advantage. Most of the newly written code make use of `optional function type
111 anotation <https://www.python.org/dev/peps/pep-0484/>`_ leading to clearer code
112 and better documentation.
113
114 The total size of the repository has also for a first time between releases
115 (excluding the big split for 4.0) decreased by about 1500 lines, potentially
116 quite a bit more codewide as some documents like this one are append only and
117 are about 300 lines long.
118
119 The removal as of Python2/Python3 shim layer has made the code quite clearer and
120 more idiomatic in a number of location, and much friendlier to work with and
121 understand. We hope to further embrace Python 3 capability in the next release
122 cycle and introduce more of the Python 3 only idioms (yield from, kwarg only,
123 general unpacking) in the code base of IPython, and see if we can take advantage
124 of these as well to improve user experience with better error messages and
125 hints.
126
127
128 Miscs improvements
129 ------------------
130
131
132 - The :cellmagic:`capture` magic can now capture the result of a cell (from an
133 expression on the last line), as well as printed and displayed output.
134 :ghpull:`9851`.
135
136 - Pressing Ctrl-Z in the terminal debugger now suspends IPython, as it already
137 does in the main terminal prompt.
138
139 - autoreload can now reload ``Enum``. See :ghissue:`10232` and :ghpull:`10316`
140
141 - IPython.display has gained a :any:`GeoJSON <IPython.display.GeoJSON>` object.
142 :ghpull:`10288` and :ghpull:`10253`
14
143
15 .. DO NOT EDIT THIS LINE BEFORE RELEASE. FEATURE INSERTION POINT.
144 .. DO NOT EDIT THIS LINE BEFORE RELEASE. FEATURE INSERTION POINT.
16
145
17
146
18 Backwards incompatible changes
147 Backwards incompatible changes
19 ------------------------------
148 ------------------------------
20
149
21 .. DO NOT EDIT THIS LINE BEFORE RELEASE. INCOMPAT INSERTION POINT.
150 .. DO NOT EDIT THIS LINE BEFORE RELEASE. INCOMPAT INSERTION POINT.
@@ -1,264 +1,265 b''
1 #!/usr/bin/env python3
1 #!/usr/bin/env python3
2 # -*- coding: utf-8 -*-
2 # -*- coding: utf-8 -*-
3 """Setup script for IPython.
3 """Setup script for IPython.
4
4
5 Under Posix environments it works like a typical setup.py script.
5 Under Posix environments it works like a typical setup.py script.
6 Under Windows, the command sdist is not supported, since IPython
6 Under Windows, the command sdist is not supported, since IPython
7 requires utilities which are not available under Windows."""
7 requires utilities which are not available under Windows."""
8
8
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10 # Copyright (c) 2008-2011, IPython Development Team.
10 # Copyright (c) 2008-2011, IPython Development Team.
11 # Copyright (c) 2001-2007, Fernando Perez <fernando.perez@colorado.edu>
11 # Copyright (c) 2001-2007, Fernando Perez <fernando.perez@colorado.edu>
12 # Copyright (c) 2001, Janko Hauser <jhauser@zscout.de>
12 # Copyright (c) 2001, Janko Hauser <jhauser@zscout.de>
13 # Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>
13 # Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>
14 #
14 #
15 # Distributed under the terms of the Modified BSD License.
15 # Distributed under the terms of the Modified BSD License.
16 #
16 #
17 # The full license is in the file COPYING.rst, distributed with this software.
17 # The full license is in the file COPYING.rst, distributed with this software.
18 #-----------------------------------------------------------------------------
18 #-----------------------------------------------------------------------------
19
19
20 from __future__ import print_function
20 from __future__ import print_function
21
21
22 import os
22 import os
23 import sys
23 import sys
24
24
25 # **Python version check**
25 # **Python version check**
26 #
26 #
27 # This check is also made in IPython/__init__, don't forget to update both when
27 # This check is also made in IPython/__init__, don't forget to update both when
28 # changing Python version requirements.
28 # changing Python version requirements.
29 if sys.version_info < (3, 4):
29 if sys.version_info < (3, 4):
30 pip_message = 'This may be due to an out of date pip. Make sure you have pip >= 9.0.1.'
30 pip_message = 'This may be due to an out of date pip. Make sure you have pip >= 9.0.1.'
31 try:
31 try:
32 import pip
32 import pip
33 pip_version = tuple([int(x) for x in pip.__version__.split('.')[:3]])
33 pip_version = tuple([int(x) for x in pip.__version__.split('.')[:3]])
34 if pip_version < (9, 0, 1) :
34 if pip_version < (9, 0, 1) :
35 pip_message = 'Your pip version is out of date, please install pip >= 9.0.1. '\
35 pip_message = 'Your pip version is out of date, please install pip >= 9.0.1. '\
36 'pip {} detected.'.format(pip.__version__)
36 'pip {} detected.'.format(pip.__version__)
37 else:
37 else:
38 # pip is new enough - it must be something else
38 # pip is new enough - it must be something else
39 pip_message = ''
39 pip_message = ''
40 except Exception:
40 except Exception:
41 pass
41 pass
42
42
43
43
44 error = """
44 error = """
45 IPython 7.0+ supports Python 3.4 and above.
45 IPython 7.0+ supports Python 3.4 and above.
46 When using Python 2.7, please install IPython 5.x LTS Long Term Support version.
46 When using Python 2.7, please install IPython 5.x LTS Long Term Support version.
47 Python 3.3 was supported up to IPython 6.x.
47 Python 3.3 was supported up to IPython 6.x.
48
48
49 See IPython `README.rst` file for more information:
49 See IPython `README.rst` file for more information:
50
50
51 https://github.com/ipython/ipython/blob/master/README.rst
51 https://github.com/ipython/ipython/blob/master/README.rst
52
52
53 Python {py} detected.
53 Python {py} detected.
54 {pip}
54 {pip}
55 """.format(py=sys.version_info, pip=pip_message )
55 """.format(py=sys.version_info, pip=pip_message )
56
56
57 print(error, file=sys.stderr)
57 print(error, file=sys.stderr)
58 sys.exit(1)
58 sys.exit(1)
59
59
60 # At least we're on the python version we need, move on.
60 # At least we're on the python version we need, move on.
61
61
62 # BEFORE importing distutils, remove MANIFEST. distutils doesn't properly
62 # BEFORE importing distutils, remove MANIFEST. distutils doesn't properly
63 # update it when the contents of directories change.
63 # update it when the contents of directories change.
64 if os.path.exists('MANIFEST'): os.remove('MANIFEST')
64 if os.path.exists('MANIFEST'): os.remove('MANIFEST')
65
65
66 from distutils.core import setup
66 from distutils.core import setup
67
67
68 # Our own imports
68 # Our own imports
69 from setupbase import target_update
69 from setupbase import target_update
70
70
71 from setupbase import (
71 from setupbase import (
72 setup_args,
72 setup_args,
73 find_packages,
73 find_packages,
74 find_package_data,
74 find_package_data,
75 check_package_data_first,
75 check_package_data_first,
76 find_entry_points,
76 find_entry_points,
77 build_scripts_entrypt,
77 build_scripts_entrypt,
78 find_data_files,
78 find_data_files,
79 git_prebuild,
79 git_prebuild,
80 install_symlinked,
80 install_symlinked,
81 install_lib_symlink,
81 install_lib_symlink,
82 install_scripts_for_symlink,
82 install_scripts_for_symlink,
83 unsymlink,
83 unsymlink,
84 )
84 )
85
85
86 isfile = os.path.isfile
86 isfile = os.path.isfile
87 pjoin = os.path.join
87 pjoin = os.path.join
88
88
89 #-------------------------------------------------------------------------------
89 #-------------------------------------------------------------------------------
90 # Handle OS specific things
90 # Handle OS specific things
91 #-------------------------------------------------------------------------------
91 #-------------------------------------------------------------------------------
92
92
93 if os.name in ('nt','dos'):
93 if os.name in ('nt','dos'):
94 os_name = 'windows'
94 os_name = 'windows'
95 else:
95 else:
96 os_name = os.name
96 os_name = os.name
97
97
98 # Under Windows, 'sdist' has not been supported. Now that the docs build with
98 # Under Windows, 'sdist' has not been supported. Now that the docs build with
99 # Sphinx it might work, but let's not turn it on until someone confirms that it
99 # Sphinx it might work, but let's not turn it on until someone confirms that it
100 # actually works.
100 # actually works.
101 if os_name == 'windows' and 'sdist' in sys.argv:
101 if os_name == 'windows' and 'sdist' in sys.argv:
102 print('The sdist command is not available under Windows. Exiting.')
102 print('The sdist command is not available under Windows. Exiting.')
103 sys.exit(1)
103 sys.exit(1)
104
104
105
105
106 #-------------------------------------------------------------------------------
106 #-------------------------------------------------------------------------------
107 # Things related to the IPython documentation
107 # Things related to the IPython documentation
108 #-------------------------------------------------------------------------------
108 #-------------------------------------------------------------------------------
109
109
110 # update the manuals when building a source dist
110 # update the manuals when building a source dist
111 if len(sys.argv) >= 2 and sys.argv[1] in ('sdist','bdist_rpm'):
111 if len(sys.argv) >= 2 and sys.argv[1] in ('sdist','bdist_rpm'):
112
112
113 # List of things to be updated. Each entry is a triplet of args for
113 # List of things to be updated. Each entry is a triplet of args for
114 # target_update()
114 # target_update()
115 to_update = [
115 to_update = [
116 ('docs/man/ipython.1.gz',
116 ('docs/man/ipython.1.gz',
117 ['docs/man/ipython.1'],
117 ['docs/man/ipython.1'],
118 'cd docs/man && gzip -9c ipython.1 > ipython.1.gz'),
118 'cd docs/man && gzip -9c ipython.1 > ipython.1.gz'),
119 ]
119 ]
120
120
121
121
122 [ target_update(*t) for t in to_update ]
122 [ target_update(*t) for t in to_update ]
123
123
124 #---------------------------------------------------------------------------
124 #---------------------------------------------------------------------------
125 # Find all the packages, package data, and data_files
125 # Find all the packages, package data, and data_files
126 #---------------------------------------------------------------------------
126 #---------------------------------------------------------------------------
127
127
128 packages = find_packages()
128 packages = find_packages()
129 package_data = find_package_data()
129 package_data = find_package_data()
130
130
131 data_files = find_data_files()
131 data_files = find_data_files()
132
132
133 setup_args['packages'] = packages
133 setup_args['packages'] = packages
134 setup_args['package_data'] = package_data
134 setup_args['package_data'] = package_data
135 setup_args['data_files'] = data_files
135 setup_args['data_files'] = data_files
136
136
137 #---------------------------------------------------------------------------
137 #---------------------------------------------------------------------------
138 # custom distutils commands
138 # custom distutils commands
139 #---------------------------------------------------------------------------
139 #---------------------------------------------------------------------------
140 # imports here, so they are after setuptools import if there was one
140 # imports here, so they are after setuptools import if there was one
141 from distutils.command.sdist import sdist
141 from distutils.command.sdist import sdist
142
142
143 setup_args['cmdclass'] = {
143 setup_args['cmdclass'] = {
144 'build_py': \
144 'build_py': \
145 check_package_data_first(git_prebuild('IPython')),
145 check_package_data_first(git_prebuild('IPython')),
146 'sdist' : git_prebuild('IPython', sdist),
146 'sdist' : git_prebuild('IPython', sdist),
147 'symlink': install_symlinked,
147 'symlink': install_symlinked,
148 'install_lib_symlink': install_lib_symlink,
148 'install_lib_symlink': install_lib_symlink,
149 'install_scripts_sym': install_scripts_for_symlink,
149 'install_scripts_sym': install_scripts_for_symlink,
150 'unsymlink': unsymlink,
150 'unsymlink': unsymlink,
151 }
151 }
152
152
153
153
154 #---------------------------------------------------------------------------
154 #---------------------------------------------------------------------------
155 # Handle scripts, dependencies, and setuptools specific things
155 # Handle scripts, dependencies, and setuptools specific things
156 #---------------------------------------------------------------------------
156 #---------------------------------------------------------------------------
157
157
158 # For some commands, use setuptools. Note that we do NOT list install here!
158 # For some commands, use setuptools. Note that we do NOT list install here!
159 # If you want a setuptools-enhanced install, just run 'setupegg.py install'
159 # If you want a setuptools-enhanced install, just run 'setupegg.py install'
160 needs_setuptools = {'develop', 'release', 'bdist_egg', 'bdist_rpm',
160 needs_setuptools = {'develop', 'release', 'bdist_egg', 'bdist_rpm',
161 'bdist', 'bdist_dumb', 'bdist_wininst', 'bdist_wheel',
161 'bdist', 'bdist_dumb', 'bdist_wininst', 'bdist_wheel',
162 'egg_info', 'easy_install', 'upload', 'install_egg_info',
162 'egg_info', 'easy_install', 'upload', 'install_egg_info',
163 }
163 }
164
164
165 if len(needs_setuptools.intersection(sys.argv)) > 0:
165 if len(needs_setuptools.intersection(sys.argv)) > 0:
166 import setuptools
166 import setuptools
167
167
168 # This dict is used for passing extra arguments that are setuptools
168 # This dict is used for passing extra arguments that are setuptools
169 # specific to setup
169 # specific to setup
170 setuptools_extra_args = {}
170 setuptools_extra_args = {}
171
171
172 # setuptools requirements
172 # setuptools requirements
173
173
174 extras_require = dict(
174 extras_require = dict(
175 parallel = ['ipyparallel'],
175 parallel = ['ipyparallel'],
176 qtconsole = ['qtconsole'],
176 qtconsole = ['qtconsole'],
177 doc = ['Sphinx>=1.3'],
177 doc = ['Sphinx>=1.3'],
178 test = ['nose>=0.10.1', 'requests', 'testpath', 'pygments', 'nbformat', 'ipykernel', 'numpy'],
178 test = ['nose>=0.10.1', 'requests', 'testpath', 'pygments', 'nbformat', 'ipykernel', 'numpy'],
179 terminal = [],
179 terminal = [],
180 kernel = ['ipykernel'],
180 kernel = ['ipykernel'],
181 nbformat = ['nbformat'],
181 nbformat = ['nbformat'],
182 notebook = ['notebook', 'ipywidgets'],
182 notebook = ['notebook', 'ipywidgets'],
183 nbconvert = ['nbconvert'],
183 nbconvert = ['nbconvert'],
184 )
184 )
185
185
186 install_requires = [
186 install_requires = [
187 'setuptools>=18.5',
187 'setuptools>=18.5',
188 'jedi>=0.10',
188 'jedi>=0.10',
189 'decorator',
189 'decorator',
190 'pickleshare',
190 'pickleshare',
191 'simplegeneric>0.8',
191 'simplegeneric>0.8',
192 'traitlets>=4.2',
192 'traitlets>=4.2',
193 'prompt_toolkit>=2.0.0,<2.1.0',
193 'prompt_toolkit>=2.0.0,<2.1.0',
194 'pygments',
194 'pygments',
195 'backcall',
195 'backcall',
196 ]
196 ]
197
197
198 # Platform-specific dependencies:
198 # Platform-specific dependencies:
199 # This is the correct way to specify these,
199 # This is the correct way to specify these,
200 # but requires pip >= 6. pip < 6 ignores these.
200 # but requires pip >= 6. pip < 6 ignores these.
201
201
202 extras_require.update({
202 extras_require.update({
203 ':python_version == "3.4"': ['typing'],
203 ':python_version == "3.4"': ['typing'],
204 ':python_version >= "3.5"': ['trio', 'curio'],
204 ':sys_platform != "win32"': ['pexpect'],
205 ':sys_platform != "win32"': ['pexpect'],
205 ':sys_platform == "darwin"': ['appnope'],
206 ':sys_platform == "darwin"': ['appnope'],
206 ':sys_platform == "win32"': ['colorama'],
207 ':sys_platform == "win32"': ['colorama'],
207 ':sys_platform == "win32" and python_version < "3.6"': ['win_unicode_console>=0.5'],
208 ':sys_platform == "win32" and python_version < "3.6"': ['win_unicode_console>=0.5'],
208 })
209 })
209 # FIXME: re-specify above platform dependencies for pip < 6
210 # FIXME: re-specify above platform dependencies for pip < 6
210 # These would result in non-portable bdists.
211 # These would result in non-portable bdists.
211 if not any(arg.startswith('bdist') for arg in sys.argv):
212 if not any(arg.startswith('bdist') for arg in sys.argv):
212 if sys.platform == 'darwin':
213 if sys.platform == 'darwin':
213 install_requires.extend(['appnope'])
214 install_requires.extend(['appnope'])
214
215
215 if not sys.platform.startswith('win'):
216 if not sys.platform.startswith('win'):
216 install_requires.append('pexpect')
217 install_requires.append('pexpect')
217
218
218 # workaround pypa/setuptools#147, where setuptools misspells
219 # workaround pypa/setuptools#147, where setuptools misspells
219 # platform_python_implementation as python_implementation
220 # platform_python_implementation as python_implementation
220 if 'setuptools' in sys.modules:
221 if 'setuptools' in sys.modules:
221 for key in list(extras_require):
222 for key in list(extras_require):
222 if 'platform_python_implementation' in key:
223 if 'platform_python_implementation' in key:
223 new_key = key.replace('platform_python_implementation', 'python_implementation')
224 new_key = key.replace('platform_python_implementation', 'python_implementation')
224 extras_require[new_key] = extras_require.pop(key)
225 extras_require[new_key] = extras_require.pop(key)
225
226
226 everything = set()
227 everything = set()
227 for key, deps in extras_require.items():
228 for key, deps in extras_require.items():
228 if ':' not in key:
229 if ':' not in key:
229 everything.update(deps)
230 everything.update(deps)
230 extras_require['all'] = everything
231 extras_require['all'] = everything
231
232
232 if 'setuptools' in sys.modules:
233 if 'setuptools' in sys.modules:
233 setuptools_extra_args['python_requires'] = '>=3.4'
234 setuptools_extra_args['python_requires'] = '>=3.4'
234 setuptools_extra_args['zip_safe'] = False
235 setuptools_extra_args['zip_safe'] = False
235 setuptools_extra_args['entry_points'] = {
236 setuptools_extra_args['entry_points'] = {
236 'console_scripts': find_entry_points(),
237 'console_scripts': find_entry_points(),
237 'pygments.lexers': [
238 'pygments.lexers': [
238 'ipythonconsole = IPython.lib.lexers:IPythonConsoleLexer',
239 'ipythonconsole = IPython.lib.lexers:IPythonConsoleLexer',
239 'ipython = IPython.lib.lexers:IPythonLexer',
240 'ipython = IPython.lib.lexers:IPythonLexer',
240 'ipython3 = IPython.lib.lexers:IPython3Lexer',
241 'ipython3 = IPython.lib.lexers:IPython3Lexer',
241 ],
242 ],
242 }
243 }
243 setup_args['extras_require'] = extras_require
244 setup_args['extras_require'] = extras_require
244 setup_args['install_requires'] = install_requires
245 setup_args['install_requires'] = install_requires
245
246
246 else:
247 else:
247 # scripts has to be a non-empty list, or install_scripts isn't called
248 # scripts has to be a non-empty list, or install_scripts isn't called
248 setup_args['scripts'] = [e.split('=')[0].strip() for e in find_entry_points()]
249 setup_args['scripts'] = [e.split('=')[0].strip() for e in find_entry_points()]
249
250
250 setup_args['cmdclass']['build_scripts'] = build_scripts_entrypt
251 setup_args['cmdclass']['build_scripts'] = build_scripts_entrypt
251
252
252 #---------------------------------------------------------------------------
253 #---------------------------------------------------------------------------
253 # Do the actual setup now
254 # Do the actual setup now
254 #---------------------------------------------------------------------------
255 #---------------------------------------------------------------------------
255
256
256 setup_args.update(setuptools_extra_args)
257 setup_args.update(setuptools_extra_args)
257
258
258
259
259
260
260 def main():
261 def main():
261 setup(**setup_args)
262 setup(**setup_args)
262
263
263 if __name__ == '__main__':
264 if __name__ == '__main__':
264 main()
265 main()
General Comments 0
You need to be logged in to leave comments. Login now