homepage

The shelve module documentation states that "by default, mutations to
persistent-dictionary mutable entries are not automatically written
back. If the optional writeback parameter is set to True, all entries
accessed are cached in memory, and written back at close time..."
however the implementation's __setitem__ is the following:
 def __setitem__(self, key, value):
 if self.writeback:
 self.cache[key] = value
 f = StringIO()
 p = Pickler(f, self._protocol)
 p.dump(value)
 self.dict[key] = f.getvalue()
which maintains the cache correctly but writes back to the disk on every
operation, violating the writeback documentation. Changing it to 
 def __setitem__(self, key, value):
 if self.writeback:
 self.cache[key] = value
 else:
 f = StringIO()
 p = Pickler(f, self._protocol)
 p.dump(value)
 self.dict[key] = f.getvalue()
seems to match the documentation's intent.
(First report, sorry for any formatting/style issues!)

I think you're misquoting Python's shelve module documentation in your
first sentence. The documentation says:
"By default modified objects are written only when assigned to the shelf
[...]. If the optional writeback parameter is set to True, all entries
accessed are cached in memory, and written back at close time [...]."
The emphasis should be on the word "only:" it does *always* write to the
database when assigned to the shelf but, iff writeback=True, *also* to
the cache.
Also consider the consequences of *only* caching keys:
(a) __contains__ and has_key have to consult the dict and the cache for
membership tests.
(b) keys and __len__ need to compute a union of both sources.
(c) __delitem__ is no longer guaranteed to fail on the cache if it
failed for the database.
I admit the docs could spell this out more clearly. I attached a patch
ensuring the behaviour I described in a test and updating the docs.
(Note: shelve is no extension module -- it's part of the stdlib. Patch
applies to 3.x as well.)

Thanks for the patch. I applied the doc patch and a slightly simplified version of the test in r78141 (we tend to just let errors bubble up rather than code explicit Fails, since as often as not if you provide a specific message it turns out to be wrong when something breaks the test).
I'll merge the change to the other branches as well.