make get_or_create returns a tuple with the retrieved or created object and a boolean specifying whether a new object was created

docs/guide/querying.rst

@@ -135,8 +135,8 @@ additional keyword argument, :attr:`defaults` may be provided, which will be
 used as default values for the new document, in the case that it should need
 to be created::
 
-    >>> a = User.objects.get_or_create(name='User A', defaults={'age': 30})
-    >>> b = User.objects.get_or_create(name='User A', defaults={'age': 40})
+    >>> a, created = User.objects.get_or_create(name='User A', defaults={'age': 30})
+    >>> b, created = User.objects.get_or_create(name='User A', defaults={'age': 40})
     >>> a.name == b.name and a.age == b.age
     True
 

mongoengine/queryset.py

@@ -360,7 +360,9 @@ class QuerySet(object):
                                               % self._document._class_name)
 
     def get_or_create(self, *q_objs, **query):
-        """Retreive unique object or create, if it doesn't exist. Raises
+        """Retrieve unique object or create, if it doesn't exist. Returns a tuple of 
+        ``(object, created)``, where ``object`` is the retrieved or created object 
+        and ``created`` is a boolean specifying whether a new object was created. Raises
         :class:`~mongoengine.queryset.MultipleObjectsReturned` or
         `DocumentName.MultipleObjectsReturned` if multiple results are found.
         A new document will be created if the document doesn't exists; a
@@ -379,9 +381,9 @@ class QuerySet(object):
             query.update(defaults)
             doc = self._document(**query)
             doc.save()
-            return doc
+            return doc, True
         elif count == 1:
-            return self.first()
+            return self.first(), False
         else:
             message = u'%d items returned, instead of 1' % count
             raise self._document.MultipleObjectsReturned(message)

tests/queryset.py

@@ -184,14 +184,17 @@ class QuerySetTest(unittest.TestCase):
                           self.Person.objects.get_or_create)
 
         # Use a query to filter the people found to just person2
-        person = self.Person.objects.get_or_create(age=30)
+        person, created = self.Person.objects.get_or_create(age=30)
         self.assertEqual(person.name, "User B")
+        self.assertEqual(created, False)
         
-        person = self.Person.objects.get_or_create(age__lt=30)
+        person, created = self.Person.objects.get_or_create(age__lt=30)
         self.assertEqual(person.name, "User A")
+        self.assertEqual(created, False)
         
         # Try retrieving when no objects exists - new doc should be created
-        self.Person.objects.get_or_create(age=50, defaults={'name': 'User C'})
+        person, created = self.Person.objects.get_or_create(age=50, defaults={'name': 'User C'})
+        self.assertEqual(created, True)
         
         person = self.Person.objects.get(age=50)
         self.assertEqual(person.name, "User C")