|
| 1 | +#!/usr/bin/env python3 |
| 2 | +# -*- coding: utf-8; py-indent-offset: 4 -*- |
| 3 | +# |
| 4 | +# Author: Linuxfabrik GmbH, Zurich, Switzerland |
| 5 | +# Contact: info (at) linuxfabrik (dot) ch |
| 6 | +# https://www.linuxfabrik.ch/ |
| 7 | +# License: The Unlicense, see LICENSE file. |
| 8 | + |
| 9 | +"""Guard against the DOCUMENTATION YAML bug that breaks `ansible-doc`. |
| 10 | +
|
| 11 | +In a `description` block (a YAML list), a bullet that contains a colon |
| 12 | +followed by a space is parsed as a mapping instead of a string, e.g. |
| 13 | +
|
| 14 | + description: |
| 15 | + - Useful for X: it does Y. # parsed as {"Useful for X": "it does Y."} |
| 16 | +
|
| 17 | +`ansible-doc` then aborts with "expected str instance, AnsibleMapping |
| 18 | +found". This test parses every in-house plugin's DOCUMENTATION (and |
| 19 | +RETURN) and asserts that every `description` is a string or a list of |
| 20 | +strings, catching the bug at unit-test time instead of at render time. |
| 21 | +
|
| 22 | +Vendored plugins keep their upstream docs and are out of scope. |
| 23 | +""" |
| 24 | + |
| 25 | +from __future__ import absolute_import, division, print_function |
| 26 | + |
| 27 | +__metaclass__ = type |
| 28 | + |
| 29 | +import ast |
| 30 | +import glob |
| 31 | +import os |
| 32 | +import unittest |
| 33 | + |
| 34 | +import yaml |
| 35 | + |
| 36 | +_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) |
| 37 | +_PLUGIN_GLOBS = [ |
| 38 | + 'plugins/filter/*.py', |
| 39 | + 'plugins/lookup/*.py', |
| 40 | + 'plugins/modules/*.py', |
| 41 | +] |
| 42 | +# Vendored plugins are kept in lockstep with upstream and not restyled here. |
| 43 | +_VENDORED_PREFIXES = ('ipa',) |
| 44 | +_VENDORED_NAMES = {'lvm_pv.py'} |
| 45 | + |
| 46 | + |
| 47 | +def _in_house_plugin_files(): |
| 48 | + files = [] |
| 49 | + for pattern in _PLUGIN_GLOBS: |
| 50 | + for path in glob.glob(os.path.join(_REPO_ROOT, pattern)): |
| 51 | + name = os.path.basename(path) |
| 52 | + if name.startswith(_VENDORED_PREFIXES) or name in _VENDORED_NAMES: |
| 53 | + continue |
| 54 | + files.append(path) |
| 55 | + return sorted(files) |
| 56 | + |
| 57 | + |
| 58 | +def _extract_doc_constants(source): |
| 59 | + """Return {const_name: yaml_obj} for DOCUMENTATION/RETURN string assignments.""" |
| 60 | + tree = ast.parse(source) |
| 61 | + docs = {} |
| 62 | + for node in tree.body: |
| 63 | + if not isinstance(node, ast.Assign): |
| 64 | + continue |
| 65 | + names = [t.id for t in node.targets if isinstance(t, ast.Name)] |
| 66 | + for wanted in ('DOCUMENTATION', 'RETURN'): |
| 67 | + if wanted in names and isinstance(node.value, ast.Constant) \ |
| 68 | + and isinstance(node.value.value, str): |
| 69 | + docs[wanted] = yaml.safe_load(node.value.value) |
| 70 | + return docs |
| 71 | + |
| 72 | + |
| 73 | +def _iter_description_problems(obj, path=''): |
| 74 | + """Yield human-readable paths where a `description` is not str / list[str].""" |
| 75 | + if isinstance(obj, dict): |
| 76 | + for key, value in obj.items(): |
| 77 | + if key == 'description': |
| 78 | + if isinstance(value, str): |
| 79 | + pass |
| 80 | + elif isinstance(value, list): |
| 81 | + for i, item in enumerate(value): |
| 82 | + if not isinstance(item, str): |
| 83 | + yield f'{path}.description[{i}] is {type(item).__name__}, expected str' |
| 84 | + else: |
| 85 | + yield f'{path}.description is {type(value).__name__}, expected str or list[str]' |
| 86 | + yield from _iter_description_problems(value, f'{path}.{key}') |
| 87 | + elif isinstance(obj, list): |
| 88 | + for i, item in enumerate(obj): |
| 89 | + yield from _iter_description_problems(item, f'{path}[{i}]') |
| 90 | + |
| 91 | + |
| 92 | +class TestPluginDocs(unittest.TestCase): |
| 93 | + |
| 94 | + def test_in_house_plugins_have_renderable_descriptions(self): |
| 95 | + files = _in_house_plugin_files() |
| 96 | + self.assertTrue(files, 'no in-house plugin files found') |
| 97 | + for path in files: |
| 98 | + with self.subTest(plugin=os.path.relpath(path, _REPO_ROOT)): |
| 99 | + with open(path, 'r') as f: |
| 100 | + source = f.read() |
| 101 | + docs = _extract_doc_constants(source) |
| 102 | + problems = [] |
| 103 | + for const_name, doc in docs.items(): |
| 104 | + problems += [f'{const_name}{p}' for p in _iter_description_problems(doc)] |
| 105 | + self.assertEqual( |
| 106 | + problems, [], |
| 107 | + 'description fields must be str or list[str] ' |
| 108 | + '(a colon + space in a bullet makes ansible-doc fail):\n ' |
| 109 | + + '\n '.join(problems), |
| 110 | + ) |
| 111 | + |
| 112 | + |
| 113 | +if __name__ == '__main__': |
| 114 | + unittest.main() |
0 commit comments