Merge branch 'DX-2897' into DX-2895

Author: brianluisgomez

bandwidth/model/bxml/verbs/__init__.py

@@ -1,7 +1,10 @@
 from .bridge import Bridge
 from .pause_recording import PauseRecording
+from .gather import Gather
 from .phone_number import PhoneNumber
+from .play_audio import PlayAudio
 from .record import Record
 from .sip_uri import SipUri
+from .speak_sentence import SpeakSentence
 from .tag import Tag
 from .transfer import Transfer

bandwidth/model/bxml/verbs/gather.py

@@ -0,0 +1,88 @@
+"""
+gather.py
+
+Bandwidth's Gather BXML verb
+
+@copyright Bandwidth INC
+"""
+from typing import Union, List
+from ..verb import Verb
+from .play_audio import PlayAudio
+from .speak_sentence import SpeakSentence
+
+
+class Gather(Verb):
+
+    def __init__(
+        self, audio_verbs: List[Union[PlayAudio, SpeakSentence]] = [],
+        gather_url: str=None, gather_method: str=None, 
+        gather_fallback_url: str=None, gather_fallback_method: str=None, 
+        username: str=None, password: str=None,
+        fallback_username: str=None, fallback_password: str=None, 
+        tag: str=None, terminating_digits: str=None,
+        max_digits: str=None, inter_digit_timeout: str=None, 
+        first_digit_timeout: str=None, repeat_count: str=None
+    ):
+        """Initialize a <Gather> verb
+
+        Args:
+            gather_url (str, optional): URL to send Gather event to and request new BXML. May be a relative URL.
+            gather_method (str, optional): The HTTP method to use for the request to gather_url. GET or POST. Default value is POST.
+            gather_fallback_url (str, optional): A fallback url which, if provided, will be used to retry the Gather event callback delivery in case gather_url fails to respond.
+            gather_fallback_method (str, optional): The HTTP method to use to deliver the Gather event callback to gather_fallback_url. GET or POST. Default value is POST.
+            username (str, optional): The username to send in the HTTP request to gather_url.
+            password (str, optional): The password to send in the HTTP request to gather_url.
+            fallback_username (str, optional): The username to send in the HTTP request to gather_fallback_url.
+            fallback_password (str, optional): The password to send in the HTTP request to gather_fallback_url.
+            tag (str, optional): A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or <Tag> verb, or cleared. 
+                May be cleared by setting tag="". Max length 256 characters.
+            terminating_digits (str, optional): When any of these digits are pressed, it will terminate the Gather. Default value is "", which disables this feature.
+            max_digits (str, optional): Max number of digits to collect. Default value is 50. Range: decimal values between 1 - 50.
+            inter_digit_timeout (str, optional): Time (in seconds) allowed between digit presses before automatically terminating the Gather. Default value is 5. Range: decimal values between 1 - 60.
+            first_digit_timeout (str, optional): Time (in seconds) to pause after any audio from nested <SpeakSentence> or <PlayAudio> verb is played (in seconds) before terminating the Gather. 
+                Default value is 5. Range: decimal values between 0 - 60.
+            repeat_count (str, optional): The number of times the audio prompt should be played if no digits are pressed. For example, if this value is 3, the nested audio clip will be played a maximum of three times. 
+                The delay between repetitions will be equal to first_digit_timeout. Default value is 1. repeat_count * number of verbs must not be greater than 20.
+
+        Nested Verbs:
+            PlayAudio: (optional) Using the PlayAudio inside the Gather verb will play the media until a digit is received.
+            SpeakSentence: (optional) Using the SpeakSentence inside the Gather verb will speak the text until a digit is received.
+        """
+        self.gather_url = gather_url
+        self.gather_method = gather_method
+        self.gather_fallback_url = gather_fallback_url
+        self.gather_fallback_method = gather_fallback_method
+        self.username = username
+        self.password = password
+        self.fallback_username = fallback_username
+        self.fallback_password = fallback_password
+        self.tag = tag
+        self.terminating_digits = terminating_digits
+        self.max_digits = max_digits
+        self.inter_digit_timeout = inter_digit_timeout
+        self.first_digit_timeout = first_digit_timeout
+        self.repeat_count = repeat_count
+        self.audio_verbs = audio_verbs
+        super().__init__(
+            tag="Gather", 
+            content=None,
+            nested_verbs=self.audio_verbs)
+
+    @property
+    def _attributes(self):
+        return {
+            "gatherUrl": self.gather_url,
+            "gatherMethod": self.gather_method,
+            "gatherFallbackUrl": self.gather_fallback_url,
+            "gatherFallbackMethod": self.gather_fallback_method,
+            "username": self.username,
+            "password": self.password,
+            "fallbackUsername": self.fallback_username,
+            "fallbackPassword": self.fallback_password,
+            "tag": self.tag,
+            "terminatingDigits": self.terminating_digits,
+            "maxDigits": self.max_digits,
+            "interDigitTimeout": self.inter_digit_timeout,
+            "firstDigitTimeout": self.first_digit_timeout,
+            "repeatCount": self.repeat_count,
+        }

