Rename child twiml methods to be the tag name and deprecate old methods

tests/unit/base/test_deprecation.py

@@ -0,0 +1,43 @@
+import unittest
+import warnings
+
+from twilio.base.obsolete import deprecated_method
+
+
+class DeprecatedMethodTest(unittest.TestCase):
+
+    def test_deprecation_decorator(self):
+
+        @deprecated_method()
+        def old_method():
+            return True
+
+        with warnings.catch_warnings(record=True) as caught_warnings:
+            warnings.simplefilter("always")
+            # Call function that should raise a warning, but still execute
+            self.assertTrue(old_method())
+            if len(caught_warnings):
+                self.assertEqual(
+                    str(caught_warnings[0].message),
+                    'Function method .old_method() is being deprecated'
+                )
+                assert issubclass(caught_warnings[0].category, DeprecationWarning)
+
+    def test_deprecation_decorator_with_new_method(self):
+
+        @deprecated_method('new_method')
+        def old_method():
+            return True
+
+        with warnings.catch_warnings(record=True) as caught_warnings:
+            warnings.simplefilter("always")
+
+            # Call function that should raise a warning, but still execute
+            self.assertTrue(old_method())
+
+            if len(caught_warnings):
+                self.assertEqual(
+                    str(caught_warnings[0].message),
+                    'Function method .old_method() is being deprecated in favor of .new_method()'
+                )
+                assert issubclass(caught_warnings[0].category, DeprecationWarning)

twilio/base/obsolete.py

@@ -21,3 +21,23 @@ def new_func(*args, **kwargs):
         )
 
     return new_func
+
+
+def deprecated_method(new_func=None):
+    """
+    This is a decorator which can be used to mark deprecated methods.
+    It will report in a DeprecationWarning being emitted to stderr when the deprecated method is used.
+    """
+
+    def deprecated_method_wrapper(func):
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            msg = 'Function method .{}() is being deprecated'.format(func.__name__)
+            msg += ' in favor of .{}()'.format(new_func) if new_func else ''
+            warnings.warn(msg, DeprecationWarning)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return deprecated_method_wrapper

twilio/twiml/fax_response.py

@@ -7,6 +7,7 @@
 """
 
 import json
+from twilio.base.obsolete import deprecated_method
 from twilio.twiml import (
     TwiML,
     format_language,

twilio/twiml/messaging_response.py

@@ -7,6 +7,7 @@
 """
 
 import json
