mirror of https://github.com/python/cpython
173 lines
7.5 KiB
TeX
173 lines
7.5 KiB
TeX
\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{,protocol=\code{None}\optional{,writeback=\code{False}}}}}
|
|
Open a persistent dictionary. The filename specified is the base filename
|
|
for the underlying database. As a side-effect, an extension may be added to
|
|
the filename and more than one file may be created. By default, the
|
|
underlying database file is opened for reading and writing. The optional
|
|
{}\var{flag} parameter has the same interpretation as the \var{flag}
|
|
parameter of \function{anydbm.open}.
|
|
|
|
By default, version 0 pickles are used to serialize values.
|
|
The version of the pickle protocol can be specified with the
|
|
\var{protocol} parameter. \versionchanged[The \var{protocol}
|
|
parameter was added]{2.3}
|
|
|
|
By default, mutations to persistent-dictionary mutable entries are not
|
|
automatically written back. If the optional \var{writeback} parameter
|
|
is set to {}\var{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).
|
|
|
|
\end{funcdesc}
|
|
|
|
Shelve objects support all methods supported by dictionaries. This eases
|
|
the transition from dictionary based scripts to those requiring persistent
|
|
storage.
|
|
|
|
One additional method is supported:
|
|
\begin{methoddesc}[Shelf]{sync}{}
|
|
Write back all entries in the cache if the shelf was opened with
|
|
\var{writeback} set to \var{True}. Also empty the cache and synchronize
|
|
the persistent dictionary on disk, if feasible. This is called automatically
|
|
when the shelf is closed with \method{close()}.
|
|
\end{methoddesc}
|
|
|
|
\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{, protocol=None\optional{, writeback=False}}}
|
|
A subclass of \class{UserDict.DictMixin} which stores pickled values in the
|
|
\var{dict} object.
|
|
|
|
By default, version 0 pickles are used to serialize values. The
|
|
version of the pickle protocol can be specified with the
|
|
\var{protocol} parameter. See the \module{pickle} documentation for a
|
|
discussion of the pickle protocols. \versionchanged[The \var{protocol}
|
|
parameter was added]{2.3}
|
|
|
|
If the \var{writeback} parameter is \code{True}, the object will hold a
|
|
cache of all entries accessed and write them back to the \var{dict} at
|
|
sync and close times. This allows natural operations on mutable entries,
|
|
but can consume much more memory and make sync and close take a long time.
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{BsdDbShelf}{dict\optional{, protocol=None\optional{, writeback=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{protocol} and \var{writeback} parameters have the
|
|
same interpretation as for the \class{Shelf} class.
|
|
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{DbfilenameShelf}{filename\optional{, flag='c'\optional{, protocol=None\optional{, writeback=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{protocol} and \var{writeback} parameters
|
|
have 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 a COPY of 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!)
|
|
|
|
# as d was opened WITHOUT writeback=True, beware:
|
|
d['xx'] = range(4) # this works as expected, but...
|
|
d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!!!
|
|
# having opened d without writeback=True, you need to code carefully:
|
|
temp = d['xx'] # extracts the copy
|
|
temp.append(5) # mutates the copy
|
|
d['xx'] = temp # stores the copy right back, to persist it
|
|
# or, d=shelve.open(filename,writeback=True) would let you just code
|
|
# d['xx'].append(5) and have it work as expected, BUT it would also
|
|
# consume more memory and make the d.close() operation slower.
|
|
|
|
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}
|