diff --git a/docs/guide/querying.rst b/docs/guide/querying.rst index eba75d7d..bad8b340 100644 --- a/docs/guide/querying.rst +++ b/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 diff --git a/mongoengine/queryset.py b/mongoengine/queryset.py index 6c162070..43b6eee8 100644 --- a/mongoengine/queryset.py +++ b/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) diff --git a/tests/queryset.py b/tests/queryset.py index e1fa6f45..aba3bc7d 100644 --- a/tests/queryset.py +++ b/tests/queryset.py @@ -184,15 +184,18 @@ 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") - - person = self.Person.objects.get_or_create(age__lt=30) + self.assertEqual(created, False) + + 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")