docstring etc.

Author: Licini

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Added `compas_rhino8` as starting point for Rhino8 support.
 * Added tutorial for `compas.datastructures.Tree`.
+* Added `compas.datastructures.HashTree` and `compas.datastructures.HashNode`.
 
 ### Changed
 

src/compas/datastructures/__init__.py

@@ -165,6 +165,7 @@
 from .cell_network.cell_network import CellNetwork
 
 from .tree.tree import Tree, TreeNode
+from .tree.hashtree import HashTree, HashNode
 
 __all__ = [
     "Datastructure",
@@ -280,6 +281,8 @@
     # Trees
     "Tree",
     "TreeNode",
+    "HashTree",
+    "HashNode",
 ]
 
 if not compas.IPY:

src/compas/datastructures/tree/hashtree.py

@@ -4,11 +4,35 @@
 import hashlib
 
 
-def sha256(content):
-    return hashlib.sha256(json_dumps(content).encode()).hexdigest()
-
-
 class HashNode(TreeNode):
+    """A node in a HashTree. This class is used internally by the HashTree class.
+
+    Parameters
+    ----------
+    path : str
+        The relative path of the node.
+    value : str, int, float, list, bool, None
+        The value of the node. Only leaf nodes can have a value.
+
+    Attributes
+    ----------
+    path : str
+        The relative path of the node.
+    value : str, int, float, list, bool, None
+        The value of the node. Only leaf nodes can have a value.
+    absolute_path : str
+        The absolute path of the node.
+    is_value : bool
+        True if the node is a leaf node and has a value.
+    signature : str
+        The SHA256 signature of the node.
+    children_dict : dict
+        A dictionary of the children of the node. The keys are the relative paths
+    children_paths : list[str]
+        A list of the relative paths of the children of the node.
+
+    """
+
     def __init__(self, path, value=None):
         super().__init__()
         self.path = path
@@ -46,6 +70,21 @@ def children_paths(self):
 
     @classmethod
     def from_dict(cls, data_dict, path=""):
+        """Construct a HashNode from a dictionary.
+
+        Parameters
+        ----------
+        data_dict : dict
+            A dictionary to construct the HashNode from.
+        path : str
+            The relative path of the node.
+
+        Returns
+        -------
+        :class:`compas.datastructures.HashNode`
+            A HashNode constructed from the dictionary.
+
+        """
         node = cls(path)
         for key in data_dict:
             path = ".{}".format(key)
@@ -59,40 +98,128 @@ def from_dict(cls, data_dict, path=""):
 
 
 class HashTree(Tree):
+    """A Hash tree (or Merkle tree) is a tree in which every leaf node is labelled with the cryptographic hash of a data block
+    and every non-leaf node is labelled with the hash of the labels of its child nodes.
+    Hash trees allow efficient and secure verification of the contents of large data structures.
+    They can also be used to compare different versions(states) of the same data structure for changes.
+
+    Attributes
+    ----------
+    signatures : dict[str, str]
+        The SHA256 signatures of the nodes in the tree. The keys are the absolute paths of the nodes, the values are the signatures.
+
+
+    Examples
+    --------
+    >>> tree1 = HashTree.from_dict({"a": {"b": 1, "c": 3}, "d": [1, 2, 3], "e": 2})
+    >>> tree2 = HashTree.from_dict({"a": {"b": 1, "c": 2}, "d": [1, 2, 3], "f": 2})
+    >>> tree1.print_hierarchy()
+    └── ROOT @ 4cd56
+        ├── .a @ c16fd
+        │   ├── .b:1 @ c9b55
+        │   └── .c:3 @ 518d4
+        ├── .d:[1, 2, 3] @ 9be3a
+        └── .e:2 @ 68355
+    >>> tree2.print_hierarchy()
+    └── ROOT @ fbe39
+        ├── .a @ c2022
+        │   ├── .b:1 @ c9b55
+        │   └── .c:2 @ e3365
+        ├── .d:[1, 2, 3] @ 9be3a
+        └── .f:2 @ 93861
+    >>> tree2.print_diff(tree1)
+    Added:
+    {'path': '.f', 'value': 2}
+    Removed:
+    {'path': '.e', 'value': 2}
+    Modified:
+    {'path': '.a.c', 'old': 3, 'new': 2}
+
+
+    """
+
     def __init__(self):
         super().__init__()
         self.signatures = {}
 
     @classmethod
     def from_dict(cls, data_dict):
