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."""
head = self.__head # so that itpl can find it even if private
ds = getdoc(obj)
if formatter:
ds = formatter(ds)
if inspect.isclass(obj):
init_ds = getdoc(obj.__init__)
output = itpl('$head("Class Docstring:")\n'
'$indent(ds)\n'
'$head("Constructor Docstring"):\n'
'$indent(init_ds)')
elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
and hasattr(obj,'__call__'):
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 help(self, s, pager=True):
"""
Print help on a given topic.
EXAMPLES::
sage: print gap.help('SymmetricGroup', pager=False)
Basic Groups _____________________________________________ Group Libraries
...
"""
tmp_to_use = self._local_tmpfile()
if self.is_remote():
tmp_to_use = self._remote_tmpfile()
else:
tmp_to_use = self._local_tmpfile()
self.eval('$SAGE.tempfile := "%s";' % tmp_to_use)
line = Expect.eval(self, "? %s" % s)
match = re.search("Page from (\d+)", line)
if match == None:
print line
else:
(sline, ) = match.groups()
if self.is_remote():
self._get_tmpfile()
F = open(self._local_tmpfile(), "r")
if pager:
page(F.read(), start=int(sline) - 1)
else:
return F.read()
def pfile(self, obj, oname=''):
"""Show the whole file where an object was defined."""
try:
try:
lineno = inspect.getsourcelines(obj)[1]
except TypeError:
# For instances, try the class object like getsource() does
if hasattr(obj, '__class__'):
lineno = inspect.getsourcelines(obj.__class__)[1]
# Adjust the inspected object so getabsfile() below works
obj = obj.__class__
except:
self.noinfo('file', oname)
return
# We only reach this point if object was successfully queried
# run contents of file through pager starting at line
# 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
elif not os.path.isfile(ofile):
print 'File %r does not exist, not printing.' % ofile
else:
# Print only text files, not extension binaries. Note that
# getsourcelines returns lineno with 1-offset and page() uses
# 0-offset, so we must adjust.
page(self.format(open(ofile).read()), lineno - 1)
def help(self, s, pager=True):
"""
Print help on a given topic.
EXAMPLES::
sage: print gap.help('SymmetricGroup', pager=False)
Basic Groups _____________________________________________ Group Libraries
...
"""
tmp_to_use = self._local_tmpfile()
if self.is_remote():
tmp_to_use = self._remote_tmpfile()
else:
tmp_to_use = self._local_tmpfile()
self.eval('$SAGE.tempfile := "%s";'%tmp_to_use)
line = Expect.eval(self, "? %s"%s)
match = re.search("Page from (\d+)", line)
if match == None:
print line
else:
(sline,) = match.groups()
if self.is_remote():
self._get_tmpfile()
F = open(self._local_tmpfile(),"r")
if pager:
page(F.read(), start = int(sline)-1)
else:
return F.read()
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."""
head = self.__head # so that itpl can find it even if private
ds = getdoc(obj)
if formatter:
ds = formatter(ds)
if inspect.isclass(obj):
init_ds = getdoc(obj.__init__)
output = itpl('$head("Class Docstring:")\n'
'$indent(ds)\n'
'$head("Constructor Docstring"):\n'
'$indent(init_ds)')
elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
and hasattr(obj,'__call__'):
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 pfile(self, obj, oname=""):
"""Show the whole file where an object was defined."""
try:
try:
lineno = inspect.getsourcelines(obj)[1]
except TypeError:
# For instances, try the class object like getsource() does
if hasattr(obj, "__class__"):
lineno = inspect.getsourcelines(obj.__class__)[1]
# Adjust the inspected object so getabsfile() below works
obj = obj.__class__
except:
self.noinfo("file", oname)
return
# We only reach this point if object was successfully queried
# run contents of file through pager starting at line
# 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
elif not os.path.isfile(ofile):
print "File %r does not exist, not printing." % ofile
else:
# Print only text files, not extension binaries. Note that
# getsourcelines returns lineno with 1-offset and page() uses
# 0-offset, so we must adjust.
page(self.format(open(ofile).read()), lineno - 1)
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:
- 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
# 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
search_result = []
for ns_name in ns_search:
ns = ns_table[ns_name]
tmp_res = list(list_namespace(ns,type_pattern,filter,
ignore_case=ignore_case,
show_all=show_all))
search_result.extend(tmp_res)
search_result.sort()
page('\n'.join(search_result))
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
# where the object is defined
page(self.format(open(inspect.getabsfile(obj)).read()), lineno)
def dag(self, parameter_s=''):
import pymel.core as pm
options, args = dag_parser.parse_args(parameter_s.split())
colors = get_colors(self)
dagtree = DagTree(colors, options)
if args:
roots = [pm.PyNode(args[0])]
else:
roots = pm.ls(assemblies=1)
page(dagtree.make_tree(roots))
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:
src = getsource(obj)
except:
self.noinfo('source',oname)
else:
page(self.format(src))
def dag(self, parameter_s=''):
import pymel.core as pm
options, args = dag_parser.parse_args(parameter_s.split())
colors = get_colors(self)
dagtree = DagTree(colors, options)
if args:
roots = [pm.PyNode(args[0])]
else:
roots = pm.ls(assemblies=1)
page(dagtree.make_tree(roots))
def gphelp():
"""Print information about the Gnuplot facilities in IPython."""
page("""
IPython provides an interface to access the Gnuplot scientific plotting
system, in an environment similar to that of Mathematica or Matlab.
New top-level global objects
----------------------------
Please see their respective docstrings for further details.
- gp: a running Gnuplot instance. You can access its methods as
gp.<method>. gp(`a string`) will execute the given string as if it had been
typed in an interactive gnuplot window.
- plot, splot, replot and hardcopy: aliases to the methods of the same name in
the global running Gnuplot instance gp. These allow you to simply type:
In [1]: plot(x,sin(x),title='Sin(x)') # assuming x is a Numeric array
and obtain a plot of sin(x) vs x with the title 'Sin(x)'.
- gp_new: a function which returns a new Gnuplot instance. This can be used to
have multiple Gnuplot instances running in your session to compare different
plots, each in a separate window.
- Gnuplot: alias to the Gnuplot2 module, an improved drop-in replacement for
the original Gnuplot.py. Gnuplot2 needs Gnuplot but redefines several of its
functions with improved versions (Gnuplot2 comes with IPython).
- gpdata, gpfile, gpstring, gpfunc, gpgrid: aliases to Gnuplot.Data,
Gnuplot.File, Gnuplot.String, Gnuplot.Func and Gnuplot.GridData
respectively. These functions create objects which can then be passed to the
plotting commands. See the Gnuplot.py documentation for details.
Keep in mind that all commands passed to a Gnuplot instance are executed in
the Gnuplot namespace, where no Python variables exist. For example, for
plotting sin(x) vs x as above, typing
In [2]: gp('plot x,sin(x)')
would not work. Instead, you would get the plot of BOTH the functions 'x' and
'sin(x)', since Gnuplot doesn't know about the 'x' Python array. The plot()
method lives in python and does know about these variables.
New magic functions
-------------------
%gpc: pass one command to Gnuplot and execute it or open a Gnuplot shell where
each line of input is executed.
%gp_set_default: reset the value of IPython's global Gnuplot instance.""")
def gphelp():
"""Print information about the Gnuplot facilities in IPython."""
page("""
IPython provides an interface to access the Gnuplot scientific plotting
system, in an environment similar to that of Mathematica or Matlab.
New top-level global objects
----------------------------
Please see their respective docstrings for further details.
- gp: a running Gnuplot instance. You can access its methods as
gp.<method>. gp(`a string`) will execute the given string as if it had been
typed in an interactive gnuplot window.
- plot, splot, replot and hardcopy: aliases to the methods of the same name in
the global running Gnuplot instance gp. These allow you to simply type:
In [1]: plot(x,sin(x),title='Sin(x)') # assuming x is a Numeric array
and obtain a plot of sin(x) vs x with the title 'Sin(x)'.
- gp_new: a function which returns a new Gnuplot instance. This can be used to
have multiple Gnuplot instances running in your session to compare different
plots, each in a separate window.
- Gnuplot: alias to the Gnuplot2 module, an improved drop-in replacement for
the original Gnuplot.py. Gnuplot2 needs Gnuplot but redefines several of its
functions with improved versions (Gnuplot2 comes with IPython).
- gpdata, gpfile, gpstring, gpfunc, gpgrid: aliases to Gnuplot.Data,
Gnuplot.File, Gnuplot.String, Gnuplot.Func and Gnuplot.GridData
respectively. These functions create objects which can then be passed to the
plotting commands. See the Gnuplot.py documentation for details.
Keep in mind that all commands passed to a Gnuplot instance are executed in
the Gnuplot namespace, where no Python variables exist. For example, for
plotting sin(x) vs x as above, typing
In [2]: gp('plot x,sin(x)')
would not work. Instead, you would get the plot of BOTH the functions 'x' and
'sin(x)', since Gnuplot doesn't know about the 'x' Python array. The plot()
method lives in python and does know about these variables.
New magic functions
-------------------
%gpc: pass one command to Gnuplot and execute it or open a Gnuplot shell where
each line of input is executed.
%gp_set_default: reset the value of IPython's global Gnuplot instance.""")
def magic_dghist(self, parameter_s=''):
"""
"""
options, args = dg_parser.parse_args(parameter_s.split())
colors = color_table[self.rc.colors].colors
dgtree = DGHistoryTree(colors, options)
roots = [core.PyNode(args[0])]
page(dgtree.make_tree(roots))
def magic_dghist(self, parameter_s=''):
"""
"""
options, args = dg_parser.parse_args(parameter_s.split())
colors = color_table[self.rc.colors].colors
dgtree = DGHistoryTree(colors, options)
roots = [core.PyNode(args[0])]
page(dgtree.make_tree(roots))
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:
src = getsource(obj)
except:
self.noinfo('source', oname)
else:
page(self.format(src))
def magic_dag(self, parameter_s=''):
"""
"""
options, args = dag_parser.parse_args(parameter_s.split())
colors = color_table[self.rc.colors].colors
dagtree = DagTree(colors, options)
if args:
roots = [core.PyNode(args[0])]
else:
roots = core.ls(assemblies=1)
page(dagtree.make_tree(roots))
def magic_dag(self, parameter_s=''):
"""
"""
options, args = dag_parser.parse_args(parameter_s.split())
colors = color_table[self.rc.colors].colors
dagtree = DagTree(colors, options)
if args:
roots = [core.PyNode(args[0])]
else:
roots = core.ls(assemblies=1)
page(dagtree.make_tree(roots))
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
# 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
else:
# Print only text files, not extension binaries.
page(self.format(open(ofile).read()), lineno)
def magic_dghist(self, parameter_s=''):
"""
"""
import pymel.core as pm
options, args = dg_parser.parse_args(parameter_s.split())
if not args:
print "must pass in nodes to display the history of"
return
colors = get_colors(self)
dgtree = DGHistoryTree(colors, options)
roots = [pm.PyNode(args[0])]
page(dgtree.make_tree(roots))
def dghist(self, parameter_s=''):
"""
"""
import pymel.core as pm
options, args = dg_parser.parse_args(parameter_s.split())
if not args:
print "must pass in nodes to display the history of"
return
colors = get_colors(self)
dgtree = DGHistoryTree(colors, options)
roots = [pm.PyNode(args[0])]
page(dgtree.make_tree(roots))
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
# 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
elif not os.path.isfile(ofile):
print 'File %r does not exist, not printing.' % ofile
else:
# Print only text files, not extension binaries.
page(self.format(open(ofile).read()),lineno)
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:
ds = "Alias to the system command:\n %s" % obj[1]
else:
ds = getdoc(obj)
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 ??)
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
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
try:
file = inspect.getabsfile(obj)
if file.endswith('<string>'):
file = 'Dynamically generated function. No source code available.'
out.writeln(header('File:\t\t') + file)
except:
pass
# 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))
# Original source code for any callable
if detail_level:
# Flush the source cache because inspect can return out-of-date source
linecache.checkcache()
try:
source = self.format(inspect.getsource(obj))
out.write(header('Source:\n') + source.rstrip())
except:
if ds:
out.writeln(header('Docstring:\n') + indent(ds))
# Constructor docstring for classes
if obj_type is types.ClassType:
# 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:
elif obj_type is types.InstanceType:
# 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__)
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__)
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__'):
out.writeln(header('Callable:\t') + 'Yes')
call_def = self.__getdef(obj.__call__, oname)
if call_def is None:
out.write(
header('Call def:\t') +
'Calling definition not available.')
else:
out.write(header('Call def:\t') + self.format(call_def))
call_ds = getdoc(obj.__call__)
if call_ds:
out.writeln(header('Call docstring:\n') + indent(call_ds))
# Finally send to printer/pager
output = out.getvalue()
if output:
page(output)
def xmidas_hlp(self, arg):
"""Tutorial on using IPython with XMidas/XMPY"""
from IPython.genutils import page
page(IXMPY_SUMMARY)
class Inspector:
def __init__(self,
color_table,
code_color_table,
scheme,
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)
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:
print
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 = ''
if inspect.isclass(obj):
header = self.__head('Class constructor information:\n')
obj = obj.__init__
elif type(obj) is types.InstanceType:
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."""
head = self.__head # so that itpl can find it even if private
ds = getdoc(obj)
if formatter:
ds = formatter(ds)
if inspect.isclass(obj):
init_ds = getdoc(obj.__init__)
output = itpl('$head("Class Docstring:")\n'
'$indent(ds)\n'
'$head("Constructor Docstring"):\n'
'$indent(init_ds)')
elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
and hasattr(obj,'__call__'):
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:
src = getsource(obj)
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
# 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
elif not os.path.isfile(ofile):
print 'File %r does not exist, not printing.' % ofile
else:
# Print only text files, not extension binaries.
page(self.format(open(ofile).read()), lineno)
#page(self.format(open(inspect.getabsfile(obj)).read()),lineno)
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:
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)
# 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 ??)
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
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
binary_file = False
try:
fname = inspect.getabsfile(obj)
if fname.endswith('<string>'):
fname = 'Dynamically generated function. No source code available.'
if (fname.endswith('.so') or fname.endswith('.dll')):
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
# 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))
# Original source code for any callable
if detail_level:
# Flush the source cache because inspect can return out-of-date
# source
linecache.checkcache()
source_success = False
try:
source = self.format(getsource(obj, binary_file))
if source:
out.write(header('Source:\n') + source.rstrip())
source_success = True
except Exception, msg:
pass
if ds and not source_success:
out.writeln(
header('Docstring [source file open failed]:\n') +
indent(ds))
# Constructor docstring for classes
if inspect.isclass(obj):
# 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:
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:
elif obj_type is types.InstanceType or \
isinstance(obj,object):
# 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:
out.writeln(
header('Class Docstring:\n') + indent(class_ds))
# 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:
out.writeln(
header('Constructor Docstring:\n') + indent(init_ds))
# Call form docstring for callable instances
if hasattr(obj, '__call__'):
#out.writeln(header('Callable:\t')+'Yes')
call_def = self.__getdef(obj.__call__, oname)
#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))
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:
out.writeln(header('Call docstring:\n') + indent(call_ds))
# Finally send to printer/pager
output = out.getvalue()
if output:
page(output)
except SystemExit:
message = """*** SystemExit exception caught in code being profiled."""
except KeyboardInterrupt:
message = ("*** KeyboardInterrupt exception caught in code being "
"profiled.")
finally:
if had_profile:
__builtin__.__dict__['profile'] = old_profile
# Trap text output.
stdout_trap = StringIO()
profile.print_stats(stdout_trap)
output = stdout_trap.getvalue()
output = output.rstrip()
page(output, screen_lines=self.shell.rc.screen_length)
print message,
dump_file = opts.D[0]
if dump_file:
profile.dump_stats(dump_file)
print '\n*** Profile stats pickled to file',\
`dump_file`+'.',message
text_file = opts.T[0]
if text_file:
pfile = open(text_file, 'w')
pfile.write(output)
pfile.close()
print '\n*** Profile printout saved to text file',\
`text_file`+'.',message
def magic_lprun(self, parameter_s=''):
""" Execute a statement under the line-by-line profiler from the
line_profiler module.
Usage:
%lprun -f func1 -f func2 <statement>
The given statement (which doesn't require quote marks) is run via the
LineProfiler. Profiling is enabled for the functions specified by the -f
options. The statistics will be shown side-by-side with the code through the
pager once the statement has completed.
Options:
-f <function>: LineProfiler only profiles functions and methods it is told
to profile. This option tells the profiler about these functions. Multiple
-f options may be used. The argument may be any expression that gives
a Python function or method object. However, one must be careful to avoid
spaces that may confuse the option parser. Additionally, functions defined
in the interpreter at the In[] prompt or via %run currently cannot be
displayed. Write these functions out to a separate file and import them.
-m <module>: Get all the functions/methods in a module
One or more -f or -m options are required to get any useful results.
-D <filename>: dump the raw statistics out to a pickle file on disk. The
usual extension for this is ".lprof". These statistics may be viewed later
by running line_profiler.py as a script.
-T <filename>: dump the text-formatted statistics with the code side-by-side
out to a text file.
-r: return the LineProfiler object after it has completed profiling.
-s: strip out all entries from the print-out that have zeros.
"""
# Local imports to avoid hard dependency.
from distutils.version import LooseVersion
import IPython
ipython_version = LooseVersion(IPython.__version__)
if ipython_version < '0.11':
from IPython.genutils import page
from IPython.ipstruct import Struct
from IPython.ipapi import UsageError
else:
from IPython.core.page import page
from IPython.utils.ipstruct import Struct
from IPython.core.error import UsageError
# Escape quote markers.
opts_def = Struct(D=[''], T=[''], f=[], m=[])
parameter_s = parameter_s.replace('"', r'\"').replace("'", r"\'")
opts, arg_str = self.parse_options(parameter_s,
'rsf:m:D:T:',
list_all=True)
opts.merge(opts_def)
global_ns = self.shell.user_global_ns
local_ns = self.shell.user_ns
# Get the requested functions.
funcs = []
for name in opts.f:
try:
funcs.append(eval(name, global_ns, local_ns))
except Exception as e:
raise UsageError('Could not find function %r.\n%s: %s' %
(name, e.__class__.__name__, e))
profile = LineProfiler(*funcs)
# Get the modules, too
for modname in opts.m:
try:
mod = __import__(modname, fromlist=[''])
profile.add_module(mod)
except Exception as e:
raise UsageError('Could not find module %r.\n%s: %s' %
(modname, e.__class__.__name__, e))
# Add the profiler to the builtins for @profile.
if PY3:
import builtins
else:
import __builtin__ as builtins
if 'profile' in builtins.__dict__:
had_profile = True
old_profile = builtins.__dict__['profile']
else:
had_profile = False
old_profile = None
builtins.__dict__['profile'] = profile
try:
try:
profile.runctx(arg_str, global_ns, local_ns)
message = ''
except SystemExit:
message = """*** SystemExit exception caught in code being profiled."""
except KeyboardInterrupt:
message = ("*** KeyboardInterrupt exception caught in code being "
"profiled.")
finally:
if had_profile:
builtins.__dict__['profile'] = old_profile
# Trap text output.
stdout_trap = StringIO()
profile.print_stats(stdout_trap, stripzeros='s' in opts)
output = stdout_trap.getvalue()
output = output.rstrip()
if ipython_version < '0.11':
page(output, screen_lines=self.shell.rc.screen_length)
else:
page(output)
print(message, end="")
dump_file = opts.D[0]
if dump_file:
profile.dump_stats(dump_file)
print('\n*** Profile stats pickled to file %r. %s' %
(dump_file, message))
text_file = opts.T[0]
if text_file:
pfile = open(text_file, 'w')
pfile.write(output)
pfile.close()
print('\n*** Profile printout saved to text file %r. %s' %
(text_file, message))
return_value = None
if 'r' in opts:
return_value = profile
return return_value
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('Documentation:\n') + indent(init_ds))
# Finally send to printer/pager
output = out.getvalue()
if output:
page(output)
# end pinfo
def page(strng, start=0, screen_lines=0, pager_cmd=None):
'''Non-paging page implementation to provide a non-paging Q-Shell
'''
#This comes from IPython.genutils.page
str_lines = strng.split(os.linesep)[start:]
str_toprint = os.linesep.join(str_lines)
print >> IPython.genutils.Term.cout, str_toprint
class Shell:
'''pylabs-customized IPython shell class'''
def magic_mprun(self, parameter_s=''):
""" Execute a statement under the line-by-line memory profiler from the
memory_profilser module.
Usage:
%mprun -f func1 -f func2 <statement>
The given statement (which doesn't require quote marks) is run via the
LineProfiler. Profiling is enabled for the functions specified by the -f
options. The statistics will be shown side-by-side with the code through
the pager once the statement has completed.
Options:
-f <function>: LineProfiler only profiles functions and methods it is told
to profile. This option tells the profiler about these functions. Multiple
-f options may be used. The argument may be any expression that gives
a Python function or method object. However, one must be careful to avoid
spaces that may confuse the option parser. Additionally, functions defined
in the interpreter at the In[] prompt or via %run currently cannot be
displayed. Write these functions out to a separate file and import them.
One or more -f options are required to get any useful results.
-T <filename>: dump the text-formatted statistics with the code
side-by-side out to a text file.
-r: return the LineProfiler object after it has completed profiling.
"""
try:
from StringIO import StringIO
except ImportError: # Python 3.x
from io import StringIO
# Local imports to avoid hard dependency.
from distutils.version import LooseVersion
import IPython
ipython_version = LooseVersion(IPython.__version__)
if ipython_version < '0.11':
from IPython.genutils import page
from IPython.ipstruct import Struct
from IPython.ipapi import UsageError
else:
from IPython.core.page import page
from IPython.utils.ipstruct import Struct
from IPython.core.error import UsageError
# Escape quote markers.
opts_def = Struct(T=[''], f=[])
parameter_s = parameter_s.replace('"', r'\"').replace("'", r"\'")
opts, arg_str = self.parse_options(parameter_s, 'rf:T:', list_all=True)
opts.merge(opts_def)
global_ns = self.shell.user_global_ns
local_ns = self.shell.user_ns
# Get the requested functions.
funcs = []
for name in opts.f:
try:
funcs.append(eval(name, global_ns, local_ns))
except Exception as e:
raise UsageError('Could not find function %r.\n%s: %s' % (name,
e.__class__.__name__, e))
profile = LineProfiler()
for func in funcs:
profile(func)
# Add the profiler to the builtins for @profile.
try:
import builtins
except ImportError: # Python 3x
import __builtin__ as builtins
if 'profile' in builtins.__dict__:
had_profile = True
old_profile = builtins.__dict__['profile']
else:
had_profile = False
old_profile = None
builtins.__dict__['profile'] = profile
try:
try:
profile.runctx(arg_str, global_ns, local_ns)
message = ''
except SystemExit:
message = "*** SystemExit exception caught in code being profiled."
except KeyboardInterrupt:
message = ("*** KeyboardInterrupt exception caught in code being "
"profiled.")
finally:
if had_profile:
builtins.__dict__['profile'] = old_profile
# Trap text output.
stdout_trap = StringIO()
show_results(profile, stdout_trap)
output = stdout_trap.getvalue()
output = output.rstrip()
if ipython_version < '0.11':
page(output, screen_lines=self.shell.rc.screen_length)
else:
page(output)
print(message,)
text_file = opts.T[0]
if text_file:
with open(text_file, 'w') as pfile:
pfile.write(output)
print('\n*** Profile printout saved to text file %s. %s' % (text_file,
message))
return_value = None
if 'r' in opts:
return_value = profile
return return_value
def showcfg(self, arg):
"""Prints all ipapi options"""
from IPython.genutils import page
import pprint
opts = pprint.pformat(IPython.ipapi.get().options)
page(opts)
def magic_lprun(self, parameter_s=''):
""" Execute a statement under the line-by-line profiler from the
line_profiler module.
Usage:
%lprun -f func1 -f func2 <statement>
The given statement (which doesn't require quote marks) is run via the
LineProfiler. Profiling is enabled for the functions specified by the -f
options. The statistics will be shown side-by-side with the code through the
pager once the statement has completed.
Options:
-f <function>: LineProfiler only profiles functions and methods it is told
to profile. This option tells the profiler about these functions. Multiple
-f options may be used. The argument may be any expression that gives
a Python function or method object. However, one must be careful to avoid
spaces that may confuse the option parser. Additionally, functions defined
in the interpreter at the In[] prompt or via %run currently cannot be
displayed. Write these functions out to a separate file and import them.
-m <module>: Get all the functions/methods in a module
One or more -f or -m options are required to get any useful results.
-D <filename>: dump the raw statistics out to a pickle file on disk. The
usual extension for this is ".lprof". These statistics may be viewed later
by running line_profiler.py as a script.
-T <filename>: dump the text-formatted statistics with the code side-by-side
out to a text file.
-r: return the LineProfiler object after it has completed profiling.
-s: strip out all entries from the print-out that have zeros.
"""
# Local imports to avoid hard dependency.
from distutils.version import LooseVersion
import IPython
ipython_version = LooseVersion(IPython.__version__)
if ipython_version < '0.11':
from IPython.genutils import page
from IPython.ipstruct import Struct
from IPython.ipapi import UsageError
else:
from IPython.core.page import page
from IPython.utils.ipstruct import Struct
from IPython.core.error import UsageError
# Escape quote markers.
opts_def = Struct(D=[''], T=[''], f=[], m=[])
parameter_s = parameter_s.replace('"', r'\"').replace("'", r"\'")
opts, arg_str = self.parse_options(parameter_s, 'rsf:m:D:T:', list_all=True)
opts.merge(opts_def)
global_ns = self.shell.user_global_ns
local_ns = self.shell.user_ns
# Get the requested functions.
funcs = []
for name in opts.f:
try:
funcs.append(eval(name, global_ns, local_ns))
except Exception as e:
raise UsageError('Could not find function %r.\n%s: %s' % (name,
e.__class__.__name__, e))
profile = LineProfiler(*funcs)
# Get the modules, too
for modname in opts.m:
try:
mod = __import__(modname, fromlist=[''])
profile.add_module(mod)
except Exception as e:
raise UsageError('Could not find module %r.\n%s: %s' % (name,
e.__class__.__name__, e))
# Add the profiler to the builtins for @profile.
if PY3:
import builtins
else:
import __builtin__ as builtins
if 'profile' in builtins.__dict__:
had_profile = True
old_profile = builtins.__dict__['profile']
else:
had_profile = False
old_profile = None
builtins.__dict__['profile'] = profile
try:
try:
profile.runctx(arg_str, global_ns, local_ns)
message = ''
except SystemExit:
message = """*** SystemExit exception caught in code being profiled."""
except KeyboardInterrupt:
message = ("*** KeyboardInterrupt exception caught in code being "
"profiled.")
finally:
if had_profile:
builtins.__dict__['profile'] = old_profile
# Trap text output.
stdout_trap = StringIO()
profile.print_stats(stdout_trap, stripzeros='s' in opts)
output = stdout_trap.getvalue()
output = output.rstrip()
if ipython_version < '0.11':
page(output, screen_lines=self.shell.rc.screen_length)
else:
page(output)
print(message, end="")
dump_file = opts.D[0]
if dump_file:
profile.dump_stats(dump_file)
print('\n*** Profile stats pickled to file %r. %s' % (
dump_file, message))
text_file = opts.T[0]
if text_file:
pfile = open(text_file, 'w')
pfile.write(output)
pfile.close()
print('\n*** Profile printout saved to text file %r. %s' % (
text_file, message))
return_value = None
if 'r' in opts:
return_value = profile
return return_value
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('Documentation:\n') + indent(init_ds))
# Finally send to printer/pager
output = out.getvalue()
if output:
page(output)
# end pinfo
def page(strng,start=0,screen_lines=0,pager_cmd = None):
'''Non-paging page implementation to provide a non-paging Q-Shell
'''
#This comes from IPython.genutils.page
str_lines = strng.split(os.linesep)[start:]
str_toprint = os.linesep.join(str_lines)
print >>IPython.genutils.Term.cout, str_toprint
class Shell:
'''pylabs-customized IPython shell class'''
def mprun(self, parameter_s='', cell=None):
""" Execute a statement under the line-by-line memory profiler from the
memory_profiler module.
Usage, in line mode:
%mprun -f func1 -f func2 <statement>
Usage, in cell mode:
%%mprun -f func1 -f func2 [statement]
code...
code...
In cell mode, the additional code lines are appended to the (possibly
empty) statement in the first line. Cell mode allows you to easily
profile multiline blocks without having to put them in a separate
function.
The given statement (which doesn't require quote marks) is run via the
LineProfiler. Profiling is enabled for the functions specified by the -f
options. The statistics will be shown side-by-side with the code through
the pager once the statement has completed.
Options:
-f <function>: LineProfiler only profiles functions and methods it is told
to profile. This option tells the profiler about these functions. Multiple
-f options may be used. The argument may be any expression that gives
a Python function or method object. However, one must be careful to avoid
spaces that may confuse the option parser. Additionally, functions defined
in the interpreter at the In[] prompt or via %run currently cannot be
displayed. Write these functions out to a separate file and import them.
One or more -f options are required to get any useful results.
-T <filename>: dump the text-formatted statistics with the code
side-by-side out to a text file.
-r: return the LineProfiler object after it has completed profiling.
-c: If present, add the memory usage of any children process to the report.
"""
from io import StringIO
from memory_profiler import show_results, LineProfiler
# Local imports to avoid hard dependency.
from distutils.version import LooseVersion
import IPython
ipython_version = LooseVersion(IPython.__version__)
if ipython_version < '0.11':
from IPython.genutils import page
from IPython.ipstruct import Struct
from IPython.ipapi import UsageError
else:
from IPython.core.page import page
from IPython.utils.ipstruct import Struct
from IPython.core.error import UsageError
# Escape quote markers.
opts_def = Struct(T=[''], f=[])
parameter_s = parameter_s.replace('"', r'\"').replace("'", r"\'")
opts, arg_str = self.parse_options(parameter_s, 'rf:T:c',
list_all=True)
opts.merge(opts_def)
global_ns = self.shell.user_global_ns
local_ns = self.shell.user_ns
if cell is not None:
arg_str += '\n' + cell
# Get the requested functions.
funcs = []
for name in opts.f:
try:
funcs.append(eval(name, global_ns, local_ns))
except Exception as e:
raise UsageError('Could not find function %r.\n%s: %s' % (name,
e.__class__.__name__,
e))
include_children = 'c' in opts
profile = LineProfiler(include_children=include_children)
for func in funcs:
profile(func)
# Add the profiler to the builtins for @profile.
if 'profile' in builtins.__dict__:
had_profile = True
old_profile = builtins.__dict__['profile']
else:
had_profile = False
old_profile = None
builtins.__dict__['profile'] = profile
try:
profile.runctx(arg_str, global_ns, local_ns)
message = ''
except SystemExit:
message = "*** SystemExit exception caught in code being profiled."
except KeyboardInterrupt:
message = ("*** KeyboardInterrupt exception caught in code being "
"profiled.")
finally:
if had_profile:
builtins.__dict__['profile'] = old_profile
# Trap text output.
stdout_trap = StringIO()
show_results(profile, stdout_trap)
output = stdout_trap.getvalue()
output = output.rstrip()
if ipython_version < '0.11':
page(output, screen_lines=self.shell.rc.screen_length)
else:
page(output)
print(message, )
text_file = opts.T[0]
if text_file:
with open(text_file, 'w') as pfile:
pfile.write(output)
print('\n*** Profile printout saved to text file %s. %s' % (
text_file,
message))
return_value = None
if 'r' in opts:
return_value = profile
return return_value
message = """*** SystemExit exception caught in code being profiled."""
except KeyboardInterrupt:
message = ("*** KeyboardInterrupt exception caught in code being "
"profiled.")
finally:
if had_profile:
__builtin__.__dict__['profile'] = old_profile
# Trap text output.
stdout_trap = StringIO()
profile.print_stats(stdout_trap)
output = stdout_trap.getvalue()
output = output.rstrip()
if ipython_version < '0.11':
page(output, screen_lines=self.shell.rc.screen_length)
else:
page(output)
print message,
dump_file = opts.D[0]
if dump_file:
profile.dump_stats(dump_file)
print '\n*** Profile stats pickled to file',\
`dump_file`+'.',message
text_file = opts.T[0]
if text_file:
pfile = open(text_file, 'w')
pfile.write(output)
pfile.close()
