Merge branch 'main' into fix-doctest

Author: tomvanmele

CHANGELOG.md

@@ -9,13 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* Added instructions for creating new data types to the dev guide.
+
 ### Changed
 
 * Fixed `RuntimeError` when using `compas_rhino.unload_modules` in CPython`. 
 * Fixed bug in `Box.scaled` causing a `TypeError` due to incorrect parameter forwarding.
 * Changed argument names of `Box.scale()` to `x`, `y`, `z`, instead of `factor` and made `y` and `z` optional to keep positional arguments backwards compatible.
 * Fixed import errors in `compas_rhino.conduits` for Rhino 8.
 * Fixed doctest failures.
+* Fixed bug in serialization when `compas.datastructures.attributes.AttributeView` is used.
 
 ### Removed
 
@@ -27,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 * Fixed support for `compas_gpython` in Rhino 8 Grasshopper CPython components.
+* Changed installation instructions for Rhino 8 in the user guide.
 * Fixed `Graph.from_edges` always returning `None`.
 
 ### Removed

docs/devguide/dtypes.rst

@@ -1,2 +1,184 @@
 Implementing a New Data Type
 ============================
+
+COMPAS data types are classes that are based on :class:`compas.data.Data`.
+
+Data types can be serialized to JSON with
+
+* :func:`compas.json_dump`
+* :func:`compas.json_dumps`
+* :func:`compas.json_dumpz`
+
+and deserialized with the corresponding "load" functions
+
+* :func:`compas.json_load`
+* :func:`compas.json_loads`
+* :func:`compas.json_loadz`
+
+All geometry objects and data structures,
+and also, for example, the visualization scene,
+are serializable data types.
+
+
+Creating a new data type
+========================
+
+In most cases, it is sufficient to implement the ``__data__`` property when creating your custom `Data` class.
+
+.. code-block:: python
+
+    class SomeThing(Data):
+
+        def __init__(self, a, b)
+            super().__init__()
+            # note that if the code needs to be compatible with IronPython
+            # you should write the following:
+            # super(SomeThing, self).__init__()
+            self.a = a
+            self.b = b
+
+        @property
+        def __data__(self):
+            return {
+                "a": self.a,
+                "b": self.b,
+            }
+
+
+>>> custom = SomeThing(a=1, b=2)
+>>> compas.json_dump(custom, "custom.json")
+>>> result = compas.json_load("custom.json")
+>>> isinstance(result, SomeThing)
+True
+>>> result.a
+1
+>>> result.b
+2
+
+If the attributes stored in the data dictionary defined by the ``__data__`` property
+are different from the initialization parameters of the class,
+you must also customize the ``__from_data__`` class method to compensate for the difference.
+
+.. code-block:: python
+
+    class SomeThing(Data):
+
+        def __init__(self)
+            super().__init__()
+            # note that if the code needs to be compatible with IronPython
+            # you should write the following:
+            # super(SomeThing, self).__init__()
+            self.items = []
+
+        @property
+        def __data__(self):
+            return {
+                "items": self.items,
+            }
+
+        @classmethod
+        def __from_data__(cls, data):
+            custom = cls()
+            for item in data['items']:
+                custom.add(item)
+            return custom
+
+        def add(self, item):
+            self.items.append(item)
+
+
+>>> custom = SomeThing()
+>>> custom.add(1)
+>>> custom.add(2)
+>>> compas.json_dump(custom, "custom.json")
+>>> result = compas.json_load("custom.json")
+>>> isinstance(result, SomeThing)
+True
+>>> result.items
+[1, 2]
+
+
+Attribute types
+===============
+
+Any attribute that is an instance of a Python base type or a serializable COMPAS data object
+can be included in the data dict created by the ``__data__`` property without further processing.
+The serialization process will recursively serialize all these attributes.
+
+.. code-block:: python
+
+    class SomeThing(Data):
+
+        def __init__(self, point, frame, mesh):
+            super().__init__()
+            # note that if the code needs to be compatible with IronPython
+            # you should write the following:
+            # super(SomeThing, self).__init__()
+            self.point = point
+            self.frame = frame
+            self.mesh = mesh
+
+        @property
+        def __data__(self):
+            return {
+                "point": self.point,
+                "frame": self.frame,
+                "mesh": self.mesh,
+            }
+
+
+>>> import compas
+>>> from compas.geometry import Point, Frame
+>>> from compas.datastructures import Mesh
+>>> point = Point(1, 2, 3)
+>>> frame = Frame()
+>>> mesh = Mesh.from_meshgrid(10, 10)
+>>> custom = SomeThing(point, frame, mesh)
+>>> compas.json_dump(custom, "custom.json")
+>>> result = compas.json_load("custom.json")
+>>> isinstance(result.point, Point)
+True
+>>> isinstance(result.frame, Frame)
+True
+>>> isinstance(result.mesh, Mesh)
+True
+>>> result.point == point
+True
+>>> result.point is point
+False
+
+
+Note that the the automatic serialization process will incur overhead information
+that increases the size of the resulting JSON file.
+The performance impact may be significant when many of these instances are serialized.
+
+To avoid this, anticipated conversions can be included explicitly in `__data__` and `__from_data__`.
+
+.. code-block:: python
+
+    class SomeThing(Data):
+
+        def __init__(self, point, frame, mesh):
+            super().__init__()
+            # note that if the code needs to be compatible with IronPython
+            # you should write the following:
+            # super(SomeThing, self).__init__()
+            self.point = point
+            self.frame = frame
+            self.mesh = mesh
+
+        @property
+        def __data__(self):
+            return {
+                "point": self.point.__data__,
+                "frame": self.frame.__data__,
+                "mesh": self.mesh.__data__,
+            }
+
+        @classmethod
+        def __from_data__(cls, data):
+            return cls(
+                Point.__from_data__(data['point']),
+                Frame.__from_data__(data['frame']),
+                Mesh.__from_data__(data['mesh']),
+            )

src/compas/data/encoders.py

@@ -115,6 +115,7 @@ def default(self, o):
             The serialized object.
 
         """
+        from compas.datastructures.attributes import AttributeView
 
         if hasattr(o, "__jsondump__"):
             return o.__jsondump__(minimal=DataEncoder.minimal)
@@ -153,6 +154,9 @@ def default(self, o):
             if isinstance(o, (System.Decimal, System.Double, System.Single)):
                 return float(o)
 
+        if isinstance(o, AttributeView):
+            return dict(o)
+
         return super(DataEncoder, self).default(o)
 
 

tests/compas/data/test_json.py

@@ -20,23 +20,23 @@ def test_json_native():
 
 def test_json_primitive():
     before = Point(0, 0, 0)
-    after = compas.json_loads(compas.json_dumps(before))
+    after = compas.json_loads(compas.json_dumps(before))  # type: Point
     assert before.__dtype__ == after.__dtype__
     assert all(a == b for a, b in zip(before, after))
     assert before.guid == after.guid
 
 
 def test_json_shape():
     before = Box(frame=Frame(Point(0, 0, 0), Vector(1, 0, 0), Vector(0, 1, 0)), xsize=1, ysize=1, zsize=1)
-    after = compas.json_loads(compas.json_dumps(before))
+    after = compas.json_loads(compas.json_dumps(before))  # type: Box
     assert before.__dtype__ == after.__dtype__
     assert all(a == b for a, b in zip(before.to_vertices_and_faces()[0], after.to_vertices_and_faces()[0]))
     assert before.guid == after.guid
 
 
 def test_json_xform():
     before = Transformation.from_frame_to_frame(Frame.worldXY(), Frame.worldXY())
-    after = compas.json_loads(compas.json_dumps(before))
+    after = compas.json_loads(compas.json_dumps(before))  # type: Transformation
     assert before.__dtype__ == after.__dtype__
     assert all(a == b for a, b in zip(before, after))
     assert before.guid == after.guid
@@ -47,7 +47,7 @@ def test_json_graph():
     a = before.add_node()
     b = before.add_node()
     before.add_edge(a, b)
-    after = compas.json_loads(compas.json_dumps(before))
+    after = compas.json_loads(compas.json_dumps(before))  # type: Graph
     assert before.__dtype__ == after.__dtype__
     # assert before.attributes == after.attributes
     assert all(before.has_node(node) for node in after.nodes())
@@ -59,7 +59,7 @@ def test_json_graph():
 
 def test_json_mesh():
     before = Mesh.from_vertices_and_faces([[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0]], [[0, 1, 2, 3]])
-    after = compas.json_loads(compas.json_dumps(before))
+    after = compas.json_loads(compas.json_dumps(before))  # type: Mesh
     assert before.__dtype__ == after.__dtype__
     # assert before.attributes == after.attributes
     assert all(before.has_vertex(vertex) for vertex in after.vertices())
@@ -95,7 +95,7 @@ def test_json_volmesh():
             ]
         ],
     )
-    after = compas.json_loads(compas.json_dumps(before))
+    after = compas.json_loads(compas.json_dumps(before))  # type: VolMesh
     assert before.__dtype__ == after.__dtype__
     # assert before.attributes == after.attributes
     assert all(before.has_vertex(vertex) for vertex in after.vertices())
@@ -121,12 +121,34 @@ def test_json_zip():
 
     before = Box(frame=Frame(Point(0, 0, 0), Vector(1, 0, 0), Vector(0, 1, 0)), xsize=2, ysize=5, zsize=3)
     compas.json_dumpz(before, zipfile_name)
-    after = compas.json_loadz(zipfile_name)
+    after = compas.json_loadz(zipfile_name)  # type: Box
     assert before.__dtype__ == after.__dtype__
     assert all(a == b for a, b in zip(before.to_vertices_and_faces()[0], after.to_vertices_and_faces()[0]))
     assert before.guid == after.guid
 
 
+def test_json_attributeview():
+    mesh = Mesh.from_meshgrid(10, 10)
+    before = Mesh()
+    for vertex in mesh.vertices():
+        attr = mesh.vertex_attributes(vertex)
+        before.add_vertex(key=vertex, attr_dict=attr)
+    for face in mesh.faces():
+        attr = mesh.face_attributes(face)
+        before.add_face(vertices=mesh.face_vertices(face), fkey=face, attr_dict=attr)
+    after = compas.json_loads(compas.json_dumps(before))  # type: Mesh
+
+    assert before.__dtype__ == after.__dtype__
+    assert all(before.has_vertex(vertex) for vertex in after.vertices())
+    assert all(after.has_vertex(vertex) for vertex in before.vertices())
+    assert all(before.has_face(face) for face in after.faces())
+    assert all(after.has_face(face) for face in before.faces())
+    assert all(before.has_edge(edge) for edge in after.edges())
+    assert all(after.has_edge(edge) for edge in before.edges())
+    assert all(before.face_vertices(a) == after.face_vertices(b) for a, b in zip(before.faces(), after.faces()))
+    assert before.guid == after.guid
+
+
 # temporarily commented because folder does not exist yet on main
 # def test_json_url():
 #     data = compas.json_load('https://raw.githubusercontent.com/compas-dev/compas/main/src/compas/data/schemas/graph.json')