mms-client 1.4.0__tar.gz → 1.4.1__tar.gz

{mms_client-1.4.0 → mms_client-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mms-client
-Version: 1.4.0
+Version: 1.4.1
 Summary: API client for accessing the MMS
 Home-page: https://github.com/ElectroRoute-Japan/mms-client
 Author: Ryan Wood
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 [![Unit Tests Status](https://github.com/ElectroRoute-Japan/mms-client/actions/workflows/check.yml/badge.svg)](https://github.com/ElectroRoute-Japan/mms-client/actions)
 
 # Overview
-This repository contains a Python client that is capable of communication with the Market Management System (MMS), which handles requests related to Flex or Virtual Power Plant (VPP) trading. The underlying library is relies on SOAP communication, which is a pain to work with at the best of times. This particular SOAP API adds its own special layer of obnoxiousness, however. As such, it was deemed useful to have a client which would obfuscate most, if not all of this away from the user.
+This repository contains a Python client that is capable of communication with the Market Management System (MMS), which handles requests related to Flex or Virtual Power Plant (VPP) trading. The underlying library relies on SOAP communication, which is a pain to work with at the best of times. This particular SOAP API adds its own special layer of obnoxiousness, however. As such, it was deemed useful to have a client which would obfuscate most, if not all of this away from the user.
 
 # Communication
 The underlying API sends and receives XML documents. Each of these request or responses, which we will hereafter refer to as *outer* requests and responses, contains metadata about the request/response as well as three fields which are extremely important to successful communication with the API:
@@ -47,7 +47,9 @@ After the data has been converted and added to the outer request object, it is s
 This library relies on Pydantic 2 and the pydantic-xml library for serialization/deserialization. As such, any type in this library can be converted to not only XML, but to JSON as well. This is extremely useful if you're trying to build a pass-through API service or something similar.
 
 ## Client Types
-Clients cannot call any and all endpoints in this API, willy-nilly. Some endpoints are restricted to particular clients. At the moment, there are two clients: Balance Service Providers (BSPs) and Transmission Service Operators (TSOs). Most likely you're operating as a BSP, in which case you'll have access to all endpoints. However, it makes little sense for a TSO to be able to submit bids on their own power, so they are restricted to a read-only role in most cases.
+Clients cannot call any and all endpoints in this API, willy-nilly. Some endpoints are restricted to particular clients. At the moment, there are three clients: Balance Service Providers (BSPs), Market Operators (MOs), and Transmission Service Operators (TSOs). Most likely you're operating as a BSP or MO, in which case you'll have access to most or all endpoints. However, it makes little sense for a TSO to be able to submit bids on their own power, so they are restricted to a read-only role in most cases.
+
+Note that MOs and BSPs access the MMS service using the same endpoints, but have distinct permissions. As such, both client types are supported explicitly here.
 
 Should you request an endpoint which you are not authorized for, you will receive an `mms_client.utils.errors.AudienceError`.
 

{mms_client-1.4.0 → mms_client-1.4.1}/README.md

@@ -1,7 +1,7 @@
 [![Unit Tests Status](https://github.com/ElectroRoute-Japan/mms-client/actions/workflows/check.yml/badge.svg)](https://github.com/ElectroRoute-Japan/mms-client/actions)
 
 # Overview
-This repository contains a Python client that is capable of communication with the Market Management System (MMS), which handles requests related to Flex or Virtual Power Plant (VPP) trading. The underlying library is relies on SOAP communication, which is a pain to work with at the best of times. This particular SOAP API adds its own special layer of obnoxiousness, however. As such, it was deemed useful to have a client which would obfuscate most, if not all of this away from the user.
+This repository contains a Python client that is capable of communication with the Market Management System (MMS), which handles requests related to Flex or Virtual Power Plant (VPP) trading. The underlying library relies on SOAP communication, which is a pain to work with at the best of times. This particular SOAP API adds its own special layer of obnoxiousness, however. As such, it was deemed useful to have a client which would obfuscate most, if not all of this away from the user.
 
 # Communication
 The underlying API sends and receives XML documents. Each of these request or responses, which we will hereafter refer to as *outer* requests and responses, contains metadata about the request/response as well as three fields which are extremely important to successful communication with the API:
@@ -15,7 +15,9 @@ After the data has been converted and added to the outer request object, it is s
 This library relies on Pydantic 2 and the pydantic-xml library for serialization/deserialization. As such, any type in this library can be converted to not only XML, but to JSON as well. This is extremely useful if you're trying to build a pass-through API service or something similar.
 
 ## Client Types
-Clients cannot call any and all endpoints in this API, willy-nilly. Some endpoints are restricted to particular clients. At the moment, there are two clients: Balance Service Providers (BSPs) and Transmission Service Operators (TSOs). Most likely you're operating as a BSP, in which case you'll have access to all endpoints. However, it makes little sense for a TSO to be able to submit bids on their own power, so they are restricted to a read-only role in most cases.
+Clients cannot call any and all endpoints in this API, willy-nilly. Some endpoints are restricted to particular clients. At the moment, there are three clients: Balance Service Providers (BSPs), Market Operators (MOs), and Transmission Service Operators (TSOs). Most likely you're operating as a BSP or MO, in which case you'll have access to most or all endpoints. However, it makes little sense for a TSO to be able to submit bids on their own power, so they are restricted to a read-only role in most cases.
+
+Note that MOs and BSPs access the MMS service using the same endpoints, but have distinct permissions. As such, both client types are supported explicitly here.
 
 Should you request an endpoint which you are not authorized for, you will receive an `mms_client.utils.errors.AudienceError`.
 

{mms_client-1.4.0 → mms_client-1.4.1}/pyproject.toml

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

{mms_client-1.4.0 → mms_client-1.4.1}/src/mms_client/services/base.py

@@ -59,7 +59,7 @@ class EndpointConfiguration(Generic[E, P]):
     name: str
 
     # The allowed client types for the endpoint
-    allowed_client: Optional[ClientType]
+    allowed_clients: Optional[List[ClientType]]
 
     # The service for the endpoint
     service: ServiceConfiguration
@@ -139,7 +139,7 @@ def mms_endpoint(
     name: str,
     service: ServiceConfiguration,
     request_type: RequestType,
-    allowed_client: Optional[ClientType] = None,
+    allowed_clients: Optional[List[ClientType]] = None,
     resp_envelope_type: Optional[Type[E]] = None,
     resp_data_type: Optional[Type[P]] = None,
 ):
@@ -150,18 +150,18 @@ def mms_endpoint(
     Decorated functions will only be responsible for creating the payload envelope to submit to the MMS server.
 
     Arguments:
-    name (str):                     The name of the endpoint.
-    service (ServiceConfiguration): The configuration for the service.
-    request_type (RequestType):     The type of request to submit to the MMS server.
-    allowed_client (ClientType):    The type of client that is allowed to access the endpoint. If this is not provided,
-                                    then any client type is allowed.
-    resp_envelope_type (Type[E]):   The type of payload to expect in the response. If this is not provided, then the
-                                    the response envelope will be assumed to have the same type as the request envelope.
-    resp_data_type (Type[P]):       The type of data to expect in the response. If this is not provided, then the
-                                    response data will be assumed to have the same type as the request data.
+    name (str):                         The name of the endpoint.
+    service (ServiceConfiguration):     The configuration for the service.
+    request_type (RequestType):         The type of request to submit to the MMS server.
+    allowed_clients (List[ClientType]): The types of clients that are allowed to access the endpoint. If this is not
+                                        provided, then any client will be allowed.
+    resp_envelope_type (Type[E]):       The type of payload to expect in the response. If this is not provided, then the
+                                        response envelope will be assumed to have the same type as the request envelope.
+    resp_data_type (Type[P]):           The type of data to expect in the response. If this is not provided, then the
+                                        response data will be assumed to have the same type as the request data.
     """
     # First, create the endpoint configuration from the given parameters
-    config = EndpointConfiguration(name, allowed_client, service, request_type, resp_envelope_type, resp_data_type)
+    config = EndpointConfiguration(name, allowed_clients, service, request_type, resp_envelope_type, resp_data_type)
 
     # Next, create a decorator that will add the endpoint configuration to the function
     def decorator(func):
@@ -189,7 +189,7 @@ def mms_multi_endpoint(
     name: str,
     service: ServiceConfiguration,
     request_type: RequestType,
-    allowed_client: Optional[ClientType] = None,
+    allowed_clients: Optional[List[ClientType]] = None,
     resp_envelope_type: Optional[Type[E]] = None,
     resp_data_type: Optional[Type[P]] = None,
 ):
@@ -201,21 +201,22 @@ def mms_multi_endpoint(
     the MMS server.
 
     Arguments:
-    name (str):                     The name of the endpoint.
-    service (ServiceConfiguration): The configuration for the service.
-    request_type (RequestType):     The type of request to submit to the MMS server.
-    allowed_client (ClientType):    The type of client that is allowed to access the endpoint. If this is not provided,
-                                    then any client type is allowed.
-    resp_envelope_type (Type[E]):   The type of payload to expect in the response. If this is not provided, then the
-                                    the response envelope will be assumed to have the same type as the request envelope.
-    resp_data_type (Type[P]):       The type of data to expect in the response. If this is not provided, then the
-                                    response data will be assumed to have the same type as the request data. Note, that
-                                    this is not intended to account for the expected sequence type of the response data.
-                                    That is already handled in the wrapped function, so this should only be set if the
-                                    inner data type being returned differs from what was sent.
+    name (str):                         The name of the endpoint.
+    service (ServiceConfiguration):     The configuration for the service.
+    request_type (RequestType):         The type of request to submit to the MMS server.
+    allowed_clients (List[ClientType]): The types of clients that are allowed to access the endpoint. If this is not
+                                        provided, then any client will be allowed.
+    resp_envelope_type (Type[E]):       The type of payload to expect in the response. If this is not provided, then
+                                        the response envelope will be assumed to have the same type as the request
+                                        envelope.
+    resp_data_type (Type[P]):           The type of data to expect in the response. If this is not provided, then the
+                                        response data will be assumed to have the same type as the request data. Note,
+                                        that this is not intended to account for the expected sequence type of the
+                                        response data. That is already handled in the wrapped function, so this should
+                                        only be set if the inner data type being returned differs from what was sent.
     """
     # First, create the endpoint configuration from the given parameters
-    config = EndpointConfiguration(name, allowed_client, service, request_type, resp_envelope_type, resp_data_type)
+    config = EndpointConfiguration(name, allowed_clients, service, request_type, resp_envelope_type, resp_data_type)
 
     # Next, create a decorator that will add the endpoint configuration to the function
     def decorator(func):
@@ -318,11 +319,11 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         ValueError: If the client type is not allowed.
         """
         self._logger.debug(
-            f"{config.name}: Verifying audience. Allowed client: "
-            f"{config.allowed_client.name if config.allowed_client else 'Any'}."
+            f"{config.name}: Verifying audience. Allowed clients: "
+            f"{config.allowed_clients if config.allowed_clients else 'Any'}."
         )
-        if config.allowed_client and self._client_type != config.allowed_client:
-            raise AudienceError(config.name, config.allowed_client, self._client_type)
+        if config.allowed_clients and (self._client_type not in config.allowed_clients):
+            raise AudienceError(config.name, config.allowed_clients, self._client_type)
 
     def request_one(
         self,

{mms_client-1.4.0 → mms_client-1.4.1}/src/mms_client/services/market.py

@@ -30,7 +30,7 @@ class MarketClientMixin:  # pylint: disable=unused-argument
     # The configuration for the market service
     config = ServiceConfiguration(Interface.MI, Serializer(SchemaType.MARKET, "MarketData"))
 
-    @mms_endpoint("MarketSubmit_OfferData", config, RequestType.INFO, ClientType.BSP)
+    @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:
@@ -56,7 +56,7 @@ class MarketClientMixin:  # pylint: disable=unused-argument
             days=days,
         )
 
-    @mms_multi_endpoint("MarketSubmit_OfferData", config, RequestType.INFO, ClientType.BSP)
+    @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]:
@@ -106,7 +106,7 @@ class MarketClientMixin:  # pylint: disable=unused-argument
             days=days,
         )
 
-    @mms_endpoint("MarketCancel_OfferCancel", config, RequestType.INFO, ClientType.BSP)
+    @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:

{mms_client-1.4.0 → mms_client-1.4.1}/src/mms_client/services/registration.py

@@ -27,7 +27,7 @@ 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)
+    @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.
 
@@ -50,6 +50,7 @@ class RegistrationClientMixin:  # pylint: disable=unused-argument
         "RegistrationQuery_Resource",
         config,
         RequestType.REGISTRATION,
+        allowed_clients=[ClientType.BSP, ClientType.TSO],
         resp_envelope_type=RegistrationSubmit,
         resp_data_type=ResourceData,
     )

{mms_client-1.4.0 → mms_client-1.4.1}/src/mms_client/utils/errors.py

@@ -14,7 +14,7 @@ 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):
+    def __init__(self, method: str, allowed: List[ClientType], audience: ClientType):
         """Initialize the error.
 
         Arguments:
@@ -22,8 +22,13 @@ class AudienceError(ValueError):
         allowed (str):  The allowed audience.
         audience (str): The invalid audience.
         """
+        inner = (
+            f"'{allowed[0].name}' is"
+            if len(allowed) == 1
+            else f"""{" or ".join([f"'{a.name}'" for a in allowed])} are"""
+        )
         self.method = method
-        self.message = f"{method}: Invalid client type, '{audience.name}' provided. Only '{allowed.name}' is supported."
+        self.message = f"{method}: Invalid client type, '{audience.name}' provided. Only {inner} supported."
         self.allowed = allowed
         self.audience = audience
         super().__init__(self.message)

{mms_client-1.4.0 → mms_client-1.4.1}/src/mms_client/utils/web.py

@@ -1,6 +1,6 @@
 """Contains the HTTP/web layer for communicating with the MMS server."""
 
-from enum import Enum
+from enum import StrEnum
 from logging import Logger
 from pathlib import Path
 from typing import List
@@ -21,17 +21,19 @@ from mms_client.types.transport import MmsRequest
 from mms_client.types.transport import MmsResponse
 
 
-class ClientType(Enum):
+class ClientType(StrEnum):
     """Identifies the type of client to use.
 
-    The client can be either "bsp" (Balancing Service Provider) or "tso" (Transmission System Operator).
+    The client can be either "bsp" (Balancing Service Provider), "mo" (Market Operator), or "tso" (Transmission System
+    Operator).
     """
 
     BSP = "bsp"
+    MO = "mo"
     TSO = "tso"
 
 
-class Interface(Enum):
+class Interface(StrEnum):
     """Identifies the type of interface to use.
 
     The interface can be either "omi" (Other Market Initiator) or "mi" (Market Initiator).
@@ -76,32 +78,30 @@ class ServiceEndpoint:
             self._selected = self.main
 
 
-# Defines the service endpoints for the BSP and TSO clients for the OMI and MI web services, respectively.
-URLS = {
-    ClientType.BSP: {
-        Interface.OMI: ServiceEndpoint(
-            main="https://www5.tdgc.jp/axis2/services/OmiWebService",
-            backup="https://www6.tdgc.jp/axis2/services/OmiWebService",
-            test="https://www7.tdgc.jp/axis2/services/OmiWebService",
-        ),
-        Interface.MI: ServiceEndpoint(
-            main="https://www2.tdgc.jp/axis2/services/MiWebService",
-            backup="https://www3.tdgc.jp/axis2/services/MiWebService",
-            test="https://www4.tdgc.jp/axis2/services/MiWebService",
-        ),
-    },
-    ClientType.TSO: {
-        Interface.OMI: ServiceEndpoint(
-            main="https://maiwlba103v07.tdgc.jp/axis2/services/OmiWebService",
-            backup="https://mbiwlba103v07.tdgc.jp/axis2/services/OmiWebService",
-            test="https://mbiwlba103v08.tdgc.jp/axis2/services/OmiWebService",
-        ),
-        Interface.MI: ServiceEndpoint(
-            main="https://maiwlba103v03.tdgc.jp/axis2/services/MiWebService",
-            backup="https://mbiwlba103v03.tdgc.jp/axis2/services/MiWebService",
-            test="https://mbiwlba103v06.tdgc.jp/axis2/services/MiWebService",
-        ),
-    },
+# Defines the service endpoints for the BSP, MO and TSO clients for the OMI and MI web services, respectively.
+BSP_MO_URLS = {
+    Interface.OMI: ServiceEndpoint(
+        main="https://www5.tdgc.jp/axis2/services/OmiWebService",
+        backup="https://www6.tdgc.jp/axis2/services/OmiWebService",
+        test="https://www7.tdgc.jp/axis2/services/OmiWebService",
+    ),
+    Interface.MI: ServiceEndpoint(
+        main="https://www2.tdgc.jp/axis2/services/MiWebService",
+        backup="https://www3.tdgc.jp/axis2/services/MiWebService",
+        test="https://www4.tdgc.jp/axis2/services/MiWebService",
+    ),
+}
+TSO_URLS = {
+    Interface.OMI: ServiceEndpoint(
+        main="https://maiwlba103v07.tdgc.jp/axis2/services/OmiWebService",
+        backup="https://mbiwlba103v07.tdgc.jp/axis2/services/OmiWebService",
+        test="https://mbiwlba103v08.tdgc.jp/axis2/services/OmiWebService",
+    ),
+    Interface.MI: ServiceEndpoint(
+        main="https://maiwlba103v03.tdgc.jp/axis2/services/MiWebService",
+        backup="https://mbiwlba103v03.tdgc.jp/axis2/services/MiWebService",
+        test="https://mbiwlba103v06.tdgc.jp/axis2/services/MiWebService",
+    ),
 }
 
 
@@ -158,8 +158,12 @@ class ZWrapper:
         test (bool):                If True, use the test service endpoint. This is useful for testing the client.
         """
         # First, we'll check that the client is valid. If it's not, we'll raise a ValueError.
-        if client not in URLS:
-            raise ValueError(f"Invalid client, '{client}'. Only 'bsp' and 'tso' are supported.")
+        if client in [ClientType.BSP, ClientType.MO]:
+            urls = BSP_MO_URLS
+        elif client == ClientType.TSO:
+            urls = TSO_URLS
+        else:
+            raise ValueError(f"Invalid client, '{client}'. Only 'bsp', 'mo', and 'tso' are supported.")
 
         # We need to determine the service port and location of the WSDL file based on the given interface. If the
         # interface is neither "omi" nor "mi", we raise a ValueError.
@@ -172,7 +176,7 @@ class ZWrapper:
             raise ValueError(f"Invalid interface, '{self._interface}'. Only 'mi' and 'omi' are supported.")
 
         # Next, we need to select the correct service endpoint based on the given client and interface.
-        self._endpoint = URLS[client][self._interface]
+        self._endpoint = urls[self._interface]
         self._endpoint.select(test=test)
 
         # Now, we need to create a new session and mount the PKCS12 adapter to it. This is necessary for