mms-client 1.6.0__py3-none-any.whl → 1.8.0__py3-none-any.whl

mms_client/utils/multipart_transport.py

@@ -0,0 +1,259 @@
+"""Contains a transport override supporting MTOMS attachments."""
+
+import string
+from base64 import b64encode
+from email.encoders import encode_7or8bit
+from email.mime.application import MIMEApplication
+from email.mime.base import MIMEBase
+from email.mime.multipart import MIMEMultipart
+from logging import getLogger
+from random import SystemRandom
+from typing import Dict
+from typing import Optional
+
+from lxml import etree
+from lxml.etree import _Element as Element
+from pendulum import now
+from requests import Session
+from zeep.cache import VersionedCacheBase
+from zeep.transports import Transport
+from zeep.wsdl.utils import etree_to_string
+
+# Set the default logger for the MMS client
+logger = getLogger(__name__)
+
+
+# Define the namespaces used in the XML
+XOP = "http://www.w3.org/2004/08/xop/include"
+XMIME5 = "http://www.w3.org/2005/05/xmlmime"
+FILETAG = "xop:Include:"
+ID_LEN = 16
+
+
+# Define a function to generate a randomized ID string
+def get_id(length: int = ID_LEN) -> str:
+    """Generate a randomized ID string.
+
+    Arguments:
+    length (int):   The length of the ID string to generate.
+
+    Returns:    The randomized ID string.
+    """
+    return "".join(SystemRandom().choice(string.ascii_uppercase + string.digits) for _ in range(length))
+
+
+def now_b64():
+    """Return a base64 encoded string of the current timestamp."""
+    return b64encode(f"{now().timestamp()}".replace(".", "").encode("UTF-8")).decode("UTF-8")
+
+
+def get_boundary() -> str:
+    """Return a randomized MIME boundary string."""
+    return f"MIMEBoundary_{now_b64()}".center(33, "=")
+
+
+def get_content_id(domain: str) -> str:
+    """Return a randomized MIME content ID string.
+
+    Arguments:
+    domain (str):   The domain of the content ID.
+
+    Returns:    The randomized MIME content ID string.
+    """
+    return f"<{now_b64()}@{domain}>"
+
+
+def overwrite_attachnode(node):
+    """Overwrite the attachment node.
+
+    Arguments:
+    node (Element):    The XML node to be overwritten.
+
+    Returns:    The attachment node.
+    """
+    cid = node.text[len(FILETAG) :]
+    node.text = None
+    etree.SubElement(node, f"{{{XOP}}}Include", nsmap={"xop": XOP}, href=f"cid:{cid}")
+    return cid
+
+
+def get_multipart(content_id: str) -> MIMEMultipart:
+    """Create a MIME multipart object.
+
+    Arguments:
+    content_id (str):   The content ID to be used for the attachment.
+
+    Returns:    The MIME multipart object.
+    """
+    part = MIMEMultipart(
+        "related", charset="UTF-8", type="application/xop+xml", boundary=get_boundary(), start=content_id
+    )
+    part.set_param("start-info", "application/soap+xml")
+    return part
+
+
+def get_envelope_part(envelope: Element, content_id: str) -> MIMEApplication:
+    """Create the MIME envelope part.
+
+    Arguments:
+    envelope (Element):    The XML envelope to be attached.
+    content_id (str):      The content ID to be used for the attachment.
+
+    Returns:    The MIME envelope part.
+    """
+    part = MIMEApplication(etree_to_string(envelope), "xop+xml", encode_7or8bit)
+    part.set_param("charset", "utf-8")
+    part.set_param("type", "text/xml")
+    part.add_header("Content-ID", content_id)
+    part.add_header("Content-Transfer-Encoding", "binary")
+    return part
+
+
+class Attachment:
+    """Represents an attachment to be sent with a multipart request."""
+
+    def __init__(self, name: str, data: bytes, domain: str):
+        """Create a new attachment.
+
+        Arguments:
+        name (str):   The name of the attachment.
+        data (bytes): The data to be attached.
+        domain (str): The domain of the content ID.
+        """
+        self.name = name
+        self.data = data
+        self.cid = f"{get_id()}-{name}@{domain}"
+        self.tag = FILETAG + self.cid
+
+
+class MultipartTransport(Transport):
+    """A transport that supports MTOMS attachments."""
+
+    def __init__(
+        self,
+        domain: str,
+        cache: Optional[VersionedCacheBase] = None,
+        timeout: int = 300,
+        operation_timeout: Optional[int] = None,
+        session: Optional[Session] = None,
+    ):
+        """Create a new MTOMS transport.
+
+        Arguments:
+        domain (str):                           The domain of the content ID to use.
+        cache (VersionedCacheBase, optional):   The cache to be used for the transport.
+        timeout (int):                          The timeout for the transport.
+        operation_timeout (int, optional):      The operation timeout for the transport.
+        session (Session, optional):            The session to be used for the transport.
+        """
+        # Save the domain for later use
+        self._domain = domain
+
+        # Setup a dictionary to store the attachments after they're registered
+        self._attachments: Dict[str, Attachment] = {}
+
+        # Call the parent constructor
+        super().__init__(
+            cache=cache,
+            timeout=timeout,
+            operation_timeout=operation_timeout,
+            session=session,
+        )
+
+    def register_attachment(self, name: str, data: bytes) -> str:
+        """Register an attachment.
+
+        Registered attachments will be sent with the request as MTOMS attachments. The content ID of the attachment
+        will be returned so that it can be used in the request.
+
+        Arguments:
+        name (str):     The name of the attachment.
+        data (bytes):   The data to be attached.
+
+        Returns:    The content ID of the attachment, which should be used in place of the attachment data.
+        """
+        attachment = Attachment(name, data, self._domain)
+        self._attachments[attachment.cid] = attachment
+        return attachment.tag
+
+    def post_xml(self, address: str, envelope: Element, headers: dict):
+        """Post the XML envelope and attachments.
+
+        Arguments:
+        address (str):      The address to post the data to.
+        envelope (Element): The XML envelope to be attached.
+        headers (dict):     The headers to be used for the request.
+
+        Returns:    The response from the server.
+        """
+        # Search for values that start with our FILETAG
+        filetags = envelope.xpath(f"//*[starts-with(text(), '{FILETAG}')]")
+
+        # if there are any attached files, we will set the attachments. Otherwise, just the envelope
+        if filetags:
+            message = self.create_mtom_request(filetags, envelope, headers).encode("UTF-8")
+        else:
+            message = etree_to_string(envelope)
+
+        # Post the request and return the response
+        return self.post(address, message, headers)
+
+    def create_mtom_request(self, filetags, envelope: Element, headers: dict) -> str:
+        """Set MTOM attachments and return the right envelope.
+
+        Arguments:
+        filetags (list):    The list of XML paths to the attachments.
+        envelope (Element): The XML envelope to be attached.
+        headers (dict):     The headers to be used for the request.
+
+        Returns:    The XML envelope with the attachments.
+        """
+        # First, get an identifier for the request and then use it to create a new multipart request
+        content_id = get_content_id(self._domain)
+        mtom_part = get_multipart(content_id)
+
+        # Next, let's set the XOP:Include nodes for each attachment
+        files = [overwrite_attachnode(f) for f in filetags]
+
+        # Now, create the request envelope and attach it to the multipart request
+        env_part = get_envelope_part(envelope, content_id)
+        mtom_part.attach(env_part)
+
+        # Attach each file to the multipart request
+        for cid in files:
+            mtom_part.attach(self.create_attachment(cid))
+
+        # Finally, create the final multipart request string
+        bound = f"--{mtom_part.get_boundary()}"
+        marray = mtom_part.as_string().split(bound)
+        mtombody = bound + bound.join(marray[1:])
+
+        # Set the content length and add the MTOM headers to the request
+        mtom_part.add_header("Content-Length", str(len(mtombody)))
+        headers.update(dict(mtom_part.items()))
+
+        # Decode the XML and return the request
+        message = mtom_part.as_string().split("\n\n", 1)[1]
+        message = message.replace("\n", "\r\n", 5)
+        return message
+
+    def create_attachment(self, cid):
+        """Create an attachment for the multipart request.
+
+        Arguments:
+        cid (str):   The content ID of the attachment.
+
+        Returns:    The attachment.
+        """
+        # First, get the attachment from the cache
+        attach = self._attachments[cid]
+
+        # Next, create the attachment
+        part = MIMEBase("application", "octet-stream")
+        part["Content-Transfer-Encoding"] = "binary"
+        part["Content-ID"] = f"<{attach.cid}>"
+        part.set_payload(attach.data, charset="utf-8")
+        del part["mime-version"]
+
+        # Finally, return the attachment
+        return part

