Fix various sanity errors in plugins (#881) (#893)

* Fix deprecation of callables.

* Fix various sanity errors.

* Revert callback_type -> type transform.

* Fix stat_result times: these are float according to https://github.com/python/typeshed/blob/master/stdlib/3/os/__init__.pyi

* Apply suggestions from code review

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
(cherry picked from commit 7cf472855c)

Co-authored-by: Felix Fontein <felix@fontein.de>

meta/runtime.yml

@@ -740,3 +740,16 @@ plugin_routing:
         removal_version: 2.0.0
         warning_text: The mysql module_utils has been moved to the community.mysql collection.
       redirect: community.mysql.mysql
+  callback:
+    actionable:
+      deprecation:
+        removal_version: 2.0.0
+        warning_text: see plugin documentation for details
+    full_skip:
+      deprecation:
+        removal_version: 2.0.0
+        warning_text: see plugin documentation for details
+    stderr:
+      deprecation:
+        removal_version: 2.0.0
+        warning_text: see plugin documentation for details

plugins/become/pfexec.py

@@ -14,7 +14,7 @@ DOCUMENTATION = '''
         become_user:
             description:
                 - User you 'become' to execute the task
-                - This plugin ignores this setting as pfexec uses it's own ``exec_attr`` to figure this out,
+                - This plugin ignores this setting as pfexec uses it's own C(exec_attr) to figure this out,
                   but it is supplied here for Ansible to make decisions needed for the task execution, like file permissions.
             default: root
             ini:
@@ -80,8 +80,8 @@ DOCUMENTATION = '''
               - name: ansible_pfexec_wrap_execution
             env:
               - name: ANSIBLE_PFEXEC_WRAP_EXECUTION
-    note:
-      - This plugin ignores ``become_user`` as pfexec uses it's own ``exec_attr`` to figure this out.
+    notes:
+      - This plugin ignores I(become_user) as pfexec uses it's own C(exec_attr) to figure this out.
 '''
 
 from ansible.plugins.become import BecomeBase

plugins/callback/counter_enabled.py

@@ -6,11 +6,6 @@
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
-from ansible import constants as C
-from ansible.plugins.callback import CallbackBase
-from ansible.utils.color import colorize, hostcolor
-from ansible.template import Templar
-from ansible.playbook.task_include import TaskInclude
 
 DOCUMENTATION = '''
     callback: counter_enabled
@@ -26,6 +21,12 @@ DOCUMENTATION = '''
       - set as stdout callback in ansible.cfg  (stdout_callback = counter_enabled)
 '''
 
+from ansible import constants as C
+from ansible.plugins.callback import CallbackBase
+from ansible.utils.color import colorize, hostcolor
+from ansible.template import Templar
+from ansible.playbook.task_include import TaskInclude
+
 
 class CallbackModule(CallbackBase):
 

plugins/callback/mail.py

@@ -52,7 +52,7 @@ options:
     ini:
         - section: callback_mail
           key: bcc
-note:
+notes:
 - "TODO: expand configuration options now that plugins can leverage Ansible's configuration"
 '''
 

plugins/inventory/gitlab_runners.py

@@ -10,8 +10,8 @@ __metaclass__ = type
 DOCUMENTATION = '''
     name: gitlab_runners
     plugin_type: inventory
-    authors:
-      - Stefan Heitmüller (stefan.heitmueller@gmx.com)
+    author:
+      - Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>
     short_description: Ansible dynamic inventory plugin for GitLab runners.
     requirements:
         - python >= 2.7

plugins/lookup/chef_databag.py

@@ -34,7 +34,9 @@ EXAMPLES = """
 RETURN = """
   _raw:
     description:
-      - The value from the databag
+      - The value from the databag.
+    type: list
+    elements: dict
 """
 
 from ansible.errors import AnsibleError

plugins/lookup/consul_kv.py

@@ -98,6 +98,7 @@ RETURN = """
   _raw:
     description:
       - Value(s) stored in consul.
+    type: dict
 """
 
 import os

plugins/lookup/credstash.py

@@ -78,7 +78,8 @@ EXAMPLES = """
 RETURN = """
   _raw:
     description:
-      - value(s) stored in Credstash
+      - Value(s) stored in Credstash.
+    type: str
 """
 
 import os

plugins/lookup/cyberarkpassword.py

@@ -30,8 +30,8 @@ DOCUMENTATION = '''
         default: 'password'
       _extra:
         description: for extra_params values please check parameters for clipasswordsdk in CyberArk's "Credential Provider and ASCP Implementation Guide"
-    note:
-      - For Ansible on windows, please change the -parameters (-p, -d, and -o) to /parameters (/p, /d, and /o) and change the location of CLIPasswordSDK.exe
+    notes:
+      - For Ansible on Windows, please change the -parameters (-p, -d, and -o) to /parameters (/p, /d, and /o) and change the location of CLIPasswordSDK.exe.
 '''
 
 EXAMPLES = """

plugins/lookup/dig.py

@@ -77,8 +77,10 @@ EXAMPLES = """
 RETURN = """
   _list:
     description:
-      - list of composed strings or dictionaries with key and value
+      - List of composed strings or dictionaries with key and value
         If a dictionary, fields shows the keys returned depending on query type
+    type: list
+    elements: raw
     contains:
        ALL:
            description:

plugins/lookup/dsv.py

@@ -70,6 +70,8 @@ _list:
     description:
         - One or more JSON responses to C(GET /secrets/{path}).
         - See U(https://dsv.thycotic.com/api/index.html#operation/getSecret).
+    type: list
+    elements: dict
 """
 
 EXAMPLES = r"""

plugins/lookup/etcd3.py

@@ -94,6 +94,7 @@ DOCUMENTATION = '''
     seealso:
     - module: community.general.etcd3
     - ref: etcd_lookup
+      description: The etcd v2 lookup.
 
     requirements:
     - "etcd3 >= 0.10"

plugins/lookup/filetree.py

@@ -53,42 +53,60 @@ EXAMPLES = r"""
 
 RETURN = r"""
   _raw:
-    description: list of dictionaries with file information
+    description: List of dictionaries with file information.
+    type: list
+    elements: dict
     contains:
         src:
           description:
-          - full path to file.
-          - not returned when C(item.state) is set to C(directory).
+          - Full path to file.
+          - Not returned when I(item.state) is set to C(directory).
+          type: path
         root:
-          description: allows filtering by original location.
+          description: Allows filtering by original location.
+          type: path
         path:
-          description: contains the relative path to root.
+          description: Contains the relative path to root.
+          type: path
         mode:
           description: The permissions the resulting file or directory.
+          type: str
         state:
           description: TODO
+          type: str
         owner:
           description: Name of the user that owns the file/directory.
+          type: raw
         group:
           description: Name of the group that owns the file/directory.
+          type: raw
         seuser:
           description: The user part of the SELinux file context.
+          type: raw
         serole:
           description: The role part of the SELinux file context.
+          type: raw
         setype:
           description: The type part of the SELinux file context.
+          type: raw
         selevel:
           description: The level part of the SELinux file context.
+          type: raw
         uid:
           description: Owner ID of the file/directory.
+          type: int
         gid:
           description: Group ID of the file/directory.
+          type: int
         size:
           description: Size of the target.
+          type: int
         mtime:
           description: Time of last modification.
+          type: float
         ctime:
           description: Time of last metadata update or creation (depends on OS).
+          type: float
 """
 import os
 import pwd

plugins/lookup/gcp_storage_file.py

@@ -40,6 +40,8 @@ RETURN = '''
 _raw:
     description:
         - base64 encoded file content
+    type: list
+    elements: str
 '''
 
 import base64

plugins/lookup/hashi_vault.py

@@ -241,6 +241,8 @@ RETURN = """
 _raw:
   description:
     - secrets(s) requested
+  type: list
+  elements: dict
 """
 
 import os

plugins/lookup/hiera.py

@@ -18,7 +18,7 @@ DOCUMENTATION = '''
             description:
                 - The list of keys to lookup on the Puppetmaster
             type: list
-            element_type: string
+            elements: string
             required: True
       _bin_file:
             description:
@@ -55,7 +55,8 @@ RETURN = """
     _raw:
         description:
             - a value associated with input key
-        type: strings
+        type: list
+        elements: str
 """
 
 import os

plugins/lookup/keyring.py

@@ -29,7 +29,9 @@ EXAMPLES = """
 
 RETURN = """
   _raw:
-    description: secrets stored
+    description: Secrets stored.
+    type: list
+    elements: str
 """
 
 HAS_KEYRING = True

plugins/lookup/lastpass.py

@@ -32,6 +32,8 @@ EXAMPLES = """
 RETURN = """
   _raw:
     description: secrets stored
+    type: list
+    elements: str
 """
 
 from subprocess import Popen, PIPE

plugins/lookup/lmdb_kv.py

@@ -48,6 +48,8 @@ EXAMPLES = """
 RETURN = """
 _raw:
   description: value(s) stored in LMDB
+  type: list
+  elements: raw
 """
 
 

plugins/lookup/nios.py

@@ -83,7 +83,6 @@ RETURN = """
 obj_type:
   description:
     - The object type specified in the terms argument
-  returned: always
   type: complex
   contains:
     obj_field:

plugins/lookup/nios_next_ip.py

@@ -64,7 +64,6 @@ RETURN = """
 _list:
   description:
     - The list of next IP addresses available
-  returned: always
   type: list
 """
 

plugins/lookup/nios_next_network.py

@@ -74,7 +74,6 @@ RETURN = """
 _list:
   description:
     - The list of next network addresses available
-  returned: always
   type: list
 """
 

plugins/lookup/onepassword.py

@@ -86,6 +86,8 @@ EXAMPLES = """
 RETURN = """
   _raw:
     description: field data requested
+    type: list
+    elements: str
 """
 
 import errno

plugins/lookup/onepassword_raw.py

@@ -62,6 +62,8 @@ EXAMPLES = """
 RETURN = """
   _raw:
     description: field data requested
+    type: list
+    elements: dict
 """
 
 import json

plugins/lookup/passwordstore.py

@@ -91,6 +91,8 @@ RETURN = """
 _raw:
   description:
     - a password
+  type: list
+  elements: str
 """
 
 import os

plugins/lookup/redis.py

@@ -67,6 +67,8 @@ EXAMPLES = """
 RETURN = """
 _raw:
   description: value(s) stored in Redis
+  type: list
+  elements: str
 """
 
 import os

plugins/lookup/shelvefile.py

@@ -29,6 +29,8 @@ EXAMPLES = """
 RETURN = """
 _list:
   description: value(s) of key(s) in shelve file(s)
+  type: list
+  elements: str
 """
 import shelve
 

plugins/lookup/tss.py

@@ -66,6 +66,8 @@ _list:
     description:
         - The JSON responses to C(GET /secrets/{id}).
         - See U(https://updates.thycotic.net/secretserver/restapiguide/TokenAuth/#operation--secrets--id--get).
+    type: list
+    elements: dict
 """
 
 EXAMPLES = r"""