Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{shelve}} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 2 | \stmodindex{shelve} |
| 3 | \stmodindex{pickle} |
| 4 | \bimodindex{dbm} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 5 | \bimodindex{gdbm} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 5680b95 | 1995-02-16 16:29:01 +0000 | [diff] [blame] | 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 |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 48 | Dependent on the implementation, closing a persistent dictionary may |
| 49 | or may not be necessary to flush changes to disk. |
| 50 | |
Guido van Rossum | 5680b95 | 1995-02-16 16:29:01 +0000 | [diff] [blame] | 51 | \item |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 5680b95 | 1995-02-16 16:29:01 +0000 | [diff] [blame] | 58 | |
| 59 | \end{itemize} |