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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mms-client
-Version: 1.3.0
+Version: 1.4.0
 Summary: API client for accessing the MMS
 Home-page: https://github.com/ElectroRoute-Japan/mms-client
 Author: Ryan Wood
@@ -174,14 +174,14 @@ There's a lot of code here but it's not terribly difficult to understand. All th
 If you want to test your MMS connection, you can try using the test server:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
+client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
 ```
 
 ## Connecting as a Market Admin
 If you're connecting as a market operator (MO), you can connect in admin mode:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
+client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
 ```
 
 ## Log Settings
@@ -193,6 +193,27 @@ client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.B
 
 The client currently logs a number of informational, debug and error messages. You can freely change the logging level yourself.
 
+## Auditing XML Requests & Responses
+A common requirement for this sort of library is recording or saving the raw XML requests and responses for audit/logging purposes. This library supports this workflow through the `mms_client.utils.auditing.AuditPlugin` object. This object intercepts the XML request at the Zeep client level right before it is sent to the MMS and, similarly, intercepts the XML response immediately after it is received from the MMS. Before passing these objects on, without modifying them, it records the XML data as a byte string and passes it to two methods: `audit_request` and `audit_response`. These can be overridden by any object that inherits from this class, allowing the user to direct this data to whatever store they prefer to use for auditing or logging.
+
+```python
+class TestAuditPlugin(AuditPlugin):
+
+    def __init__(self):
+        self.request = None
+        self.response = None
+
+    def audit_request(self, mms_request: bytes) -> None:
+        self.request = mms_request
+
+    def audit_response(self, mms_response: bytes) -> None:
+        self.response = mms_response
+
+client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
+```
+
+This same input allows for the user to create their own plugins and add them to the Zeep client, allowing for a certain amount of extensibility.
+
 # Completeness
 This client is not complete. Currently, it supports the following endpoints:
 - MarketSubmit_OfferData

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

@@ -142,14 +142,14 @@ There's a lot of code here but it's not terribly difficult to understand. All th
 If you want to test your MMS connection, you can try using the test server:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
+client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
 ```
 
 ## Connecting as a Market Admin
 If you're connecting as a market operator (MO), you can connect in admin mode:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
+client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
 ```
 
 ## Log Settings
@@ -161,6 +161,27 @@ client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.B
 
 The client currently logs a number of informational, debug and error messages. You can freely change the logging level yourself.
 
+## Auditing XML Requests & Responses
+A common requirement for this sort of library is recording or saving the raw XML requests and responses for audit/logging purposes. This library supports this workflow through the `mms_client.utils.auditing.AuditPlugin` object. This object intercepts the XML request at the Zeep client level right before it is sent to the MMS and, similarly, intercepts the XML response immediately after it is received from the MMS. Before passing these objects on, without modifying them, it records the XML data as a byte string and passes it to two methods: `audit_request` and `audit_response`. These can be overridden by any object that inherits from this class, allowing the user to direct this data to whatever store they prefer to use for auditing or logging.
+
+```python
+class TestAuditPlugin(AuditPlugin):
+
+    def __init__(self):
+        self.request = None
+        self.response = None
+
+    def audit_request(self, mms_request: bytes) -> None:
+        self.request = mms_request
+
+    def audit_response(self, mms_response: bytes) -> None:
+        self.response = mms_response
+
+client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
+```
+
+This same input allows for the user to create their own plugins and add them to the Zeep client, allowing for a certain amount of extensibility.
+
 # Completeness
 This client is not complete. Currently, it supports the following endpoints:
 - MarketSubmit_OfferData

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

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

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

@@ -33,6 +33,7 @@ from mms_client.utils.errors import MMSValidationError
 from mms_client.utils.serialization import Serializer
 from mms_client.utils.web import ClientType
 from mms_client.utils.web import Interface
+from mms_client.utils.web import Plugin
 from mms_client.utils.web import ZWrapper
 
 # Set the default logger for the MMS client
@@ -253,6 +254,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         client_type: ClientType,
         cert: Certificate,
         logger: Optional[Logger] = None,
+        plugins: Optional[List[Plugin]] = None,
         is_admin: bool = False,
         test: bool = False,
     ):
@@ -265,6 +267,8 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         cert (Certificate):         The certificate to use for signing requests.
         logger (Logger):            The logger to use for instrumentation. If this is not provided, then the default
                                     logger will be used.
