\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}

\begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,binary=\code{False}}}}
Open a persistent dictionary.  By default, the underlying database file is
opened for reading and writing.  The optional \var{flag} pararameter, if set
to \code{'r'}, can be used to force the file to be opened in read-only mode.
By default, ASCII pickles are used to serialize values.  If the optional
{}\var{binary} parameter is set to \var{True}, binary pickles will be used
instead.
\end{funcdesc}

Shelve objects support all methods supported by dictionaries.  This eases
the transition from dictionary based scripts to those requiring persistent
storage.

\subsection{Restrictions}

\begin{itemize}

\item
The choice of which database package will be used
(such as \refmodule{dbm}, \refmodule{gdbm} or \refmodule{bsddb}) 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}
\refbimodindex{bsddb}

\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{flag} parameter has the same interpretation as for the
\function{open} function.
The optional \var{binary} parameter has the same interpretation as for the
\class{Shelf} class.
\end{classdesc}

\subsection{Example}

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}

\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}