mms-client 1.9.3__py3-none-any.whl → 1.11.0__py3-none-any.whl

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/types/market.py

@@ -4,7 +4,9 @@ from enum import Enum
 from typing import Optional
 
 from pydantic_extra_types.pendulum_dt import Date
+from pydantic_xml import BaseXmlModel
 from pydantic_xml import attr
+from pydantic_xml import element
 
 from mms_client.types.base import Envelope
 from mms_client.types.fields import participant
@@ -32,12 +34,19 @@ class BaseMarketRequest(Envelope):
     user: str = attr(name="UserName", min_length=1, max_length=12, pattern=r"^[A-Z0-9]*$")
 
 
+class Defaults(BaseXmlModel):
+    """Represents the default settings to apply when submitting a market request."""
+
+    # Whether or not the submission represents the default
+    is_default: bool = attr(name="StandingFlag")
+
+
 class MarketQuery(BaseMarketRequest):
     """Represents the base fields for a market query."""
 
     # If the market type is specified as "DAM" (day-ahead market), the number of days should be specified as "1".
     # Otherwise, this field indicates the number of days ahead for which the data is being queried.
-    days: int = attr(default=1, name="NumOfDays", ge=1, le=7)
+    days: Optional[int] = attr(default=None, name="NumOfDays", ge=1, le=7)
 
 
 class MarketSubmit(BaseMarketRequest):
@@ -48,7 +57,11 @@ class MarketSubmit(BaseMarketRequest):
 
     # If the market type is specified as "DAM" (day-ahead market), the number of days should be specified as "1".
     # Otherwise, this field indicates the number of days ahead for which the data is being submitted.
-    days: int = attr(default=1, name="NumOfDays", ge=1, le=31)
+    days: Optional[int] = attr(default=None, name="NumOfDays", ge=1, le=31)
+
+    # Default values to include with the submission. The request will be rejected if this is included in a request
+    # where it is not allowed.
+    defaults: Optional[Defaults] = element(default=None, tag="StandingData")
 
 
 class MarketCancel(BaseMarketRequest):

mms_client/types/offer.py

@@ -72,6 +72,12 @@ class OfferStack(Payload):
     # The unit price of the power, in JPY/kW/segment
     unit_price: Decimal = price("OfferUnitPrice", 10000.00)
 
+    # The unit price charged for the start up cost of the power, in JPY/kW/segment
+    start_up_unit_price: Annotated[Decimal, price("StartUpUnitPrice", 10000.00, True)]
+
+    # The unit price charged for the ramp down cost of the power, in JPY/kW/segment
+    ramp_down_unit_price: Annotated[Decimal, price("RampDownUnitPrice", 10000.00, True)]
+
     # The ID of the offer to which this stack belongs
     id: Optional[str] = offer_id("OfferId", True)
 

mms_client/types/omi.py

@@ -0,0 +1,26 @@
+"""Contains objects for OMI information."""
+
+from pydantic_extra_types.pendulum_dt import Date
+from pydantic_xml import attr
+
+from mms_client.types.base import Envelope
+from mms_client.types.fields import participant
+
+
+class MarketSubmit(Envelope):
+    """Represents the base fields for a market registration request."""
+
+    # Date of the transaction in the format "YYYY-MM-DD"
+    date: Date = attr(name="Date")
+
+    # MMS code of the business entity to which the requesting user belongs, and will be used to track the user who made
+    # the request. This value will be checked against the certificate used to make the request.
+    participant: str = participant("ParticipantName")
+
+    # The user name of the person making the request. This value is used to track the user who made the request, and
+    # will be checked against the certificate used to make the request.
+    user: str = attr(name="UserName", min_length=1, max_length=12, pattern=r"^[A-Z0-9]*$")
+
+
+class MarketQuery(MarketSubmit):
+    """Represents the base fields for a market query."""

mms_client/types/settlement.py