mms_client/utils/serialization.py

@@ -56,89 +56,128 @@ class Serializer:
         with open(XSD_DIR / self._xsd.value, "rb") as f:
             self._schema = XMLSchema(parse(f))
 
-    def serialize(self, request_envelope: E, request_data: P) -> bytes:
+    def serialize(self, request_envelope: E, request_data: P, for_report: bool = False) -> bytes:
         """Serialize the envelope and data to a byte string for sending to the MMS server.
 
         Arguments:
         request_envelope (Envelope):    The envelope to be serialized.
         request_data (Payload):         The data to be serialized.
+        for_report (bool):              If True, the data will be serialized for a report request.
 
         Returns:    A byte string containing the XML-formatted data to be sent to the MMS server.
         """
-        # First, create our payload class from the payload and data types
-        payload_cls = _create_request_payload_type(
+        # First, choose the correct payload factory based on the request type
+        factory = _create_report_payload_type if for_report else _create_request_payload_type
+
+        # Next, create our payload class from the payload and data types
+        payload_cls = factory(
             self._payload_key,
             type(request_envelope),
             type(request_data),
             False,  # type: ignore[arg-type]
         )
 
-        # Next, inject the payload and data into the payload class
+        # Now, inject the payload and data into the payload class
         # NOTE: this returns a type that inherits from PayloadBase and the arguments provided to the initializer
         # here are correct, but mypy thinks they are incorrect because it doesn't understand the the inherited type
         payload = payload_cls(request_envelope, request_data, self._xsd.value)  # type: ignore[call-arg, misc]
 
         # Finally, convert the payload to XML and return it
         # NOTE: we provided the encoding here so this will return bytes, not a string
-        return payload.to_xml(skip_empty=True, encoding="utf-8", xml_declaration=True)  # type: ignore[return-value]
+        return self._to_canoncialized_xml(payload)
 
-    def serialize_multi(self, request_envelope: E, request_data: List[P], request_type: Type[P]) -> bytes:
+    def serialize_multi(
+        self, request_envelope: E, request_data: List[P], request_type: Type[P], for_report: bool = False
+    ) -> bytes:
         """Serialize the envelope and data to a byte string for sending to the MMS server.
 
         Arguments:
         request_envelope (Envelope):    The envelope to be serialized.
-        request_data (List[Payload]):    The data to be serialized.
-        request_type (Type[Payload]):    The type of data to be serialized.
+        request_data (List[Payload]):   The data to be serialized.
+        request_type (Type[Payload]):   The type of data to be serialized.
+        for_report (bool):              If True, the data will be serialized for a report request.
 
         Returns:    A byte string containing the XML-formatted data to be sent to the MMS server.
         """
-        # First, create our payload class from the payload and data types
-        payload_cls = _create_request_payload_type(
-            self._payload_key, type(request_envelope), request_type, True  # type: ignore[arg-type]
-        )
+        # First, choose the correct payload factory based on the request type
+        factory = _create_report_payload_type if for_report else _create_request_payload_type
+
+        # Next, create our payload class from the payload and data types
+        payload_cls = factory(self._payload_key, type(request_envelope), request_type, True)  # type: ignore[arg-type]
 
-        # Next, inject the payload and data into the payload class
+        # Now, inject the payload and data into the payload class
         # NOTE: this returns a type that inherits from PayloadBase and the arguments provided to the initializer
         # here are correct, but mypy thinks they are incorrect because it doesn't understand the the inherited type
         payload = payload_cls(request_envelope, request_data, self._xsd.value)  # type: ignore[call-arg, misc]
 
         # Finally, convert the payload to XML and return it
         # NOTE: we provided the encoding here so this will return bytes, not a string
-        return payload.to_xml(skip_empty=True, encoding="utf-8", xml_declaration=True)  # type: ignore[return-value]
+        return self._to_canoncialized_xml(payload)
 
-    def deserialize(self, data: bytes, envelope_type: Type[E], data_type: Type[P]) -> Response[E, P]:
+    def deserialize(
+        self, data: bytes, envelope_type: Type[E], data_type: Type[P], for_report: bool = False
+    ) -> Response[E, P]:
         """Deserialize the data to a response object.
 
         Arguments:
         data (bytes):                   The raw data to be deserialized.
         envelope_type (Type[Envelope]): The type of envelope to be constructed.
         data_type (Type[Payload]):      The type of data to be constructed.
+        for_report (bool):              If True, the data will be serialized for a report request.
 
         Returns:    A response object containing the envelope and data extracted from the raw data.
         """
         tree = self._from_xml(data)
-        return self._from_tree(tree, envelope_type, data_type)
+        return self._from_tree(tree, envelope_type, data_type, for_report)
 
-    def deserialize_multi(self, data: bytes, envelope_type: Type[E], data_type: Type[P]) -> MultiResponse[E, P]:
+    def deserialize_multi(
+        self, data: bytes, envelope_type: Type[E], data_type: Type[P], for_report: bool = False
+    ) -> MultiResponse[E, P]:
         """Deserialize the data to a multi-response object.
 
         Arguments:
         data (bytes):                   The raw data to be deserialized.
         envelope_type (Type[Envelope]): The type of envelope to be constructed.
         data_type (Type[Payload]):      The type of data to be constructed.
+        for_report (bool):              If True, the data will be serialized for a report request.
 
         Returns:    A multi-response object containing the envelope and data extracted from the raw data.
         """
         tree = self._from_xml(data)
-        return self._from_tree_multi(tree, envelope_type, data_type)
+        return self._from_tree_multi(tree, envelope_type, data_type, for_report)
+
+    def _to_canoncialized_xml(self, payload: PayloadBase) -> bytes:
+        """Convert the payload to a canonicalized XML string.
+
+        Arguments:
+        payload (PayloadBase): The payload to be converted.
 
-    def _from_tree(self, raw: Element, envelope_type: Type[E], data_type: Type[P]) -> Response[E, P]:
+        Returns:    The canonicalized XML string.
+        """
+        # First, convert the payload to a raw XML string
+        raw: bytes = payload.to_xml(
+            skip_empty=True,
+            encoding="utf-8",
+            xml_declaration=False,
+        )  # type: ignore[assignment]
+
+        # Next, parse it back into an XML tree
+        unparsed = parse(BytesIO(raw))
+
+        # Finally, convert the XML tree to a canonicalized XML string and return it
+        buffer = BytesIO()
+        unparsed.write_c14n(buffer)
+        buffer.seek(0)
+        return buffer.read()
+
+    def _from_tree(self, raw: Element, envelope_type: Type[E], data_type: Type[P], for_report: bool) -> Response[E, P]:
         """Convert the raw data to a response object.
 
         Arguments:
         raw (Element):                  The raw data to be converted.
         envelope_type (Type[Envelope]): The type of envelope to be constructed.
         data_type (Type[Payload]):      The type of data to be constructed.
+        for_report (bool):              If True, the data will be serialized for a report request.
 
         Returns:    A response object containing the envelope and data extracted from the raw data.
         """
@@ -155,7 +194,9 @@ class Serializer:
         resp = cls.from_xml_tree(raw)  # type: ignore[arg-type]
 
         # Next, attempt to extract the envelope and data from within the response
-        resp.envelope, resp.envelope_validation, envelope_node = self._from_tree_envelope(raw, envelope_type)
+        resp.envelope, resp.envelope_validation, envelope_node = self._from_tree_envelope(
+            raw, envelope_type, for_report
+        )
 
         # Now, verify that the response doesn't contain an unexpected data type and then retrieve the payload data
         # from within the envelope
@@ -163,18 +204,23 @@ class Serializer:
         resp.payload = self._from_tree_data(envelope_node.find(get_tag(data_type)), data_type)
 
         # Finally, attempt to extract the messages from within the payload
-        resp.messages = self._from_tree_messages(raw, envelope_type, data_type, self._payload_key, False)
+        resp.messages = self._from_tree_messages(
+            raw, get_tag(envelope_type), data_type, self._payload_key, False, for_report=for_report
+        )
 
         # Return the response
         return resp
 
-    def _from_tree_multi(self, raw: Element, envelope_type: Type[E], data_type: Type[P]) -> MultiResponse[E, P]:
+    def _from_tree_multi(
+        self, raw: Element, envelope_type: Type[E], data_type: Type[P], for_report: bool
+    ) -> MultiResponse[E, P]:
         """Convert the raw data to a multi-response object.
 
         Arguments:
         raw (Element):                  The raw data to be converted.
         envelope_type (Type[Envelope]): The type of envelope to be constructed.
         data_type (Type[Payload]):      The type of data to be constructed.
+        for_report (bool):              If True, the data will be serialized for a report request.
 
         Returns:    A multi-response object containing the envelope and data extracted from the raw data.
         """
@@ -191,7 +237,7 @@ class Serializer:
         resp = cls.from_xml_tree(raw)  # type: ignore[arg-type]
 
         # Next, attempt to extract the envelope from the response
-        resp.envelope, resp.envelope_validation, env_node = self._from_tree_envelope(raw, envelope_type)
+        resp.envelope, resp.envelope_validation, env_node = self._from_tree_envelope(raw, envelope_type, for_report)
 
         # Now, verify that the response doesn't contain an unexpected data type and then retrieve the payload data
         # from within the envelope
@@ -202,17 +248,22 @@ class Serializer:
         ]
 
         # Finally, attempt to extract the messages from within the payload
