Mercurial > cpython-lru_cache-weakref

annotate Doc/libgdbm.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 c6fe80ce7c20
children 4887d754692a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1765
a04689f9983e Added gdbm docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Module \sectcode{gdbm}}
5817
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
2 \label{module-gdbm}
1765
a04689f9983e Added gdbm docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{gdbm}
a04689f9983e Added gdbm docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
4
5817
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
5 This module is quite similar to the \code{dbm} module, but uses {\sc gdbm}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
6 instead to provide some additional functionality. Please note that
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
7 the file formats created by {\sc gdbm} and dbm are incompatible.
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
8 \bimodindex{dbm}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
9
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
10 The \code{gdbm} module provides an interface to the GNU DBM
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
11 library. {\sc gdbm} objects behave like mappings
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
12 (dictionaries), except that keys and values are always strings.
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
13 Printing a {\sc gdbm} object doesn't print the keys and values, and the
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
14 \code{items()} and \code{values()} methods are not supported.
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
15
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
16 The module defines the following constant and functions:
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
17
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
18 \renewcommand{\indexsubitem}{(in module dbm)}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
19 \begin{excdesc}{error}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
20 Raised on dbm-specific errors, such as I/O errors. \code{KeyError} is
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
21 raised for general mapping errors like specifying an incorrect key.
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
22 \end{excdesc}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
23
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
24 \begin{funcdesc}{open}{filename\, \optional{flag\, \optional{mode}}}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
25 Open a dbm database and return a dbm object. The \var{filename}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
26 argument is the name of the database file (without the \file{.dir} or
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
27 \file{.pag} extensions).
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
28
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
29 The optional \var{flag} argument can be
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
30 \code{'r'} (to open an existing database for reading only --- default),
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
31 \code{'w'} (to open an existing database for reading and writing),
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
32 \code{'c'} (which creates the database if it doesn't exist), or
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
33 \code{'n'} (which always creates a new empty database).
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
34
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
35 Appending \code{f} to the flag opens the database in fast mode;
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
36 altered data will not automatically be written to the disk after every
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
37 change. This results in faster writes to the database, but may result
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
38 in an inconsistent database if the program crashes while the database
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
39 is still open. Use the \code{sync()} method to force any unwritten
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
40 data to be written to the disk.
1765
a04689f9983e Added gdbm docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
41
5817
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
42 The optional \var{mode} argument is the \UNIX{} mode of the file, used
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
43 only when the database has to be created. It defaults to octal
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
44 \code{0666}.
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
45 \end{funcdesc}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
46
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
47 In addition to the dictionary-like methods, {\sc gdbm} objects have the
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
48 following methods:
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
49
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
50 \begin{funcdesc}{firstkey}{}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
51 It's possible to loop over every key in the database using this method
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
52 and the \code{nextkey()} method. The traversal is ordered by {\sc gdbm}'s
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
53 internal hash values, and won't be sorted by the key values. This
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
54 method returns the starting key.
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
55 \end{funcdesc}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
56
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
57 \begin{funcdesc}{nextkey}{key}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
58 Returns the key that follows \var{key} in the traversal. The
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
59 following code prints every key in the database \code{db}, without having to
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
60 create a list in memory that contains them all:
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
61 \bcode\begin{verbatim}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
62 k=db.firstkey()
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
63 while k!=None:
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
64 print k
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
65 k=db.nextkey(k)
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
66 \end{verbatim}\ecode
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
67 \end{funcdesc}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
68
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
69 \begin{funcdesc}{reorganize}{}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
70 If you have carried out a lot of deletions and would like to shrink
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
71 the space used by the {\sc gdbm} file, this routine will reorganize the
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
72 database. {\sc gdbm} will not shorten the length of a database file except
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
73 by using this reorganization; otherwise, deleted file space will be
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
74 kept and reused as new (key,value) pairs are added.
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
75 \end{funcdesc}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
76
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
77 \begin{funcdesc}{sync}{}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
78 When the database has been opened in fast mode, this method forces any
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
79 unwritten data to be written to the disk.
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
80 \end{funcdesc}
48b94de85bf3 Extensive changes by AMK.
Guido van Rossum <guido@python.org>
parents: 2814
diff changeset
81