+from twilio.base.obsolete import deprecated_method
 from twilio.twiml import (
     TwiML,
     format_language,

twilio/twiml/voice_response.py

@@ -7,6 +7,7 @@
 """
 
 import json
+from twilio.base.obsolete import deprecated_method
 from twilio.twiml import (
     TwiML,
     format_language,
@@ -618,7 +619,7 @@ def __init__(self, message=None, **kwargs):
         if message:
             self.value = message
 
-    def ssml_break(self, strength=None, time=None, **kwargs):
+    def break_(self, strength=None, time=None, **kwargs):
         """
         Create a <Break> element
 
@@ -630,7 +631,20 @@ def ssml_break(self, strength=None, time=None, **kwargs):
         """
         return self.nest(SsmlBreak(strength=strength, time=time, **kwargs))
 
-    def ssml_emphasis(self, words, level=None, **kwargs):
+    @deprecated_method(break_)
+    def ssml_break(self, strength=None, time=None, **kwargs):
+        """
+        Create a <Break> element
+
+        :param strength: Set a pause based on strength
+        :param time: Set a pause to a specific length of time in seconds or milliseconds, available values: [number]s, [number]ms
+        :param kwargs: additional attributes
+
+        :returns: <Break> element
+        """
+        return self.break_(strength=strength, time=time, **kwargs)
+
+    def emphasis(self, words, level=None, **kwargs):
         """
         Create a <Emphasis> element
 
@@ -642,7 +656,20 @@ def ssml_emphasis(self, words, level=None, **kwargs):
         """
         return self.nest(SsmlEmphasis(words, level=level, **kwargs))
 
-    def ssml_lang(self, words, xml_lang=None, **kwargs):
+    @deprecated_method(emphasis)
+    def ssml_emphasis(self, words, level=None, **kwargs):
+        """
+        Create a <Emphasis> element
+
+        :param words: Words to emphasize
+        :param level: Specify the degree of emphasis
+        :param kwargs: additional attributes
+
+        :returns: <Emphasis> element
+        """
+        return self.emphasis(words, level=level, **kwargs)
+
+    def lang(self, words, xml_lang=None, **kwargs):
         """
         Create a <Lang> element
 
@@ -654,7 +681,20 @@ def ssml_lang(self, words, xml_lang=None, **kwargs):
         """
         return self.nest(SsmlLang(words, xml_lang=xml_lang, **kwargs))
 
-    def ssml_p(self, words, **kwargs):
+    @deprecated_method(lang)
+    def ssml_lang(self, words, xml_lang=None, **kwargs):
+        """
+        Create a <Lang> element
+
+        :param words: Words to speak
+        :param xml:lang: Specify the language
+        :param kwargs: additional attributes
+
+        :returns: <Lang> element
+        """
+        return self.lang(words, xml_lang=xml_lang, **kwargs)
+
+    def p(self, words, **kwargs):
         """
         Create a <P> element
 
@@ -665,7 +705,19 @@ def ssml_p(self, words, **kwargs):
         """
         return self.nest(SsmlP(words, **kwargs))
 
-    def ssml_phoneme(self, words, alphabet=None, ph=None, **kwargs):
+    @deprecated_method(p)
+    def ssml_p(self, words, **kwargs):
+        """
+        Create a <P> element
+
+        :param words: Words to speak
+        :param kwargs: additional attributes
+
+        :returns: <P> element
+        """
+        return self.p(words, **kwargs)
+
+    def phoneme(self, words, alphabet=None, ph=None, **kwargs):
         """
         Create a <Phoneme> element
 
@@ -678,7 +730,21 @@ def ssml_phoneme(self, words, alphabet=None, ph=None, **kwargs):
         """
         return self.nest(SsmlPhoneme(words, alphabet=alphabet, ph=ph, **kwargs))
 
-    def ssml_prosody(self, words, volume=None, rate=None, pitch=None, **kwargs):
+    @deprecated_method(phoneme)
+    def ssml_phoneme(self, words, alphabet=None, ph=None, **kwargs):
+        """
+        Create a <Phoneme> element
+
+        :param words: Words to speak
+        :param alphabet: Specify the phonetic alphabet
+        :param ph: Specifiy the phonetic symbols for pronunciation
+        :param kwargs: additional attributes
+
+        :returns: <Phoneme> element
+        """
+        return self.phoneme(words, alphabet=alphabet, ph=ph, **kwargs)
+
+    def prosody(self, words, volume=None, rate=None, pitch=None, **kwargs):
         """
         Create a <Prosody> element
 
@@ -692,7 +758,22 @@ def ssml_prosody(self, words, volume=None, rate=None, pitch=None, **kwargs):
         """
         return self.nest(SsmlProsody(words, volume=volume, rate=rate, pitch=pitch, **kwargs))
 
-    def ssml_s(self, words, **kwargs):
+    @deprecated_method(prosody)
+    def ssml_prosody(self, words, volume=None, rate=None, pitch=None, **kwargs):
+        """
+        Create a <Prosody> element
+
+        :param words: Words to speak
+        :param volume: Specify the volume, available values: default, silent, x-soft, soft, medium, loud, x-loud, +ndB, -ndB
+        :param rate: Specify the rate, available values: x-slow, slow, medium, fast, x-fast, n%
+        :param pitch: Specify the pitch, available values: default, x-low, low, medium, high, x-high, +n%, -n%
+        :param kwargs: additional attributes
+
+        :returns: <Prosody> element
+        """
+        return self.prosody(words, volume=volume, rate=rate, pitch=pitch, **kwargs)
+
+    def s(self, words, **kwargs):
         """
         Create a <S> element
 
@@ -703,7 +784,19 @@ def ssml_s(self, words, **kwargs):
         """
         return self.nest(SsmlS(words, **kwargs))
 
-    def ssml_say_as(self, words, interpret_as=None, role=None, **kwargs):
+    @deprecated_method(s)
+    def ssml_s(self, words, **kwargs):
+        """
+        Create a <S> element
+
+        :param words: Words to speak
+        :param kwargs: additional attributes
+
+        :returns: <S> element
+        """
+        return self.s(words, **kwargs)
+
+    def say_as(self, words, interpret_as=None, role=None, **kwargs):
         """
         Create a <Say-As> element
 
@@ -716,7 +809,21 @@ def ssml_say_as(self, words, interpret_as=None, role=None, **kwargs):
         """
         return self.nest(SsmlSayAs(words, interpret_as=interpret_as, role=role, **kwargs))
 
-    def ssml_sub(self, words, alias=None, **kwargs):
+    @deprecated_method(say_as)
+    def ssml_say_as(self, words, interpret_as=None, role=None, **kwargs):
+        """
+        Create a <Say-As> element
+
+        :param words: Words to be interpreted
+        :param interpret-as: Specify the type of words are spoken
+        :param role: Specify the format of the date when interpret-as is set to date
+        :param kwargs: additional attributes
+
+        :returns: <Say-As> element
+        """
+        return self.say_as(words, interpret_as=interpret_as, role=role, **kwargs)
+
+    def sub(self, words, alias=None, **kwargs):
         """
         Create a <Sub> element
 
@@ -728,7 +835,20 @@ def ssml_sub(self, words, alias=None, **kwargs):
         """
         return self.nest(SsmlSub(words, alias=alias, **kwargs))
 
-    def ssml_w(self, words, role=None, **kwargs):
+    @deprecated_method(sub)
+    def ssml_sub(self, words, alias=None, **kwargs):
+        """
+        Create a <Sub> element
+
+        :param words: Words to be substituted
+        :param alias: Substitute a different word (or pronunciation) for selected text such as an acronym or abbreviation
+        :param kwargs: additional attributes
+
+        :returns: <Sub> element
+        """
+        return self.sub(words, alias=alias, **kwargs)
+
+    def w(self, words, role=None, **kwargs):
         """
         Create a <W> element
 
@@ -740,6 +860,19 @@ def ssml_w(self, words, role=None, **kwargs):
         """
         return self.nest(SsmlW(words, role=role, **kwargs))
 
+    @deprecated_method(w)
+    def ssml_w(self, words, role=None, **kwargs):
+        """
+        Create a <W> element
+
+        :param words: Words to speak
+        :param role: Customize the pronunciation of words by specifying the word’s part of speech or alternate meaning
+        :param kwargs: additional attributes
+
+        :returns: <W> element
+        """
+        return self.w(words, role=role, **kwargs)
+
 
 class SsmlW(TwiML):
     """ Improving Pronunciation by Specifying Parts of Speech in <Say> """