Doc/libshelve.tex

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