Add DeprecationWarning for EmbeddedDocument.save & .reload - those will be removed soon

docs/changelog.rst

@@ -8,6 +8,7 @@ Development
 - Fix .only() working improperly after using .count() of the same instance of QuerySet
 - POTENTIAL BREAKING CHANGE: All result fields are now passed, including internal fields (_cls, _id) when using `QuerySet.as_pymongo` #1976
 - Fix InvalidStringData error when using modify on a BinaryField #1127
+- DEPRECATION: `EmbeddedDocument.save` & `.reload` are marked as deprecated and will be removed in a next version of mongoengine #1552
 
 =================
 Changes in 0.16.3

mongoengine/document.py

@@ -90,9 +90,15 @@ class EmbeddedDocument(six.with_metaclass(DocumentMetaclass, BaseDocument)):
         return data
 
     def save(self, *args, **kwargs):
+        warnings.warn("EmbeddedDocument.save is deprecated and will be removed in a next version of mongoengine."
+                      "Use the parent document's .save() or ._instance.save()",
+                      DeprecationWarning, stacklevel=2)
         self._instance.save(*args, **kwargs)
 
     def reload(self, *args, **kwargs):
+        warnings.warn("EmbeddedDocument.reload is deprecated and will be removed in a next version of mongoengine."
+                      "Use the parent document's .reload() or ._instance.reload()",
+                      DeprecationWarning, stacklevel=2)
         self._instance.reload(*args, **kwargs)
 
 

tests/document/instance.py

@@ -7,6 +7,8 @@ import uuid
 import weakref
 
 from datetime import datetime
+
+import warnings
 from bson import DBRef, ObjectId
 from pymongo.errors import DuplicateKeyError
 
@@ -2000,7 +2002,6 @@ class InstanceTest(MongoDBTestCase):
         child_record.delete()
         self.assertEqual(Record.objects(name='parent').get().children, [])
 
-
     def test_reverse_delete_rule_with_custom_id_field(self):
         """Ensure that a referenced document with custom primary key
         is also deleted upon deletion.
@@ -3086,6 +3087,24 @@ class InstanceTest(MongoDBTestCase):
             "UNDEFINED",
             system.nodes["node"].parameters["param"].macros["test"].value)
 
+    def test_embedded_document_save_reload_warning(self):
+        """Relates to #1570"""
+        class Embedded(EmbeddedDocument):
+            pass
+
+        class Doc(Document):
+            emb = EmbeddedDocumentField(Embedded)
+
+        doc = Doc(emb=Embedded()).save()
+        doc.emb.save()  # Make sure its still working
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DeprecationWarning)
+            with self.assertRaises(DeprecationWarning):
+                doc.emb.save()
+
+            with self.assertRaises(DeprecationWarning):
+                doc.emb.reload()
+
     def test_embedded_document_equality(self):
         class Test(Document):
             field = StringField(required=True)
@@ -3381,7 +3400,6 @@ class InstanceTest(MongoDBTestCase):
         class User(Document):
             company = ReferenceField(Company)
 
-
         # Ensure index creation exception aren't swallowed (#1688)
         with self.assertRaises(DuplicateKeyError):
             User.objects().select_related()