-        resp.messages = self._from_tree_messages(raw, envelope_type, data_type, self._payload_key, True)
+        resp.messages = self._from_tree_messages(
+            raw, get_tag(envelope_type), data_type, self._payload_key, True, for_report=for_report
+        )
 
         # Return the response
         return resp
 
-    def _from_tree_envelope(self, raw: Element, envelope_type: Type[E]) -> Tuple[E, ResponseCommon, Element]:
+    def _from_tree_envelope(
+        self, raw: Element, envelope_type: Type[E], for_report: bool
+    ) -> Tuple[E, ResponseCommon, Element]:
         """Attempt to extract the envelope from within the response.
 
         Arguments:
         raw (Element):                  The raw data to be converted.
         envelope_type (Type[Envelope]): The type of envelope to be constructed.
+        for_report (bool):              If True, the data will be serialized for a report request.
 
         Returns:
         Envelope:       The request payload constructed from the raw data.
@@ -220,9 +271,10 @@ class Serializer:
         """
         # First, attempt to extract the envelope from within the response; if the key isn't found then we'll raise an
         # exception to indicate that the envelope wasn't found.
-        envelope_node = raw.find(envelope_type.__name__)
-        if envelope_node is None:
-            raise ValueError(f"Expected envelope type '{envelope_type.__name__}' not found in response")
+        envelope_tag = get_tag(envelope_type)
+        envelope_node = raw if for_report else raw.find(envelope_tag)
+        if envelope_node is None or envelope_node.tag != envelope_tag:
+            raise ValueError(f"Expected envelope type '{envelope_tag}' not found in response")
 
         # Next, create a new envelope type that contains the envelope type with the appropriate XML tag. We have to do
         # this because the envelope type doesn't include the ResponseCommon fields, and the tag doesn't match
