mms-client 1.0.6__py3-none-any.whl → 1.2.0__py3-none-any.whl

mms_client/services/base.py

@@ -10,6 +10,7 @@ from typing import Optional
 from typing import Protocol
 from typing import Tuple
 from typing import Type
+from typing import Union
 
 from mms_client.security.crypto import Certificate
 from mms_client.security.crypto import CryptoWrapper
@@ -119,7 +120,7 @@ class ClientProto(Protocol):
     def request_many(
         self,
         envelope: E,
-        data: P,
+        data: Union[P, List[P]],
         config: EndpointConfiguration,
     ) -> Tuple[MultiResponse[E, P], Dict[str, bytes]]:
         """Submit a request to the MMS server and return the multi-response.
@@ -361,7 +362,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
     def request_many(
         self,
         envelope: E,
-        payload: P,
+        payload: Union[P, List[P]],
         config: EndpointConfiguration[E, P],
     ) -> Tuple[MultiResponse[E, P], Dict[str, bytes]]:
         """Submit a request to the MMS server and return the multi-response.
@@ -374,13 +375,20 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         Returns:    The multi-response from the MMS server.
         """
         # First, create the MMS request from the payload and data.
+        is_list = isinstance(payload, list)
+        data_type = type(payload[0]) if is_list else type(payload)  # type: ignore[index]
         self._logger.debug(
             (
                 f"{config.name}: Starting multi-request. Envelope: {type(envelope).__name__}, "
-                f"Data: {type(payload).__name__}"
+                f"Data: {data_type.__name__}"
             ),
         )
-        request = self._to_mms_request(config.request_type, config.service.serializer.serialize(envelope, payload))
+        serialized = (
+            config.service.serializer.serialize_multi(envelope, payload, data_type)  # type: ignore[arg-type]
+            if is_list
+            else config.service.serializer.serialize(envelope, payload)  # type: ignore[type-var]
+        )
+        request = self._to_mms_request(config.request_type, serialized)
 
         # Next, submit the request to the MMS server and get and verify the response.
         resp = self._get_wrapper(config.service).submit(request)
@@ -391,8 +399,12 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
 
         # Finally, deserialize and verify the response
         envelope_type = config.response_envelope_type or type(envelope)
-        data_type = config.response_data_type or type(payload)
-        data: MultiResponse[E, P] = config.service.serializer.deserialize_multi(resp.payload, envelope_type, data_type)
+        data_type = config.response_data_type or data_type
+        data: MultiResponse[E, P] = config.service.serializer.deserialize_multi(
+            resp.payload,
+            envelope_type,
+            data_type,  # type: ignore[arg-type]
+        )
         self._verify_multi_response(data, config)
 
         # Return the response data and any attachments

mms_client/services/market.py

@@ -54,6 +54,32 @@ class MarketClientMixin:  # pylint: disable=unused-argument
             days=days,
         )
 
+    @mms_multi_endpoint("MarketSubmit_OfferData", config, RequestType.INFO, ClientType.BSP)
+    def put_offers(
+        self: ClientProto, requests: List[OfferData], market_type: MarketType, days: int, date: Optional[Date] = None
+    ) -> List[OfferData]:
+        """Submit multiple offers to the MMS server.
+
+        This endpoint is only accessible to BSPs.
+
+        Arguments:
+        requests (List[OfferData]): The offers to submit to the MMS server.
+        market_type (MarketType):   The type of market for which the offers are being submitted.
+        days (int):                 The number of days ahead for which the offers are being submitted.
+        date (Date):                The date of the transaction in the format "YYYY-MM-DD". This value defaults to the
+                                    current date.
+
+        Returns:    A list of offers that have been registered with the MMS server.
+        """
+        # Note: the return type does not match the method definition but the decorator will return the correct type
+        return MarketSubmit(  # type: ignore[return-value]
+            date=date or Date.today(),
+            participant=self.participant,
+            user=self.user,
+            market_type=market_type,
+            days=days,
+        )
+
     @mms_multi_endpoint(
         "MarketQuery_OfferQuery", config, RequestType.INFO, resp_envelope_type=MarketSubmit, resp_data_type=OfferData
     )

mms_client/services/registration.py

@@ -1,8 +1,23 @@
 """Contains the client layer for making registration requests to the MMS server."""
 
+from datetime import date as Date
+from typing import List
+from typing import Optional
+
+from mms_client.services.base import ClientProto
 from mms_client.services.base import ServiceConfiguration
+from mms_client.services.base import mms_endpoint
+from mms_client.services.base import mms_multi_endpoint
+from mms_client.types.registration import QueryAction
+from mms_client.types.registration import QueryType
+from mms_client.types.registration import RegistrationQuery
+from mms_client.types.registration import RegistrationSubmit
+from mms_client.types.resource import ResourceData
+from mms_client.types.resource import ResourceQuery
+from mms_client.types.transport import RequestType
 from mms_client.utils.serialization import SchemaType
 from mms_client.utils.serialization import Serializer
+from mms_client.utils.web import ClientType
 from mms_client.utils.web import Interface
 
 
@@ -11,3 +26,52 @@ class RegistrationClientMixin:  # pylint: disable=unused-argument
 
     # The configuration for the registration service
     config = ServiceConfiguration(Interface.MI, Serializer(SchemaType.REGISTRATION, "RegistrationData"))
+
+    @mms_endpoint("RegistrationSubmit_Resource", config, RequestType.REGISTRATION, ClientType.BSP)
+    def put_resource(self: ClientProto, request: ResourceData) -> ResourceData:
+        """Submit a new resource to the MMS server.
+
+        This endpoint is only accessible to BSPs.
+
+        Arguments:
+        request (ResourceData): The resource to register with the MMS server.
+
+        Returns:    The resource that has been registered with the MMS server.
+        """
+        # For some reason, the registration DTOs require that the participant ID exist on the payload rather than on
+        # the envelope so we need to set it before we return the envelope.
+        request.participant = self.participant
+
+        # Create and return the registration submit DTO.
+        return RegistrationSubmit()  # type: ignore[return-value]
+
+    @mms_multi_endpoint(
+        "RegistrationQuery_Resource",
+        config,
+        RequestType.REGISTRATION,
+        resp_envelope_type=RegistrationSubmit,
+        resp_data_type=ResourceData,
+    )
+    def query_resources(
+        self: ClientProto, request: ResourceQuery, action: QueryAction, date: Optional[Date] = None
+    ) -> List[ResourceData]:
+        """Query resources from the MMS server.
+
+        Arguments:
+        request (ResourceQuery):    The query to send to the MMS server.
+        action (QueryAction):       The type of query being made. NORMAL for all records or LATEST for the most recent.
+        date (Date):                The date of the transaction in the format "YYYY-MM-DD". This value defaults to the
+                                    current date.
+
+        Returns:    A list of resources that match the query.
+        """
+        # For some reason, the registration DTOs require that the participant ID exist on the payload rather than on
+        # the envelope so we need to set it before we return the envelope.
+        request.participant = self.participant
+
+        # Inject our parameters into the query and return it.
+        return RegistrationQuery(  # type: ignore[return-value]
+            action=action,
+            query_type=QueryType.TRADE,
+            date=date or Date.today(),
+        )

mms_client/types/base.py

@@ -14,6 +14,8 @@ from pydantic_xml import BaseXmlModel
 from pydantic_xml import attr
 from pydantic_xml import element
 
+from mms_client.types.fields import transaction_id
+
 
 class ValidationStatus(Enum):
     """Represents the status of the validation check done on an element."""
@@ -67,7 +69,7 @@ class ProcessingStatistics(BaseXmlModel):
     time_ms: Optional[int] = attr(default=None, name="ProcessingTimeMs")
 
     # The transaction ID of the request
-    transaction_id: Optional[str] = attr(default=None, name="TransactionID", min_length=8, max_length=10)
+    transaction_id: Optional[str] = transaction_id("TransactionId", True)
 
     # When the request was received, in the format "DDD MMM DD HH:MM:SS TZ YYYY"
     timestamp: str = attr(default="", name="TimeStamp")

mms_client/types/enums.py

@@ -1,6 +1,7 @@
 """Contains enums common to all MMS types."""
 
 from enum import Enum
+from enum import IntEnum
 
 
 class AreaCode(Enum):
@@ -16,3 +17,10 @@ class AreaCode(Enum):
     SHIKOKU = "08"
     KYUSHU = "09"
     OKINAWA = "10"
+
+
+class Frequency(IntEnum):
+    """Represents the frequency of power sources."""
+
+    EAST = 50
+    WEST = 60

mms_client/types/fields.py

@@ -4,7 +4,13 @@ from pydantic_core import PydanticUndefined
 from pydantic_xml import attr
 
 # Describes the regular expression required by the MMS API for Japanese text
-JAPANESE_TEXT = r"^[\u3000-\u30FF\uFF00-\uFF60\uFFA0-\uFFEF\u4E00-\u9FEA]*$"
+JAPANESE_TEXT = r"[\u3000-\u30FF\uFF00-\uFF60\uFFA0-\uFFEF\u4E00-\u9FEA]*"
+
+# Describes the regular expression required by the MMS API for ASCII text
+ASCII_TEXT = r"[a-zA-Z0-9 ~!@#$*()_+}{:?>`='/.,%;\^\|\-\]\[\\<&"]*"
+
+# Describes the regular expression required by the MMS API for Japanese or ASCII text
+JAPANESE_ASCII_TEXT = f"{JAPANESE_TEXT}|{ASCII_TEXT}"
 
 
 def participant(alias: str, optional: bool = False):
@@ -43,6 +49,41 @@ def operator_code(alias: str, optional: bool = False):
     )
 
 
+def transaction_id(alias: str, optional: bool = False):
+    """Create a field for a transaction ID.
+
+    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 transaction ID.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined,
+        name=alias,
+        min_length=8,
+        max_length=10,
+        pattern=r"^[a-zA-Z0-9]{8,10}$",
+    )
+
+
+def capacity(alias: str, minimum: int, optional: bool = False):
+    """Create a field for a capacity value.
+
+    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.
+    minimum (int):      The minimum value for the capacity field.
+    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 capacity value.
+    """
+    return attr(default=None if optional else PydanticUndefined, name=alias, ge=minimum, le=10000000)
+
+
 def power_positive(alias: str, optional: bool = False):
     """Create a field for a positive power value.
 
@@ -68,7 +109,21 @@ def price(alias: str, optional: bool = False):
 
     Returns:    A Pydantic Field object for the price value.
     """
