DX-2870 Refactor of BXML Module (#113)

* DX-2870 Create Base BXML Classes

Created base class for root (`<Bxml>` and `<Response>`)

Created base class for verbs

Wrote `<Tag>` verb to do some basic testing

* Add docstrings

* Refactor

`BxmlRoot` -> `Root`
`BxmlVerb` -> `Verb`

* Refactor tests for bxml base classes

* Add `test_tag.py` to test `<Tag>`

Also fixed some bugs in the base models causing test failures

* Clean up tests to follow proper pytest convention

Removed `lxml` from requirements
Added base class tests

* Add another test to add verbs during init of root

* DX-2901, DX-2908, DX-2918 (#114)

* DX-2901 `<PhoneNumber>` BXML

Had to fix some bugs with the attributes in the `Verb` class

Reordered arguments in the `Tag` class to match `Verb`

* DX-2908 Refactor `<SipUri> BXML

* DX-2918 Refactor `<Transfer>` BXML

* Cleanup and update descriptions in docstrings

* Fix WebRTC Utilities Test

* import List type for Python < 3.9

https://stackoverflow.com/a/63460173/11633328

* Fix other `List` instances

* Missed one `List`

* Add `Union` to support multiple types in List

* Construct verbs in alphabetical order to satisfy [email protected] tests

* Alphabetize attributes dict for python3.7

Author: ajrice6713

.gitignore

@@ -69,6 +69,9 @@ target/
 #Ipython Notebook
 .ipynb_checkpoints
 
+# IntelliJ
+.idea
+
 # VS Code
 .vscode
 

bandwidth/model/bxml/bxml.py

@@ -1,42 +1,21 @@
 """
 bxml.py
 
-Class that allows user to generate BXML programatically in python
-BXML is the parent element
+Class that allows user to generate a Bxml document
 
 @copyright Bandwidth INC
 """
+from typing import List
 
-BXML_TAG = "Bxml"
-XML_HEADER = '<?xml version="1.0" encoding="UTF-8"?>'
+from .root import Root
+from .verb import Verb
 
 
-class Bxml:
+class Bxml(Root):
+    def __init__(self, nested_verbs: List[Verb] = []):
+        """Initialize an instance of the <Bxml> root
 
-    def __init__(self):
+        Args:
+            nested_verbs (list[BxmlVerb], optional): Optional nested verbs to create the model with. Defaults to [].
         """
-        Creates the Bxml class 
-        """
-        self.verbs = []
-
-    def add_verb(self, verb):
-        """
-        Adds the Verb to the already existing verbs
-
-        :param Verb verb: The Verb to add
-        """
-        self.verbs.append(verb)
-
-    def to_bxml(self):
-        """
-        Converts the Bxml class to its XML representation
-
-        :rtype str: The XML representation of the Bxml class
-        """
-        xml_string = XML_HEADER
-        xml_string += '<' + BXML_TAG + '>'
-        for verb in self.verbs:
-            xml_string += verb.to_bxml()
-        xml_string += '</' + BXML_TAG + '>' 
-
-        return xml_string
+        super().__init__(tag="Bxml", nested_verbs=nested_verbs)

bandwidth/model/bxml/response.py

@@ -1,41 +1,21 @@
 """
 response.py
 
-Class that allows user to generate BXML programatically in python
+Class that allows user to generate a Response document
 
 @copyright Bandwidth INC
 """
+from typing import List
 
-RESPONSE_TAG = "Response"
-XML_HEADER = '<?xml version="1.0" encoding="UTF-8"?>'
+from .root import Root
+from .verb import Verb
 
 
-class Response:
+class Response(Root):
+    def __init__(self, nested_verbs: List[Verb] = []):
+        """Initialize an instance of the <Response> root
 
-    def __init__(self):
+        Args:
+            nested_verbs (list[BxmlVerb], optional): Optional nested verbs to create the model with. Defaults to [].
         """
-        Creates the Response class 
-        """
-        self.verbs = []
-
-    def add_verb(self, verb):
-        """
-        Adds the Verb to the already existing verbs
-
-        :param Verb verb: The Verb to add
-        """
-        self.verbs.append(verb)
-
-    def to_bxml(self):
-        """
-        Converts the Response class to its XML representation
-
-        :rtype str: The XML representation of the Response class
-        """
-        xml_string = XML_HEADER
-        xml_string += '<' + RESPONSE_TAG + '>'
-        for verb in self.verbs:
-            xml_string += verb.to_bxml()
-        xml_string += '</' + RESPONSE_TAG + '>' 
-
-        return xml_string
+        super().__init__(tag="Response", nested_verbs=nested_verbs)

bandwidth/model/bxml/root.py

@@ -0,0 +1,78 @@
+"""
+root.py
+
+Defines the base verb class for all BXML roots
+
+@copyright Bandwidth INC
+"""
+from typing import List
+import xml.etree.ElementTree as ET
+
+from bandwidth.model.bxml.verb import Verb
+
+
+class Root:
+    """Base class for BXML roots
+    """
+
+    def __init__(self, tag: str, nested_verbs: List[Verb] = None):
+        """Initialize instance of class
+
+        Args:
+            tag (str): The XML element name
+            nested_verbs (list[BxmlVerb], optional): List of nested BXML verbs. Defaults to None.
+        """
+        self._tag = tag
+        self._nested_verbs = nested_verbs
+        if not self._nested_verbs:
+            self._nested_verbs = []
+
+    def __len__(self) -> int:
+        """Override default len method. Returns length of _nested_verbs array
+
+        Returns:
+            int: Length of self._nested_verbs
+        """
+        return len(self._nested_verbs)
+    
+    def __getitem__(self, position: int) -> Verb:
+        """Override default getitem method. Makes the object iterable.
+
+        Args:
+            position (int): Desired self._nested_verbs list position
+
+        Returns:
+            BxmlVerb: Desired BXML verb 
+        """
+        return self._nested_verbs[position]
+    
+    def _generate_xml(self) -> ET.Element:
+        """Generates an XML dom
+
+        Returns:
+            ET.Element: The XML dom for the verb and its nested verbs
+        """
+        root = ET.Element(self._tag)
+        if self._nested_verbs:
+            for verb in self._nested_verbs:
+                root.append(verb._to_etree_element())
+        dom = ET.ElementTree(root)
+        return dom
+    
+    def add_verb(self, verb: Verb) -> None:
+        """Add a verb to the object's nested_verbs array
+
+        Args:
+            verb (BxmlVerb): BXML verb to nest within the parent. Becomes a child xml element.
+        """
+        self._nested_verbs.append(verb)
+    
+    def to_bxml(self) -> str:
+        """Return the serialized BXML string
+
+        Returns:
+            str: Serialized BXML string
+        """
+        xml_document = self._generate_xml()
+        return ET.tostring(xml_document._root, encoding='utf8', method='xml').decode("utf8")
+

bandwidth/model/bxml/verb.py

@@ -0,0 +1,108 @@
+"""
+verb.py
+
+Defines the base verb class for all BXML verbs
+
+@copyright Bandwidth INC
+"""
+from __future__ import annotations
+import xml.etree.ElementTree as ET
+
+
+class Verb:
+    """Base class for BXML verbs
+    """
+
+    def __init__(self, tag: str, content: str = None, attributes: dict = None, nested_verbs: list[BxmlVerb] = None):
+        """Initialize the verb model
+
+        Args:
+            tag (str): Name of the XML element
+            content (str, optional): XML element content. Defaults to None.
+            attributes (dict, optional): XML element attributes. Defaults to None.
+            nested_verbs (list[BxmlVerb], optional): XML element children. Defaults to None.
+        """
+        self._tag = tag
+        self._content = content
+        self._attributes = attributes
+        self._nested_verbs = nested_verbs
+        if not self._nested_verbs:
+            self._nested_verbs = []
+
+    def __len__(self) -> int:
+        """Override default len method. Returns length of _nested_verbs array
+
+        Returns:
+            int: Length of self._nested_verbs
+        """
+        return len(self._nested_verbs)
+    
+    def __getitem__(self, position) -> Verb:
+        """Override default getitem method. Makes the object iterable.
+
+        Args:
+            position (int): Desired self._nested_verbs list position
+
+        Returns:
+            BxmlVerb: Desired BXML verb 
+        """
+        return self._nested_verbs[position]
+    
+    def _set_attributes(self, root: ET.Element):
+        """Set XML attributes on an Element
+
+        Args:
+            root (ET.Element): XML Element to add attributes to
+        """
+        if self._attributes:
+            for key, value in self._attributes.items():
+                if value is not None:
+                    root.set(key, value)
+
+    def _to_etree_element(self) -> ET.Element:
+        """Generate an ET.Element object from a Verb Object
+
+        Returns:
+            ET.Element: ET.Element representation of Verb
+        """
+        root = ET.Element(self._tag)
+        if self._content:
+            root.text = self._content
+        self._set_attributes(root)
+        if self._nested_verbs:
+            for verb in self._nested_verbs:
+                root.append(verb._to_etree_element())
+        return root
+
+    def _generate_xml(self) -> ET.ElementTree:
+        """Generates an XML dom
+
+        Returns:
+            ET.Element: The XML dom for the verb and its nested verbs
+        """
+        root = ET.Element(self._tag)
+        if self._content:
+            root.text = self._content
+        self._set_attributes(root)
+        if self._nested_verbs:
+            for verb in self._nested_verbs:
+                root.append(verb._to_etree_element())
+        dom = ET.ElementTree(root)
+        return dom
+
+    def add_verb(self, verb) -> None:
+        """Add a verb to the object's nested_verbs array
+
+        Args:
+            verb (BxmlVerb): BXML verb to nest within the parent. Becomes a child xml element.
+        """
+        self._nested_verbs.append(verb)
+
+    def to_bxml(self) -> str:
+        """Return the serialized BXML string
+
+        Returns:
+            str: Serialized BXML string
+        """
+        xml_document = self._generate_xml()
+        return ET.tostring(xml_document._root).decode('utf8')

bandwidth/model/bxml/verbs/__init__.py

@@ -1,24 +1,4 @@
-from .hangup import Hangup
-from .send_dtmf import SendDtmf
-from .gather import Gather
-from .pause import Pause
 from .phone_number import PhoneNumber
-from .redirect import Redirect
-from .speak_sentence import SpeakSentence
-from .transfer import Transfer
-from .play_audio import PlayAudio
-from .forward import Forward
-from .record import Record
-from .pause_recording import PauseRecording
-from .resume_recording import ResumeRecording
-from .stop_recording import StopRecording
-from .start_recording import StartRecording
-from .conference import Conference
-from .bridge import Bridge
-from .ring import Ring
-from .stop_gather import StopGather
-from .start_gather import StartGather
-from .tag import Tag
 from .sip_uri import SipUri
-from .start_stream import StartStream
-from .stop_stream import StopStream
+from .tag import Tag
+from .transfer import Transfer