RDBC-1023: add session.advanced.what_changed_for(entity) and get_tracked_entities()

redknightlois · redknightlois · commit 2bf82dad516d · 2026-02-25T20:26:36.000-03:00
C# Advanced.WhatChangedFor(entity) returns DocumentsChanges[] for a single entity. Python had no equivalent. Added _what_changed_for() to InMemoryDocumentSessionOperations and exposed it via Advanced.what_changed_for().

Matches C# behaviour: returns [DocumentDeleted] immediately when the entity has been deleted in the same session, before running the JSON diff.

C# Advanced.GetTrackedEntities() returns a dict of all entities currently tracked by the session (stored and deleted). Added _get_tracked_entities() to InMemoryDocumentSessionOperations and exposed it via Advanced.get_tracked_entities(). Each entry maps document ID to a dict with keys: id, entity, is_deleted.
Matches C# behaviour: entries deleted by string ID (present in _known_missing_ids but absent from _deleted_entities) appear with is_deleted=True.

Regression tests: test_session_advanced_api.py verifies that what_changed_for() returns per-entity changes and correctly reports DocumentDeleted when the entity
is deleted before the call; get_tracked_entities() includes newly stored entities with is_deleted=False and entries deleted by string id with is_deleted=True.
diff --git a/ravendb/documents/session/document_session.py b/ravendb/documents/session/document_session.py
@@ -802,6 +802,12 @@ def graph_query(self, object_type: type, query: str):  # -> GraphDocumentQuery:
         def what_changed(self) -> Dict[str, List[DocumentsChanges]]:
             return self._session._what_changed()
 
+        def what_changed_for(self, entity: object) -> List[DocumentsChanges]:
+            return self._session._what_changed_for(entity)
+
+        def get_tracked_entities(self) -> Dict[str, dict]:
+            return self._session._get_tracked_entities()
+
         def exists(self, key: str) -> bool:
             if key is None:
                 raise ValueError("Key cannot be None")
diff --git a/ravendb/documents/session/document_session_operations/in_memory_document_session_operations.py b/ravendb/documents/session/document_session_operations/in_memory_document_session_operations.py
@@ -1183,6 +1183,59 @@ def _what_changed(self) -> Dict[str, List[DocumentsChanges]]:
 
         return changes
 
+    def _what_changed_for(self, entity: object) -> List[DocumentsChanges]:
+        if self._documents_by_entity.get(entity) is None:
+            return []
+        if entity in self._deleted_entities:
+            return [
+                DocumentsChanges(
+                    field_old_value="",
+                    field_new_value="",
+                    change=DocumentsChanges.ChangeType.DOCUMENT_DELETED,
+                )
+            ]
+        doc_info = self._get_document_info(entity)
+        _update_metadata_modifications(doc_info.metadata_instance, doc_info.metadata)
+        new_obj = self.entity_to_json.convert_entity_to_json(entity, doc_info)
+        changes: Dict[str, List[DocumentsChanges]] = {}
+        self._entity_changed(new_obj, doc_info, changes)
+        return [
+            DocumentsChanges(
+                field_old_value=d["old_value"],
+                field_new_value=d["new_value"],
+                change=d["change"],
+                field_name=d["field_name"],
+                field_path=d["field_path"],
+            )
+            for d in changes.get(doc_info.key, [])
+        ]
+
+    def _get_tracked_entities(self) -> Dict[str, dict]:
+        result = {}
+        for entity_result in self._documents_by_entity:
+            doc_info = entity_result.value
+            result[doc_info.key] = {
+                "id": doc_info.key,
+                "entity": entity_result.key,
+                "is_deleted": self.is_deleted(doc_info.key),
+            }
+        for deleted in self._deleted_entities:
+            doc_info = self._documents_by_entity.get(deleted.entity)
+            if doc_info:
+                result[doc_info.key] = {
+                    "id": doc_info.key,
+                    "entity": deleted.entity,
+                    "is_deleted": True,
+                }
+        for key in self._known_missing_ids:
+            if key not in result:
+                result[key] = {
+                    "id": key,
+                    "entity": None,
+                    "is_deleted": True,
+                }
+        return result
+
     def __get_all_entities_changes(self, changes: Dict[str, List[DocumentsChanges]]) -> None:
         for key, value in self._documents_by_id.items():
             _update_metadata_modifications(value.metadata_instance, value.metadata)