-    return attr(default=None if optional else PydanticUndefined, name=alias, ge=0.00, le=10000.00, decimal_places=2)
+    return attr(default=None if optional else PydanticUndefined, name=alias, ge=0.00, lt=10000.00, decimal_places=2)
+
+
+def percentage(alias: str, optional: bool = False):
+    """Create a field for a percentage value.
+
+    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 percentage value.
+    """
+    return attr(default=None if optional else PydanticUndefined, name=alias, ge=0.0, le=100.0, decimal_places=1)
 
 
 def dr_patter_number(alias: str, optional: bool = False):
@@ -85,6 +140,22 @@ def dr_patter_number(alias: str, optional: bool = False):
     return attr(default=None if optional else PydanticUndefined, name=alias, ge=1, le=20)
 
 
+def pattern_name(alias: str, optional: bool = False):
+    """Create a field for a pattern 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 pattern name.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined, name=alias, min_length=1, max_length=20, pattern=JAPANESE_TEXT
+    )
+
+
 def company_short_name(alias: str, optional: bool = False):
     """Create a field for a company short name.
 
@@ -101,6 +172,44 @@ def company_short_name(alias: str, optional: bool = False):
     )
 
 
+def address(alias: str, optional: bool = False):
+    """Create a field for an address.
+
+    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 address.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined, name=alias, min_length=1, max_length=50, pattern=JAPANESE_TEXT
+    )
+
+
+def phone(alias: str, first_part: bool, optional: bool = False):
+    """Create a field for a phone number.
+
+    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.
+    first_part (bool):  If True, the field will be the first part of the phone number. If False, the field will be the
+                        second part of the phone number.
+    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 phone number.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined,
+        name=alias,
+        min_length=1,
+        max_length=5 if first_part else 4,
+        pattern=r"^[0-9]*$",
+    )
+
+
 def resource_name(alias: str, optional: bool = False):
     """Create a field for a resource name.
 
@@ -151,3 +260,42 @@ def system_code(alias: str, optional: bool = False):
     return attr(
         default=None if optional else PydanticUndefined, name=alias, min_length=5, max_length=5, pattern=r"^[A-Z0-9]*$"
     )
+
+
+def minute(alias: str, optional: bool = False):
+    """Create a field for a minute value.
+
+    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 minute value.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined,
+        name=alias,
+        ge=0,
+        le=99,
+    )
+
+
+def hour(alias: str, optional: bool = False):
+    """Create a field for an hour value.
+
+    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 hour value.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined,
+        name=alias,
+        ge=0.0,
+        lt=100.0,
+        decimal_places=1,
+    )

mms_client/types/offer.py

@@ -61,13 +61,24 @@ class OfferStack(Payload):
         mandatory.
     """
 
