add custom module type validation (#27183)

* Module argument_spec now accepts a callable for the type argument, which is passed through and called with the value when appropriate. On validation/conversion failure, the name of the callable (or its type as a fallback) is used in the error message.
* adds basic smoke tests for custom callable validator functionality

CHANGELOG.md

@@ -33,6 +33,7 @@ Ansible Changes By Release
   - Also added an ansible-config CLI to allow for listing config options and dumping current config (including origin)
   - TODO: build upon this to add many features detailed in ansible-config proposal https://github.com/ansible/proposals/issues/35
 * Windows modules now support the use of multiple shared module_utils files in the form of Powershell modules (.psm1), via `#Requires -Module Ansible.ModuleUtils.Whatever.psm1`
+* Python module argument_spec now supports custom validation logic by accepting a callable as the `type` argument.
 
 ### Deprecations
 * The behaviour when specifying `--tags` (or `--skip-tags`) multiple times on the command line

lib/ansible/module_utils/basic.py

@@ -1874,6 +1874,12 @@ class AnsibleModule(object):
             wanted = v.get('type', None)
             if k not in param:
                 continue
+
+            value = param[k]
+            if value is None:
+                continue
+
+            if not callable(wanted):
                 if wanted is None:
                     # Mostly we want to default to str.
                     # For values set to None explicitly, return None instead as
@@ -1881,15 +1887,15 @@ class AnsibleModule(object):
                     if param[k] is None:
                         continue
                     wanted = 'str'
-
-            value = param[k]
-            if value is None:
-                continue
-
                 try:
                     type_checker = self._CHECK_ARGUMENT_TYPES_DISPATCHER[wanted]
                 except KeyError:
                     self.fail_json(msg="implementation error: unknown type %s requested for %s" % (wanted, k))
+            else:
+                # set the type_checker to the callable, and reset wanted to the callable's name (or type if it doesn't have one, ala MagicMock)
+                type_checker = wanted
+                wanted = getattr(wanted, '__name__', to_native(type(wanted)))
+
             try:
                 param[k] = type_checker(value)
             except (TypeError, ValueError):

test/units/module_utils/basic/test_argument_spec.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division)
+__metaclass__ = type
+
+import json
+
+from ansible.compat.tests import unittest
+from ansible.compat.tests.mock import MagicMock
+from units.mock.procenv import swap_stdin_and_argv, swap_stdout
+from ansible.module_utils import basic
+
+
+class TestCallableTypeValidation(unittest.TestCase):
+    def setUp(self):
+        args = json.dumps(dict(ANSIBLE_MODULE_ARGS=dict(arg="42")))
+        self.stdin_swap_ctx = swap_stdin_and_argv(stdin_data=args)
+        self.stdin_swap_ctx.__enter__()
+
+        # since we can't use context managers and "with" without overriding run(), call them directly
+        self.stdout_swap_ctx = swap_stdout()
+        self.fake_stream = self.stdout_swap_ctx.__enter__()
+
+        basic._ANSIBLE_ARGS = None
+
+    def tearDown(self):
+        # since we can't use context managers and "with" without overriding run(), call them directly to clean up
+        self.stdin_swap_ctx.__exit__(None, None, None)
+        self.stdout_swap_ctx.__exit__(None, None, None)
+
+    def test_validate_success(self):
+        mock_validator = MagicMock(return_value=42)
+        m = basic.AnsibleModule(argument_spec=dict(
+            arg=dict(type=mock_validator)
+        ))
+
+        self.assertTrue(mock_validator.called)
+        self.assertEqual(m.params['arg'], 42)
+        self.assertEqual(type(m.params['arg']), int)
+
+    def test_validate_fail(self):
+        mock_validator = MagicMock(side_effect=TypeError("bad conversion"))
+        with self.assertRaises(SystemExit) as ecm:
+            m = basic.AnsibleModule(argument_spec=dict(
+                arg=dict(type=mock_validator)
+            ))
+
+        self.assertIn("bad conversion", json.loads(self.fake_stream.getvalue())['msg'])