Merge lp:~cmiller/desktopcouch/put_record_documented_more into lp:desktopcouch

[Chad Miller]

Make it clear that a owner of a record will get their data mutated when they call put_record, and that the result is safe to put again, with no need to fetch it from the server.

[Eric Casteleijn (thisfred)]

Looks clear to me

review: Approve

[lp:~cmiller/desktopcouch/put_record_documented_more]

126. By Chad Miller on 2010-02-25

More ACHTUNG.

=== modified file 'desktopcouch/records/doc/records.txt'
--- desktopcouch/records/doc/records.txt	2009-11-11 16:24:22 +0000
+++ desktopcouch/records/doc/records.txt	2010-02-25 19:47:14 +0000
@@ -19,16 +19,31 @@
 
 >>> r['c'] = ['d','e','f']
 
-Save the record into the database with put_record:
+Save the record into the database and update its ID and REV with 
+put_record.  Before you put the record the first time, the ID and REV
+may be unset:
 
+>>> r.record_id is None
+True
+>>> r.record_revision is None
+True
 >>> record_id = db.put_record(r)
 
+The record r is ready to be sent again, since put_record has side-effects
+that mutate it.
+
+>>> r.record_id is not None
+True
+>>> r.record_revision is not None
+True
+>>> r['g'] = 'h'
+>>> record_id = db.put_record(r)    # HAS SIDE-EFFECT!  Mutates r!
+
 Fetch existing records from the database by ID:
 
 >>> fetched = db.get_record(record_id)
->>> print fetched['a']
-b
->>>
+>>> print fetched['g']
+h
 
 There is no ad-hoc query functionality.
 

=== modified file 'desktopcouch/records/server_base.py'
--- desktopcouch/records/server_base.py	2010-02-04 23:14:37 +0000
+++ desktopcouch/records/server_base.py	2010-02-25 19:47:14 +0000
@@ -199,19 +199,10 @@
             record.record_id = uuid4().hex
         self.db[record.record_id] = record._data
 
-        # At this point, we've saved new document to the database, by
-        # we do not know the revision number of it.  We need *a*
-        # specific revision now, so that we can attach BLOBs to it.
-
-        # This is bad.  We can get the most recent revision, but that
-        # doesn't assure us that what we're attaching records to is
-        # the revision we just sent.
-
-        retrieved_document = self.db[record.record_id]
         for attachment_name in record.list_attachments():
             data, content_type = record.attachment_data(attachment_name)
             self.db.put_attachment(
-                retrieved_document, data, attachment_name, content_type)
+                record._data, data, attachment_name, content_type)
 
         return record.record_id