Deprecate str() to generate RSS

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
+        )

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.
 

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,