mms-client 1.9.2__tar.gz → 1.10.0__tar.gz

{mms_client-1.9.2 → mms_client-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mms-client
-Version: 1.9.2
+Version: 1.10.0
 Summary: API client for accessing the MMS
 Home-page: https://github.com/ElectroRoute-Japan/mms-client
 Author: Ryan Wood
@@ -80,6 +80,8 @@ This object represents the top-level XML element contained within the `MmsRespon
 ### Response & MultiResponse
 These objects contain the actual payload data and inherit from `BaseResponse`. These are what will actually be returned from the deserialization process. They also contain validation data for the top-level paylaod item(s). The difference between `Response` and `MultiResponse` is that the former contains a single item and the latter contains a list.
 
+Note that the `MultiResponse` object covers a special case where queries made to the MMS may return no items, in which case the response will be the request object itself. This is handled internally by the client, and the user will receive an empty list in such cases.
+
 ## Envelopes
 Not to be confused with the SOAP envelope, this envelope contains the method parameters used to send requests to the MMS server. For example, if you wanted to send a market-related request, this would take on the form of a `MarketQuery`, `MarketSubmit` or `MarketCancel` object. This is combined with the payload during the serialization process to produce the final XML payload before injecting it into the `MmsRequest`. During the deserialization process, this is extracted from the XML paylod on the `MmsResponse` object. Each of these should inherit from `mms_client.types.base.Envelope`.
 

{mms_client-1.9.2 → mms_client-1.10.0}/README.md

@@ -46,6 +46,8 @@ This object represents the top-level XML element contained within the `MmsRespon
 ### Response & MultiResponse
 These objects contain the actual payload data and inherit from `BaseResponse`. These are what will actually be returned from the deserialization process. They also contain validation data for the top-level paylaod item(s). The difference between `Response` and `MultiResponse` is that the former contains a single item and the latter contains a list.
 
+Note that the `MultiResponse` object covers a special case where queries made to the MMS may return no items, in which case the response will be the request object itself. This is handled internally by the client, and the user will receive an empty list in such cases.
+
 ## Envelopes
 Not to be confused with the SOAP envelope, this envelope contains the method parameters used to send requests to the MMS server. For example, if you wanted to send a market-related request, this would take on the form of a `MarketQuery`, `MarketSubmit` or `MarketCancel` object. This is combined with the payload during the serialization process to produce the final XML payload before injecting it into the `MmsRequest`. During the deserialization process, this is extracted from the XML paylod on the `MmsResponse` object. Each of these should inherit from `mms_client.types.base.Envelope`.
 

{mms_client-1.9.2 → mms_client-1.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "mms_client"
-version = "v1.9.2"
+version = "v1.10.0"
 description = "API client for accessing the MMS"
 authors = ["Ryan Wood <ryan.wood@electroroute.co.jp>"]
 readme = "README.md"

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/services/base.py

@@ -28,6 +28,7 @@ from mms_client.types.transport import RequestDataType
 from mms_client.types.transport import RequestType
 from mms_client.types.transport import ResponseDataType
 from mms_client.utils.errors import AudienceError
+from mms_client.utils.errors import EnvelopeNodeNotFoundError
 from mms_client.utils.errors import MMSClientError
 from mms_client.utils.errors import MMSServerError
 from mms_client.utils.errors import MMSValidationError
@@ -131,7 +132,7 @@ class ClientProto(Protocol):
         envelope: E,
         data: Union[P, List[P]],
         config: EndpointConfiguration,
-    ) -> Tuple[MultiResponse[E, P], Dict[str, bytes]]:
+    ) -> Tuple[MultiResponse[E, P], Dict[str, bytes], bool]:
         """Submit a request to the MMS server and return the multi-response.
 
         Arguments:
@@ -139,7 +140,10 @@ class ClientProto(Protocol):
         data (Payload):                 The data to submit to the MMS server.
         config (EndpointConfiguration): The configuration for the endpoint.
 
-        Returns:    The multi-response from the MMS server.
+        Returns:
+        MultiResponse[E, P]:    The multi-response from the MMS server.
+        Dict[str, bytes]:       The attachments returned with the response.
+        bool:                   Whether or not the response was found.
         """
 
 
@@ -244,15 +248,15 @@ def mms_multi_endpoint(**kwargs):
                 envelope, callback = result, None
 
             # Now, submit the request to the MMS server and get the response
