Doc/lib/libshelve.tex

   1 \section{\module{shelve} ---
   2          Python object persistence}
   3
   4 \declaremodule{standard}{shelve}
   5 \modulesynopsis{Python object persistence.}
   6
   7
   8 A ``shelf'' is a persistent, dictionary-like object.  The difference
   9 with ``dbm'' databases is that the values (not the keys!) in a shelf
  10 can be essentially arbitrary Python objects --- anything that the
  11 \refmodule{pickle} module can handle.  This includes most class
  12 instances, recursive data types, and objects containing lots of shared
  13 sub-objects.  The keys are ordinary strings.
  14 \refstmodindex{pickle}
  15
  16 To summarize the interface (\code{key} is a string, \code{data} is an
  17 arbitrary object):
  18
  19 \begin{verbatim}
  20 import shelve
  21
  22 d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
  23
  24 d[key] = data   # store data at key (overwrites old data if
  25                 # using an existing key)
  26 data = d[key]   # retrieve data at key (raise KeyError if no
  27                 # such key)
  28 del d[key]      # delete data stored at key (raises KeyError
  29                 # if no such key)
  30 flag = d.has_key(key)   # true if the key exists
  31 list = d.keys() # a list of all existing keys (slow!)
  32
  33 d.close()       # close it
  34 \end{verbatim}
  35
  36 Restrictions:
  37
  38 \begin{itemize}
  39
  40 \item
  41 The choice of which database package will be used
  42 (e.g. \refmodule{dbm} or \refmodule{gdbm}) depends on which interface
  43 is available.  Therefore it is not safe to open the database directly
  44 using \refmodule{dbm}.  The database is also (unfortunately) subject
  45 to the limitations of \refmodule{dbm}, if it is used --- this means
  46 that (the pickled representation of) the objects stored in the
  47 database should be fairly small, and in rare cases key collisions may
  48 cause the database to refuse updates.
  49 \refbimodindex{dbm}
  50 \refbimodindex{gdbm}
  51
  52 \item
  53 Dependent on the implementation, closing a persistent dictionary may
  54 or may not be necessary to flush changes to disk.
  55
  56 \item
  57 The \module{shelve} module does not support \emph{concurrent} read/write
  58 access to shelved objects.  (Multiple simultaneous read accesses are
  59 safe.)  When a program has a shelf open for writing, no other program
  60 should have it open for reading or writing.  \UNIX{} file locking can
  61 be used to solve this, but this differs across \UNIX{} versions and
  62 requires knowledge about the database implementation used.
  63
  64 \end{itemize}
  65
  66
  67 \begin{seealso}
  68   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  69   \seemodule{dbhash}{BSD \code{db} database interface.}
  70   \seemodule{dbm}{Standard \UNIX{} database interface.}
  71   \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
  72   \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
  73   \seemodule{pickle}{Object serialization used by \module{shelve}.}
  74   \seemodule{cPickle}{High-performance version of \refmodule{pickle}.}
  75 \end{seealso}