diff --git a/podgen/decorators.py b/podgen/decorators.py new file mode 100644 index 0000000..1c2ab43 --- /dev/null +++ b/podgen/decorators.py @@ -0,0 +1,44 @@ +from __future__ import absolute_import + +import warnings + +def deprecated(deprecated_since, removed_in, description): + """Decorator for marking functions as deprecated. It wraps and copies name + and documentation of the decorated function. This decorator only allows for + deprecation of functions. + + :param deprecated_since: Version in which the function was deprecated. + :param removed_in: Version in which the function is to be removed. + :param description: Description of the deprecation. + :returns: Decorated function. + """ + + def deprecation_decorator(func): + def func_wrapper(*args, **kwargs): + deprecation_warning( + func.__name__, + deprecated_since, + removed_in, + description) + return func(*args, **kwargs) + + # Hide the decorator by taking the decorated functions name and docs. + func_wrapper.__name__ = func.__name__ + func_wrapper.__doc__ = func.__doc__ + return func_wrapper + return deprecation_decorator + +def deprecation_warning( + deprecated_name, + deprecated_since, + removed_in, + description): + + warnings.warn\ + ( + "{} is deprecated as of {} and will be removed in {}. {}" \ + .format(deprecated_name, deprecated_since, removed_in, \ + description), + category=DeprecationWarning, + stacklevel=2 + ) diff --git a/podgen/podcast.py b/podgen/podcast.py index 41e96a3..0c8caa9 100644 --- a/podgen/podcast.py +++ b/podgen/podcast.py @@ -20,6 +20,7 @@ import dateutil.tz from podgen import EPISODE_TYPE_FULL +from podgen.decorators import deprecated from podgen.episode import Episode from podgen.warnings import NotSupportedByItunesWarning from podgen.util import ensure_format, formatRFC2822, listToHumanreadableStr, \ @@ -670,6 +671,7 @@ def _get_xslt_pi(self): 'type="text/xsl" href="' + quote_sanitized + '"', ), encoding="UTF-8").decode("UTF-8") + @deprecated('1.2.0', '2.0.0', 'Please use rss_str() directly.') def __str__(self): """Print the podcast in RSS format, using the default options. diff --git a/podgen/tests/test_podcast.py b/podgen/tests/test_podcast.py index fa81180..9a6fd5d 100644 --- a/podgen/tests/test_podcast.py +++ b/podgen/tests/test_podcast.py @@ -305,6 +305,15 @@ def test_generator(self): assert software_name in generator assert self.programname not in generator + def test__str__deprecation(self): + # Context manager catches and records deprecation warnings. + with warnings.catch_warnings(record=True) as catched_warning: + warnings.simplefilter("always") + + assert str(self.fg) + assert len(catched_warning) == 1 + assert issubclass(catched_warning[-1].category, DeprecationWarning) + def test_str(self): assert str(self.fg) == self.fg.rss_str( minimize=False,