+        plugins (List[Plugin]):     A list of plugins to add to the Zeep client. This can be useful for auditing or
+                                    other purposes.
         is_admin (bool):            Whether the user is an admin (i.e. is a market operator).
         test (bool):                Whether to use the test server.
         """
@@ -281,6 +285,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
 
         # Now, set our logger to either the provided logger or the default logger
         self._logger = logger or default_logger
+        self._plugins = plugins or []
 
         # Finally, create a list of wrappers for the different interfaces
         self._wrappers: Dict[Interface, ZWrapper] = {}
@@ -598,6 +603,12 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         if service.interface not in self._wrappers:
             self._logger.debug(f"Creating wrapper for {service.interface.name} interface.")
             self._wrappers[service.interface] = ZWrapper(
-                self._client_type, service.interface, self._cert.to_adapter(), self._logger, True, self._test
+                self._client_type,
+                service.interface,
+                self._cert.to_adapter(),
+                self._logger,
+                self._plugins,
+                True,
+                self._test,
             )
         return self._wrappers[service.interface]

{mms_client-1.3.0 → mms_client-1.4.0}/src/mms_client/types/base.py

@@ -115,7 +115,7 @@ class SchemaType(Enum):
     OMI = "omi.xsd"
 
 
-class PayloadBase(BaseXmlModel, nsmap={"xsi": "http://www.w3.org/2001/XMLSchema"}):
+class PayloadBase(BaseXmlModel, nsmap={"xsi": "http://www.w3.org/2001/XMLSchema-instance"}):
     """Represents the base fields for an MMS request payload."""
 
     # The XML schema to use for validation

mms_client-1.4.0/src/mms_client/utils/auditing.py

@@ -0,0 +1,54 @@
+"""Contains functions for auditability plugins."""
+
+from abc import ABC
+from abc import abstractmethod
+
+from lxml.etree import _Element as Element
+from lxml.etree import tostring
+from zeep import Plugin
+
+
+class AuditPlugin(ABC, Plugin):
+    """Base class for audit plugins."""
+
+    def egress(self, envelope: Element, http_headers: dict, operation, binding_options):
+        """Handle the MMS request before it is sent.
+
+        Arguments are the same as in the egress method of the Plugin class.
+
+        Returns:
+        lxml.etree.Element: The XML message to send.
+        dict:               The HTTP headers to send.
+        """
+        data = tostring(envelope, encoding="UTF-8", xml_declaration=True)
+        self.audit_request(data)
+        return envelope, http_headers
+
+    def ingress(self, envelope: Element, http_headers: dict, operation):
+        """Handle the MMS response before it is processed.
+
+        Arguments are the same as in the ingress method of the Plugin class.
+
+        Returns:
+        lxml.etree.Element: The XML message to process.
+        dict:               The HTTP headers to process.
+        """
+        data = tostring(envelope, encoding="UTF-8", xml_declaration=True)
+        self.audit_response(data)
+        return envelope, http_headers
+
+    @abstractmethod
+    def audit_request(self, mms_request: bytes) -> None:
+        """Audit an MMS request.
+
+        Arguments:
+        mms_request (bytes):    The MMS request XML to audit.
+        """
+
+    @abstractmethod
+    def audit_response(self, mms_response: bytes) -> None:
+        """Audit an MMS response.
+
+        Arguments:
+        mms_response (bytes):   The MMS response XML to audit.
+        """

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

@@ -3,12 +3,15 @@
 from enum import Enum
 from logging import Logger
 from pathlib import Path
+from typing import List
+from typing import Optional
 
 from backoff import expo
 from backoff import on_exception
 from requests import Session
 from requests_pkcs12 import Pkcs12Adapter
 from zeep import Client
+from zeep import Plugin
 from zeep import Transport
 from zeep.cache import SqliteCache
 from zeep.exceptions import TransportError
@@ -132,6 +135,7 @@ class ZWrapper:
         interface: Interface,
         adapter: Pkcs12Adapter,
         logger: Logger,
+        plugins: Optional[List[Plugin]] = None,
         cache: bool = True,
         test: bool = False,
     ):
@@ -147,6 +151,8 @@ class ZWrapper:
         adapter (Pkcs12Adapter):    The PKCS12 adapter containing the certificate and private key to use for
                                     authenticating with the MMS server.
         logger (Logger):            The logger to use for instrumentation.
+        plugins (List[Plugin]):     A list of Zeep plugins to use with the client. This is useful for adding additional
+                                    functionality to the client, such as auditing or logging.
         cache (bool):               If True, use a cache for the Zeep client. This is useful for avoiding repeated
                                     lookups of the WSDL file, which should result in lower latency.
         test (bool):                If True, use the test service endpoint. This is useful for testing the client.
@@ -184,6 +190,7 @@ class ZWrapper:
         self._client = Client(
             wsdl=str(location.resolve()),
             transport=Transport(cache=SqliteCache() if cache else None, session=sess),
+            plugins=plugins,
         )
         self._create_service()