[PATCH 08/21] utils: Add a new warn_deprecated helper

[Mathieu Bridon]

From: Mathieu Bridon <bochecha at daitauha.fr>

This helps deprecate parts of the API properly, emitting a warning for
API users.

We're going to start using it soon.
---
 src/pyrpkg/utils.py | 20 ++++++++++++++++++++
 test/test_utils.py  | 38 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/src/pyrpkg/utils.py b/src/pyrpkg/utils.py
index 2d16ce0..1d95218 100644
--- a/src/pyrpkg/utils.py
+++ b/src/pyrpkg/utils.py
@@ -13,6 +13,10 @@ This module contains a bunch of utilities used elsewhere in pyrpkg.
 """
 
 
+import warnings
+warnings.simplefilter('always', DeprecationWarning)
+
+
 class cached_property(property):
     """A property caching its return value
 
@@ -41,3 +45,19 @@ class cached_property(property):
             v = super(cached_property, self).__get__(inst, type)
             setattr(inst, '_%s' % self.fget.__name__, v)
             return v
+
+
+def warn_deprecated(clsname, oldname, newname):
+    """Emit a deprecation warning
+
+    Args:
+        clsname (str): The name of the class which has its attribute
+            deprecated.
+        oldname (str): The name of the deprecated attribute.
+        newname (str): The name of the new attribute, which should be used
+            instead.
+    """
+    warnings.warn(
+        "%s.%s is deprecated and will be removed eventually.\n    Please "
+        "use %s.%s instead." % (clsname, oldname, clsname, newname),
+        DeprecationWarning, stacklevel=3)
diff --git a/test/test_utils.py b/test/test_utils.py
index 047dde5..f9aa14a 100644
--- a/test/test_utils.py
+++ b/test/test_utils.py
@@ -1,11 +1,14 @@
 import os
 import sys
 import unittest
+import warnings
+
+import mock
 
 old_path = list(sys.path)
 src_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), '../src')
 sys.path.insert(0, src_path)
-from pyrpkg.utils import cached_property
+from pyrpkg.utils import cached_property, warn_deprecated
 sys.path = old_path
 
 
@@ -121,3 +124,36 @@ class CachedPropertyTestCase(unittest.TestCase):
         self.assertEqual(len(bar_runs), 1)
         self.assertEqual(b.foo, 43)
         self.assertEqual(len(bar_runs), 1)
+
+
+class DeprecationUtilsTestCase(unittest.TestCase):
+    def setUp(self):
+        warnings.simplefilter('always', DeprecationWarning)
+
+    @mock.patch('sys.stderr')
+    def test_warn_deprecated(self, mock_stderr):
+        class Foo(object):
+            def old_method(self):
+                warn_deprecated(self.__class__.__name__, 'old_method',
+                                'new_method')
+                return self.new_method()
+
+            def new_method(self):
+                return "Yay!"
+
+        def mock_write(msg):
+            written_lines.append(msg)
+
+        written_lines = []
+        mock_stderr.write.side_effect = mock_write
+
+        foo = Foo()
+        self.assertEqual(foo.old_method(), foo.new_method())
+        self.assertEqual(len(written_lines), 1)
+        self.assertTrue('DeprecationWarning' in written_lines[0])
+        self.assertTrue('Foo.old_method' in written_lines[0])
+        self.assertTrue('Foo.new_method' in written_lines[0])
+
+        warnings.simplefilter('error', DeprecationWarning)
+        self.assertRaises(DeprecationWarning, foo.old_method)
+        self.assertEqual(len(written_lines), 1)
-- 
2.1.0