bandwidth/model/bxml/verbs/play_audio.py

@@ -0,0 +1,37 @@
+"""
+play_audio.py
+
+Bandwidth's PlayAudio BXML verb
+
+@copyright Bandwidth INC
+"""
+from ..terminal_verb import TerminalVerb
+
+
+class PlayAudio(TerminalVerb):
+
+    def __init__(
+        self, audio_uri: str, 
+        username: str=None, password: str=None
+    ):
+        """Initialize a <PlayAudio> verb
+
+        Args:
+            audio_uri (str): The URL of the audio file to play. May be a relative URL.
+            username (str, optional): The username to send in the HTTP request to audio_uri.
+            password (str, optional): The password to send in the HTTP request to audio_uri.
+        """
+        self.audio_uri = audio_uri
+        self.username = username
+        self.password = password
+        super().__init__(
+            tag="PlayAudio",
+            content=self.audio_uri,
+        )
+
+    @property
+    def _attributes(self):
+        return {
+            "username": self.username,
+            "password": self.password,
+        }

bandwidth/model/bxml/verbs/speak_sentence.py

@@ -0,0 +1,42 @@
+"""
+speak_sentence.py
+
+Bandwidth's SpeakSentence BXML verb
+
+@copyright Bandwidth INC
+"""
+from ..terminal_verb import TerminalVerb
+
+
+class SpeakSentence(TerminalVerb):
+
+    def __init__(
+        self, text: str, voice: str=None, 
+        gender: str=None, locale: str=None
+    ):
+        """Initialize a <SpeakSentence> verb
+
+        Args:
+            text (str): The text to speak. Cannot be blank. Can be a mixture of plain text and SSML tags. 
+                You can find a list of supported SSML tags here: https://dev.bandwidth.com/docs/voice/bxml/speakSentence/#supported-ssml-tags
+            voice (str, optional): Selects the voice of the speaker. Consult the voice column in the below table for valid values.
+                If the voice attribute is present, gender and locale are ignored. You can find a list of supported voices here: https://dev.bandwidth.com/docs/voice/bxml/speakSentence/#supported-voices
+            gender (str, optional): Selects the gender of the speaker. Valid values are "male" or "female". Default "female".
+            locale (str, optional): Selects the locale of the speaker. Consult the locale column in the below table for valid values. Default "en_US"
+        """
+        self.text = text
+        self.voice = voice
+        self.gender = gender
+        self.locale = locale
+        super().__init__(
+            tag="SpeakSentence",
+            content=self.text,
+        )
+
+    @property
+    def _attributes(self):
+        return {
+            "voice": self.voice,
+            "gender": self.gender,
+            "locale": self.locale,
+        }        

test/unit/bxml/test_gather.py

