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

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.

Author: redknightlois

ravendb/documents/session/document_session.py

@@ -803,6 +803,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")

ravendb/documents/session/document_session_operations/in_memory_document_session_operations.py

@@ -1183,6 +1183,51 @@ def _what_changed(self) -> Dict[str, List[DocumentsChanges]]:
 
         return changes
 
+    def _what_changed_for(self, entity: object) -> List[DocumentsChanges]:
+        if (doc_info := 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,
+                )
+            ]
+        _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]] = {}
+        if not self._entity_changed(new_obj, doc_info, changes):
+            return []
+        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 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)

ravendb/tests/session_tests/test_session_advanced_api.py

@@ -0,0 +1,212 @@
+"""C# ref: WhatChangedFor.cs, TrackEntity.cs, WhatChanged.cs"""
+
+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_change_field(self):
+        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))
+            self.assertEqual(DocumentsChanges.ChangeType.FIELD_CHANGED, result[0].change)
+
+    def test_what_changed_for_new_field_before_save(self):
+        """What_Changed_For_New_Field — first block: before SaveChanges."""
+        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))
+            self.assertEqual(DocumentsChanges.ChangeType.DOCUMENT_ADDED, result[0].change)
+
+    def test_what_changed_for_new_field(self):
+        """What_Changed_For_New_Field — second block: load as wider type."""
+        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"
+
+            result = session.advanced.what_changed_for(user)
+            self.assertEqual(1, len(result))
+            self.assertEqual(DocumentsChanges.ChangeType.NEW_FIELD, result[0].change)
+
+    def test_what_changed_for_removed_field(self):
+        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
+
+            result = session.advanced.what_changed_for(user)
+            self.assertEqual(1, len(result))
+            self.assertEqual(DocumentsChanges.ChangeType.REMOVED_FIELD, result[0].change)
+
+    def test_what_changed_for_delete_after_change_value(self):
+        """RavenDB-13501: field changes discarded after delete in same session."""
+        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))
+            self.assertEqual(DocumentsChanges.ChangeType.DOCUMENT_DELETED, result[0].change)
+
+    def test_get_tracked_entities(self):
+        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)
+            self.assertIs(user, tracked["users/2"]["entity"])
+            self.assertFalse(tracked["users/2"]["is_deleted"])
+
+    def test_get_tracked_entities_delete_by_id(self):
+        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")
+
+            tracked = session.advanced.get_tracked_entities()
+            self.assertIn("users/3", tracked)
+            self.assertTrue(tracked["users/3"]["is_deleted"])
+
+    def test_get_tracked_entities_delete_by_entity(self):
+        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)
+
+            tracked = session.advanced.get_tracked_entities()
+            self.assertIn("users/4", tracked)
+            self.assertTrue(tracked["users/4"]["is_deleted"])
+
+    def test_what_changed_delete_after_change_value(self):
+        """RavenDB-13501: what_changed() reports only DOCUMENT_DELETED after delete."""
+        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)
+        self.assertEqual(1, len(changes["ABC"]))
+        self.assertEqual(DocumentsChanges.ChangeType.DOCUMENT_DELETED, changes["ABC"][0].change)
+
+
+class TestWhatChangedForArrayChanges(TestBase):
+    def setUp(self):
+        super().setUp()
+
+    def test_what_changed_for_array_value_changed(self):
+        """["a",1,"b"] -> ["a",2,"c"] produces 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"]
+
+            changes = session.advanced.what_changed_for(arr)
+
+        self.assertEqual(2, len(changes))
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_CHANGED, changes[0].change)
+        self.assertEqual(1, changes[0].field_old_value)
+        self.assertEqual(2, changes[0].field_new_value)
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_CHANGED, changes[1].change)
+        self.assertEqual("b", changes[1].field_old_value)
+        self.assertEqual("c", changes[1].field_new_value)
+
+    def test_what_changed_for_array_value_added(self):
+        """["a",1,"b"] -> ["a",1,"b","c",2] produces 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))
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_ADDED, changes[0].change)
+        self.assertIsNone(changes[0].field_old_value)
+        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)
+        self.assertEqual(2, changes[1].field_new_value)
+
+    def test_what_changed_for_array_value_removed(self):
+        """["a",1,"b"] -> ["a"] produces 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))
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_REMOVED, changes[0].change)
+        self.assertEqual(1, changes[0].field_old_value)
+        self.assertIsNone(changes[0].field_new_value)
+        self.assertEqual(DocumentsChanges.ChangeType.ARRAY_VALUE_REMOVED, changes[1].change)
+        self.assertEqual("b", changes[1].field_old_value)
+        self.assertIsNone(changes[1].field_new_value)