Make it clear up front that shelve only records changes

when objects are assigned back to it when writeback is False.

diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 8a34dd6f4ef6472dbb0314e475edd2ff120899ca..4e18ab155c4909c03bf5dedbd7347dd42816474d 100644 (file)
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -28,13 +28,15 @@ lots of shared  sub-objects.  The keys are ordinary strings.
    .. versionchanged:: 2.3
       The *protocol* parameter was added.
 
-   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; this can make it handier to mutate mutable entries in the persistent
-   dictionary, but, if many entries are accessed, it can consume vast amounts of
-   memory for the cache, and it can make the close operation very slow since all
-   accessed entries are written back (there is no way to determine which accessed
+   Because of Python semantics, a shelf cannot know when a mutable
+   persistent-dictionary entry is modified.  By default modified objects are
+   written only when assigned to the shelf (see :ref:`shelve-example`).  If
+   the optional *writeback* parameter is set to *True*, all entries accessed
+   are cached in memory, and written back at close time; this can make it
+   handier to mutate mutable entries in the persistent dictionary, but, if
+   many entries are accessed, it can consume vast amounts of memory for the
+   cache, and it can make the close operation very slow since all accessed
+   entries are written back (there is no way to determine which accessed
    entries are mutable, nor which ones were actually mutated).
 
 Shelf objects support all methods supported by dictionaries.  This eases the
@@ -125,6 +127,8 @@ Restrictions
    interpretation as for the :class:`Shelf` class.
 
 
+.. _shelve-example:
+
 Example
 -------