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 = _