mms-client 1.0.5__py3-none-any.whl

mms_client/services/market.py

@@ -0,0 +1,107 @@
+"""Contains the client layer for making market 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.market import MarketCancel
+from mms_client.types.market import MarketQuery
+from mms_client.types.market import MarketSubmit
+from mms_client.types.market import MarketType
+from mms_client.types.offer import OfferCancel
+from mms_client.types.offer import OfferData
+from mms_client.types.offer import OfferQuery
+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
+
+
+class MarketClientMixin:  # pylint: disable=unused-argument
+    """Market client for the MMS server."""
+
+    # The configuration for the market service
+    config = ServiceConfiguration(Interface.MI, Serializer(SchemaType.MARKET, "MarketData"))
+
+    @mms_endpoint("MarketSubmit_OfferData", config, RequestType.INFO, ClientType.BSP)
+    def put_offer(
+        self: ClientProto, request: OfferData, market_type: MarketType, days: int, date: Optional[Date] = None
+    ) -> OfferData:
+        """Submit an offer to the MMS server.
+
+        This endpoint is only accessible to BSPs.
+
+        Arguments:
+        request (OfferData):        The offer to submit to the MMS server.
+        market_type (MarketType):   The type of market for which the offer is being submitted.
+        days (int):                 The number of days ahead for which the offer is being submitted.
+        date (Date):                The date of the transaction in the format "YYYY-MM-DD". This value defaults to the
+                                    current date.
+
+        Returns:    The offer that has 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
+    )
+    def query_offers(
+        self: ClientProto, request: OfferQuery, market_type: MarketType, days: int, date: Optional[Date] = None
+    ) -> List[OfferData]:
+        """Query the MMS server for offers.
+
+        This endpoint is accessible to all client types.
+
+        Arguments:
+        request (OfferQuery):       The query to submit to the MMS server.
+        market_type (MarketType):   The type of market for which the offer was submitted.
+        days (int):                 The number of days ahead for which the data is being queried.
+        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 match the query.
+        """
+        # Note: the return type does not match the method definition but the decorator will return the correct type
+        return MarketQuery(  # type: ignore[return-value]
+            date=date or Date.today(),
+            participant=self.participant,
+            user=self.user,
+            market_type=market_type,
+            days=days,
+        )
+
+    @mms_endpoint("MarketCancel_OfferCancel", config, RequestType.INFO, ClientType.BSP)
+    def cancel_offer(
+        self: ClientProto, request: OfferCancel, market_type: MarketType, days: int, date: Optional[Date] = None
+    ) -> OfferCancel:
+        """Cancel an offer in the MMS server.
+
+        This endpoint is only accessible to BSPs.
+
+        Arguments:
+        request (OfferCancel):      The offer to cancel in the MMS server.
+        market_type (MarketType):   The type of market for which the offer was submitted.
+        days (int):                 The number of days ahead for which the data is being cancelled.
+        date (Date):                The date of the transaction in the format "YYYY-MM-DD". This value defaults to the
+                                    current date.
+        """
+        # Note: the return type does not match the method definition but the decorator will return the correct type
+        return MarketCancel(  # type: ignore[return-value]
+            date=date or Date.today(),
+            participant=self.participant,
+            user=self.user,
+            market_type=market_type,
+            days=days,
+        )

mms_client/services/omi.py

@@ -0,0 +1,13 @@
+"""Contains the client layer for making OMI requests to the MMS server."""
+
+from mms_client.services.base import ServiceConfiguration
+from mms_client.utils.serialization import SchemaType
+from mms_client.utils.serialization import Serializer
+from mms_client.utils.web import Interface
+
+
+class OMIClientMixin:  # pylint: disable=unused-argument
+    """OMI client for the MMS server."""
+
+    # The configuration for the OMI service
+    config = ServiceConfiguration(Interface.OMI, Serializer(SchemaType.OMI, "MarketData"))

mms_client/services/registration.py

@@ -0,0 +1,13 @@
+"""Contains the client layer for making registration requests to the MMS server."""
+
+from mms_client.services.base import ServiceConfiguration
+from mms_client.utils.serialization import SchemaType
+from mms_client.utils.serialization import Serializer
+from mms_client.utils.web import Interface
+
+
+class RegistrationClientMixin:  # pylint: disable=unused-argument
+    """Registration client for the MMS server."""
+
+    # The configuration for the registration service
+    config = ServiceConfiguration(Interface.MI, Serializer(SchemaType.REGISTRATION, "RegistrationData"))