@@ -0,0 +1,81 @@
+"""Contains objects for MMS settlement."""
+
+from typing import Annotated
+from typing import List
+from typing import Optional
+
+from pendulum import Timezone
+from pydantic import field_serializer
+from pydantic import field_validator
+from pydantic_core import PydanticUndefined
+from pydantic_extra_types.pendulum_dt import Date
+from pydantic_extra_types.pendulum_dt import DateTime
+from pydantic_xml import attr
+from pydantic_xml import element
+
+from mms_client.types.base import Payload
+from mms_client.types.fields import company_short_name
+from mms_client.types.fields import participant
+
+
+def file_name(alias: str, optional: bool = False):
+    """Create a field for a file name.
+
+    Arguments:
+    alias (str):        The name of the alias to assign to the Pydanitc field. This value will be used to map the field
+                        to the JSON/XML key.
+    optional (bool):    If True, the field will be optional with a default of None. If False, the field will be
+                        required, with no default.
+
+    Returns:    A Pydantic Field object for the file name.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined,
+        name=alias,
+        min_length=18,
+        max_length=60,
+        pattern=r"^([A-Z0-9]{4}_){2}[A-Z0-9_-]{4,46}\.(pdf|zip|csv|xml)$",
+    )
+
+
+class SettlementFile(Payload):
+    """Represents a settlement file."""
+
+    # The name of the settlement file as it is recorded in the system
+    name: str = file_name("Name")
+
+    # The name of the participant (only valid if operating as a TSO)
+    participant: Optional[str] = participant("ParticipantName", True)
+
+    # The name of the company associated with the file (only valid if operating as a TSO)
+    company: Optional[str] = company_short_name("CompanyShortName", True)
+
+    # When the file was submitted (not sure why this can be None but it's in the spec)
+    submission_time: Optional[DateTime] = attr(name="SubmissionTime", default=None)
+
+    # The date when settlement occurred (not included if settlement is in the future)
+    settlement_date: Optional[Date] = attr(name="SttlDate", default=None)
+
+    # The size of the file in bytes, if it has been uploaded
+    size: Optional[int] = attr(name="FileSize", default=None, ge=0, lt=1000000000)
+
+    @field_serializer("submission_time")
+    def encode_datetime(self, value: DateTime) -> str:
+        """Encode the datetime to an MMS-compliant ISO 8601 string."""
+        return value.replace(tzinfo=None).isoformat() if value else ""
+
+    @field_validator("submission_time")
+    def decode_datetime(cls, value: DateTime) -> DateTime:  # pylint: disable=no-self-argument
+        """Decode the datetime from an MMS-compliant ISO 8601 string."""
+        return value.replace(tzinfo=Timezone("Asia/Tokyo"))
+
+
+class SettlementResults(Payload):
+    """Contains a list of settlement files that can be requested separately later."""
+
+    # The file results that were retrieved by the query
+    files: Annotated[List[SettlementFile], element(tag="File", min_length=1)]
+
+
+class SettlementQuery(Payload, tag="SettlementResultsFileListQuery"):
+    """Represents a request to query settlement results file list."""

mms_client/types/surplus_capcity.py

@@ -0,0 +1,187 @@
+"""Contains objects for surplus capacity information."""
+
+from enum import Enum
+from typing import Optional
+
+from pendulum import Timezone
+from pydantic import field_serializer
+from pydantic import field_validator
+from pydantic_extra_types.pendulum_dt import DateTime
+from pydantic_xml import attr
+
+from mms_client.types.base import Payload
+from mms_client.types.enums import AreaCode
+from mms_client.types.fields import company_short_name
+from mms_client.types.fields import participant
+from mms_client.types.fields import power_positive
+from mms_client.types.fields import resource_name
+from mms_client.types.fields import resource_short_name
+from mms_client.types.fields import system_code
+
+
+class RejectCategory(Enum):
+    """Represents the category of the reason for rejecting a surplus capacity request."""
+
+    FUEL_RESTRICTION = "1"
+    RIVER_FLOW_RESTRICTION = "2"
+    WORK_RELATED = "3"
+    OTHER = "9"
+
+
+class OperationalRejectCategory(Enum):
+    """Represents the category of the reason for rejecting an operational request.
+
+    This include voltage adjustment, black start, over-power, peak mode or system security pump request.
+    """
+
+    EQUIPMENT_FAILURE = "1"
+    NOT_SUPPORTED = "2"
+    OTHER = "9"
+
+
+class SurplusCapacitySubmit(Payload, tag="RemainingReserveData"):
+    """Represents the base fields for a surplus capacity response."""
+
+    # The name of the resource for which the surplus capacity is being submitted
+    resource_code: str = resource_name("ResourceName")
+
+    # The DR pattern number for which the surplus capacity is being submitted
+    pattern_number: int = attr(name="DrPatternNumber", ge=1, le=20)
+
+    # The start block from when the surplus capacity should apply
+    start: DateTime = attr(name="StartTime")
+
+    # The end block until when the surplus capacity should apply
+    end: DateTime = attr(name="EndTime")
+
+    # The available surplus capacity that can be increased or dispatched when needed, such as in response to grid
+    # demand fluctuations. This should not be submitted for standalone generators.
+    upward_capacity: Optional[int] = power_positive("RemainingReserveUp", True)
+
+    # In the case where excess surplus capacity is rejected, this field will indicate the category of the reason.
+    upward_capacity_rejected: Optional[RejectCategory] = attr(default=None, name="RemainingReserveUpRejectFlag")
+
+    # If the upward dispatch is rejected, this field will indicate a specific reason.
+    upward_capacity_rejection_reason: Optional[str] = attr(
+        default=None, name="RemainingReserveUpRejectReason", min_length=1, max_length=50
+    )
+
+    # The available surplus capacity that can be decreased when needed, such as in response to grid demand fluctuations.
+    # This should not be submitted for standalone generators.
+    downward_capacity: Optional[int] = power_positive("RemainingReserveDown", True)
+
+    # In the case where excess surplus capacity is rejected, this field will indicate the category of the reason.
+    downward_capacity_rejected: Optional[RejectCategory] = attr(default=None, name="RemainingReserveDownRejectFlag")
+
+    # If the downward dispatch is rejected, this field will indicate a specific reason.
+    downward_capacity_rejection_reason: Optional[str] = attr(
+        default=None, name="RemainingReserveDownRejectReason", min_length=1, max_length=50
+    )
+
+    # If voltage adjustment is rejected, this field will indicate the category of the reason.
+    voltage_adjustment_rejected: Optional[OperationalRejectCategory] = attr(
+        default=None, name="VoltageAdjustmentRejectFlag"
+    )
+
+    # If voltage adjustment is rejected, this field will indicate a specific reason.
+    voltage_adjustment_rejection_reason: Optional[str] = attr(
+        default=None, name="VoltageAdjustmentRejectReason", min_length=1, max_length=50
+    )
+
+    # If black start is rejected, this field will indicate the category of the reason.
+    black_start_rejected: Optional[OperationalRejectCategory] = attr(default=None, name="BlackStartRejectFlag")
+
+    # If black start is rejected, this field will indicate a specific reason.
+    black_start_rejection_reason: Optional[str] = attr(
+        default=None, name="BlackStartRejectReason", min_length=1, max_length=50
+    )
+
+    # The additional reserve capacity that can be utilized in cases of excessive or "overpower" conditions, such as
+    # when demand exceeds usual levels.
+    over_power_capacity: Optional[int] = power_positive("OverPowerRemainingReserveUp", True)
+
+    # In the case where over-power capacity is rejected, this field will indicate the category of the reason.
+    over_power_rejected: Optional[OperationalRejectCategory] = attr(default=None, name="OverPowerRejectFlag")
+
+    # If over-power capacity is rejected, this field will indicate a specific reason.
+    over_power_rejection_reason: Optional[str] = attr(
+        default=None, name="OverPowerRejectReason", min_length=1, max_length=50
+    )
+
+    # The available surplus capacity that can be increased specifically during peak demand periods
+    peak_mode_capacity: Optional[int] = power_positive("PeakModeRemainingReserveUp", True)
+
+    # In the case where peak mode capacity is rejected, this field will indicate the category of the reason.
+    peak_mode_rejected: Optional[OperationalRejectCategory] = attr(default=None, name="PeakModeRejectFlag")
+
+    # If peak mode capacity is rejected, this field will indicate a specific reason.
+    peak_mode_rejection_reason: Optional[str] = attr(
+        default=None, name="PeakModeRejectReason", min_length=1, max_length=50
+    )
+
+    # Indicates whether the operation of a pumped-storage hydroelectric pump is restricted or disallowed for system
+    # security reasons.
+    system_security_pump_rejected: Optional[OperationalRejectCategory] = attr(
+        default=None, name="SystemSecurityPumpRejectFlag"
+    )
+
+    # If the operation of a pumped-storage hydroelectric pump is restricted or disallowed for system security reasons,
+    # this field will indicate a specific reason.
+    system_security_pump_rejection_reason: Optional[str] = attr(
+        default=None, name="SystemSecurityPumpRejectReason", min_length=1, max_length=50
+    )
+
+    @field_serializer("start", "end")
+    def encode_datetime(self, value: DateTime) -> str:
+        """Encode the datetime to an MMS-compliant ISO 8601 string."""
+        return value.replace(tzinfo=None).isoformat() if value else ""
+
+    @field_validator("start", "end")
+    def decode_datetime(cls, value: DateTime) -> DateTime:  # pylint: disable=no-self-argument
+        """Decode the datetime from an MMS-compliant ISO 8601 string."""
+        return value.replace(tzinfo=Timezone("Asia/Tokyo"))
+
+
+class SurplusCapacityData(SurplusCapacitySubmit, tag="RemainingReserveData"):
+    """Represents the base fields for a surplus capacity response."""
+
+    # The region in which the resource for which surplus capacity is being submitted is located
+    area: Optional[AreaCode] = attr(default=None, name="Area")
+
+    # The name of the BSP participant submitting the surplus capacity
+    participant: Optional[str] = participant("ParticipantName", True)
+
+    # The abbreviated name of the company submitting the surplus capacity
+    company: Optional[str] = company_short_name("CompanyShortName", True)
+
+    # The MMS code of the business entity to which the registration applies
+    system_code: Optional[str] = system_code("SystemCode", True)
+
+    # The abbreviated name of the resource being traded
+    resource_name: Optional[str] = resource_short_name("ResourceShortName", True)
+
+
+class SurplusCapacityQuery(Payload, tag="RemainingReserveDataQuery"):
+    """Represents the base fields for a surplus capacity query."""
+
+    # The name of the resource for which the surplus capacity is being submitted
+    resource_code: Optional[str] = resource_name("ResourceName", True)
+
+    # The DR pattern number for which the surplus capacity is being submitted
+    pattern_number: Optional[int] = attr(default=None, name="DrPatternNumber", ge=1, le=20)
+
+    # The start block from when the surplus capacity should apply
+    start: DateTime = attr(name="StartTime")
+
+    # The end block until when the surplus capacity should apply
+    end: DateTime = attr(name="EndTime")
+
+    @field_serializer("start", "end")
+    def encode_datetime(self, value: DateTime) -> str:
+        """Encode the datetime to an MMS-compliant ISO 8601 string."""
+        return value.replace(tzinfo=None).isoformat() if value else ""
+
+    @field_validator("start", "end")
+    def decode_datetime(cls, value: DateTime) -> DateTime:  # pylint: disable=no-self-argument
+        """Decode the datetime from an MMS-compliant ISO 8601 string."""
+        return value.replace(tzinfo=Timezone("Asia/Tokyo"))

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/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.
@@ -156,7 +161,8 @@ class Serializer:
         """
         # First, convert the payload to a raw XML string
         raw: bytes = payload.to_xml(
-            skip_empty=True,
+            exclude_none=True,
+            exclude_unset=True,
             encoding="utf-8",
             xml_declaration=False,
         )  # type: ignore[assignment]
