Hexagonal architecture for schema validators (JSON schema and pydantic) (#179)

* introduce base class and move serializer registry one level top
* complete implementation

Author: VigneshVSV

.github/workflows/ci-pipeline.yml

@@ -81,13 +81,19 @@ jobs:
           source .venv/bin/activate
           ruff check --config ruff.toml hololinked/client
           ruff check --config ruff.toml hololinked/serializers
+          ruff check --config ruff.toml hololinked/schema_validators
+          ruff check --config ruff.toml hololinked/serialization.py
+          ruff check --config ruff.toml hololinked/schemas.py
 
       - name: run ty type checker
         if: matrix.tool == 'ty'
         run: |
           source .venv/bin/activate
           ty check hololinked/client
           ty check hololinked/serializers
+          ty check hololinked/schema_validators
+          ty check hololinked/serialization.py
+          ty check hololinked/schemas.py
 
   scan:
     name: security scan (${{ matrix.tool }})

hololinked/__init__.py

@@ -3,5 +3,9 @@
 __version__ = "0.4.0"
 
 from .config import global_config  # noqa
-import hololinked.core  # noqa: F401
+from .serialization import Serializers as Serializers
+from .schemas import JSONSchema as JSONSchema, SchemaValidatorClasses as SchemaValidatorClasses
+
+import hololinked.core  # noqa: F401 # this one is lazy for most part
 import hololinked.serializers  # noqa: F401
+import hololinked.schema_validators  # noqa: F401

hololinked/client/factory.py

@@ -13,6 +13,7 @@
 from paho.mqtt.client import CallbackAPIVersion, MQTTMessage, MQTTProtocolVersion
 from paho.mqtt.client import Client as PahoMQTTClient
 
+from hololinked import Serializers
 from hololinked.client.abstractions import (
     ConsumedThingAction,
     ConsumedThingEvent,
@@ -25,7 +26,7 @@
     OAuthDirectAccessGrant,
 )
 from hololinked.constants import ZMQ_TRANSPORTS
-from hololinked.core import Serializers, Thing
+from hololinked.core import Thing
 from hololinked.td.interaction_affordance import (
     ActionAffordance,
     EventAffordance,

hololinked/client/http/consumed_interactions.py

@@ -12,6 +12,7 @@
 import httpx
 import structlog
 
+from hololinked import Serializers
 from hololinked.client.abstractions import (
     SSE,
     ConsumedThingAction,
@@ -20,7 +21,6 @@
 )
 from hololinked.client.exceptions import raise_local_exception
 from hololinked.constants import Operations
-from hololinked.core import Serializers
 from hololinked.td.forms import Form
 from hololinked.td.interaction_affordance import (
     ActionAffordance,

hololinked/client/mqtt/consumed_interactions.py

@@ -9,8 +9,8 @@
 from paho.mqtt.client import Client as PahoMQTTClient
 from paho.mqtt.client import MQTTMessage
 
+from hololinked import Serializers
 from hololinked.client.abstractions import SSE, ConsumedThingEvent
-from hololinked.core import Serializers
 from hololinked.core.interfaces import BaseSerializer  # noqa: F401
 from hololinked.td.forms import Form
 from hololinked.td.interaction_affordance import EventAffordance, PropertyAffordance

hololinked/constants.py

@@ -8,6 +8,7 @@
 # types
 JSONSerializable = typing.Union[str, int, float, bool, None, typing.Dict[str, typing.Any], typing.List]
 JSON = typing.Dict[str, JSONSerializable]
+JSONSchema = typing.Dict[str, str | typing.Dict[str, typing.Any] | typing.List[typing.Dict[str, typing.Any]]]
 
 byte_types = (bytes, bytearray, memoryview)
 

hololinked/core/__init__.py

@@ -4,12 +4,57 @@
 State machines, meta classes, descriptor registries and the concrete implementation of how an operation is executed
 is also included here.
 """
-# Order of import is reflected in this file to avoid circular imports
-
-from .thing import *  # noqa
-from .events import *  # noqa
-from .actions import *  # noqa
-from .property import *  # noqa
-from .state_machine import StateMachine as StateMachine
-from .meta import ThingMeta as ThingMeta
-from .serializer_registry import Serializers as Serializers
+
+from typing import TYPE_CHECKING
+
+# Interfaces must be available to register adappters
+from .interfaces import BaseSchemaValidator as BaseSchemaValidator
+from .interfaces import BaseSerializer as BaseSerializer
+
+
+__all__ = [
+    "BaseSchemaValidator",
+    "BaseSerializer",
+    "action",
+    "Action",
+    "Event",
+    "ThingMeta",
+    "Property",
+    "StateMachine",
+    "Thing",
+]
+
+# Submodules that use SchemaValidatorClasses / Serializers are loaded lazily so
+# that hololinked/__init__.py can finish registering the adapters (schema_validators,
+# serializers) before any class body in meta.py / actions.py / property.py executes.
+_lazy: dict[str, tuple[str, str]] = {
+    "action": (".actions", "action"),
+    "Action": (".actions", "Action"),
+    "Event": (".events", "Event"),
+    "ThingMeta": (".meta", "ThingMeta"),
+    "Property": (".property", "Property"),
+    "StateMachine": (".state_machine", "StateMachine"),
+    "Thing": (".thing", "Thing"),
+}
+
+
+def __getattr__(name: str):
+    if name in _lazy:
+        import importlib
+
+        module_path, attr = _lazy[name]
+        mod = importlib.import_module(module_path, package=__name__)
+        val = getattr(mod, attr)
+        globals()[name] = val  # cache so subsequent access skips __getattr__
+        return val
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+if TYPE_CHECKING:
+    from .actions import Action as Action
+    from .actions import action as action
+    from .events import Event as Event
+    from .meta import ThingMeta as ThingMeta
+    from .property import Property as Property
+    from .state_machine import StateMachine as StateMachine
+    from .thing import Thing as Thing

hololinked/core/actions.py

@@ -9,30 +9,34 @@
 
 from pydantic import BaseModel, RootModel
 
-from ..constants import JSON
-from ..param.parameterized import ParameterizedFunction
-from ..schema_validators.validators import JSONSchemaValidator, PydanticSchemaValidator
-from ..utils import (
+from hololinked import SchemaValidatorClasses
+from hololinked.constants import JSON
+from hololinked.core.exceptions import StateMachineError
+from hololinked.param.parameterized import ParameterizedFunction
+from hololinked.utils import (
     get_input_model_from_signature,
     get_return_type_from_signature,
     has_async_def,
     isclassmethod,
     issubklass,
 )
+
 from .dataklasses import ActionInfoValidator
-from .exceptions import StateMachineError
 
 
 class Action:
     """
     Object that models an action.
+
     These actions are unbound and return a bound action when accessed using the owning object.
     """
 
     __slots__ = ["obj", "owner", "_execution_info"]
 
     def __init__(self, obj: MethodType) -> None:
         """
+        Initialize an Action.
+
         Parameters
         ----------
         obj: MethodType
@@ -69,13 +73,13 @@ def __call__(self, *args, **kwargs):
 
     @property
     def name(self) -> str:
-        """name of the action"""
+        """Name of the action."""
         return self.obj.__name__
 
     @property
     def execution_info(self) -> ActionInfoValidator:
         """
-        internal dataclass that holds all information about the action
+        Internal dataclass that holds all information about the action.
 
         TODO: this can be refactored
         """
@@ -107,9 +111,7 @@ def to_affordance(self, owner_inst=None):
 
 
 class BoundAction:
-    """
-    A bound action - base class for both sync and async methods.
-    """
+    """A bound action, base class for both sync and async methods."""
 
     __slots__ = [
         "obj",
@@ -173,14 +175,14 @@ def validate_call(self, args, kwargs: dict[str, Any]) -> None:
 
     @property
     def name(self) -> str:
-        """name of the action"""
+        """Name of the action."""
         return self.obj.__name__
 
     def __call__(self, *args, **kwargs):
         raise NotImplementedError("call must be implemented by subclass")
 
     def external_call(self, *args, **kwargs):
-        """validated call to the action with state machine and payload checks"""
+        """Validated call to the action with state machine and payload checks."""
         raise NotImplementedError("external_call must be implemented by subclass")
 
     def __str__(self):
@@ -224,7 +226,7 @@ class BoundSyncAction(BoundAction):
     """
 
     def external_call(self, *args, **kwargs):
-        """validated call to the action with state machine and payload checks"""
+        """Validated call to the action with state machine and payload checks"""
         self.validate_call(args, kwargs)
         return self.__call__(*args, **kwargs)
 
@@ -241,7 +243,7 @@ class BoundAsyncAction(BoundAction):
     """
 
     async def external_call(self, *args, **kwargs):
-        """validated call to the action with state machine and payload checks"""
+        """Validated call to the action with state machine and payload checks"""
         self.validate_call(args, kwargs)
         return await self.__call__(*args, **kwargs)
 
@@ -358,9 +360,9 @@ def inner(obj):
                 )
         if input_schema:
             if isinstance(input_schema, dict):
-                execution_info_validator.schema_validator = JSONSchemaValidator(input_schema)
+                execution_info_validator.schema_validator = SchemaValidatorClasses.json_schema(input_schema)
             elif issubklass(input_schema, (BaseModel, RootModel)):
-                execution_info_validator.schema_validator = PydanticSchemaValidator(input_schema)
+                execution_info_validator.schema_validator = SchemaValidatorClasses.pydantic(input_schema)
             else:
                 raise TypeError(
                     "input schema must be a JSON schema or a Pydantic model, got {}".format(type(input_schema))

hololinked/core/dataklasses.py

@@ -9,11 +9,11 @@
 
 from pydantic import BaseModel, RootModel
 
-from ..constants import USE_OBJECT_NAME
-from ..param.parameterized import ParameterizedMetaclass
-from ..param.parameters import Boolean, ClassSelector, Parameter, String, Tuple
-from ..schema_validators import BaseSchemaValidator
-from ..utils import issubklass
+from hololinked.constants import USE_OBJECT_NAME
+from hololinked.core.interfaces import BaseSchemaValidator
+from hololinked.param.parameterized import ParameterizedMetaclass
+from hololinked.param.parameters import Boolean, ClassSelector, Parameter, String, Tuple
+from hololinked.utils import issubklass
 
 
 # TODO, this class will be removed in future and merged directly into the corresponding object

hololinked/core/exceptions.py

@@ -1,38 +1,31 @@
-class BreakInnerLoop(Exception):
-    """raise to break an inner loop"""
+"""Exception classes."""
+
 
-    pass
+class BreakInnerLoop(Exception):
+    """Raise to break an inner loop."""
 
 
 class BreakAllLoops(Exception):
-    """raise to exit all loops"""
-
-    pass
+    """Raise to exit all loops."""
 
 
 class BreakLoop(Exception):
-    """raise and catch to exit a loop from within another function or method"""
-
-    pass
+    """Raise and catch to exit a loop from within another function or method."""
 
 
 class BreakFlow(Exception):
-    """raised to break the flow of the program"""
-
-    pass
+    """Raise to break the flow of the program."""
 
 
 # TODO - remove unused and reduce number of definitions
 
 
 class StateMachineError(Exception):
-    """raise to show errors while calling actions or writing properties in wrong state"""
-
-    pass
+    """Raise to show errors while calling actions or writing properties in wrong state."""
 
 
 class DatabaseError(Exception):
-    """raise to show database related errors"""
+    """Raise to show database related errors."""
 
 
 __all__ = ["BreakInnerLoop", "BreakAllLoops", "BreakLoop", "BreakFlow", "StateMachineError", "DatabaseError"]