\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, with (g)dbm filename -- no suffix

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
(e.g. \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
Dependent on the implementation, closing a persistent dictionary may
or may not be necessary to flush changes to disk.

\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{seealso}
  \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  \seemodule{dbhash}{BSD \code{db} database interface.}
  \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}