-            resp, attachments = self.request_many(envelope, args[0], config)
+            resp, attachments, found = self.request_many(envelope, args[0], config)
 
             # Call the callback function if it was provided
             if callback:
-                callback(resp, attachments)  # pragma: no cover
+                callback(resp, attachments, found)  # pragma: no cover
 
             # Finally, extract the data from the response and return it
             logger.info(f"{config.name}: Returning {len(resp.data)} item(s).")
-            return resp.data
+            return resp.data if found else []
 
         return wrapper
 
@@ -382,7 +386,9 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         envelope_type = config.response_envelope_type or type(envelope)
         data_type = config.response_data_type or type(payload)
         deserializer = config.serializer or config.service.serializer
-        data: Response[E, P] = deserializer.deserialize(resp.payload, envelope_type, data_type, config.for_report)
+        data: Response[E, P] = deserializer.deserialize(
+            config.name, resp.payload, envelope_type, data_type, config.for_report
+        )
         self._verify_response(data, config)
 
         # Return the response data and any attachments
@@ -391,12 +397,12 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         )
         return data, attachments
 
-    def request_many(
+    def request_many(  # pylint: disable=too-many-locals
         self,
         envelope: E,
         payload: Union[P, List[P]],
         config: EndpointConfiguration[E, P],
-    ) -> Tuple[MultiResponse[E, P], Dict[str, bytes]]:
+    ) -> Tuple[MultiResponse[E, P], Dict[str, bytes], bool]:
         """Submit a request to the MMS server and return the multi-response.
 
         Arguments:
@@ -404,7 +410,10 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         payload (Payload):              The data to submit to the MMS server.
         config (EndpointConfiguration): The configuration for the endpoint.
 
-        Returns:    The multi-response from the MMS server.
+        Returns:
+        MultiResponse[E, P]:    The multi-response from the MMS server.
+        Dict[str, bytes]:       The attachments returned with the response.
+        bool:                   Whether or not the response was found.
         """
         # Create a new ZWrapper for the given service
         wrapper = self._get_wrapper(config.service)
@@ -434,23 +443,41 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         # Now, extract the attachments from the response
         attachments = {a.name: b64decode(a.data) for a in resp.attachments}
 
-        # Finally, deserialize and verify the response
-        envelope_type = config.response_envelope_type or type(envelope)
-        data_type = config.response_data_type or data_type
+        # Finally, deserialize the response and verify it
         deserializer = config.serializer or config.service.serializer
-        data: MultiResponse[E, P] = deserializer.deserialize_multi(
-            resp.payload,
-            envelope_type,
-            data_type,  # type: ignore[arg-type]
-            config.for_report,
-        )
+        try:
+            found = True
+            envelope_type = config.response_envelope_type or type(envelope)
+            resp_data_type = config.response_data_type or data_type
+            data: MultiResponse[E, P] = deserializer.deserialize_multi(
+                config.name,
+                resp.payload,
+                envelope_type,
+                resp_data_type,  # type: ignore[arg-type]
+                config.for_report,
+            )
+        except EnvelopeNodeNotFoundError:
+            logger.warning(
+                f"{config.name}: Failed to deserialize multi-response. Attempting to deserialize as the request object."
+            )
+            found = False
+            envelope_type = type(envelope)
+            resp_data_type = data_type
+            data = deserializer.deserialize_multi(
+                config.name,
+                resp.payload,
+                envelope_type,
+                data_type,  # type: ignore[arg-type]
+                config.for_report,
+            )
         self._verify_multi_response(data, config)
 
         # Return the response data and any attachments
         logger.debug(
-            f"{config.name}: Returning multi-response. Envelope: {envelope_type.__name__}, Data: {data_type.__name__}",
+            f"{config.name}: Returning multi-response. Envelope: {envelope_type.__name__}, Data: "
+            f"{resp_data_type.__name__}"
         )
