chore: release Python bindings 1.17.1

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "loro_py"
-version = "1.16.2"
+version = "1.17.1"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
@@ -9,7 +9,7 @@ name = "loro"
 crate-type = ["cdylib"]
 
 [dependencies]
-loro = { version = "1.16.2", features = ["counter", "jsonpath"] }
+loro = { version = "1.17.1", features = ["counter", "jsonpath"] }
 rustc-hash = "2.1.1"
 pyo3 = { version = "0.26.0" }
 serde_json = "1"

README.md

@@ -68,3 +68,12 @@ cd loro-py
 pip install maturin
 maturin develop
 ```
+
+## 1.17.1
+
+Uses Loro core 1.17.1. Adds `LoroDoc.export_pending_updates()` to persist received
+updates waiting for missing dependencies alongside a consistent snapshot. Restore
+the snapshot first, then import the pending bytes. `None` means nothing is pending;
+clear any previously saved pending bytes when replacing a checkpoint with `None`.
+JSON export keeps returning the existing JSON string and reports history decode
+failures as Python exceptions. The `state_vv` property retains its existing type.

loro.pyi

@@ -788,6 +788,14 @@ class LoroDoc:
         """
         ...
 
+    def export_pending_updates(self) -> typing.Optional[bytes]:
+        """Export remote updates waiting for dependencies without committing local edits.
+
+        Save with a consistent snapshot. Restore the snapshot first, then import
+        these bytes. None means no received updates are pending.
+        """
+        ...
+
     def get_path_to_container(
         self, id: ContainerID
     ) -> typing.Optional[list[tuple[ContainerID, Index]]]:

src/doc.rs

@@ -515,11 +515,15 @@ impl LoroDoc {
     // TODO: return an object
     /// Export the current state with json-string format of the document.
     #[inline]
-    pub fn export_json_updates(&self, start_vv: VersionVector, end_vv: VersionVector) -> String {
+    pub fn export_json_updates(
+        &self,
+        start_vv: VersionVector,
+        end_vv: VersionVector,
+    ) -> PyLoroResult<String> {
         let json = self
             .doc
-            .export_json_updates(&start_vv.into(), &end_vv.into());
-        serde_json::to_string(&json).unwrap()
+            .export_json_updates(&start_vv.into(), &end_vv.into())?;
+        serde_json::to_string(&json).map_err(|error| PyLoroError::Error(error.to_string()))
     }
 
     /// Exports changes within the specified ID span to JSON schema format.
@@ -873,6 +877,15 @@ impl LoroDoc {
         Ok(Cow::Owned(ans))
     }
 
+    /// Export received remote updates that are waiting for missing dependencies.
+    ///
+    /// Returns None when nothing is pending. Save these bytes together with a
+    /// consistent snapshot, then restore the snapshot before importing these bytes.
+    /// This does not commit local edits or consume pending updates.
+    pub fn export_pending_updates(&self) -> PyLoroResult<Option<Cow<'_, [u8]>>> {
+        Ok(self.doc.export_pending_updates()?.map(Cow::Owned))
+    }
+
     // /// Analyze the container info of the doc
     // ///
     // /// This is used for development and debugging. It can be slow.

tests/test_pending_updates.py

@@ -0,0 +1,52 @@
+import json
+
+from loro import ExportMode, LoroDoc, VersionVector
+
+
+def test_pending_updates_survive_a_snapshot_checkpoint():
+    source = LoroDoc()
+    source.get_text("text").insert(0, "base")
+    base = source.export(ExportMode.Snapshot())
+    before_a = source.oplog_vv
+    source.get_text("text").insert(4, "A")
+    a = source.export(ExportMode.Updates(before_a))
+    after_a = source.oplog_vv
+    source.get_text("text").insert(5, "B")
+    b = source.export(ExportMode.Updates(after_a))
+
+    receiver = LoroDoc()
+    receiver.import_(base)
+    receiver.import_(b)
+    assert receiver.get_text("text").to_string() == "base"
+    snapshot = receiver.export(ExportMode.Snapshot())
+    pending = receiver.export_pending_updates()
+    assert isinstance(pending, bytes)
+    assert receiver.export_pending_updates() == pending
+
+    restored = LoroDoc()
+    restored.import_(snapshot)
+    restored.import_(pending)
+    assert restored.get_text("text").to_string() == "base"
+    restored.import_(a)
+    assert restored.get_text("text").to_string() == "baseAB"
+    assert restored.export_pending_updates() is None
+
+
+def test_pending_export_does_not_commit_local_edits():
+    doc = LoroDoc()
+    doc.get_text("text").insert(0, "local")
+    pending_count = doc.get_pending_txn_len()
+    assert pending_count > 0
+    assert doc.export_pending_updates() is None
+    assert doc.get_pending_txn_len() == pending_count
+
+
+def test_json_export_keeps_the_existing_schema():
+    doc = LoroDoc()
+    doc.get_text("text").insert(0, "hello")
+    doc.commit()
+    updates = doc.export_json_updates(VersionVector(), doc.oplog_vv)
+    assert "schema_version" in json.loads(updates)
+    restored = LoroDoc()
+    restored.import_json_updates(updates)
+    assert restored.get_text("text").to_string() == "hello"