\section{\module{shelve} ---
         Python object persistence}

\declaremodule{standard}{shelve}
\modulesynopsis{Python object persistence.}


A ``shelf'' is a persistent, dictionary-like object.  The difference
with ``dbm'' databases is that the values (not the keys!) in a shelf
can be essentially arbitrary Python objects --- anything that the
\refmodule{pickle} module can handle.  This includes most class
instances, recursive data types, and objects containing lots of shared 
sub-objects.  The keys are ordinary strings.
\refstmodindex{pickle}

To summarize the interface (\code{key} is a string, \code{data} is an
arbitrary object):

\begin{verbatim}
import shelve

d = shelve.open(filename) # open -- file may get suffix added by low-level
                          # library

d[key] = data   # store data at key (overwrites old data if
                # using an existing key)
data = d[key]   # retrieve data at key (raise KeyError if no
                # such key)
del d[key]      # delete data stored at key (raises KeyError
                # if no such key)
flag = d.has_key(key)   # true if the key exists
list = d.keys() # a list of all existing keys (slow!)

d.close()       # close it
\end{verbatim}

In addition to the above, shelve supports all methods that are
supported by dictionaries.  This eases the transition from dictionary
based scripts to those requiring persistent storage.

Restrictions:

\begin{itemize}

\item
The choice of which database package will be used
(such as \refmodule{dbm} or \refmodule{gdbm}) depends on which interface
is available.  Therefore it is not safe to open the database directly
using \refmodule{dbm}.  The database is also (unfortunately) subject
to the limitations of \refmodule{dbm}, if it is used --- this means
that (the pickled representation of) the objects stored in the
database should be fairly small, and in rare cases key collisions may
cause the database to refuse updates.
\refbimodindex{dbm}
\refbimodindex{gdbm}

\item
Depending on the implementation, closing a persistent dictionary may
or may not be necessary to flush changes to disk.  The \method{__del__}
method of the \class{Shelf} class calls the \method{close} method, so the
programmer generally need not do this explicitly.

\item
The \module{shelve} module does not support \emph{concurrent} read/write
access to shelved objects.  (Multiple simultaneous read accesses are
safe.)  When a program has a shelf open for writing, no other program
should have it open for reading or writing.  \UNIX{} file locking can
be used to solve this, but this differs across \UNIX{} versions and
requires knowledge about the database implementation used.

\end{itemize}

\begin{classdesc}{Shelf}{dict\optional{, binary=False}}
A subclass of \class{UserDict.DictMixin} which stores pickled values in the
\var{dict} object.  If the \var{binary} parameter is \code{True}, binary
pickles will be used.  This can provide much more compact storage than plain
text pickles, depending on the nature of the objects stored in the database.
\end{classdesc}

\begin{classdesc}{BsdDbShelf}{dict\optional{, binary=False}}
A subclass of \class{Shelf} which exposes \method{first}, \method{next},
\method{previous}, \method{last} and \method{set_location} which are
available in the \module{bsddb} module but not in other database modules.
The \var{dict} object passed to the constructor must support those methods.
This is generally accomplished by calling one of \function{bsddb.hashopen},
\function{bsddb.btopen} or \function{bsddb.rnopen}.  The optional
\var{binary} parameter has the same interpretation as for the \class{Shelf}
class. 
\end{classdesc}

\begin{classdesc}{DbfilenameShelf}{filename\optional{, flag='c'\optional{, binary=False}}}
A subclass of \class{Shelf} which accepts a \var{filename} instead of a dict-like
object.  The underlying file will be opened using \function{anydbm.open}.
By default, the file will be created and opened for both read and write.
The optional \var{binary} parameter has the same interpretation as for the
\class{Shelf} class.
\end{classdesc}

\begin{seealso}
  \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  \seemodule{bsddb}{BSD \code{db} database interface.}
  \seemodule{dbhash}{Thin layer around the \module{bsddb} which provides an
  \function{open} function like the other database modules.}
  \seemodule{dbm}{Standard \UNIX{} database interface.}
  \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
  \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
  \seemodule{pickle}{Object serialization used by \module{shelve}.}
  \seemodule{cPickle}{High-performance version of \refmodule{pickle}.}
\end{seealso}