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

mms_client/types/transport.py

@@ -17,7 +17,7 @@ class RequestType(Enum):
 
     INFO = "mp.info"
     MARKET = "mp.market"
-    REGISTRATION = "mp.registration"
+    REGISTRATION = "mpr"
     REPORT = "mp.report"
     OMI = "mp.omi"
 

mms_client/utils/serialization.py

@@ -4,6 +4,7 @@ from functools import lru_cache
 from io import BytesIO
 from pathlib import Path
 from typing import Dict
+from typing import List
 from typing import Optional
 from typing import Tuple
 from typing import Type
@@ -62,8 +63,33 @@ class Serializer:
         # First, create our payload class from the payload and data types
         payload_cls = _create_request_payload_type(
             self._payload_key,
-            type(request_envelope),  # type: ignore[arg-type]
-            type(request_data),  # type: ignore[arg-type]
+            type(request_envelope),
+            type(request_data),
+            False,  # type: ignore[arg-type]
+        )
+
+        # Next, inject the payload and data into the payload class
+        # Note: this returns a type that inherits from PayloadBase and the arguments provided to the initializer
+        # here are correct, but mypy thinks they are incorrect because it doesn't understand the the inherited type
+        payload = payload_cls(request_envelope, request_data, self._xsd.value)  # type: ignore[call-arg, misc]
+
+        # Finally, convert the payload to XML and return it
+        # Note: we provided the encoding here so this will return bytes, not a string
+        return payload.to_xml(skip_empty=True, encoding="utf-8", xml_declaration=True)  # type: ignore[return-value]
+
+    def serialize_multi(self, request_envelope: E, request_data: List[P], request_type: Type[P]) -> bytes:
+        """Serialize the envelope and data to a byte string for sending to the MMS server.
+
+        Arguments:
+        request_envelope (Envelope):    The envelope to be serialized.
+        request_data (List[Payload]):    The data to be serialized.
+        request_type (Type[Payload]):    The type of data to be serialized.
+
+        Returns:    A byte string containing the XML-formatted data to be sent to the MMS server.
+        """
+        # First, create our payload class from the payload and data types
+        payload_cls = _create_request_payload_type(
+            self._payload_key, type(request_envelope), request_type, True  # type: ignore[arg-type]
         )
 
         # Next, inject the payload and data into the payload class
@@ -129,7 +155,7 @@ class Serializer:
         # Now, verify that the response doesn't contain an unexpected data type and then retrieve the payload data
         # from within the envelope
         self._verify_tree_data_tag(envelope_node, data_type)
-        resp.payload = self._from_tree_data(envelope_node.find(data_type.__name__), data_type)
+        resp.payload = self._from_tree_data(envelope_node.find(get_tag(data_type)), data_type)
 
         # Finally, attempt to extract the messages from within the payload
         resp.messages = self._from_tree_messages(raw, envelope_type, data_type, self._payload_key, False)
@@ -167,7 +193,7 @@ class Serializer:
         # Note: apparently, mypy doesn't know about setter-getter properties either...
         self._verify_tree_data_tag(env_node, data_type)
         resp.payload = [
-            self._from_tree_data(item, data_type) for item in env_node.findall(data_type.__name__)  # type: ignore[misc]
+            self._from_tree_data(item, data_type) for item in env_node.findall(get_tag(data_type))  # type: ignore[misc]
         ]
 
         # Finally, attempt to extract the messages from within the payload
@@ -216,7 +242,7 @@ class Serializer:
         ValueError:    If the expected data type is not found in the response.
         """
         data_tags = set(node.tag for node in raw)
-        if not data_tags.issubset([data_type.__name__, "Messages"]):
+        if not data_tags.issubset([data_type.__name__, data_type.__xml_tag__, "Messages"]):
             raise ValueError(f"Expected data type '{data_type.__name__}' not found in response")
 
     def _from_tree_data(self, raw: Optional[Element], data_type: Type[P]) -> Optional[ResponseData[P]]:
@@ -291,8 +317,7 @@ class Serializer:
             )
         else:
             # Iterate over each field on the current type...
-            for name, field in current_type.model_fields.items():
-                print(f"Checking field {name} with type {field.annotation}...")
+            for field in current_type.model_fields.values():
 
                 # First, get the arguments and origin of the field's annotation
                 args = get_args(field.annotation)
@@ -420,7 +445,7 @@ def _create_response_payload_type(key: str, envelope_type: Type[E], data_type: T
 
 
 @lru_cache(maxsize=None)
-def _create_response_common_type(tag_type: Type) -> Type[ResponseCommon]:
+def _create_response_common_type(tag_type: Type[Union[E, P]]) -> Type[ResponseCommon]:
     """Create a new wrapper for the ResponseCommon type with the given tag.
 
     This method is intended to save us the overhead of writing a new class for each tag type. Instead, we can