@@ -247,7 +299,7 @@ class Serializer:
         ValueError:    If the expected data type is not found in the response.
         """
         data_tags = set(node.tag for node in raw)
-        if not data_tags.issubset([data_type.__name__, data_type.__xml_tag__, "Messages"]):
+        if not data_tags.issubset([data_type.__name__, data_type.__xml_tag__, "ProcessingStatistics", "Messages"]):
             raise ValueError(f"Expected data type '{data_type.__name__}' not found in response")
 
     def _from_tree_data(self, raw: Optional[Element], data_type: Type[P]) -> Optional[ResponseData[P]]:
@@ -278,11 +330,12 @@ class Serializer:
     def _from_tree_messages(
         self,
         raw: Element,
-        envelope_type: Type[E],
+        envelope_tag: str,
         current_type: Type[P],
         root: str,
         multi: bool,
         wrapped: bool = False,
+        for_report: bool = False,
     ) -> Dict[str, Messages]:
         """Attempt to extract the messages from within the payload.
 
@@ -292,13 +345,14 @@ class Serializer:
 
         Arguments:
         raw (Element):                  The raw data to be converted.
-        envelope_type (Type[Envelope]): The type of envelope being constructed.
+        envelope_tag (str):             The tag of the envelope being constructed.
         current_type (Type[Payload]):   The type of data being constructed.
         root (str):                     The root of the dictionary, used to create the key for the messages.
         multi (bool):                   Whether we're processing a list of nodes or a single node. If called with the
                                         payload root, this value will determine whether we're processing a multi-
                                         response or a single response.
         wrapped (bool):                 Whether or not this type is referenced from a wrapped field.
