def main():
"""
Main doctest function.
Calculate how many things are documented and not documented yet.
And report a random selection of undocumented functions/ modules.
"""
moduleList = []
os.path.walk("Cura", treeWalk, moduleList)
moduleDocCount = 0
functionCount = 0
functionDocCount = 0
memberCount = 0
memberDocCount = 0
typeCount = 0
typeDocCount = 0
undocList = []
for module in moduleList:
if inspect.getdoc(module):
moduleDocCount += 1
else:
undocList.append(module.__name__)
for name in dir(module):
a = getattr(module, name)
try:
if not inspect.getfile(a).startswith('Cura'):
continue
except:
continue
if type(a) is types.FunctionType:
functionCount += 1
if inspect.getdoc(a):
functionDocCount += 1
else:
undocList.append('%s.%s' % (module.__name__, name))
elif type(a) is types.TypeType:
typeCount += 1
if inspect.getdoc(a):
typeDocCount += 1
else:
undocList.append('%s.%s' % (module.__name__, name))
for name2 in dir(a):
a2 = getattr(a, name2)
if type(a2) is types.MethodType:
if hasattr(a.__bases__[0], name2):
continue
memberCount += 1
if inspect.getdoc(a2):
memberDocCount += 1
# else:
# undocList.append('%s.%s.%s' % (module.__name__, name, name2))
print '%d/%d modules have documentation.' % (moduleDocCount, len(moduleList))
print '%d/%d types have documentation.' % (typeDocCount, typeCount)
print '%d/%d functions have documentation.' % (functionDocCount, functionCount)
print '%d/%d member functions have documentation.' % (memberDocCount, memberCount)
print '%.1f%% documented.' % (float(moduleDocCount + functionDocCount + typeDocCount + memberDocCount) / float(len(moduleList) + functionCount + typeCount + memberCount) * 100.0)
print ''
print 'You might want to document:'
for n in xrange(0, 10):
print random.Random().choice(undocList)
def test_format_doc_objectInput_format():
# Tests with object input and formatting
def docstring():
'''test {0} test {opt}'''
pass
# Raises an indexerror if not given the formatted args and kwargs
with pytest.raises(IndexError):
@format_doc(docstring)
def testfunc_fail():
pass
# Test that the formatting is done right
@format_doc(docstring, '+', opt='= 2 * test')
def testfunc2():
pass
assert inspect.getdoc(testfunc2) == 'test + test = 2 * test'
# Test that we can include the original docstring
def docstring2():
'''test {0} test {__doc__}'''
pass
@format_doc(docstring2, '+')
def testfunc3():
'''= 4 / 2 * test'''
pass
assert inspect.getdoc(testfunc3) == 'test + test = 4 / 2 * test'
def test_format_doc_stringInput_format():
# Tests with string input and formatting
docstring = 'yes {0} no {opt}'
# Raises an indexerror if not given the formatted args and kwargs
with pytest.raises(IndexError):
@format_doc(docstring)
def testfunc1():
pass
# Test that the formatting is done right
@format_doc(docstring, '/', opt='= life')
def testfunc2():
pass
assert inspect.getdoc(testfunc2) == 'yes / no = life'
# Test that we can include the original docstring
docstring2 = 'yes {0} no {__doc__}'
@format_doc(docstring2, '/')
def testfunc3():
'''= 2 / 2 * life'''
pass
assert inspect.getdoc(testfunc3) == 'yes / no = 2 / 2 * life'
def _basic_entry(self, cls, obj, parent, name):
entry = etree.SubElement(self.root, cls)
entry.attrib['id'] = self._canonical_name(obj, parent, name)
t = type(obj)
entry.attrib['type'] = "%s.%s" % (t.__module__, t.__name__)
doc = inspect.getdoc(obj)
if hasattr(obj, '__class__'):
classdoc = inspect.getdoc(obj.__class__)
else:
classdoc = None
if doc != classdoc and doc is not None:
entry.text = escape_text(doc)
else:
entry.text = ""
f, l = self._get_source_info(obj, parent)
if f:
entry.attrib['file'] = os.path.abspath(str(f))
if l is not None:
entry.attrib['line'] = str(l)
self._id_cache[entry.attrib['id']] = entry
return entry
def test_format_doc_objectInput_simple():
# Simple tests with object input
def docstring_fail():
pass
# Self input while the function has no docstring raises an error
with pytest.raises(ValueError):
@format_doc(docstring_fail)
def testfunc_fail():
pass
def docstring0():
'''test'''
pass
# A first test that replaces an empty docstring
@format_doc(docstring0)
def testfunc_1():
pass
assert inspect.getdoc(testfunc_1) == inspect.getdoc(docstring0)
# Test that it replaces an existing docstring
@format_doc(docstring0)
def testfunc_2():
'''not test'''
pass
assert inspect.getdoc(testfunc_2) == inspect.getdoc(docstring0)
def printExtensions():
'''
Echoes all entities in our extension module.
Useful to create documentation.
'''
print(" Types:")
for name, o in inspect.getmembers(frepple):
if not inspect.isclass(o) or issubclass(o,Exception) or hasattr(o,"__iter__"): continue
print(" %s: %s" % (o.__name__, inspect.getdoc(o)))
print(" Methods:")
for name, o in inspect.getmembers(frepple):
if not inspect.isroutine(o): continue
print(" %s: %s" % (o.__name__, inspect.getdoc(o)))
print(" Exceptions:")
for name, o in inspect.getmembers(frepple):
if not inspect.isclass(o) or not issubclass(o,Exception): continue
print(" %s" % (o.__name__))
print(" Iterators:")
for name, o in inspect.getmembers(frepple):
if not inspect.isclass(o) or not hasattr(o,"__iter__"): continue
print(" %s: %s" % (o.__name__, inspect.getdoc(o)))
print(" Other:")
for name, o in inspect.getmembers(frepple):
# Negating the exact same filters as in the previous blocks
if not(not inspect.isclass(o) or issubclass(o,Exception) or hasattr(o,"__iter__")): continue
if inspect.isroutine(o): continue
if not(not inspect.isclass(o) or not issubclass(o,Exception)): continue
if not(not inspect.isclass(o) or not hasattr(o,"__iter__")): continue
print(" %s: %s" % (name, o))
def test_format_doc_stringInput_simple():
# Simple tests with string input
docstring_fail = ''
# Raises an valueerror if input is empty
with pytest.raises(ValueError):
@format_doc(docstring_fail)
def testfunc_fail():
pass
docstring = 'test'
# A first test that replaces an empty docstring
@format_doc(docstring)
def testfunc_1():
pass
assert inspect.getdoc(testfunc_1) == docstring
# Test that it replaces an existing docstring
@format_doc(docstring)
def testfunc_2():
'''not test'''
pass
assert inspect.getdoc(testfunc_2) == docstring
def bind(self, target):
if self.func not in dir(target):
return None
funcs = []
if self.read_pattern is not None:
def getter():
return getattr(target, self.func)
if inspect.isdatadescriptor(getattr(type(target), self.func)):
getter.__doc__ = 'Getter: ' + inspect.getdoc(getattr(type(target), self.func))
funcs.append(
Func(getter, self.read_pattern, return_mapping=self.return_mapping, doc=self.doc))
if self.write_pattern is not None:
def setter(new_value):
setattr(target, self.func, new_value)
if inspect.isdatadescriptor(getattr(type(target), self.func)):
setter.__doc__ = 'Setter: ' + inspect.getdoc(getattr(type(target), self.func))
funcs.append(
Func(setter, self.write_pattern, argument_mappings=self.argument_mappings,
return_mapping=self.return_mapping, doc=self.doc))
return funcs
def printClass(cls, tag="", header=True):
methods = {}
for (key, val) in cls.__dict__.items():
if not inspect.isfunction(val):
continue
if not "_doc" in val.__dict__:
continue
if val.__dict__["_doc"] == tag:
methods[key] = val
if header:
print ".. _%s:" % cls.__name__
print
print "Class ``%s``" % cls.__name__
print "~~~~~~~~%s~~" % "~" * len(cls.__name__)
print
print "class **%s**" % cls.__name__
printIndented(inspect.getdoc(cls), 1)
for name in sorted(methods.keys()):
func = methods[name]
(args, varargs, keywords, defaults) = inspect.getargspec(func)
printIndented(".. _%s.%s:" % (cls.__name__, name), 1)
printIndented("**%s** (%s)" % (name, ", ".join(args)), 1)
printIndented(inspect.getdoc(func), 2)
def print_doc(arg):
"""print full documentation for a toolchain, module, or filter"""
from inspect import getdoc
if arg == "":
print "* To process data in mspikes, pick a predefined toolchain:\n"
print_toolchains()
print """\n* Define or extended toolchains with modules and filters:
For example, "input = arf_reader(); output=arf_writer((input, _structure))" will
read data from an ARF file, filter out any data that's not tagged as
'structure', and write the data to a new file. Filters are applied with 'OR'
logic. """
print_modules()
# print_filters()
print "\n* For more on a toolchain, module, or filter: 'mspikes --doc <entity>'\n"
elif hasattr(toolchains, arg):
sdoc,defs = getattr(toolchains, arg)
print "{0}: {1}\n\n{2}".format(arg, sdoc, defs)
elif hasattr(modules, arg):
cls = getattr(modules, arg)
doc = getdoc(cls)
print "{0}: {1}".format(arg, doc)
print_options(cls)
elif hasattr(filters, arg):
doc = getdoc(getattr(filters, arg))
print "{0}: {1}".format(arg, doc)
else:
print "E: no such toolchain, module, or filter '{0}'".format(arg)
def n_ok(expected, class_object=None, method_name=None, message=None):
"""
Just like nose test okay method but with more info
@param expected: the expected results
@param class_object: a string of the file name if a function and instance of the object if class
@param method_name: the function or method name
@param message: any other information that you want
@return: A nicely formatted string with the test case docstring,
the class method docstring, actual and expected result plus a message
"""
output = '\n\n'
frame = _get_frame()
obj = _get_object(frame)
output += "Test Case Docstring:\n" + _convert(inspect.getdoc(obj))
if class_object and method_name:
if type(class_object) == str:
imp = "__import__('" + class_object + "', globals=globals())"
x = eval(imp)
output += "Function Docstring:\n" + _convert(inspect.getdoc(eval("x." + method_name)))
del x
else:
output += 'Method Docstring:\n' + _convert(inspect.getdoc(eval("class_object." + method_name)))
if message:
output += "\n\nMore Info:\n\t" + str(message)
return ok_(expected, output)
def get_member_info(member):
info = {
'type': str(type(member)),
}
if isinstance(member, property):
info['getter'] = (member.fget.__name__, getdoc(member.fget))
elif isroutine(member):
info['rutine'] = (member.__name__, getdoc(member))
elif 'freeOrionAIInterface' in info['type']:
info['value'] = str(member)
elif isinstance(member, int):
if type(member) == int:
info['value'] = member
else:
info['value'] = str(member)
elif isinstance(member, (str, long, bool, float)):
info['value'] = member
elif isinstance(member, (list, tuple, dict, set, frozenset)):
if not len(member):
info['value'] = member
else:
print '>>>', type(member), "of", member
print
return info
def print_class(cls, tag="", header=True):
out = ""
methods = {}
for (key, val) in cls.__dict__.items():
if not inspect.isfunction(val):
continue
if not "_doc" in val.__dict__:
continue
if val.__dict__["_doc"] == tag:
methods[key] = val
if header:
out += ".. _%s:\n\n" % cls.__name__
out += "Class ``%s``\n" % cls.__name__
out += "~~~~~~~~%s~~" % ("~" * len(cls.__name__))
out += "\n\n"
out += "class **%s**\n" % cls.__name__
out += print_indented(inspect.getdoc(cls), 1)
for name in sorted(methods.keys()):
func = methods[name]
(args, varargs, keywords, defaults) = inspect.getargspec(func)
out += print_indented(".. _%s.%s:" % (cls.__name__, name), 1)
out += print_indented("**%s** (%s)" % (name, ", ".join(args)), 1)
out += print_indented(inspect.getdoc(func), 2)
return out
def help(cls, doc=False):
for slicername in sorted(cls.registry):
if not doc:
print slicername
if doc:
print '---- ', slicername, ' ----'
print inspect.getdoc(cls.registry[slicername])
def help(self, command=None):
"""Get help.
Usage: help [command]
When invoked without arguments, displays a list of all available
commands. When a command is given as an argument, detailed help for
this command is shown instead."""
if command and command not in self._commands:
print("Unknown command {}!".format(command))
return
if command:
print(inspect.getdoc(getattr(self, command)))
return
for command in sorted(self._commands):
print(command, end="")
doc = inspect.getdoc(getattr(self, command))
if not doc:
print()
continue
print(": {}".format(doc.splitlines()[0]))
def list(cls, doc=False):
for databasename in sorted(cls.registry):
if not doc:
print databasename
if doc:
print '---- ', databasename, ' ----'
print inspect.getdoc(cls.registry[databasename])
def client_methods_properties(resource_object, paths):
methods = []
for method in resource_object.iter_route_methods(wrappers.Route):
derivative_methods = method.client_methods or {method.__name__: None}
for method_name, method_defaults in six.iteritems(derivative_methods):
method_defaults = method_defaults or {}
url = '/'.join(paths + [resource_object.path(), method.path])
args = [arg for arg in method.spec.args if arg not in method_defaults]
kwargs = method.spec.kwargs
keywords = method.spec.keywords
doc_string = inspect.getdoc(method)
if method_defaults and hasattr(resource_object, method_name):
sub_method = getattr(resource_object, method_name)
doc_string = inspect.getdoc(sub_method)
sub_spec = func_spec.FuncSpec(sub_method)
args = sub_spec.args
kwargs = sub_spec.kwargs
keywords = sub_spec.keywords
methods.append(dict(
method_name=method_name,
method=method.method,
url=method.path,
args=args,
kwargs=kwargs,
url_kw=[arg for arg in method.spec.args if "{{{}}}".format(arg) in url],
defaults=method_defaults,
success_code=method.success_code,
keywords=keywords,
doc_string=doc_string,
keyword_map=method.keyword_map,
))
return methods
def _viewPlugins(self, request, error=None): # @UnusedVariable
plugins = {}
from seishub.core.core import ComponentMeta
for component in ComponentMeta._components:
try:
module = sys.modules[component.__module__]
except:
continue
description = getFirstSentence(inspect.getdoc(module))
modulename = module.__name__
classname = modulename + '.' + component.__name__
plugin = {
'name': component.__name__,
'module': module.__name__,
'file': module.__file__,
'classname': classname,
'description': getFirstSentence(inspect.getdoc(component)),
'enabled': self.env.isComponentEnabled(classname),
'required': classname in DEFAULT_COMPONENTS or \
modulename in DEFAULT_COMPONENTS,
}
packagename = '.'.join(modulename.split('.')[0:3])
plugins.setdefault(packagename, {})
plugins[packagename].setdefault(modulename, {})
plugins[packagename][modulename].setdefault('plugins',
[]).append(plugin)
plugins[packagename][modulename]['description'] = description
data = {
'sorted_plugins': sorted(plugins),
'plugins': plugins,
'error': error,
}
return data
def help2md(filepath, output='README.md', name='code'):
"""help2md
Converts python help to a .md file.
params:
- filename - The full path of the input file
- output - The full path of the output file ( defaults to README.md )
- name - The name of the file. It puts this at the top of the document.
"""
document = '#' + name + '\n'
c = imp.load_source(name, filepath)
doc = inspect.getdoc(c)
if doc:
document += doc + '\n'
else:
document += '\n'
main_file = getattr(c, '__file__')
modules = []
items = dir(c)
for i in items:
item = getattr(c, i)
if inspect.isfunction(item):
doc = inspect.getdoc(item)
if doc == None:
doc = 'No documentation'
params = inspect.formatargspec(*inspect.getfullargspec(item))
document += ('\n\n##' + i + '\n```python\ndef ' + i + params +
':\n\t"""' + '\n\t'.join(doc.split('\n'))
+ '"""\n```')
if inspect.isclass(item):
doc = inspect.getdoc(item)
if doc == None:
doc = 'No documentation'
document += ('\n\n##' + i + '\n```python\nclass ' + i +
'():\n\t"""' + '\n\t'.join(doc.split('\n'))
+ '"""\n```')
methods = dir(item)
for m in methods:
mitem = getattr(item, m)
if inspect.isfunction(mitem):
params = inspect.formatargspec(
*inspect.getfullargspec(mitem))
doc = inspect.getdoc(mitem)
if doc == None:
doc = 'No documentation'
document += ('\n\n###' + m + '\n```python\n\tdef ' + m
+ params + ':\n\t\t"""' + '\n\t\t'.join(
doc.split('\n')) + '"""\n```')
if inspect.ismodule(item):
modules.append(i)
document += '\n\n# Dependencies\n- ' + '\n- '.join(modules)
document += '\n\n***Made with help2md***'
with open(output, 'w') as ofile:
ofile.write(document)
return None
def __init__(self, input_file=None, args=None, output_file=None):
# CSVClean.__init__(self)
self.file_name = input_file
# def __init__(self, args=None, output_file=None):
"""
Perform argument processing and other setup for a CSVKitUtility.
"""
# self._init_common_parser()
# self.add_arguments()
# self.args = self.argparser.parse_args(args)
self.input_file = self._open_input_file(self.file_name)
inspect.getdoc(self.input_file)
# if 'f' not in self.override_flags:
# self.input_file = self._open_input_file(self.args.input_path)
self.reader_kwargs = self._extract_csv_reader_kwargs()
self.writer_kwargs = self._extract_csv_writer_kwargs()
self._install_exception_handler()
if output_file is None:
self.output_file = sys.stdout
else:
self.output_file = output_file
def __init__(self, obj):
if not callable(obj):
raise TypeError('Object not callable: %s' % obj)
# Save some attributes about the task
self.name = obj.__name__
self.doc = inspect.getdoc(obj) or ''
# If the provided object is a type (like a class), we'll treat
# it a little differently from if it's a pure function. The
# assumption is that the class will be instantiated wit no
# arguments, and then called with the provided arguments
if isinstance(obj, type):
try:
self._obj = obj()
except:
raise TypeError(
'%s => Task classes must take no arguments' % self.name)
self.spec = inspect.getargspec(self._obj.__call__)
self.doc = inspect.getdoc(self._obj.__call__) or self.doc
self.line = 'Unknown line'
self.file = 'Unknown file'
else:
self.spec = inspect.getargspec(obj)
self._obj = obj
self.line = obj.__code__.co_firstlineno
self.file = obj.__code__.co_filename
self.module = self._obj.__module__
self.fullname = self.name
# What module / etc. this overrides, if any
self.overrides = None
def _help(self, msg, *args):
"""Returns a help string containing all commands"""
msg_type = msg['type']
# MUC provides more commands as normal chat
if msg_type in ('normal', 'chat'):
cmds = self._cmds
elif msg_type == 'groupchat':
cmds = self._muc_cmds
docs = []
if args: # help <command>
cmd = args[0]
if len(args) > 1 or cmd not in cmds:
return
doc = inspect.getdoc(cmds[cmd])
docs.append(doc)
else: # help
docs.append('Available commands:{}'.format(os.linesep))
for cmd in sorted(cmds.keys()):
doc = inspect.getdoc(cmds[cmd])
if cmd == 'help' or not doc:
continue
lines = doc.splitlines()
docs.append('{}{}: {}'.format(self._CMD_PREFIX, cmd, lines[0]))
bottom = ('{0}Type !help <command name> to get more info '
'about that specific command.').format(os.linesep)
docs.append(bottom)
src = 'Source code available at http://kurzma.ch/botsrc'
docs.append(src)
return os.linesep.join(docs)
def parse(self, argv, global_options):
options = docopt_full_help(getdoc(self), argv, **self.docopt_options())
command = options["COMMAND"]
# Add command line arg for specifying environments
if options["--environment"]:
self.env = options["--environment"]
# Add command line arg or specifying alternate fig file.
if options["--file"]:
self.yaml_file = options["--file"]
else:
self.yaml_file = "fig.yml"
if command is None:
raise SystemExit(getdoc(self))
if not hasattr(self, command):
raise NoSuchCommand(command, self)
handler = getattr(self, command)
docstring = getdoc(handler)
if docstring is None:
raise NoSuchCommand(command, self)
command_options = docopt_full_help(docstring, options["ARGS"], options_first=True)
return (options, command, handler, command_options)
def test_10_doc_string_is_kept(self):
def t():
"""Always returns True."""
return True
t2 = TT.memoize(t)
self.assertEquals(getdoc(t), getdoc(t2))
def doc_quiz(quiz_type):
list_of_names = list(data.DATA[quiz_type])
while True:
name = random.choice(list_of_names)
if name in MEMORY:
continue
MEMORY.append(name)
try:
if quiz_type == 'modules':
mod = __import__(name, globals(), locals())
doc = inspect.getdoc(mod)
elif quiz_type == 'keywords':
doc = data.DATA['keywords'][name]
else:
doc = inspect.getdoc(eval(name))
if doc is None:
print('skipping {0} because no docs'.format(name))
continue
hidden_name = '*' * len(name)
doc = doc.replace(name, hidden_name)
doc = doc.replace(name.capitalize(), hidden_name)
print('(Ctrl-C to quit)\n\nTo which name '
'does this documentation belong?:\n')
inp = input(doc + '\n\n> ')
except KeyboardInterrupt:
return
except Exception as error:
print(error)
raise
time.sleep(.3)
if inp == name:
print('Very good. Next!')
else:
print('No, it is ' + name)
time.sleep(.5)
def help(cls, doc=False):
for metricname in sorted(cls.registry):
if not doc:
print metricname
if doc:
print '---- ', metricname, ' ----'
print inspect.getdoc(cls.registry[metricname])
def help(self, cmd_arg):
"""
/help [command]
Display this help text.
"""
if cmd_arg is "":
for command in self.commands:
if command in Player.commands and hasattr(self, command):
docs = getdoc(getattr(self, command))
head = docs.splitlines()[0]
rest = "\n".join(docs.splitlines()[1:])
self.client.send(output=[
{'tags': ['help header'], 'text': head},
{'tags': ['help text'], 'text': rest}
])
else:
command = cmd_arg.strip()
if command in self.commands and hasattr(self, command):
docs = getdoc(getattr(self, command))
head = docs.splitlines()[0]
rest = "\n".join(docs.splitlines()[1:])
self.client.send(output=[
{'tags': ['help header'], 'text': head},
{'tags': ['help text'], 'text': rest}
])
else:
self.client.send("Command {} not found.".format(command))
def docstring(f):
doc = inspect.getdoc(f)
if doc is None:
raise AssertionError("Missing docstring for " + f.__name__)
doc = inspect.getdoc(f).rstrip("\n")
doc = " " + doc.replace("\n", "\n ")
return doc
def test_generate_markdown_for_class(self):
index = {
'TestClass': TestClass,
'TestClass.a_method': TestClass.a_method,
'TestClass.a_property': TestClass.a_property,
'TestClass.ChildClass': TestClass.ChildClass,
'TestClass.CLASS_MEMBER': TestClass.CLASS_MEMBER
}
tree = {
'TestClass': ['a_method', 'a_property', 'ChildClass', 'CLASS_MEMBER']
}
docs = parser.generate_markdown(
full_name='TestClass', py_object=TestClass, duplicate_of={},
duplicates={}, index=index, tree=tree, reverse_index={}, doc_index={},
guide_index={}, base_dir='/')
# Make sure all required docstrings are present.
self.assertTrue(inspect.getdoc(TestClass) in docs)
self.assertTrue(inspect.getdoc(TestClass.a_method) in docs)
self.assertTrue(inspect.getdoc(TestClass.a_property) in docs)
# Make sure that the signature is extracted properly and omits self.
self.assertTrue('a_method(arg=\'default\')' in docs)
# Make sure there is a link to the child class and it points the right way.
self.assertTrue('[`class ChildClass`](./TestClass/ChildClass.md)' in docs)
# Make sure CLASS_MEMBER is mentioned.
self.assertTrue('CLASS_MEMBER' in docs)
# Make sure this file is contained as the definition location.
self.assertTrue(os.path.relpath(__file__, '/') in docs)
def makeMetricList(outfile):
f = open(outfile, 'w')
print("=================", file=f)
print("Available metrics", file=f)
print("=================", file=f)
print("Core LSST MAF metrics", file=f)
print("=====================", file=f)
print(" ", file=f)
for name, obj in inspect.getmembers(metrics):
if inspect.isclass(obj):
modname = inspect.getmodule(obj).__name__
if modname.startswith('lsst.sims.maf.metrics'):
link = "lsst.sims.maf.metrics.html#%s.%s" % (modname, obj.__name__)
simpledoc = inspect.getdoc(obj).split('\n')[0]
print("- `%s <%s>`_ \n \t %s" % (name, link, simpledoc), file=f)
print(" ", file=f)
if mafContribPresent:
print("Contributed mafContrib metrics", file=f)
print("==============================", file=f)
print(" ", file=f)
for name, obj in inspect.getmembers(mafContrib):
if inspect.isclass(obj):
modname = inspect.getmodule(obj).__name__
if modname.startswith('mafContrib') and name.endswith('Metric'):
link = 'http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/%s.py' % (modname.split('.')[-1])
simpledoc = inspect.getdoc(obj).split('\n')[0]
print("- `%s <%s>`_ \n \t %s" % (name, link, simpledoc), file=f)
print(" ", file=f)
1) contains 10 terms. Although it has not been proved yet (Collatz
Problem), it is thought that all starting numbers finish at 1.
Which starting number, under one million, produces the longest
chain?
NOTE: Once the chain starts the terms are allowed to go above one
million.
"""
max_len = 0
max_i = 0
values[1] = 1
for i in range(int(MAX_RANGE / 2), MAX_RANGE):
seq_len = collatz_len(i)
if seq_len > max_len:
max_len = seq_len
max_i = i
return max_i
if __name__ == "__main__":
program = os.path.splitext(os.path.basename(__file__))[0]
start = timer()
print(colored("-" * 70, "red"))
print(colored(program, "red"))
print(colored(inspect.getdoc(calculate), "yellow"))
print(f'> {colored(calculate(), "green", attrs=["dark"])}')
delta = round(timer() - start, 4)
print(f'(Finished in {colored(delta, "magenta")} seconds)')
print(colored("-" * 70, "red"))
def get_setup_action_description(self, action):
return inspect.getdoc(self.__class__)
def add_subcommand(self,
cmd,
base,
subcommand_group=None,
name=None,
description: str = None,
base_description: str = None,
subcommand_group_description: str = None,
guild_ids: typing.List[int] = None,
options: list = None,
connector: dict = None):
"""
Registers subcommand to SlashCommand.
:param cmd: Subcommand Coroutine.
:type cmd: Coroutine
:param base: Name of the base command.
:type base: str
:param subcommand_group: Name of the subcommand group, if any. Default ``None`` which represents there is no sub group.
:type subcommand_group: str
:param name: Name of the subcommand. Default name of the coroutine.
:type name: str
:param description: Description of the subcommand. Defaults to command docstring or ``None``.
:type description: str
:param base_description: Description of the base command. Default ``None``.
:type base_description: str
:param subcommand_group_description: Description of the subcommand_group. Default ``None``.
:type subcommand_group_description: str
:param guild_ids: List of guild ID of where the command will be used. Default ``None``, which will be global command.
:type guild_ids: List[int]
:param options: Options of the subcommand. This will affect ``auto_convert`` and command data at Discord API. Default ``None``.
:type options: list
:param connector: Kwargs connector for the command. Default ``None``.
:type connector: dict
"""
base = base.lower()
subcommand_group = subcommand_group.lower(
) if subcommand_group else subcommand_group
name = name or cmd.__name__
name = name.lower()
description = description or getdoc(cmd)
guild_ids = guild_ids or []
if base in self.commands:
for x in guild_ids:
if x not in self.commands[base].allowed_guild_ids:
self.commands[base].allowed_guild_ids.append(x)
if options is None:
options = manage_commands.generate_options(cmd, description,
connector)
_cmd = {
"func": None,
"description": base_description,
"guild_ids": guild_ids.copy(),
"api_options": [],
"connector": {},
"has_subcommands": True
}
_sub = {
"func": cmd,
"name": name,
"description": description,
"base_desc": base_description,
"sub_group_desc": subcommand_group_description,
"guild_ids": guild_ids,
"api_options": options,
"connector": connector or {}
}
if base not in self.commands:
self.commands[base] = model.CommandObject(base, _cmd)
else:
self.commands[base].has_subcommands = True
if self.commands[base].description:
_cmd["description"] = self.commands[base].description
if base not in self.subcommands:
self.subcommands[base] = {}
if subcommand_group:
if subcommand_group not in self.subcommands[base]:
self.subcommands[base][subcommand_group] = {}
if name in self.subcommands[base][subcommand_group]:
raise error.DuplicateCommand(
f"{base} {subcommand_group} {name}")
obj = model.SubcommandObject(_sub, base, name, subcommand_group)
self.subcommands[base][subcommand_group][name] = obj
else:
if name in self.subcommands[base]:
raise error.DuplicateCommand(f"{base} {name}")
obj = model.SubcommandObject(_sub, base, name)
self.subcommands[base][name] = obj
self.logger.debug(
f"Added subcommand `{base} {subcommand_group or ''} {name or cmd.__name__}`"
)
return obj
def _lookfor_generate_cache(module, import_modules, regenerate):
"""
Generate docstring cache for given module.
Parameters
----------
module : str, None, module
Module for which to generate docstring cache
import_modules : bool
Whether to import sub-modules in packages.
regenerate : bool
Re-generate the docstring cache
Returns
-------
cache : dict {obj_full_name: (docstring, kind, index), ...}
Docstring cache for the module, either cached one (regenerate=False)
or newly generated.
"""
# Local import to speed up numpy's import time.
import inspect
from io import StringIO
if module is None:
module = "numpy"
if isinstance(module, str):
try:
__import__(module)
except ImportError:
return {}
module = sys.modules[module]
elif isinstance(module, list) or isinstance(module, tuple):
cache = {}
for mod in module:
cache.update(
_lookfor_generate_cache(mod, import_modules, regenerate))
return cache
if id(module) in _lookfor_caches and not regenerate:
return _lookfor_caches[id(module)]
# walk items and collect docstrings
cache = {}
_lookfor_caches[id(module)] = cache
seen = {}
index = 0
stack = [(module.__name__, module)]
while stack:
name, item = stack.pop(0)
if id(item) in seen:
continue
seen[id(item)] = True
index += 1
kind = "object"
if inspect.ismodule(item):
kind = "module"
try:
_all = item.__all__
except AttributeError:
_all = None
# import sub-packages
if import_modules and hasattr(item, '__path__'):
for pth in item.__path__:
for mod_path in os.listdir(pth):
this_py = os.path.join(pth, mod_path)
init_py = os.path.join(pth, mod_path, '__init__.py')
if (os.path.isfile(this_py)
and mod_path.endswith('.py')):
to_import = mod_path[:-3]
elif os.path.isfile(init_py):
to_import = mod_path
else:
continue
if to_import == '__init__':
continue
try:
old_stdout = sys.stdout
old_stderr = sys.stderr
try:
sys.stdout = StringIO()
sys.stderr = StringIO()
__import__("%s.%s" % (name, to_import))
finally:
sys.stdout = old_stdout
sys.stderr = old_stderr
# Catch SystemExit, too
except BaseException:
continue
for n, v in _getmembers(item):
try:
item_name = getattr(v, '__name__', "%s.%s" % (name, n))
mod_name = getattr(v, '__module__', None)
except NameError:
# ref. SWIG's global cvars
# NameError: Unknown C global variable
item_name = "%s.%s" % (name, n)
mod_name = None
if '.' not in item_name and mod_name:
item_name = "%s.%s" % (mod_name, item_name)
if not item_name.startswith(name + '.'):
# don't crawl "foreign" objects
if isinstance(v, ufunc):
# ... unless they are ufuncs
pass
else:
continue
elif not (inspect.ismodule(v) or _all is None or n in _all):
continue
stack.append(("%s.%s" % (name, n), v))
elif inspect.isclass(item):
kind = "class"
for n, v in _getmembers(item):
stack.append(("%s.%s" % (name, n), v))
elif hasattr(item, "__call__"):
kind = "func"
try:
doc = inspect.getdoc(item)
except NameError:
# ref SWIG's NameError: Unknown C global variable
doc = None
if doc is not None:
cache[name] = (doc, kind, index)
return cache
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):
name = object.__name__
arguments = formatargspec(*getargspec(object))
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__
arguments = "()"
try:
if hasattr(object, '__init__'):
arguments = formatargspec(
*getargspec(object.__init__.__func__))
arglist = arguments.split(', ')
if len(arglist) > 1:
arglist[1] = "(" + arglist[1]
arguments = ", ".join(arglist[1:])
except Exception:
pass
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 inspect.ismethod(object):
name = object.__name__
arguments = formatargspec(*getargspec(object.__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(" " + argstr + "\n", file=output)
print(inspect.getdoc(object), file=output)
elif hasattr(object, '__doc__'):
print(inspect.getdoc(object), file=output)
def get_module_documentation(self,
node: ObjectNode,
select_members=None) -> Module:
"""
Get the documentation for a module and its children.
Arguments:
node: The node representing the module and its parents.
select_members: Explicit members to select.
Returns:
The documented module object.
"""
module = node.obj
path = node.dotted_path
name = path.split(".")[-1]
source: Optional[Source]
try:
source = Source(inspect.getsource(module), 1)
except OSError as error:
try:
code = Path(node.file_path).read_text()
except OSError:
self.errors.append(
f"Couldn't read source for '{path}': {error}")
source = None
else:
source = Source(code, 1) if code else None
root_object = Module(
name=name,
path=path,
file_path=node.file_path,
docstring=inspect.getdoc(module),
source=source,
)
if select_members is False:
return root_object
select_members = select_members or set()
attributes_data = get_module_attributes(module)
root_object.parse_docstring(self.docstring_parser,
attributes=attributes_data)
for member_name, member in inspect.getmembers(module):
if self.select(member_name, select_members): # type: ignore
child_node = ObjectNode(member, member_name, parent=node)
if child_node.is_class(
) and node.root.obj is inspect.getmodule(member):
root_object.add_child(
self.get_class_documentation(child_node))
elif child_node.is_function(
) and node.root.obj is inspect.getmodule(member):
root_object.add_child(
self.get_function_documentation(child_node))
elif member_name in attributes_data:
root_object.add_child(
self.get_attribute_documentation(
child_node, attributes_data[member_name]))
if hasattr(module, "__path__"): # noqa: WPS421 (hasattr)
for _, modname, _ in pkgutil.iter_modules(module.__path__):
if self.select(modname, select_members):
leaf = get_object_tree(f"{path}.{modname}")
root_object.add_child(self.get_module_documentation(leaf))
return root_object
await group.is_runnable(context)
except errors.CheckFailure:
await CustomHelp.object_not_found(context, "")
return
if not (subcommands := await help_.filter_commands(
context, group.subcommands)):
return await CustomHelp.send_command_help(context, group)
embed = CustomHelp.get_base_embed(context)
CustomHelp.common_command_formatting(context, embed, group)
for subcommand in sorted(subcommands, key=attrgetter("name")):
embed.add_field(
name=CustomHelp.get_command_signature(subcommand),
value=inspect.getdoc(subcommand.callback)
or "No help text provided...",
inline=False,
)
await context.respond(embed=embed)
@staticmethod
async def query(context: Context) -> typing.Optional[hikari.Embed]:
query = CustomHelp.get_arg(context)
queries = [i.lower() for i in query.split()]
cmd = context.bot.get_command(query)
iterable = getattr(cmd, "subcommands", context.bot.commands)
</svg>
<div>
The functionality here is experimental, and may change between versions without notice. Use at your own risk.
</div>
</div>
:::
---\n
""")
else:
f.write(f"# {title}\n---\n")
top_doc_obj = page.get("top-level-doc")
if top_doc_obj is not None:
top_doc = inspect.getdoc(top_doc_obj)
if top_doc is not None:
f.write(top_doc + "\n")
for obj, methods in classes:
f.write(format_subheader(obj))
f.write(format_doc(obj) + "\n\n")
if type(obj) == toolz.functoolz.curry:
f.write("\n")
continue
public_members = get_class_methods(obj, methods)
f.write(
create_methods_table(public_members, title="methods:"))
f.write("\n---\n<br>\n\n")
def get_macro_description(self, name):
"""Return the subclass's docstring."""
return inspect.getdoc(self.__class__)
def find_exportable_in_python_files(folder_name, class_type, verbose=False):
"""
load all the instruments or script objects that are located in folder_name and
return a dictionary with the script class name and path_to_python_file
Args:
folder_name (string): folder in which to search for class objects / or name of module
class_type (string or class): class type for which to look for
Returns:
a dictionary with the class name and path_to_python_file:
{
'class': class_of_instruments,
'filepath': path_to_python_file
}
"""
# if the module name was passed instead of a filename, figure out the path to the module
if not os.path.isdir(folder_name):
try:
folder_name = os.path.dirname(
inspect.getfile(import_module(folder_name)))
except ImportError:
raise ImportError('could not find module ' + folder_name)
subdirs = [
os.path.join(folder_name, x) for x in os.listdir(folder_name) if
os.path.isdir(os.path.join(folder_name, x)) and not x.startswith('.')
]
classes_dict = {}
# if there are subdirs in the folder recursively check all the subfolders for scripts
for subdir in subdirs:
classes_dict.update(find_exportable_in_python_files(
subdir, class_type))
if class_type.lower() == 'instrument':
class_type = Instrument
elif class_type.lower() == 'script':
class_type = Script
for python_file in [
f for f in glob.glob(os.path.join(folder_name, "*.py"))
if '__init__' not in f and 'setup' not in f
]:
print('file', python_file)
module, path = module_name_from_path(python_file)
try:
module = import_module(module)
classes_dict.update({
name: {
'class': name,
'filepath': inspect.getfile(obj),
'info': inspect.getdoc(obj)
}
for name, obj in inspect.getmembers(module)
if inspect.isclass(obj) and issubclass(obj, class_type)
and not obj in (Instrument, Script, ScriptIterator)
})
except ImportError:
if verbose:
print('Could not import module', module)
return classes_dict
def get_docstring(obj):
return inspect.getdoc(obj)
def autodoc_skip_member_handler(app, what, name, obj, skip, options):
"""
Enforce the "exclude-members" option, even in cases where it seems to be
ignored by Sphinx.
"""
excluded = options.get('exclude-members', set())
if excluded:
# Either it's a one-item set with the string passed in conf.py
try:
excluded, = excluded
# Or it's an already-processed set
except ValueError:
pass
else:
excluded = exclude_members_option(excluded)
# Import conf.py Sphinx configuration, since the "excluded-members" option
# can be overriden by the user in ReST directives.
import conf
default_excluded = exclude_members_option(
conf.autodoc_default_options.get('exclude-members', '')
)
excluded = excluded | default_excluded
name = name.split('.')[-1]
unwrapped = inspect.unwrap(obj)
# Get rid of the default implementation of dunder names, since it adds no
# value in the documentation
if any(
hasattr(cls, name) and getattr(cls, name) in (obj, unwrapped)
# providers of "uninteresting" methods that are useless in our
# documentation
for cls in (
object,
type,
abc.ABC,
abc.ABCMeta,
)
):
return True
# Some classes like ABCMeta are more sneaky so also ban things that are
# just builtin functions
elif any(
type_ in map(type, (obj, unwrapped))
for type_ in (
# Work with multiple Python versions
getattr(types, type_name)
for type_name in (
'BuiltinFunctionType',
'BuiltinMethodType',
'WrapperDescriptorType',
'MethodWrapperType',
'MethodDescriptorType',
'ClassMethodDescriptorType',
'GetSetDescriptorType',
'MemberDescriptorType',
)
if hasattr(types, type_name)
)
):
return True
# Dunder names without any doc are of no interest, they are probably just
# implementation details
elif name.startswith('__') and name.endswith('__') and not inspect.getdoc(obj):
return True
elif name in excluded:
return True
else:
return skip
async def _inline_handler(self, inline_query: InlineQuery) -> None:
"""Inline query handler (forms' calls)"""
# Retrieve query from passed object
query = inline_query.query
# If we didn't get any query, return help
if not query:
_help = ""
for mod in self._allmodules.modules:
if (not hasattr(mod, "inline_handlers")
or not isinstance(mod.inline_handlers, dict)
or not mod.inline_handlers):
continue
_ihandlers = dict(mod.inline_handlers.items())
for name, fun in _ihandlers.items():
# If user doesn't have enough permissions
# to run this inline command, do not show it
# in help
if not self.check_inline_security(
fun, inline_query.from_user.id):
continue
# Retrieve docs from func
doc = utils.escape_html("\n".join([
line.strip()
for line in inspect.getdoc(fun).splitlines()
if not line.strip().startswith("@")
]))
_help += f"🎹 <code>@{self.bot_username} {name}</code> - {doc}\n"
await inline_query.answer(
[
InlineQueryResultArticle(
id=rand(20),
title="Show available inline commands",
description=
f"You have {len(_help.splitlines())} available command(-s)",
input_message_content=InputTextMessageContent(
f"<b>ℹ️ Available inline commands:</b>\n\n{_help}",
"HTML",
disable_web_page_preview=True,
),
thumb_url=
"https://img.icons8.com/fluency/50/000000/info-squared.png",
thumb_width=128,
thumb_height=128,
)
],
cache_time=0,
)
return
# First, dispatch all registered inline handlers
for mod in self._allmodules.modules:
if (not hasattr(mod, "inline_handlers")
or not isinstance(mod.inline_handlers, dict)
or not mod.inline_handlers):
continue
instance = GeekInlineQuery(inline_query)
for query_text, query_func in mod.inline_handlers.items():
if inline_query.query.split()[0].lower(
) == query_text.lower() and self.check_inline_security(
query_func, inline_query.from_user.id):
try:
await query_func(instance)
except BaseException:
logger.exception("Error on running inline watcher!")
# Process forms
for form in self._forms.copy().values():
for button in array_sum(form.get("buttons", [])):
if ("_switch_query" in button and "input" in button
and button["_switch_query"] == query.split()[0]
and inline_query.from_user.id in [self._me] + self.
_client.dispatcher.security._owner # skipcq: PYL-W0212
+ form["always_allow"]):
await inline_query.answer(
[
InlineQueryResultArticle(
id=rand(20),
title=button["input"],
description=
"⚠️ Please, do not remove identifier!",
input_message_content=InputTextMessageContent(
"🔄 <b>Transferring value to userbot...</b>\n"
"<i>This message is gonna be deleted...</i>",
"HTML",
disable_web_page_preview=True,
),
)
],
cache_time=60,
)
return
# Process galleries
for gallery in self._galleries.copy().values():
if (inline_query.from_user.id in [
self._me
] + self._client.dispatcher.security._owner # skipcq: PYL-W0212
+ gallery["always_allow"] and query == gallery["uid"]):
markup = InlineKeyboardMarkup()
markup.add(
InlineKeyboardButton(
"Next ➡️", callback_data=gallery["btn_call_data"]))
caption = gallery["caption"]
caption = caption() if callable(caption) else caption
await inline_query.answer(
[
InlineQueryResultPhoto(
id=rand(20),
title="Toss a coin",
photo_url=gallery["photo_url"],
thumb_url=gallery["photo_url"],
caption=caption,
description=caption,
reply_markup=markup,
parse_mode="HTML",
)
],
cache_time=0,
)
return
# If we don't know, what this query is for, just ignore it
if query not in self._forms:
return
# Otherwise, answer it with templated form
await inline_query.answer(
[
InlineQueryResultArticle(
id=rand(20),
title="GeekTG",
input_message_content=InputTextMessageContent(
self._forms[query]["text"],
"HTML",
disable_web_page_preview=True,
),
reply_markup=self._generate_markup(query),
)
],
cache_time=60,
)
def help(self) -> str:
# if not defined in subclass, fallback to inline doc
doc = inspect.getdoc(type(self))
return doc if doc else f"{self.name}: no help available."
def get(self):
"""Generates markdown documentation.
Args:
None
Example URLs:
GET /api/v1/doc
"""
exclude_list = ["StaticFileHandler", "DocHandler"]
handlers = set()
accum = [BOILER_PLATE]
for rule in self.service.application.default_router.rules:
if not rule.target.rules:
continue
handlers.add(rule.target.rules[0].target)
handlers = sorted(handlers, key=lambda x: x.__name__)
accum.append("## <a name='handlers'></a>Handlers\n")
for handler in handlers:
if handler.__name__ in exclude_list:
continue
accum.append(" * [%s](#%s)" % (handler.__name__, handler.__name__))
accum.append("\n")
for handler in handlers:
if handler.__name__ in exclude_list:
continue
accum.append("# <a name='%s'></a>%s ([Top](#handlers))\n" %
(handler.__name__, handler.__name__))
accum.append("%s\n" % inspect.getdoc(handler))
if hasattr(handler, "URLS") and handler.URLS:
accum.append("### URLs\n")
for url in handler.URLS:
accum.append(" %s" % url)
accum.append("\n")
if hasattr(handler, "get"):
doc = inspect.getdoc(getattr(handler, "get"))
if doc:
accum.append("### GET\n")
accum.append(doc)
accum.append("\n")
if hasattr(handler, "put"):
doc = inspect.getdoc(getattr(handler, "put"))
if doc:
accum.append("### PUT\n")
accum.append(doc)
accum.append("\n")
if hasattr(handler, "post"):
doc = inspect.getdoc(getattr(handler, "post"))
if doc:
accum.append("### POST\n")
accum.append(doc)
accum.append("\n")
if hasattr(handler, "delete"):
doc = inspect.getdoc(getattr(handler, "delete"))
if doc:
accum.append("### DELETE\n")
accum.append(doc)
accum.append("\n")
self.write('\n'.join(accum))
def py__doc__(self, include_call_signature=False):
return force_unicode(inspect.getdoc(self._obj)) or u''
def _methodHelp(self, method):
f = getattr(self, method)
return inspect.getdoc(f)
def get_property_doc(target, prop):
for name, obj in inspect.getmembers(type(target),
inspect.isdatadescriptor):
if (isinstance(obj, property) and name == prop):
return inspect.getdoc(obj.fget)
return None
def display_class(cls, stream, level, args): #@DuplicatedSignature
print " class {}".format(cls.__name__)
title(stream, level, "Class " + cls.__name__)
stream.write(inspect.getdoc(cls) or "")
if cls.__init__ is object.__init__:
spec = ""
else:
try:
inspect.getargspec(cls.__init__)
except:
print " Skipping class spec"
spec = ""
else:
spec = inspect.formatargspec(*inspect.getargspec(cls.__init__))
if args.mro:
mro = inspect.getmro(cls)[1:-1]
if mro:
stream.write("\n\n")
stream.write("*Method resolution order:* ")
stream.write(", ".join(":obj:`~{0}.{1}`".format(c.__module__, c.__name__) for c in mro))
stream.write("\n\n.. class:: " + cls.__name__ + spec + "\n\n")
class_stream = IndentStream(stream, " ")
class_stream.write(inspect.getdoc(cls.__init__) or "")
# Sort out aliases. thing_dict maps names (the names we're going to
# document things under) to 2-tuples (thing, names), where thing is the
# thing itself and names is a list of names under which it can be found
# (including the key under which the tuple is registered in thing_dict)
thing_dict = {}
for name, kind, definer, thing in sorted(inspect.classify_class_attrs(cls)):
if definer is cls and pydoc.visiblename(name, None, thing) and name != "__init__":
# See if we've already seen this thing before. Python 3
# compatibility note: we have to iterate over a copy of the dict's
# items since we could end up modifying the dict during iteration.
for k, (v, names) in list(thing_dict.items()):
# We have to use == here instead of "is" as the bound method
# object returned for each attribute of a class is generated on
# the fly, so it's different each time we request it. They
# compare equal, though, if they wrap the same underlying
# function, so using == works as expected.
if v == thing:
# We have, under the name k. Add an alias for it under our
# current name.
names.append(name)
# If this thing has a __name__ and its __name__ is the
# current name we're looking at, relocate the thing's entry
# in thing_dict to list it under the current name. This
# causes things to be preferentially documented under the
# name with which they were actually defined.
if getattr(thing, "__name__", None) == name:
del thing_dict[k]
thing_dict[name] = (v, names)
# Also move the defined name so that it's first in the
# list, which will cause it to be listed first in the
# resulting documentation
names.remove(name)
names.insert(0, name)
break
else:
# We haven't seen it before, so add a new entry for it.
thing_dict[name] = (thing, [name])
for _, (thing, names) in sorted(thing_dict.iteritems()):
# TODO: Handle nested classes here
if should_document_as_method(thing):
try:
inspect.getargspec(thing)
except:
print " Couldn't get argspec, skipping {}".format(names)
else:
display_method(thing, class_stream, level + 1, args, cls, names)
elif should_document_as_property(thing):
display_property(thing, class_stream, level + 1, args, cls, names)
else:
print " Not a method or property, skipping {}".format(names)
if args.inheritance:
inheritance_dict = {}
for name, kind, definer, thing in sorted(inspect.classify_class_attrs(cls)):
if (
definer is not cls and
definer is not object and
pydoc.visiblename(name, None, thing) and
name not in ["__dict__", "__weakref__"] and
(should_document_as_method(thing) or should_document_as_property(thing))):
inheritance_dict.setdefault(definer, []).append(name)
for base_class in inspect.getmro(cls):
if base_class in inheritance_dict:
class_stream.write("\n\n*Members inherited from class* :obj:`~{0}.{1}`\\ *:* ".format(base_class.__module__, base_class.__name__))
class_stream.write(", ".join(":obj:`~{0}.{1}.{2}`".format(base_class.__module__, base_class.__name__, n) for n in inheritance_dict[base_class]))
"""
MODULE_HEADER = """
## Module: {modname}
"""
PROP_HEADER = """- *{propkey}*: {prophelp}
"""
# @TODO: having type information here would be awesome
PROP_HEADER_NO_HELP = """- *{propkey}*
"""
# three ways to try and get the property + docstring
PROP_FETCHERS = (
lambda cl, k: inspect.getdoc(getattr(cl, k)),
lambda cl, k: inspect.getdoc(getattr(cl, "_" + k)),
lambda cl, k: inspect.getdoc(getattr(cl(), k)) and "" or "",
)
def _parsed_args():
""" parse commandline arguments with argparse """
parser = argparse.ArgumentParser(
description=__doc__,
formatter_class=argparse.ArgumentDefaultsHelpFormatter)
group = parser.add_mutually_exclusive_group()
group.add_argument(
"-d",
"--dryrun",
# get list of benchamrks to run
bench_methods = [
x[0] for x in inspect.getmembers(
Benchmark,
predicate=lambda x: inspect.ismethod(x) or inspect.isfunction(x))
]
print(bench_methods)
if args.list:
for name in bench_methods:
logging.info(("\t " + name))
sys.exit(0)
if args.benchmarks:
bench_methods = filter(lambda x: x in args.benchmarks.split(","),
bench_methods)
# setup operations
setup(args.workdir)
for name in bench_methods:
method = getattr(Benchmark, name)
logging.info(("\n" + name + "(): " + inspect.getdoc(method)))
method(Benchmark())
try:
shutil.rmtree(WORKDIR)
except Exception:
logging.info(("Cleanup failed"))
def display_function(function, stream, level, args, name): #@DuplicatedSignature
print " Function " + name
stream.write("\n\n.. function:: " + name + inspect.formatargspec(*inspect.getargspec(function)) + "\n\n")
function_stream = IndentStream(stream, " ")
function_stream.write(inspect.getdoc(function) or "")
def add_sub_flow_args(self, sub_flows):
""" Take an array of workflow objects and use introspection to extract
the parameters, types and docstrings of their run method. Only the
optional input parameters are extracted for these as they are treated as
sub workflows.
Parameters
-----------
sub_flows : array of dipy.workflows.workflow.Workflow
Workflows to inspect.
Returns
-------
sub_flow_optionals : dictionary of all sub workflow optional parameters
"""
sub_flow_optionals = dict()
for name, flow, short_name in sub_flows:
sub_flow_optionals[name] = {}
doc = inspect.getdoc(flow)
npds = NumpyDocString(doc)
_doc = npds['Parameters']
args, defaults = get_args_default(flow)
len_args = len(args)
len_defaults = len(defaults)
flow_args = \
self.add_argument_group('{0} arguments(optional)'.
format(name))
for i, arg_name in enumerate(args):
is_not_optionnal = i < len_args - len_defaults
if 'out_' in arg_name or is_not_optionnal:
continue
arg_name = '{0}.{1}'.format(short_name, arg_name)
sub_flow_optionals[name][arg_name] = None
prefix = '--'
typestr = _doc[i][1]
dtype, isnarg = self._select_dtype(typestr)
help_msg = ''.join(_doc[i][2])
_args = ['{0}{1}'.format(prefix, arg_name)]
_kwargs = {'help': help_msg,
'type': dtype,
'action': 'store'}
_kwargs['metavar'] = dtype.__name__
if dtype is bool:
_kwargs['action'] = 'store_true'
default_ = dict()
default_[arg_name] = False
self.set_defaults(**default_)
del _kwargs['type']
del _kwargs['metavar']
elif dtype is bool:
_kwargs['type'] = int
_kwargs['choices'] = [0, 1]
if dtype is tuple:
_kwargs['type'] = str
if isnarg:
_kwargs['nargs'] = '*'
flow_args.add_argument(*_args, **_kwargs)
return sub_flow_optionals
def check_rest(module, names, dots=True):
"""
Check reStructuredText formatting of docstrings
Returns: [(name, success_flag, output), ...]
"""
try:
skip_types = (dict, str, unicode, float, int)
except NameError:
# python 3
skip_types = (dict, str, float, int)
results = []
if module.__name__[6:] not in OTHER_MODULE_DOCS:
results += [(module.__name__,) +
validate_rst_syntax(inspect.getdoc(module),
module.__name__, dots=dots)]
for name in names:
full_name = module.__name__ + '.' + name
obj = getattr(module, name, None)
if obj is None:
results.append((full_name, False, "%s has no docstring" % (full_name,)))
continue
elif isinstance(obj, skip_types):
continue
if inspect.ismodule(obj):
text = inspect.getdoc(obj)
else:
try:
text = str(get_doc_object(obj))
except:
import traceback
results.append((full_name, False,
"Error in docstring format!\n" +
traceback.format_exc()))
continue
m = re.search("([\x00-\x09\x0b-\x1f])", text)
if m:
msg = ("Docstring contains a non-printable character %r! "
"Maybe forgot r\"\"\"?" % (m.group(1),))
results.append((full_name, False, msg))
continue
try:
src_file = short_path(inspect.getsourcefile(obj))
except TypeError:
src_file = None
if src_file:
file_full_name = src_file + ':' + full_name
else:
file_full_name = full_name
results.append((full_name,) + validate_rst_syntax(text, file_full_name, dots=dots))
return results
from IPython.utils import PyColorize
from IPython.utils import io
from IPython.utils import openpy
from IPython.utils import py3compat
from IPython.utils.dir2 import safe_hasattr
from IPython.utils.text import indent
from IPython.utils.wildcard import list_namespace
from IPython.utils.coloransi import TermColors, ColorScheme, ColorSchemeTable
from IPython.utils.py3compat import cast_unicode, string_types, PY3
from IPython.utils.signatures import signature
# builtin docstrings to ignore
_func_call_docstring = types.FunctionType.__call__.__doc__
_object_init_docstring = object.__init__.__doc__
_builtin_type_docstrings = {
inspect.getdoc(t)
for t in (types.ModuleType, types.MethodType, types.FunctionType, property)
}
_builtin_func_type = type(all)
_builtin_meth_type = type(
str.upper) # Bound methods have the same type as builtin functions
#****************************************************************************
# Builtin color schemes
Colors = TermColors # just a shorthand
# Build a few color schemes
NoColor = ColorScheme(
'NoColor',
{
def add_workflow(self, workflow):
""" Take a workflow object and use introspection to extract the parameters,
types and docstrings of its run method. Then add these parameters
to the current arparser's own params to parse. If the workflow is of
type combined_workflow, the optional input parameters of its
sub workflows will also be added.
Parameters
-----------
workflow : dipy.workflows.workflow.Workflow
Workflow from which to infer parameters.
Returns
-------
sub_flow_optionals : dictionary of all sub workflow optional parameters
"""
doc = inspect.getdoc(workflow.run)
npds = NumpyDocString(doc)
self.doc = npds['Parameters']
self.description = ' '.join(npds['Extended Summary'])
self.outputs = [param for param in npds['Parameters'] if
'out_' in param[0]]
args, defaults = get_args_default(workflow.run)
len_args = len(args)
len_defaults = len(defaults)
output_args = \
self.add_argument_group('output arguments(optional)')
for i, arg in enumerate(args):
prefix = ''
is_optionnal = i >= len_args - len_defaults
if is_optionnal:
prefix = '--'
typestr = self.doc[i][1]
dtype, isnarg = self._select_dtype(typestr)
help_msg = ''.join(self.doc[i][2])
_args = ['{0}{1}'.format(prefix, arg)]
_kwargs = {'help': help_msg,
'type': dtype,
'action': 'store'}
if is_optionnal:
_kwargs['metavar'] = dtype.__name__
if dtype is bool:
_kwargs['action'] = 'store_true'
default_ = dict()
default_[arg] = False
self.set_defaults(**default_)
del _kwargs['type']
del _kwargs['metavar']
elif dtype is bool:
_kwargs['type'] = int
_kwargs['choices'] = [0, 1]
if dtype is tuple:
_kwargs['type'] = str
if isnarg:
_kwargs['nargs'] = '*'
if 'out_' in arg:
output_args.add_argument(*_args, **_kwargs)
else:
self.add_argument(*_args, **_kwargs)
return self.add_sub_flow_args(workflow.get_sub_runs())
def __init__(self, func):
self.func = func
self.instance = None # bind with instance class of decorated method
self.cache = {}
self.__doc__ = inspect.getdoc(self.func)
async def format(self):
"""Handles the actual behaviour involved with formatting.
To change the behaviour, this method should be overridden.
Returns
--------
list
A paginated output of the help command.
"""
self._paginator = Paginator()
# we need a padding of ~80 or so
description = self.command.description if not self.is_cog(
) else inspect.getdoc(self.command)
if description:
# <description> portion
self._paginator.add_line(description, empty=True)
if isinstance(self.command, Command):
# <signature portion>
signature = self.get_command_signature()
self._paginator.add_line(signature, empty=True)
# <long doc> section
if self.command.help:
self._paginator.add_line(self.command.help, empty=True)
# end it here if it's just a regular command
if not self.has_subcommands():
self._paginator.close_page()
return self._paginator.pages
max_width = self.max_name_size
def category(tup):
cog = tup[1].cog_name
# we insert the zero width space there to give it approximate
# last place sorting position.
return cog + ':' if cog is not None else '\u200bNo Category:'
filtered = await self.filter_command_list()
if self.is_bot():
data = sorted(filtered, key=category)
for category, commands in itertools.groupby(data, key=category):
# there simply is no prettier way of doing this.
commands = sorted(commands)
if len(commands) > 0:
self._paginator.add_line(category)
self._add_subcommands_to_page(max_width, commands)
else:
filtered = sorted(filtered)
if filtered:
self._paginator.add_line('Commands:')
self._add_subcommands_to_page(max_width, filtered)
# add the ending note
self._paginator.add_line()
ending_note = self.get_ending_note()
self._paginator.add_line(ending_note)
return self._paginator.pages
def extract_documentation(func):
doc = inspect.getdoc(func)
if doc is not None:
return doc.decode("utf-8")
def getCallTip(command='', locals=None):
"""For a command, return a tuple of object name, argspec, tip text.
The call tip information will be based on the locals namespace."""
calltip = ('', '', '') # object name, argspec, tip text.
# Get the proper chunk of code from the command.
root = getRoot(command, terminator='(')
try:
if locals is not None:
obj = eval(root, locals)
else:
obj = eval(root)
except:
return calltip
name = ''
obj, dropSelf = getBaseObject(obj)
try:
name = obj.__name__
except AttributeError:
pass
tip1 = ''
argspec = ''
if inspect.isbuiltin(obj):
# Builtin functions don't have an argspec that we can get.
pass
elif inspect.isfunction(obj):
# tip1 is a string like: "getCallTip(command='', locals=None)"
argspec = inspect.getargspec(
obj) if not PY3 else inspect.getfullargspec(obj)
argspec = inspect.formatargspec(*argspec)
if dropSelf:
# The first parameter to a method is a reference to an
# instance, usually coded as "self", and is usually passed
# automatically by Python; therefore we want to drop it.
temp = argspec.split(',')
if len(temp) == 1: # No other arguments.
argspec = '()'
elif temp[0][:2] == '(*': # first param is like *args, not self
pass
else: # Drop the first argument.
argspec = '(' + ','.join(temp[1:]).lstrip()
tip1 = name + argspec
doc = ''
if callable(obj):
try:
doc = inspect.getdoc(obj)
except:
pass
if doc:
# tip2 is the first separated line of the docstring, like:
# "Return call tip text for a command."
# tip3 is the rest of the docstring, like:
# "The call tip information will be based on ... <snip>
firstline = doc.split('\n')[0].lstrip()
if tip1 == firstline or firstline[:len(name) + 1] == name + '(':
tip1 = ''
else:
tip1 += '\n\n'
docpieces = doc.split('\n\n')
tip2 = docpieces[0]
tip3 = '\n\n'.join(docpieces[1:])
tip = f'{tip1}{tip2}\n\n{tip3}'
else:
tip = tip1
calltip = (name, argspec[1:-1], tip.strip())
return calltip
