OInspect.py
569 lines
| 19.9 KiB
| text/x-python
|
PythonLexer
/ IPython / OInspect.py
fperez
|
r0 | # -*- coding: utf-8 -*- | ||
"""Tools for inspecting Python objects. | ||||
Uses syntax highlighting for presenting the various information elements. | ||||
Similar in spirit to the inspect module, but all calls take a name argument to | ||||
reference the name under which an object is being read. | ||||
fperez
|
r752 | $Id: OInspect.py 2584 2007-08-05 18:16:31Z fperez $ | ||
fperez
|
r0 | """ | ||
#***************************************************************************** | ||||
# Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu> | ||||
# | ||||
# Distributed under the terms of the BSD License. The full license is in | ||||
# the file COPYING, distributed as part of this software. | ||||
#***************************************************************************** | ||||
from IPython import Release | ||||
__author__ = '%s <%s>' % Release.authors['Fernando'] | ||||
__license__ = Release.license | ||||
__all__ = ['Inspector','InspectColors'] | ||||
# stdlib modules | ||||
fperez
|
r41 | import __builtin__ | ||
fperez
|
r52 | import inspect | ||
import linecache | ||||
import string | ||||
import StringIO | ||||
import types | ||||
vivainio
|
r270 | import os | ||
vivainio
|
r363 | import sys | ||
fperez
|
r0 | # IPython's own | ||
fperez
|
r37 | from IPython import PyColorize | ||
fperez
|
r52 | from IPython.genutils import page,indent,Term,mkdict | ||
fperez
|
r0 | from IPython.Itpl import itpl | ||
fperez
|
r41 | from IPython.wildcard import list_namespace | ||
fperez
|
r0 | from IPython.ColorANSI import * | ||
#**************************************************************************** | ||||
vivainio
|
r363 | # HACK!!! This is a crude fix for bugs in python 2.3's inspect module. We | ||
# simply monkeypatch inspect with code copied from python 2.4. | ||||
if sys.version_info[:2] == (2,3): | ||||
from inspect import ismodule, getabsfile, modulesbyfile | ||||
def getmodule(object): | ||||
"""Return the module an object was defined in, or None if not found.""" | ||||
if ismodule(object): | ||||
return object | ||||
if hasattr(object, '__module__'): | ||||
return sys.modules.get(object.__module__) | ||||
try: | ||||
file = getabsfile(object) | ||||
except TypeError: | ||||
return None | ||||
if file in modulesbyfile: | ||||
return sys.modules.get(modulesbyfile[file]) | ||||
for module in sys.modules.values(): | ||||
if hasattr(module, '__file__'): | ||||
modulesbyfile[ | ||||
os.path.realpath( | ||||
getabsfile(module))] = module.__name__ | ||||
if file in modulesbyfile: | ||||
return sys.modules.get(modulesbyfile[file]) | ||||
main = sys.modules['__main__'] | ||||
if not hasattr(object, '__name__'): | ||||
return None | ||||
if hasattr(main, object.__name__): | ||||
mainobject = getattr(main, object.__name__) | ||||
if mainobject is object: | ||||
return main | ||||
builtin = sys.modules['__builtin__'] | ||||
if hasattr(builtin, object.__name__): | ||||
builtinobject = getattr(builtin, object.__name__) | ||||
if builtinobject is object: | ||||
return builtin | ||||
inspect.getmodule = getmodule | ||||
#**************************************************************************** | ||||
fperez
|
r0 | # Builtin color schemes | ||
Colors = TermColors # just a shorthand | ||||
# Build a few color schemes | ||||
NoColor = ColorScheme( | ||||
'NoColor',{ | ||||
'header' : Colors.NoColor, | ||||
'normal' : Colors.NoColor # color off (usu. Colors.Normal) | ||||
} ) | ||||
LinuxColors = ColorScheme( | ||||
'Linux',{ | ||||
'header' : Colors.LightRed, | ||||
'normal' : Colors.Normal # color off (usu. Colors.Normal) | ||||
} ) | ||||
LightBGColors = ColorScheme( | ||||
'LightBG',{ | ||||
'header' : Colors.Red, | ||||
'normal' : Colors.Normal # color off (usu. Colors.Normal) | ||||
} ) | ||||
# Build table of color schemes (needed by the parser) | ||||
InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors], | ||||
'Linux') | ||||
#**************************************************************************** | ||||
# Auxiliary functions | ||||
def getdoc(obj): | ||||
"""Stable wrapper around inspect.getdoc. | ||||
This can't crash because of attribute problems. | ||||
It also attempts to call a getdoc() method on the given object. This | ||||
allows objects which provide their docstrings via non-standard mechanisms | ||||
(like Pyro proxies) to still be inspected by ipython's ? system.""" | ||||
ds = None # default return value | ||||
try: | ||||
ds = inspect.getdoc(obj) | ||||
except: | ||||
# Harden against an inspect failure, which can occur with | ||||
# SWIG-wrapped extensions. | ||||
pass | ||||
# Allow objects to offer customized documentation via a getdoc method: | ||||
try: | ||||
ds2 = obj.getdoc() | ||||
except: | ||||
pass | ||||
else: | ||||
# if we get extra info, we add it to the normal docstring. | ||||
if ds is None: | ||||
ds = ds2 | ||||
else: | ||||
ds = '%s\n%s' % (ds,ds2) | ||||
return ds | ||||
fptest
|
r390 | def getsource(obj,is_binary=False): | ||
"""Wrapper around inspect.getsource. | ||||
This can be modified by other projects to provide customized source | ||||
extraction. | ||||
Inputs: | ||||
- obj: an object whose source code we will attempt to extract. | ||||
Optional inputs: | ||||
- is_binary: whether the object is known to come from a binary source. | ||||
This implementation will skip returning any output for binary objects, but | ||||
fperez
|
r739 | custom extractors may know how to meaningfully process them.""" | ||
fptest
|
r390 | |||
if is_binary: | ||||
return None | ||||
else: | ||||
return inspect.getsource(obj) | ||||
fperez
|
r0 | #**************************************************************************** | ||
# Class definitions | ||||
class myStringIO(StringIO.StringIO): | ||||
"""Adds a writeln method to normal StringIO.""" | ||||
def writeln(self,*arg,**kw): | ||||
"""Does a write() and then a write('\n')""" | ||||
self.write(*arg,**kw) | ||||
self.write('\n') | ||||
class Inspector: | ||||
fperez
|
r299 | def __init__(self,color_table,code_color_table,scheme, | ||
str_detail_level=0): | ||||
fperez
|
r0 | self.color_table = color_table | ||
self.parser = PyColorize.Parser(code_color_table,out='str') | ||||
self.format = self.parser.format | ||||
fperez
|
r299 | self.str_detail_level = str_detail_level | ||
fperez
|
r0 | self.set_active_scheme(scheme) | ||
def __getargspec(self,obj): | ||||
"""Get the names and default values of a function's arguments. | ||||
A tuple of four things is returned: (args, varargs, varkw, defaults). | ||||
'args' is a list of the argument names (it may contain nested lists). | ||||
'varargs' and 'varkw' are the names of the * and ** arguments or None. | ||||
'defaults' is an n-tuple of the default values of the last n arguments. | ||||
Modified version of inspect.getargspec from the Python Standard | ||||
Library.""" | ||||
if inspect.isfunction(obj): | ||||
func_obj = obj | ||||
elif inspect.ismethod(obj): | ||||
func_obj = obj.im_func | ||||
else: | ||||
raise TypeError, 'arg is not a Python function' | ||||
args, varargs, varkw = inspect.getargs(func_obj.func_code) | ||||
return args, varargs, varkw, func_obj.func_defaults | ||||
def __getdef(self,obj,oname=''): | ||||
"""Return the definition header for any callable object. | ||||
If any exception is generated, None is returned instead and the | ||||
exception is suppressed.""" | ||||
try: | ||||
return oname + inspect.formatargspec(*self.__getargspec(obj)) | ||||
except: | ||||
return None | ||||
def __head(self,h): | ||||
"""Return a header string with proper colors.""" | ||||
return '%s%s%s' % (self.color_table.active_colors.header,h, | ||||
self.color_table.active_colors.normal) | ||||
def set_active_scheme(self,scheme): | ||||
self.color_table.set_active_scheme(scheme) | ||||
self.parser.color_table.set_active_scheme(scheme) | ||||
def noinfo(self,msg,oname): | ||||
"""Generic message when no information is found.""" | ||||
print 'No %s found' % msg, | ||||
if oname: | ||||
print 'for %s' % oname | ||||
else: | ||||
def pdef(self,obj,oname=''): | ||||
"""Print the definition header for any callable object. | ||||
If the object is a class, print the constructor information.""" | ||||
if not callable(obj): | ||||
print 'Object is not callable.' | ||||
return | ||||
header = '' | ||||
fperez
|
r739 | |||
if inspect.isclass(obj): | ||||
fperez
|
r0 | header = self.__head('Class constructor information:\n') | ||
obj = obj.__init__ | ||||
fperez
|
r739 | elif type(obj) is types.InstanceType or \ | ||
isinstance(obj,object): | ||||
fperez
|
r0 | obj = obj.__call__ | ||
output = self.__getdef(obj,oname) | ||||
if output is None: | ||||
self.noinfo('definition header',oname) | ||||
else: | ||||
print >>Term.cout, header,self.format(output), | ||||
def pdoc(self,obj,oname='',formatter = None): | ||||
"""Print the docstring for any object. | ||||
Optional: | ||||
-formatter: a function to run the docstring through for specially | ||||
formatted docstrings.""" | ||||
fperez
|
r739 | |||
fperez
|
r0 | head = self.__head # so that itpl can find it even if private | ||
ds = getdoc(obj) | ||||
if formatter: | ||||
ds = formatter(ds) | ||||
fperez
|
r739 | if inspect.isclass(obj): | ||
fperez
|
r0 | init_ds = getdoc(obj.__init__) | ||
output = itpl('$head("Class Docstring:")\n' | ||||
'$indent(ds)\n' | ||||
'$head("Constructor Docstring"):\n' | ||||
'$indent(init_ds)') | ||||
fperez
|
r739 | elif (type(obj) is types.InstanceType or isinstance(obj,object)) \ | ||
and hasattr(obj,'__call__'): | ||||
fperez
|
r0 | call_ds = getdoc(obj.__call__) | ||
if call_ds: | ||||
output = itpl('$head("Class Docstring:")\n$indent(ds)\n' | ||||
'$head("Calling Docstring:")\n$indent(call_ds)') | ||||
else: | ||||
output = ds | ||||
else: | ||||
output = ds | ||||
if output is None: | ||||
self.noinfo('documentation',oname) | ||||
return | ||||
page(output) | ||||
def psource(self,obj,oname=''): | ||||
"""Print the source code for an object.""" | ||||
# Flush the source cache because inspect can return out-of-date source | ||||
linecache.checkcache() | ||||
try: | ||||
fptest
|
r390 | src = getsource(obj) | ||
fperez
|
r0 | except: | ||
self.noinfo('source',oname) | ||||
else: | ||||
page(self.format(src)) | ||||
def pfile(self,obj,oname=''): | ||||
"""Show the whole file where an object was defined.""" | ||||
try: | ||||
sourcelines,lineno = inspect.getsourcelines(obj) | ||||
except: | ||||
self.noinfo('file',oname) | ||||
else: | ||||
# run contents of file through pager starting at line | ||||
vivainio
|
r136 | # where the object is defined | ||
ofile = inspect.getabsfile(obj) | ||||
if (ofile.endswith('.so') or ofile.endswith('.dll')): | ||||
print 'File %r is binary, not printing.' % ofile | ||||
vivainio
|
r270 | elif not os.path.isfile(ofile): | ||
print 'File %r does not exist, not printing.' % ofile | ||||
vivainio
|
r136 | else: | ||
# Print only text files, not extension binaries. | ||||
page(self.format(open(ofile).read()),lineno) | ||||
#page(self.format(open(inspect.getabsfile(obj)).read()),lineno) | ||||
fperez
|
r0 | |||
def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0): | ||||
"""Show detailed information about an object. | ||||
Optional arguments: | ||||
- oname: name of the variable pointing to the object. | ||||
- formatter: special formatter for docstrings (see pdoc) | ||||
- info: a structure with some information fields which may have been | ||||
precomputed already. | ||||
- detail_level: if set to 1, more information is given. | ||||
""" | ||||
obj_type = type(obj) | ||||
header = self.__head | ||||
if info is None: | ||||
ismagic = 0 | ||||
isalias = 0 | ||||
ospace = '' | ||||
else: | ||||
ismagic = info.ismagic | ||||
isalias = info.isalias | ||||
ospace = info.namespace | ||||
# Get docstring, special-casing aliases: | ||||
if isalias: | ||||
vivainio
|
r737 | if not callable(obj): | ||
ds = "Alias to the system command:\n %s" % obj[1] | ||||
else: | ||||
ds = "Alias to " + str(obj) | ||||
fperez
|
r0 | else: | ||
ds = getdoc(obj) | ||||
vivainio
|
r109 | if ds is None: | ||
ds = '<no docstring>' | ||||
fperez
|
r0 | if formatter is not None: | ||
ds = formatter(ds) | ||||
# store output in a list which gets joined with \n at the end. | ||||
out = myStringIO() | ||||
string_max = 200 # max size of strings to show (snipped if longer) | ||||
shalf = int((string_max -5)/2) | ||||
if ismagic: | ||||
obj_type_name = 'Magic function' | ||||
elif isalias: | ||||
obj_type_name = 'System alias' | ||||
else: | ||||
obj_type_name = obj_type.__name__ | ||||
out.writeln(header('Type:\t\t')+obj_type_name) | ||||
try: | ||||
bclass = obj.__class__ | ||||
out.writeln(header('Base Class:\t')+str(bclass)) | ||||
except: pass | ||||
# String form, but snip if too long in ? form (full in ??) | ||||
fperez
|
r299 | if detail_level >= self.str_detail_level: | ||
try: | ||||
ostr = str(obj) | ||||
str_head = 'String Form:' | ||||
if not detail_level and len(ostr)>string_max: | ||||
ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:] | ||||
ostr = ("\n" + " " * len(str_head.expandtabs())).\ | ||||
join(map(string.strip,ostr.split("\n"))) | ||||
if ostr.find('\n') > -1: | ||||
# Print multi-line strings starting at the next line. | ||||
str_sep = '\n' | ||||
else: | ||||
str_sep = '\t' | ||||
out.writeln("%s%s%s" % (header(str_head),str_sep,ostr)) | ||||
except: | ||||
pass | ||||
fperez
|
r0 | |||
if ospace: | ||||
out.writeln(header('Namespace:\t')+ospace) | ||||
# Length (for strings and lists) | ||||
try: | ||||
length = str(len(obj)) | ||||
out.writeln(header('Length:\t\t')+length) | ||||
except: pass | ||||
# Filename where object was defined | ||||
vivainio
|
r136 | binary_file = False | ||
fperez
|
r0 | try: | ||
vivainio
|
r136 | fname = inspect.getabsfile(obj) | ||
if fname.endswith('<string>'): | ||||
fname = 'Dynamically generated function. No source code available.' | ||||
vivainio
|
r270 | if (fname.endswith('.so') or fname.endswith('.dll') or | ||
not os.path.isfile(fname)): | ||||
vivainio
|
r136 | binary_file = True | ||
out.writeln(header('File:\t\t')+fname) | ||||
except: | ||||
# if anything goes wrong, we don't want to show source, so it's as | ||||
# if the file was binary | ||||
binary_file = True | ||||
fperez
|
r0 | |||
# reconstruct the function definition and print it: | ||||
defln = self.__getdef(obj,oname) | ||||
if defln: | ||||
out.write(header('Definition:\t')+self.format(defln)) | ||||
# Docstrings only in detail 0 mode, since source contains them (we | ||||
# avoid repetitions). If source fails, we add them back, see below. | ||||
if ds and detail_level == 0: | ||||
out.writeln(header('Docstring:\n') + indent(ds)) | ||||
vivainio
|
r270 | |||
fperez
|
r0 | # Original source code for any callable | ||
if detail_level: | ||||
# Flush the source cache because inspect can return out-of-date source | ||||
linecache.checkcache() | ||||
vivainio
|
r270 | source_success = False | ||
fperez
|
r0 | try: | ||
fptest
|
r390 | source = self.format(getsource(obj,binary_file)) | ||
if source: | ||||
vivainio
|
r136 | out.write(header('Source:\n')+source.rstrip()) | ||
vivainio
|
r270 | source_success = True | ||
fptest
|
r390 | except Exception, msg: | ||
vivainio
|
r270 | pass | ||
if ds and not source_success: | ||||
fptest
|
r390 | out.writeln(header('Docstring [source file open failed]:\n') | ||
+ indent(ds)) | ||||
fperez
|
r0 | |||
# Constructor docstring for classes | ||||
fperez
|
r739 | if inspect.isclass(obj): | ||
fperez
|
r0 | # reconstruct the function definition and print it: | ||
try: | ||||
obj_init = obj.__init__ | ||||
except AttributeError: | ||||
init_def = init_ds = None | ||||
else: | ||||
init_def = self.__getdef(obj_init,oname) | ||||
init_ds = getdoc(obj_init) | ||||
if init_def or init_ds: | ||||
out.writeln(header('\nConstructor information:')) | ||||
if init_def: | ||||
out.write(header('Definition:\t')+ self.format(init_def)) | ||||
if init_ds: | ||||
out.writeln(header('Docstring:\n') + indent(init_ds)) | ||||
# and class docstring for instances: | ||||
fperez
|
r739 | elif obj_type is types.InstanceType or \ | ||
isinstance(obj,object): | ||||
fperez
|
r0 | |||
# First, check whether the instance docstring is identical to the | ||||
# class one, and print it separately if they don't coincide. In | ||||
# most cases they will, but it's nice to print all the info for | ||||
# objects which use instance-customized docstrings. | ||||
if ds: | ||||
class_ds = getdoc(obj.__class__) | ||||
fperez
|
r741 | # Skip Python's auto-generated docstrings | ||
fperez
|
r742 | if class_ds and \ | ||
(class_ds.startswith('function(code, globals[,') or \ | ||||
fperez
|
r752 | class_ds.startswith('instancemethod(function, instance,') or \ | ||
class_ds.startswith('module(name[,') ): | ||||
fperez
|
r741 | class_ds = None | ||
fperez
|
r0 | if class_ds and ds != class_ds: | ||
out.writeln(header('Class Docstring:\n') + | ||||
indent(class_ds)) | ||||
# Next, try to show constructor docstrings | ||||
try: | ||||
init_ds = getdoc(obj.__init__) | ||||
fperez
|
r741 | # Skip Python's auto-generated docstrings | ||
if init_ds.startswith('x.__init__(...) initializes x'): | ||||
init_ds = None | ||||
fperez
|
r0 | except AttributeError: | ||
init_ds = None | ||||
if init_ds: | ||||
out.writeln(header('Constructor Docstring:\n') + | ||||
indent(init_ds)) | ||||
# Call form docstring for callable instances | ||||
if hasattr(obj,'__call__'): | ||||
fperez
|
r741 | #out.writeln(header('Callable:\t')+'Yes') | ||
fperez
|
r0 | call_def = self.__getdef(obj.__call__,oname) | ||
fperez
|
r741 | #if call_def is None: | ||
# out.writeln(header('Call def:\t')+ | ||||
# 'Calling definition not available.') | ||||
if call_def is not None: | ||||
out.writeln(header('Call def:\t')+self.format(call_def)) | ||||
fperez
|
r0 | call_ds = getdoc(obj.__call__) | ||
fperez
|
r741 | # Skip Python's auto-generated docstrings | ||
vivainio
|
r747 | if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'): | ||
fperez
|
r741 | call_ds = None | ||
fperez
|
r0 | if call_ds: | ||
out.writeln(header('Call docstring:\n') + indent(call_ds)) | ||||
# Finally send to printer/pager | ||||
output = out.getvalue() | ||||
if output: | ||||
page(output) | ||||
# end pinfo | ||||
fperez
|
r37 | |||
fperez
|
r41 | def psearch(self,pattern,ns_table,ns_search=[], | ||
ignore_case=False,show_all=False): | ||||
fperez
|
r40 | """Search namespaces with wildcards for objects. | ||
fperez
|
r37 | |||
fperez
|
r41 | Arguments: | ||
- pattern: string containing shell-like wildcards to use in namespace | ||||
searches and optionally a type specification to narrow the search to | ||||
objects of that type. | ||||
- ns_table: dict of name->namespaces for search. | ||||
fperez
|
r37 | Optional arguments: | ||
fperez
|
r41 | - ns_search: list of namespace names to include in search. | ||
fperez
|
r40 | |||
fperez
|
r41 | - ignore_case(False): make the search case-insensitive. | ||
fperez
|
r40 | |||
fperez
|
r41 | - show_all(False): show all names, including those starting with | ||
underscores. | ||||
fperez
|
r40 | """ | ||
fperez
|
r742 | #print 'ps pattern:<%r>' % pattern # dbg | ||
fperez
|
r41 | # defaults | ||
fperez
|
r40 | type_pattern = 'all' | ||
fperez
|
r41 | filter = '' | ||
cmds = pattern.split() | ||||
fperez
|
r40 | len_cmds = len(cmds) | ||
if len_cmds == 1: | ||||
fperez
|
r41 | # Only filter pattern given | ||
filter = cmds[0] | ||||
fperez
|
r40 | elif len_cmds == 2: | ||
fperez
|
r41 | # Both filter and type specified | ||
fperez
|
r40 | filter,type_pattern = cmds | ||
fperez
|
r41 | else: | ||
raise ValueError('invalid argument string for psearch: <%s>' % | ||||
pattern) | ||||
fperez
|
r40 | |||
fperez
|
r41 | # filter search namespaces | ||
for name in ns_search: | ||||
if name not in ns_table: | ||||
raise ValueError('invalid namespace <%s>. Valid names: %s' % | ||||
(name,ns_table.keys())) | ||||
fperez
|
r40 | |||
fperez
|
r41 | #print 'type_pattern:',type_pattern # dbg | ||
fperez
|
r40 | search_result = [] | ||
fperez
|
r41 | for ns_name in ns_search: | ||
ns = ns_table[ns_name] | ||||
fperez
|
r40 | tmp_res = list(list_namespace(ns,type_pattern,filter, | ||
fperez
|
r41 | ignore_case=ignore_case, | ||
show_all=show_all)) | ||||
fperez
|
r40 | search_result.extend(tmp_res) | ||
search_result.sort() | ||||
page('\n'.join(search_result)) | ||||