Sync Method (#831)

* implemented

* doc

beanie/__init__.py

@@ -16,7 +16,7 @@
 from beanie.odm.bulk import BulkWriter
 from beanie.odm.custom_types import DecimalAnnotation
 from beanie.odm.custom_types.bson.binary import BsonBinary
-from beanie.odm.documents import Document
+from beanie.odm.documents import Document, MergeStrategy
 from beanie.odm.enums import SortDirection
 from beanie.odm.fields import (
  BackLink,
@@ -46,6 +46,7 @@
  "TimeSeriesConfig",
  "Granularity",
  "SortDirection",
+ "MergeStrategy",
  # Actions
  "before_event",
  "after_event",

beanie/exceptions.py

@@ -68,3 +68,7 @@ class DocWasNotRegisteredInUnionClass(Exception):
 
 class Deprecation(Exception):
  pass
+
+
+class ApplyChangesException(Exception):
+ pass

beanie/odm/documents.py

@@ -1,5 +1,6 @@
 import asyncio
 import warnings
+from enum import Enum
 from typing import (
  Any,
  ClassVar,
@@ -81,7 +82,7 @@
 from beanie.odm.queries.update import UpdateMany, UpdateResponse
 from beanie.odm.settings.document import DocumentSettings
 from beanie.odm.utils.dump import get_dict, get_top_level_nones
-from beanie.odm.utils.parsing import merge_models
+from beanie.odm.utils.parsing import apply_changes, merge_models
 from beanie.odm.utils.pydantic import (
  IS_PYDANTIC_V2,
  get_extra_field_info,
@@ -126,6 +127,11 @@ def document_alias_generator(s: str) -> str:
  return s
 
 
+class MergeStrategy(str, Enum):
+ local = "local"
+ remote = "remote"
+
+
 class Document(
  LazyModel,
  SettersInterface,
@@ -254,6 +260,41 @@ async def get(
  **pymongo_kwargs,
  )
 
+ async def sync(self, merge_strategy: MergeStrategy = MergeStrategy.remote):
+ """
+ Sync the document with the database
+
+ :param merge_strategy: MergeStrategy - how to merge the document
+ :return: None
+ """
+ if (
+ merge_strategy == MergeStrategy.local
+ and self.get_settings().use_state_management is False
+ ):
+ raise ValueError(
+ "State management must be turned on to use local merge strategy"
+ )
+ if self.id is None:
+ raise DocumentWasNotSaved
+ document = await self.find_one({"_id": self.id})
+ if document is None:
+ raise DocumentNotFound
+
+ if merge_strategy == MergeStrategy.local:
+ original_changes = self.get_changes()
+ new_state = document.get_saved_state()
+ if new_state is None:
+ raise DocumentWasNotSaved
+ changes_to_apply = self._collect_updates(
+ new_state, original_changes
+ )
+ merge_models(self, document)
+ apply_changes(changes_to_apply, self)
+ elif merge_strategy == MergeStrategy.remote:
+ merge_models(self, document)
+ else:
+ raise ValueError("Invalid merge strategy")
+
  @wrap_with_actions(EventTypes.INSERT)
  @save_state_after
  @validate_self_before

beanie/odm/utils/parsing.py

@@ -1,8 +1,9 @@
-from typing import TYPE_CHECKING, Any, Type, Union
+from typing import TYPE_CHECKING, Any, Dict, Type, Union
 
 from pydantic import BaseModel
 
 from beanie.exceptions import (
+ ApplyChangesException,
  DocWasNotRegisteredInUnionClass,
  UnionHasNoRegisteredDocs,
 )
@@ -45,6 +46,47 @@ def merge_models(left: BaseModel, right: BaseModel) -> None:
  left.__setattr__(k, right_value)
 
 
+def apply_changes(
+ changes: Dict[str, Any], target: Union[BaseModel, Dict[str, Any]]
+):
+ for key, value in changes.items():
+ if "." in key:
+ key_parts = key.split(".")
+ current_target = target
+ try:
+ for part in key_parts[:-1]:
+ if isinstance(current_target, dict):
+ current_target = current_target[part]
+ elif isinstance(current_target, BaseModel):
+ current_target = getattr(current_target, part)
+ else:
+ raise ApplyChangesException(
+ f"Unexpected type of target: {type(target)}"
+ )
+ final_key = key_parts[-1]
+ if isinstance(current_target, dict):
+ current_target[final_key] = value
+ elif isinstance(current_target, BaseModel):
+ setattr(current_target, final_key, value)
+ else:
+ raise ApplyChangesException(
+ f"Unexpected type of target: {type(target)}"
+ )
+ except (KeyError, AttributeError) as e:
+ raise ApplyChangesException(
+ f"Failed to apply change for key '{key}': {e}"
+ )
+ else:
+ if isinstance(target, dict):
+ target[key] = value
+ elif isinstance(target, BaseModel):
+ setattr(target, key, value)
+ else:
+ raise ApplyChangesException(
+ f"Unexpected type of target: {type(target)}"
+ )
+
+
 def save_state(item: BaseModel):
  if hasattr(item, "_save_state"):
  item._save_state() # type: ignore

docs/tutorial/find.md

@@ -77,6 +77,38 @@ you can use the [find_one](../api-documentation/interfaces.md/#findinterfacefind
 bar = await Product.find_one(Product.name == "Peanut Bar")
 ```
 
+## Syncing from the Database
+
+If you wish to apply changes from the database to the document, utilize the [sync](../api-documentation/document.md/#documentsync) method:
+
+```python
+await bar.sync()
+```
+
+Two merging strategies are available: `local` and `remote`.
+
+### Remote Merge Strategy
+
+The remote merge strategy replaces the local document with the one from the database, disregarding local changes:
+
+```python
+from beanie import MergeStrategy
+
+await bar.sync(merge_strategy=MergeStrategy.remote)
+```
+The remote merge strategy is the default.
+
+### Local Merge Strategy
+
+The local merge strategy retains changes made locally to the document and updates other fields from the database.
+**BE CAREFUL**: it may raise an `ApplyChangesException` in case of a merging conflict.
+
+```python
+from beanie import MergeStrategy
+
+await bar.sync(merge_strategy=MergeStrategy.local)
+```
+
 ## More complex queries
 
 ### Multiple search criteria

tests/odm/conftest.py

@@ -28,6 +28,7 @@
  DocumentTestModelWithLink,
  DocumentTestModelWithSimpleIndex,
  DocumentToBeLinked,
+ DocumentToTestSync,
  DocumentUnion,
  DocumentWithActions,
  DocumentWithActions2,
@@ -281,6 +282,7 @@ async def init(db):
  DocumentWithOptionalListBackLink,
  DocumentWithComplexDictKey,
  DocumentWithIndexedObjectId,
+ DocumentToTestSync,
  ]
  await init_beanie(
  database=db,

tests/odm/documents/test_sync.py

@@ -0,0 +1,54 @@
+import pytest
+
+from beanie.exceptions import ApplyChangesException
+from beanie.odm.documents import MergeStrategy
+from tests.odm.models import DocumentToTestSync
+
+
+class TestSync:
+ async def test_merge_remote(self):
+ doc = DocumentToTestSync()
+ await doc.insert()
+
+ doc2 = await DocumentToTestSync.get(doc.id)
+ doc2.s = "foo"
+
+ doc.i = 100
+ await doc.save()
+
+ await doc2.sync()
+
+ assert doc2.s == "TEST"
+ assert doc2.i == 100
+
+ async def test_merge_local(self):
+ doc = DocumentToTestSync(d={"option_1": {"s": "foo"}})
+ await doc.insert()
+
+ doc2 = await DocumentToTestSync.get(doc.id)
+ doc2.s = "foo"
+ doc2.n.option_1.s = "bar"
+ doc2.d["option_1"]["s"] = "bar"
+
+ doc.i = 100
+ await doc.save()
+
+ await doc2.sync(merge_strategy=MergeStrategy.local)
+
+ assert doc2.s == "foo"
+ assert doc2.n.option_1.s == "bar"
+ assert doc2.d["option_1"]["s"] == "bar"
+
+ assert doc2.i == 100
+
+ async def test_merge_local_impossible_apply_changes(self):
+ doc = DocumentToTestSync(d={"option_1": {"s": "foo"}})
+ await doc.insert()
+
+ doc2 = await DocumentToTestSync.get(doc.id)
+ doc2.d["option_1"]["s"] = {"foo": "bar"}
+
+ doc.d = {"option_1": "nothing"}
+ await doc.save()
+ with pytest.raises(ApplyChangesException):
+ await doc2.sync(merge_strategy=MergeStrategy.local)

tests/odm/models.py

@@ -1050,3 +1050,16 @@ class DocumentWithIndexedObjectId(Document):
  pyid: Indexed(PydanticObjectId)
  uuid: Annotated[UUID4, Indexed(unique=True)]
  email: Annotated[EmailStr, Indexed(unique=True)]
+
+
+class DocumentToTestSync(Document):
+ s: str = "TEST"
+ i: int = 1
+ n: Nested = Nested(
+ integer=1, option_1=Option1(s="test"), union=Option1(s="test")
+ )
+ o: Optional[Option2] = None
+ d: Dict[str, Any] = {}
+
+ class Settings:
+ use_state_management = True