@@ -432,7 +457,7 @@ def _create_response_common_type(tag_type: Type) -> Type[ResponseCommon]:
     Returns:    The wrapper type that will be used for deserialization.
     """  # fmt: skip
     # First, create a new wrapper type that contains the ResponseCommon type with the appropriate XML tag
-    class Wrapper(ResponseCommon, tag=tag_type.__name__):  # type: ignore[call-arg]
+    class Wrapper(ResponseCommon, tag=get_tag(tag_type)):  # type: ignore[call-arg]
         """Wrapper for the validation object with the proper XML tag."""
 
     # Finally, return the wrapper type so we can instantiate it
@@ -440,7 +465,12 @@ def _create_response_common_type(tag_type: Type) -> Type[ResponseCommon]:
 
 
 @lru_cache(maxsize=None)
-def _create_request_payload_type(key: str, envelope_type: Type[E], data_type: Type[P]) -> Type[PayloadBase]:
+def _create_request_payload_type(
+    key: str,
+    envelope_type: Type[E],
+    data_type: Type[Union[P, List[P]]],
+    multi: bool,
+) -> Type[PayloadBase]:
     """Create a new payload type for the given payload and data types.
 
     This method is intended to save us the overhead of writing a new class for each payload type. Instead, we can
@@ -454,17 +484,21 @@ def _create_request_payload_type(key: str, envelope_type: Type[E], data_type: Ty
     key: str                        The tag to use for the parent element of the payload.
     envelope_type (Type[Envelope]): The type of payload to be constructed.
     data_type (Type[Payload]):      The type of data to be constructed.
+    multi (bool):                   If True, the payload will be a list; otherwise, it will be a singleton.
 
     Returns:    A new payload type that can be used for serialization.
     """  # fmt: skip
-    # First, create a wrapper for our data type that will be used to store the data in the payload
+    # First, create our data type
+    payload_type = List[data_type] if multi else data_type  # type: ignore[valid-type]
+
+    # Next, create a wrapper for our data type that will be used to store the data in the payload
     class Envelope(envelope_type):  # type: ignore[valid-type, misc]
         """Wrapper for the data type that will be used to store the data in the payload."""
 
         # The data to be stored in the payload
-        data: data_type = element(tag=data_type.__name__)  # type: ignore[valid-type]
+        data: payload_type = element(tag=get_tag(data_type))  # type: ignore[valid-type, type-var]
 
-        def __init__(self, envelope: envelope_type, data: data_type):  # type: ignore[valid-type]
+        def __init__(self, envelope: envelope_type, data: payload_type):  # type: ignore[valid-type]
             """Create a new envelope to store payload data.
 
             Arguments:
@@ -475,14 +509,14 @@ def _create_request_payload_type(key: str, envelope_type: Type[E], data_type: Ty
             obj["data"] = data
             super().__init__(**obj)
 
-    # Next, create our payload type that actually contains all the XML data
+    # Now, create our payload type that actually contains all the XML data
     class RQPayload(PayloadBase, tag=key):  # type: ignore[call-arg]
         """The payload type that will be used for serialization."""
 
         # The payload containing our request object and any data
         envelope: Envelope = element(tag=envelope_type.__name__)
 
-        def __init__(self, envelope: envelope_type, data: data_type, schema: str):  # type: ignore[valid-type]
+        def __init__(self, envelope: envelope_type, data: payload_type, schema: str):  # type: ignore[valid-type]
             """Create a new payload containing the request object and any data.
 
             Arguments:
@@ -511,3 +545,14 @@ def _find_or_fail(node: Element, tag: str) -> Element:
     if found is None:
         raise ValueError(f"Expected tag '{tag}' not found in node")  # pragma: no cover
     return found
+
+
+def get_tag(data_type: Type[P]) -> str:
+    """Get the tag for the given data type.
+
+    Arguments:
+    data_type (Type[Payload]):  The data type to get the tag for.
+
+    Returns:    The tag for the given data type.
+    """
+    return data_type.__xml_tag__ or data_type.__name__

{mms_client-1.0.6.dist-info → mms_client-1.2.0.dist-info}/METADATA

@@ -1,12 +1,23 @@
 Metadata-Version: 2.1
 Name: mms-client
-Version: 1.0.6
+Version: 1.2.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.dist-info → mms_client-1.2.0.dist-info}/RECORD

@@ -12,23 +12,25 @@ mms_client/security/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 mms_client/security/certs.py,sha256=kNCUFmy18YIxkWKu3mdMmlxmHdft4a6BvtyJ46rA9I4,1489
 mms_client/security/crypto.py,sha256=M7aIllM3_ZwZgm9nH6QQ6Ig14XCAd6e6WGwqqUbbI1Q,2149
 mms_client/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mms_client/services/base.py,sha256=8yWBeDoBimY9BZeMOkMDV-ggvPTzZHnlqXiv9eo8fIQ,25363
-mms_client/services/market.py,sha256=kwcbXz1Op4hwXbOn_Xsx_qBNuHfvWAxBH6G2f4AWzPI,4892
+mms_client/services/base.py,sha256=mcUL-AZpaJETVkzAOoazmKfI5O3cJ0KWzIYQ5bjpNuE,25839
+mms_client/services/market.py,sha256=juYIZuSsJ10srzDK4N6s8guoGqdDuQXGohecF43WQh8,6169
 mms_client/services/omi.py,sha256=h6cM5U3-iSm0YiIaJwqYTZeI5uhLbA7FPxh_qy_3qww,521
-mms_client/services/registration.py,sha256=MUUp0SDE7F0d_lV5pXNqPhrU87CAZc6AA72AdmRAu6Q,571
+mms_client/services/registration.py,sha256=9pNZdgwRbJJCnmsVgESNnc3ywkn-wdQryumUhLn6Xvg,3419
 mms_client/services/report.py,sha256=HYVJNwEHo6ZC6497UqO5y1IqZ2ga3kVH5AepdxhYfug,537
 mms_client/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mms_client/types/base.py,sha256=EMGCDvf_B_8q1YMH-l31c_lV0OdxxAReFNU3zPs0K0Q,9681
-mms_client/types/enums.py,sha256=WzFD9fG9jKFsA91oKyXCAW0oKzUTH3NyUkV4A_N0sXg,329
-mms_client/types/fields.py,sha256=QaNnfU0goAld8VADD_DXZ6qEuUrxISY7rFg5gB6k948,6250
+mms_client/types/base.py,sha256=wrDPn9io30in_w2qKa4A503gX_gAaMT7a1MpZ3HcmIc,9701
+mms_client/types/enums.py,sha256=wXlXvifWXWm9dowfG5iQlkax_6OX6z2nHid94WkhQwE,464
+mms_client/types/fields.py,sha256=SAvrDJGSvOVtbGvaaqLFBx2mCr0AxzqVFUTJgPSEDOY,12065
 mms_client/types/market.py,sha256=OKjBIx9aIgaLUci6b5WoB4NZbFncRbbd2FxeAvW1iWw,2588
-mms_client/types/offer.py,sha256=EdxgHlU9FWPuMq3tLYcbILBWnL5SWMsH5Qe7NRhGz9Y,6300
-mms_client/types/transport.py,sha256=SGzDGoTpUvhGpkKxoyJR22z-Ao_Dj5idz97vd6u7fqk,4419
+mms_client/types/offer.py,sha256=orlohxAWZlW2rwPJpGAoiy1knoCT2x2sXJyzThkXYVY,7693
+mms_client/types/registration.py,sha256=Nir73S3ffpk0O_fnTD2alFaqV1k67_8dcyyduXvPBI4,1381
+mms_client/types/resource.py,sha256=_pRNAqOX8A0lUXmU8qO_8QwRtRx9BwZDdrN-w_Fnu38,66466
+mms_client/types/transport.py,sha256=vyosoeGSdYthqlmiyDAkZusYa8yVHUwOzfTqwZne2Ik,4407
 mms_client/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mms_client/utils/errors.py,sha256=jYdlG4OPI82s0fJcXCRNlKeEixDUSSAxjs_7C16qVL4,2306
-mms_client/utils/serialization.py,sha256=Zp1pZvrWcbV4p_PERS5e9zNKPSeHQFijYzJiby3y0Pk,25206
+mms_client/utils/serialization.py,sha256=TqkucFL1rvMu49sxsWDwCZSvWMDd75Gj9kZmm1FYUzc,27203
 mms_client/utils/web.py,sha256=fcdCtdDrHBPyhIlTcyiuAk3D3TlW8HmUw-wGfpG4KTA,9653
-mms_client-1.0.6.dist-info/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
-mms_client-1.0.6.dist-info/METADATA,sha256=sImN-laCo5emcrt6KlfJZGmdb85XlBbTumjRlmIkUZQ,13840
-mms_client-1.0.6.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
-mms_client-1.0.6.dist-info/RECORD,,
+mms_client-1.2.0.dist-info/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
+mms_client-1.2.0.dist-info/METADATA,sha256=xTwJZuKbEW7HKg_C5zw-uVYVXjnI112CiYxEPxGmoWA,14742
+mms_client-1.2.0.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
+mms_client-1.2.0.dist-info/RECORD,,