+        """Construct a HashTree from a dictionary.
+
+        Parameters
+        ----------
+        data_dict : dict
+            A dictionary to construct the HashTree from.
+
+        Returns
+        -------
+        :class:`compas.datastructures.HashTree`
+            A HashTree constructed from the dictionary.
+
+        """
         tree = cls()
         root = HashNode.from_dict(data_dict)
         tree.add(root)
-        tree.calculate_signatures()
+        tree.node_signature(tree.root)
         return tree
 
-    def calculate_signatures(self):
-        self.node_signature(self.root)
+    @classmethod
+    def from_object(cls, obj):
+        """Construct a HashTree from a COMPAS object."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_scene(cls, scene):
+        """Construct a HashTree from a COMPAS scene."""
+        raise NotImplementedError
 
     def node_signature(self, node, parent_path=""):
+        """Compute the SHA256 signature of a node. The computed nodes are cached in `self.signatures` dictionary.
+
+        Parameters
+        ----------
+        node : :class:`compas.datastructures.HashNode`
+            The node to compute the signature of.
+        parent_path : str
+            The absolute path of the parent node.
+
+        Returns
+        -------
+        str
+            The SHA256 signature of the node.
+
+        """
         absolute_path = parent_path + node.path
         if absolute_path in self.signatures:
             return self.signatures[absolute_path]
 
-        signature = sha256(
-            {
-                "path": node.path,
-                "value": node.value,
-                "children": [self.node_signature(child, absolute_path) for child in node.children],
-            }
-        )
+        content = {
+            "path": node.path,
+            "value": node.value,
+            "children": [self.node_signature(child, absolute_path) for child in node.children],
+        }
+
+        signature = hashlib.sha256(json_dumps(content).encode()).hexdigest()
 
         self.signatures[absolute_path] = signature
         node._signature = signature
 
         return signature
 
     def diff(self, other):
+        """Compute the difference between two HashTrees.
+
+        Parameters
+        ----------
+        other : :class:`compas.datastructures.HashTree`
+            The HashTree to compare with.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the differences between the two HashTrees. The keys are `added`, `removed` and `modified`.
+            The values are lists of dictionaries containing the paths and values of the nodes that were added, removed or modified.
+        """
         added = []
         removed = []
         modified = []
@@ -123,6 +250,15 @@ def _diff(node1, node2):
         return {"added": added, "removed": removed, "modified": modified}
 
     def print_diff(self, other):
+        """Print the difference between two HashTrees.
+
+        Parameters
+        ----------
+        other : :class:`compas.datastructures.HashTree`
+            The HashTree to compare with.
+
+        """
+
         diff = self.diff(other)
         print("Added:")
         for item in diff["added"]:
@@ -133,27 +269,3 @@ def print_diff(self, other):
         print("Modified:")
         for item in diff["modified"]:
             print(item)
-
-
-if __name__ == "__main__":
-
-    print("\nCOMPARE DICTS:")
-    tree1 = HashTree.from_dict({"a": {"b": 1, "c": 3}, "d": [1, 2, 3], "e": 2})
-    tree2 = HashTree.from_dict({"a": {"b": 1, "c": 2}, "d": [1, 2, 3], "f": 2})
-
-    tree1.print_hierarchy()
-    tree2.print_hierarchy()
-
-    tree2.print_diff(tree1)
-
-    print("\nCOMPARE MESH CHANGE:")
-
-    from compas.datastructures import Mesh
-
-    mesh = Mesh.from_polyhedron(4)
-    tree1 = HashTree.from_dict(mesh.data)
-    mesh.vertex_attribute(0, "x", 1.0)
-    tree2 = HashTree.from_dict(mesh.data)
-    tree1.print_hierarchy()
-    tree2.print_hierarchy()
-    tree2.print_diff(tree1)