From 90799975b432562246f4c4af586a8b3082e0995c Mon Sep 17 00:00:00 2001
From: Joshua Harlow <harlowja@yahoo-inc.com>
Date: Mon, 27 Jul 2015 16:39:47 -0700
Subject: [PATCH] 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               | 29 +++++++++++++++++++++++++
 debtcollector/tests/test_deprecation.py | 10 +++++++++
 doc/source/api.rst                      |  5 +++++
 doc/source/examples.rst                 | 21 ++++++++++++++++++
 tox.ini                                 |  1 -
 5 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/debtcollector/__init__.py b/debtcollector/__init__.py
index d4d32bb..738ce25 100644
--- a/debtcollector/__init__.py
+++ b/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)
diff --git a/debtcollector/tests/test_deprecation.py b/debtcollector/tests/test_deprecation.py
index 8184280..be79f80 100644
--- a/debtcollector/tests/test_deprecation.py
+++ b/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__)
diff --git a/doc/source/api.rst b/doc/source/api.rst
index dc33af8..4469ff7 100644
--- a/doc/source/api.rst
+++ b/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
 -----
 
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
index 0e94457..3ad6edb 100644
--- a/doc/source/examples.rst
+++ b/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'
diff --git a/tox.ini b/tox.ini
index d47e71b..8ba8fab 100644
--- a/tox.ini
+++ b/tox.ini
@@ -34,7 +34,6 @@ commands =
 
 [flake8]
 # E123, E125 skipped as they are invalid PEP-8.
-
 show-source = True
 ignore = E123,E125
 builtins = _