oinspect.py
826 lines
| 27.5 KiB
| text/x-python
|
PythonLexer
|
r1032 | # -*- 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. | ||||
""" | ||||
#***************************************************************************** | ||||
# 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. | ||||
#***************************************************************************** | ||||
__all__ = ['Inspector','InspectColors'] | ||||
# stdlib modules | ||||
import __builtin__ | ||||
import inspect | ||||
import linecache | ||||
import os | ||||
import sys | ||||
|
r1413 | import types | ||
|
r2931 | from collections import namedtuple | ||
|
r4744 | try: | ||
from itertools import izip_longest | ||||
except ImportError: | ||||
from itertools import zip_longest as izip_longest | ||||
|
r1413 | |||
|
r1032 | # IPython's own | ||
|
r2830 | from IPython.core import page | ||
|
r5204 | from IPython.testing.skipdoctest import skip_doctest_py3 | ||
|
r2498 | from IPython.utils import PyColorize | ||
|
r3800 | from IPython.utils import io | ||
|
r4744 | from IPython.utils import py3compat | ||
|
r2498 | from IPython.utils.text import indent | ||
|
r2051 | from IPython.utils.wildcard import list_namespace | ||
|
r2010 | from IPython.utils.coloransi import * | ||
|
r1032 | |||
#**************************************************************************** | ||||
# 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') | ||||
#**************************************************************************** | ||||
|
r2931 | # Auxiliary functions and objects | ||
# See the messaging spec for the definition of all these fields. This list | ||||
# effectively defines the order of display | ||||
info_fields = ['type_name', 'base_class', 'string_form', 'namespace', | ||||
'length', 'file', 'definition', 'docstring', 'source', | ||||
'init_definition', 'class_docstring', 'init_docstring', | ||||
'call_def', 'call_docstring', | ||||
# These won't be printed but will be used to determine how to | ||||
# format the object | ||||
|
r3856 | 'ismagic', 'isalias', 'isclass', 'argspec', 'found', 'name' | ||
|
r2931 | ] | ||
|
r3051 | def object_info(**kw): | ||
"""Make an object info dict with all fields present.""" | ||||
|
r2931 | infodict = dict(izip_longest(info_fields, [None])) | ||
infodict.update(kw) | ||||
|
r3051 | return infodict | ||
|
r2931 | |||
|
r1032 | 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.""" | ||||
# Allow objects to offer customized documentation via a getdoc method: | ||||
try: | ||||
|
r5535 | ds = obj.getdoc() | ||
except Exception: | ||||
|
r1032 | pass | ||
else: | ||||
# if we get extra info, we add it to the normal docstring. | ||||
|
r5535 | if isinstance(ds, basestring): | ||
|
r5536 | return inspect.cleandoc(ds) | ||
|
r5535 | |||
try: | ||||
return inspect.getdoc(obj) | ||||
except Exception: | ||||
# Harden against an inspect failure, which can occur with | ||||
# SWIG-wrapped extensions. | ||||
return None | ||||
|
r1032 | |||
|
r1413 | |||
|
r1032 | 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 | ||||
custom extractors may know how to meaningfully process them.""" | ||||
|
r4266 | |||
|
r1032 | if is_binary: | ||
return None | ||||
else: | ||||
|
r4267 | # get source if obj was decorated with @decorator | ||
|
r4266 | if hasattr(obj,"__wrapped__"): | ||
obj = obj.__wrapped__ | ||||
|
r1228 | try: | ||
src = inspect.getsource(obj) | ||||
except TypeError: | ||||
if hasattr(obj,'__class__'): | ||||
src = inspect.getsource(obj.__class__) | ||||
return src | ||||
|
r1032 | |||
|
r1413 | def getargspec(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 | ||||
|
r3051 | elif hasattr(obj, '__call__'): | ||
func_obj = obj.__call__ | ||||
|
r1413 | else: | ||
|
r2932 | raise TypeError('arg is not a Python function') | ||
|
r1413 | args, varargs, varkw = inspect.getargs(func_obj.func_code) | ||
return args, varargs, varkw, func_obj.func_defaults | ||||
|
r3051 | |||
def format_argspec(argspec): | ||||
"""Format argspect, convenience wrapper around inspect's. | ||||
This takes a dict instead of ordered arguments and calls | ||||
inspect.format_argspec with the arguments in the necessary order. | ||||
""" | ||||
return inspect.formatargspec(argspec['args'], argspec['varargs'], | ||||
argspec['varkw'], argspec['defaults']) | ||||
def call_tip(oinfo, format_call=True): | ||||
"""Extract call tip data from an oinfo dict. | ||||
Parameters | ||||
---------- | ||||
oinfo : dict | ||||
format_call : bool, optional | ||||
If True, the call line is formatted and returned as a string. If not, a | ||||
tuple of (name, argspec) is returned. | ||||
Returns | ||||
------- | ||||
call_info : None, str or (str, dict) tuple. | ||||
When format_call is True, the whole call information is formattted as a | ||||
single string. Otherwise, the object's name and its argspec dict are | ||||
returned. If no call information is available, None is returned. | ||||
|
r4872 | |||
|
r3051 | docstring : str or None | ||
The most relevant docstring for calling purposes is returned, if | ||||
available. The priority is: call docstring for callable instances, then | ||||
constructor docstring for classes, then main object's docstring otherwise | ||||
(regular functions). | ||||
""" | ||||
# Get call definition | ||||
|
r3934 | argspec = oinfo.get('argspec') | ||
|
r3051 | if argspec is None: | ||
call_line = None | ||||
else: | ||||
# Callable objects will have 'self' as their first argument, prune | ||||
# it out if it's there for clarity (since users do *not* pass an | ||||
# extra first argument explicitly). | ||||
try: | ||||
has_self = argspec['args'][0] == 'self' | ||||
except (KeyError, IndexError): | ||||
pass | ||||
else: | ||||
if has_self: | ||||
argspec['args'] = argspec['args'][1:] | ||||
|
r4872 | |||
|
r3051 | call_line = oinfo['name']+format_argspec(argspec) | ||
# Now get docstring. | ||||
# The priority is: call docstring, constructor docstring, main one. | ||||
|
r3934 | doc = oinfo.get('call_docstring') | ||
|
r3051 | if doc is None: | ||
|
r3934 | doc = oinfo.get('init_docstring') | ||
|
r3051 | if doc is None: | ||
|
r3934 | doc = oinfo.get('docstring','') | ||
|
r3051 | |||
return call_line, doc | ||||
|
r1413 | |||
|
r7290 | def find_file(obj): | ||
"""Find the absolute path to the file where an object was defined. | ||||
This is essentially a robust wrapper around `inspect.getabsfile`. | ||||
Returns None if no file can be found. | ||||
Parameters | ||||
---------- | ||||
obj : any Python object | ||||
Returns | ||||
------- | ||||
fname : str | ||||
The absolute path to the file where the object was defined. | ||||
""" | ||||
|
r7431 | # get source if obj was decorated with @decorator | ||
if hasattr(obj, '__wrapped__'): | ||||
obj = obj.__wrapped__ | ||||
|
r7520 | |||
fname = None | ||||
|
r7290 | try: | ||
fname = inspect.getabsfile(obj) | ||||
except TypeError: | ||||
# For an instance, the file that matters is where its class was | ||||
# declared. | ||||
|
r7431 | if hasattr(obj, '__class__'): | ||
|
r7290 | try: | ||
fname = inspect.getabsfile(obj.__class__) | ||||
except TypeError: | ||||
# Can happen for builtins | ||||
|
r7520 | pass | ||
|
r7290 | except: | ||
|
r7520 | pass | ||
|
r7290 | return fname | ||
def find_source_lines(obj): | ||||
"""Find the line number in a file where an object was defined. | ||||
This is essentially a robust wrapper around `inspect.getsourcelines`. | ||||
Returns None if no file can be found. | ||||
Parameters | ||||
---------- | ||||
obj : any Python object | ||||
Returns | ||||
------- | ||||
lineno : int | ||||
The line number where the object definition starts. | ||||
""" | ||||
|
r7431 | # get source if obj was decorated with @decorator | ||
if hasattr(obj, '__wrapped__'): | ||||
obj = obj.__wrapped__ | ||||
|
r7290 | try: | ||
try: | ||||
lineno = inspect.getsourcelines(obj)[1] | ||||
except TypeError: | ||||
# For instances, try the class object like getsource() does | ||||
|
r7431 | if hasattr(obj, '__class__'): | ||
|
r7290 | lineno = inspect.getsourcelines(obj.__class__)[1] | ||
except: | ||||
return None | ||||
return lineno | ||||
|
r1032 | class Inspector: | ||
|
r3051 | def __init__(self, color_table=InspectColors, | ||
code_color_table=PyColorize.ANSICodeColors, | ||||
scheme='NoColor', | ||||
|
r1032 | str_detail_level=0): | ||
self.color_table = color_table | ||||
self.parser = PyColorize.Parser(code_color_table,out='str') | ||||
self.format = self.parser.format | ||||
self.str_detail_level = str_detail_level | ||||
self.set_active_scheme(scheme) | ||||
|
r2929 | def _getdef(self,obj,oname=''): | ||
|
r1032 | """Return the definition header for any callable object. | ||
If any exception is generated, None is returned instead and the | ||||
exception is suppressed.""" | ||||
|
r4872 | |||
|
r1032 | try: | ||
|
r2930 | # We need a plain string here, NOT unicode! | ||
hdef = oname + inspect.formatargspec(*getargspec(obj)) | ||||
|
r4747 | return py3compat.unicode_to_str(hdef, 'ascii') | ||
|
r1032 | except: | ||
return None | ||||
|
r4872 | |||
|
r1032 | 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) | ||||
|
r7290 | def set_active_scheme(self, scheme): | ||
|
r1032 | self.color_table.set_active_scheme(scheme) | ||
self.parser.color_table.set_active_scheme(scheme) | ||||
|
r4872 | |||
|
r7290 | def noinfo(self, msg, oname): | ||
|
r1032 | """Generic message when no information is found.""" | ||
print 'No %s found' % msg, | ||||
if oname: | ||||
print 'for %s' % oname | ||||
else: | ||||
|
r4872 | |||
|
r7290 | def pdef(self, obj, oname=''): | ||
|
r1032 | """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 = '' | ||||
if inspect.isclass(obj): | ||||
header = self.__head('Class constructor information:\n') | ||||
obj = obj.__init__ | ||||
|
r7461 | elif (not py3compat.PY3) and type(obj) is types.InstanceType: | ||
|
r1032 | obj = obj.__call__ | ||
|
r2929 | output = self._getdef(obj,oname) | ||
|
r1032 | if output is None: | ||
self.noinfo('definition header',oname) | ||||
else: | ||||
|
r3800 | print >>io.stdout, header,self.format(output), | ||
|
r1032 | |||
|
r5204 | # In Python 3, all classes are new-style, so they all have __init__. | ||
@skip_doctest_py3 | ||||
|
r1032 | def pdoc(self,obj,oname='',formatter = None): | ||
"""Print the docstring for any object. | ||||
Optional: | ||||
-formatter: a function to run the docstring through for specially | ||||
|
r4249 | formatted docstrings. | ||
|
r4872 | |||
|
r4249 | Examples | ||
-------- | ||||
|
r4872 | |||
|
r4249 | In [1]: class NoInit: | ||
...: pass | ||||
|
r4872 | |||
|
r4249 | In [2]: class NoDoc: | ||
...: def __init__(self): | ||||
...: pass | ||||
|
r4872 | |||
|
r4249 | In [3]: %pdoc NoDoc | ||
No documentation found for NoDoc | ||||
|
r4872 | |||
|
r4249 | In [4]: %pdoc NoInit | ||
No documentation found for NoInit | ||||
In [5]: obj = NoInit() | ||||
|
r4872 | |||
|
r4249 | In [6]: %pdoc obj | ||
No documentation found for obj | ||||
In [5]: obj2 = NoDoc() | ||||
|
r4872 | |||
|
r4249 | In [6]: %pdoc obj2 | ||
No documentation found for obj2 | ||||
""" | ||||
|
r1032 | |||
|
r4052 | head = self.__head # For convenience | ||
|
r4249 | lines = [] | ||
|
r1032 | ds = getdoc(obj) | ||
if formatter: | ||||
ds = formatter(ds) | ||||
|
r4249 | if ds: | ||
lines.append(head("Class Docstring:")) | ||||
lines.append(indent(ds)) | ||||
if inspect.isclass(obj) and hasattr(obj, '__init__'): | ||||
|
r1032 | init_ds = getdoc(obj.__init__) | ||
|
r4249 | if init_ds is not None: | ||
lines.append(head("Constructor Docstring:")) | ||||
lines.append(indent(init_ds)) | ||||
|
r4896 | elif hasattr(obj,'__call__'): | ||
|
r1032 | call_ds = getdoc(obj.__call__) | ||
if call_ds: | ||||
|
r4249 | lines.append(head("Calling Docstring:")) | ||
lines.append(indent(call_ds)) | ||||
if not lines: | ||||
|
r1032 | self.noinfo('documentation',oname) | ||
|
r4249 | else: | ||
page.page('\n'.join(lines)) | ||||
|
r4872 | |||
|
r1032 | 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: | ||||
|
r4872 | src = getsource(obj) | ||
|
r1032 | except: | ||
self.noinfo('source',oname) | ||||
else: | ||||
|
r4744 | page.page(self.format(py3compat.unicode_to_str(src))) | ||
|
r1032 | |||
|
r7290 | def pfile(self, obj, oname=''): | ||
|
r1032 | """Show the whole file where an object was defined.""" | ||
|
r7290 | |||
lineno = find_source_lines(obj) | ||||
if lineno is None: | ||||
self.noinfo('file', oname) | ||||
|
r1228 | return | ||
|
r7290 | ofile = find_file(obj) | ||
# run contents of file through pager starting at line where the object | ||||
# is defined, as long as the file isn't binary and is actually on the | ||||
# filesystem. | ||||
|
r3929 | if ofile.endswith(('.so', '.dll', '.pyd')): | ||
|
r1228 | print 'File %r is binary, not printing.' % ofile | ||
elif not os.path.isfile(ofile): | ||||
print 'File %r does not exist, not printing.' % ofile | ||||
|
r1032 | else: | ||
|
r1228 | # Print only text files, not extension binaries. Note that | ||
# getsourcelines returns lineno with 1-offset and page() uses | ||||
# 0-offset, so we must adjust. | ||||
|
r7290 | page.page(self.format(open(ofile).read()), lineno-1) | ||
|
r4872 | |||
|
r3856 | def _format_fields(self, fields, title_width=12): | ||
"""Formats a list of fields for display. | ||||
|
r4872 | |||
|
r3856 | Parameters | ||
---------- | ||||
fields : list | ||||
A list of 2-tuples: (field_title, field_content) | ||||
title_width : int | ||||
How many characters to pad titles to. Default 12. | ||||
""" | ||||
out = [] | ||||
header = self.__head | ||||
for title, content in fields: | ||||
if len(content.splitlines()) > 1: | ||||
title = header(title + ":") + "\n" | ||||
else: | ||||
title = header((title+":").ljust(title_width)) | ||||
out.append(title + content) | ||||
return "\n".join(out) | ||||
# The fields to be displayed by pinfo: (fancy_name, key_in_info_dict) | ||||
pinfo_fields1 = [("Type", "type_name"), | ||||
("Base Class", "base_class"), | ||||
("String Form", "string_form"), | ||||
("Namespace", "namespace"), | ||||
("Length", "length"), | ||||
("File", "file"), | ||||
("Definition", "definition")] | ||||
|
r4872 | |||
|
r3862 | pinfo_fields_obj = [("Class Docstring", "class_docstring"), | ||
("Constructor Docstring","init_docstring"), | ||||
|
r3856 | ("Call def", "call_def"), | ||
("Call docstring", "call_docstring")] | ||||
|
r4872 | |||
|
r1032 | def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0): | ||
"""Show detailed information about an object. | ||||
Optional arguments: | ||||
|
r4872 | |||
|
r1032 | - 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. | ||||
""" | ||||
|
r3856 | info = self.info(obj, oname=oname, formatter=formatter, | ||
info=info, detail_level=detail_level) | ||||
displayfields = [] | ||||
for title, key in self.pinfo_fields1: | ||||
field = info[key] | ||||
if field is not None: | ||||
displayfields.append((title, field.rstrip())) | ||||
|
r4872 | |||
|
r3856 | # Source or docstring, depending on detail level and whether | ||
# source found. | ||||
if detail_level > 0 and info['source'] is not None: | ||||
|
r5773 | displayfields.append(("Source", self.format(py3compat.cast_bytes_py2(info['source'])))) | ||
|
r3856 | elif info['docstring'] is not None: | ||
displayfields.append(("Docstring", info["docstring"])) | ||||
|
r4872 | |||
|
r3856 | # Constructor info for classes | ||
if info['isclass']: | ||||
if info['init_definition'] or info['init_docstring']: | ||||
displayfields.append(("Constructor information", "")) | ||||
if info['init_definition'] is not None: | ||||
displayfields.append((" Definition", | ||||
info['init_definition'].rstrip())) | ||||
if info['init_docstring'] is not None: | ||||
displayfields.append((" Docstring", | ||||
indent(info['init_docstring']))) | ||||
|
r4872 | |||
|
r3856 | # Info for objects: | ||
|
r1032 | else: | ||
|
r3856 | for title, key in self.pinfo_fields_obj: | ||
field = info[key] | ||||
if field is not None: | ||||
displayfields.append((title, field.rstrip())) | ||||
|
r4872 | |||
|
r3856 | # Finally send to printer/pager: | ||
if displayfields: | ||||
page.page(self._format_fields(displayfields)) | ||||
|
r1032 | |||
|
r2931 | def info(self, obj, oname='', formatter=None, info=None, detail_level=0): | ||
"""Compute a dict with detailed information about an object. | ||||
Optional arguments: | ||||
|
r4872 | |||
|
r2931 | - 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 | ||||
|
r3051 | |||
|
r2931 | # Get docstring, special-casing aliases: | ||
if isalias: | ||||
if not callable(obj): | ||||
try: | ||||
ds = "Alias to the system command:\n %s" % obj[1] | ||||
except: | ||||
ds = "Alias: " + str(obj) | ||||
else: | ||||
ds = "Alias to " + str(obj) | ||||
if obj.__doc__: | ||||
ds += "\nDocstring:\n" + obj.__doc__ | ||||
else: | ||||
ds = getdoc(obj) | ||||
if ds is None: | ||||
ds = '<no docstring>' | ||||
if formatter is not None: | ||||
ds = formatter(ds) | ||||
|
r3051 | # store output in a dict, we initialize it here and fill it as we go | ||
out = dict(name=oname, found=True, isalias=isalias, ismagic=ismagic) | ||||
|
r4872 | |||
|
r2931 | 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['type_name'] = obj_type_name | ||||
try: | ||||
bclass = obj.__class__ | ||||
out['base_class'] = str(bclass) | ||||
except: pass | ||||
# String form, but snip if too long in ? form (full in ??) | ||||
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())).\ | ||||
|
r3160 | join(q.strip() for q in ostr.split("\n")) | ||
|
r2931 | out[str_head] = ostr | ||
except: | ||||
pass | ||||
if ospace: | ||||
out['namespace'] = ospace | ||||
# Length (for strings and lists) | ||||
try: | ||||
out['length'] = str(len(obj)) | ||||
except: pass | ||||
# Filename where object was defined | ||||
binary_file = False | ||||
|
r7290 | fname = find_file(obj) | ||
if fname is None: | ||||
|
r2931 | # if anything goes wrong, we don't want to show source, so it's as | ||
# if the file was binary | ||||
binary_file = True | ||||
|
r7290 | else: | ||
if fname.endswith(('.so', '.dll', '.pyd')): | ||||
binary_file = True | ||||
elif fname.endswith('<string>'): | ||||
fname = 'Dynamically generated function. No source code available.' | ||||
out['file'] = fname | ||||
|
r2931 | # reconstruct the function definition and print it: | ||
|
r3051 | defln = self._getdef(obj, oname) | ||
|
r2931 | if defln: | ||
out['definition'] = self.format(defln) | ||||
|
r3051 | |||
|
r2931 | # 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: | ||||
|
r3051 | out['docstring'] = ds | ||
|
r4872 | |||
|
r2931 | # Original source code for any callable | ||
if detail_level: | ||||
# Flush the source cache because inspect can return out-of-date | ||||
# source | ||||
linecache.checkcache() | ||||
|
r3857 | source = None | ||
|
r2931 | try: | ||
try: | ||||
|
r7290 | source = getsource(obj, binary_file) | ||
|
r2931 | except TypeError: | ||
|
r7290 | if hasattr(obj, '__class__'): | ||
source = getsource(obj.__class__, binary_file) | ||||
|
r4748 | if source is not None: | ||
|
r2931 | out['source'] = source.rstrip() | ||
|
r3856 | except Exception: | ||
|
r3857 | pass | ||
|
r4872 | |||
|
r3857 | if ds and source is None: | ||
out['docstring'] = ds | ||||
|
r4872 | |||
|
r2931 | |||
# Constructor docstring for classes | ||||
if inspect.isclass(obj): | ||||
|
r3856 | out['isclass'] = True | ||
|
r2931 | # 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) | ||||
# Skip Python's auto-generated docstrings | ||||
if init_ds and \ | ||||
init_ds.startswith('x.__init__(...) initializes'): | ||||
init_ds = None | ||||
if init_def or init_ds: | ||||
if init_def: | ||||
out['init_definition'] = self.format(init_def) | ||||
if init_ds: | ||||
|
r3051 | out['init_docstring'] = init_ds | ||
|
r2931 | # and class docstring for instances: | ||
|
r3856 | else: | ||
|
r2931 | # 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: | ||||
try: | ||||
cls = getattr(obj,'__class__') | ||||
except: | ||||
class_ds = None | ||||
else: | ||||
class_ds = getdoc(cls) | ||||
# Skip Python's auto-generated docstrings | ||||
if class_ds and \ | ||||
(class_ds.startswith('function(code, globals[,') or \ | ||||
class_ds.startswith('instancemethod(function, instance,') or \ | ||||
class_ds.startswith('module(name[,') ): | ||||
class_ds = None | ||||
if class_ds and ds != class_ds: | ||||
|
r3051 | out['class_docstring'] = class_ds | ||
|
r2931 | |||
# Next, try to show constructor docstrings | ||||
try: | ||||
init_ds = getdoc(obj.__init__) | ||||
# Skip Python's auto-generated docstrings | ||||
if init_ds and \ | ||||
init_ds.startswith('x.__init__(...) initializes'): | ||||
init_ds = None | ||||
except AttributeError: | ||||
init_ds = None | ||||
if init_ds: | ||||
|
r3051 | out['init_docstring'] = init_ds | ||
|
r2931 | |||
# Call form docstring for callable instances | ||||
|
r3051 | if hasattr(obj, '__call__'): | ||
call_def = self._getdef(obj.__call__, oname) | ||||
|
r2931 | if call_def is not None: | ||
out['call_def'] = self.format(call_def) | ||||
call_ds = getdoc(obj.__call__) | ||||
# Skip Python's auto-generated docstrings | ||||
if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'): | ||||
call_ds = None | ||||
if call_ds: | ||||
|
r3051 | out['call_docstring'] = call_ds | ||
# Compute the object's argspec as a callable. The key is to decide | ||||
# whether to pull it from the object itself, from its __init__ or | ||||
# from its __call__ method. | ||||
|
r4872 | |||
|
r3051 | if inspect.isclass(obj): | ||
|
r3868 | # Old-style classes need not have an __init__ | ||
callable_obj = getattr(obj, "__init__", None) | ||||
|
r3051 | elif callable(obj): | ||
callable_obj = obj | ||||
else: | ||||
callable_obj = None | ||||
if callable_obj: | ||||
try: | ||||
args, varargs, varkw, defaults = getargspec(callable_obj) | ||||
except (TypeError, AttributeError): | ||||
# For extensions/builtins we can't retrieve the argspec | ||||
pass | ||||
else: | ||||
out['argspec'] = dict(args=args, varargs=varargs, | ||||
varkw=varkw, defaults=defaults) | ||||
|
r2931 | |||
|
r3051 | return object_info(**out) | ||
|
r2931 | |||
|
r1032 | def psearch(self,pattern,ns_table,ns_search=[], | ||
ignore_case=False,show_all=False): | ||||
"""Search namespaces with wildcards for objects. | ||||
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. | ||||
Optional arguments: | ||||
|
r4872 | |||
|
r1032 | - ns_search: list of namespace names to include in search. | ||
- ignore_case(False): make the search case-insensitive. | ||||
- show_all(False): show all names, including those starting with | ||||
underscores. | ||||
""" | ||||
#print 'ps pattern:<%r>' % pattern # dbg | ||||
|
r4872 | |||
|
r1032 | # defaults | ||
type_pattern = 'all' | ||||
filter = '' | ||||
cmds = pattern.split() | ||||
len_cmds = len(cmds) | ||||
if len_cmds == 1: | ||||
# Only filter pattern given | ||||
filter = cmds[0] | ||||
elif len_cmds == 2: | ||||
# Both filter and type specified | ||||
filter,type_pattern = cmds | ||||
else: | ||||
raise ValueError('invalid argument string for psearch: <%s>' % | ||||
pattern) | ||||
# 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())) | ||||
#print 'type_pattern:',type_pattern # dbg | ||||
|
r5550 | search_result, namespaces_seen = set(), set() | ||
|
r1032 | for ns_name in ns_search: | ||
ns = ns_table[ns_name] | ||||
|
r5550 | # Normally, locals and globals are the same, so we just check one. | ||
if id(ns) in namespaces_seen: | ||||
continue | ||||
namespaces_seen.add(id(ns)) | ||||
tmp_res = list_namespace(ns, type_pattern, filter, | ||||
ignore_case=ignore_case, show_all=show_all) | ||||
search_result.update(tmp_res) | ||||
page.page('\n'.join(sorted(search_result))) | ||||