def get_plugin_metadata(plugin_type, plugin_name):
# if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs
loader = getattr(plugin_loader, '%s_loader' % plugin_type)
result = loader.find_plugin_with_context(plugin_name,
mod_type='.py',
ignore_deprecated=True,
check_aliases=True)
if not result.resolved:
raise AssibleError("unable to load {0} plugin named {1} ".format(
plugin_type, plugin_name))
filename = result.plugin_resolved_path
collection_name = result.plugin_resolved_collection
try:
doc, __, __, __ = get_docstring(
filename,
fragment_loader,
verbose=(context.CLIARGS['verbosity'] > 0),
collection_name=collection_name,
is_module=(plugin_type == 'module'))
except Exception:
display.vvv(traceback.format_exc())
raise AssibleError(
"%s %s at %s has a documentation formatting error or is missing documentation."
% (plugin_type, plugin_name, filename))
if doc is None:
# Removed plugins don't have any documentation
return None
return dict(name=plugin_name,
namespace=DocCLI.namespace_from_plugin_filepath(
filename, plugin_name, loader.package_path),
description=doc.get('short_description', "UNKNOWN"),
version_added=doc.get('version_added', "UNKNOWN"))
def _get_plugin_doc(plugin, plugin_type, loader, search_paths):
# if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs
result = loader.find_plugin_with_context(plugin,
mod_type='.py',
ignore_deprecated=True,
check_aliases=True)
if not result.resolved:
raise PluginNotFound('%s was not found in %s' %
(plugin, search_paths))
plugin_name = result.plugin_resolved_name
filename = result.plugin_resolved_path
collection_name = result.plugin_resolved_collection
doc, plainexamples, returndocs, metadata = get_docstring(
filename,
fragment_loader,
verbose=(context.CLIARGS['verbosity'] > 0),
collection_name=collection_name,
is_module=(plugin_type == 'module'))
# If the plugin existed but did not have a DOCUMENTATION element and was not removed, it's an error
if doc is None:
raise ValueError('%s did not contain a DOCUMENTATION attribute' %
plugin)
doc['filename'] = filename
doc['collection'] = collection_name
return doc, plainexamples, returndocs, metadata
def main():
plugins = []
for path in sys.argv[1:] or sys.stdin.read().splitlines():
with open(path, 'rb') as f:
try:
mm_file = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
except ValueError:
continue
if DOC_RE.search(mm_file):
plugins.append(path)
mm_file.close()
for plugin in plugins:
data = {}
data['doc'], data['examples'], data['return'], data[
'metadata'] = get_docstring(plugin, fragment_loader)
for result in find_deprecations(data['doc']):
print('%s: %s is scheduled for removal in %s' %
(plugin, '.'.join(str(i)
for i in result[0][:-2]), result[1]))
base = os.path.join(os.path.dirname(assible.config.__file__), 'base.yml')
with open(base) as f:
data = yaml.safe_load(f)
for result in find_deprecations(data):
print('%s: %s is scheduled for removal in %s' %
(base, '.'.join(str(i) for i in result[0][:-2]), result[1]))
def helpdefault(self, module_name):
if module_name in self.modules:
in_path = module_loader.find_plugin(module_name)
if in_path:
oc, a, _, _ = plugin_docs.get_docstring(
in_path, fragment_loader)
if oc:
display.display(oc['short_description'])
display.display('Parameters:')
for opt in oc['options'].keys():
display.display(' ' +
stringc(opt, self.NORMAL_PROMPT) +
' ' +
oc['options'][opt]['description'][0])
else:
display.error('No documentation found for %s.' %
module_name)
else:
display.error(
'%s is not a valid command, use ? to list all valid commands.'
% module_name)
def module_args(self, module_name):
in_path = module_loader.find_plugin(module_name)
oc, a, _, _ = plugin_docs.get_docstring(in_path,
fragment_loader,
is_module=True)
return list(oc['options'].keys())