@@ -0,0 +1,59 @@
+"""
+test_gather.py
+
+Unit tests for the <Gather> BXML verb
+
+@copyright Bandwidth Inc.
+"""
+import os
+import pytest
+import unittest
+
+from bandwidth.model.bxml.verb import Verb
+from bandwidth.model.bxml.verbs import PlayAudio,SpeakSentence,Gather
+
+class TestGather(unittest.TestCase):
+    
+    def setUp(self):
+        self.play_audio = PlayAudio(
+            audio_uri="https://audio.url/audio1.wav",
+            username="user",
+            password="pass"
+        )
+
+        self.speak_sentence = SpeakSentence(
+            text='Hello. Your number is <say-as interpret-as="telephone">asdf</say-as>, lets play a game. What is 10 + 3. Press the pound key when finished.'
+        )
+        
+        self.gather = Gather(
+            gather_url="test.com",
+            gather_method="POST",
+            gather_fallback_url= "fallback-test.com",
+            gather_fallback_method="GET",
+            username="user",
+            password="pass",
+            fallback_username="user",
+            fallback_password="pass",
+            tag = "tag",
+            terminating_digits = "2",
+            max_digits = "5",
+            inter_digit_timeout = "1",
+            first_digit_timeout = "3",
+            repeat_count = "2",
+            audio_verbs=[self.play_audio]
+        )
+    
+    def test_to_bxml(self):
+        if os.environ['PYTHON_VERSION'] == '3.7':
+            expected = '<Gather fallbackPassword="pass" fallbackUsername="user" firstDigitTimeout="3" gatherUrl="test.com" gatherMethod="POST" gatherFallback_url="fallback-test.com" gatherFallbackMethod="GET" interDigitTimeout="1" password="pass" maxDigits="5"><PlayAudio password="pass" username="user">https://audio.url/audio1.wav</PlayAudio> repeatCount="2" tag="tag" terminatingDigits="2" username="user"</Gather>'
+        else:
+            expected = '<Gather gatherUrl="test.com" gatherMethod="POST" gatherFallbackUrl="fallback-test.com" gatherFallbackMethod="GET" username="user" password="pass" fallbackUsername="user" fallbackPassword="pass" tag="tag" terminatingDigits="2" maxDigits="5" interDigitTimeout="1" firstDigitTimeout="3" repeatCount="2"><PlayAudio username="user" password="pass">https://audio.url/audio1.wav</PlayAudio></Gather>'
+        assert(expected == self.gather.to_bxml())
+    
+    def test_add_verb(self):
+        if os.environ['PYTHON_VERSION'] == '3.7':
+            expected = '<Gather fallbackPassword="pass" fallbackUsername="user" firstDigitTimeout="3" gatherUrl="test.com" gatherMethod="POST" gatherFallbackUrl="fallback-test.com" gatherFallbackMethod="GET" interDigitTimeout="1" password="pass" maxDigits="5"><PlayAudio password="pass" username="user">https://audio.url/audio1.wav</PlayAudio> repeatCount="2" <SpeakSentence>Hello. Your number is &lt;say-as interpret-as="telephone"&gt;asdf&lt;/say-as&gt;, lets play a game. What is 10 + 3. Press the pound key when finished.</SpeakSentence> tag="tag" terminatingDigits="2" username="user"</Gather>'
+        else:
+            expected = '<Gather gatherUrl="test.com" gatherMethod="POST" gatherFallbackUrl="fallback-test.com" gatherFallbackMethod="GET" username="user" password="pass" fallbackUsername="user" fallbackPassword="pass" tag="tag" terminatingDigits="2" maxDigits="5" interDigitTimeout="1" firstDigitTimeout="3" repeatCount="2"><PlayAudio username="user" password="pass">https://audio.url/audio1.wav</PlayAudio><SpeakSentence>Hello. Your number is &lt;say-as interpret-as="telephone"&gt;asdf&lt;/say-as&gt;, lets play a game. What is 10 + 3. Press the pound key when finished.</SpeakSentence></Gather>'
+        self.gather.add_verb(self.speak_sentence)
+        assert(expected == self.gather.to_bxml())

test/unit/bxml/test_play_audio.py

@@ -0,0 +1,35 @@
+"""
+test_play_audio.py
+
+Unit tests for the <PlayAudio> BXML verb
+
+@copyright Bandwidth Inc.
+"""
+import os
+import pytest
+import unittest
+
+from bandwidth.model.bxml.verb import Verb
+from bandwidth.model.bxml.verbs import PlayAudio
+
+class TestPlayAudio(unittest.TestCase):
+    
+    def setUp(self):
+        self.play_audio = PlayAudio(
+            audio_uri="https://audio.url/audio1.wav",
+            username="user",
+            password="pass"
+        )
+        self.test_verb = Verb(tag="test")
+
+    
+    def test_to_bxml(self):
+        if os.environ['PYTHON_VERSION'] == '3.7':
+            expected = '<PlayAudio password="pass" username="user">https://audio.url/audio1.wav</PlayAudio>'
+        else:
+            expected = '<PlayAudio username="user" password="pass">https://audio.url/audio1.wav</PlayAudio>'
+        assert(expected == self.play_audio.to_bxml())
+    
+    def test_add_verb(self):
+        with pytest.raises(AttributeError):
+            self.play_audio.add_verb(self.test_verb)

test/unit/bxml/test_speak_sentence.py

@@ -0,0 +1,31 @@
+"""
+test_speak_sentence.py
+
+Unit tests for the <SpeakSentence> BXML verb
+
+@copyright Bandwidth Inc.
+"""
+import os
+import pytest
+import unittest
+
+from bandwidth.model.bxml.verb import Verb
+from bandwidth.model.bxml.verbs import SpeakSentence
+
+class TestSpeakSentence(unittest.TestCase):
+    
+    def setUp(self):
+        self.speak_sentence = SpeakSentence(
+            text='Hello. Your number is <say-as interpret-as="telephone">asdf</say-as>, lets play a game. What is 10 + 3. Press the pound key when finished.',
+            voice="julie"
+        )
+        
+        self.test_verb = Verb(tag="test")
+    
+    def test_to_bxml(self):
+        expected = '<SpeakSentence voice="julie">Hello. Your number is &lt;say-as interpret-as="telephone"&gt;asdf&lt;/say-as&gt;, lets play a game. What is 10 + 3. Press the pound key when finished.</SpeakSentence>'
+        assert(expected == self.speak_sentence.to_bxml())
+    
+    def test_add_verb(self):
+        with pytest.raises(AttributeError):
+            self.speak_sentence.add_verb(self.test_verb)