Changeset 391 for python/trunk/Doc/library/shelve.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/shelve.rst (modified) (6 diffs)

python/trunk/Doc/library/shelve.rst

@@ -7 +7 @@
 
 .. index:: module: pickle
+
+**Source code:** :source:`Lib/shelve.py`
+
+--------------
 
 A "shelf" is a persistent, dictionary-like object.  The difference with "dbm"
@@ -15 +19 @@
 
 
-.. function:: open(filename[, flag='c'[, protocol=None[, writeback=False]]])
+.. function:: open(filename, flag='c', protocol=None, writeback=False)
 
    Open a persistent dictionary.  The filename specified is the base filename for
@@ -41 +45 @@
    mutated).
 
-   .. note::
-
-      Do not rely on the shelf being closed automatically; always call
-      :meth:`close` explicitly when you don't need it any more, or use a
-      :keyword:`with` statement with :func:`contextlib.closing`.
-
+   Like file objects, shelve objects should be closed explicitly to ensure
+   that the persistent data is flushed to disk.
+
+.. warning::
+
+   Because the :mod:`shelve` module is backed by :mod:`pickle`, it is insecure
+   to load a shelf from an untrusted source.  Like with pickle, loading a shelf
+   can execute arbitrary code.
 
 Shelf objects support all methods supported by dictionaries.  This eases the
@@ -97 +103 @@
 
 
-.. class:: Shelf(dict[, protocol=None[, writeback=False]])
+.. class:: Shelf(dict, protocol=None, writeback=False)
 
    A subclass of :class:`UserDict.DictMixin` which stores pickled values in the
@@ -115 +121 @@
 
 
-.. class:: BsdDbShelf(dict[, protocol=None[, writeback=False]])
+.. class:: BsdDbShelf(dict, protocol=None, writeback=False)
 
    A subclass of :class:`Shelf` which exposes :meth:`first`, :meth:`!next`,
@@ -126 +132 @@
 
 
-.. class:: DbfilenameShelf(filename[, flag='c'[, protocol=None[, writeback=False]]])
+.. class:: DbfilenameShelf(filename, flag='c', protocol=None, writeback=False)
 
    A subclass of :class:`Shelf` which accepts a *filename* instead of a dict-like