classification
Title: Possible mistake regarding writeback in documentation of shelve.open()
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.0, Python 3.1, Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: r.david.murray Nosy List: MLModel, georg.brandl, r.david.murray
Priority: low Keywords: patch

Created on 2009-05-07 18:00 by MLModel, last changed 2009-05-12 01:42 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
issue5957.doc.patch r.david.murray, 2009-05-08 16:47
unnamed MLModel, 2009-05-08 18:27
Messages (5)
msg87381 - (view) Author: Mitchell Model (MLModel) Date: 2009-05-07 18:00
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"?
msg87384 - (view) Author: Mitchell Model (MLModel) Date: 2009-05-07 18:24
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)
msg87449 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2009-05-08 16:47
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.)
msg87456 - (view) Author: Mitchell Model (MLModel) Date: 2009-05-08 18:27
>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
msg87601 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2009-05-12 01:42
Fixed in r72572, r72573, r72574, and r72575.
History
Date User Action Args
2009-05-12 01:42:47r.david.murraysetstatus: open -> closed
resolution: fixed
messages: + msg87601

stage: patch review -> resolved
2009-05-08 18:27:40MLModelsetfiles: + unnamed

messages: + msg87456
title: Possible mistake regarding writeback in documentation of shelve.open() -> Possible mistake regarding writeback in documentation of shelve.open()
2009-05-08 16:47:26r.david.murraysetfiles: + issue5957.doc.patch


assignee: georg.brandl -> r.david.murray
keywords: + patch
stage: patch review
versions: + Python 2.6, Python 2.7
nosy: + r.david.murray
messages: + msg87449
priority: low
type: behavior
2009-05-07 18:24:41MLModelsetmessages: + msg87384
2009-05-07 18:00:39MLModelcreate