change logic of orm constructor so that initial values are not considered updates, and explain a bit in the docstring

doublethink/orm.py

@@ -195,11 +195,30 @@ class Document(dict, object):
             cls.table_create(rr)
 
     def __init__(self, rr, d={}):
+        '''
+        Sets initial values from `d`, then calls `self.populate_defaults()`.
+
+        Args:
+            rr (doublethink.Rethinker): rethinker
+            d (dict): initial value
+
+        If you want to create a new document, and set the primary key yourself,
+        do not call `doc = MyDocument(rr, d={'id': 'my_id', ...})`. The
+        assumption is that if the primary key is set in the constructor, the
+        document already exists in the database. Thus a call to `doc.save()`
+        may not save anything. Do this instead:
+
+            doc = MyDocument(rr, d={'id': 'my_id', ...})
+            doc.id = 'my_id'
+            # ...whatever else...
+            doc.save()
+        '''
         dict.__setattr__(self, 'rr', rr)
         self._pk = None
         self._clear_updates()
         for k in d or {}:
-            self[k] = watch(d[k], callback=self._updated, field=k)
+            dict.__setitem__(
+                    self, k, watch(d[k], callback=self._updated, field=k))
         self.populate_defaults()
 
     def _clear_updates(self):

setup.py

@@ -3,7 +3,7 @@ import codecs
 
 setuptools.setup(
     name='doublethink',
-    version='0.2.0.dev71',
+    version='0.2.0.dev72',
     packages=['doublethink'],
     classifiers=[
         'Programming Language :: Python :: 2.7',

tests/test_orm.py

@@ -253,7 +253,8 @@ def test_orm_pk(rr):
     assert NonstandardPrimaryKey.load(rr, 'no_such_thing') is None
 
     # new doc with (only) primary key
-    d = NonstandardPrimaryKey(rr, {'not_id': 1})
+    d = NonstandardPrimaryKey(rr)
+    d.not_id = 1
     assert d.not_id == 1
     assert d.pk_value == 1
     d.save()