Merge pull request mongodb#164 from shelman/master

Added full_response parameter to find_and_modify for PYTHON-492

Author: behackett

doc/contributors.rst

@@ -61,3 +61,4 @@ The following is a list of people who have contributed to
 - Michael Henson (hensom)
 - Craig Hobbs (craigahobbs)
 - Emily Stolfo (estolfo)
+- Sam Helman (shelman)

pymongo/collection.py

@@ -1302,7 +1302,7 @@ def inline_map_reduce(self, map, reduce, full_response=False, **kwargs):
             return res.get("results")
 
     def find_and_modify(self, query={}, update=None,
-                        upsert=False, sort=None, **kwargs):
+                        upsert=False, sort=None, full_response=False, **kwargs):
         """Update and return an object.
 
         This is a thin wrapper around the findAndModify_ command. The
@@ -1315,13 +1315,21 @@ def find_and_modify(self, query={}, update=None,
         parameter. If no objects match the `query` and `upsert` is false,
         returns ``None``. If upserting and `new` is false, returns ``{}``.
 
+        If the full_response parameter is true, the return value will be 
+        the entire response object from the server, including the 'ok' and
+        'lastErrorObject' fields, rather than just the modified object.
+        This is useful mainly because the 'lastErrorObject' document holds 
+        information about the command's execution.
+
         :Parameters:
             - `query`: filter for the update (default ``{}``)
             - `update`: see second argument to :meth:`update` (no default)
             - `upsert`: insert if object doesn't exist (default ``False``)
             - `sort`: a list of (key, direction) pairs specifying the sort
               order for this query. See :meth:`~pymongo.cursor.Cursor.sort`
               for details.
+            - `full_response`: return the entire response object from the
+              server
             - `remove`: remove rather than updating (default ``False``)
             - `new`: return updated rather than original object
               (default ``False``)
@@ -1336,6 +1344,9 @@ def find_and_modify(self, query={}, update=None,
 
         .. note:: Requires server version **>= 1.3.0**
 
+        .. versionchanged:: 2.5
+           Added the optional full_response parameter
+
         .. versionchanged:: 2.4
            Deprecated the use of mapping types for the sort parameter
 
@@ -1385,7 +1396,10 @@ def find_and_modify(self, query={}, update=None,
                 # Should never get here b/c of allowable_errors
                 raise ValueError("Unexpected Error: %s" % (out,))
 
-        return out.get('value')
+        if full_response:
+            return out
+        else:
+            return out.get('value')
 
     def __iter__(self):
         return self

test/test_collection.py

@@ -1732,6 +1732,21 @@ def test_find_and_modify(self):
                          c.find_and_modify({'_id': 1}, {'$inc': {'i': 1}},
                                            new=True, fields={'i': 1}))
 
+        # Test with full_response=True (version > 2.4.2)
+        result = c.find_and_modify({'_id': 1}, {'$inc': {'i': 1}},
+                                           new=True, upsert=True, 
+                                           full_response=True,
+                                           fields={'i': 1})
+        self.assertEqual({'_id': 1, 'i': 5}, result["value"])
+        self.assertEqual(True, result["lastErrorObject"]["updatedExisting"])
+        
+        result = c.find_and_modify({'_id': 2}, {'$inc': {'i': 1}},
+                                           new=True, upsert=True, 
+                                           full_response=True,
+                                           fields={'i': 1})
+        self.assertEqual({'_id': 2, 'i': 1}, result["value"])
+        self.assertEqual(False, result["lastErrorObject"]["updatedExisting"])
+
         class ExtendedDict(dict):
             pass