def splitdocfor(path):
"""split the docstring for a path
valid paths are::
./path/to/module.py
./path/to/module.py:SomeClass.method
returns (description, long_description) from the docstring for path
or (None, None) if there isn't a docstring.
Example::
>>> splitdocfor("./wsgi_intercept/__init__.py")[0]
'installs a WSGI application in place of a real URI for testing.'
>>> splitdocfor("./wsgi_intercept/__init__.py:WSGI_HTTPConnection.get_app")[0]
'Return the app object for the given (host, port).'
>>>
"""
if ":" in path:
filename, objpath = path.split(':')
else:
filename, objpath = path, None
inspector = DocInspector(filename)
visitor.walk(compiler.parseFile(filename), inspector)
if objpath is None:
if inspector.top_level_doc is None:
return None, None
return pydoc.splitdoc(inspector.top_level_doc)
else:
if inspector[objpath] is None:
return None, None
return pydoc.splitdoc(inspector[objpath])
def splitdocfor(path):
"""split the docstring for a path
valid paths are::
./path/to/module.py
./path/to/module.py:SomeClass.method
returns (description, long_description) from the docstring for path
or (None, None) if there isn't a docstring.
Example::
>>> splitdocfor("./wsgi_intercept/__init__.py")[0]
'installs a WSGI application in place of a real URI for testing.'
>>> splitdocfor("./wsgi_intercept/__init__.py:WSGI_HTTPConnection.get_app")[0]
'Return the app object for the given (host, port).'
>>>
"""
if ":" in path:
filename, objpath = path.split(':')
else:
filename, objpath = path, None
inspector = DocInspector(filename)
visitor.walk(compiler.parseFile(filename), inspector)
if objpath is None:
if inspector.top_level_doc is None:
return None, None
return pydoc.splitdoc(inspector.top_level_doc)
else:
if inspector[objpath] is None:
return None, None
return pydoc.splitdoc(inspector[objpath])
def include_docstring(
name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
"""include reStructuredText from a docstring. use the directive like:
| .. include_docstring:: path.to.module
| .. include_docstring:: path.to.module:SomeClass
| .. include_docstring:: path.to.module:SomeClass.method
"""
rawpath = arguments[0]
obj = get_object_from_path(rawpath)
source = inspect.getdoc(obj)
if hasattr(obj, '__module__'):
mod = obj.__module__
else:
mod = obj # big assumption :/
doctest.run_docstring_examples(source, mod.__dict__)
if source is None:
raise ValueError("cannot find docstring for %s" % obj)
summary, body = pydoc.splitdoc(source)
# nabbed from docutils.parsers.rst.directives.misc.include
include_lines = statemachine.string2lines(body, convert_whitespace=1)
state_machine.insert_input(include_lines, None)
return []
def setup(args=None):
# make sure our directory is at the front of sys.path
module = metadata('backupmgr')
# get the version and description from the source
version = module.__version__
description = pydoc.splitdoc(pydoc.getdoc(module))[0]
author, author_email = email.utils.parseaddr(module.__authors__[0])
# get the long description from README-type files
long_description = []
for path in READMES:
with open(os.path.join(SRCROOT, path), 'r') as fh:
long_description.append(fh.read())
long_description = '\n'.join([ x for x in long_description if x ])
# use setuptools to do the rest
setuptools.setup(
name=pkg_resources.safe_name(module.__name__),
packages=setuptools.find_packages(),
version=version,
description=description,
author=author,
author_email=author_email,
zip_safe=True,
#url=None,
install_requires=["python-dateutil"],
long_description=long_description,
license='BSD',
classifiers=[
'Development Status :: 3 - Alpha',
'Intended Audience :: Developers'
])
def hh(cmd=None):
"""Get help on a command."""
shell_funcs['hh'] = hh
import pydoc
from inspect import getargspec, formatargspec
if not cmd:
print "\nUse addrspace() for Kernel/Virtual AS"
print "Use addrspace().base for Physical AS"
print "Use proc() to get the current process object"
print " and proc().get_process_address_space() for the current process AS"
print " and proc().get_load_modules() for the current process DLLs\n"
for f in sorted(shell_funcs):
doc = pydoc.getdoc(shell_funcs[f])
synop, _full = pydoc.splitdoc(doc)
print "{0:40} : {1}".format(
f + formatargspec(*getargspec(shell_funcs[f])), synop)
print "\nFor help on a specific command, type 'hh(<command>)'"
elif type(cmd) == str:
try:
doc = pydoc.getdoc(shell_funcs[cmd])
except KeyError:
print "No such command: {0}".format(cmd)
return
print doc
else:
doc = pydoc.getdoc(cmd)
print doc
def display_module(module, stream, level, args):
print "module " + module.__name__
synopsis, doc = pydoc.splitdoc(inspect.getdoc(module) or "")
title(stream, level, ":mod:`" + module.__name__ + "` --- " + synopsis)
stream.write(".. module:: " + module.__name__ + "\n :synopsis: " + synopsis + "\n\n")
stream.write(doc or "")
# stream.write("\n\n.. contents:: Things\n :depth: 1\n :local:\n\n")
if hasattr(module, "__all__"):
names = module.__all__
else:
names = sorted(dir(module))
for name in names:
thing = getattr(module, name)
if isinstance(thing, types.FunctionType):
continue
if should_document_module_member(name, thing, module):
if isinstance(thing, type):
display_class(thing, stream, level + 1, args)
elif isinstance(thing, types.FunctionType):
display_function(thing, stream, level + 1, args)
else:
print " Unknown type, skipping {}".format(name)
function_names = [n for n in names if isinstance(getattr(module, n), types.FunctionType) and should_document_module_member(n, getattr(module, n), module)]
if function_names:
title(stream, level + 1, "Functions")
for name in function_names:
thing = getattr(module, name)
display_function(thing, stream, level + 2, args, name)
def hh(cmd = None):
"""Get help on a command."""
shell_funcs['hh'] = hh
import pydoc
from inspect import getargspec, formatargspec
if not cmd:
print "\nUse self.addrspace for Kernel/Virtual AS"
print "Use self.addrspace.base for Physical AS"
print "Use self.proc to get the current _EPROCESS object"
print " and self.proc.get_process_address_space() for the current process AS"
print " and self.proc.get_load_modules() for the current process DLLs\n"
for f in sorted(shell_funcs):
doc = pydoc.getdoc(shell_funcs[f])
synop, _full = pydoc.splitdoc(doc)
print "{0:40} : {1}".format(f + formatargspec(*getargspec(shell_funcs[f])), synop)
print "\nFor help on a specific command, type 'hh(<command>)'"
elif type(cmd) == str:
try:
doc = pydoc.getdoc(shell_funcs[cmd])
except KeyError:
print "No such command: {0}".format(cmd)
return
print doc
else:
doc = pydoc.getdoc(cmd)
print doc
def _sig_fallback(obj, parent, doc):
"""
Look for the signature in the synopsis line.
Check if the synopsis line is a signature and extract it if so. Ensure that
the extracted signature has the `self` parameter if `parent` is a class.
Args:
obj (routine): Routine in need of signature.
parent (class): Parent class or module of `obj`.
doc (str): Docstring of `obj`.
Returns:
tuple: (signature, docstring)
"""
path = get_path(parent, obj)
syn, rem = pydoc.splitdoc(doc)
match = re.match(r"([\w\.]+)\((.*)\)", syn)
if match:
sig = match[2]
if inspect.isclass(parent):
if sig and not sig.startswith("self"):
sig = f"self, {sig}"
elif not sig.startswith("self"):
sig = "self"
sig = f"({sig})"
results = (sig, rem)
logger.debug("Found signature for `%s` using fallback.", path)
else:
doc = "\n".join((syn, rem)).strip(WHITESPACE)
results = ("(...)", doc)
logger.debug("Could not find signature for `%s`.", path)
return results
def main():
usage = __import__(__name__).__doc__.strip()
usage += "\n\nCommands:\n\n"
commands = {}
for func in sorted(COMMANDS):
name = func.__name__.strip().replace("cmd_", "").replace("_", "-")
commands[name] = func
head, tail = pydoc.splitdoc(pydoc.getdoc(func))
cmd_help = textwrap.fill(tail, width=70).replace("\n", "\n ").strip()
usage += "%s\n %s\n\n" % (head, cmd_help)
usage = usage.strip()
parser = OptionParser(usage=usage)
parser.allow_interspersed_args = False
(options, args) = parser.parse_args()
if len(args) < 1:
parser.error("No command given")
cmd_name = args.pop(0)
cmd = commands.get(cmd_name)
if cmd is None:
parser.error("Unknown command %s" % cmd_name)
else:
cmd(args)
def setup(args=None):
# make sure our directory is at the front of sys.path
module = metadata('backupmgr')
# get the version and description from the source
version = module.__version__
description = pydoc.splitdoc(pydoc.getdoc(module))[0]
author, author_email = email.utils.parseaddr(module.__authors__[0])
# get the long description from README-type files
long_description = []
for path in READMES:
with open(os.path.join(SRCROOT, path), 'r') as fh:
long_description.append(fh.read())
long_description = '\n'.join([ x for x in long_description if x ])
# use setuptools to do the rest
setuptools.setup(
name=pkg_resources.safe_name(module.__name__),
packages=setuptools.find_packages(),
version=version,
description=description,
author=author,
author_email=author_email,
zip_safe=True,
#url=None,
install_requires=["python-dateutil"],
long_description=long_description,
license='BSD',
classifiers=[
'Development Status :: 3 - Alpha',
'Intended Audience :: Developers'
])
def __init__(self, task):
self._parser = None
self._dests = None
self.task = task
self.dargs = []
self.oargs = []
if task.__doc__:
self.desc, self.long_desc = pydoc.splitdoc(task.__doc__)
else:
self.desc, self.long_desc = "", ""
prog = os.path.basename(getattr(task, "_path_", task._name_))
mgrname = self.task.parent.get_managerattr("name")
self.prog = mgrname + " " + prog[-20:]
self.usage = None
self.description = self.desc
self.epilog = ""
self.parents = []
self.formatter_class = argparse.RawDescriptionHelpFormatter
self.add_help = True
def get_module_meta(modfile):
docstring = None
version = [(tokenize.NAME, '__version__'), (tokenize.OP, '=')]
f = open(modfile,'r')
for toknum, tokval, _, _, _ in tokenize.generate_tokens(lambda: f.readline()):
if not docstring:
if toknum == tokenize.STRING:
docstring = tokval
continue
if len(version):
if (toknum, tokval) == version[0]:
version.pop(0)
else:
version = tokval
break
if docstring is None:
raise ValueError("could not find docstring in %s" % modfile)
if not isinstance(version, basestring):
raise ValueError("could not find __version__ in %s" % modfile)
# unquote :
docstring = docstring[3:]
docstring = docstring[:-3]
version = version[1:]
version = version[:-1]
return (version,) + pydoc.splitdoc(docstring)
def synopsis(foo):
"""
Return a functions short description
"""
import pydoc
doc = foo.func_doc
s = pydoc.splitdoc(doc)[0]
return s
def module_section(self, obj, package_context ):
"""Create a module-links section for the given object (module)"""
modules = inspect.getmembers(obj, inspect.ismodule)
package_context.clean(modules, obj)
package_context.recurse_scan(modules)
if hasattr(obj, '__path__'):
modpkgs = []
modnames = []
for file in os.listdir(obj.__path__[0]):
path = os.path.join(obj.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modnames:
modpkgs.append((modname, obj.__name__, 0, 0))
modnames.append(modname)
elif pydoc.ispackage(path):
modpkgs.append((file, obj.__name__, 1, 0))
modpkgs.sort()
# do more recursion here...
for (modname, name, ya, yo) in modpkgs:
package_context.add_interesting('.'.join((obj.__name__, modname)))
items = []
for (modname, name, ispackage, is_shadowed) in modpkgs:
try:
# get the actual module obj...
#if modname == "events":
# import pdb
# pdb.set_trace()
module = pydoc.safeimport('{0}.{1}'.format(name, modname))
description, documentation = pydoc.splitdoc(inspect.getdoc(module))
if description:
items.append(
'{0} -- {1}'.format(
self.modpkglink((modname, name, ispackage, is_shadowed)),
description,
)
)
else:
items.append(
self.modpkglink((modname, name, ispackage, is_shadowed))
)
except:
items.append(
self.modpkglink((modname, name, ispackage, is_shadowed))
)
contents = '<br>'.join(items)
result = self.bigsection(
'Package Contents', '#ffffff', '#aa55cc', contents)
elif modules:
contents = self.multicolumn(
modules,
lambda a: self.modulelink(a[1])
)
result = self.bigsection(
'Modules', '#fffff', '#aa55cc', contents)
else:
result = ""
return result
def get_module_meta(modfile):
ast = compiler.parseFile(modfile)
modnode = ModuleVisitor()
visitor.walk(ast, modnode)
if modnode.mod_doc is None:
raise RuntimeError("could not parse doc string from %s" % modfile)
if modnode.mod_version is None:
raise RuntimeError("could not parse __version__ from %s" % modfile)
return (modnode.mod_version, ) + pydoc.splitdoc(modnode.mod_doc)
def moduleSection( self, object, packageContext ): """Create a module-links section for the given object (module)""" modules = inspect.getmembers(object, inspect.ismodule) packageContext.clean ( modules, object ) packageContext.recurseScan( modules ) if hasattr(object, '__path__'): modpkgs = [] modnames = [] for file in os.listdir(object.__path__[0]): path = os.path.join(object.__path__[0], file) modname = inspect.getmodulename(file) if modname and modname not in modnames: modpkgs.append((modname, object.__name__, 0, 0)) modnames.append(modname) elif pydoc.ispackage(path): modpkgs.append((file, object.__name__, 1, 0)) modpkgs.sort() # do more recursion here... for (modname, name, ya,yo) in modpkgs: packageContext.addInteresting( join( (object.__name__, modname), '.')) items = [] for (modname, name, ispackage,isshadowed) in modpkgs: try: # get the actual module object... ## if modname == "events": ## import pdb ## pdb.set_trace() module = pydoc.safeimport( "%s.%s"%(name,modname) ) description, documentation = pydoc.splitdoc( inspect.getdoc( module )) if description: items.append( """%s -- %s"""% ( self.modpkglink( (modname, name, ispackage, isshadowed) ), description, ) ) else: items.append( self.modpkglink( (modname, name, ispackage, isshadowed) ) ) except: items.append( self.modpkglink( (modname, name, ispackage, isshadowed) ) ) contents = string.join( items, '<br>') result = self.bigsection( 'Package Contents', '#ffffff', '#aa55cc', contents) elif modules: contents = self.multicolumn( modules, lambda (key, value), s=self: s.modulelink(value)) result = self.bigsection( 'Modules', '#fffff', '#aa55cc', contents) else: result = "" return result
def moduleSection(self, object, packageContext):
"""Create a module-links section for the given object (module)"""
modules = inspect.getmembers(object, inspect.ismodule)
packageContext.clean(modules, object)
packageContext.recurseScan(modules)
if hasattr(object, '__path__'):
modpkgs = []
modnames = []
for file in os.listdir(object.__path__[0]):
path = os.path.join(object.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modnames:
modpkgs.append((modname, object.__name__, 0, 0))
modnames.append(modname)
elif pydoc.ispackage(path):
modpkgs.append((file, object.__name__, 1, 0))
modpkgs.sort()
# do more recursion here...
for (modname, name, ya, yo) in modpkgs:
packageContext.addInteresting(
join((object.__name__, modname), '.'))
items = []
for (modname, name, ispackage, isshadowed) in modpkgs:
try:
# get the actual module object...
## if modname == "events":
## import pdb
## pdb.set_trace()
module = pydoc.safeimport("%s.%s" % (name, modname))
description, documentation = pydoc.splitdoc(
inspect.getdoc(module))
if description:
items.append("""%s -- %s""" % (
self.modpkglink(
(modname, name, ispackage, isshadowed)),
description,
))
else:
items.append(
self.modpkglink(
(modname, name, ispackage, isshadowed)))
except:
items.append(
self.modpkglink(
(modname, name, ispackage, isshadowed)))
contents = string.join(items, '<br>')
result = self.bigsection('Package Contents', '#ffffff', '#aa55cc',
contents)
elif modules:
contents = self.multicolumn(
modules, lambda (key, value), s=self: s.modulelink(value))
result = self.bigsection('Modules', '#fffff', '#aa55cc', contents)
else:
result = ""
return result
def module_section(self, obj, package_context):
"""Create a module-links section for the given object (module)"""
modules = inspect.getmembers(obj, inspect.ismodule)
package_context.clean(modules, obj)
package_context.recurse_scan(modules)
if hasattr(obj, '__path__'):
modpkgs = []
modnames = []
for file in os.listdir(obj.__path__[0]):
path = os.path.join(obj.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modnames:
modpkgs.append((modname, obj.__name__, 0, 0))
modnames.append(modname)
elif pydoc.ispackage(path):
modpkgs.append((file, obj.__name__, 1, 0))
modpkgs.sort()
# do more recursion here...
for (modname, name, ya, yo) in modpkgs:
package_context.add_interesting('.'.join(
(obj.__name__, modname)))
items = []
for (modname, name, ispackage, is_shadowed) in modpkgs:
try:
# get the actual module obj...
#if modname == "events":
# import pdb
# pdb.set_trace()
module = pydoc.safeimport('{0}.{1}'.format(name, modname))
description, documentation = pydoc.splitdoc(
inspect.getdoc(module))
if description:
items.append('{0} -- {1}'.format(
self.modpkglink(
(modname, name, ispackage, is_shadowed)),
description,
))
else:
items.append(
self.modpkglink(
(modname, name, ispackage, is_shadowed)))
except:
items.append(
self.modpkglink(
(modname, name, ispackage, is_shadowed)))
contents = '<br>'.join(items)
result = self.bigsection('Package Contents', '#ffffff', '#aa55cc',
contents)
elif modules:
contents = self.multicolumn(modules,
lambda a: self.modulelink(a[1]))
result = self.bigsection('Modules', '#fffff', '#aa55cc', contents)
else:
result = ""
return result
def formatDocString(self, doc):
doc = pydoc.splitdoc(doc)
bodylines = doc[1].splitlines()
body = ""
for idx, line in enumerate(bodylines):
if len(line) == 0:
body += "\n"
body += line.strip() + " "
ret = "%s\n\n%s" % (doc[0], body)
return ret.strip()
def formatDocString(self, doc):
doc = pydoc.splitdoc(doc)
bodylines = doc[1].splitlines()
body = ""
for idx, line in enumerate(bodylines):
if len(line) == 0:
body += "\n"
body += line.strip() + " "
ret = "%s\n\n%s" % (doc[0], body)
return ret.strip()
def get_module_meta(modfile):
ast = compiler.parseFile(modfile)
modnode = ModuleVisitor()
visitor.walk(ast, modnode)
if modnode.mod_doc is None:
raise RuntimeError(
"could not parse doc string from %s" % modfile)
if modnode.mod_version is None:
raise RuntimeError(
"could not parse __version__ from %s" % modfile)
return (modnode.mod_version,) + pydoc.splitdoc(modnode.mod_doc)
def build_help_cb(bot, *args, **kwargs):
'''
Build the help overview so it can be cached and poked at from shell.
'''
global HELP_OVERVIEW
HELP_OVERVIEW += 'Available commands:\n'
for category in sorted(COMMAND_CATEGORIES):
if category:
HELP_OVERVIEW += '- {}:\n'.format(category)
for command in sorted(COMMAND_CATEGORIES[category]):
HELP_OVERVIEW += '{}: {}\n'.format(
command[0], pydoc.splitdoc(command[2].__doc__)[0])
def docmodule(self, module, name=None, *args) -> str:
"""Produce text documentation for a given module object.
"""
name = name or module.__name__
synopsis, description = pydoc.splitdoc(pydoc.getdoc(module))
synopsis = self.__clean(self.__escape(synopsis))
description = self.__clean(self.__escape(description))
doc_loc = self.getdocloc(module)
packages, package_names = self.__get_module_packages(module)
submodules = self.__get_module_submodules(module, name, package_names)
classes = self.__get_module_classes(module)
functions = self.__get_module_functions(module)
data = self.__get_module_data(module)
return '%s%s%s%s%s%s%s%s%s%s%s%s%s' % (
self._section(self._create_module_name_heading(name),
self._create_module_name_content(synopsis)),
self._section(self._create_module_doc_loc_heading(),
self._create_module_doc_loc_content(doc_loc))
if doc_loc is not None else '',
self._section(self._create_module_description_heading(),
self._create_module_description_content(description))
if description else '',
self._section(self._create_module_packages_heading(),
self._create_module_packages_content(packages))
if packages else '',
self._section(self._create_module_submodules_heading(),
self._create_module_submodules_content(submodules))
if submodules else '',
self._section(
self._create_module_classes_heading(),
self._create_module_classes_content(module, name, classes))
if classes else '',
self._section(
self._create_module_functions_heading(),
self._create_module_functions_content(name, functions))
if functions else '',
self._section(self._create_module_data_heading(
), self._create_module_data_content(name, data)) if data else '',
self._section(self._create_module_version_heading(),
self._create_module_version_content(module))
if hasattr(module, '__version__') else '',
self._section(self._create_module_date_heading(),
self._create_module_date_content(module)) if hasattr(
module, '__date__') else '',
self._section(self._create_module_author_heading(),
self._create_module_author_content(module))
if hasattr(module, '__author__') else '',
self._section(self._create_module_credits_heading(),
self._create_module_credits_content(module))
if hasattr(module, '__credits__') else '',
self._section(self._create_module_file_heading(),
self._create_module_file_content(module)))
def build_help_cb(bot, *args, **kwargs):
'''
Build the help overview so it can be cached and poked at from shell.
'''
global HELP_OVERVIEW
HELP_OVERVIEW += 'Available commands:\n'
for category in sorted(COMMAND_CATEGORIES):
if category:
HELP_OVERVIEW += '- {}:\n'.format(category)
for command in sorted(COMMAND_CATEGORIES[category]):
HELP_OVERVIEW += '{}: {}\n'.format(
command[0],
pydoc.splitdoc(command[2].__doc__)[0])
def _default_optparse(cmd, args, option_list=[], indoc=False, outfile=False,
nargs=None, syspath=False):
if indoc:
option_list += [
make_option("-i", action="store", dest="infile", type="str",
help="input file, '-' means stdin, '--' means empty input file (default)",
default="--")
]
if outfile:
option_list += [
make_option("-o", action="store", dest="outfile", type="str",
help="output file, '-' means stdout (default)",
default="-")
]
if syspath:
option_list += [
make_option("-s", "--sys-path", action="store", dest="path",
type="str", default=None,
help="prepend paths to sys.path")
]
head, tail = pydoc.splitdoc(pydoc.getdoc(cmd))
p = OptionParser(usage="pydoc-tool.py %s\n\n%s" % (head, tail),
option_list=option_list)
opts, args = p.parse_args(args)
if nargs is not None:
if len(args) != nargs:
p.error("wrong number of arguments")
if outfile:
if opts.outfile == '-':
opts.outfile = sys.stdout
else:
opts.outfile = open(opts.outfile, 'w')
if indoc:
if opts.infile == '--':
opts.indoc = Documentation()
elif opts.infile == '-':
opts.indoc = Documentation.load(sys.stdin)
else:
opts.indoc = Documentation.load(open(opts.infile, 'r'))
if syspath:
if opts.path is not None:
sys.path = [os.path.abspath(x)
for x in opts.path.split(os.path.pathsep)] + sys.path
return opts, args, p
def get_whitelisted_methods(
imported_class: object, ) -> typeGenerator[Tuple[str, object], None, None]:
"""Provides the method_name and a reference to the method itself for every Public API method in a class.
Args:
imported_class: the class object that needs to be checked for Public API methods.
Yields:
A tuple consisting of the name of a Public API method and a reference to the method itself.
"""
methods = dict(inspect.getmembers(imported_class, inspect.isroutine))
for method_name, class_method in methods.items():
synopsis, desc = pydoc.splitdoc(pydoc.getdoc(class_method))
if is_included_in_public_api(desc):
yield method_name, class_method
def split_doc_from_module(modfile):
docstring = None
f = open(modfile,'r')
for toknum, tokval, _, _, _ in tokenize.generate_tokens(lambda: f.readline()):
if toknum == tokenize.STRING:
docstring = tokval
break
if toknum not in (tokenize.NL, tokenize.COMMENT):
# we went too far
break
if docstring is None:
raise ValueError("could not find docstring in %s" % modfile)
docstring = docstring[3:]
docstring = docstring[:-3]
return pydoc.splitdoc(docstring)
def split_doc_from_module(modfile):
docstring = None
f = open(modfile,'r')
for toknum, tokval, _, _, _ in tokenize.generate_tokens(lambda: f.readline()):
if toknum == tokenize.STRING:
docstring = tokval
break
if toknum not in (tokenize.NL, tokenize.COMMENT):
# we went too far
break
if docstring is None:
raise ValueError("could not find docstring in %s" % modfile)
docstring = docstring[3:]
docstring = docstring[:-3]
return pydoc.splitdoc(docstring)
def _lines(name, title, tasks):
lines = [title]
lines.append("-" * len(title))
for task in sorted(tasks):
docs = tasks[task].__doc__
if docs:
lines.append("{0:10} : {1}".format(task,
pydoc.splitdoc(docs)[0]))
else:
lines.append("{0:10} : {0}".format(task))
return lines
def gather_classes_to_document(
import_path: str, ) -> typeGenerator[Tuple[str, object], None, None]:
"""Get all the class names and object references for Public API classes in a given module.
Args:
import_path: the import statement for the module to parse.
Yields:
A tuple consisting of the class name and a reference for the class itself for all Public API classes in the
provided module.
"""
module = importlib.import_module(import_path)
imported_classes = dict(inspect.getmembers(module, inspect.isclass))
for class_name, imported_class in imported_classes.items():
synopsis, desc = pydoc.splitdoc(pydoc.getdoc(imported_class))
if is_included_in_public_api(desc):
yield class_name, imported_class
def import_testplx(path, manager, argv, subargv):
if argv is None:
argv = []
if subargv is None:
subargv = []
if not os.path.isfile(path):
raise UsageError("PlX Task '%s' is not found."
" Please check plx path." % str(path))
PlXTest._plx_ = plx = PlXTestTask(manager)
plx._setup(path)
prog = os.path.basename(getattr(plx, "_path_", plx._name_))
plx._parser.prog = plx.get_mgrname() + " " + prog[-20:]
if hasattr(plx, "__doc__") and plx.__doc__:
plx._parser.desc, plx._parser.long_desc = pydoc.splitdoc(
plx.__doc__)
super(PlXTask, plx).run(argv, subargv=subargv)
del PlXTest._setups[:]
del PlXTest._teardowns[:]
# create test methods
for hdr, body in plx.plx_sections:
if hdr.endswith("*"):
if hdr.startswith("setup"):
PlXTest._setups.append(partial(PlXTest._test_template, header=hdr[:-1], body=body))
elif hdr.startswith("teardown"):
PlXTest._teardowns.append(partial(PlXTest._test_template, header=hdr[:-1], body=body))
else:
setattr(PlXTest, "test_%s" % hdr.replace("@", "_"),
partial(PlXTest._test_template, header=hdr, body=body))
import imp
mod = imp.new_module("")
setattr(mod, "PlXTest", PlXTest)
return mod
def docclass(self, clazz, name=None, mod=None, level=1, *args) -> str:
"""Produce text documentation for a given class object.
"""
name = name or clazz.__name__
synopsis, description = pydoc.splitdoc(pydoc.getdoc(clazz))
synopsis = self.__clean(self.__escape(synopsis))
description = self.__clean(self.__escape(description))
mro = deque(inspect.getmro(clazz))
attrs = self.__get_clazz_attributes(clazz)
return '%s%s%s' % (
self._section(
self._create_class_name_heading(clazz, name),
self._create_class_name_content(synopsis, description), level),
# List the mro, if non-trivial.
self.__doc_class_mro(clazz, mro) if len(mro) > 2 else '',
self.__newline.join([
self.__docclass_attribute(clazz, mod, attr) for attr in attrs
]))
def run(self, argv, subargv=None, forward=None):
if not argv:
raise UsageError("PlX Task is not found."
" Please check plx path.")
elif not os.path.isfile(argv[0]):
raise UsageError("PlX Task '%s' is not found."
" Please check plx path." % str(argv[0]))
self._setup(argv[0])
prog = os.path.basename(getattr(self, "_path_", self._name_))
self._parser.prog = self.get_mgrname() + " " + prog[-20:]
if hasattr(self, "__doc__") and self.__doc__:
self._parser.desc, self._parser.long_desc = pydoc.splitdoc(
self.__doc__)
return super(PlXTask, self).run(argv[1:],
subargv=subargv,
forward=forward)
def hh(cmd=None):
"""Get help on a command."""
shell_funcs['hh'] = hh
import pydoc
from inspect import getargspec, formatargspec
if not cmd:
for f in shell_funcs:
doc = pydoc.getdoc(shell_funcs[f])
synop, full = pydoc.splitdoc(doc)
print "%-40s : %s" % (f + formatargspec(*getargspec(shell_funcs[f])), synop)
print
print "For help on a specific command, type 'hh(<command>)'"
elif type(cmd) == str:
try:
doc = pydoc.getdoc(shell_funcs[cmd])
except KeyError:
print "No such command: %s" % cmd
return
print doc
else:
doc = pydoc.getdoc(cmd)
print doc
def makedocindex():
"""
Return a string with GPI Index.
"""
import pydoc
sections = {}
from Ganga.Utility.strings import ItemizedTextParagraph
for sec, names in zip(_GPIhelp_sections.keys(), _GPIhelp_sections.values()):
itbuf = ItemizedTextParagraph(sec + ":")
for name, obj, docstring in names:
# if docstring not provided when exporting the object to GPI then use the docstring generated by pydoc
if not docstring:
docstring = pydoc.splitdoc(pydoc.getdoc(obj))[0]
itbuf.addLine(name, docstring)
sections[sec] = itbuf.getString()
return _GPIhelp % sections
def hh(cmd = None):
"""Get help on a command."""
shell_funcs['hh'] = hh
import pydoc
from inspect import getargspec, formatargspec
if not cmd:
for f in shell_funcs:
doc = pydoc.getdoc(shell_funcs[f])
synop, _full = pydoc.splitdoc(doc)
print("{0:40} : {1}".format(f + formatargspec(*getargspec(shell_funcs[f])), synop))
print()
print("For help on a specific command, type 'hh(<command>)'")
elif type(cmd) == str:
try:
doc = pydoc.getdoc(shell_funcs[cmd])
except KeyError:
print("No such command: {0}".format(cmd))
return
print(doc)
else:
doc = pydoc.getdoc(cmd)
print(doc)
def hh(cmd=None):
"""Get help on a command."""
shell_funcs['hh'] = hh
import pydoc
from inspect import getargspec, formatargspec
if not cmd:
for f in shell_funcs:
doc = pydoc.getdoc(shell_funcs[f])
synop, full = pydoc.splitdoc(doc)
print "%-40s : %s" % (
f + formatargspec(*getargspec(shell_funcs[f])), synop)
print
print "For help on a specific command, type 'hh(<command>)'"
elif type(cmd) == str:
try:
doc = pydoc.getdoc(shell_funcs[cmd])
except KeyError:
print "No such command: %s" % cmd
return
print doc
else:
doc = pydoc.getdoc(cmd)
print doc
def hh(cmd=None):
"""Get help on a command."""
shell_funcs['hh'] = hh
import pydoc
from inspect import getargspec, formatargspec
if not cmd:
for f in shell_funcs:
doc = pydoc.getdoc(shell_funcs[f])
synop, _full = pydoc.splitdoc(doc)
print("{0:40} : {1}".format(
f + formatargspec(*getargspec(shell_funcs[f])), synop))
print()
print("For help on a specific command, type 'hh(<command>)'")
elif type(cmd) == str:
try:
doc = pydoc.getdoc(shell_funcs[cmd])
except KeyError:
print("No such command: {0}".format(cmd))
return
print(doc)
else:
doc = pydoc.getdoc(cmd)
print(doc)
def functionToParameterDict(self, function, **overrides):
"""
Converts a function into a list of child parameter dicts
"""
children = []
out = dict(name=function.__name__, type="group", children=children)
if self.title is not None:
out["title"] = self._nameToTitle(function.__name__,
forwardStrTitle=True)
funcParams = inspect.signature(function).parameters
if function.__doc__:
# Reasonable "tip" default is the brief docstring description if it exists
synopsis, _ = pydoc.splitdoc(function.__doc__)
if synopsis:
out.setdefault("tip", synopsis)
# Make pyqtgraph parameter dicts from each parameter
# Use list instead of funcParams.items() so kwargs can add to the iterable
checkNames = list(funcParams)
isKwarg = [p.kind is p.VAR_KEYWORD for p in funcParams.values()]
if any(isKwarg):
# Function accepts kwargs, so any overrides not already present as a function
# parameter should be accepted
# Remove the keyword parameter since it can't be parsed properly
# Only one kwarg can be in the signature, so there will be only one
# "True" index
del checkNames[isKwarg.index(True)]
notInSignature = [n for n in overrides if n not in checkNames]
checkNames.extend(notInSignature)
for name in checkNames:
# May be none if this is an override name after function accepted kwargs
param = funcParams.get(name)
pgDict = self.createFunctionParameter(name, param,
overrides.get(name, {}))
children.append(pgDict)
return out
def display_module(module, stream, level, args):
print "module " + module.__name__
synopsis, doc = pydoc.splitdoc(inspect.getdoc(module) or "")
title(stream, level, ":mod:`" + module.__name__ + "` --- " + synopsis)
stream.write(".. module:: " + module.__name__ + "\n :synopsis: " + synopsis + "\n\n")
stream.write(doc or "")
# stream.write("\n\n.. contents:: Things\n :depth: 1\n :local:\n\n")
for name in sorted(dir(module)):
thing = getattr(module, name)
if isinstance(thing, types.FunctionType):
continue
if should_document_module_member(name, thing, module):
if isinstance(thing, type):
display_class(thing, stream, level + 1, args)
elif isinstance(thing, types.FunctionType):
display_function(thing, stream, level + 1, args)
else:
print " Unknown type, skipping {}".format(name)
function_names = [n for n in sorted(dir(module)) if isinstance(getattr(module, n), types.FunctionType) and should_document_module_member(n, getattr(module, n), module)]
if function_names:
title(stream, level + 1, "Functions")
for name in function_names:
thing = getattr(module, name)
display_function(thing, stream, level + 2, args, name)
def test_splitdoc_with_description(self):
example_string = "I Am A Doc\n\n\nHere is my description"
self.assertEqual(pydoc.splitdoc(example_string),
('I Am A Doc', '\nHere is my description'))
def make_argparser(name, fn, target_args, always):
"""Generate an option parser based on the function arguments
Arguments:
name(str): the function name (used in help output)
fn(function): the function
target_args(int): how many function arguments will be provided by the
target class, and not from the command line
always(bool): if false, add the --force option
Returns:
a meta function which takes command line arguments.
"""
docs = pydoc.getdoc(fn)
syn, rest = pydoc.splitdoc(docs)
parser = ArgumentParser(sys.argv[0] + " " + name, description=syn)
helps, typs = parsedoc(rest)
# print helps, rest
if not always:
parser.add_argument("--force", "-f", help="run even if all dependencies are satisfied", action="store_true")
argspec = inspect.getargspec(fn)
pos, opt = parse_argspec(argspec, target_args)
for arg in pos:
t = typs.get(arg, str)
if t == "fflag":
parser.add_argument(arg, help=helps.get(arg, None), action="store_true")
elif t == "tflag":
parser.add_argument(arg, help=helps.get(arg, None), action="store_false")
else:
parser.add_argument(arg, help=helps.get(arg, None), type=typs.get(arg, str))
shorts = []
argnames = {}
for arg, default in opt:
if arg[0] in shorts:
argnames[arg] = ["--" + arg]
else:
shorts.append(arg[0])
argnames[arg] = ["--" + arg, "-" + arg[0]]
for arg, default in opt:
t = typs.get(arg, str)
if t == "fflag":
parser.add_argument(*argnames[arg], dest=arg, help=helps.get(arg, None), action="store_true")
elif t == "tflag":
parser.add_argument(*argnames[arg], dest=arg, help=helps.get(arg, None), action="store_false")
else:
parser.add_argument(
*argnames[arg], dest=arg, default=default, help=helps.get(arg, None), type=typs.get(arg, str)
)
if argspec.varargs:
parser.add_argument(
"--" + argspec.varargs, nargs="*", help=helps.get(argspec.varargs, None), type=typs.get(arg, str)
)
def meta(args):
"""Convert command-line arguments into *args and **kwargs for the function
Arguments:
args[str]: command-line arguments
Returns:
pargs[args]: positional arguments
dargs(dict): optional keyword arguments
res: the "Namespace" object with all the arguments together
"""
res = parser.parse_args(args)
dct = vars(res)
pargs = list(dct[i] for i in pos)
dargs = dict((i, dct[i]) for i, j in opt)
return pargs, dargs, res
return meta
fromlist_expects_type = str
if sys.version_info < (3, 0):
fromlist_expects_type = bytes
main_module_name = 'daemon'
main_module_fromlist = list(map(fromlist_expects_type, [
'_metadata']))
main_module = __import__(
main_module_name,
level=0, fromlist=main_module_fromlist)
metadata = main_module._metadata
(synopsis, long_description) = pydoc.splitdoc(pydoc.getdoc(main_module))
version_info = metadata.get_distribution_version_info()
version_string = version_info['version']
(maintainer_name, maintainer_email) = metadata.parse_person_field(
version_info['maintainer'])
setup(
name=metadata.distribution_name,
version=version_string,
packages=find_packages(exclude=["test"]),
cmdclass={
"write_version_info": version.WriteVersionInfoCommand,
"egg_info": version.EggInfoCommand,
with open('setup.cfg', 'w') as setup_cfg:
setup_cfg.write('[global]\n')
setup_cfg.write('version=' + self.version)
_sdist.run(self)
os.remove('setup.cfg')
if self.release_responsible:
for archive in self.get_archive_files():
print('Publishing %s to savannahh..' % archive)
subprocess.call([
'scp', archive,
'%[email protected]:/releases/%s/' %
(self.release_responsible, traydevice.__name__)
])
docs = pydoc.splitdoc(traydevice.__doc__)
class Distribution(_Distribution):
def parse_config_files(self, filenames=None):
_Distribution.parse_config_files(self, filenames)
self.metadata.version = self.version
pass
if __name__ == '__main__':
setup(distclass=Distribution,
cmdclass={
build.__name__: build,
build_manpage.__name__: build_manpage,
install_manpage.__name__: install_manpage,
def docmodule(self, obj, name=None, mod=None):
"""Produce markdown documentation for a given module obj."""
name = obj.__name__ # ignore the passed-in name
synop, desc = pydoc.splitdoc(pydoc.getdoc(obj))
result = self.section('NAME', name.replace(r'_', r'\_') + (synop and ' - ' + synop))
try:
moduleall = obj.__all__
except AttributeError:
moduleall = None
try:
filepath = os.path.dirname(inspect.getabsfile(obj))
except TypeError:
filepath = '(built-in)'
result = result + self.section('FILE', '`'+filepath+'`')
docloc = self.getdocloc(obj)
if docloc is not None:
result = result + self.section('MODULE DOCS', docloc)
if desc:
result = result + self.section('DESCRIPTION', desc)
if hasattr(obj, '__version__'):
version = pydoc._binstr(obj.__version__)
if version[:11] == '$Revision: ' and version[-1:] == '$':
version = version[11:-1].strip()
result = result + self.section('VERSION', version)
if hasattr(obj, '__date__'):
result = result + self.section('DATE', pydoc._binstr(obj.__date__))
if hasattr(obj, '__author__'):
result = result + self.section('AUTHOR', pydoc._binstr(obj.__author__))
if hasattr(obj, '__credits__'):
result = result + self.section('CREDITS', pydoc._binstr(obj.__credits__))
classes = []
for key, value in inspect.getmembers(obj, inspect.isclass):
# if __all__ exists, believe it. Otherwise use old heuristic.
if moduleall is not None or (inspect.getmodule(value) or obj) is obj:
if pydoc.visiblename(key, moduleall, obj):
classes.append((key, value))
funcs = []
for key, value in inspect.getmembers(obj, inspect.isroutine):
# if __all__ exists, believe it. Otherwise use old heuristic.
if moduleall is not None or inspect.isbuiltin(value) or inspect.getmodule(value) is obj:
if pydoc.visiblename(key, moduleall, obj):
funcs.append((key, value))
data = []
for key, value in inspect.getmembers(obj, pydoc.isdata):
if pydoc.visiblename(key, moduleall, obj):
data.append((key, value))
modules = []
for key, _ in inspect.getmembers(obj, inspect.ismodule):
modules.append(key)
if modules:
modules = sorted(modules)
contents = ', '.join(['[%s](https://www.google.com/#q=python+%s)' % (m, m) for m in modules]) + '\n{: .lead}'
result = result + self.section('MODULES', contents)
modpkgs = []
modpkgs_names = set()
if hasattr(obj, '__path__'):
for _, modname, ispkg in pkgutil.iter_modules(obj.__path__):
modpkgs_names.add(modname)
if ispkg:
modpkgs.append(modname + ' (package)')
else:
modpkgs.append(modname)
modpkgs.sort()
result = result + self.section('PACKAGE CONTENTS', pydoc.join(modpkgs, '\n'))
# Detect submodules as sometimes created by C extensions
submodules = []
for key, value in inspect.getmembers(obj, inspect.ismodule):
if value.__name__.startswith(name + '.') and key not in modpkgs_names:
submodules.append(key)
if submodules:
submodules.sort()
result = result + self.section('SUBMODULES', pydoc.join(submodules, '\n'))
if funcs:
contents = []
for key, value in funcs:
contents.append(self.document(value, key, name))
result = result + self.section('FUNCTIONS', pydoc.join(contents, '\n'))
if classes:
classlist = [x[1] for x in classes]
contents = [self.formattree(inspect.getclasstree(classlist, 1), name)]
for key, value in classes:
contents.append(self.document(value, key, name))
result = result + self.section('CLASSES', pydoc.join(contents, '\n'))
if data:
contents = []
for key, value in data:
contents.append(self.docother(value, key, name))
result = result + self.section('DATA', pydoc.join(contents, '\n'))
return result
def info(object=None,maxwidth=76,output=sys.stdout,toplevel='numpy'):
"""
Get help information for a function, class, or module.
Parameters
----------
object : object or str, optional
Input object or name to get information about. If `object` is a
numpy object, its docstring is given. If it is a string, available
modules are searched for matching objects.
If None, information about `info` itself is returned.
maxwidth : int, optional
Printing width.
output : file like object, optional
File like object that the output is written to, default is ``stdout``.
The object has to be opened in 'w' or 'a' mode.
toplevel : str, optional
Start search at this level.
See Also
--------
source, lookfor
Notes
-----
When used interactively with an object, ``np.info(obj)`` is equivalent to
``help(obj)`` on the Python prompt or ``obj?`` on the IPython prompt.
Examples
--------
>>> np.info(np.polyval) # doctest: +SKIP
polyval(p, x)
Evaluate the polynomial p at x.
...
When using a string for `object` it is possible to get multiple results.
>>> np.info('fft') # doctest: +SKIP
*** Found in numpy ***
Core FFT routines
...
*** Found in numpy.fft ***
fft(a, n=None, axis=-1)
...
*** Repeat reference found in numpy.fft.fftpack ***
*** Total of 3 references found. ***
"""
global _namedict, _dictlist
# Local import to speed up numpy's import time.
import pydoc, inspect
if hasattr(object,'_ppimport_importer') or \
hasattr(object, '_ppimport_module'):
object = object._ppimport_module
elif hasattr(object, '_ppimport_attr'):
object = object._ppimport_attr
if object is None:
info(info)
elif isinstance(object, ndarray):
import numpy.numarray as nn
nn.info(object, output=output, numpy=1)
elif isinstance(object, str):
if _namedict is None:
_namedict, _dictlist = _makenamedict(toplevel)
numfound = 0
objlist = []
for namestr in _dictlist:
try:
obj = _namedict[namestr][object]
if id(obj) in objlist:
print >> output, "\n *** Repeat reference found in %s *** " % namestr
else:
objlist.append(id(obj))
print >> output, " *** Found in %s ***" % namestr
info(obj)
print >> output, "-"*maxwidth
numfound += 1
except KeyError:
pass
if numfound == 0:
print >> output, "Help for %s not found." % object
else:
print >> output, "\n *** Total of %d references found. ***" % numfound
elif inspect.isfunction(object):
name = object.func_name
arguments = inspect.formatargspec(*inspect.getargspec(object))
if len(name+arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
print >> output, inspect.getdoc(object)
elif inspect.isclass(object):
name = object.__name__
arguments = "()"
try:
if hasattr(object, '__init__'):
arguments = inspect.formatargspec(*inspect.getargspec(object.__init__.im_func))
arglist = arguments.split(', ')
if len(arglist) > 1:
arglist[1] = "("+arglist[1]
arguments = ", ".join(arglist[1:])
except:
pass
if len(name+arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
doc1 = inspect.getdoc(object)
if doc1 is None:
if hasattr(object,'__init__'):
print >> output, inspect.getdoc(object.__init__)
else:
print >> output, inspect.getdoc(object)
methods = pydoc.allmethods(object)
if methods != []:
print >> output, "\n\nMethods:\n"
for meth in methods:
if meth[0] == '_':
continue
thisobj = getattr(object, meth, None)
if thisobj is not None:
methstr, other = pydoc.splitdoc(inspect.getdoc(thisobj) or "None")
print >> output, " %s -- %s" % (meth, methstr)
elif type(object) is types.InstanceType: ## check for __call__ method
print >> output, "Instance of class: ", object.__class__.__name__
print >> output
if hasattr(object, '__call__'):
arguments = inspect.formatargspec(*inspect.getargspec(object.__call__.im_func))
arglist = arguments.split(', ')
if len(arglist) > 1:
arglist[1] = "("+arglist[1]
arguments = ", ".join(arglist[1:])
else:
arguments = "()"
if hasattr(object,'name'):
name = "%s" % object.name
else:
name = "<name>"
if len(name+arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
doc = inspect.getdoc(object.__call__)
if doc is not None:
print >> output, inspect.getdoc(object.__call__)
print >> output, inspect.getdoc(object)
else:
print >> output, inspect.getdoc(object)
elif inspect.ismethod(object):
name = object.__name__
arguments = inspect.formatargspec(*inspect.getargspec(object.im_func))
arglist = arguments.split(', ')
if len(arglist) > 1:
arglist[1] = "("+arglist[1]
arguments = ", ".join(arglist[1:])
else:
arguments = "()"
if len(name+arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
print >> output, inspect.getdoc(object)
elif hasattr(object, '__doc__'):
print >> output, inspect.getdoc(object)
def get_module_description(module):
"""Return a description of the number."""
doc = pydoc.splitdoc(pydoc.getdoc(module))[1]
# remove the doctests
return _strip_doctest_re.sub('', doc[1]).strip(),
def docmodule(self, object, name=None, mod=None):
''' Produce text documentation for a given module object.
'''
name = object.__name__ # ignore the passed-in name
synop, desc = pydoc.splitdoc(pydoc.getdoc(object))
result = self.section('Name', name + (synop and ' - ' + synop))
if desc:
result = result + self.section('Description', desc)
classes = []
for key, value in inspect.getmembers(object, inspect.isclass):
if (inspect.getmodule(value) or object) is object:
classes.append((key, value))
funcs = []
for key, value in inspect.getmembers(object, inspect.isroutine):
if inspect.isbuiltin(value) or inspect.getmodule(value) is object:
funcs.append((key, value))
if hasattr(object, '__path__'):
modpkgs = []
for file in os.listdir(object.__path__[0]):
path = os.path.join(object.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modpkgs:
modpkgs.append(modname)
elif pydoc.ispackage(path):
modpkgs.append(file + ' (package)')
modpkgs.sort()
result = result + self.section(
'Package contents', '\n'.join(modpkgs))
if classes:
classlist = map(lambda (key, value): value, classes)
classes_tree = self.formattree(inspect.getclasstree(classlist, 1), name)
if classes_tree:
classes_tree = '```text\n%s\n```\n' % classes_tree
result = result + self.section('Classes Tree', classes_tree)
contents = []
for key, value in classes:
contents.append(self.document(value, key, name))
result = result + self.section('Classes', '\n'.join(contents))
if funcs:
contents = []
for key, value in funcs:
contents.append(self.document(value, key, name))
result = result + self.section('Functions', '\n'.join(contents))
if hasattr(object, '__version__'):
version = str(object.__version__)
if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
version = strip(version[11:-1])
result = result + self.section('Version', version)
if hasattr(object, '__date__'):
result = result + self.section('Date', str(object.__date__))
if hasattr(object, '__author__'):
result = result + self.section('Author', str(object.__author__))
if hasattr(object, '__credits__'):
result = result + self.section('Credits', str(object.__credits__))
return result
def get_module_name(module):
"""Return the short description of the number."""
return pydoc.splitdoc(pydoc.getdoc(module))[0].strip('.')
def get_module_name(module):
"""Return the short description of the number."""
return pydoc.splitdoc(pydoc.getdoc(module))[0].strip('.')
def info(object=None,maxwidth=76,output=sys.stdout,toplevel='numpy'):
"""
Get help information for a function, class, or module.
Parameters
----------
object : optional
Input object to get information about.
maxwidth : int, optional
Printing width.
output : file like object open for writing, optional
Write into file like object.
toplevel : string, optional
Start search at this level.
Examples
--------
>>> np.info(np.polyval) # doctest: +SKIP
polyval(p, x)
Evaluate the polymnomial p at x.
...
"""
global _namedict, _dictlist
# Local import to speed up numpy's import time.
import pydoc, inspect
if hasattr(object,'_ppimport_importer') or \
hasattr(object, '_ppimport_module'):
object = object._ppimport_module
elif hasattr(object, '_ppimport_attr'):
object = object._ppimport_attr
if object is None:
info(info)
elif isinstance(object, ndarray):
import numpy.numarray as nn
nn.info(object, output=output, numpy=1)
elif isinstance(object, str):
if _namedict is None:
_namedict, _dictlist = _makenamedict(toplevel)
numfound = 0
objlist = []
for namestr in _dictlist:
try:
obj = _namedict[namestr][object]
if id(obj) in objlist:
print >> output, "\n *** Repeat reference found in %s *** " % namestr
else:
objlist.append(id(obj))
print >> output, " *** Found in %s ***" % namestr
info(obj)
print >> output, "-"*maxwidth
numfound += 1
except KeyError:
pass
if numfound == 0:
print >> output, "Help for %s not found." % object
else:
print >> output, "\n *** Total of %d references found. ***" % numfound
elif inspect.isfunction(object):
name = object.func_name
arguments = inspect.formatargspec(*inspect.getargspec(object))
if len(name+arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
print >> output, inspect.getdoc(object)
elif inspect.isclass(object):
name = object.__name__
arguments = "()"
try:
if hasattr(object, '__init__'):
arguments = inspect.formatargspec(*inspect.getargspec(object.__init__.im_func))
arglist = arguments.split(', ')
if len(arglist) > 1:
arglist[1] = "("+arglist[1]
arguments = ", ".join(arglist[1:])
except:
pass
if len(name+arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
doc1 = inspect.getdoc(object)
if doc1 is None:
if hasattr(object,'__init__'):
print >> output, inspect.getdoc(object.__init__)
else:
print >> output, inspect.getdoc(object)
methods = pydoc.allmethods(object)
if methods != []:
print >> output, "\n\nMethods:\n"
for meth in methods:
if meth[0] == '_':
continue
thisobj = getattr(object, meth, None)
if thisobj is not None:
methstr, other = pydoc.splitdoc(inspect.getdoc(thisobj) or "None")
print >> output, " %s -- %s" % (meth, methstr)
elif type(object) is types.InstanceType: ## check for __call__ method
print >> output, "Instance of class: ", object.__class__.__name__
print >> output
if hasattr(object, '__call__'):
arguments = inspect.formatargspec(*inspect.getargspec(object.__call__.im_func))
arglist = arguments.split(', ')
if len(arglist) > 1:
arglist[1] = "("+arglist[1]
arguments = ", ".join(arglist[1:])
else:
arguments = "()"
if hasattr(object,'name'):
name = "%s" % object.name
else:
name = "<name>"
if len(name+arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
doc = inspect.getdoc(object.__call__)
if doc is not None:
print >> output, inspect.getdoc(object.__call__)
print >> output, inspect.getdoc(object)
else:
print >> output, inspect.getdoc(object)
elif inspect.ismethod(object):
name = object.__name__
arguments = inspect.formatargspec(*inspect.getargspec(object.im_func))
arglist = arguments.split(', ')
if len(arglist) > 1:
arglist[1] = "("+arglist[1]
arguments = ", ".join(arglist[1:])
else:
arguments = "()"
if len(name+arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
print >> output, inspect.getdoc(object)
elif hasattr(object, '__doc__'):
print >> output, inspect.getdoc(object)
def test_splitdoc_with_description(self):
example_string = "I Am A Doc\n\n\nHere is my description"
self.assertEqual(pydoc.splitdoc(example_string),
('I Am A Doc', '\nHere is my description'))
def get_module_description(module):
"""Return a description of the number."""
doc = pydoc.splitdoc(pydoc.getdoc(module))[1]
# remove the doctests
return _strip_doctest_re.sub('', doc[1]).strip(),
def run(self):
summary, doc = pydoc.splitdoc(wsgi_intercept.__doc__)
wikidoc = publish_string(doc, writer=WikiWriter())
print wikidoc
def info(object=None, maxwidth=76, output=sys.stdout):
"""Get help information for a function, class, or module.
Example:
>>> from scipy import *
>>> info(polyval)
polyval(p, x)
Evaluate the polymnomial p at x.
Description:
If p is of length N, this function returns the value:
p[0]*(x**N-1) + p[1]*(x**N-2) + ... + p[N-2]*x + p[N-1]
"""
global _namedict, _dictlist
if hasattr(object, "_ppimport_importer") or hasattr(object, "_ppimport_module"):
object = object._ppimport_module
elif hasattr(object, "_ppimport_attr"):
object = object._ppimport_attr
if object is None:
info(info)
elif isinstance(object, types.StringType):
if _namedict is None:
_namedict, _dictlist = makenamedict()
numfound = 0
objlist = []
for namestr in _dictlist:
try:
obj = _namedict[namestr][object]
if id(obj) in objlist:
print >> output, "\n *** Repeat reference found in %s *** " % namestr
else:
objlist.append(id(obj))
print >> output, " *** Found in %s ***" % namestr
info(obj)
print >> output, "-" * maxwidth
numfound += 1
except KeyError:
pass
if numfound == 0:
print >> output, "Help for %s not found." % object
else:
print >> output, "\n *** Total of %d references found. ***" % numfound
elif inspect.isfunction(object):
name = object.func_name
arguments = apply(inspect.formatargspec, inspect.getargspec(object))
if len(name + arguments) > maxwidth:
argstr = split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
print >> output, inspect.getdoc(object)
elif inspect.isclass(object):
name = object.__name__
if hasattr(object, "__init__"):
arguments = apply(inspect.formatargspec, inspect.getargspec(object.__init__.im_func))
arglist = arguments.split(", ")
if len(arglist) > 1:
arglist[1] = "(" + arglist[1]
arguments = ", ".join(arglist[1:])
else:
arguments = "()"
else:
arguments = "()"
if len(name + arguments) > maxwidth:
argstr = split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
doc1 = inspect.getdoc(object)
if doc1 is None:
if hasattr(object, "__init__"):
print >> output, inspect.getdoc(object.__init__)
else:
print >> output, inspect.getdoc(object)
methods = pydoc.allmethods(object)
if methods != []:
print >> output, "\n\nMethods:\n"
for meth in methods:
if meth[0] == "_":
continue
thisobj = getattr(object, meth, None)
if thisobj is not None:
methstr, other = pydoc.splitdoc(inspect.getdoc(thisobj) or "None")
print >> output, " %s -- %s" % (meth, methstr)
elif type(object) is types.InstanceType: ## check for __call__ method
print >> output, "Instance of class: ", object.__class__.__name__
print >> output
if hasattr(object, "__call__"):
arguments = apply(inspect.formatargspec, inspect.getargspec(object.__call__.im_func))
arglist = arguments.split(", ")
if len(arglist) > 1:
arglist[1] = "(" + arglist[1]
arguments = ", ".join(arglist[1:])
else:
arguments = "()"
if hasattr(object, "name"):
name = "%s" % object.name
else:
name = "<name>"
if len(name + arguments) > maxwidth:
argstr = split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
doc = inspect.getdoc(object.__call__)
if doc is not None:
print >> output, inspect.getdoc(object.__call__)
print >> output, inspect.getdoc(object)
else:
print >> output, inspect.getdoc(object)
elif inspect.ismethod(object):
name = object.__name__
arguments = apply(inspect.formatargspec, inspect.getargspec(object.im_func))
arglist = arguments.split(", ")
if len(arglist) > 1:
arglist[1] = "(" + arglist[1]
arguments = ", ".join(arglist[1:])
else:
arguments = "()"
if len(name + arguments) > maxwidth:
argstr = split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print >> output, " " + argstr + "\n"
print >> output, inspect.getdoc(object)
elif hasattr(object, "__doc__"):
print >> output, inspect.getdoc(object)
def info(object=None, maxwidth=76, output=sys.stdout, toplevel='numpy'):
"""
Get help information for a function, class, or module.
Parameters
----------
object : object or str, optional
Input object or name to get information about. If `object` is a
numpy object, its docstring is given. If it is a string, available
modules are searched for matching objects. If None, information
about `info` itself is returned.
maxwidth : int, optional
Printing width.
output : file like object, optional
File like object that the output is written to, default is
``stdout``. The object has to be opened in 'w' or 'a' mode.
toplevel : str, optional
Start search at this level.
See Also
--------
source, lookfor
Notes
-----
When used interactively with an object, ``np.info(obj)`` is equivalent
to ``help(obj)`` on the Python prompt or ``obj?`` on the IPython
prompt.
Examples
--------
>>> np.info(np.polyval) # doctest: +SKIP
polyval(p, x)
Evaluate the polynomial p at x.
...
When using a string for `object` it is possible to get multiple results.
>>> np.info('fft') # doctest: +SKIP
*** Found in numpy ***
Core FFT routines
...
*** Found in numpy.fft ***
fft(a, n=None, axis=-1)
...
*** Repeat reference found in numpy.fft.fftpack ***
*** Total of 3 references found. ***
"""
global _namedict, _dictlist
# Local import to speed up numpy's import time.
import pydoc
import inspect
if (hasattr(object, '_ppimport_importer')
or hasattr(object, '_ppimport_module')):
object = object._ppimport_module
elif hasattr(object, '_ppimport_attr'):
object = object._ppimport_attr
if object is None:
info(info)
elif isinstance(object, ndarray):
_info(object, output=output)
elif isinstance(object, str):
if _namedict is None:
_namedict, _dictlist = _makenamedict(toplevel)
numfound = 0
objlist = []
for namestr in _dictlist:
try:
obj = _namedict[namestr][object]
if id(obj) in objlist:
print("\n "
"*** Repeat reference found in %s *** " % namestr,
file=output)
else:
objlist.append(id(obj))
print(" *** Found in %s ***" % namestr, file=output)
info(obj)
print("-" * maxwidth, file=output)
numfound += 1
except KeyError:
pass
if numfound == 0:
print("Help for %s not found." % object, file=output)
else:
print("\n "
"*** Total of %d references found. ***" % numfound,
file=output)
elif inspect.isfunction(object) or inspect.ismethod(object):
name = object.__name__
try:
arguments = str(inspect.signature(object))
except Exception:
arguments = "()"
if len(name + arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print(" " + argstr + "\n", file=output)
print(inspect.getdoc(object), file=output)
elif inspect.isclass(object):
name = object.__name__
try:
arguments = str(inspect.signature(object))
except Exception:
arguments = "()"
if len(name + arguments) > maxwidth:
argstr = _split_line(name, arguments, maxwidth)
else:
argstr = name + arguments
print(" " + argstr + "\n", file=output)
doc1 = inspect.getdoc(object)
if doc1 is None:
if hasattr(object, '__init__'):
print(inspect.getdoc(object.__init__), file=output)
else:
print(inspect.getdoc(object), file=output)
methods = pydoc.allmethods(object)
if methods != []:
print("\n\nMethods:\n", file=output)
for meth in methods:
if meth[0] == '_':
continue
thisobj = getattr(object, meth, None)
if thisobj is not None:
methstr, other = pydoc.splitdoc(
inspect.getdoc(thisobj) or "None")
print(" %s -- %s" % (meth, methstr), file=output)
elif hasattr(object, '__doc__'):
print(inspect.getdoc(object), file=output)
print >> sys.stderr, warning
# Fallback on the old 'doc/doc.rst' file if it exists.
try:
doc = path("doc/doc.rst").open().read()
except IOError, sh.ErrorReturnCode:
doc = None # there is nothing we can do at this stage.
warning = "warning: unable to use existing ReST documentation."
print >> sys.stderr, warning
else:
error = "the doc format should be 'markdown' or 'restructuredtext'."
raise ValueError(error)
if doc is not None:
# We assume that pydoc conventions are met:
# the first line is the summary, it's followed by a blankline,
# and then by the long description.
metadata["description"], metadata["long_description"] = pydoc.splitdoc(doc)
# Process trove classifiers.
classifiers = metadata.get("classifiers")
if classifiers and isinstance(classifiers, str):
classifiers = [c.strip() for c in classifiers.splitlines() if c.strip()]
metadata["classifiers"] = classifiers
return metadata
def printer(line, stdin):
print line,
class About(setuptools.Command):
description = "Display Project Metadata"
