Add AnsibleModule signature schema, and fix associated issues (#43512)

docs/docsite/rst/dev_guide/testing_validate-modules.rst

@@ -120,6 +120,7 @@ Errors
   329       Default value from the argument_spec is not compatible with type defined in the argument_spec
   330       Choices value from the argument_spec is not compatible with type defined in the argument_spec
   331       argument in argument_spec must be a dictionary/hash when used
+  332       ``AnsibleModule`` schema validation error
   ..
 ---------   -------------------
   **4xx**   **Syntax**

lib/ansible/modules/cloud/amazon/ecs_attribute.py

@@ -257,7 +257,7 @@ def main():
         attributes=dict(required=True, type='list'),
     ))
 
-    required_together = (['cluster', 'ec2_instance_id', 'attributes'])
+    required_together = [['cluster', 'ec2_instance_id', 'attributes']]
 
     module = AnsibleModule(argument_spec=argument_spec, supports_check_mode=True,
                            required_together=required_together)

lib/ansible/modules/cloud/amazon/ecs_cluster.py

@@ -162,7 +162,7 @@ def main():
         delay=dict(required=False, type='int', default=10),
         repeat=dict(required=False, type='int', default=10)
     ))
-    required_together = (['state', 'name'])
+    required_together = [['state', 'name']]
 
     module = AnsibleModule(argument_spec=argument_spec, supports_check_mode=True, required_together=required_together)
 

lib/ansible/modules/cloud/amazon/elb_application_lb.py

@@ -540,9 +540,9 @@ def main():
                               required_if=[
                                   ('state', 'present', ['subnets', 'security_groups'])
                               ],
-                              required_together=(
+                              required_together=[
                                   ['access_logs_enabled', 'access_logs_s3_bucket', 'access_logs_s3_prefix']
-                              )
+                              ]
                               )
 
     # Quick check of listeners parameters

lib/ansible/modules/cloud/amazon/elb_application_lb_facts.py

@@ -258,7 +258,7 @@ def main():
     )
 
     module = AnsibleModule(argument_spec=argument_spec,
-                           mutually_exclusive=['load_balancer_arns', 'names'],
+                           mutually_exclusive=[['load_balancer_arns', 'names']],
                            supports_check_mode=True
                            )
 

lib/ansible/modules/cloud/amazon/elb_target.py

@@ -296,7 +296,7 @@ def main():
     )
 
     module = AnsibleModule(argument_spec=argument_spec,
-                           mutually_exclusive=['target_group_arn', 'target_group_name']
+                           mutually_exclusive=[['target_group_arn', 'target_group_name']]
                            )
 
     if not HAS_BOTO3:

lib/ansible/modules/cloud/amazon/elb_target_group_facts.py

@@ -247,7 +247,7 @@ def main():
     )
 
     module = AnsibleModule(argument_spec=argument_spec,
-                           mutually_exclusive=['load_balancer_arn', 'target_group_arns', 'names'],
+                           mutually_exclusive=[['load_balancer_arn', 'target_group_arns', 'names']],
                            supports_check_mode=True
                            )
 

lib/ansible/modules/cloud/digital_ocean/digital_ocean_floating_ip.py

@@ -302,12 +302,12 @@ def main():
             validate_certs=dict(type='bool', default=True),
             timeout=dict(type='int', default=30),
         ),
-        required_if=([
+        required_if=[
             ('state', 'delete', ['ip'])
-        ]),
+        ],
-        mutually_exclusive=(
+        mutually_exclusive=[
             ['region', 'droplet_id']
-        ),
+        ],
     )
 
     core(module)

lib/ansible/modules/cloud/opennebula/one_service.py

@@ -693,7 +693,7 @@ def main():
                                ['template_id', 'template_name', 'cardinality'],
                                ['service_id', 'custom_attrs']
                            ],
-                           required_together=['role', 'cardinality'],
+                           required_together=[['role', 'cardinality']],
                            supports_check_mode=True)
 
     auth = get_connection_info(module)

lib/ansible/modules/net_tools/basics/get_url.py

@@ -398,7 +398,7 @@ def main():
         argument_spec=argument_spec,
         add_file_common_args=True,
         supports_check_mode=True,
-        mutually_exclusive=(['checksum', 'sha256sum']),
+        mutually_exclusive=[['checksum', 'sha256sum']],
     )
 
     url = module.params['url']

lib/ansible/modules/net_tools/dnsimple.py

@@ -169,9 +169,9 @@ def main():
             state=dict(required=False, choices=['present', 'absent']),
             solo=dict(required=False, type='bool'),
         ),
-        required_together=(
+        required_together=[
             ['record', 'value']
-        ),
+        ],
         supports_check_mode=True,
     )
 

lib/ansible/modules/net_tools/dnsmadeeasy.py

@@ -562,9 +562,9 @@ def main():
             ip5=dict(required=False),
             validate_certs=dict(default='yes', type='bool'),
         ),