mms_client/services/report.py

@@ -0,0 +1,13 @@
+"""Contains the client layer for making report requests to the MMS server."""
+
+from mms_client.services.base import ServiceConfiguration
+from mms_client.utils.serialization import SchemaType
+from mms_client.utils.serialization import Serializer
+from mms_client.utils.web import Interface
+
+
+class ReportClientMixin:  # pylint: disable=unused-argument
+    """Report client for the MMS server."""
+
+    # The configuration for the report service
+    config = ServiceConfiguration(Interface.MI, Serializer(SchemaType.REPORT, "MarketReport"))

mms_client/types/base.py

@@ -0,0 +1,272 @@
+"""Contains the base types necessary for communication with the MMS server."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict
+from typing import Generic
+from typing import List
+from typing import Optional
+from typing import TypeVar
+
+from pydantic import PrivateAttr
+from pydantic_extra_types.pendulum_dt import DateTime
+from pydantic_xml import BaseXmlModel
+from pydantic_xml import attr
+from pydantic_xml import element
+
+
+class ValidationStatus(Enum):
+    """Represents the status of the validation check done on an element."""
+
+    PASSED = "PASSED"  # The validation check for all data within the element has succeeded.
+    WARNING = "WARNING"  # There are data within the element that have triggered warnings during the validation check.
+    PASSED_PARTIAL = "PASSED_PARTIAL"  # Some data within the element has failed the validation check.
+    FAILED = "FAILED"  # The data inside the element failed the validation check.
+    NOT_DONE = "NOT_DONE"  # There are data with incomplete validation checks within the element.
+
+
+class Message(BaseXmlModel):
+    """Represents a message returned with a payload."""
+
+    # 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\-]*$")
+
+
+class Messages(BaseXmlModel, search_mode="unordered"):
+    """Represents a collection of messages returned with a payload."""
+
+    # A list of information messages returned with a payload
+    information: List[Message] = element(default=[], tag="Information", nillable=True)
+
+    # A list of warning messages returned with a payload
+    warnings: List[Message] = element(default=[], tag="Warning", nillable=True)
+
+    # A list of error messages returned with a payload
+    errors: List[Message] = element(default=[], tag="Error", nillable=True)
+
+
+class ProcessingStatistics(BaseXmlModel):
+    """Represents the statistics returned with a payload."""
+
+    # The number of objects received with the request
+    received: Optional[int] = attr(default=None, name="Received")
+
+    # The number of objects that passed validation
+    valid: Optional[int] = attr(default=None, name="Valid")
+
+    # The number of objects that failed validation
+    invalid: Optional[int] = attr(default=None, name="Invalid")
+
+    # The number of objects that were successfully processed
+    successful: Optional[int] = attr(default=None, name="Successful")
+
+    # The number of objects that were unsuccessfully processed
+    unsuccessful: Optional[int] = attr(default=None, name="Unsuccessful")
+
+    # The amount of time it took to process the request in milliseconds
+    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)
+
+    # When the request was received, in the format "DDD MMM DD HH:MM:SS TZ YYYY"
+    timestamp: str = attr(default="", name="TimeStamp")
+
+    # When the request was received, in the format "YYYY-MM-DD HH:MM:SSZ"
+    timestamp_xml: Optional[DateTime] = attr(default=None, name="XmlTimeStamp")
+
+
+class ResponseCommon(BaseXmlModel, search_mode="unordered"):
+    """Contains fields common to many (but not all) market DTOs."""
+
+    # Whether the request was successful. This field will certainly be present in responses, but should not be present
+    # in requests.
+    success: bool = attr(default=True, name="Success")
+
+    # The status of the validation check done on the element. This field is not required for requests, and will be
+    # populated in responses. For responses, the default value is "NOT_DONE".
+    validation: ValidationStatus = attr(default=ValidationStatus.NOT_DONE, name="Validation")
+
+
+class Payload(BaseXmlModel, search_mode="unordered"):
+    """Represents the base fields for MMS request data."""
+
+
+# Define a generic type used to identify the data type. This type will be used to create the MarketData class.
+P = TypeVar("P", bound=Payload)
+
+
+class Envelope(BaseXmlModel):
+    """Represents the base fields for an MMS request data envelope."""
+
+
+# Define a generic type used to identify the payload type. This type will be used to create the MarketData class.
+E = TypeVar("E", bound=Envelope)
+
+
+class SchemaType(Enum):
+    """Represents the type of schema to be used for validation."""
+
+    MARKET = "mi-market.xsd"
+    REPORT = "mi-report.xsd"
+    REGISTRATION = "mpr.xsd"
+    OMI = "omi.xsd"
+
+
+class PayloadBase(BaseXmlModel, nsmap={"xsi": "http://www.w3.org/2001/XMLSchema"}):
+    """Represents the base fields for an MMS request payload."""
+
+    # The XML schema to use for validation
+    location: SchemaType = attr(name="noNamespaceSchemaLocation", ns="xsi")
+
+
+class BaseResponse(BaseXmlModel, Generic[E], tag="BaseResponse"):
+    """Contains the base data extracted from the MMS response in a format we can use."""
+
+    # The processing statistics returned with the payload. This will not be present in requests, and will be populated
+    # in responses.
+    statistics: ProcessingStatistics = element(tag="ProcessingStatistics")
+
+    # The request payload, containing the request data
+    _envelope: E = PrivateAttr()
+
+    # The validation information for the request payload
+    _envelope_validation: ResponseCommon = PrivateAttr()
+
+    # The messages returned with the payload. Each object will likely have its own so these
+    # will be parsed separately.
+    _messages: Dict[str, Messages] = PrivateAttr()
+
+    def __init__(self, **data):
+        """Create a new BaseResponse object.
+
+        Arguments:
+        **data:    The data to use to create the object.
+        """
+        super().__init__(**data)
+        self._envelope = None
+        self._envelope_validation = None
+        self._messages = {}
+
+    @property
+    def envelope(self) -> E:
+        """Return the request payload."""
+        return self._envelope
+
+    @envelope.setter
+    def envelope(self, value: E) -> None:
+        """Set the request payload.
+
+        Arguments:
+        value (E):    The request payload.
+        """
+        self._envelope = value
+
+    @property
+    def envelope_validation(self) -> ResponseCommon:
+        """Return the validation information for the request payload."""
+        return self._envelope_validation
+
+    @envelope_validation.setter
+    def envelope_validation(self, value: ResponseCommon) -> None:
+        """Set the validation information for the request payload.
+
+        Arguments:
+        value (ResponseCommon):    The validation information for the request payload.
+        """
+        self._envelope_validation = value
+
+    @property
+    def messages(self) -> Dict[str, Messages]:
+        """Return the messages returned with the payload."""
+        return self._messages
+
+    @messages.setter
+    def messages(self, value: Dict[str, Messages]) -> None:
+        """Set the messages returned with the payload.
+
+        Arguments:
+        value (Dict[str, Messages]):    The messages returned with the payload.
+        """
+        self._messages = value
+
+
+@dataclass
+class ResponseData(Generic[P]):
+    """Contains the actual payload data extracted from the MMS response in a format we can use."""
+
+    # The data extracted from the response
+    data: P
+
+    # The validation information for the data extracted from the response
+    data_validation: ResponseCommon
+
+
+class Response(BaseResponse[E], Generic[E, P]):
+    """Contains all the data extracted from the MMS response in a format we can use."""
+
+    # The payload data extracted from the response
+    _payload_data: Optional[ResponseData[P]] = PrivateAttr()
+
+    def __init__(self, **data):
+        """Create a new Response object.
+
+        Arguments:
+        **data:    The data to use to create the object.
+        """
+        super().__init__(**data)
+        self._payload_data = None
+
+    @property
+    def data(self) -> Optional[P]:
+        """Return the data extracted from the response."""
+        return self._payload_data.data if self._payload_data else None  # pylint: disable=no-member
+
+    @property
+    def payload(self) -> Optional[ResponseData[P]]:
+        """Return the response payload."""
+        return self._payload_data
+
+    @payload.setter
+    def payload(self, value: Optional[ResponseData[P]]) -> None:
+        """Set the payload extracted from the response.
+
+        Arguments:
+        value (ResponseData[P]):    The payload extracted from the response.
+        """
+        self._payload_data = value
+
+
+class MultiResponse(BaseResponse[E], Generic[E, P]):
+    """Contains all the data extracted from the MMS response in a format we can use."""
+
+    # The payload data extracted from the response
+    _payload_data: List[ResponseData[P]] = PrivateAttr()
+
+    def __init__(self, **data):
+        """Create a new MultiResponse object.
+
+        Arguments:
+        **data:    The data to use to create the object.
+        """
+        super().__init__(**data)
+        self._payload_data = []
+
+    @property
+    def data(self) -> List[P]:
+        """Return the data extracted from the response."""
+        return [response.data for response in self._payload_data]  # pylint: disable=not-an-iterable
+
+    @property
+    def payload(self) -> List[ResponseData[P]]:
+        """Return the response payload."""
+        return self._payload_data
+
+    @payload.setter
+    def payload(self, values: List[Optional[ResponseData[P]]]) -> None:
+        """Set the payload extracted from the response.
+
+        Arguments:
+        values (List[ResponseData[P]]): The payload extracted from the response.
+        """
+        self._payload_data = [value for value in values if value]

mms_client/types/enums.py

@@ -0,0 +1,18 @@
+"""Contains enums common to all MMS types."""
+
+from enum import Enum
+
+
+class AreaCode(Enum):
+    """Represents the area code of the market."""
+
+    HOKKAIDO = "01"
+    TOHOKU = "02"
+    TOKYO = "03"
+    CHUBU = "04"
+    HOKURIKU = "05"
+    KANSAI = "06"
+    CHUGOKU = "07"
+    SHIKOKU = "08"
+    KYUSHU = "09"
+    OKINAWA = "10"

mms_client/types/fields.py

@@ -0,0 +1,153 @@
+"""Contains the definitions for various fields used in the MMS API."""
+
+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]*$"
+
+
+def participant(alias: str, optional: bool = False):
+    """Create a field for a participant 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 participant ID.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined,
+        name=alias,
+        min_length=4,
+        max_length=4,
+        pattern=r"^[A-Z]([0-9]{2}[1-9]|[0-9][1-9][0-9]|[1-9][0-9]{2})$",
+    )
+
+
+def operator_code(alias: str, optional: bool = False):
+    """Create a field for an operator code.
+
+    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 operator code.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined, name=alias, min_length=4, max_length=4, pattern=r"^[A-Z0-9]*$"
+    )
+
+
+def power_positive(alias: str, optional: bool = False):
+    """Create a field for a positive power 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 power value.
+    """
+    return attr(default=None if optional else PydanticUndefined, name=alias, gt=0, le=10000000)
+
+
+def price(alias: str, optional: bool = False):
+    """Create a field for a price 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 price value.
+    """
+    return attr(default=None if optional else PydanticUndefined, name=alias, ge=0.00, le=10000.00, decimal_places=2)
+
+
+def dr_patter_number(alias: str, optional: bool = False):
+    """Create a field for a DR pattern 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.
+    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 DR pattern number.
+    """
+    return attr(default=None if optional else PydanticUndefined, name=alias, ge=1, le=20)
+
+
+def company_short_name(alias: str, optional: bool = False):
+    """Create a field for a company short 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 company short name.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined, name=alias, min_length=1, max_length=10, pattern=JAPANESE_TEXT
+    )
+
+
+def resource_name(alias: str, optional: bool = False):
+    """Create a field for a resource 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 resource name.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined,
+        name=alias,
+        min_length=1,
+        max_length=10,
+        pattern=r"^[A-Z0-9_\-]*$",
+    )
+
+
+def resource_short_name(alias: str, optional: bool = False):
+    """Create a field for a resource short 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 resource short name.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined, name=alias, min_length=1, max_length=10, pattern=JAPANESE_TEXT
+    )
+
+
+def system_code(alias: str, optional: bool = False):
+    """Create a field for a system code.
+
+    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 system code.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined, name=alias, min_length=5, max_length=5, pattern=r"^[A-Z0-9]*$"
+    )

mms_client/types/market.py

@@ -0,0 +1,61 @@
+"""Contains objects for market information."""
+
+# 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
+from mms_client.types.fields import participant
+
+
+class MarketType(Enum):
+    """Represents the type of market for which the data is being submitted."""
+
+    DAY_AHEAD = "DAM"
+    WEEK_AHEAD = "WAM"
+
+
+class BaseMarketRequest(Envelope):
+    """Represents the header of a market 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]*$")
+
+    # The type of market for which the data is being submitted
+    market_type: Optional[MarketType] = attr(default=None, name="MarketType")
+
+
+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)
+
+
+class MarketSubmit(BaseMarketRequest):
+    """Represents the base fields for a market registration request."""
+
+    # 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)
+
+
+class MarketCancel(BaseMarketRequest):
+    """Represents the base fields for a market cancellation request."""
+
+    # 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 cancelled.
+    days: int = attr(default=1, name="NumOfDays", ge=1, le=31)