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