mms-client 1.0.5__py3-none-any.whl

mms_client/types/offer.py

@@ -0,0 +1,163 @@
+"""Contains objects for MMS offers."""
+
+from decimal import Decimal
+from enum import Enum
+from typing import List
+from typing import Optional
+
+from pydantic_core import PydanticUndefined
+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.enums import AreaCode
+from mms_client.types.fields import company_short_name
+from mms_client.types.fields import dr_patter_number
+from mms_client.types.fields import operator_code
+from mms_client.types.fields import participant
+from mms_client.types.fields import power_positive
+from mms_client.types.fields import price
+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
+from mms_client.types.market import MarketType
+
+
+def offer_id(alias: str, optional: bool = False):
+    """Create a field for an offer 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 offer ID.
+    """
+    return attr(
+        default=None if optional else PydanticUndefined,
+        name=alias,
+        min_length=1,
+        max_length=30,
+        pattern=r"^[a-zA-Z0-9_-]*$",
+    )
+
+
+class Direction(Enum):
+    """Represents the reserve direction of the offer."""
+
+    SELL = "1"  # Increasing the reserves (sell)
+    # Note: Support for the BUY direction was removed from the MMS API
+    # BUY = "2"  # Decreasing the reserves (buy)
+
+
+class OfferStack(Payload):
+    """Represents a single price-quantity pair in an offer request.
+
+    Notes:
+        For the Day-ahead Market, the tertiary 2 sell bidding volume is mandatory.
+        For the Week-ahead Market, one of primary, secondary 1, secondary 2, or tertiary 1 sell bidding volumes are
+        mandatory.
+    """
+
+    # A number used to identify this PQ pair within the offer
+    number: int = attr(name="StackNumber", ge=1, le=20)
+
+    # The minimum quantity that must be provided before the offer can be awarded
+    minimum_quantity_kw: int = power_positive("MinimumQuantityInKw")
+
+    # The primary bid quantity in kW
+    primary_qty_kw: Optional[int] = power_positive("PrimaryOfferQuantityInKw", True)
+
+    # The first secondary bid quantity in kW
+    secondary_1_qty_kw: Optional[int] = power_positive("Secondary1OfferQuantityInKw", True)
+
+    # The second secondary bid quantity in kW
+    secondary_2_qty_kw: Optional[int] = power_positive("Secondary2OfferQuantityInKw", True)
+
+    # The first tertiary bid quantity in kW
+    tertiary_1_qty_kw: Optional[int] = power_positive("Tertiary1OfferQuantityInKw", True)
+
+    # The second tertiary bid quantity in kW.
+    tertiary_2_qty_kw: Optional[int] = power_positive("Tertiary2OfferQuantityInKw", True)
+
+    # The unit price of the power, in JPY/kW/segment
+    unit_price: Decimal = price("OfferUnitPrice")
+
+    # The ID of the offer to which this stack belongs
+    id: Optional[str] = offer_id("OfferId", True)
+
+
+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)
+
+    # The identifier for the power resource being traded
+    resource: str = resource_name("ResourceName")
+
+    # Date and time of the starting block associated with the offer
+    start: DateTime = attr(name="StartTime")
+
+    # Date and time of the ending block associated with the offer
+    end: DateTime = attr(name="EndTime")
+
+    # The direction of the offer (buy, sell)
+    direction: Direction = attr(name="Direction")
+
+    # The type of market for which the offer is being submitted
+    pattern_number: Optional[int] = dr_patter_number("DrPatternNumber", True)
+
+    # The name of the BSP participant submitting the offer
+    bsp_participant: Optional[str] = participant("BspParticipantName", True)
+
+    # The abbreviated name of the counterparty
+    company_short_name: Optional[str] = company_short_name("CompanyShortName", True)
+
+    # A code identifying the TSO or MO
+    operator: Optional[str] = operator_code("OperatorCode", True)
+
+    # The area associated with the offer
+    area: Optional[AreaCode] = attr(default=None, name="Area")
+
+    # The abbreviated name of the resource being traded
+    resource_short_name: Optional[str] = resource_short_name("ResourceShortName", True)
+
+    # The grid code of the resource being traded
+    system_code: Optional[str] = system_code("SystemCode", True)
+
+    # The date and time when the offer was submitted
+    submission_time: Optional[DateTime] = attr(default=None, name="SubmissionTime")
+
+
+class OfferCancel(Payload):
+    """Describes the data necessary to cancel an offer in the MMS."""
+
+    # The identifier for the power resource this offer is trading on
+    resource: str = resource_name("ResourceName")
+
+    # The date and time of the starting block associated with the offer
+    start: DateTime = attr(name="StartTime")
+
+    # The date and time of the ending block associated with the offer. You can cancel multiple blocks by specifying the
+    # end date and time for any block within the period from the trading day to the specified number of days.
+    end: DateTime = attr(name="EndTime")
+
+    # The type of market for the offer was submitted on
+    market_type: MarketType = attr(name="MarketType")
+
+
+class OfferQuery(Payload):
+    """Describes the data necessary to query for offers in the MMS."""
+
+    # The type of market for the offer was submitted on
+    market_type: MarketType = attr(name="MarketType")
+
+    # The identifier for the power resource being requested. If this isn't provided, then all offers for the specified
+    # region will be returned
+    resource: Optional[str] = resource_name("ResourceName", True)
+
+    # The area associated with the offer. For TSOs and MOs, this field is mandatory
+    area: Optional[AreaCode] = attr(default=None, name="Area")