+        for_report (bool):              If True, the data will be serialized for a report request.
         """
         # First, find the Messages node in the raw data
         message_node = raw.find("Messages")
@@ -313,21 +367,21 @@ class Serializer:
         # at the root of the response, we need to call this method for the envelope type. If we are at the envelope
         # type, we need to call this method for the data type. If we are at the data type, we need to call this method
         # for each field in the data type that is a Payload type.
-        if root == self._payload_key:
+        if root == self._payload_key and not for_report:
             messages.update(
                 self._from_tree_messages(
-                    _find_or_fail(raw, envelope_type.__name__),
-                    envelope_type,
+                    _find_or_fail(raw, envelope_tag),
+                    envelope_tag,
                     current_type,
-                    f"{root}.{envelope_type.__name__}",
+                    f"{root}.{envelope_tag}",
                     multi,
                     False,
                 )
             )
-        elif root.endswith(envelope_type.__name__) or wrapped:
+        elif root.endswith(envelope_tag) or wrapped:
             messages.update(
                 self._from_tree_messages_inner(
-                    raw, envelope_type, current_type, root, get_tag(current_type), multi, False
+                    raw, envelope_tag, current_type, root, get_tag(current_type), multi, False
                 )
             )
         else:
@@ -350,7 +404,7 @@ class Serializer:
                 messages.update(
                     self._from_tree_messages_inner(
                         raw,
-                        envelope_type,
+                        envelope_tag,
                         arg,
                         root,
                         field.path,  # type: ignore[attr-defined]
@@ -365,7 +419,7 @@ class Serializer:
     def _from_tree_messages_inner(
         self,
         raw: Element,
-        envelope_type: Type[E],
+        envelope_tag: str,
         current_type: Type[P],
         root: str,
         tag: str,
@@ -376,7 +430,7 @@ class Serializer:
 
         Arguments:
         raw (Element):                  The raw data to be converted.
-        envelope_type (Type[Envelope]): The type of envelope being constructed.
+        envelope_tag (str):             The tag of the envelope being constructed.
         current_type (Type[Payload]):   The type of data being constructed.
         root (str):                     The root of the dictionary, used to create the key for the messages.
         tag (str):                      The tag of the current node being processed.
@@ -402,7 +456,7 @@ class Serializer:
             for i, node in enumerate(nodes):
                 messages.update(
                     self._from_tree_messages(
-                        node, envelope_type, current_type, path_base if wrapped else f"{path_base}[{i}]", True, wrapped
+                        node, envelope_tag, current_type, path_base if wrapped else f"{path_base}[{i}]", True, wrapped
                     )
                 )
             return messages
@@ -412,7 +466,7 @@ class Serializer:
         return (
             {}
             if child is None
-            else self._from_tree_messages(child, envelope_type, current_type, path_base, False, wrapped)
+            else self._from_tree_messages(child, envelope_tag, current_type, path_base, False, wrapped)
         )
 
     def _from_xml(self, data: bytes) -> Element:
@@ -497,7 +551,7 @@ def _create_response_common_type(tag_type: Type[Union[E, P]]) -> Type[ResponseCo
 def _create_request_payload_type(
     key: str,
     envelope_type: Type[E],
-    data_type: Type[Union[P, List[P]]],
+    data_type: Type[P],
     multi: bool,
 ) -> Type[PayloadBase]:
     """Create a new payload type for the given payload and data types.
