Add unfold option to diff endpoint

terminusdb_client/client/Client.py

@@ -2403,7 +2403,9 @@ def diff_object(self, before_object, after_object):
             )
         )
 
-    def diff_version(self, before_version, after_version):
+    def diff_version(
+        self, before_version, after_version, unfold: bool = True
+    ):
         """Diff two different versions. Can either be a branch or a commit
 
         Parameters
@@ -2412,6 +2414,10 @@ def diff_version(self, before_version, after_version):
             Commit or branch of the before version to compare
         after_version : string
             Commit or branch of the after version to compare
+        unfold : bool, optional
+            Expand subdocuments inline when retrieving documents from the
+            specified versions. Defaults to ``True``; set to ``False`` to
+            compare folded documents by reference.
         """
         self._check_connection(check_db=False)
         return json.loads(
@@ -2422,6 +2428,7 @@ def diff_version(self, before_version, after_version):
                     json={
                         "before_data_version": before_version,
                         "after_data_version": after_version,
+                        "unfold": unfold,
                     },
                     auth=self._auth(),
                 )
@@ -2447,13 +2454,21 @@ def diff(
             List["DocumentTemplate"],  # noqa:F821
         ],
         document_id: Union[str, None] = None,
+        unfold: bool = True,
     ):
         """DEPRECATED
 
         Perform diff on 2 set of document(s), result in a Patch object.
 
         Do not connect when using public API.
 
+        Parameters
+        ----------
+        unfold : bool, optional
+            Expand subdocuments inline when retrieving documents from commits
+            or branches. Only used when ``before`` or ``after`` is a version
+            reference. Defaults to ``True``.
+
         Returns
         -------
         obj
@@ -2482,6 +2497,9 @@ def diff(
                 raise ValueError(
                     "`document_id` can only be used in conjusction with a data version or commit ID as `before`, not a document object"
                 )
+        if isinstance(before, str) or isinstance(after, str):
+            request_dict["unfold"] = unfold
+
         if self._connected:
             result = _finish_response(
                 self._session.post(

terminusdb_client/tests/test_Client.py

@@ -745,3 +745,182 @@ def test_convert_document_keeps_prefixed_and_schema_ids():
         [{"@id": "Coordinate", "@type": "Class"}], "schema"
     )
     assert docs[0]["@id"] == "Coordinate"
+
+
+@mock.patch.object(requests.Session, "head", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "get", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "post", side_effect=mocked_request_success)
+def test_diff_version(mocked_post, mocked_get, mocked_head):
+    client = Client("http://localhost:6363", user="admin", key="root", team="admin")
+    client.connect(db="myDBName")
+
+    client.diff_version("main", "changes")
+
+    client._session.post.assert_called_once_with(
+        "http://localhost:6363/api/diff/admin/myDBName/local/branch/main",
+        auth=("admin", "root"),
+        headers={"user-agent": f"terminusdb-client-python/{__version__}"},
+        json={
+            "before_data_version": "main",
+            "after_data_version": "changes",
+            "unfold": True,
+        },
+    )
+
+
+@mock.patch.object(requests.Session, "head", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "get", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "post", side_effect=mocked_request_success)
+def test_diff_version_folded(mocked_post, mocked_get, mocked_head):
+    client = Client("http://localhost:6363", user="admin", key="root", team="admin")
+    client.connect(db="myDBName")
+
+    client.diff_version("main", "changes", unfold=False)
+
+    client._session.post.assert_called_once_with(
+        "http://localhost:6363/api/diff/admin/myDBName/local/branch/main",
+        auth=("admin", "root"),
+        headers={"user-agent": f"terminusdb-client-python/{__version__}"},
+        json={
+            "before_data_version": "main",
+            "after_data_version": "changes",
+            "unfold": False,
+        },
+    )
+
+
+@mock.patch.object(requests.Session, "head", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "get", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "post", side_effect=mocked_request_success)
+def test_diff_versions(mocked_post, mocked_get, mocked_head):
+    client = Client("http://localhost:6363", user="admin", key="root", team="admin")
+    client.connect(db="myDBName")
+
+    result = client.diff("main", "changes")
+
+    client._session.post.assert_called_once_with(
+        "http://localhost:6363/api/diff/admin/myDBName/local/branch/main",
+        auth=("admin", "root"),
+        headers={"user-agent": f"terminusdb-client-python/{__version__}"},
+        json={
+            "before_data_version": "main",
+            "after_data_version": "changes",
+            "unfold": True,
+        },
+    )
+    assert result.content is not None
+
+
+@mock.patch.object(requests.Session, "head", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "get", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "post", side_effect=mocked_request_success)
+def test_diff_versions_folded(mocked_post, mocked_get, mocked_head):
+    client = Client("http://localhost:6363", user="admin", key="root", team="admin")
+    client.connect(db="myDBName")
+
+    client.diff("main", "changes", unfold=False)
+
+    client._session.post.assert_called_once_with(
+        "http://localhost:6363/api/diff/admin/myDBName/local/branch/main",
+        auth=("admin", "root"),
+        headers={"user-agent": f"terminusdb-client-python/{__version__}"},
+        json={
+            "before_data_version": "main",
+            "after_data_version": "changes",
+            "unfold": False,
+        },
+    )
+
+
+@mock.patch.object(requests.Session, "head", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "get", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "post", side_effect=mocked_request_success)
+def test_diff_version_and_document(mocked_post, mocked_get, mocked_head):
+    client = Client("http://localhost:6363", user="admin", key="root", team="admin")
+    client.connect(db="myDBName")
+    janine = {"@id": "Person/Janine", "@type": "Person", "name": "Janine"}
+
+    client.diff("main", janine)
+
+    client._session.post.assert_called_once_with(
+        "http://localhost:6363/api/diff/admin/myDBName/local/branch/main",
+        auth=("admin", "root"),
+        headers={"user-agent": f"terminusdb-client-python/{__version__}"},
+        json={
+            "before_data_version": "main",
+            "after": janine,
+            "unfold": True,
+        },
+    )
+
+
+@mock.patch.object(requests.Session, "head", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "get", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "post", side_effect=mocked_request_success)
+def test_diff_documents_no_unfold(mocked_post, mocked_get, mocked_head):
+    client = Client("http://localhost:6363", user="admin", key="root", team="admin")
+    client.connect(db="myDBName")
+    jane = {"@id": "Person/Jane", "@type": "Person", "name": "Jane"}
+    janine = {"@id": "Person/Jane", "@type": "Person", "name": "Janine"}
+
+    client.diff(jane, janine)
+
+    client._session.post.assert_called_once_with(
+        "http://localhost:6363/api/diff/admin/myDBName/local/branch/main",
+        auth=("admin", "root"),
+        headers={"user-agent": f"terminusdb-client-python/{__version__}"},
+        json={"before": jane, "after": janine},
+    )
+
+
+@mock.patch.object(requests.Session, "head", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "get", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "post", side_effect=mocked_request_success)
+def test_diff_document_id(mocked_post, mocked_get, mocked_head):
+    client = Client("http://localhost:6363", user="admin", key="root", team="admin")
+    client.connect(db="myDBName")
+    janine = {"@id": "Person/Jane", "@type": "Person", "name": "Janine"}
+
+    client.diff("commit123", janine, document_id="Person/Jane")
+
+    client._session.post.assert_called_once_with(
+        "http://localhost:6363/api/diff/admin/myDBName/local/branch/main",
+        auth=("admin", "root"),
+        headers={"user-agent": f"terminusdb-client-python/{__version__}"},
+        json={
+            "before_data_version": "commit123",
+            "after": janine,
+            "document_id": "terminusdb:///data/Person/Jane",
+            "unfold": True,
+        },
+    )
+
+
+@mock.patch.object(requests, "post", side_effect=mocked_request_success)
+def test_diff_no_connection(mocked_post):
+    client = Client("http://localhost:6363")
+
+    result = client.diff("main", "changes")
+
+    mocked_post.assert_called_once_with(
+        "http://localhost:6363",
+        headers={"user-agent": f"terminusdb-client-python/{__version__}"},
+        json={
+            "before_data_version": "main",
+            "after_data_version": "changes",
+            "unfold": True,
+        },
+    )
+    assert result.content is not None
+
+
+@mock.patch.object(requests.Session, "head", side_effect=mocked_request_success)
+@mock.patch.object(requests.Session, "get", side_effect=mocked_request_success)
+def test_diff_document_id_invalid(mocked_get, mocked_head):
+    client = Client("http://localhost:6363", user="admin", key="root", team="admin")
+    client.connect(db="myDBName")
+    jane = {"@id": "Person/Jane", "@type": "Person", "name": "Jane"}
+    janine = {"@id": "Person/Jane", "@type": "Person", "name": "Janine"}
+
+    with pytest.raises(ValueError):
+        client.diff(jane, janine, document_id="Person/Jane")