mms_client/types/transport.py

@@ -0,0 +1,130 @@
+"""Contains the base types necessary for communication with the MMS server."""
+
+from enum import Enum
+from typing import List
+from typing import Optional
+
+from pydantic import BaseModel
+from pydantic import Field
+
+
+class RequestType(Enum):
+    """Represents the type of request to be sent to the MMS server.
+
+    Note that the first four items are valid for the Market Initiator (MI) interface, while the last item is valid for
+    the Other Market Initiator (OMI) interface.
+    """
+
+    INFO = "mp.info"
+    MARKET = "mp.market"
+    REGISTRATION = "mp.registration"
+    REPORT = "mp.report"
+    OMI = "mp.omi"
+
+
+class RequestDataType(Enum):
+    """Represents the type of data to be sent to the MMS server.
+
+    Note that JSON is currently not supported and has been left in for future use.
+    """
+
+    JSON = "JSON"
+    XML = "XML"
+
+
+class ResponseDataType(Enum):
+    """Represents the type of data to be received from the MMS server.
+
+    Note that JSON is currently not supported and has been left in for future use.
+    """
+
+    XML = "XML"
+    HTML = "HTML"
+    CSV = "CSV"
+    JSON = "JSON"
+    TXT = "TXT"
+
+
+class Attachment(BaseModel):
+    """Represents a file attachment to be sent with a request or response."""
+
+    # The signature used to encrypt the attachment
+    signature: str = Field(alias="signature")
+
+    # The name of the attachment file
+    name: str = Field(alias="name")
+
+    # The attachment file data
+    data: bytes = Field(alias="binaryData")
+
+
+class MmsRequest(BaseModel):
+    """Base class for all MMS requests."""
+
+    # The API subsystem to which the request is sent.
+    subsystem: RequestType = Field(alias="requestType")
+
+    # Whether the request is being made as the market operator
+    as_admin: bool = Field(default=False, alias="adminRole")
+
+    # Whether the request data is compressed (for future use only)
+    compressed: bool = Field(default=False, alias="requestDataCompressed")
+
+    # The type of data to be sent to the MMS server.
+    data_type: RequestDataType = Field(alias="requestDataType")
+
+    # Whether to send the request data in the response, on a successful request
+    respond_with_request: bool = Field(default=True, alias="sendRequestDataOnSuccess")
+
+    # Wether the response data should be compressed (for future use only)
+    response_compressed: bool = Field(default=False, alias="sendResponseDataCompressed")
+
+    # The signature used to encrypt the request payload
+    signature: str = Field(alias="requestSignature")
+
+    # The base-64 encoded payload of the request
+    payload: bytes = Field(alias="requestData")
+
+    # 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")
+
+    def to_arguments(self) -> dict:
+        """Convert the request to a dictionary of arguments for use in the MMS client."""
+        # First, convert the type to a dictionary format
+        converted = self.model_dump(by_alias=True)
+
+        # Next, convert the enum types to their string representations
+        converted["requestType"] = converted["requestType"].value
+        converted["requestDataType"] = converted["requestDataType"].value
+
+        # Finally, return the converted dictionary
+        return converted
+
+
+class MmsResponse(BaseModel):
+    """Base class for all MMS responses."""
+
+    # Whether the request was successful
+    success: bool = Field(alias="success")
+
+    # Whether there were any warnings. This field will only be present if the request was successful.
+    warnings: bool = Field(default=False, alias="warnings")
+
+    # Whether the response is binary data.
+    is_binary: bool = Field(default=False, alias="responseBinary")
+
+    # Whether the response data is compressed (for future use only)
+    compressed: bool = Field(default=False, alias="responseCompressed")
+
+    # The type of data to be received from the MMS server.
+    data_type: ResponseDataType = Field(alias="responseDataType")
+
+    # The filename assigned to the response (for pre-generated reports)
+    report_filename: Optional[str] = Field(default=None, alias="responseFilename")
+
+    # The base-64 encoded payload of the response
+    payload: bytes = Field(alias="responseData")
+
+    # Any attached files to be sent with the response
+    attachments: List[Attachment] = Field(default=[], alias="attachmentData")

