Don't mix deprecations messages with warnings messages (#21337)

* Remove unused attribute '_passthrough'

* Don't mix deprecations with warnings

* Return values: add 'deprecations' key used internally

* 'deprecations' and 'warnings' return values: add tests

docs/docsite/rst/common_return_values.rst

@@ -84,6 +84,10 @@ warnings
 ````````
 This key contains a list of strings that will be presented to the user.
 
+deprecations
+````````````
+This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are `msg` and `version`, values are string, value for the `version` key can be an empty string.
+
 .. seealso::
 
    :doc:`modules`

lib/ansible/module_utils/basic.py

@@ -689,7 +689,6 @@ class AnsibleModule(object):
         self.run_command_environ_update = {}
         self._warnings = []
         self._deprecations = []
-        self._passthrough = ['warnings', 'deprecations']
 
         self.aliases = {}
         self._legal_inputs = ['_ansible_check_mode', '_ansible_no_log', '_ansible_debug', '_ansible_diff', '_ansible_verbosity', '_ansible_selinux_special_fs', '_ansible_module_name', '_ansible_version', '_ansible_syslog_facility', '_ansible_socket']
@@ -1949,15 +1948,19 @@ class AnsibleModule(object):
                     self.warn(w)
             else:
                 self.warn(kwargs['warnings'])
+
         if self._warnings:
             kwargs['warnings'] = self._warnings
 
         if 'deprecations' in kwargs:
             if isinstance(kwargs['deprecations'], list):
                 for d in kwargs['deprecations']:
-                    self.deprecate(d)
+                    if isinstance(d, SEQUENCETYPE) and len(d) == 2:
+                       self.deprecate(d[0], version=d[1])
+                    else:
+                       self.deprecate(d)
             else:
-                self.warn(kwargs['deprecations'])
+                self.deprecate(d)
 
         if self._deprecations:
             kwargs['deprecations'] = self._deprecations

test/units/module_utils/basic/test_deprecate_warn.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+import json
+import sys
+
+from ansible.compat.tests import unittest
+from units.mock.procenv import swap_stdin_and_argv, swap_stdout
+
+import ansible.module_utils.basic
+
+
+class TestAnsibleModuleWarnDeprecate(unittest.TestCase):
+    """Test the AnsibleModule Warn Method"""
+
+    def test_warn(self):
+        args = json.dumps(dict(ANSIBLE_MODULE_ARGS={}))
+        with swap_stdin_and_argv(stdin_data=args):
+            with swap_stdout():
+
+                ansible.module_utils.basic._ANSIBLE_ARGS = None
+                am = ansible.module_utils.basic.AnsibleModule(
+                    argument_spec = dict(),
+                )
+                am._name = 'unittest'
+
+                am.warn('warning1')
+
+                with self.assertRaises(SystemExit):
+                    am.exit_json(warnings=['warning2'])
+                self.assertEquals(json.loads(sys.stdout.getvalue())['warnings'], ['warning1', 'warning2'])
+
+    def test_deprecate(self):
+        args = json.dumps(dict(ANSIBLE_MODULE_ARGS={}))
+        with swap_stdin_and_argv(stdin_data=args):
+            with swap_stdout():
+
+                ansible.module_utils.basic._ANSIBLE_ARGS = None
+                am = ansible.module_utils.basic.AnsibleModule(
+                    argument_spec = dict(),
+                )
+                am._name = 'unittest'
+
+                am.deprecate('deprecation1')
+                am.deprecate('deprecation2', '2.3')
+
+                with self.assertRaises(SystemExit):
+                    am.exit_json(deprecations=['deprecation3', ('deprecation4', '2.4')])
+                output = json.loads(sys.stdout.getvalue())
+                self.assertTrue('warnings' not in output or output['warnings'] == [])
+                self.assertEquals(output['deprecations'], [
+                    {u'msg': u'deprecation1', u'version': None},
+                    {u'msg': u'deprecation2', u'version': '2.3'},
+                    {u'msg': u'deprecation3', u'version': None},
+                    {u'msg': u'deprecation4', u'version': '2.4'},
+                ])
+