Added a helper function to raise warnings until a specified salt version.

The helper raises a warning, by default, a ``DeprecationWarning``, until the provided ``version_info`` is matched, after which, a ``RuntimeError`` will be raised to remember the developers to remove the warning.

salt/utils/__init__.py

@@ -64,6 +64,7 @@ import salt._compat
 import salt.log
 import salt.minion
 import salt.payload
+import salt.version
 from salt.exceptions import (
     SaltClientError, CommandNotFoundError, SaltSystemExit
 )
@@ -1330,3 +1331,46 @@ def date_format(date=None, format="%Y-%m-%d"):
     'Dec 25, 2002'
     '''
     return date_cast(date).strftime(format)
+
+
+def warn_until(version_info, message,
+               category=DeprecationWarning, stacklevel=None):
+    '''
+    Helper function to raise a warning, by default, a ``DeprecationWarning``,
+    until the provided ``version_info``, after which, a ``RuntimeError`` will
+    be raised to remember the developers to remove the warning because the
+    version defined has matched.
+
+    :param version_info: The version info after which the warning becomes a
+                         ``RuntimeError``. For example ``(0, 17)``.
+    :param message: The warning message to be displayed.
+    :param category: The warning class to be thrown, by default
+                     ``DeprecationWarning``
+    :param stacklevel: There should be no need to set the value of
+                       ``stacklevel`` salt should be able to do the right thing
+    '''
+
+    if not isinstance(version_info, tuple):
+        raise RuntimeError(
+            'The \'version_info\' argument should be passed as a tuple.'
+        )
+
+    if stacklevel is None:
+        # Show the warning a triggered from the calling function not warn_until
+        stacklevel = 2
+
+    if salt.version.__version_info__ >= version_info:
+        caller = inspect.getframeinfo(sys._getframe(stacklevel-1))
+        raise RuntimeError(
+            'The warning triggered on filename {filename!r}, line number '
+            '{lineno}, is supposed to be shown until salt {until_version!r} '
+            'is released. Salt version is now {salt_version!r}. Please '
+            'remove the warning.'.format(
+                filename=caller.filename,
+                lineno=caller.lineno,
+                until_version='.'.join(map(str, version_info)),
+                salt_version='.'.join(map(str, salt.version.__version_info__))
+            ),
+        )
+
+    warnings.warn(message, category, stacklevel=stacklevel)

tests/unit/utils/warnings_test.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+'''
+    tests.unit.utils.warnings_test
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Test ``salt.utils.warn_until``
+
+    :codeauthor: :email:`Pedro Algarvio (pedro@algarvio.me)`
+    :copyright: © 2013 by the SaltStack Team, see AUTHORS for more details.
+    :license: Apache 2.0, see LICENSE for more details.
+'''
+
+# Import python libs
+import warnings
+
+# Import Salt Testing libs
+from salttesting import skipIf, TestCase
+from salttesting.helpers import ensure_in_syspath
+ensure_in_syspath('../../')
+
+# Import salt libs
+from salt.utils import warn_until
+
+# Import 3rd party libs
+try:
+    from mock import patch
+    HAS_MOCK = True
+except ImportError:
+    HAS_MOCK = False
+
+
+@skipIf(HAS_MOCK is False, 'mock python module is unavailable')
+class WarnUntilTestCase(TestCase):
+
+    @patch('salt.version')
+    def test_warning_raised(self, salt_version_mock):
+        # We *always* want *all* warnings thrown on this module
+        warnings.filterwarnings('always', '', DeprecationWarning, __name__)
+
+        # Define a salt version info
+        salt_version_mock.__version_info__ = (0, 16)
+
+        def raise_warning():
+            warn_until(
+                (0, 17), 'Deprecation Message!'
+            )
+
+        # raise_warning should show warning until version info is >= (0, 17)
+        with warnings.catch_warnings(record=True) as recorded_warnings:
+            raise_warning()
+            self.assertEqual(
+                'Deprecation Message!', str(recorded_warnings[0].message)
+            )
+
+        # Let's set version info to (0, 17), a RuntimeError should be raised
+        salt_version_mock.__version_info__ = (0, 17)
+        with self.assertRaisesRegexp(
+                RuntimeError,
+                r'The warning triggered on filename \'(.*)warnings_test.py\', '
+                r'line number ([\d]+), is supposed to be shown until salt '
+                r'\'0.17\' is released. Salt version is now \'0.17\'. Please '
+                r'remove the warning.'):
+            raise_warning()
+
+
+if __name__ == '__main__':
+    from integration import run_tests
+    run_tests(WarnUntilTestCase, needs_daemon=False)