Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libshelve.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents f47bc5554418
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2353
diff changeset
1 \section{Standard Module \sectcode{shelve}}
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \stmodindex{shelve}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \stmodindex{pickle}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 \bimodindex{dbm}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2353
diff changeset
5 \bimodindex{gdbm}
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 A ``shelf'' is a persistent, dictionary-like object. The difference
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 with ``dbm'' databases is that the values (not the keys!) in a shelf
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 can be essentially arbitrary Python objects --- anything that the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 \code{pickle} module can handle. This includes most class instances,
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 recursive data types, and objects containing lots of shared
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 sub-objects. The keys are ordinary strings.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
13
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 To summarize the interface (\code{key} is a string, \code{data} is an
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 arbitrary object):
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \begin{verbatim}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 import shelve
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
19
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 d[key] = data # store data at key (overwrites old data if
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 # using an existing key)
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 data = d[key] # retrieve data at key (raise KeyError if no
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 # such key)
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 del d[key] # delete data stored at key (raises KeyError
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 # if no such key)
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 flag = d.has_key(key) # true if the key exists
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 list = d.keys() # a list of all existing keys (slow!)
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
30
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 d.close() # close it
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 \end{verbatim}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
33
2353
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
34 Restrictions:
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
35
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
36 \begin{itemize}
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
37
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
38 \item
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
39 The choice of which database package will be used (e.g. dbm or gdbm)
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
40 depends on which interface is available. Therefore it isn't safe to
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
41 open the database directly using dbm. The database is also
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
42 (unfortunately) subject to the limitations of dbm, if it is used ---
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
43 this means that (the pickled representation of) the objects stored in
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
44 the database should be fairly small, and in rare cases key collisions
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
45 may cause the database to refuse updates.
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
46
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
47 \item
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 Dependent on the implementation, closing a persistent dictionary may
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 or may not be necessary to flush changes to disk.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
50
2353
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
51 \item
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2353
diff changeset
52 The \code{shelve} module does not support {\em concurrent} read/write
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2353
diff changeset
53 access to shelved objects. (Multiple simultaneous read accesses are
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2353
diff changeset
54 safe.) When a program has a shelf open for writing, no other program
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2353
diff changeset
55 should have it open for reading or writing. \UNIX{} file locking can
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2353
diff changeset
56 be used to solve this, but this differs across \UNIX{} versions and
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2353
diff changeset
57 requires knowledge about the database implementation used.
2353
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
58
8a8765343cc0 added list of restrictions
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
59 \end{itemize}