Merge pull request #1460 from compas-dev/mro

serialize and deserilize mro

Author: Licini

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* Added `inheritance` field to `__jsondump__` of `compas.datastructures.Datastructure` to allow for deserialization to closest available superclass of custom datastructures.
+
 ### Changed
 
 ### Removed

docs/userguide/advanced.serialisation.rst

@@ -149,6 +149,50 @@ which will help with IntelliSense and code completion.
     boxes: List[Box] = session['boxes']
 
 
+Inheritance
+===========
+
+When working with custom classes that inherit from COMPAS datastructures, COMPAS will encode the inheritance chain in the serialized data. This allows the object to be reconstructed using the closest available superclass if the custom class is not available in the environment where the data is loaded.
+For example, a user can create a custom mesh class and serialize it to JSON:
+
+.. code-block:: python
+
+    from compas.datastructures import Mesh
+    from compas import json_dump
+
+    class CustomMesh(Mesh):
+        def __init__(self, *args, **kwargs):
+            super(CustomMesh, self).__init__(*args, **kwargs)
+            self.custom_mesh_attr = "custom_mesh"
+
+        @property
+        def __data__(self):
+            data = super(CustomMesh, self).__data__
+            data["custom_mesh_attr"] = self.custom_mesh_attr
+            return data
+
+        @classmethod
+        def __from_data__(cls, data):
+            obj = super(CustomMesh, cls).__from_data__(data)
+            obj.custom_mesh_attr = data.get("custom_mesh_attr", "")
+            return obj
+
+    # Create and serialize a custom mesh
+    custom_mesh = CustomMesh(name="test")
+    json_dump(custom_mesh, 'custom_mesh.json')
+
+If another user loads "custom_mesh.json" in an environment where the CustomMesh class is not available, COMPAS will reconstruct the object as an instance of its closest available superclass, which in this case is the regular Mesh class:
+
+.. code-block:: python
+
+    from compas.datastructures import Mesh
+    from compas import json_load
+
+    mesh = json_load('custom_mesh.json')
+    assert isinstance(mesh, Mesh) # This will be True
+
+
+
 Validation
 ==========
 

src/compas/data/data.py

@@ -75,6 +75,10 @@ def __init__(self, name=None):
     def __dtype__(self):
         return "{}/{}".format(".".join(self.__class__.__module__.split(".")[:2]), self.__class__.__name__)
 
+    @classmethod
+    def __clstype__(cls):
+        return "{}/{}".format(".".join(cls.__module__.split(".")[:2]), cls.__name__)
+
     @property
     def __data__(self):
         raise NotImplementedError

src/compas/data/encoders.py

@@ -40,14 +40,16 @@
     numpy_support = False
 
 
-def cls_from_dtype(dtype):  # type: (...) -> Type[Data]
+def cls_from_dtype(dtype, inheritance=None):  # type: (...) -> Type[Data]
     """Get the class object corresponding to a COMPAS data type specification.
 
     Parameters
     ----------
     dtype : str
         The data type of the COMPAS object in the following format:
         '{}/{}'.format(o.__class__.__module__, o.__class__.__name__).
+    inheritance : list[str], optional
+        The inheritance chain of this class, a list of superclasses that can be used if given dtype is not found.
 
     Returns
     -------
@@ -63,9 +65,23 @@ def cls_from_dtype(dtype):  # type: (...) -> Type[Data]
         If the module doesn't contain the specified data type.
 
     """
-    mod_name, attr_name = dtype.split("/")
-    module = __import__(mod_name, fromlist=[attr_name])
-    return getattr(module, attr_name)
+
+    if inheritance is None:
+        full_inheritance = [dtype]
+    else:
+        full_inheritance = [dtype] + inheritance
+
+    for dtype in full_inheritance:
+        mod_name, attr_name = dtype.split("/")
+        try:
+            module = __import__(mod_name, fromlist=[attr_name])
+            return getattr(module, attr_name)
+        except ImportError:
+            continue
+        except AttributeError:
+            continue
+
+    raise ValueError("No class found in inheritance chain: {}".format(full_inheritance))
 
 
 class DataEncoder(json.JSONEncoder):
