mirror of
https://github.com/python/cpython.git
synced 2024-12-01 11:15:56 +01:00
f8316638af
SourceForge doesn't choke on this batch :-)
I'm not entirely sure this is 100% correct. The patch changes an
\index{persistency} to \index{presistence}, and I don't know what \index{}
does. But it seems to do so persi--er, consistently, so I hope it isn't a
problem.
76 lines
2.8 KiB
TeX
76 lines
2.8 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}
|
|
|
|
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}
|
|
|
|
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}
|