@@ -170,10 +176,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 +193,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 +204,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 +221,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 +237,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 +247,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 +268,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 +287,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 +301,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.
 
@@ -299,8 +313,10 @@ 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__, "ProcessingStatistics", "Messages"]):
-            raise ValueError(f"Expected data type '{data_type.__name__}' not found in response")
+        if not data_tags.issubset(
+            [data_type.__name__, data_type.__xml_tag__, "ProcessingStatistics", "Messages", "StandingData"]
+        ):
+            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.

{mms_client-1.9.3.dist-info → mms_client-1.11.0.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: mms-client
-Version: 1.9.3
+Version: 1.11.0
 Summary: API client for accessing the MMS
 Home-page: https://github.com/ElectroRoute-Japan/mms-client
 Author: Ryan Wood
 Author-email: ryan.wood@electroroute.co.jp
-Requires-Python: >=3.11,<4.0
+Requires-Python: >=3.12,<4.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: Pydantic :: 2
 Classifier: Framework :: Pytest
@@ -14,8 +14,8 @@ Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: backoff (>=2.2.1,<3.0.0)
@@ -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`.
 
@@ -219,12 +221,17 @@ This client is not complete. Currently, it supports the following endpoints:
 - MarketQuery_OfferQuery
 - MarketCancel_OfferCancel
 - MarketQuery_AwardResultsQuery
+- MarketQuery_SettlementResultsFileListQuery
+- MarketSubmit_BupSubmit
+- MarketQuery_BupQuery
 - RegistrationSubmit_Resource
 - RegistrationQuery_Resource
 - ReportCreateRequest
 - ReportListRequest
 - ReportDownloadRequestTrnID
 - BSP_ResourceList
+- MarketSubmit_RemainingReserveData
+- MarketQuery_RemainingReserveDataQuery
 
 We can add support for additional endpoints as time goes on, and independent contribution is, of course, welcome. However, support for attachments is currently limited because none of the endpoints we support currently require them. We have implemented attachment support up to the client level, but we haven't developed an architecture for submitting them through an endpoint yet.