From 7e54dd6110f8bc8d4c5d0c289d3af7c8979672dd Mon Sep 17 00:00:00 2001 From: Jiri Podivin Date: Mon, 1 Mar 2021 14:09:26 +0100 Subject: [PATCH] Expanded docstrings for library subpackage. Reintroduces the __init__.py in library dir, to help with doc building. apidoc seems to get confused without it. Plus it allows for writing general into to the subpkg. Signed-off-by: Jiri Podivin Change-Id: I72b7a665da482d84b7b3e4d5560c75c8af7111d7 --- validations_common/library/__init__.py | 2 + .../library/check_package_update.py | 21 +++- validations_common/library/reportentry.py | 9 ++ .../library/validations_read_ini.py | 110 +++++++++--------- 4 files changed, 88 insertions(+), 54 deletions(-) diff --git a/validations_common/library/__init__.py b/validations_common/library/__init__.py index e69de29..a1b35d9 100644 --- a/validations_common/library/__init__.py +++ b/validations_common/library/__init__.py @@ -0,0 +1,2 @@ +"""Provides several ansible modules for I/O needs of validations. +""" diff --git a/validations_common/library/check_package_update.py b/validations_common/library/check_package_update.py index 2a0cc56..08defaf 100644 --- a/validations_common/library/check_package_update.py +++ b/validations_common/library/check_package_update.py @@ -109,6 +109,9 @@ def get_package_details(pkg_details_string): """Returns PackageDetails namedtuple from given string. Raises ValueError if the number of '|' separated fields is < 4. + + :return: package details + :rtype: collections.namedtuple """ split_output = pkg_details_string.split('|') try: @@ -143,8 +146,11 @@ def _allowed_pkg_manager_stderr(stderr, allowed_errors): def _command(command): """ - :returns: the result of a subprocess call - as a tuple (stdout, stderr). + Return result of a subprocess call. + Doesn't set timeout for the call, so the process can hang. + Potentially for a very long time. + :return: stdout and stderr from Popen.communicate() + :rtype: tuple """ process = subprocess.Popen( command, @@ -229,6 +235,17 @@ def check_update(module, packages_list, pkg_mgr): """Check if the packages in the 'packages_list are up to date. Queries binaries, defined the in relevant SUPPORTED_PKG_MGRS entry, to obtain information about present and available packages. + + :param module: ansible module providing fail_json and exit_json + methods + :type module: AnsibleModule + :param packages_list: list of packages to be checked + :type package: list + :param pkg_mgr: Package manager to check for update availability + :type pkg_mgr: string + + :return: None + :rtype: None """ if len(packages_list) == 0: module.fail_json( diff --git a/validations_common/library/reportentry.py b/validations_common/library/reportentry.py index 77034ce..926fb04 100644 --- a/validations_common/library/reportentry.py +++ b/validations_common/library/reportentry.py @@ -57,6 +57,12 @@ EXAMPLES = ''' def format_msg_report(status, reason, recommendations): + """ + Turn status, reason and list of recommendations into more + readable formatted strings. + :return: status and reason as string, recommendations as separate strings + :rtype: tuple of strings + """ msg = ("[{}] '{}'\n".format(status, reason)) if recommendations: for rec in recommendations: @@ -66,6 +72,9 @@ def format_msg_report(status, reason, recommendations): def display_type_report(module, status, msg): + """ + Pass msg to fail_json or exit_json methods depending on status. + """ if status == 'ERROR': module.fail_json(msg=msg) elif status == "SKIPPED": diff --git a/validations_common/library/validations_read_ini.py b/validations_common/library/validations_read_ini.py index a4f0c35..efe6ae6 100644 --- a/validations_common/library/validations_read_ini.py +++ b/validations_common/library/validations_read_ini.py @@ -11,17 +11,17 @@ # implied. # See the License for the specific language governing permissions and # limitations under the License. +""" +Ansible module to read a value from an INI file. +Usage: +validations_read_ini: path=/path/to/file.ini section=default key=something -# Ansible module to read a value from an Ini file. -# Usage: -# - validations_read_ini: path=/path/to/file.ini section=default key=something -# register: my_ini -# -# This will read the `path/to/file.ini` file and read the `Hello!` value under: -# [default] -# something = Hello! -# -# You can register the result and use it later with `{{ my_ini.value }}` +This will read the `path/to/file.ini` file and read the `Hello!` value under: + [default] + something = Hello! + +You can register the result and use it later with `{{ my_ini.value }}` +""" try: import configparser as ConfigParser @@ -35,6 +35,54 @@ from ansible.module_utils.basic import AnsibleModule from yaml import safe_load as yaml_safe_load + +DOCUMENTATION = ''' +--- +module: validations_read_ini +short_description: Get data from an ini file +description: + - Get data from an ini file +options: + path: + required: true + description: + - File path + type: str + section: + required: true + description: + - Section to look up + type: str + key: + required: true + description: + - Section key to look up + type: str + default: + required: false + description: + - Default value if key isn't found + ignore_missing_file: + required: false + description: + - Flag if a missing file should be ignored + type: bool +author: "Tomas Sedovic" +''' + +EXAMPLES = ''' +- hosts: fizzbuz + tasks: + - name: Lookup bar value + validations_read_ini: + path: config.ini + section: foo + key: bar + ignore_missing_file: True + register: bar_value +''' + + # Possible return values class ReturnValue(Enum): OK = 0 @@ -87,48 +135,6 @@ def get_result(path, section, key, default=None): return (ret, msg, value) -DOCUMENTATION = ''' ---- -module: validations_read_ini -short_description: Get data from an ini file -description: - - Get data from an ini file -options: - path: - required: true - description: - - File path - type: str - section: - required: true - description: - - Section to look up - type: str - key: - required: true - description: - - Section key to look up - type: str - default: - required: false - description: - - Default value if key isn't found - ignore_missing_file: - required: false - description: - - Flag if a missing file should be ignored - type: bool -author: "Tomas Sedovic" -''' - -EXAMPLES = ''' -- hosts: webservers - tasks: - - name: Lookup bar value - validations_read_ini: path=config.ini section=foo key=bar ignore_missing_file=True -''' - - def main(): module = AnsibleModule( argument_spec=yaml_safe_load(DOCUMENTATION)['options']