openadr3-client-gac-compliance 0.0.1__tar.gz

openadr3_client_gac_compliance-0.0.1/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.3
+Name: openadr3-client-gac-compliance
+Version: 0.0.1
+Summary: 
+Author: Nick van der Burgt
+Author-email: nick.van.der.burgt@elaad.nl
+Requires-Python: >=3.12, <4
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: openadr3-client (>=0.0.1,<0.0.2)
+Requires-Dist: pydantic (>=2.11.2,<3.0.0)
+Description-Content-Type: text/markdown
+
+# OpenADR3 client
+
+This repository contains a plugin for the [OpenADR3-client](https://github.com/ElaadNL/openadr3-client) library that adds additional pydantic validators to the OpenADR3 domain models to ensure GAC compliance. Since GAC compliance is a superset of OpenADR3, adding validation rules on top of the OpenADR3 models is sufficient to ensure compliance.
+
+To use this plugin, the package must be imported once globally. We recommend doing this in your root directories `__init__.py` file.
+
+```python
+import openadr3_client_gac_compliance  # noqa: F401 (in case you use ruff)
+```

openadr3_client_gac_compliance-0.0.1/README.md

@@ -0,0 +1,9 @@
+# OpenADR3 client
+
+This repository contains a plugin for the [OpenADR3-client](https://github.com/ElaadNL/openadr3-client) library that adds additional pydantic validators to the OpenADR3 domain models to ensure GAC compliance. Since GAC compliance is a superset of OpenADR3, adding validation rules on top of the OpenADR3 models is sufficient to ensure compliance.
+
+To use this plugin, the package must be imported once globally. We recommend doing this in your root directories `__init__.py` file.
+
+```python
+import openadr3_client_gac_compliance  # noqa: F401 (in case you use ruff)
+```

openadr3_client_gac_compliance-0.0.1/openadr3_client_gac_compliance/__init__.py

@@ -0,0 +1,2 @@
+import openadr3_client_gac_compliance.program_gac_compliant  # noqa: F401
+import openadr3_client_gac_compliance.event_gac_compliant  # noqa: F401

openadr3_client_gac_compliance-0.0.1/openadr3_client_gac_compliance/event_gac_compliant.py

@@ -0,0 +1,204 @@
+"""Module which implements GAC compliance validators for the event OpenADR3 types.
+
+This module validates all the object constraints and requirements on the OpenADR3 events resource
+as specified in the Grid aware charging (GAC) specification.
+
+There is one requirement that is not validated here, as it cannot be validated through the scope of the
+pydantic validators. Namely, the requirement that a safe mode event MUST be present in a program.
+
+As the pydantic validator works on the scope of a single Event Object, it is not possible to validate
+that a safe mode event is present in a program. And it cannot be validated on the Program object,
+as the program object does not contain the events, these are stored seperately in the VTN.
+"""
+
+from itertools import pairwise
+import re
+from openadr3_client.models.model import ValidatorRegistry, Model as ValidatorModel
+from openadr3_client.models.event.event import Event
+from openadr3_client.models.event.event_payload import EventPayloadType
+
+
+def _continuous_or_seperated(self: Event) -> Event:
+    """Enforces that events either have consistent interval definitions compliant with GAC.
+
+    the Grid aware charging (GAC) specification allows for two types of (mutually exclusive)
+    interval definitions:
+
+    1. Continuous
+    2. Seperated
+
+    The continious implementation can be used when all intervals have the same duration.
+    In this case, only the top-level intervalPeriod of the event can be used, and the intervalPeriods
+    of the individual intervals must be None.
+
+    In the seperated intervalDefinition approach, the intervalPeriods must be set on each individual intervals,
+    and the top-level intervalPeriod of the event must be None. This seperated approach is used when events have differing
+    durations.
+    """
+    intervals = self.intervals or ()
+
+    if self.interval_period is None:
+        # interval period not set at top level of the event.
+        # Ensure that all intervals have the interval_period defined, to comply with the GAC specification.
+        undefined_intervals_period = [i for i in intervals if i.interval_period is None]
+        if undefined_intervals_period:
+            raise ValueError(
+                "Either 'interval_period' must be set on the event once, or every interval must have its own 'interval_period'."
+            )
+    else:
+        # interval period set at top level of the event.
+        # Ensure that all intervals do not have the interval_period defined, to comply with the GAC specification.
+        duplicate_interval_period = [
+            i for i in intervals if i.interval_period is not None
+        ]
+        if duplicate_interval_period:
+            raise ValueError(
+                "Either 'interval_period' must be set on the event once, or every interval must have its own 'interval_period'."
+            )
+
+    return self
+
+
+def _targets_compliant(self: Event) -> Event:
+    """Enforces that the targets of the event are compliant with GAC.
+
+    GAC enforces the following constraints for targets:
+
+    - The event must contain a POWER_SERVICE_LOCATIONS target.
+    - The POWER_SERVICE_LOCATIONS target value must be a list of 'EAN18' values.
+    - The event must contain a VEN_NAME target.
+    - The VEN_NAME target value must be a list of 'ven object name' values (between 1 and 128 characters).
+    """
+    targets = self.targets or ()
+
+    power_service_locations = [
+        t for t in targets if t.type == "POWER_SERVICE_LOCATIONS"
+    ]
+    ven_names = [t for t in targets if t.type == "VEN_NAME"]
+
+    if not power_service_locations:
+        raise ValueError("The event must contain a POWER_SERVICE_LOCATIONS target.")
+
+    if not ven_names:
+        raise ValueError("The event must contain a VEN_NAME target.")
+
+    if len(power_service_locations) > 1:
+        raise ValueError(
+            "The event must contain exactly one POWER_SERVICE_LOCATIONS target."
+        )
+
+    if len(ven_names) > 1:
+        raise ValueError("The event must contain only one VEN_NAME target.")
+
+    power_service_location = power_service_locations[0]
+    ven_name = ven_names[0]
+
+    if len(power_service_location.values) == 0:
+        raise ValueError("The POWER_SERVICE_LOCATIONS target value cannot be empty.")
+
+    if not all(re.fullmatch(r"\d{18}", v) for v in power_service_location.values):
+        raise ValueError(
+            "The POWER_SERVICE_LOCATIONS target value must be a list of 'EAN18' values."
+        )
+
+    if len(ven_name.values) == 0:
+        raise ValueError("The VEN_NAME target value cannot be empty.")
+
+    if not all(1 <= len(v) <= 128 for v in ven_name.values):
+        raise ValueError(
+            "The VEN_NAME target value must be a list of 'ven object name' values (between 1 and 128 characters)."
+        )
+
+    return self
+
+
+def _payload_descriptor_gac_compliant(self: Event) -> Event:
+    """Enforces that the payload descriptor is GAC compliant.
+
+    GAC enforces the following constraints for payload descriptors:
+
+    - The event interval must exactly one payload descriptor.
+    - The payload descriptor must have a payload type of 'IMPORT_CAPACITY_LIMIT'
+    - The payload descriptor must have a units of 'KW' (case sensitive).
+    """
+    if self.payload_descriptor is None:
+        raise ValueError("The event must have a payload descriptor.")
+
+    if len(self.payload_descriptor) != 1:
+        raise ValueError("The event must have exactly one payload descriptor.")
+
+    payload_descriptor = self.payload_descriptor[0]
+
+    if payload_descriptor.payload_type != EventPayloadType.IMPORT_CAPACITY_LIMIT:
+        raise ValueError(
+            "The payload descriptor must have a payload type of 'IMPORT_CAPACITY_LIMIT'."
+        )
+
+    if payload_descriptor.units != "KW":
+        raise ValueError(
+            "The payload descriptor must have a units of 'KW' (case sensitive)."
+        )
+
+    return self
+
+
+def _event_interval_gac_compliant(self: Event) -> Event:
+    """Enforces that the event interval is GAC compliant.
+
+    GAC enforces the following constraints for event intervals:
+
+    - The event interval must have an id value that is strictly increasing.
+    - The event interval must have exactly one payload.
+    - The payload of the event interval must have a type of 'IMPORT_CAPACITY_LIMIT'
+    """
+    if not self.intervals:
+        raise ValueError("The event must have at least one interval.")
+
+    if not all(curr.id > prev.id for prev, curr in pairwise(self.intervals)):
+        raise ValueError(
+            "The event interval must have an id value that is strictly increasing."
+        )
+
+    for interval in self.intervals:
+        if interval.payloads is None:
+            raise ValueError("The event interval must have a payload.")
+
+        if len(interval.payloads) != 1:
+            raise ValueError("The event interval must have exactly one payload.")
+
+        payload = interval.payloads[0]
+
+        if payload.type != EventPayloadType.IMPORT_CAPACITY_LIMIT:
+            raise ValueError(
+                "The event interval payload must have a payload type of 'IMPORT_CAPACITY_LIMIT'."
+            )
+
+    return self
+
+
+@ValidatorRegistry.register(Event, ValidatorModel())
+def event_gac_compliant(self: Event) -> Event:
+    """Enforces that events are GAC compliant.
+
+    GAC enforces the following constraints for events:
+
+    - The event must have a priority set.
+    - The priority must be greater than or equal to 0 and less than or equal to 999.
+    - The event must have either a continuous or seperated interval definition.
+    """
+    if self.priority is None:
+        raise ValueError("The event must have a priority set.")
+
+    if self.priority > 999:
+        raise ValueError(
+            "The priority must be greater than or equal to 0 and less than or equal to 999."
+        )
+
+    interval_periods_validated = _continuous_or_seperated(self)
+    targets_validated = _targets_compliant(interval_periods_validated)
+    payload_descriptor_validated = _payload_descriptor_gac_compliant(targets_validated)
+    event_interval_validated = _event_interval_gac_compliant(
+        payload_descriptor_validated
+    )
+
+    return event_interval_validated

openadr3_client_gac_compliance-0.0.1/openadr3_client_gac_compliance/program_gac_compliant.py

@@ -0,0 +1,38 @@
+"""Module which implements GAC compliance validators for the program OpenADR3 types."""
+
+from openadr3_client.models.program.program import Program
+from openadr3_client.models.model import ValidatorRegistry, Model as ValidatorModel
+
+import re
+
+
+@ValidatorRegistry.register(Program, ValidatorModel())
+def program_gac_compliant(self: Program) -> Program:
+    """Enforces that the program is GAC compliant.
+
+    GAC enforces the following constraints for programs:
+    - The program must have a retailer name
+    - The retailer name must be an EAN13 identifier.
+    - The program MUST have a programType.
+    - The programType MUST equal "DSO_CPO_INTERFACE-x.x.x, where x.x.x is the version as defined in the GAC specification.
+    - The program MUST have bindingEvents set to True.
+    are allowed there.
+    """
+    program_type_regex = r"^DSO_CPO_INTERFACE-(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
+
+    if self.retailer_name is None:
+        raise ValueError("The program must have a retailer name.")
+    if not re.fullmatch(r"\d{13}", self.retailer_name):
+        raise ValueError("The retailer name must be an EAN13 identifier.")
+
+    if self.program_type is None:
+        raise ValueError("The program must have a program type.")
+    if not re.fullmatch(program_type_regex, self.program_type):
+        raise ValueError(
+            "The program type must follow the format DSO_CPO_INTERFACE-x.x.x."
+        )
+
+    if self.binding_events is False:
+        raise ValueError("The program must have bindingEvents set to True.")
+
+    return self

openadr3_client_gac_compliance-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "openadr3-client-gac-compliance"
+version = "0.0.1"
+description = ""
+authors = [
+    {name = "Nick van der Burgt", email = "nick.van.der.burgt@elaad.nl"}
+]
+readme = "README.md"
+requires-python = ">=3.12, <4"
+dependencies = [
+    "pydantic (>=2.11.2,<3.0.0)",
+    "openadr3-client (>=0.0.1,<0.0.2)",
+]
+
+# TODO: remove local openadr3-client dependency when the openadr3-client package is published to pypi
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+mypy = "^1.15.0"
+ruff = "^0.11.4"
+pytest = "^8.3.5"
+pytest-cov = "^6.1.1"
+
+[[tool.mypy.overrides]]
+module = ["openadr3_client"]
+ignore_missing_imports = true