-    # A number used to identify this PQ pair within the offer
+    # A number used to identify this PQ pair within the offer. Ensure that there are no duplicates of the combination
+    # of the same resource, pattern number, start date and time, and bid management number in the submitted data. In
+    # case of multiple bids in the same time slot and for the same resource, each bid must have a unique number. Enter
+    # '1' for a single bid.
     number: int = attr(name="StackNumber", ge=1, le=20)
 
-    # The minimum quantity that must be provided before the offer can be awarded
+    # The minimum quantity that must be provided before the offer can be awarded. For resources with dedicated line
+    # control or monitoring methods, must be 5000kW or higher. For resources with simple command (online) control
+    # or monitoring methods, must be 1000kW or higher.
     minimum_quantity_kw: int = power_positive("MinimumQuantityInKw")
 
-    # The primary bid quantity in kW
+    # The primary bid quantity in kW. Must be equal to or greater than minimum_quantity_kw. For non-VPP resources, the
+    # total bid volume of all records with the same resource and start date and time must be below the maximum supply
+    # capacity for the corresponding product category of the power source. However, in the case of tertiary adjustment
+    # power 2, it must be the value obtained by subtracting the total agreed capacity of effective tertiary adjustment
+    # power 1. For VPP power sources, the total bid volume of all records with the same power source code and start
+    # date and time must be below the maximum supply capacity registered for the corresponding product category in the
+    # pattern number.
     primary_qty_kw: Optional[int] = power_positive("PrimaryOfferQuantityInKw", True)
 
     # The first secondary bid quantity in kW
