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