mms-client 1.0.6__tar.gz → 1.1.0__tar.gz

{mms_client-1.0.6 → mms_client-1.1.0}/PKG-INFO

@@ -1,12 +1,23 @@
 Metadata-Version: 2.1
 Name: mms-client
-Version: 1.0.6
+Version: 1.1.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
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pydantic :: 2
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 Requires-Dist: backoff (>=2.2.1,<3.0.0)
 Requires-Dist: cryptography (>=42.0.5,<43.0.0)
 Requires-Dist: lxml (>=5.1.0,<6.0.0)
@@ -32,6 +43,9 @@ The underlying API sends and receives XML documents. Each of these request or re
 
 After the data has been converted and added to the outer request object, it is sent to the appropriate server endpoint via a Zeep client. The client certificate is also injected into the request using a PCKS12 adaptor.
 
+# Serialization
+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.
 
@@ -43,7 +57,7 @@ The MMS has two separate endpoints, depending on whether you want to access mark
 # Object Hierarchy
 The object hierarchy contained in this project is not trivial, and perhaps that reflects a bit of overengineering on our part. However, we chose the paradigm we did to reduce the number of types which had to be exposed to the user. The diagram below indicates how this hierarchy works:
 
-![MMS Client Object Hierarchy](https://github.com/ElectroRoute-Japan/mms-client/blob/main/docs/mmsclient_hierarchy.drawio.png)
+![MMS Client Object Hierarchy](https://github.com/ElectroRoute-Japan/mms-client/raw/main/docs/mmsclient_hierarchy.drawio.png)
 
 Note that there are some types here that are shared between the request and response: mainly, anything inheriting from `mms_client.types.base.Envelop` or `mms_client.types.base.Payload`. For users of the client, only the Payload types need ever be used. Everything else has been obfuscated away, so it is unecessary for the user to have access to these. However, we will explain our reasoning here to provide additional context.
 
@@ -184,6 +198,8 @@ This client is not complete. Currently, it supports the following endpoints:
 - MarketSubmit_OfferData
 - MarketQuery_OfferQuery
 - MarketCancel_OfferCancel
+- RegistrationSubmit_Resource
+- RegistrationQuery_Resource
 
 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.
 

{mms_client-1.0.6 → mms_client-1.1.0}/README.md

@@ -11,6 +11,9 @@ The underlying API sends and receives XML documents. Each of these request or re
 
 After the data has been converted and added to the outer request object, it is sent to the appropriate server endpoint via a Zeep client. The client certificate is also injected into the request using a PCKS12 adaptor.
 
+# Serialization
+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.
 
@@ -22,7 +25,7 @@ The MMS has two separate endpoints, depending on whether you want to access mark
 # Object Hierarchy
 The object hierarchy contained in this project is not trivial, and perhaps that reflects a bit of overengineering on our part. However, we chose the paradigm we did to reduce the number of types which had to be exposed to the user. The diagram below indicates how this hierarchy works:
 
-![MMS Client Object Hierarchy](https://github.com/ElectroRoute-Japan/mms-client/blob/main/docs/mmsclient_hierarchy.drawio.png)
+![MMS Client Object Hierarchy](https://github.com/ElectroRoute-Japan/mms-client/raw/main/docs/mmsclient_hierarchy.drawio.png)
 
 Note that there are some types here that are shared between the request and response: mainly, anything inheriting from `mms_client.types.base.Envelop` or `mms_client.types.base.Payload`. For users of the client, only the Payload types need ever be used. Everything else has been obfuscated away, so it is unecessary for the user to have access to these. However, we will explain our reasoning here to provide additional context.
 
@@ -163,6 +166,8 @@ This client is not complete. Currently, it supports the following endpoints:
 - MarketSubmit_OfferData
 - MarketQuery_OfferQuery
 - MarketCancel_OfferCancel
+- RegistrationSubmit_Resource
+- RegistrationQuery_Resource
 
 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.
 

{mms_client-1.0.6 → mms_client-1.1.0}/pyproject.toml

@@ -1,10 +1,24 @@
 [tool.poetry]
 name = "mms_client"
-version = "v1.0.6"
+version = "v1.1.0"
 description = "API client for accessing the MMS"
 authors = ["Ryan Wood <ryan.wood@electroroute.co.jp>"]
 readme = "README.md"
 packages = [{ include = "mms_client", from = "src" }]
+homepage = "https://github.com/ElectroRoute-Japan/mms-client"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: Pydantic :: 2",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: The Unlicense (Unlicense)",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
 
 [tool.poetry.dependencies]
 python = "^3.11"
@@ -99,6 +113,9 @@ omit = ["*/__init__.py"]
 [tool.coverage.report]
 fail_under = 100
 
+[tool.coverage.html]
+directory = "coverage_html_report"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"

mms_client-1.1.0/src/mms_client/services/registration.py

@@ -0,0 +1,77 @@
+"""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
+
+
+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_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-1.0.6 → mms_client-1.1.0}/src/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-1.0.6 → mms_client-1.1.0}/src/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-1.0.6 → mms_client-1.1.0}/src/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-1.0.6 → mms_client-1.1.0}/src/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-1.1.0/src/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."""