diff --git a/ravendb/tests/session_tests/test_session_advanced_api.py b/ravendb/tests/session_tests/test_session_advanced_api.py
@@ -0,0 +1,325 @@
+"""
+Session advanced API: what_changed_for(entity) and get_tracked_entities().
+
+C# references:
+  FastTests/Client/WhatChangedFor.cs   — all WhatChangedFor tests
+  FastTests/Client/TrackEntity.cs      — Get_Tracked_Entities
+  FastTests/Client/WhatChanged.cs      — WhatChanged_Delete_After_Change_Value (RavenDB-13501)
+"""
+from ravendb.documents.session.misc import DocumentsChanges
+from ravendb.tests.test_base import TestBase
+
+
+class User:
+    def __init__(self, name: str = "", age: int = 0):
+        self.name = name
+        self.age = age
+
+
+class Obj:
+    def __init__(self, id: str = None, a: str = None, b: str = None):
+        self.Id = id
+        self.A = a
+        self.B = b
+
+
+class Arr:
+    def __init__(self, arr=None):
+        self.arr = arr if arr is not None else []
+
+
+class TestRavenDBSessionAdvancedApi(TestBase):
+    def setUp(self):
+        super().setUp()
+
+    def test_what_changed_for_returns_per_entity_changes(self):
+        """
+        session.advanced.what_changed_for(entity) returns the change list
+        for a single entity (C#: DocumentsChanges[]).
+
+        C# ref: all WhatChangedFor.cs tests depend on this method."""
+        with self.store.open_session() as session:
+            session.store(User(name="Alice"), "users/1")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            user = session.load("users/1", User)
+            user.age = 5
+
+            result = session.advanced.what_changed_for(user)
+            self.assertEqual(1, len(result), msg=f"Expected 1 change, got {len(result)}")
+            self.assertEqual(
+                DocumentsChanges.ChangeType.FIELD_CHANGED,
+                result[0].change,
+                msg=f"Expected FIELD_CHANGED, got {result[0].change}",
+            )
+
+    def test_what_changed_for_returns_document_added_for_new_entity(self):
+        """
+        what_changed_for() on a newly stored, unsaved entity returns one
+        DOCUMENT_ADDED entry.
+
+        C# ref: What_Changed_For_New_Field — first block calls WhatChangedFor
+        before SaveChanges and asserts 1 DocumentAdded entry."""
+        with self.store.open_session() as session:
+            user = User(name="Alice")
+            session.store(user, "users/1")
+
+            result = session.advanced.what_changed_for(user)
+            self.assertEqual(
+                1,
+                len(result),
+                msg="Expected 1 entry (DOCUMENT_ADDED) before SaveChanges",
+            )
+            self.assertEqual(
+                DocumentsChanges.ChangeType.DOCUMENT_ADDED,
+                result[0].change,
+                msg=f"Expected DOCUMENT_ADDED, got {result[0].change}",
+            )
+
+    def test_what_changed_for_returns_new_field_when_attribute_added(self):
+        """
+        Dynamically adding an attribute to a loaded entity is reported as
+        NEW_FIELD by what_changed_for().
+
+        C# ref: What_Changed_For_New_Field — load as wider type, set new field,
+        expect change == NewField."""
+        with self.store.open_session() as session:
+            session.store(User(name="Toli"), "users/1")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            user = session.load("users/1", User)
+            user.email = "toli@example.com"  # attribute absent from stored document
+
+            result = session.advanced.what_changed_for(user)
+            self.assertEqual(1, len(result), msg=f"Expected 1 NEW_FIELD entry, got {len(result)}")
+            self.assertEqual(
+                DocumentsChanges.ChangeType.NEW_FIELD,
+                result[0].change,
+                msg=f"Expected NEW_FIELD, got {result[0].change}",
+            )
+
+    def test_what_changed_for_returns_removed_field_when_attribute_deleted(self):
+        """
+        Deleting an attribute from a loaded entity is reported as REMOVED_FIELD
+        by what_changed_for().
+
+        C# ref: What_Changed_For_Removed_Field — load as narrower type,
+        expect change == RemovedField."""
+        with self.store.open_session() as session:
+            session.store(User(name="Toli", age=5), "users/1")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            user = session.load("users/1", User)
+            del user.age  # field present in document but removed from entity
+
+            result = session.advanced.what_changed_for(user)
+            self.assertEqual(1, len(result), msg=f"Expected 1 REMOVED_FIELD entry, got {len(result)}")
+            self.assertEqual(
+                DocumentsChanges.ChangeType.REMOVED_FIELD,
+                result[0].change,
+                msg=f"Expected REMOVED_FIELD, got {result[0].change}",
+            )
+
+    def test_what_changed_for_returns_document_deleted_for_deleted_entity(self):
+        """
+        Modifying fields then deleting an entity in the same session: what_changed_for()
+        must return exactly one DocumentDeleted entry — field changes are discarded.
+
+        C# ref: WhatChangedFor.cs — What_Changed_For_Delete_After_Change_Value (RavenDB-13501)."""
+        with self.store.open_session() as session:
+            session.store(Obj(id="DEL", a="A", b="A"), "DEL")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            o = session.load("DEL", Obj)
+            o.A = "B"
+            o.B = "C"
+            session.delete(o)
+
+            result = session.advanced.what_changed_for(o)
+            self.assertEqual(1, len(result), msg="Expected exactly 1 change entry (DocumentDeleted)")
+            self.assertEqual(
+                DocumentsChanges.ChangeType.DOCUMENT_DELETED,
+                result[0].change,
+                msg="Expected DocumentDeleted, got something else",
+            )
+
+    def test_get_tracked_entities_returns_tracked_dict(self):
+        """
+        session.advanced.get_tracked_entities() returns a dict mapping
+        document ID → EntityInfo dict (keys: id, entity, is_deleted).
+        The entity value must be the exact stored object.
+
+        C# ref: TrackEntity.cs — Get_Tracked_Entities verifies the tracked dict
+        contents both before and after save, for stored and deleted entities."""
+        with self.store.open_session() as session:
+            user = User(name="Bob")
+            session.store(user, "users/2")
+
+            tracked = session.advanced.get_tracked_entities()
+            self.assertIn(
+                "users/2",
+                tracked,
+                msg="Tracked entities should include 'users/2' after store()",
+            )
+            self.assertIs(
+                user,
+                tracked["users/2"]["entity"],
+                msg="Tracked entity must be the exact stored object",
+            )
+            self.assertFalse(
+                tracked["users/2"]["is_deleted"],
+                msg="Stored entity should not be marked as deleted",
+            )
+
+    def test_get_tracked_entities_shows_delete_by_id_as_deleted(self):
+        """
+        session.delete(string_id) adds the key to _known_missing_ids but does NOT
+        add to _deleted_entities.  get_tracked_entities() must include such entries
+        with is_deleted=True.
+
+        C# ref: TrackEntity.cs — Get_Tracked_Entities, second session block."""
+        with self.store.open_session() as session:
+            session.store(User(name="Eve"), "users/3")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            session.load("users/3", User)
+            session.delete("users/3")  # delete by string ID
+
+            tracked = session.advanced.get_tracked_entities()
+            self.assertIn("users/3", tracked, msg="Deleted-by-id entry must appear in tracked dict")
+            self.assertTrue(
+                tracked["users/3"]["is_deleted"],
+                msg="Entry deleted by string id must have is_deleted=True",
+            )
+
+    def test_get_tracked_entities_shows_entity_delete_as_deleted(self):
+        """
+        session.delete(entity) — object deletion — marks the entity as deleted
+        in get_tracked_entities().
+
+        C# ref: TrackEntity.cs — Get_Tracked_Entities last block: load user,
+        delete entity object, tracked count=1, is_deleted=True."""
+        with self.store.open_session() as session:
+            session.store(User(name="Frank"), "users/4")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            user = session.load("users/4", User)
+            session.delete(user)  # delete entity object, not by string ID
+
+            tracked = session.advanced.get_tracked_entities()
+            self.assertIn("users/4", tracked, msg="Entity-deleted entry must appear in tracked dict")
+            self.assertTrue(
+                tracked["users/4"]["is_deleted"],
+                msg="Entity deleted via session.delete(entity) must have is_deleted=True",
+            )
+
+    def test_delete_overrides_field_changes_in_what_changed(self):
+        """
+        C# spec (RavenDB-13501): modifying fields and then calling Delete() on
+        the same entity in the same session must cause what_changed() to report
+        only DOCUMENT_DELETED — the interim field changes are discarded."""
+        with self.store.open_session() as session:
+            session.store(Obj(id="ABC", a="A", b="A"), "ABC")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            o = session.load("ABC", Obj)
+            o.A = "B"
+            o.B = "C"
+            session.delete(o)
+
+            changes = session.advanced.what_changed()
+
+        self.assertIn("ABC", changes, msg="Deleted entity must appear in what_changed()")
+        self.assertEqual(1, len(changes["ABC"]), msg="Only one change entry expected (DocumentDeleted)")
+        self.assertEqual(
+            DocumentsChanges.ChangeType.DOCUMENT_DELETED,
+            changes["ABC"][0].change,
+            msg="Expected DOCUMENT_DELETED change type",
+        )
+
+
+class TestWhatChangedForArrayChanges(TestBase):
+    def setUp(self):
+        super().setUp()
+
+    def test_what_changed_for_reports_array_value_changed(self):
+        """
+        what_changed_for(entity) reports ARRAY_VALUE_CHANGED for each modified
+        array element, with correct field_old_value and field_new_value.
+
+        C# ref: What_Changed_For_Array_Value_Changed — ["a",1,"b"] → ["a",2,"c"]
+        produces exactly 2 ARRAY_VALUE_CHANGED entries."""
+        with self.store.open_session() as session:
+            session.store(Arr(arr=["a", 1, "b"]), "arr/1")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            arr = session.load("arr/1", Arr)
+            arr.arr = ["a", 2, "c"]  # index 0 unchanged; index 1: 1→2; index 2: "b"→"c"
+
+            changes = session.advanced.what_changed_for(arr)
+
+        self.assertEqual(2, len(changes), msg=f"Expected 2 ARRAY_VALUE_CHANGED entries, got {len(changes)}")
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_CHANGED, changes[0].change)
+        self.assertEqual(1, changes[0].field_old_value, msg="First change: old value should be 1")
+        self.assertEqual(2, changes[0].field_new_value, msg="First change: new value should be 2")
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_CHANGED, changes[1].change)
+        self.assertEqual("b", changes[1].field_old_value, msg="Second change: old value should be 'b'")
+        self.assertEqual("c", changes[1].field_new_value, msg="Second change: new value should be 'c'")
+
+    def test_what_changed_for_reports_array_value_added(self):
+        """
+        what_changed_for(entity) reports ARRAY_VALUE_ADDED for each element
+        appended beyond the original array length, with field_old_value=None.
+
+        C# ref: What_Changed_For_Array_Value_Added — extend ["a",1,"b"] by
+        2 elements → 2 ARRAY_VALUE_ADDED entries."""
+        with self.store.open_session() as session:
+            session.store(Arr(arr=["a", 1, "b"]), "arr/1")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            arr = session.load("arr/1", Arr)
+            arr.arr = ["a", 1, "b", "c", 2]
+
+            changes = session.advanced.what_changed_for(arr)
+
+        self.assertEqual(2, len(changes), msg=f"Expected 2 ARRAY_VALUE_ADDED entries, got {len(changes)}")
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_ADDED, changes[0].change)
+        self.assertIsNone(changes[0].field_old_value, msg="Added element must have old_value=None")
+        self.assertEqual("c", changes[0].field_new_value)
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_ADDED, changes[1].change)
+        self.assertIsNone(changes[1].field_old_value, msg="Added element must have old_value=None")
+        self.assertEqual(2, changes[1].field_new_value)
+
+    def test_what_changed_for_reports_array_value_removed(self):
+        """
+        what_changed_for(entity) reports ARRAY_VALUE_REMOVED for each element
+        dropped from the original array, with field_new_value=None.
+
+        C# ref: What_Changed_For_Array_Value_Removed — shrink ["a",1,"b"] to
+        ["a"] → 2 ARRAY_VALUE_REMOVED entries."""
+        with self.store.open_session() as session:
+            session.store(Arr(arr=["a", 1, "b"]), "arr/1")
+            session.save_changes()
+
+        with self.store.open_session() as session:
+            arr = session.load("arr/1", Arr)
+            arr.arr = ["a"]
+
+            changes = session.advanced.what_changed_for(arr)
+
+        self.assertEqual(2, len(changes), msg=f"Expected 2 ARRAY_VALUE_REMOVED entries, got {len(changes)}")
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_REMOVED, changes[0].change)
+        self.assertEqual(1, changes[0].field_old_value, msg="First removed element should be 1")
+        self.assertIsNone(changes[0].field_new_value, msg="Removed element must have new_value=None")
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_REMOVED, changes[1].change)
+        self.assertEqual("b", changes[1].field_old_value, msg="Second removed element should be 'b'")
+        self.assertIsNone(changes[1].field_new_value, msg="Removed element must have new_value=None")
