Add a Database.save method for creating and updating a doc.

atomatt · atomatt · commit b4dca14a7659 · 2010-04-13T16:51:16.000+01:00
diff --git a/couchdb/client.py b/couchdb/client.py
@@ -357,6 +357,40 @@ def create(self, data):
         _, _, data = self.resource.post_json(body=data)
         return data['id']
 
+    def save(self, doc, **options):
+        """Create a new document or update an existing document.
+
+        If doc has no _id then the server will allocate a random ID and a new
+        document will be created. Otherwise the doc's _id will be used to
+        identity the document to create or update. Trying to update an existing
+        document with an incorrect _rev will raise a ResourceConflict exception.
+
+        Note that it is generally better to avoid saving documents with no _id
+        and instead generate document IDs on the client side. This is due to
+        the fact that the underlying HTTP ``POST`` method is not idempotent,
+        and an automatic retry due to a problem somewhere on the networking
+        stack may cause multiple documents being created in the database.
+
+        To avoid such problems you can generate a UUID on the client side.
+        Python (since version 2.5) comes with a ``uuid`` module that can be
+        used for this::
+
+            from uuid import uuid4
+            doc = {'_id': uuid4().hex, 'type': 'person', 'name': 'John Doe'}
+            db.save(doc)
+
+        :param doc: the document to store
+        :param options: optional args, e.g. batch='ok'
+        :return: (id, rev) tuple of the save document
+        :rtype: `tuple`
+        """
+        _, _, data = self.resource.post_json(body=doc, **options)
+        id, rev = data['id'], data.get('rev')
+        doc['_id'] = id
+        if rev is not None: # Not present for batch='ok'
+            doc['_rev'] = rev
+        return id, rev
+
     def commit(self):
         """If the server is configured to delay commits, or previous requests
         used the special ``X-Couch-Full-Commit: false`` header to disable
diff --git a/couchdb/tests/client.py b/couchdb/tests/client.py
@@ -141,6 +141,43 @@ def tearDown(self):
 
 class DatabaseTestCase(TempDatabaseMixin, unittest.TestCase):
 
+    def test_save_new(self):
+        doc = {'foo': 'bar'}
+        id, rev = self.db.save(doc)
+        self.assertTrue(id is not None)
+        self.assertTrue(rev is not None)
+        self.assertEqual((id, rev), (doc['_id'], doc['_rev']))
+        doc = self.db.get(id)
+        self.assertEqual(doc['foo'], 'bar')
+
+    def test_save_new_with_id(self):
+        doc = {'_id': 'foo'}
+        id, rev = self.db.save(doc)
+        self.assertTrue(doc['_id'] == id == 'foo')
+        self.assertEqual(doc['_rev'], rev)
+
+    def test_save_existing(self):
+        doc = {}
+        id_rev_old = self.db.save(doc)
+        doc['foo'] = True
+        id_rev_new = self.db.save(doc)
+        self.assertTrue(doc['_rev'] == id_rev_new[1])
+        self.assertTrue(id_rev_old[1] != id_rev_new[1])
+
+    def test_save_new_batch(self):
+        doc = {'_id': 'foo'}
+        id, rev = self.db.save(doc, batch='ok')
+        self.assertTrue(rev is None)
+        self.assertTrue('_rev' not in doc)
+
+    def test_save_existing_batch(self):
+        doc = {'_id': 'foo'}
+        self.db.save(doc)
+        id_rev_old = self.db.save(doc)
+        id_rev_new = self.db.save(doc, batch='ok')
+        self.assertTrue(id_rev_new[1] is None)
+        self.assertEqual(id_rev_old[1], doc['_rev'])
+
     def test_exists(self):
         self.assertTrue(client.Database(client.DEFAULT_BASE_URL+'python-tests'))
         self.assertFalse(client.Database('python-tests-missing'))
