Expose a top level 'deprecate' function

To make it possible for easy usage of the message generating
formats that debtcollector uses, allow users to call into a
helper function that can be used to deprecate arbitrary things.

Closes-Bug: 1478676

Change-Id: I4d5b8fe44150ce2d6d5418a9f4e13812e6b558ce

debtcollector/__init__.py

@@ -14,6 +14,35 @@
 
 import pbr.version
 
+from debtcollector import _utils
 
 __version__ = pbr.version.VersionInfo(
     'debtcollector').version_string()
+
+
+def deprecate(prefix, postfix=None, message=None,
+              version=None, removal_version=None,
+              stacklevel=3, category=DeprecationWarning):
+    """Helper to deprecate some thing using generated message format.
+
+    :param prefix: prefix string used as the prefix of the output message
+    :param postfix: postfix string used as the postfix of the output message
+    :param message: message string used as ending contents of the deprecate
+                    message
+    :param version: version string (represents the version this
+                    deprecation was created in)
+    :param removal_version: version string (represents the version this
+                            deprecation will be removed in); a string of '?'
+                            will denote this will be removed in some future
+                            unknown version
+    :param stacklevel: stacklevel used in the :func:`warnings.warn` function
+                       to locate where the users code is in the
+                       :func:`warnings.warn` call
+    :param category: the :mod:`warnings` category to use, defaults to
+                     :py:class:`DeprecationWarning` if not provided
+    """
+    out_message = _utils.generate_message(prefix, postfix=postfix,
+                                          version=version, message=message,
+                                          removal_version=removal_version)
+    _utils.deprecation(out_message, stacklevel=stacklevel,
+                       category=category)

debtcollector/tests/test_deprecation.py

@@ -14,6 +14,7 @@
 
 import warnings
 
+import debtcollector
 from debtcollector import moves
 from debtcollector import removals
 from debtcollector import renames
@@ -136,6 +137,15 @@ OldHotness2 = moves.moved_class(NewHotness, 'OldHotness', __name__,
                                 category=PendingDeprecationWarning)
 
 
+class DeprecateAnythingTest(test_base.TestCase):
+    def test_generation(self):
+        with warnings.catch_warnings(record=True) as capture:
+            warnings.simplefilter("always")
+            debtcollector.deprecate("Its broken")
+            debtcollector.deprecate("Its really broken")
+        self.assertEqual(2, len(capture))
+
+
 class MovedInheritableClassTest(test_base.TestCase):
     def test_broken_type_class(self):
         self.assertRaises(TypeError, moves.moved_class, 'b', __name__)

doc/source/api.rst

@@ -12,6 +12,11 @@ are defined below.
     to a **minimum** as they may be altered, refactored or moved to other
     locations **without** notice (and without the typical deprecation cycle).
 
+Helpers
+-------
+
+.. automodule:: debtcollector
+
 Moves
 -----
 

doc/source/examples.rst

@@ -313,3 +313,24 @@ A basic example to do just this:
 .. testoutput::
 
     __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated, please use the 'nizzle' argument instead: Pretty please stop using it
+
+Deprecating anything else
+-------------------------
+
+For use-cases which do not fit the above decorators, properties other
+provided functionality the final option is to use debtcollectors
+the :py:func:`~debtcollector.deprecate` function to make your own
+messages (using the message building logic that debtcollector uses itself).
+
+A basic example to do just this:
+
+.. doctest::
+
+    >>> import warnings
+    >>> warnings.simplefilter("always")
+    >>> import debtcollector
+    >>> debtcollector.deprecate("This is no longer supported", version="1.0")
+
+.. testoutput::
+
+    __main__:1: DeprecationWarning: This is no longer supported in version '1.0'

tox.ini

@@ -34,7 +34,6 @@ commands =
 
 [flake8]
 # E123, E125 skipped as they are invalid PEP-8.
-
 show-source = True
 ignore = E123,E125
 builtins = _