@@ -220,7 +236,7 @@ def object_hook(self, o):
             return o
 
         try:
-            cls = cls_from_dtype(o["dtype"])
+            cls = cls_from_dtype(o["dtype"], o.get("inheritance", None))
 
         except ValueError:
             raise DecoderError(

src/compas/datastructures/datastructure.py

@@ -21,6 +21,51 @@ def __init__(self, attributes=None, name=None):
         self._aabb = None
         self._obb = None
 
+    @property
+    def __inheritance__(self):
+        """Get the inheritance chain of the datastructure.
+        Until one level above the Datastructure class (eg. Mesh, Graph, ...).
+
+        Returns
+        -------
+        list[str]
+            The inheritance chain of the datastructure.
+
+        """
+        inheritance = []
+        for cls in self.__class__.__mro__:
+            if cls == self.__class__:
+                continue
+            if cls == Datastructure:
+                break
+            inheritance.append(cls.__clstype__())
+        return inheritance
+
+    def __jsondump__(self, minimal=False):
+        """Return the required information for serialization with the COMPAS JSON serializer.
+
+        Parameters
+        ----------
+        minimal : bool, optional
+            If True, exclude the GUID from the dump dict.
+
+        Returns
+        -------
+        dict
+
+        """
+        state = {
+            "dtype": self.__dtype__,
+            "data": self.__data__,
+            "inheritance": self.__inheritance__,
+        }
+        if minimal:
+            return state
+        if self._name is not None:
+            state["name"] = self._name
+        state["guid"] = str(self.guid)
+        return state
+
     @property
     def aabb(self):
         if self._aabb is None:

tests/compas/datastructures/test_datastructure.py

@@ -0,0 +1,173 @@
+import pytest
+import compas
+from compas.datastructures import Datastructure
+from compas.datastructures import Mesh
+from compas.data import json_dumps, json_loads
+
+
+class Level1(Datastructure):
+    def __init__(self, attributes=None, name=None):
+        super(Level1, self).__init__(attributes=attributes, name=name)
+        self.level1_attr = "level1"
+
+    @property
+    def __data__(self):
+        return {"attributes": self.attributes, "level1_attr": self.level1_attr}
+
+    @classmethod
+    def __from_data__(cls, data):
+        obj = cls(attributes=data.get("attributes"))
+        obj.level1_attr = data.get("level1_attr", "")
+        return obj
+
+
+@pytest.fixture
+def level2():
+    # Level2 is a custom class that is not available outside of this local scope
+    class Level2(Level1):
+        def __init__(self, attributes=None, name=None):
+            super(Level2, self).__init__(attributes=attributes, name=name)
+            self.level2_attr = "level2"
+
+        @property
+        def __data__(self):
+            data = super(Level2, self).__data__
+            data["level2_attr"] = self.level2_attr
+            return data
+
+        @classmethod
+        def __from_data__(cls, data):
+            obj = super(Level2, cls).__from_data__(data)
+            obj.level2_attr = data.get("level2_attr", "")
+            return obj
+
+    # return an instance of Level2
+    return Level2(name="test")
+
+
+@pytest.fixture
+def level3():
+    # Level2 and Level3 are custom classes that are not available outside of this local scope
+    class Level2(Level1):
+        def __init__(self, attributes=None, name=None):
+            super(Level2, self).__init__(attributes=attributes, name=name)
+            self.level2_attr = "level2"
+
+        @property
+        def __data__(self):
+            data = super(Level2, self).__data__
+            data["level2_attr"] = self.level2_attr
+            return data
+
+        @classmethod
+        def __from_data__(cls, data):
+            obj = super(Level2, cls).__from_data__(data)
+            obj.level2_attr = data.get("level2_attr", "")
+            return obj
+
+    class Level3(Level2):
+        def __init__(self, attributes=None, name=None):
+            super(Level3, self).__init__(attributes=attributes, name=name)
+            self.level3_attr = "level3"
+
+        @property
+        def __data__(self):
+            data = super(Level3, self).__data__
+            data["level3_attr"] = self.level3_attr
+            return data
+
+        @classmethod
+        def __from_data__(cls, data):
+            obj = super(Level3, cls).__from_data__(data)
+            obj.level3_attr = data.get("level3_attr", "")
+            return obj
+
+    # return an instance of Level3
+    return Level3(name="test")
+
+
+@pytest.fixture
+def custom_mesh():
+    class CustomMesh(Mesh):
+        def __init__(self, *args, **kwargs):
+            super(CustomMesh, self).__init__(*args, **kwargs)
+            self.custom_mesh_attr = "custom_mesh"
+
+        @property
+        def __data__(self):
+            data = super(CustomMesh, self).__data__
+            data["custom_mesh_attr"] = self.custom_mesh_attr
+            return data
+
+        @classmethod
+        def __from_data__(cls, data):
+            obj = super(CustomMesh, cls).__from_data__(data)
+            obj.custom_mesh_attr = data.get("custom_mesh_attr", "")
+            return obj
+
+    return CustomMesh(name="test")
+
+
+def test_inheritance_fallback(level2):
+    if compas.IPY:
+        # IronPython is not able to deserialize a class that is defined in a local scope like Level1.
+        # We skip this tests for IronPython.
+        return
+
+    assert level2.__jsondump__()["dtype"] == "test_datastructure/Level2"
+    # Level2 should serialize Level1 into the inheritance
+    assert level2.__jsondump__()["inheritance"] == ["test_datastructure/Level1"]
+
+    dumped = json_dumps(level2)
+    loaded = json_loads(dumped)
+
+    # The loaded object should be deserialized as the closes available class: Level1
+    assert loaded.__class__ == Level1
+    assert loaded.__jsondump__()["dtype"] == "test_datastructure/Level1"
+    assert loaded.__jsondump__()["inheritance"] == []
+
+    # level1 attributes should still be available
+    assert loaded.level1_attr == "level1"
+    # Meanwhile, level2 attributes will be discarded
+    assert not hasattr(loaded, "level2_attr")
+
+
+def test_inheritance_fallback_multi_level(level3):
+    if compas.IPY:
+        # IronPython is not able to deserialize a class that is defined in a local scope like Level1.
+        # We skip this tests for IronPython.
+        return
+
+    assert level3.__jsondump__()["dtype"] == "test_datastructure/Level3"
+    # Level3 should serialize Level2 and Level1 into the inheritance
+    assert level3.__jsondump__()["inheritance"] == ["test_datastructure/Level2", "test_datastructure/Level1"]
+
+    dumped = json_dumps(level3)
+    loaded = json_loads(dumped)
+
+    # The loaded object should be deserialized as the closes available class: Level1
+    assert loaded.__class__ == Level1
+    assert loaded.__jsondump__()["dtype"] == "test_datastructure/Level1"
+    assert loaded.__jsondump__()["inheritance"] == []
+
+    # level1 attributes should still be available
+    assert loaded.level1_attr == "level1"
+
+    # level2 and 3 attributes will be discarded
+    assert not hasattr(loaded, "level2_attr")
+    assert not hasattr(loaded, "level3_attr")
+
+
+def test_custom_mesh(custom_mesh):
+    # This test should pass both Python and IronPython
+    assert custom_mesh.__jsondump__()["dtype"].endswith("CustomMesh")
+    assert custom_mesh.__jsondump__()["inheritance"] == ["compas.datastructures/Mesh"]
+    assert custom_mesh.__jsondump__()["data"]["custom_mesh_attr"] == "custom_mesh"
+
+    dumped = json_dumps(custom_mesh)
+    loaded = json_loads(dumped)
+
+    assert loaded.__class__ == Mesh
+    assert loaded.__jsondump__()["dtype"] == "compas.datastructures/Mesh"
+    assert loaded.__jsondump__()["inheritance"] == []
+    assert not hasattr(loaded, "custom_mesh_attr")