Merge "Expanded docstrings for library subpackage."

validations_common/library/__init__.py

@@ -0,0 +1,2 @@
+"""Provides several ansible modules for I/O needs of validations.
+"""

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(

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":

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']