@@ -107,7 +118,8 @@ class OfferData(Payload):
     # The direction of the offer (buy, sell)
     direction: Direction = attr(name="Direction")
 
-    # The type of market for which the offer is being submitted
+    # The type of market for which the offer is being submitted. Must be a valid pattern number for the submission date
+    # Required for VPP resources. Ensure there are no duplicate pattern numbers for the same resource and start time.
     pattern_number: Optional[int] = dr_patter_number("DrPatternNumber", True)
 
     # The name of the BSP participant submitting the offer

mms_client/types/registration.py

@@ -0,0 +1,47 @@
+"""Contains objects for registrations."""
+
+# Have to use this becasue pydantic doesn't like pendulum.Date. I've submitted a PR to address this but it hasn't been
+# merged or released yet.
+from datetime import date as Date
+from enum import Enum
+from typing import Optional
+
+from pydantic_xml import attr
+
+from mms_client.types.base import Envelope
+
+
+class QueryAction(Enum):
+    """Represents the type of query being made."""
+
+    NORMAL = "NORMAL"
+    LATEST = "LATEST"
+
+
+class QueryType(Enum):
+    """Represents the type of data being queried."""
+
+    TRADE = "TRADE"
+
+
+class RegistrationSubmit(Envelope):
+    """Represents the base fields for a registration request."""
+
+
+class RegistrationQuery(Envelope):
+    """Represents the base fields for a registration query."""
+
+    # The query type being made.
+    # NORMAL: Retrieve all records that match the specified conditions.
+    # LATEST: Retrieve only the latest record that matches the specified conditions.
+    action: QueryAction = attr(default=QueryAction.NORMAL, name="Action")
+
+    # The type of data being queried
+    query_type: QueryType = attr(default=QueryType.TRADE, name="DateType")
+
+    # Date of the transaction in the format "YYYY-MM-DD"
+    date: Optional[Date] = attr(default=None, name="Date")
+
+
+class RegistrationApproval(Envelope):
+    """Represents the base fields for a registration approval request."""