-        required_together=(
+        required_together=[
             ['record_value', 'record_ttl', 'record_type']
-        ),
+        ],
         required_if=[
             ['failover', True, ['autoFailover', 'port', 'protocol', 'ip1', 'ip2']],
             ['monitor', True, ['port', 'protocol', 'maxEmails', 'systemDescription', 'ip1']]

lib/ansible/modules/network/vyos/vyos_interface.py

@@ -393,7 +393,7 @@ def main():
     required_one_of = [['name', 'aggregate']]
     mutually_exclusive = [['name', 'aggregate']]
 
-    required_together = (['speed', 'duplex'])
+    required_together = [['speed', 'duplex']]
     module = AnsibleModule(argument_spec=argument_spec,
                            required_one_of=required_one_of,
                            mutually_exclusive=mutually_exclusive,

lib/ansible/modules/packaging/language/pear.py

@@ -201,10 +201,9 @@ def check_packages(module, packages, state):
 def main():
     module = AnsibleModule(
         argument_spec=dict(
-            name=dict(aliases=['pkg']),
+            name=dict(aliases=['pkg'], required=True),
             state=dict(default='present', choices=['present', 'installed', "latest", 'absent', 'removed']),
             executable=dict(default=None, required=False, type='path')),
-        required_one_of=[['name']],
         supports_check_mode=True)
 
     p = module.params

test/sanity/validate-modules/main.py

@@ -43,7 +43,7 @@ from ansible.utils.plugin_docs import BLACKLIST, add_fragments, get_docstring
 
 from module_args import AnsibleModuleImportError, get_argument_spec
 
-from schema import doc_schema, metadata_1_1_schema, return_schema
+from schema import ansible_module_kwargs_schema, doc_schema, metadata_1_1_schema, return_schema
 
 from utils import CaptureStd, NoArgsAnsibleModule, compare_unordered_lists, is_empty, parse_yaml
 from voluptuous.humanize import humanize_error
@@ -1032,19 +1032,7 @@ class ModuleValidator(Validator):
                 msg='version_added should be %s. Currently %s' % (should_be, version_added)
             )
 
-    def _validate_argument_spec(self, docs):
+    def _validate_ansible_module_call(self, docs):
-        if not self.analyze_arg_spec:
-            return
-
-        if docs is None:
-            docs = {}
-
-        try:
-            add_fragments(docs, self.object_path, fragment_loader=fragment_loader)
-        except Exception:
-            # Cannot merge fragments
-            return
-
         try:
             spec, args, kwargs = get_argument_spec(self.path)
         except AnsibleModuleImportError as e:
@@ -1059,6 +1047,23 @@ class ModuleValidator(Validator):
             )
             return
 
+        self._validate_docs_schema(kwargs, ansible_module_kwargs_schema, 'AnsibleModule', 332)
+
+        self._validate_argument_spec(docs, spec, kwargs)
+
+    def _validate_argument_spec(self, docs, spec, kwargs):
+        if not self.analyze_arg_spec:
+            return
+
+        if docs is None:
+            docs = {}
+
+        try:
+            add_fragments(docs, self.object_path, fragment_loader=fragment_loader)
+        except Exception:
+            # Cannot merge fragments
+            return
+
         # Use this to access type checkers later
         module = NoArgsAnsibleModule({})
 
@@ -1375,7 +1380,7 @@ class ModuleValidator(Validator):
                 # FIXME if +2 then file should be empty? - maybe add this only in the future
 
         if self._python_module() and not self._just_docs() and not end_of_deprecation_should_be_docs_only:
-            self._validate_argument_spec(docs)
+            self._validate_ansible_module_call(docs)
             self._check_for_sys_exit()
             self._find_blacklist_imports()
             main = self._find_main_call()

test/sanity/validate-modules/schema.py

@@ -16,10 +16,41 @@
 #    You should have received a copy of the GNU General Public License
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-from voluptuous import PREVENT_EXTRA, Any, Required, Schema, Self
+from voluptuous import PREVENT_EXTRA, All, Any, Length, Required, Schema, Self
 from ansible.module_utils.six import string_types
 list_string_types = list(string_types)
 
+
+def sequence_of_sequences(min=None, max=None):
+    return All(
+        Any(
+            None,
+            [Length(min=min, max=max)],
+            tuple([Length(min=min, max=max)]),
+        ),
+        Any(
+            None,
+            [Any(list, tuple)],
+            tuple([Any(list, tuple)]),
+        ),
+    )
+
+
+ansible_module_kwargs_schema = Schema(
+    {
+        'argument_spec': dict,
+        'bypass_checks': bool,
+        'no_log': bool,
+        'check_invalid_arguments': Any(None, bool),
+        'mutually_exclusive': sequence_of_sequences(min=2),
+        'required_together': sequence_of_sequences(min=2),
+        'required_one_of': sequence_of_sequences(min=2),
+        'add_file_common_args': bool,
+        'supports_check_mode': bool,
+        'required_if': sequence_of_sequences(min=3),
+    }
+)
+
 suboption_schema = Schema(
     {
         Required('description'): Any(list_string_types, *string_types),