@@ -559,6 +613,45 @@ def _create_request_payload_type(
     return RQPayload
 
 
+@lru_cache(maxsize=None)
+def _create_report_payload_type(key: str, envelope_type: Type[E], data_type: Type[P], multi: bool) -> Type[PayloadBase]:
+    """Create a new payload type for the given report data request.
+
+    Arguments:
+    key: str                        The tag to use for the parent element of the payload.
+    envelope_type (Type[Envelope]): The type of payload to be used for the envelope.
+    data_type (Type[Payload]):      The type of payload to be used for the data.
+    multi (bool):                   If True, the payload will be a list; otherwise, it will be a singleton.
+
+    Returns:    The base payload type that will be used for serialization.
+    """
+    # First, create our data type
+    payload_type = List[data_type] if multi else data_type  # type: ignore[valid-type]
+
+    # Next, create a wrapper for our data type that will be used to store the data in the payload
+    class Envelope(PayloadBase, envelope_type, tag=key):  # type: ignore[valid-type, misc]
+        """Wrapper for the data type that will be used to store the data in the payload."""
+
+        # The data to be stored in the payload
+        data: payload_type = element(tag=get_tag(data_type))  # type: ignore[valid-type]
+
+        def __init__(self, envelope: envelope_type, data: payload_type, schema: str):  # type: ignore[valid-type]
+            """Create a new envelope to store payload data.
+
+            Arguments:
+            envelope (Envelope):    The payload to be stored in the data.
+            data (Payload):         The data to be stored in the payload.
+            schema (str):           The name of the schema file to use for validation.
+            """
+            obj = dict(envelope)
+            obj["data"] = data
+            obj["location"] = schema
+            super().__init__(**obj)
+
+    # Finally, return the payload type so we can instantiate it
+    return Envelope
+
+
 def _find_or_fail(node: Element, tag: str) -> Element:
     """Find the node with the given tag, or raise an error if it isn't found.
 
@@ -615,7 +708,7 @@ def _get_field_typing(typ: Type) -> Tuple[Type, bool]:
     return args[-1][0] if len(args) > 0 else typ, get_origin(origin_type) is list  # typing: ignore[return-value]
 
 
-def get_tag(data_type: Type[P]) -> str:
+def get_tag(data_type: Union[Type[P], Type[E]]) -> str:
     """Get the tag for the given data type.
 
     Arguments: