The documentation of shelve.open() states (paragraph 3) that "By default, mutations to persistent-dictionary mutable entries are not automatically written back." It then goes on to describe what happens if the writeback parameter is True, which involves caching the entire dictionary of objects in memory and writing the whole thing back on close. But what happens if writeback is False, the default? The statement that the mutable entires are not automatically written back leaves open the question of how to write them back. shelf.sync() is documented as being used only when writeback is true. Also, for a user unfamiliar with the nuances of persistence the sentence quoted above is somewhat mysterious -- "persistent-dictionary mutable entries"? "written back"?
OK, I've figured out from the comments in the example later on in the shelf documentation what the paragraph is supposed to mean. I still think it should be stated clearly. The distinction to be made is that modifications to the dictionary immediately change the file contents -- d[key] = data and del d[key] are, I think, the only actions that fall under this category -- but getting a value from the shelf then modifying that value does NOT affect the underlying dictionary. Ever. It's not a matter of WHEN, but WHETHER. (when writeback is False)
I remember being confused by that paragraph. Attached is a suggested doc fix. Do you think it makes it clear enough? (I'm not happy with the redundancy of saying mutation can't be detected twice in the same paragraph, but it seems better to be redundant than unclear.)
>http://bugs.python.org/file13925/issue5957.doc.patch I just spent some time attempting a rewrite, and while I liked what I ended up with it wasn't all that different from the patch. I'm happy with the patch. -- -- --- Mitchell
files: + unnamedmessages: + title: Possible mistake regarding writeback in documentation of shelve.open() -> Possible mistake regarding writeback in documentation of shelve.open()
