8000 Rename child twiml methods to be the tag name and deprecate old metho… · twilio/twilio-python@af20c9e · GitHub
[go: up one dir, main page]
Skip to content

Commit af20c9e

Browse files
eshanholtzeshanholtz
authored
Rename child twiml methods to be the tag name and deprecate old methods (#495)
* add custom decorator to send method deprecation warning * rename child twiml methods to be the tag name, with backwards compatibility
1 parent 65f6c9f commit af20c9e

File tree

4 files changed

+208
-10
lines changed

4 files changed

+208
-10
lines changed

‎tests/unit/base/test_deprecation.py

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import unittest
2+
import warnings
3+
4+
from twilio.base.obsolete import deprecated_method
5+
6+
7+
class DeprecatedMethodTest(unittest.TestCase):
8+
9+
def test_deprecation_decorator(self):
10+
11+
@deprecated_method
12+
def old_method():
13+
return True
14+
15+
with warnings.catch_warnings(record=True) as caught_warnings:
16+
warnings.simplefilter("always")
17+
# Call function that should raise a warning, but still execute
18+
self.assertTrue(old_method())
19+
self.assertTrue(len(caught_warnings))
20+
self.assertEqual(
21+
str(caught_warnings[0].message),
22+
'Function method .old_method() is deprecated'
23+
)
24+
assert issubclass(caught_warnings[0].category, DeprecationWarning)
25+
26+
def test_deprecation_decorator_with_new_method(self):
27+
28+
@deprecated_method('new_method')
29+
def old_method():
30+
return True
31+
32+
with warnings.catch_warnings(record=True) as caught_warnings:
33+
warnings.simplefilter("always")
34+
35+
# Call function that should raise a warning, but still execute
36+
self.assertTrue(old_method())
37+
self.assertTrue(len(caught_warnings))
38+
self.assertEqual(
39+
str(caught_warnings[0].message),
40+
'Function method .old_method() is deprecated in favor of .new_method()'
41+
)
42+
assert issubclass(caught_warnings[0].category, DeprecationWarning)

‎twilio/base/obsolete.py

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,25 @@ def new_func(*args, **kwargs):
2121
)
2222

2323
return new_func
24+
25+
26+
def deprecated_method(new_func=None):
27+
"""
28+
This is a decorator which can be used to mark deprecated methods.
29+
It will report in a DeprecationWarning being emitted to stderr when the deprecated method is used.
30+
"""
31+
32+
def deprecated_method_wrapper(func):
33+
34+
@functools.wraps(func)
35+
def wrapper(*args, **kwargs):
36+
msg = 'Function method .{}() is deprecated'.format(func.__name__)
37+
msg += ' in favor of .{}()'.format(new_func) if isinstance(new_func, str) else ''
38+
warnings.warn(msg, DeprecationWarning)
39+
return func(*args, **kwargs)
40+
return wrapper
41+
42+
if callable(new_func):
43+
return deprecated_method_wrapper(new_func)
44+
45+
return deprecated_method_wrapper

‎twilio/twiml/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ class TwiML(object):
3636
'xml_lang': 'xml:lang',
3737
'interpret_as': 'interpret-as',
3838
'for_': 'for',
39+
'break_': 'break'
3940
}
4041

4142
def __init__(self, **kwargs):

‎twilio/twiml/voice_response.py