-        return data, attachments
+        return data, attachments, found
 
     def _to_mms_request(
         self,

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/services/market.py

@@ -40,7 +40,7 @@ class MarketClientMixin:  # pylint: disable=unused-argument
     @mms_multi_endpoint(
         name="MarketQuery_ReserveRequirementQuery",
         service=config,
-        request_type=RequestType.INFO,
+        request_type=RequestType.MARKET,
         response_envelope_type=MarketSubmit,
         response_data_type=ReserveRequirement,
     )

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/types/award.py

@@ -2,6 +2,7 @@
 
 from decimal import Decimal
 from enum import Enum
+from typing import Annotated
 from typing import List
 from typing import Optional
 
@@ -323,7 +324,7 @@ class AwardResult(Payload, tag="AwardResults"):
     direction: Direction = attr(name="Direction")
 
     # The bid awards associated with these parameters
-    data: List[Award] = element(tag="AwardResultsData", min_length=1)
+    data: Annotated[List[Award], element(tag="AwardResultsData", min_length=1)]
 
     @field_serializer("start", "end")
     def encode_datetime(self, value: DateTime) -> str:
@@ -340,4 +341,4 @@ class AwardResponse(AwardQuery, tag="AwardResultsQuery"):
     """Contains the results of a bid award query."""
 
     # The bid awards associated with the query
-    results: Optional[List[AwardResult]] = wrapped(default=None, path="AwardResultsQueryResponse")
+    results: Annotated[Optional[List[AwardResult]], wrapped(default=None, path="AwardResultsQueryResponse")]

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/types/base.py

@@ -35,6 +35,9 @@ class Message(BaseXmlModel):
     # The message text. Not sure why this is called code in the XML.
     code: str = attr(default="", name="Code", min_length=2, max_length=50, pattern=r"^[a-zA-Z_0-9\-]*$")
 
+    # A human-readable description of the message
+    description: str
+
 
 class Messages(BaseXmlModel, search_mode="unordered", arbitrary_types_allowed=True):
     """Represents a collection of messages returned with a payload."""
@@ -49,21 +52,21 @@ class Messages(BaseXmlModel, search_mode="unordered", arbitrary_types_allowed=Tr
     errors_raw: List[Element] = element(default=[], tag="Error", nillable=True, exclude=True)
 
     @computed_element
-    def information(self) -> List[str]:
+    def information(self) -> List[Message]:
         """Return the information messages."""
         return self._parse_messages(self.information_raw)
 
     @computed_element
-    def warnings(self) -> List[str]:
+    def warnings(self) -> List[Message]:
         """Return the warning messages."""
         return self._parse_messages(self.warnings_raw)
 
     @computed_element
-    def errors(self) -> List[str]:
+    def errors(self) -> List[Message]:
         """Return the error messages."""
         return self._parse_messages(self.errors_raw)
 
-    def _parse_messages(self, raw: List[Element]) -> List[str]:
+    def _parse_messages(self, raw: List[Element]) -> List[Message]:
         """Parse the messages from the XML tree.
 
         Arguments:
@@ -73,10 +76,11 @@ class Messages(BaseXmlModel, search_mode="unordered", arbitrary_types_allowed=Tr
         """
         messages = []
         for item in raw:
+            text = item.text or ""
             if message := item.attrib.get("Code"):
-                messages.append(message)
+                messages.append(Message(description=text, code=message))
             else:
-                messages.append(item.text or "")
+                messages.append(Message(description=text))
         return messages
 
 

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/types/fields.py

@@ -115,7 +115,7 @@ def power_positive(alias: str, optional: bool = False):
 
     Returns:    A Pydantic Field object for the power value.
     """
-    return attr(default=None if optional else PydanticUndefined, name=alias, gt=0, le=10000000)
+    return attr(default=None if optional else PydanticUndefined, name=alias, ge=0, le=10000000)
 
 
 def price(alias: str, limit: float, optional: bool = False):

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/types/offer.py

@@ -1,6 +1,7 @@
 """Contains objects for MMS offers."""
 
 from decimal import Decimal
+from typing import Annotated
 from typing import List
 from typing import Optional
 
@@ -79,7 +80,7 @@ class OfferData(Payload):
     """Describes the data common to both offer requests and responses."""
 
     # The separate offers that make up the offer stack
-    stack: List[OfferStack] = element(tag="OfferStack", min_length=1, max_length=20)
+    stack: Annotated[List[OfferStack], element(tag="OfferStack", min_length=1, max_length=20)]
 
     # The identifier for the power resource being traded
     resource: str = resource_name("ResourceName")

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/types/report.py

@@ -269,7 +269,7 @@ class NewReportRequest(ReportMetadata, tag="ReportCreateRequest"):
     bsp_name: Optional[str] = participant("BSPName", True)
 
     # Parameters to be use when configuring the report
-    parameters: List[Parameter] = element(tag="Param", max_length=5)
+    parameters: Annotated[List[Parameter], element(tag="Param", max_length=5)]
 
 
 class NewReportResponse(NewReportRequest, tag="ReportCreateRequest"):
@@ -287,7 +287,7 @@ class ListReportResponse(ListReportRequest, tag="ReportListRequest"):
     """Represents the base fields for a list report response."""
 
     # The list of reports that match the query
-    reports: List[ReportItem] = wrapped(path="ReportListResponse", entity=element(tag="ReportItem"))
+    reports: Annotated[List[ReportItem], wrapped(path="ReportListResponse", entity=element(tag="ReportItem"))]
 
 
 class ReportDownloadRequest(ReportData):

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/types/reserve.py

@@ -1,5 +1,6 @@
 """Contains objects for MMS reserve requirements."""
 
+from typing import Annotated
 from typing import List
 from typing import Optional
 
@@ -71,7 +72,7 @@ class ReserveRequirement(Payload):
     area: AreaCode = attr(name="Area")
 
     # The requirements associated with the area
-    requirements: List[Requirement] = element(tag="Requirement", min_length=1)
+    requirements: Annotated[List[Requirement], element(tag="Requirement", min_length=1)]
 
 
 class ReserveRequirementQuery(Payload):

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/types/resource.py

@@ -328,7 +328,7 @@ class StartupPattern(Payload, tag="StartupPatternInfo"):
     pattern_name: str = pattern_name("PatternName")
 
     # The events associated with this startup pattern
-    events: List[StartupEvent] = element(tag="StartupPatternEvent", min_length=6, max_length=25)
+    events: Annotated[List[StartupEvent], element(tag="StartupPatternEvent", min_length=6, max_length=25)]
 
 
 class ShutdownEvent(Payload):
@@ -366,34 +366,36 @@ class ShutdownPattern(Payload, tag="StopPatternInfo"):
     pattern_name: str = pattern_name("PatternName")
 
     # The events associated with this stop pattern
-    events: List[ShutdownEvent] = element(tag="StopPatternEvent", min_length=2, max_length=21)
+    events: Annotated[List[ShutdownEvent], element(tag="StopPatternEvent", min_length=2, max_length=21)]
 
 
 class ResourceData(Payload, tag="Resource"):
     """Contains the data common to both resource requests and responses."""
 
     # The output bands associated with this resource
-    output_bands: Optional[List[OutputBand]] = wrapped(default=None, path="OutputBand", min_length=1, max_length=20)
+    output_bands: Annotated[
+        Optional[List[OutputBand]], wrapped(default=None, path="OutputBand", min_length=1, max_length=20)
+    ]
 
     # The switching outputs associated with this resource
-    switch_outputs: Optional[List[SwitchOutput]] = wrapped(
-        default=None, path="SwitchOutput", min_length=1, max_length=20
-    )
+    switch_outputs: Annotated[
+        Optional[List[SwitchOutput]], wrapped(default=None, path="SwitchOutput", min_length=1, max_length=20)
+    ]
 
     # The minimum EDC/LFC outputs associated with this resource
-    afc_minimum_outputs: Optional[List[AfcMinimumOutput]] = wrapped(
-        default=None, path="OutputRangeBelowAfc", min_length=1, max_length=20
-    )
+    afc_minimum_outputs: Annotated[
+        Optional[List[AfcMinimumOutput]], wrapped(default=None, path="OutputRangeBelowAfc", min_length=1, max_length=20)
+    ]
 
     # The startup patterns associated with this resource
-    startup_patterns: Optional[List[StartupPattern]] = wrapped(
-        default=None, path="StartupPattern", min_length=1, max_length=20
-    )
+    startup_patterns: Annotated[
+        Optional[List[StartupPattern]], wrapped(default=None, path="StartupPattern", min_length=1, max_length=20)
+    ]
 
     # The stop patterns associated with this resource
-    shutdown_patterns: Optional[List[ShutdownPattern]] = wrapped(
-        default=None, path="StopPattern", min_length=1, max_length=20
-    )
+    shutdown_patterns: Annotated[
+        Optional[List[ShutdownPattern]], wrapped(default=None, path="StopPattern", min_length=1, max_length=20)
+    ]
 
     # Any comments attached to the resource
     comments: Optional[str] = element(

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/types/transport.py

@@ -1,6 +1,7 @@
 """Contains the base types necessary for communication with the MMS server."""
 
 from enum import Enum
+from typing import Annotated
 from typing import List
 from typing import Optional
 
@@ -87,7 +88,7 @@ class MmsRequest(BaseModel):
 
     # Any attached files to be sent with the request. Only 20 of these are allowed for OMI requests. For MI requests,
     # the limit is 40.
-    attachments: List[Attachment] = Field(default=[], alias="attachmentData")
+    attachments: Annotated[List[Attachment], Field(alias="attachmentData")] = []
 
     def to_arguments(self) -> dict:
         """Convert the request to a dictionary of arguments for use in the MMS client."""
@@ -127,4 +128,4 @@ class MmsResponse(BaseModel):
     payload: bytes = Field(alias="responseData")
 
     # Any attached files to be sent with the response
-    attachments: List[Attachment] = Field(default=[], alias="attachmentData")
+    attachments: Annotated[List[Attachment], Field(alias="attachmentData")] = []

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/utils/errors.py

@@ -4,6 +4,7 @@ from logging import getLogger
 from typing import Dict
 from typing import List
 from typing import Optional
+from typing import Type
 from typing import Union
 
 from mms_client.types.base import E
@@ -88,3 +89,53 @@ class MMSValidationError(RuntimeError):
         self.method = method
         self.messages = messages
         super().__init__(self.message)
+
+
+class InvalidContainerError(ValueError):
+    """Error raised when the outer XML tag is not the expected one."""
+
+    def __init__(self, method: str, expected: str, actual: str):
+        """Initialize the error.
+
+        Arguments:
+        method (str):   The method that caused the error.
+        expected (str): The expected outer XML tag.
+        actual (str):   The actual outer XML tag.
+        """
+        self.message = f"{method}: Expected payload key '{expected}' in response, but found '{actual}'."
+        self.method = method
+        self.expected = expected
+        self.actual = actual
+        super().__init__(self.message)
+
+
+class EnvelopeNodeNotFoundError(ValueError):
+    """Error raised when the envelope node is not found."""
+
+    def __init__(self, method: str, expected: str):
+        """Initialize the error.
+
+        Arguments:
+        method (str):   The method that caused the error.
+        expected (str): The expected envelope XML tag.
+        """
+        self.message = f"{method}: Expected envelope node '{expected}' not found in response."
+        self.method = method
+        self.expected = expected
+        super().__init__(self.message)
+
+
+class DataNodeNotFoundError(ValueError):
+    """Error raised when the data node is not found."""
+
+    def __init__(self, method: str, expected: Type):
+        """Initialize the error.
+
+        Arguments:
+        method (str):       The method that caused the error.
+        expected (Type):    The expected data node.
+        """
+        self.message = f"{method}: Expected data node '{expected.__name__}' not found in response."
+        self.method = method
+        self.expected = expected
+        super().__init__(self.message)

{mms_client-1.9.2 → mms_client-1.10.0}/src/mms_client/utils/serialization.py

@@ -29,6 +29,9 @@ from mms_client.types.base import Response
 from mms_client.types.base import ResponseCommon
 from mms_client.types.base import ResponseData
 from mms_client.types.base import SchemaType
+from mms_client.utils.errors import DataNodeNotFoundError
+from mms_client.utils.errors import EnvelopeNodeNotFoundError
+from mms_client.utils.errors import InvalidContainerError
 
 # Directory containing all our XML schemas
 XSD_DIR = Path(__file__).parent.parent / "schemas" / "xsd"
@@ -115,11 +118,12 @@ class Serializer:
         return self._to_canoncialized_xml(payload)
 
     def deserialize(
-        self, data: bytes, envelope_type: Type[E], data_type: Type[P], for_report: bool = False
+        self, method: str, 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:
+        method (str):                   The method for which the data was received.
         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.
@@ -128,14 +132,15 @@ class Serializer:
         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, for_report)
+        return self._from_tree(method, tree, envelope_type, data_type, for_report)
 
     def deserialize_multi(
-        self, data: bytes, envelope_type: Type[E], data_type: Type[P], for_report: bool = False
+        self, method: str, 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:
+        method (str):                   The method for which the data was received.
         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.
@@ -144,7 +149,7 @@ class Serializer:
         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, for_report)
+        return self._from_tree_multi(method, tree, envelope_type, data_type, for_report)
 
     def _to_canoncialized_xml(self, payload: PayloadBase) -> bytes:
         """Convert the payload to a canonicalized XML string.
@@ -170,10 +175,13 @@ class Serializer:
         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]:
+    def _from_tree(
+        self, method: str, 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:
+        method (str):                   The method for which the data was received.
         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.
@@ -184,7 +192,7 @@ class Serializer:
         # First, attempt to extract the response from the raw data; if the key isn't found then we'll raise an error.
         # Otherwise, we'll attempt to construct the response from the raw data.
         if self._payload_key != raw.tag:
-            raise ValueError(f"Expected payload key '{self._payload_key}' not found in response")
+            raise InvalidContainerError(method, self._payload_key, raw.tag)
         cls: Response[E, P] = _create_response_payload_type(  # type: ignore[assignment]
             self._payload_key,
             envelope_type,  # type: ignore[arg-type]
@@ -195,12 +203,12 @@ class Serializer:
 
         # 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, for_report
+            method, 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
-        self._verify_tree_data_tag(envelope_node, data_type)
+        self._verify_tree_data_tag(method, envelope_node, data_type)
         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
@@ -212,11 +220,12 @@ class Serializer:
         return resp
 
     def _from_tree_multi(
-        self, raw: Element, envelope_type: Type[E], data_type: Type[P], for_report: bool
+        self, method: str, 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:
+        method (str):                   The method for which the data was received.
         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.
@@ -227,7 +236,7 @@ class Serializer:
         # First, attempt to extract the response from the raw data; if the key isn't found then we'll raise an error.
         # Otherwise, we'll attempt to construct the response from the raw data.
         if self._payload_key != raw.tag:
-            raise ValueError(f"Expected payload key '{self._payload_key}' not found in response")
+            raise InvalidContainerError(method, self._payload_key, raw.tag)
         cls: MultiResponse[E, P] = _create_response_payload_type(  # type: ignore[assignment]
             self._payload_key,
             envelope_type,  # type: ignore[arg-type]
@@ -237,12 +246,14 @@ 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, for_report)
+        resp.envelope, resp.envelope_validation, env_node = self._from_tree_envelope(
+            method, 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
         # NOTE: apparently, mypy doesn't know about setter-getter properties either...
-        self._verify_tree_data_tag(env_node, data_type)
+        self._verify_tree_data_tag(method, env_node, data_type)
         resp.payload = [
             self._from_tree_data(item, data_type) for item in env_node.findall(get_tag(data_type))  # type: ignore[misc]
         ]
@@ -256,11 +267,12 @@ class Serializer:
         return resp
 
     def _from_tree_envelope(
-        self, raw: Element, envelope_type: Type[E], for_report: bool
+        self, method: str, raw: Element, envelope_type: Type[E], for_report: bool
     ) -> Tuple[E, ResponseCommon, Element]:
         """Attempt to extract the envelope from within the response.
 
         Arguments:
+        method (str):                   The method for which the data was received.
         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.
@@ -274,7 +286,7 @@ class Serializer:
         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")
+            raise EnvelopeNodeNotFoundError(method, envelope_tag)
 
         # 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
@@ -288,10 +300,11 @@ class Serializer:
             envelope_node,
         )
 
-    def _verify_tree_data_tag(self, raw: Element, data_type: Type[P]) -> None:
+    def _verify_tree_data_tag(self, method: str, raw: Element, data_type: Type[P]) -> None:
         """Verify that no types other than the expected data type are present in the response.
 
         Arguments:
+        method (str):               The method for which the data was received.
         raw (Element):              The raw data to be converted.
         data_type (Type[Payload]):  The type of data to be constructed.
 
@@ -300,7 +313,7 @@ class Serializer:
         """
         data_tags = set(node.tag for node in raw)
         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")
+            raise DataNodeNotFoundError(method, data_type)
 
     def _from_tree_data(self, raw: Optional[Element], data_type: Type[P]) -> Optional[ResponseData[P]]:
         """Attempt to extract the data from within the payload.