mms_client/utils/errors.py

@@ -0,0 +1,66 @@
+"""Contains error classes for the MMS client."""
+
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Union
+
+from mms_client.types.base import E
+from mms_client.types.base import Messages
+from mms_client.types.base import P
+from mms_client.utils.web import ClientType
+
+
+class AudienceError(ValueError):
+    """Error raised when an invalid audience is provided."""
+
+    def __init__(self, method: str, allowed: ClientType, audience: ClientType):
+        """Initialize the error.
+
+        Arguments:
+        method (str):   The method that caused the error.
+        allowed (str):  The allowed audience.
+        audience (str): The invalid audience.
+        """
+        self.method = method
+        self.message = f"{method}: Invalid client type, '{audience.name}' provided. Only '{allowed.name}' is supported."
+        self.allowed = allowed
+        self.audience = audience
+        super().__init__(self.message)
+
+
+class MMSClientError(RuntimeError):
+    """Base class for MMS client errors."""
+
+    def __init__(self, method: str, message: str):
+        """Initialize the error.
+
+        Arguments:
+        method (str):   The method that caused the error.
+        message (str):  The error message.
+        """
+        super().__init__(f"{method}: {message}")
+        self.message = message
+        self.method = method
+
+
+class MMSValidationError(RuntimeError):
+    """Error raised when a request fails validation."""
+
+    def __init__(self, method: str, envelope: E, request: Optional[Union[P, List[P]]], messages: Dict[str, Messages]):
+        """Initialize the validation error.
+
+        Arguments:
+        method (str):                   The method that caused the error.
+        message (str):                  The error message.
+        envelope (E):                   The request envelope.
+        request (P):                    The request data.
+        messages (Dict[str, Messages]): The messages returned with the payload.
+        """
+        self.message = (
+            f"{method}: Request of type {type(envelope).__name__} containing data {type(request).__name__} "
+            f"failed validation. See the logs for more information."
+        )
+        self.method = method
+        self.messages = messages
+        super().__init__(self.message)