Lines changed: 143 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
"""
88

99
import json
10+
from twilio.base.obsolete import deprecated_method
1011
from twilio.twiml import (
1112
TwiML,
1213
format_language,
@@ -618,7 +619,7 @@ def __init__(self, message=None, **kwargs):
618619
if message:
619620
self.value = message
620621

621-
def ssml_break(self, strength=None, time=None, **kwargs):
622+
def break_(self, strength=None, time=None, **kwargs):
622623
"""
623624
Create a <Break> element
624625
@@ -630,7 +631,20 @@ def ssml_break(self, strength=None, time=None, **kwargs):
630631
"""
631632
return self.nest(SsmlBreak(strength=strength, time=time, **kwargs))
632633

633-
def ssml_emphasis(self, words, level=None, **kwargs):
634+
@deprecated_method('break_')
635+
def ssml_break(self, strength=None, time=None, **kwargs):
636+
"""
637+
Create a <Break> element
638+
639+
:param strength: Set a pause based on strength
640+
:param time: Set a pause to a specific length of time in seconds or milliseconds, available values: [number]s, [number]ms
641+
:param kwargs: additional attributes
642+
643+
:returns: <Break> element
644+
"""
645+
return self.break_(strength=strength, time=time, **kwargs)
646+
647+
def emphasis(self, words, level=None, **kwargs):
634648
"""
635649
Create a <Emphasis> element
636650
@@ -642,7 +656,20 @@ def ssml_emphasis(self, words, level=None, **kwargs):
642656
"""
643657
return self.nest(SsmlEmphasis(words, level=level, **kwargs))
644658

645-
def ssml_lang(self, words, xml_lang=None, **kwargs):
659+
@deprecated_method('emphasis')
660+
def ssml_emphasis(self, words, level=None, **kwargs):
661+
"""
662+
Create a <Emphasis> element
663+
664+
:param words: Words to emphasize
665+
:param level: Specify the degree of emphasis
666+
:param kwargs: additional attributes
667+
668+
:returns: <Emphasis> element
669+
"""
670+
return self.emphasis(words, level=level, **kwargs)
671+
672+
def lang(self, words, xml_lang=None, **kwargs):
646673
"""
647674
Create a <Lang> element
648675
@@ -654,7 +681,20 @@ def ssml_lang(self, words, xml_lang=None, **kwargs):
654681
"""
655682
return self.nest(SsmlLang(words, xml_lang=xml_lang, **kwargs))
656683

657-
def ssml_p(self, words, **kwargs):
684+
@deprecated_method('lang')
685+
def ssml_lang(self, words, xml_lang=None, **kwargs):
686+
"""
687+
Create a <Lang> element
688+
689+
:param words: Words to speak
690+
:param xml:lang: Specify the language
691+
:param kwargs: additional attributes
692+
693+
:returns: <Lang> element
694+
"""
695+
return self.lang(words, xml_lang=xml_lang, **kwargs)
696+
697+
def p(self, words, **kwargs):
658698
"""
659699
Create a <P> element
660700
@@ -665,7 +705,19 @@ def ssml_p(self, words, **kwargs):
665705
"""
666706
return self.nest(SsmlP(words, **kwargs))
667707

668-
def ssml_phoneme(self, words, alphabet=None, ph=None, **kwargs):
708+
@deprecated_method('p')
709+
def ssml_p(self, words, **kwargs):
710+
"""
711+
Create a <P> element
712+
713+
:param words: Words to speak
714+
:param kwargs: additional attributes
715+
716+
:returns: <P> element
717+
"""
718+
return self.p(words, **kwargs)
719+
720+
def phoneme(self, words, alphabet=None, ph=None, **kwargs):
669721
"""
670722
Create a <Phoneme> element
671723
@@ -678,7 +730,21 @@ def ssml_phoneme(self, words, alphabet=None, ph=None, **kwargs):
678730
"""
679731
return self.nest(SsmlPhoneme(words, alphabet=alphabet, ph=ph, **kwargs))
680732

681-
def ssml_prosody(self, words, volume=None, rate=None, pitch=None, **kwargs):
733+
@deprecated_method('phoneme')
734+
def ssml_phoneme(self, words, alphabet=None, ph=None, **kwargs):
735+
"""
736+
Create a <Phoneme> element
737+
738+
:param words: Words to speak
739+
:param alphabet: Specify the phonetic alphabet
740+
:param ph: Specifiy the phonetic symbols for pronunciation
741+
:param kwargs: additional attributes
742+
743+
:returns: <Phoneme> element
744+
"""
745+
return self.phoneme(words, alphabet=alphabet, ph=ph, **kwargs)
746+
747+
def prosody(self, words, volume=None, rate=None, pitch=None, **kwargs):
682748
"""
683749
Create a <Prosody> element
684750
@@ -692,7 +758,22 @@ def ssml_prosody(self, words, volume=None, rate=None, pitch=None, **kwargs):
692758
"""
693759
return self.nest(SsmlProsody(words, volume=volume, rate=rate, pitch=pitch, **kwargs))
694760

695-
def ssml_s(self, words, **kwargs):
761+
@deprecated_method('prosody')
762+
def ssml_prosody(self, words, volume=None, rate=None, pitch=None, **kwargs):
763+
"""
764+
Create a <Prosody> element
765+
766+
:param words: Words to speak
767+
:param volume: Specify the volume, available values: default, silent, x-soft, soft, medium, loud, x-loud, +ndB, -ndB
768+
:param rate: Specify the rate, available values: x-slow, slow, medium, fast, x-fast, n%
769+
:param pitch: Specify the pitch, available values: default, x-low, low, medium, high, x-high, +n%, -n%
770+
:param kwargs: additional attributes
771+
772+
:returns: <Prosody> element
773+
"""
774+
return self.prosody(words, volume=volume, rate=rate, pitch=pitch, **kwargs)
775+
776+
def s(self, words, **kwargs):
696777
"""
697778
Create a <S> element
698779
703784
"""
704785
return self.nest(SsmlS(words, **kwargs))
705786

706-
def ssml_say_as(self, words, interpret_as=None, role=None, **kwargs):
787+
@deprecated_method('s')
788+
def ssml_s(self, words, **kwargs):
789+
"""
790+
Create a <S> element
791+
792+
:param words: Words to speak
793+
:param kwargs: additional attributes
794+
795+
:returns: <S> element
796+
"""
797+
return self.s(words, **kwargs)
798+
799+
def say_as(self, words, interpret_as=None, role=None, **kwargs):
707800
"""
708801
Create a <Say-As> element
709802
@@ -716,7 +809,21 @@ def ssml_say_as(self, words, interpret_as=None, role=None, **kwargs):
716809
"""
717810
return self.nest(SsmlSayAs(words, interpret_as=interpret_as, role=role, **kwargs))
718811

719-
def ssml_sub(self, words, alias=None, **kwargs):
812+
@deprecated_method('say_as')
813+
def ssml_say_as(self, words, interpret_as=None, role=None, **kwargs):
814+
"""
815+
Create a <Say-As> element
816+
817+
:param words: Words to be interpreted
818+
:param interpret-as: Specify the type of words are spoken
819+
:param role: Specify the format of the date when interpret-as is set to date
820+
:param kwargs: additional attributes
821+
822+
:returns: <Say-As> element
823+
"""
824+
return self.say_as(words, interpret_as=interpret_as, role=role, **kwargs)
825+
826+
def sub(self, words, alias=None, **kwargs):
720827
"""
721828
Create a <Sub> element
722829< 10000 /td>
@@ -728,7 +835,20 @@ def ssml_sub(self, words, alias=None, **kwargs):
728835
"""
729836
return self.nest(SsmlSub(words, alias=alias, **kwargs))
730837

731-
def ssml_w(self, words, role=None, **kwargs):
838+
@deprecated_method('sub')
839+
def ssml_sub(self, words, alias=None, **kwargs):
840+
"""
841+
Create a <Sub> element
842+
843+
:param words: Words to be substituted
844+
:param alias: Substitute a different word (or pronunciation) for selected text such as an acronym or abbreviation
845+
:param kwargs: additional attributes
846+
847+
:returns: <Sub> element
848+
"""
849+
return self.sub(words, alias=alias, **kwargs)
850+
851+
def w(self, words, role=None, **kwargs):
732852
"""
733853
Create a <W> element
734854
@@ -740,6 +860,19 @@ def ssml_w(self, words, role=None, **kwargs):
740860
"""
741861
return self.nest(SsmlW(words, role=role, **kwargs))
742862

863+
@deprecated_method('w')
864+
def ssml_w(self, words, role=None, **kwargs):
865+
"""
866+
Create a <W> element
867+
868+
:param words: Words to speak
869+
:param role: Customize the pronunciation of words by specifying the word’s part of speech or alternate meaning
870+
:param kwargs: additional attributes
871+
872+
:returns: <W> element
873+
"""
874+
return self.w(words, role=role, **kwargs)
875+
743876

744877
class SsmlW(TwiML):
745878
""" Improving Pronunciation by Specifying Parts of Speech in <Say> """

0 commit comments

Comments
 (0)
0