##// END OF EJS Templates
Small cleanups, no functional changes.
Fernando Perez -
Show More
@@ -1,2371 +1,2374 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-2010 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 # Imports
15 15 #-----------------------------------------------------------------------------
16 16
17 17 from __future__ import with_statement
18 18 from __future__ import absolute_import
19 19
20 20 import __builtin__
21 21 import __future__
22 22 import abc
23 23 import atexit
24 24 import codeop
25 25 import exceptions
26 26 import new
27 27 import os
28 28 import re
29 29 import string
30 30 import sys
31 31 import tempfile
32 32 from contextlib import nested
33 33
34 34 from IPython.config.configurable import Configurable
35 35 from IPython.core import debugger, oinspect
36 36 from IPython.core import history as ipcorehist
37 37 from IPython.core import page
38 38 from IPython.core import prefilter
39 39 from IPython.core import shadowns
40 40 from IPython.core import ultratb
41 41 from IPython.core.alias import AliasManager
42 42 from IPython.core.builtin_trap import BuiltinTrap
43 43 from IPython.core.display_trap import DisplayTrap
44 44 from IPython.core.displayhook import DisplayHook
45 45 from IPython.core.error import TryNext, UsageError
46 46 from IPython.core.extensions import ExtensionManager
47 47 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
48 48 from IPython.core.inputlist import InputList
49 49 from IPython.core.logger import Logger
50 50 from IPython.core.magic import Magic
51 51 from IPython.core.payload import PayloadManager
52 52 from IPython.core.plugin import PluginManager
53 53 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
54 54 from IPython.external.Itpl import ItplNS
55 55 from IPython.utils import PyColorize
56 56 from IPython.utils import io
57 57 from IPython.utils import pickleshare
58 58 from IPython.utils.doctestreload import doctest_reload
59 59 from IPython.utils.io import ask_yes_no, rprint
60 60 from IPython.utils.ipstruct import Struct
61 61 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
62 62 from IPython.utils.process import system, getoutput
63 63 from IPython.utils.strdispatch import StrDispatch
64 64 from IPython.utils.syspathcontext import prepended_to_syspath
65 65 from IPython.utils.text import num_ini_spaces, format_screen
66 66 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
67 67 List, Unicode, Instance, Type)
68 68 from IPython.utils.warn import warn, error, fatal
69 69 import IPython.core.hooks
70 70
71 # from IPython.utils import growl
72 # growl.start("IPython")
73
74 71 #-----------------------------------------------------------------------------
75 72 # Globals
76 73 #-----------------------------------------------------------------------------
77 74
78 75 # compiled regexps for autoindent management
79 76 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
80 77
81 78 #-----------------------------------------------------------------------------
82 79 # Utilities
83 80 #-----------------------------------------------------------------------------
84 81
85 82 # store the builtin raw_input globally, and use this always, in case user code
86 83 # overwrites it (like wx.py.PyShell does)
87 84 raw_input_original = raw_input
88 85
89 86 def softspace(file, newvalue):
90 87 """Copied from code.py, to remove the dependency"""
91 88
92 89 oldvalue = 0
93 90 try:
94 91 oldvalue = file.softspace
95 92 except AttributeError:
96 93 pass
97 94 try:
98 95 file.softspace = newvalue
99 96 except (AttributeError, TypeError):
100 97 # "attribute-less object" or "read-only attributes"
101 98 pass
102 99 return oldvalue
103 100
104 101
105 102 def no_op(*a, **kw): pass
106 103
107 104 class SpaceInInput(exceptions.Exception): pass
108 105
109 106 class Bunch: pass
110 107
111 108
112 109 def get_default_colors():
113 110 if sys.platform=='darwin':
114 111 return "LightBG"
115 112 elif os.name=='nt':
116 113 return 'Linux'
117 114 else:
118 115 return 'Linux'
119 116
120 117
121 118 class SeparateStr(Str):
122 119 """A Str subclass to validate separate_in, separate_out, etc.
123 120
124 121 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
125 122 """
126 123
127 124 def validate(self, obj, value):
128 125 if value == '0': value = ''
129 126 value = value.replace('\\n','\n')
130 127 return super(SeparateStr, self).validate(obj, value)
131 128
132 129 class MultipleInstanceError(Exception):
133 130 pass
134 131
135 132
136 133 #-----------------------------------------------------------------------------
137 134 # Main IPython class
138 135 #-----------------------------------------------------------------------------
139 136
140 137
141 138 class InteractiveShell(Configurable, Magic):
142 139 """An enhanced, interactive shell for Python."""
143 140
144 141 _instance = None
145 142 autocall = Enum((0,1,2), default_value=1, config=True)
146 143 # TODO: remove all autoindent logic and put into frontends.
147 144 # We can't do this yet because even runlines uses the autoindent.
148 145 autoindent = CBool(True, config=True)
149 146 automagic = CBool(True, config=True)
150 147 cache_size = Int(1000, config=True)
151 148 color_info = CBool(True, config=True)
152 149 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
153 150 default_value=get_default_colors(), config=True)
154 151 debug = CBool(False, config=True)
155 152 deep_reload = CBool(False, config=True)
156 153 displayhook_class = Type(DisplayHook)
157 154 exit_now = CBool(False)
158 155 filename = Str("<ipython console>")
159 156 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
160 157 logstart = CBool(False, config=True)
161 158 logfile = Str('', config=True)
162 159 logappend = Str('', config=True)
163 160 object_info_string_level = Enum((0,1,2), default_value=0,
164 161 config=True)
165 162 pdb = CBool(False, config=True)
166 163 pprint = CBool(True, config=True)
167 164 profile = Str('', config=True)
168 165 prompt_in1 = Str('In [\\#]: ', config=True)
169 166 prompt_in2 = Str(' .\\D.: ', config=True)
170 167 prompt_out = Str('Out[\\#]: ', config=True)
171 168 prompts_pad_left = CBool(True, config=True)
172 169 quiet = CBool(False, config=True)
173 170
174 171 # The readline stuff will eventually be moved to the terminal subclass
175 172 # but for now, we can't do that as readline is welded in everywhere.
176 173 readline_use = CBool(True, config=True)
177 174 readline_merge_completions = CBool(True, config=True)
178 175 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
179 176 readline_remove_delims = Str('-/~', config=True)
180 177 readline_parse_and_bind = List([
181 178 'tab: complete',
182 179 '"\C-l": clear-screen',
183 180 'set show-all-if-ambiguous on',
184 181 '"\C-o": tab-insert',
185 182 '"\M-i": " "',
186 183 '"\M-o": "\d\d\d\d"',
187 184 '"\M-I": "\d\d\d\d"',
188 185 '"\C-r": reverse-search-history',
189 186 '"\C-s": forward-search-history',
190 187 '"\C-p": history-search-backward',
191 188 '"\C-n": history-search-forward',
192 189 '"\e[A": history-search-backward',
193 190 '"\e[B": history-search-forward',
194 191 '"\C-k": kill-line',
195 192 '"\C-u": unix-line-discard',
196 193 ], allow_none=False, config=True)
197 194
198 195 # TODO: this part of prompt management should be moved to the frontends.
199 196 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
200 197 separate_in = SeparateStr('\n', config=True)
201 198 separate_out = SeparateStr('', config=True)
202 199 separate_out2 = SeparateStr('', config=True)
203 200 wildcards_case_sensitive = CBool(True, config=True)
204 201 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
205 202 default_value='Context', config=True)
206 203
207 204 # Subcomponents of InteractiveShell
208 205 alias_manager = Instance('IPython.core.alias.AliasManager')
209 206 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
210 207 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
211 208 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
212 209 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
213 210 plugin_manager = Instance('IPython.core.plugin.PluginManager')
214 211 payload_manager = Instance('IPython.core.payload.PayloadManager')
215 212
216 213 def __init__(self, config=None, ipython_dir=None,
217 214 user_ns=None, user_global_ns=None,
218 215 custom_exceptions=((),None)):
219 216
220 217 # This is where traits with a config_key argument are updated
221 218 # from the values on config.
222 219 super(InteractiveShell, self).__init__(config=config)
223 220
224 221 # These are relatively independent and stateless
225 222 self.init_ipython_dir(ipython_dir)
226 223 self.init_instance_attrs()
227 224
228 225 # Create namespaces (user_ns, user_global_ns, etc.)
229 226 self.init_create_namespaces(user_ns, user_global_ns)
230 227 # This has to be done after init_create_namespaces because it uses
231 228 # something in self.user_ns, but before init_sys_modules, which
232 229 # is the first thing to modify sys.
233 230 # TODO: When we override sys.stdout and sys.stderr before this class
234 231 # is created, we are saving the overridden ones here. Not sure if this
235 232 # is what we want to do.
236 233 self.save_sys_module_state()
237 234 self.init_sys_modules()
238 235
239 236 self.init_history()
240 237 self.init_encoding()
241 238 self.init_prefilter()
242 239
243 240 Magic.__init__(self, self)
244 241
245 242 self.init_syntax_highlighting()
246 243 self.init_hooks()
247 244 self.init_pushd_popd_magic()
248 245 # self.init_traceback_handlers use to be here, but we moved it below
249 246 # because it and init_io have to come after init_readline.
250 247 self.init_user_ns()
251 248 self.init_logger()
252 249 self.init_alias()
253 250 self.init_builtins()
254 251
255 252 # pre_config_initialization
256 253 self.init_shadow_hist()
257 254
258 255 # The next section should contain averything that was in ipmaker.
259 256 self.init_logstart()
260 257
261 258 # The following was in post_config_initialization
262 259 self.init_inspector()
263 260 # init_readline() must come before init_io(), because init_io uses
264 261 # readline related things.
265 262 self.init_readline()
266 263 # TODO: init_io() needs to happen before init_traceback handlers
267 264 # because the traceback handlers hardcode the stdout/stderr streams.
268 265 # This logic in in debugger.Pdb and should eventually be changed.
269 266 self.init_io()
270 267 self.init_traceback_handlers(custom_exceptions)
271 268 self.init_prompts()
272 269 self.init_displayhook()
273 270 self.init_reload_doctest()
274 271 self.init_magics()
275 272 self.init_pdb()
276 273 self.init_extension_manager()
277 274 self.init_plugin_manager()
278 275 self.init_payload()
279 276 self.hooks.late_startup_hook()
280 277 atexit.register(self.atexit_operations)
281 278
282 279 @classmethod
283 280 def instance(cls, *args, **kwargs):
284 281 """Returns a global InteractiveShell instance."""
285 282 if cls._instance is None:
286 283 inst = cls(*args, **kwargs)
287 284 # Now make sure that the instance will also be returned by
288 285 # the subclasses instance attribute.
289 286 for subclass in cls.mro():
290 if issubclass(cls, subclass) and issubclass(subclass, InteractiveShell):
287 if issubclass(cls, subclass) and \
288 issubclass(subclass, InteractiveShell):
291 289 subclass._instance = inst
292 290 else:
293 291 break
294 292 if isinstance(cls._instance, cls):
295 293 return cls._instance
296 294 else:
297 295 raise MultipleInstanceError(
298 296 'Multiple incompatible subclass instances of '
299 297 'InteractiveShell are being created.'
300 298 )
301 299
302 300 @classmethod
303 301 def initialized(cls):
304 302 return hasattr(cls, "_instance")
305 303
306 304 def get_ipython(self):
307 305 """Return the currently running IPython instance."""
308 306 return self
309 307
310 308 #-------------------------------------------------------------------------
311 309 # Trait changed handlers
312 310 #-------------------------------------------------------------------------
313 311
314 312 def _ipython_dir_changed(self, name, new):
315 313 if not os.path.isdir(new):
316 314 os.makedirs(new, mode = 0777)
317 315
318 316 def set_autoindent(self,value=None):
319 317 """Set the autoindent flag, checking for readline support.
320 318
321 319 If called with no arguments, it acts as a toggle."""
322 320
323 321 if not self.has_readline:
324 322 if os.name == 'posix':
325 323 warn("The auto-indent feature requires the readline library")
326 324 self.autoindent = 0
327 325 return
328 326 if value is None:
329 327 self.autoindent = not self.autoindent
330 328 else:
331 329 self.autoindent = value
332 330
333 331 #-------------------------------------------------------------------------
334 332 # init_* methods called by __init__
335 333 #-------------------------------------------------------------------------
336 334
337 335 def init_ipython_dir(self, ipython_dir):
338 336 if ipython_dir is not None:
339 337 self.ipython_dir = ipython_dir
340 338 self.config.Global.ipython_dir = self.ipython_dir
341 339 return
342 340
343 341 if hasattr(self.config.Global, 'ipython_dir'):
344 342 self.ipython_dir = self.config.Global.ipython_dir
345 343 else:
346 344 self.ipython_dir = get_ipython_dir()
347 345
348 346 # All children can just read this
349 347 self.config.Global.ipython_dir = self.ipython_dir
350 348
351 349 def init_instance_attrs(self):
352 350 self.more = False
353 351
354 352 # command compiler
355 353 self.compile = codeop.CommandCompiler()
356 354
357 355 # User input buffer
358 356 self.buffer = []
359 357
360 358 # Make an empty namespace, which extension writers can rely on both
361 359 # existing and NEVER being used by ipython itself. This gives them a
362 360 # convenient location for storing additional information and state
363 361 # their extensions may require, without fear of collisions with other
364 362 # ipython names that may develop later.
365 363 self.meta = Struct()
366 364
367 365 # Object variable to store code object waiting execution. This is
368 366 # used mainly by the multithreaded shells, but it can come in handy in
369 367 # other situations. No need to use a Queue here, since it's a single
370 368 # item which gets cleared once run.
371 369 self.code_to_run = None
372 370
373 371 # Temporary files used for various purposes. Deleted at exit.
374 372 self.tempfiles = []
375 373
376 374 # Keep track of readline usage (later set by init_readline)
377 375 self.has_readline = False
378 376
379 377 # keep track of where we started running (mainly for crash post-mortem)
380 378 # This is not being used anywhere currently.
381 379 self.starting_dir = os.getcwd()
382 380
383 381 # Indentation management
384 382 self.indent_current_nsp = 0
385 383
386 384 def init_encoding(self):
387 385 # Get system encoding at startup time. Certain terminals (like Emacs
388 386 # under Win32 have it set to None, and we need to have a known valid
389 387 # encoding to use in the raw_input() method
390 388 try:
391 389 self.stdin_encoding = sys.stdin.encoding or 'ascii'
392 390 except AttributeError:
393 391 self.stdin_encoding = 'ascii'
394 392
395 393 def init_syntax_highlighting(self):
396 394 # Python source parser/formatter for syntax highlighting
397 395 pyformat = PyColorize.Parser().format
398 396 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
399 397
400 398 def init_pushd_popd_magic(self):
401 399 # for pushd/popd management
402 400 try:
403 401 self.home_dir = get_home_dir()
404 402 except HomeDirError, msg:
405 403 fatal(msg)
406 404
407 405 self.dir_stack = []
408 406
409 407 def init_logger(self):
410 408 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
411 409 # local shortcut, this is used a LOT
412 410 self.log = self.logger.log
413 411
414 412 def init_logstart(self):
415 413 if self.logappend:
416 414 self.magic_logstart(self.logappend + ' append')
417 415 elif self.logfile:
418 416 self.magic_logstart(self.logfile)
419 417 elif self.logstart:
420 418 self.magic_logstart()
421 419
422 420 def init_builtins(self):
423 421 self.builtin_trap = BuiltinTrap(shell=self)
424 422
425 423 def init_inspector(self):
426 424 # Object inspector
427 425 self.inspector = oinspect.Inspector(oinspect.InspectColors,
428 426 PyColorize.ANSICodeColors,
429 427 'NoColor',
430 428 self.object_info_string_level)
431 429
432 430 def init_io(self):
433 431 import IPython.utils.io
434 432 if sys.platform == 'win32' and self.has_readline:
435 433 Term = io.IOTerm(
436 434 cout=self.readline._outputfile,cerr=self.readline._outputfile
437 435 )
438 436 else:
439 437 Term = io.IOTerm()
440 438 io.Term = Term
441 439
442 440 def init_prompts(self):
443 441 # TODO: This is a pass for now because the prompts are managed inside
444 442 # the DisplayHook. Once there is a separate prompt manager, this
445 443 # will initialize that object and all prompt related information.
446 444 pass
447 445
448 446 def init_displayhook(self):
449 447 # Initialize displayhook, set in/out prompts and printing system
450 448 self.displayhook = self.displayhook_class(
451 449 shell=self,
452 450 cache_size=self.cache_size,
453 451 input_sep = self.separate_in,
454 452 output_sep = self.separate_out,
455 453 output_sep2 = self.separate_out2,
456 454 ps1 = self.prompt_in1,
457 455 ps2 = self.prompt_in2,
458 456 ps_out = self.prompt_out,
459 457 pad_left = self.prompts_pad_left
460 458 )
461 459 # This is a context manager that installs/revmoes the displayhook at
462 460 # the appropriate time.
463 461 self.display_trap = DisplayTrap(hook=self.displayhook)
464 462
465 463 def init_reload_doctest(self):
466 464 # Do a proper resetting of doctest, including the necessary displayhook
467 465 # monkeypatching
468 466 try:
469 467 doctest_reload()
470 468 except ImportError:
471 469 warn("doctest module does not exist.")
472 470
473 471 #-------------------------------------------------------------------------
474 472 # Things related to injections into the sys module
475 473 #-------------------------------------------------------------------------
476 474
477 475 def save_sys_module_state(self):
478 476 """Save the state of hooks in the sys module.
479 477
480 478 This has to be called after self.user_ns is created.
481 479 """
482 480 self._orig_sys_module_state = {}
483 481 self._orig_sys_module_state['stdin'] = sys.stdin
484 482 self._orig_sys_module_state['stdout'] = sys.stdout
485 483 self._orig_sys_module_state['stderr'] = sys.stderr
486 484 self._orig_sys_module_state['excepthook'] = sys.excepthook
487 485 try:
488 486 self._orig_sys_modules_main_name = self.user_ns['__name__']
489 487 except KeyError:
490 488 pass
491 489
492 490 def restore_sys_module_state(self):
493 491 """Restore the state of the sys module."""
494 492 try:
495 493 for k, v in self._orig_sys_module_state.items():
496 494 setattr(sys, k, v)
497 495 except AttributeError:
498 496 pass
499 497 # Reset what what done in self.init_sys_modules
500 498 try:
501 499 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
502 500 except (AttributeError, KeyError):
503 501 pass
504 502
505 503 #-------------------------------------------------------------------------
506 504 # Things related to hooks
507 505 #-------------------------------------------------------------------------
508 506
509 507 def init_hooks(self):
510 508 # hooks holds pointers used for user-side customizations
511 509 self.hooks = Struct()
512 510
513 511 self.strdispatchers = {}
514 512
515 513 # Set all default hooks, defined in the IPython.hooks module.
516 514 hooks = IPython.core.hooks
517 515 for hook_name in hooks.__all__:
518 516 # default hooks have priority 100, i.e. low; user hooks should have
519 517 # 0-100 priority
520 518 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
521 519
522 520 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
523 521 """set_hook(name,hook) -> sets an internal IPython hook.
524 522
525 523 IPython exposes some of its internal API as user-modifiable hooks. By
526 524 adding your function to one of these hooks, you can modify IPython's
527 525 behavior to call at runtime your own routines."""
528 526
529 527 # At some point in the future, this should validate the hook before it
530 528 # accepts it. Probably at least check that the hook takes the number
531 529 # of args it's supposed to.
532 530
533 531 f = new.instancemethod(hook,self,self.__class__)
534 532
535 533 # check if the hook is for strdispatcher first
536 534 if str_key is not None:
537 535 sdp = self.strdispatchers.get(name, StrDispatch())
538 536 sdp.add_s(str_key, f, priority )
539 537 self.strdispatchers[name] = sdp
540 538 return
541 539 if re_key is not None:
542 540 sdp = self.strdispatchers.get(name, StrDispatch())
543 541 sdp.add_re(re.compile(re_key), f, priority )
544 542 self.strdispatchers[name] = sdp
545 543 return
546 544
547 545 dp = getattr(self.hooks, name, None)
548 546 if name not in IPython.core.hooks.__all__:
549 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
547 print "Warning! Hook '%s' is not one of %s" % \
548 (name, IPython.core.hooks.__all__ )
550 549 if not dp:
551 550 dp = IPython.core.hooks.CommandChainDispatcher()
552 551
553 552 try:
554 553 dp.add(f,priority)
555 554 except AttributeError:
556 555 # it was not commandchain, plain old func - replace
557 556 dp = f
558 557
559 558 setattr(self.hooks,name, dp)
560 559
561 560 #-------------------------------------------------------------------------
562 561 # Things related to the "main" module
563 562 #-------------------------------------------------------------------------
564 563
565 564 def new_main_mod(self,ns=None):
566 565 """Return a new 'main' module object for user code execution.
567 566 """
568 567 main_mod = self._user_main_module
569 568 init_fakemod_dict(main_mod,ns)
570 569 return main_mod
571 570
572 571 def cache_main_mod(self,ns,fname):
573 572 """Cache a main module's namespace.
574 573
575 574 When scripts are executed via %run, we must keep a reference to the
576 575 namespace of their __main__ module (a FakeModule instance) around so
577 576 that Python doesn't clear it, rendering objects defined therein
578 577 useless.
579 578
580 579 This method keeps said reference in a private dict, keyed by the
581 580 absolute path of the module object (which corresponds to the script
582 581 path). This way, for multiple executions of the same script we only
583 582 keep one copy of the namespace (the last one), thus preventing memory
584 583 leaks from old references while allowing the objects from the last
585 584 execution to be accessible.
586 585
587 586 Note: we can not allow the actual FakeModule instances to be deleted,
588 587 because of how Python tears down modules (it hard-sets all their
589 588 references to None without regard for reference counts). This method
590 589 must therefore make a *copy* of the given namespace, to allow the
591 590 original module's __dict__ to be cleared and reused.
592 591
593 592
594 593 Parameters
595 594 ----------
596 595 ns : a namespace (a dict, typically)
597 596
598 597 fname : str
599 598 Filename associated with the namespace.
600 599
601 600 Examples
602 601 --------
603 602
604 603 In [10]: import IPython
605 604
606 605 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
607 606
608 607 In [12]: IPython.__file__ in _ip._main_ns_cache
609 608 Out[12]: True
610 609 """
611 610 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
612 611
613 612 def clear_main_mod_cache(self):
614 613 """Clear the cache of main modules.
615 614
616 615 Mainly for use by utilities like %reset.
617 616
618 617 Examples
619 618 --------
620 619
621 620 In [15]: import IPython
622 621
623 622 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
624 623
625 624 In [17]: len(_ip._main_ns_cache) > 0
626 625 Out[17]: True
627 626
628 627 In [18]: _ip.clear_main_mod_cache()
629 628
630 629 In [19]: len(_ip._main_ns_cache) == 0
631 630 Out[19]: True
632 631 """
633 632 self._main_ns_cache.clear()
634 633
635 634 #-------------------------------------------------------------------------
636 635 # Things related to debugging
637 636 #-------------------------------------------------------------------------
638 637
639 638 def init_pdb(self):
640 639 # Set calling of pdb on exceptions
641 640 # self.call_pdb is a property
642 641 self.call_pdb = self.pdb
643 642
644 643 def _get_call_pdb(self):
645 644 return self._call_pdb
646 645
647 646 def _set_call_pdb(self,val):
648 647
649 648 if val not in (0,1,False,True):
650 649 raise ValueError,'new call_pdb value must be boolean'
651 650
652 651 # store value in instance
653 652 self._call_pdb = val
654 653
655 654 # notify the actual exception handlers
656 655 self.InteractiveTB.call_pdb = val
657 656
658 657 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
659 658 'Control auto-activation of pdb at exceptions')
660 659
661 660 def debugger(self,force=False):
662 661 """Call the pydb/pdb debugger.
663 662
664 663 Keywords:
665 664
666 665 - force(False): by default, this routine checks the instance call_pdb
667 666 flag and does not actually invoke the debugger if the flag is false.
668 667 The 'force' option forces the debugger to activate even if the flag
669 668 is false.
670 669 """
671 670
672 671 if not (force or self.call_pdb):
673 672 return
674 673
675 674 if not hasattr(sys,'last_traceback'):
676 675 error('No traceback has been produced, nothing to debug.')
677 676 return
678 677
679 678 # use pydb if available
680 679 if debugger.has_pydb:
681 680 from pydb import pm
682 681 else:
683 682 # fallback to our internal debugger
684 683 pm = lambda : self.InteractiveTB.debugger(force=True)
685 684 self.history_saving_wrapper(pm)()
686 685
687 686 #-------------------------------------------------------------------------
688 687 # Things related to IPython's various namespaces
689 688 #-------------------------------------------------------------------------
690 689
691 690 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
692 691 # Create the namespace where the user will operate. user_ns is
693 692 # normally the only one used, and it is passed to the exec calls as
694 693 # the locals argument. But we do carry a user_global_ns namespace
695 694 # given as the exec 'globals' argument, This is useful in embedding
696 695 # situations where the ipython shell opens in a context where the
697 696 # distinction between locals and globals is meaningful. For
698 697 # non-embedded contexts, it is just the same object as the user_ns dict.
699 698
700 699 # FIXME. For some strange reason, __builtins__ is showing up at user
701 700 # level as a dict instead of a module. This is a manual fix, but I
702 701 # should really track down where the problem is coming from. Alex
703 702 # Schmolck reported this problem first.
704 703
705 704 # A useful post by Alex Martelli on this topic:
706 705 # Re: inconsistent value from __builtins__
707 706 # Von: Alex Martelli <aleaxit@yahoo.com>
708 707 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
709 708 # Gruppen: comp.lang.python
710 709
711 710 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
712 711 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
713 712 # > <type 'dict'>
714 713 # > >>> print type(__builtins__)
715 714 # > <type 'module'>
716 715 # > Is this difference in return value intentional?
717 716
718 717 # Well, it's documented that '__builtins__' can be either a dictionary
719 718 # or a module, and it's been that way for a long time. Whether it's
720 719 # intentional (or sensible), I don't know. In any case, the idea is
721 720 # that if you need to access the built-in namespace directly, you
722 721 # should start with "import __builtin__" (note, no 's') which will
723 722 # definitely give you a module. Yeah, it's somewhat confusing:-(.
724 723
725 724 # These routines return properly built dicts as needed by the rest of
726 725 # the code, and can also be used by extension writers to generate
727 726 # properly initialized namespaces.
728 user_ns, user_global_ns = self.make_user_namespaces(user_ns, user_global_ns)
727 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
728 user_global_ns)
729 729
730 730 # Assign namespaces
731 731 # This is the namespace where all normal user variables live
732 732 self.user_ns = user_ns
733 733 self.user_global_ns = user_global_ns
734 734
735 735 # An auxiliary namespace that checks what parts of the user_ns were
736 736 # loaded at startup, so we can list later only variables defined in
737 737 # actual interactive use. Since it is always a subset of user_ns, it
738 738 # doesn't need to be separately tracked in the ns_table.
739 739 self.user_ns_hidden = {}
740 740
741 741 # A namespace to keep track of internal data structures to prevent
742 742 # them from cluttering user-visible stuff. Will be updated later
743 743 self.internal_ns = {}
744 744
745 745 # Now that FakeModule produces a real module, we've run into a nasty
746 746 # problem: after script execution (via %run), the module where the user
747 747 # code ran is deleted. Now that this object is a true module (needed
748 748 # so docetst and other tools work correctly), the Python module
749 749 # teardown mechanism runs over it, and sets to None every variable
750 750 # present in that module. Top-level references to objects from the
751 751 # script survive, because the user_ns is updated with them. However,
752 752 # calling functions defined in the script that use other things from
753 753 # the script will fail, because the function's closure had references
754 754 # to the original objects, which are now all None. So we must protect
755 755 # these modules from deletion by keeping a cache.
756 756 #
757 757 # To avoid keeping stale modules around (we only need the one from the
758 758 # last run), we use a dict keyed with the full path to the script, so
759 759 # only the last version of the module is held in the cache. Note,
760 760 # however, that we must cache the module *namespace contents* (their
761 761 # __dict__). Because if we try to cache the actual modules, old ones
762 762 # (uncached) could be destroyed while still holding references (such as
763 763 # those held by GUI objects that tend to be long-lived)>
764 764 #
765 765 # The %reset command will flush this cache. See the cache_main_mod()
766 766 # and clear_main_mod_cache() methods for details on use.
767 767
768 768 # This is the cache used for 'main' namespaces
769 769 self._main_ns_cache = {}
770 770 # And this is the single instance of FakeModule whose __dict__ we keep
771 771 # copying and clearing for reuse on each %run
772 772 self._user_main_module = FakeModule()
773 773
774 774 # A table holding all the namespaces IPython deals with, so that
775 775 # introspection facilities can search easily.
776 776 self.ns_table = {'user':user_ns,
777 777 'user_global':user_global_ns,
778 778 'internal':self.internal_ns,
779 779 'builtin':__builtin__.__dict__
780 780 }
781 781
782 782 # Similarly, track all namespaces where references can be held and that
783 783 # we can safely clear (so it can NOT include builtin). This one can be
784 784 # a simple list.
785 785 self.ns_refs_table = [ user_ns, user_global_ns, self.user_ns_hidden,
786 786 self.internal_ns, self._main_ns_cache ]
787 787
788 788 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
789 789 """Return a valid local and global user interactive namespaces.
790 790
791 791 This builds a dict with the minimal information needed to operate as a
792 792 valid IPython user namespace, which you can pass to the various
793 793 embedding classes in ipython. The default implementation returns the
794 794 same dict for both the locals and the globals to allow functions to
795 795 refer to variables in the namespace. Customized implementations can
796 796 return different dicts. The locals dictionary can actually be anything
797 797 following the basic mapping protocol of a dict, but the globals dict
798 798 must be a true dict, not even a subclass. It is recommended that any
799 799 custom object for the locals namespace synchronize with the globals
800 800 dict somehow.
801 801
802 802 Raises TypeError if the provided globals namespace is not a true dict.
803 803
804 804 Parameters
805 805 ----------
806 806 user_ns : dict-like, optional
807 807 The current user namespace. The items in this namespace should
808 808 be included in the output. If None, an appropriate blank
809 809 namespace should be created.
810 810 user_global_ns : dict, optional
811 811 The current user global namespace. The items in this namespace
812 812 should be included in the output. If None, an appropriate
813 813 blank namespace should be created.
814 814
815 815 Returns
816 816 -------
817 817 A pair of dictionary-like object to be used as the local namespace
818 818 of the interpreter and a dict to be used as the global namespace.
819 819 """
820 820
821 821
822 822 # We must ensure that __builtin__ (without the final 's') is always
823 823 # available and pointing to the __builtin__ *module*. For more details:
824 824 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
825 825
826 826 if user_ns is None:
827 827 # Set __name__ to __main__ to better match the behavior of the
828 828 # normal interpreter.
829 829 user_ns = {'__name__' :'__main__',
830 830 '__builtin__' : __builtin__,
831 831 '__builtins__' : __builtin__,
832 832 }
833 833 else:
834 834 user_ns.setdefault('__name__','__main__')
835 835 user_ns.setdefault('__builtin__',__builtin__)
836 836 user_ns.setdefault('__builtins__',__builtin__)
837 837
838 838 if user_global_ns is None:
839 839 user_global_ns = user_ns
840 840 if type(user_global_ns) is not dict:
841 841 raise TypeError("user_global_ns must be a true dict; got %r"
842 842 % type(user_global_ns))
843 843
844 844 return user_ns, user_global_ns
845 845
846 846 def init_sys_modules(self):
847 847 # We need to insert into sys.modules something that looks like a
848 848 # module but which accesses the IPython namespace, for shelve and
849 849 # pickle to work interactively. Normally they rely on getting
850 850 # everything out of __main__, but for embedding purposes each IPython
851 851 # instance has its own private namespace, so we can't go shoving
852 852 # everything into __main__.
853 853
854 854 # note, however, that we should only do this for non-embedded
855 855 # ipythons, which really mimic the __main__.__dict__ with their own
856 856 # namespace. Embedded instances, on the other hand, should not do
857 857 # this because they need to manage the user local/global namespaces
858 858 # only, but they live within a 'normal' __main__ (meaning, they
859 859 # shouldn't overtake the execution environment of the script they're
860 860 # embedded in).
861 861
862 862 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
863 863
864 864 try:
865 865 main_name = self.user_ns['__name__']
866 866 except KeyError:
867 867 raise KeyError('user_ns dictionary MUST have a "__name__" key')
868 868 else:
869 869 sys.modules[main_name] = FakeModule(self.user_ns)
870 870
871 871 def init_user_ns(self):
872 872 """Initialize all user-visible namespaces to their minimum defaults.
873 873
874 874 Certain history lists are also initialized here, as they effectively
875 875 act as user namespaces.
876 876
877 877 Notes
878 878 -----
879 879 All data structures here are only filled in, they are NOT reset by this
880 880 method. If they were not empty before, data will simply be added to
881 881 therm.
882 882 """
883 883 # This function works in two parts: first we put a few things in
884 884 # user_ns, and we sync that contents into user_ns_hidden so that these
885 885 # initial variables aren't shown by %who. After the sync, we add the
886 886 # rest of what we *do* want the user to see with %who even on a new
887 887 # session (probably nothing, so theye really only see their own stuff)
888 888
889 889 # The user dict must *always* have a __builtin__ reference to the
890 890 # Python standard __builtin__ namespace, which must be imported.
891 891 # This is so that certain operations in prompt evaluation can be
892 892 # reliably executed with builtins. Note that we can NOT use
893 893 # __builtins__ (note the 's'), because that can either be a dict or a
894 894 # module, and can even mutate at runtime, depending on the context
895 895 # (Python makes no guarantees on it). In contrast, __builtin__ is
896 896 # always a module object, though it must be explicitly imported.
897 897
898 898 # For more details:
899 899 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
900 900 ns = dict(__builtin__ = __builtin__)
901 901
902 902 # Put 'help' in the user namespace
903 903 try:
904 904 from site import _Helper
905 905 ns['help'] = _Helper()
906 906 except ImportError:
907 907 warn('help() not available - check site.py')
908 908
909 909 # make global variables for user access to the histories
910 910 ns['_ih'] = self.input_hist
911 911 ns['_oh'] = self.output_hist
912 912 ns['_dh'] = self.dir_hist
913 913
914 914 ns['_sh'] = shadowns
915 915
916 916 # user aliases to input and output histories. These shouldn't show up
917 917 # in %who, as they can have very large reprs.
918 918 ns['In'] = self.input_hist
919 919 ns['Out'] = self.output_hist
920 920
921 921 # Store myself as the public api!!!
922 922 ns['get_ipython'] = self.get_ipython
923 923
924 924 # Sync what we've added so far to user_ns_hidden so these aren't seen
925 925 # by %who
926 926 self.user_ns_hidden.update(ns)
927 927
928 928 # Anything put into ns now would show up in %who. Think twice before
929 929 # putting anything here, as we really want %who to show the user their
930 930 # stuff, not our variables.
931 931
932 932 # Finally, update the real user's namespace
933 933 self.user_ns.update(ns)
934 934
935 935
936 936 def reset(self):
937 937 """Clear all internal namespaces.
938 938
939 939 Note that this is much more aggressive than %reset, since it clears
940 940 fully all namespaces, as well as all input/output lists.
941 941 """
942 942 for ns in self.ns_refs_table:
943 943 ns.clear()
944 944
945 945 self.alias_manager.clear_aliases()
946 946
947 947 # Clear input and output histories
948 948 self.input_hist[:] = []
949 949 self.input_hist_raw[:] = []
950 950 self.output_hist.clear()
951 951
952 952 # Restore the user namespaces to minimal usability
953 953 self.init_user_ns()
954 954
955 955 # Restore the default and user aliases
956 956 self.alias_manager.init_aliases()
957 957
958 958 def reset_selective(self, regex=None):
959 """Clear selective variables from internal namespaces based on a specified regular expression.
959 """Clear selective variables from internal namespaces based on a
960 specified regular expression.
960 961
961 962 Parameters
962 963 ----------
963 964 regex : string or compiled pattern, optional
964 A regular expression pattern that will be used in searching variable names in the users
965 namespaces.
965 A regular expression pattern that will be used in searching
966 variable names in the users namespaces.
966 967 """
967 968 if regex is not None:
968 969 try:
969 970 m = re.compile(regex)
970 971 except TypeError:
971 972 raise TypeError('regex must be a string or compiled pattern')
972 973 # Search for keys in each namespace that match the given regex
973 974 # If a match is found, delete the key/value pair.
974 975 for ns in self.ns_refs_table:
975 976 for var in ns:
976 977 if m.search(var):
977 978 del ns[var]
978 979
979 980 def push(self, variables, interactive=True):
980 981 """Inject a group of variables into the IPython user namespace.
981 982
982 983 Parameters
983 984 ----------
984 985 variables : dict, str or list/tuple of str
985 The variables to inject into the user's namespace. If a dict,
986 a simple update is done. If a str, the string is assumed to
987 have variable names separated by spaces. A list/tuple of str
988 can also be used to give the variable names. If just the variable
989 names are give (list/tuple/str) then the variable values looked
990 up in the callers frame.
986 The variables to inject into the user's namespace. If a dict, a
987 simple update is done. If a str, the string is assumed to have
988 variable names separated by spaces. A list/tuple of str can also
989 be used to give the variable names. If just the variable names are
990 give (list/tuple/str) then the variable values looked up in the
991 callers frame.
991 992 interactive : bool
992 993 If True (default), the variables will be listed with the ``who``
993 994 magic.
994 995 """
995 996 vdict = None
996 997
997 998 # We need a dict of name/value pairs to do namespace updates.
998 999 if isinstance(variables, dict):
999 1000 vdict = variables
1000 1001 elif isinstance(variables, (basestring, list, tuple)):
1001 1002 if isinstance(variables, basestring):
1002 1003 vlist = variables.split()
1003 1004 else:
1004 1005 vlist = variables
1005 1006 vdict = {}
1006 1007 cf = sys._getframe(1)
1007 1008 for name in vlist:
1008 1009 try:
1009 1010 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1010 1011 except:
1011 1012 print ('Could not get variable %s from %s' %
1012 1013 (name,cf.f_code.co_name))
1013 1014 else:
1014 1015 raise ValueError('variables must be a dict/str/list/tuple')
1015 1016
1016 1017 # Propagate variables to user namespace
1017 1018 self.user_ns.update(vdict)
1018 1019
1019 1020 # And configure interactive visibility
1020 1021 config_ns = self.user_ns_hidden
1021 1022 if interactive:
1022 1023 for name, val in vdict.iteritems():
1023 1024 config_ns.pop(name, None)
1024 1025 else:
1025 1026 for name,val in vdict.iteritems():
1026 1027 config_ns[name] = val
1027 1028
1028 1029 #-------------------------------------------------------------------------
1029 1030 # Things related to object introspection
1030 1031 #-------------------------------------------------------------------------
1031 1032 def _ofind(self, oname, namespaces=None):
1032 1033 """Find an object in the available namespaces.
1033 1034
1034 1035 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1035 1036
1036 1037 Has special code to detect magic functions.
1037 1038 """
1038 1039 #oname = oname.strip()
1039 1040 #print '1- oname: <%r>' % oname # dbg
1040 1041 try:
1041 1042 oname = oname.strip().encode('ascii')
1042 1043 #print '2- oname: <%r>' % oname # dbg
1043 1044 except UnicodeEncodeError:
1044 1045 print 'Python identifiers can only contain ascii characters.'
1045 1046 return dict(found=False)
1046 1047
1047 1048 alias_ns = None
1048 1049 if namespaces is None:
1049 1050 # Namespaces to search in:
1050 1051 # Put them in a list. The order is important so that we
1051 1052 # find things in the same order that Python finds them.
1052 1053 namespaces = [ ('Interactive', self.user_ns),
1053 1054 ('IPython internal', self.internal_ns),
1054 1055 ('Python builtin', __builtin__.__dict__),
1055 1056 ('Alias', self.alias_manager.alias_table),
1056 1057 ]
1057 1058 alias_ns = self.alias_manager.alias_table
1058 1059
1059 1060 # initialize results to 'null'
1060 1061 found = False; obj = None; ospace = None; ds = None;
1061 1062 ismagic = False; isalias = False; parent = None
1062 1063
1063 1064 # We need to special-case 'print', which as of python2.6 registers as a
1064 1065 # function but should only be treated as one if print_function was
1065 1066 # loaded with a future import. In this case, just bail.
1066 1067 if (oname == 'print' and not (self.compile.compiler.flags &
1067 1068 __future__.CO_FUTURE_PRINT_FUNCTION)):
1068 1069 return {'found':found, 'obj':obj, 'namespace':ospace,
1069 1070 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1070 1071
1071 1072 # Look for the given name by splitting it in parts. If the head is
1072 1073 # found, then we look for all the remaining parts as members, and only
1073 1074 # declare success if we can find them all.
1074 1075 oname_parts = oname.split('.')
1075 1076 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1076 1077 for nsname,ns in namespaces:
1077 1078 try:
1078 1079 obj = ns[oname_head]
1079 1080 except KeyError:
1080 1081 continue
1081 1082 else:
1082 1083 #print 'oname_rest:', oname_rest # dbg
1083 1084 for part in oname_rest:
1084 1085 try:
1085 1086 parent = obj
1086 1087 obj = getattr(obj,part)
1087 1088 except:
1088 1089 # Blanket except b/c some badly implemented objects
1089 1090 # allow __getattr__ to raise exceptions other than
1090 1091 # AttributeError, which then crashes IPython.
1091 1092 break
1092 1093 else:
1093 1094 # If we finish the for loop (no break), we got all members
1094 1095 found = True
1095 1096 ospace = nsname
1096 1097 if ns == alias_ns:
1097 1098 isalias = True
1098 1099 break # namespace loop
1099 1100
1100 1101 # Try to see if it's magic
1101 1102 if not found:
1102 1103 if oname.startswith(ESC_MAGIC):
1103 1104 oname = oname[1:]
1104 1105 obj = getattr(self,'magic_'+oname,None)
1105 1106 if obj is not None:
1106 1107 found = True
1107 1108 ospace = 'IPython internal'
1108 1109 ismagic = True
1109 1110
1110 1111 # Last try: special-case some literals like '', [], {}, etc:
1111 1112 if not found and oname_head in ["''",'""','[]','{}','()']:
1112 1113 obj = eval(oname_head)
1113 1114 found = True
1114 1115 ospace = 'Interactive'
1115 1116
1116 1117 return {'found':found, 'obj':obj, 'namespace':ospace,
1117 1118 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1118 1119
1119 1120 def _ofind_property(self, oname, info):
1120 1121 """Second part of object finding, to look for property details."""
1121 1122 if info.found:
1122 1123 # Get the docstring of the class property if it exists.
1123 1124 path = oname.split('.')
1124 1125 root = '.'.join(path[:-1])
1125 1126 if info.parent is not None:
1126 1127 try:
1127 1128 target = getattr(info.parent, '__class__')
1128 1129 # The object belongs to a class instance.
1129 1130 try:
1130 1131 target = getattr(target, path[-1])
1131 1132 # The class defines the object.
1132 1133 if isinstance(target, property):
1133 1134 oname = root + '.__class__.' + path[-1]
1134 1135 info = Struct(self._ofind(oname))
1135 1136 except AttributeError: pass
1136 1137 except AttributeError: pass
1137 1138
1138 1139 # We return either the new info or the unmodified input if the object
1139 1140 # hadn't been found
1140 1141 return info
1141 1142
1142 1143 def _object_find(self, oname, namespaces=None):
1143 1144 """Find an object and return a struct with info about it."""
1144 1145 inf = Struct(self._ofind(oname, namespaces))
1145 1146 return Struct(self._ofind_property(oname, inf))
1146 1147
1147 1148 def _inspect(self, meth, oname, namespaces=None, **kw):
1148 1149 """Generic interface to the inspector system.
1149 1150
1150 1151 This function is meant to be called by pdef, pdoc & friends."""
1151 1152 info = self._object_find(oname)
1152 1153 if info.found:
1153 1154 pmethod = getattr(self.inspector, meth)
1154 1155 formatter = format_screen if info.ismagic else None
1155 1156 if meth == 'pdoc':
1156 1157 pmethod(info.obj, oname, formatter)
1157 1158 elif meth == 'pinfo':
1158 1159 pmethod(info.obj, oname, formatter, info, **kw)
1159 1160 else:
1160 1161 pmethod(info.obj, oname)
1161 1162 else:
1162 1163 print 'Object `%s` not found.' % oname
1163 1164 return 'not found' # so callers can take other action
1164 1165
1165 1166 def object_inspect(self, oname):
1166 1167 info = self._object_find(oname)
1167 1168 if info.found:
1168 1169 return self.inspector.info(info.obj, info=info)
1169 1170 else:
1170 1171 return oinspect.mk_object_info({'found' : False})
1171 1172
1172 1173 #-------------------------------------------------------------------------
1173 1174 # Things related to history management
1174 1175 #-------------------------------------------------------------------------
1175 1176
1176 1177 def init_history(self):
1177 1178 # List of input with multi-line handling.
1178 1179 self.input_hist = InputList()
1179 1180 # This one will hold the 'raw' input history, without any
1180 1181 # pre-processing. This will allow users to retrieve the input just as
1181 1182 # it was exactly typed in by the user, with %hist -r.
1182 1183 self.input_hist_raw = InputList()
1183 1184
1184 1185 # list of visited directories
1185 1186 try:
1186 1187 self.dir_hist = [os.getcwd()]
1187 1188 except OSError:
1188 1189 self.dir_hist = []
1189 1190
1190 1191 # dict of output history
1191 1192 self.output_hist = {}
1192 1193
1193 1194 # Now the history file
1194 1195 if self.profile:
1195 1196 histfname = 'history-%s' % self.profile
1196 1197 else:
1197 1198 histfname = 'history'
1198 1199 self.histfile = os.path.join(self.ipython_dir, histfname)
1199 1200
1200 1201 # Fill the history zero entry, user counter starts at 1
1201 1202 self.input_hist.append('\n')
1202 1203 self.input_hist_raw.append('\n')
1203 1204
1204 1205 def init_shadow_hist(self):
1205 1206 try:
1206 1207 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1207 1208 except exceptions.UnicodeDecodeError:
1208 1209 print "Your ipython_dir can't be decoded to unicode!"
1209 1210 print "Please set HOME environment variable to something that"
1210 1211 print r"only has ASCII characters, e.g. c:\home"
1211 1212 print "Now it is", self.ipython_dir
1212 1213 sys.exit()
1213 1214 self.shadowhist = ipcorehist.ShadowHist(self.db)
1214 1215
1215 1216 def savehist(self):
1216 1217 """Save input history to a file (via readline library)."""
1217 1218
1218 1219 try:
1219 1220 self.readline.write_history_file(self.histfile)
1220 1221 except:
1221 1222 print 'Unable to save IPython command history to file: ' + \
1222 1223 `self.histfile`
1223 1224
1224 1225 def reloadhist(self):
1225 1226 """Reload the input history from disk file."""
1226 1227
1227 1228 try:
1228 1229 self.readline.clear_history()
1229 1230 self.readline.read_history_file(self.shell.histfile)
1230 1231 except AttributeError:
1231 1232 pass
1232 1233
1233 1234 def history_saving_wrapper(self, func):
1234 1235 """ Wrap func for readline history saving
1235 1236
1236 1237 Convert func into callable that saves & restores
1237 1238 history around the call """
1238 1239
1239 1240 if self.has_readline:
1240 1241 from IPython.utils import rlineimpl as readline
1241 1242 else:
1242 1243 return func
1243 1244
1244 1245 def wrapper():
1245 1246 self.savehist()
1246 1247 try:
1247 1248 func()
1248 1249 finally:
1249 1250 readline.read_history_file(self.histfile)
1250 1251 return wrapper
1251 1252
1252 1253 def get_history(self, index=None, raw=False, output=True):
1253 1254 """Get the history list.
1254 1255
1255 1256 Get the input and output history.
1256 1257
1257 1258 Parameters
1258 1259 ----------
1259 1260 index : n or (n1, n2) or None
1260 1261 If n, then the last entries. If a tuple, then all in
1261 1262 range(n1, n2). If None, then all entries. Raises IndexError if
1262 1263 the format of index is incorrect.
1263 1264 raw : bool
1264 1265 If True, return the raw input.
1265 1266 output : bool
1266 1267 If True, then return the output as well.
1267 1268
1268 1269 Returns
1269 1270 -------
1270 1271 If output is True, then return a dict of tuples, keyed by the prompt
1271 1272 numbers and with values of (input, output). If output is False, then
1272 1273 a dict, keyed by the prompt number with the values of input. Raises
1273 1274 IndexError if no history is found.
1274 1275 """
1275 1276 if raw:
1276 1277 input_hist = self.input_hist_raw
1277 1278 else:
1278 1279 input_hist = self.input_hist
1279 1280 if output:
1280 1281 output_hist = self.user_ns['Out']
1281 1282 n = len(input_hist)
1282 1283 if index is None:
1283 1284 start=0; stop=n
1284 1285 elif isinstance(index, int):
1285 1286 start=n-index; stop=n
1286 1287 elif isinstance(index, tuple) and len(index) == 2:
1287 1288 start=index[0]; stop=index[1]
1288 1289 else:
1289 raise IndexError('Not a valid index for the input history: %r' % index)
1290 raise IndexError('Not a valid index for the input history: %r'
1291 % index)
1290 1292 hist = {}
1291 1293 for i in range(start, stop):
1292 1294 if output:
1293 1295 hist[i] = (input_hist[i], output_hist.get(i))
1294 1296 else:
1295 1297 hist[i] = input_hist[i]
1296 1298 if len(hist)==0:
1297 1299 raise IndexError('No history for range of indices: %r' % index)
1298 1300 return hist
1299 1301
1300 1302 #-------------------------------------------------------------------------
1301 1303 # Things related to exception handling and tracebacks (not debugging)
1302 1304 #-------------------------------------------------------------------------
1303 1305
1304 1306 def init_traceback_handlers(self, custom_exceptions):
1305 1307 # Syntax error handler.
1306 1308 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1307 1309
1308 1310 # The interactive one is initialized with an offset, meaning we always
1309 1311 # want to remove the topmost item in the traceback, which is our own
1310 1312 # internal code. Valid modes: ['Plain','Context','Verbose']
1311 1313 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1312 1314 color_scheme='NoColor',
1313 1315 tb_offset = 1)
1314 1316
1315 1317 # The instance will store a pointer to the system-wide exception hook,
1316 1318 # so that runtime code (such as magics) can access it. This is because
1317 1319 # during the read-eval loop, it may get temporarily overwritten.
1318 1320 self.sys_excepthook = sys.excepthook
1319 1321
1320 1322 # and add any custom exception handlers the user may have specified
1321 1323 self.set_custom_exc(*custom_exceptions)
1322 1324
1323 1325 # Set the exception mode
1324 1326 self.InteractiveTB.set_mode(mode=self.xmode)
1325 1327
1326 1328 def set_custom_exc(self, exc_tuple, handler):
1327 1329 """set_custom_exc(exc_tuple,handler)
1328 1330
1329 1331 Set a custom exception handler, which will be called if any of the
1330 1332 exceptions in exc_tuple occur in the mainloop (specifically, in the
1331 1333 runcode() method.
1332 1334
1333 1335 Inputs:
1334 1336
1335 1337 - exc_tuple: a *tuple* of valid exceptions to call the defined
1336 1338 handler for. It is very important that you use a tuple, and NOT A
1337 1339 LIST here, because of the way Python's except statement works. If
1338 1340 you only want to trap a single exception, use a singleton tuple:
1339 1341
1340 1342 exc_tuple == (MyCustomException,)
1341 1343
1342 1344 - handler: this must be defined as a function with the following
1343 1345 basic interface::
1344 1346
1345 1347 def my_handler(self, etype, value, tb, tb_offset=None)
1346 1348 ...
1347 1349 # The return value must be
1348 1350 return structured_traceback
1349 1351
1350 1352 This will be made into an instance method (via new.instancemethod)
1351 1353 of IPython itself, and it will be called if any of the exceptions
1352 1354 listed in the exc_tuple are caught. If the handler is None, an
1353 1355 internal basic one is used, which just prints basic info.
1354 1356
1355 1357 WARNING: by putting in your own exception handler into IPython's main
1356 1358 execution loop, you run a very good chance of nasty crashes. This
1357 1359 facility should only be used if you really know what you are doing."""
1358 1360
1359 1361 assert type(exc_tuple)==type(()) , \
1360 1362 "The custom exceptions must be given AS A TUPLE."
1361 1363
1362 1364 def dummy_handler(self,etype,value,tb):
1363 1365 print '*** Simple custom exception handler ***'
1364 1366 print 'Exception type :',etype
1365 1367 print 'Exception value:',value
1366 1368 print 'Traceback :',tb
1367 1369 print 'Source code :','\n'.join(self.buffer)
1368 1370
1369 1371 if handler is None: handler = dummy_handler
1370 1372
1371 1373 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1372 1374 self.custom_exceptions = exc_tuple
1373 1375
1374 1376 def excepthook(self, etype, value, tb):
1375 1377 """One more defense for GUI apps that call sys.excepthook.
1376 1378
1377 1379 GUI frameworks like wxPython trap exceptions and call
1378 1380 sys.excepthook themselves. I guess this is a feature that
1379 1381 enables them to keep running after exceptions that would
1380 1382 otherwise kill their mainloop. This is a bother for IPython
1381 1383 which excepts to catch all of the program exceptions with a try:
1382 1384 except: statement.
1383 1385
1384 1386 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1385 1387 any app directly invokes sys.excepthook, it will look to the user like
1386 1388 IPython crashed. In order to work around this, we can disable the
1387 1389 CrashHandler and replace it with this excepthook instead, which prints a
1388 1390 regular traceback using our InteractiveTB. In this fashion, apps which
1389 1391 call sys.excepthook will generate a regular-looking exception from
1390 1392 IPython, and the CrashHandler will only be triggered by real IPython
1391 1393 crashes.
1392 1394
1393 1395 This hook should be used sparingly, only in places which are not likely
1394 1396 to be true IPython errors.
1395 1397 """
1396 1398 self.showtraceback((etype,value,tb),tb_offset=0)
1397 1399
1398 1400 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1399 1401 exception_only=False):
1400 1402 """Display the exception that just occurred.
1401 1403
1402 1404 If nothing is known about the exception, this is the method which
1403 1405 should be used throughout the code for presenting user tracebacks,
1404 1406 rather than directly invoking the InteractiveTB object.
1405 1407
1406 1408 A specific showsyntaxerror() also exists, but this method can take
1407 1409 care of calling it if needed, so unless you are explicitly catching a
1408 1410 SyntaxError exception, don't try to analyze the stack manually and
1409 1411 simply call this method."""
1410 1412
1411 1413 try:
1412 1414 if exc_tuple is None:
1413 1415 etype, value, tb = sys.exc_info()
1414 1416 else:
1415 1417 etype, value, tb = exc_tuple
1416 1418
1417 1419 if etype is None:
1418 1420 if hasattr(sys, 'last_type'):
1419 1421 etype, value, tb = sys.last_type, sys.last_value, \
1420 1422 sys.last_traceback
1421 1423 else:
1422 1424 self.write_err('No traceback available to show.\n')
1423 1425 return
1424 1426
1425 1427 if etype is SyntaxError:
1426 1428 # Though this won't be called by syntax errors in the input
1427 1429 # line, there may be SyntaxError cases whith imported code.
1428 1430 self.showsyntaxerror(filename)
1429 1431 elif etype is UsageError:
1430 1432 print "UsageError:", value
1431 1433 else:
1432 1434 # WARNING: these variables are somewhat deprecated and not
1433 1435 # necessarily safe to use in a threaded environment, but tools
1434 1436 # like pdb depend on their existence, so let's set them. If we
1435 1437 # find problems in the field, we'll need to revisit their use.
1436 1438 sys.last_type = etype
1437 1439 sys.last_value = value
1438 1440 sys.last_traceback = tb
1439 1441
1440 1442 if etype in self.custom_exceptions:
1441 1443 # FIXME: Old custom traceback objects may just return a
1442 1444 # string, in that case we just put it into a list
1443 1445 stb = self.CustomTB(etype, value, tb, tb_offset)
1444 1446 if isinstance(ctb, basestring):
1445 1447 stb = [stb]
1446 1448 else:
1447 1449 if exception_only:
1448 1450 stb = ['An exception has occurred, use %tb to see '
1449 1451 'the full traceback.\n']
1450 1452 stb.extend(self.InteractiveTB.get_exception_only(etype,
1451 1453 value))
1452 1454 else:
1453 1455 stb = self.InteractiveTB.structured_traceback(etype,
1454 1456 value, tb, tb_offset=tb_offset)
1455 1457 # FIXME: the pdb calling should be done by us, not by
1456 1458 # the code computing the traceback.
1457 1459 if self.InteractiveTB.call_pdb:
1458 1460 # pdb mucks up readline, fix it back
1459 1461 self.set_readline_completer()
1460 1462
1461 1463 # Actually show the traceback
1462 1464 self._showtraceback(etype, value, stb)
1463 1465
1464 1466 except KeyboardInterrupt:
1465 1467 self.write_err("\nKeyboardInterrupt\n")
1466 1468
1467 1469 def _showtraceback(self, etype, evalue, stb):
1468 1470 """Actually show a traceback.
1469 1471
1470 1472 Subclasses may override this method to put the traceback on a different
1471 1473 place, like a side channel.
1472 1474 """
1473 1475 # FIXME: this should use the proper write channels, but our test suite
1474 1476 # relies on it coming out of stdout...
1475 1477 print >> sys.stdout, self.InteractiveTB.stb2text(stb)
1476 1478
1477 1479 def showsyntaxerror(self, filename=None):
1478 1480 """Display the syntax error that just occurred.
1479 1481
1480 1482 This doesn't display a stack trace because there isn't one.
1481 1483
1482 1484 If a filename is given, it is stuffed in the exception instead
1483 1485 of what was there before (because Python's parser always uses
1484 1486 "<string>" when reading from a string).
1485 1487 """
1486 1488 etype, value, last_traceback = sys.exc_info()
1487 1489
1488 1490 # See note about these variables in showtraceback() above
1489 1491 sys.last_type = etype
1490 1492 sys.last_value = value
1491 1493 sys.last_traceback = last_traceback
1492 1494
1493 1495 if filename and etype is SyntaxError:
1494 1496 # Work hard to stuff the correct filename in the exception
1495 1497 try:
1496 1498 msg, (dummy_filename, lineno, offset, line) = value
1497 1499 except:
1498 1500 # Not the format we expect; leave it alone
1499 1501 pass
1500 1502 else:
1501 1503 # Stuff in the right filename
1502 1504 try:
1503 1505 # Assume SyntaxError is a class exception
1504 1506 value = SyntaxError(msg, (filename, lineno, offset, line))
1505 1507 except:
1506 1508 # If that failed, assume SyntaxError is a string
1507 1509 value = msg, (filename, lineno, offset, line)
1508 1510 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1509 1511 self._showtraceback(etype, value, stb)
1510 1512
1511 1513 #-------------------------------------------------------------------------
1512 1514 # Things related to tab completion
1513 1515 #-------------------------------------------------------------------------
1514 1516
1515 1517 def complete(self, text, line=None, cursor_pos=None):
1516 1518 """Return the completed text and a list of completions.
1517 1519
1518 1520 Parameters
1519 1521 ----------
1520 1522
1521 1523 text : string
1522 1524 A string of text to be completed on. It can be given as empty and
1523 1525 instead a line/position pair are given. In this case, the
1524 1526 completer itself will split the line like readline does.
1525 1527
1526 1528 line : string, optional
1527 1529 The complete line that text is part of.
1528 1530
1529 1531 cursor_pos : int, optional
1530 1532 The position of the cursor on the input line.
1531 1533
1532 1534 Returns
1533 1535 -------
1534 1536 text : string
1535 1537 The actual text that was completed.
1536 1538
1537 1539 matches : list
1538 1540 A sorted list with all possible completions.
1539 1541
1540 1542 The optional arguments allow the completion to take more context into
1541 1543 account, and are part of the low-level completion API.
1542 1544
1543 1545 This is a wrapper around the completion mechanism, similar to what
1544 1546 readline does at the command line when the TAB key is hit. By
1545 1547 exposing it as a method, it can be used by other non-readline
1546 1548 environments (such as GUIs) for text completion.
1547 1549
1548 1550 Simple usage example:
1549 1551
1550 1552 In [1]: x = 'hello'
1551 1553
1552 1554 In [2]: _ip.complete('x.l')
1553 1555 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1554 1556 """
1555 1557
1556 1558 # Inject names into __builtin__ so we can complete on the added names.
1557 1559 with self.builtin_trap:
1558 1560 return self.Completer.complete(text, line, cursor_pos)
1559 1561
1560 1562 def set_custom_completer(self, completer, pos=0):
1561 1563 """Adds a new custom completer function.
1562 1564
1563 1565 The position argument (defaults to 0) is the index in the completers
1564 1566 list where you want the completer to be inserted."""
1565 1567
1566 1568 newcomp = new.instancemethod(completer,self.Completer,
1567 1569 self.Completer.__class__)
1568 1570 self.Completer.matchers.insert(pos,newcomp)
1569 1571
1570 1572 def set_readline_completer(self):
1571 1573 """Reset readline's completer to be our own."""
1572 1574 self.readline.set_completer(self.Completer.rlcomplete)
1573 1575
1574 1576 def set_completer_frame(self, frame=None):
1575 1577 """Set the frame of the completer."""
1576 1578 if frame:
1577 1579 self.Completer.namespace = frame.f_locals
1578 1580 self.Completer.global_namespace = frame.f_globals
1579 1581 else:
1580 1582 self.Completer.namespace = self.user_ns
1581 1583 self.Completer.global_namespace = self.user_global_ns
1582 1584
1583 1585 #-------------------------------------------------------------------------
1584 1586 # Things related to readline
1585 1587 #-------------------------------------------------------------------------
1586 1588
1587 1589 def init_readline(self):
1588 1590 """Command history completion/saving/reloading."""
1589 1591
1590 1592 if self.readline_use:
1591 1593 import IPython.utils.rlineimpl as readline
1592 1594
1593 1595 self.rl_next_input = None
1594 1596 self.rl_do_indent = False
1595 1597
1596 1598 if not self.readline_use or not readline.have_readline:
1597 1599 self.has_readline = False
1598 1600 self.readline = None
1599 1601 # Set a number of methods that depend on readline to be no-op
1600 1602 self.savehist = no_op
1601 1603 self.reloadhist = no_op
1602 1604 self.set_readline_completer = no_op
1603 1605 self.set_custom_completer = no_op
1604 1606 self.set_completer_frame = no_op
1605 1607 warn('Readline services not available or not loaded.')
1606 1608 else:
1607 1609 self.has_readline = True
1608 1610 self.readline = readline
1609 1611 sys.modules['readline'] = readline
1610 1612
1611 1613 from IPython.core.completer import IPCompleter
1612 1614 self.Completer = IPCompleter(self,
1613 1615 self.user_ns,
1614 1616 self.user_global_ns,
1615 1617 self.readline_omit__names,
1616 1618 self.alias_manager.alias_table)
1617 1619 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1618 1620 self.strdispatchers['complete_command'] = sdisp
1619 1621 self.Completer.custom_completers = sdisp
1620 1622
1621 1623 # Platform-specific configuration
1622 1624 if os.name == 'nt':
1623 1625 # FIXME - check with Frederick to see if we can harmonize
1624 1626 # naming conventions with pyreadline to avoid this
1625 1627 # platform-dependent check
1626 1628 self.readline_startup_hook = readline.set_pre_input_hook
1627 1629 else:
1628 1630 self.readline_startup_hook = readline.set_startup_hook
1629 1631
1630 1632 # Load user's initrc file (readline config)
1631 1633 # Or if libedit is used, load editrc.
1632 1634 inputrc_name = os.environ.get('INPUTRC')
1633 1635 if inputrc_name is None:
1634 1636 home_dir = get_home_dir()
1635 1637 if home_dir is not None:
1636 1638 inputrc_name = '.inputrc'
1637 1639 if readline.uses_libedit:
1638 1640 inputrc_name = '.editrc'
1639 1641 inputrc_name = os.path.join(home_dir, inputrc_name)
1640 1642 if os.path.isfile(inputrc_name):
1641 1643 try:
1642 1644 readline.read_init_file(inputrc_name)
1643 1645 except:
1644 1646 warn('Problems reading readline initialization file <%s>'
1645 1647 % inputrc_name)
1646 1648
1647 1649 self.set_readline_completer()
1648 1650
1649 1651 # Configure readline according to user's prefs
1650 1652 # This is only done if GNU readline is being used. If libedit
1651 1653 # is being used (as on Leopard) the readline config is
1652 1654 # not run as the syntax for libedit is different.
1653 1655 if not readline.uses_libedit:
1654 1656 for rlcommand in self.readline_parse_and_bind:
1655 1657 #print "loading rl:",rlcommand # dbg
1656 1658 readline.parse_and_bind(rlcommand)
1657 1659
1658 1660 # Remove some chars from the delimiters list. If we encounter
1659 1661 # unicode chars, discard them.
1660 1662 delims = readline.get_completer_delims().encode("ascii", "ignore")
1661 1663 delims = delims.translate(string._idmap,
1662 1664 self.readline_remove_delims)
1663 1665 readline.set_completer_delims(delims)
1664 1666 # otherwise we end up with a monster history after a while:
1665 1667 readline.set_history_length(1000)
1666 1668 try:
1667 1669 #print '*** Reading readline history' # dbg
1668 1670 readline.read_history_file(self.histfile)
1669 1671 except IOError:
1670 1672 pass # It doesn't exist yet.
1671 1673
1672 1674 # If we have readline, we want our history saved upon ipython
1673 1675 # exiting.
1674 1676 atexit.register(self.savehist)
1675 1677
1676 1678 # Configure auto-indent for all platforms
1677 1679 self.set_autoindent(self.autoindent)
1678 1680
1679 1681 def set_next_input(self, s):
1680 1682 """ Sets the 'default' input string for the next command line.
1681 1683
1682 1684 Requires readline.
1683 1685
1684 1686 Example:
1685 1687
1686 1688 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1687 1689 [D:\ipython]|2> Hello Word_ # cursor is here
1688 1690 """
1689 1691
1690 1692 self.rl_next_input = s
1691 1693
1692 1694 # Maybe move this to the terminal subclass?
1693 1695 def pre_readline(self):
1694 1696 """readline hook to be used at the start of each line.
1695 1697
1696 1698 Currently it handles auto-indent only."""
1697 1699
1698 1700 if self.rl_do_indent:
1699 1701 self.readline.insert_text(self._indent_current_str())
1700 1702 if self.rl_next_input is not None:
1701 1703 self.readline.insert_text(self.rl_next_input)
1702 1704 self.rl_next_input = None
1703 1705
1704 1706 def _indent_current_str(self):
1705 1707 """return the current level of indentation as a string"""
1706 1708 return self.indent_current_nsp * ' '
1707 1709
1708 1710 #-------------------------------------------------------------------------
1709 1711 # Things related to magics
1710 1712 #-------------------------------------------------------------------------
1711 1713
1712 1714 def init_magics(self):
1713 1715 # FIXME: Move the color initialization to the DisplayHook, which
1714 1716 # should be split into a prompt manager and displayhook. We probably
1715 1717 # even need a centralize colors management object.
1716 1718 self.magic_colors(self.colors)
1717 1719 # History was moved to a separate module
1718 1720 from . import history
1719 1721 history.init_ipython(self)
1720 1722
1721 1723 def magic(self,arg_s):
1722 1724 """Call a magic function by name.
1723 1725
1724 Input: a string containing the name of the magic function to call and any
1725 additional arguments to be passed to the magic.
1726 Input: a string containing the name of the magic function to call and
1727 any additional arguments to be passed to the magic.
1726 1728
1727 1729 magic('name -opt foo bar') is equivalent to typing at the ipython
1728 1730 prompt:
1729 1731
1730 1732 In[1]: %name -opt foo bar
1731 1733
1732 1734 To call a magic without arguments, simply use magic('name').
1733 1735
1734 1736 This provides a proper Python function to call IPython's magics in any
1735 1737 valid Python code you can type at the interpreter, including loops and
1736 1738 compound statements.
1737 1739 """
1738 1740 args = arg_s.split(' ',1)
1739 1741 magic_name = args[0]
1740 1742 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1741 1743
1742 1744 try:
1743 1745 magic_args = args[1]
1744 1746 except IndexError:
1745 1747 magic_args = ''
1746 1748 fn = getattr(self,'magic_'+magic_name,None)
1747 1749 if fn is None:
1748 1750 error("Magic function `%s` not found." % magic_name)
1749 1751 else:
1750 1752 magic_args = self.var_expand(magic_args,1)
1751 1753 with nested(self.builtin_trap,):
1752 1754 result = fn(magic_args)
1753 1755 return result
1754 1756
1755 1757 def define_magic(self, magicname, func):
1756 1758 """Expose own function as magic function for ipython
1757 1759
1758 1760 def foo_impl(self,parameter_s=''):
1759 1761 'My very own magic!. (Use docstrings, IPython reads them).'
1760 1762 print 'Magic function. Passed parameter is between < >:'
1761 1763 print '<%s>' % parameter_s
1762 1764 print 'The self object is:',self
1763 1765
1764 1766 self.define_magic('foo',foo_impl)
1765 1767 """
1766 1768
1767 1769 import new
1768 1770 im = new.instancemethod(func,self, self.__class__)
1769 1771 old = getattr(self, "magic_" + magicname, None)
1770 1772 setattr(self, "magic_" + magicname, im)
1771 1773 return old
1772 1774
1773 1775 #-------------------------------------------------------------------------
1774 1776 # Things related to macros
1775 1777 #-------------------------------------------------------------------------
1776 1778
1777 1779 def define_macro(self, name, themacro):
1778 1780 """Define a new macro
1779 1781
1780 1782 Parameters
1781 1783 ----------
1782 1784 name : str
1783 1785 The name of the macro.
1784 1786 themacro : str or Macro
1785 1787 The action to do upon invoking the macro. If a string, a new
1786 1788 Macro object is created by passing the string to it.
1787 1789 """
1788 1790
1789 1791 from IPython.core import macro
1790 1792
1791 1793 if isinstance(themacro, basestring):
1792 1794 themacro = macro.Macro(themacro)
1793 1795 if not isinstance(themacro, macro.Macro):
1794 1796 raise ValueError('A macro must be a string or a Macro instance.')
1795 1797 self.user_ns[name] = themacro
1796 1798
1797 1799 #-------------------------------------------------------------------------
1798 1800 # Things related to the running of system commands
1799 1801 #-------------------------------------------------------------------------
1800 1802
1801 1803 def system(self, cmd):
1802 1804 """Call the given cmd in a subprocess."""
1803 1805 # We do not support backgrounding processes because we either use
1804 1806 # pexpect or pipes to read from. Users can always just call
1805 1807 # os.system() if they really want a background process.
1806 1808 if cmd.endswith('&'):
1807 1809 raise OSError("Background processes not supported.")
1808 1810
1809 1811 return system(self.var_expand(cmd, depth=2))
1810 1812
1811 1813 def getoutput(self, cmd):
1812 1814 """Get output (possibly including stderr) from a subprocess."""
1813 1815 if cmd.endswith('&'):
1814 1816 raise OSError("Background processes not supported.")
1815 1817 return getoutput(self.var_expand(cmd, depth=2))
1816 1818
1817 1819 #-------------------------------------------------------------------------
1818 1820 # Things related to aliases
1819 1821 #-------------------------------------------------------------------------
1820 1822
1821 1823 def init_alias(self):
1822 1824 self.alias_manager = AliasManager(shell=self, config=self.config)
1823 1825 self.ns_table['alias'] = self.alias_manager.alias_table,
1824 1826
1825 1827 #-------------------------------------------------------------------------
1826 1828 # Things related to extensions and plugins
1827 1829 #-------------------------------------------------------------------------
1828 1830
1829 1831 def init_extension_manager(self):
1830 1832 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1831 1833
1832 1834 def init_plugin_manager(self):
1833 1835 self.plugin_manager = PluginManager(config=self.config)
1834 1836
1835 1837 #-------------------------------------------------------------------------
1836 1838 # Things related to payloads
1837 1839 #-------------------------------------------------------------------------
1838 1840
1839 1841 def init_payload(self):
1840 1842 self.payload_manager = PayloadManager(config=self.config)
1841 1843
1842 1844 #-------------------------------------------------------------------------
1843 1845 # Things related to the prefilter
1844 1846 #-------------------------------------------------------------------------
1845 1847
1846 1848 def init_prefilter(self):
1847 1849 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1848 1850 # Ultimately this will be refactored in the new interpreter code, but
1849 1851 # for now, we should expose the main prefilter method (there's legacy
1850 1852 # code out there that may rely on this).
1851 1853 self.prefilter = self.prefilter_manager.prefilter_lines
1852 1854
1853 1855
1854 1856 def auto_rewrite_input(self, cmd):
1855 1857 """Print to the screen the rewritten form of the user's command.
1856 1858
1857 1859 This shows visual feedback by rewriting input lines that cause
1858 1860 automatic calling to kick in, like::
1859 1861
1860 1862 /f x
1861 1863
1862 1864 into::
1863 1865
1864 1866 ------> f(x)
1865 1867
1866 1868 after the user's input prompt. This helps the user understand that the
1867 1869 input line was transformed automatically by IPython.
1868 1870 """
1869 1871 rw = self.displayhook.prompt1.auto_rewrite() + cmd
1870 1872
1871 1873 try:
1872 1874 # plain ascii works better w/ pyreadline, on some machines, so
1873 1875 # we use it and only print uncolored rewrite if we have unicode
1874 1876 rw = str(rw)
1875 1877 print >> IPython.utils.io.Term.cout, rw
1876 1878 except UnicodeEncodeError:
1877 1879 print "------> " + cmd
1878 1880
1879 1881 #-------------------------------------------------------------------------
1880 1882 # Things related to extracting values/expressions from kernel and user_ns
1881 1883 #-------------------------------------------------------------------------
1882 1884
1883 1885 def _simple_error(self):
1884 1886 etype, value = sys.exc_info()[:2]
1885 1887 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1886 1888
1887 1889 def get_user_variables(self, names):
1888 1890 """Get a list of variable names from the user's namespace.
1889 1891
1890 1892 The return value is a dict with the repr() of each value.
1891 1893 """
1892 1894 out = {}
1893 1895 user_ns = self.user_ns
1894 1896 for varname in names:
1895 1897 try:
1896 1898 value = repr(user_ns[varname])
1897 1899 except:
1898 1900 value = self._simple_error()
1899 1901 out[varname] = value
1900 1902 return out
1901 1903
1902 1904 def eval_expressions(self, expressions):
1903 1905 """Evaluate a dict of expressions in the user's namespace.
1904 1906
1905 1907 The return value is a dict with the repr() of each value.
1906 1908 """
1907 1909 out = {}
1908 1910 user_ns = self.user_ns
1909 1911 global_ns = self.user_global_ns
1910 1912 for key, expr in expressions.iteritems():
1911 1913 try:
1912 1914 value = repr(eval(expr, global_ns, user_ns))
1913 1915 except:
1914 1916 value = self._simple_error()
1915 1917 out[key] = value
1916 1918 return out
1917 1919
1918 1920 #-------------------------------------------------------------------------
1919 1921 # Things related to the running of code
1920 1922 #-------------------------------------------------------------------------
1921 1923
1922 1924 def ex(self, cmd):
1923 1925 """Execute a normal python statement in user namespace."""
1924 1926 with nested(self.builtin_trap,):
1925 1927 exec cmd in self.user_global_ns, self.user_ns
1926 1928
1927 1929 def ev(self, expr):
1928 1930 """Evaluate python expression expr in user namespace.
1929 1931
1930 1932 Returns the result of evaluation
1931 1933 """
1932 1934 with nested(self.builtin_trap,):
1933 1935 return eval(expr, self.user_global_ns, self.user_ns)
1934 1936
1935 1937 def safe_execfile(self, fname, *where, **kw):
1936 1938 """A safe version of the builtin execfile().
1937 1939
1938 1940 This version will never throw an exception, but instead print
1939 1941 helpful error messages to the screen. This only works on pure
1940 1942 Python files with the .py extension.
1941 1943
1942 1944 Parameters
1943 1945 ----------
1944 1946 fname : string
1945 1947 The name of the file to be executed.
1946 1948 where : tuple
1947 1949 One or two namespaces, passed to execfile() as (globals,locals).
1948 1950 If only one is given, it is passed as both.
1949 1951 exit_ignore : bool (False)
1950 1952 If True, then silence SystemExit for non-zero status (it is always
1951 1953 silenced for zero status, as it is so common).
1952 1954 """
1953 1955 kw.setdefault('exit_ignore', False)
1954 1956
1955 1957 fname = os.path.abspath(os.path.expanduser(fname))
1956 1958
1957 1959 # Make sure we have a .py file
1958 1960 if not fname.endswith('.py'):
1959 1961 warn('File must end with .py to be run using execfile: <%s>' % fname)
1960 1962
1961 1963 # Make sure we can open the file
1962 1964 try:
1963 1965 with open(fname) as thefile:
1964 1966 pass
1965 1967 except:
1966 1968 warn('Could not open file <%s> for safe execution.' % fname)
1967 1969 return
1968 1970
1969 1971 # Find things also in current directory. This is needed to mimic the
1970 1972 # behavior of running a script from the system command line, where
1971 1973 # Python inserts the script's directory into sys.path
1972 1974 dname = os.path.dirname(fname)
1973 1975
1974 1976 with prepended_to_syspath(dname):
1975 1977 try:
1976 1978 execfile(fname,*where)
1977 1979 except SystemExit, status:
1978 1980 # If the call was made with 0 or None exit status (sys.exit(0)
1979 1981 # or sys.exit() ), don't bother showing a traceback, as both of
1980 1982 # these are considered normal by the OS:
1981 1983 # > python -c'import sys;sys.exit(0)'; echo $?
1982 1984 # 0
1983 1985 # > python -c'import sys;sys.exit()'; echo $?
1984 1986 # 0
1985 1987 # For other exit status, we show the exception unless
1986 1988 # explicitly silenced, but only in short form.
1987 1989 if status.code not in (0, None) and not kw['exit_ignore']:
1988 1990 self.showtraceback(exception_only=True)
1989 1991 except:
1990 1992 self.showtraceback()
1991 1993
1992 1994 def safe_execfile_ipy(self, fname):
1993 1995 """Like safe_execfile, but for .ipy files with IPython syntax.
1994 1996
1995 1997 Parameters
1996 1998 ----------
1997 1999 fname : str
1998 2000 The name of the file to execute. The filename must have a
1999 2001 .ipy extension.
2000 2002 """
2001 2003 fname = os.path.abspath(os.path.expanduser(fname))
2002 2004
2003 2005 # Make sure we have a .py file
2004 2006 if not fname.endswith('.ipy'):
2005 2007 warn('File must end with .py to be run using execfile: <%s>' % fname)
2006 2008
2007 2009 # Make sure we can open the file
2008 2010 try:
2009 2011 with open(fname) as thefile:
2010 2012 pass
2011 2013 except:
2012 2014 warn('Could not open file <%s> for safe execution.' % fname)
2013 2015 return
2014 2016
2015 2017 # Find things also in current directory. This is needed to mimic the
2016 2018 # behavior of running a script from the system command line, where
2017 2019 # Python inserts the script's directory into sys.path
2018 2020 dname = os.path.dirname(fname)
2019 2021
2020 2022 with prepended_to_syspath(dname):
2021 2023 try:
2022 2024 with open(fname) as thefile:
2023 2025 script = thefile.read()
2024 2026 # self.runlines currently captures all exceptions
2025 2027 # raise in user code. It would be nice if there were
2026 2028 # versions of runlines, execfile that did raise, so
2027 2029 # we could catch the errors.
2028 2030 self.runlines(script, clean=True)
2029 2031 except:
2030 2032 self.showtraceback()
2031 2033 warn('Unknown failure executing file: <%s>' % fname)
2032 2034
2033 2035 def runlines(self, lines, clean=False):
2034 2036 """Run a string of one or more lines of source.
2035 2037
2036 2038 This method is capable of running a string containing multiple source
2037 2039 lines, as if they had been entered at the IPython prompt. Since it
2038 2040 exposes IPython's processing machinery, the given strings can contain
2039 2041 magic calls (%magic), special shell access (!cmd), etc.
2040 2042 """
2041 2043
2042 2044 if isinstance(lines, (list, tuple)):
2043 2045 lines = '\n'.join(lines)
2044 2046
2045 2047 if clean:
2046 2048 lines = self._cleanup_ipy_script(lines)
2047 2049
2048 2050 # We must start with a clean buffer, in case this is run from an
2049 2051 # interactive IPython session (via a magic, for example).
2050 2052 self.resetbuffer()
2051 2053 lines = lines.splitlines()
2052 2054 more = 0
2053 2055 with nested(self.builtin_trap, self.display_trap):
2054 2056 for line in lines:
2055 # skip blank lines so we don't mess up the prompt counter, but do
2056 # NOT skip even a blank line if we are in a code block (more is
2057 # true)
2057 # skip blank lines so we don't mess up the prompt counter, but
2058 # do NOT skip even a blank line if we are in a code block (more
2059 # is true)
2058 2060
2059 2061 if line or more:
2060 2062 # push to raw history, so hist line numbers stay in sync
2061 2063 self.input_hist_raw.append(line + '\n')
2062 2064 prefiltered = self.prefilter_manager.prefilter_lines(line,
2063 2065 more)
2064 2066 more = self.push_line(prefiltered)
2065 2067 # IPython's runsource returns None if there was an error
2066 # compiling the code. This allows us to stop processing right
2067 # away, so the user gets the error message at the right place.
2068 # compiling the code. This allows us to stop processing
2069 # right away, so the user gets the error message at the
2070 # right place.
2068 2071 if more is None:
2069 2072 break
2070 2073 else:
2071 2074 self.input_hist_raw.append("\n")
2072 2075 # final newline in case the input didn't have it, so that the code
2073 2076 # actually does get executed
2074 2077 if more:
2075 2078 self.push_line('\n')
2076 2079
2077 2080 def runsource(self, source, filename='<input>', symbol='single'):
2078 2081 """Compile and run some source in the interpreter.
2079 2082
2080 2083 Arguments are as for compile_command().
2081 2084
2082 2085 One several things can happen:
2083 2086
2084 2087 1) The input is incorrect; compile_command() raised an
2085 2088 exception (SyntaxError or OverflowError). A syntax traceback
2086 2089 will be printed by calling the showsyntaxerror() method.
2087 2090
2088 2091 2) The input is incomplete, and more input is required;
2089 2092 compile_command() returned None. Nothing happens.
2090 2093
2091 2094 3) The input is complete; compile_command() returned a code
2092 2095 object. The code is executed by calling self.runcode() (which
2093 2096 also handles run-time exceptions, except for SystemExit).
2094 2097
2095 2098 The return value is:
2096 2099
2097 2100 - True in case 2
2098 2101
2099 2102 - False in the other cases, unless an exception is raised, where
2100 2103 None is returned instead. This can be used by external callers to
2101 2104 know whether to continue feeding input or not.
2102 2105
2103 2106 The return value can be used to decide whether to use sys.ps1 or
2104 2107 sys.ps2 to prompt the next line."""
2105 2108
2106 2109 # if the source code has leading blanks, add 'if 1:\n' to it
2107 2110 # this allows execution of indented pasted code. It is tempting
2108 2111 # to add '\n' at the end of source to run commands like ' a=1'
2109 2112 # directly, but this fails for more complicated scenarios
2110 2113 source=source.encode(self.stdin_encoding)
2111 2114 if source[:1] in [' ', '\t']:
2112 2115 source = 'if 1:\n%s' % source
2113 2116
2114 2117 try:
2115 2118 code = self.compile(source,filename,symbol)
2116 2119 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2117 2120 # Case 1
2118 2121 self.showsyntaxerror(filename)
2119 2122 return None
2120 2123
2121 2124 if code is None:
2122 2125 # Case 2
2123 2126 return True
2124 2127
2125 2128 # Case 3
2126 2129 # We store the code object so that threaded shells and
2127 2130 # custom exception handlers can access all this info if needed.
2128 2131 # The source corresponding to this can be obtained from the
2129 2132 # buffer attribute as '\n'.join(self.buffer).
2130 2133 self.code_to_run = code
2131 2134 # now actually execute the code object
2132 2135 if self.runcode(code) == 0:
2133 2136 return False
2134 2137 else:
2135 2138 return None
2136 2139
2137 2140 def runcode(self,code_obj):
2138 2141 """Execute a code object.
2139 2142
2140 2143 When an exception occurs, self.showtraceback() is called to display a
2141 2144 traceback.
2142 2145
2143 2146 Return value: a flag indicating whether the code to be run completed
2144 2147 successfully:
2145 2148
2146 2149 - 0: successful execution.
2147 2150 - 1: an error occurred.
2148 2151 """
2149 2152
2150 2153 # Set our own excepthook in case the user code tries to call it
2151 2154 # directly, so that the IPython crash handler doesn't get triggered
2152 2155 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2153 2156
2154 2157 # we save the original sys.excepthook in the instance, in case config
2155 2158 # code (such as magics) needs access to it.
2156 2159 self.sys_excepthook = old_excepthook
2157 2160 outflag = 1 # happens in more places, so it's easier as default
2158 2161 try:
2159 2162 try:
2160 2163 self.hooks.pre_runcode_hook()
2161 2164 #rprint('Running code') # dbg
2162 2165 exec code_obj in self.user_global_ns, self.user_ns
2163 2166 finally:
2164 2167 # Reset our crash handler in place
2165 2168 sys.excepthook = old_excepthook
2166 2169 except SystemExit:
2167 2170 self.resetbuffer()
2168 2171 self.showtraceback(exception_only=True)
2169 2172 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2170 2173 except self.custom_exceptions:
2171 2174 etype,value,tb = sys.exc_info()
2172 2175 self.CustomTB(etype,value,tb)
2173 2176 except:
2174 2177 self.showtraceback()
2175 2178 else:
2176 2179 outflag = 0
2177 2180 if softspace(sys.stdout, 0):
2178 2181 print
2179 2182 # Flush out code object which has been run (and source)
2180 2183 self.code_to_run = None
2181 2184 return outflag
2182 2185
2183 2186 def push_line(self, line):
2184 2187 """Push a line to the interpreter.
2185 2188
2186 2189 The line should not have a trailing newline; it may have
2187 2190 internal newlines. The line is appended to a buffer and the
2188 2191 interpreter's runsource() method is called with the
2189 2192 concatenated contents of the buffer as source. If this
2190 2193 indicates that the command was executed or invalid, the buffer
2191 2194 is reset; otherwise, the command is incomplete, and the buffer
2192 2195 is left as it was after the line was appended. The return
2193 2196 value is 1 if more input is required, 0 if the line was dealt
2194 2197 with in some way (this is the same as runsource()).
2195 2198 """
2196 2199
2197 2200 # autoindent management should be done here, and not in the
2198 2201 # interactive loop, since that one is only seen by keyboard input. We
2199 2202 # need this done correctly even for code run via runlines (which uses
2200 2203 # push).
2201 2204
2202 2205 #print 'push line: <%s>' % line # dbg
2203 2206 for subline in line.splitlines():
2204 2207 self._autoindent_update(subline)
2205 2208 self.buffer.append(line)
2206 2209 more = self.runsource('\n'.join(self.buffer), self.filename)
2207 2210 if not more:
2208 2211 self.resetbuffer()
2209 2212 return more
2210 2213
2211 2214 def resetbuffer(self):
2212 2215 """Reset the input buffer."""
2213 2216 self.buffer[:] = []
2214 2217
2215 2218 def _is_secondary_block_start(self, s):
2216 2219 if not s.endswith(':'):
2217 2220 return False
2218 2221 if (s.startswith('elif') or
2219 2222 s.startswith('else') or
2220 2223 s.startswith('except') or
2221 2224 s.startswith('finally')):
2222 2225 return True
2223 2226
2224 2227 def _cleanup_ipy_script(self, script):
2225 2228 """Make a script safe for self.runlines()
2226 2229
2227 2230 Currently, IPython is lines based, with blocks being detected by
2228 2231 empty lines. This is a problem for block based scripts that may
2229 2232 not have empty lines after blocks. This script adds those empty
2230 2233 lines to make scripts safe for running in the current line based
2231 2234 IPython.
2232 2235 """
2233 2236 res = []
2234 2237 lines = script.splitlines()
2235 2238 level = 0
2236 2239
2237 2240 for l in lines:
2238 2241 lstripped = l.lstrip()
2239 2242 stripped = l.strip()
2240 2243 if not stripped:
2241 2244 continue
2242 2245 newlevel = len(l) - len(lstripped)
2243 2246 if level > 0 and newlevel == 0 and \
2244 2247 not self._is_secondary_block_start(stripped):
2245 2248 # add empty line
2246 2249 res.append('')
2247 2250 res.append(l)
2248 2251 level = newlevel
2249 2252
2250 2253 return '\n'.join(res) + '\n'
2251 2254
2252 2255 def _autoindent_update(self,line):
2253 2256 """Keep track of the indent level."""
2254 2257
2255 2258 #debugx('line')
2256 2259 #debugx('self.indent_current_nsp')
2257 2260 if self.autoindent:
2258 2261 if line:
2259 2262 inisp = num_ini_spaces(line)
2260 2263 if inisp < self.indent_current_nsp:
2261 2264 self.indent_current_nsp = inisp
2262 2265
2263 2266 if line[-1] == ':':
2264 2267 self.indent_current_nsp += 4
2265 2268 elif dedent_re.match(line):
2266 2269 self.indent_current_nsp -= 4
2267 2270 else:
2268 2271 self.indent_current_nsp = 0
2269 2272
2270 2273 #-------------------------------------------------------------------------
2271 2274 # Things related to GUI support and pylab
2272 2275 #-------------------------------------------------------------------------
2273 2276
2274 2277 def enable_pylab(self, gui=None):
2275 2278 raise NotImplementedError('Implement enable_pylab in a subclass')
2276 2279
2277 2280 #-------------------------------------------------------------------------
2278 2281 # Utilities
2279 2282 #-------------------------------------------------------------------------
2280 2283
2281 2284 def var_expand(self,cmd,depth=0):
2282 2285 """Expand python variables in a string.
2283 2286
2284 2287 The depth argument indicates how many frames above the caller should
2285 2288 be walked to look for the local namespace where to expand variables.
2286 2289
2287 2290 The global namespace for expansion is always the user's interactive
2288 2291 namespace.
2289 2292 """
2290 2293
2291 2294 return str(ItplNS(cmd,
2292 2295 self.user_ns, # globals
2293 2296 # Skip our own frame in searching for locals:
2294 2297 sys._getframe(depth+1).f_locals # locals
2295 2298 ))
2296 2299
2297 2300 def mktempfile(self,data=None):
2298 2301 """Make a new tempfile and return its filename.
2299 2302
2300 2303 This makes a call to tempfile.mktemp, but it registers the created
2301 2304 filename internally so ipython cleans it up at exit time.
2302 2305
2303 2306 Optional inputs:
2304 2307
2305 2308 - data(None): if data is given, it gets written out to the temp file
2306 2309 immediately, and the file is closed again."""
2307 2310
2308 2311 filename = tempfile.mktemp('.py','ipython_edit_')
2309 2312 self.tempfiles.append(filename)
2310 2313
2311 2314 if data:
2312 2315 tmp_file = open(filename,'w')
2313 2316 tmp_file.write(data)
2314 2317 tmp_file.close()
2315 2318 return filename
2316 2319
2317 2320 # TODO: This should be removed when Term is refactored.
2318 2321 def write(self,data):
2319 2322 """Write a string to the default output"""
2320 2323 io.Term.cout.write(data)
2321 2324
2322 2325 # TODO: This should be removed when Term is refactored.
2323 2326 def write_err(self,data):
2324 2327 """Write a string to the default error output"""
2325 2328 io.Term.cerr.write(data)
2326 2329
2327 2330 def ask_yes_no(self,prompt,default=True):
2328 2331 if self.quiet:
2329 2332 return True
2330 2333 return ask_yes_no(prompt,default)
2331 2334
2332 2335 def show_usage(self):
2333 2336 """Show a usage message"""
2334 2337 page.page(IPython.core.usage.interactive_usage)
2335 2338
2336 2339 #-------------------------------------------------------------------------
2337 2340 # Things related to IPython exiting
2338 2341 #-------------------------------------------------------------------------
2339 2342 def atexit_operations(self):
2340 2343 """This will be executed at the time of exit.
2341 2344
2342 2345 Cleanup operations and saving of persistent data that is done
2343 2346 unconditionally by IPython should be performed here.
2344 2347
2345 2348 For things that may depend on startup flags or platform specifics (such
2346 2349 as having readline or not), register a separate atexit function in the
2347 2350 code that has the appropriate information, rather than trying to
2348 2351 clutter
2349 2352 """
2350 2353 # Cleanup all tempfiles left around
2351 2354 for tfile in self.tempfiles:
2352 2355 try:
2353 2356 os.unlink(tfile)
2354 2357 except OSError:
2355 2358 pass
2356 2359
2357 2360 # Clear all user namespaces to release all references cleanly.
2358 2361 self.reset()
2359 2362
2360 2363 # Run user hooks
2361 2364 self.hooks.shutdown_hook()
2362 2365
2363 2366 def cleanup(self):
2364 2367 self.restore_sys_module_state()
2365 2368
2366 2369
2367 2370 class InteractiveShellABC(object):
2368 2371 """An abstract base class for InteractiveShell."""
2369 2372 __metaclass__ = abc.ABCMeta
2370 2373
2371 2374 InteractiveShellABC.register(InteractiveShell)
General Comments 0
You need to be logged in to leave comments. Login now