Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdbhash.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 75c1f9c3f0d1
children d039b1bb1ea9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10607
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{dbhash} ---
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 DBM-style interface to the BSD database library}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{dbhash}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \platform{Unix, Windows}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \modulesynopsis{DBM-style interface to the BSD database library.}
10612
f425e60ac71a Minor nits, include author info.
Fred Drake <fdrake@acm.org>
parents: 10607
diff changeset
7 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
10607
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 The \module{dbhash} module provides a function to open databases using
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 the BSD \code{db} library. This module mirrors the interface of the
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 other Python database modules that provide access to DBM-style
10625
ad55bdba5dff bsddb docs from Skip Montanaro; added interesting links.
Fred Drake <fdrake@acm.org>
parents: 10612
diff changeset
13 databases. The \refmodule{bsddb}\refbimodindex{bsddb} module is required
10607
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 to use \module{dbhash}.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 This module provides an exception and a function:
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19 \begin{excdesc}{error}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 Exception raised on database errors other than
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 \exception{KeyError}. It is a synonym for \exception{bsddb.error}.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 \end{excdesc}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23
18311
75c1f9c3f0d1 Remove duplicate ', ' in dbhash.open()'s argument list.
Thomas Wouters <thomas@python.org>
parents: 18038
diff changeset
24 \begin{funcdesc}{open}{path\optional{, flag\optional{, mode}}}
10607
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 Open a \code{db} database and return the database object. The
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 \var{path} argument is the name of the database file.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 The \var{flag} argument can be
10612
f425e60ac71a Minor nits, include author info.
Fred Drake <fdrake@acm.org>
parents: 10607
diff changeset
29 \code{'r'} (the default), \code{'w'},
10607
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 \code{'c'} (which creates the database if it doesn't exist), or
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 \code{'n'} (which always creates a new empty database).
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32 For platforms on which the BSD \code{db} library supports locking,
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 an \character{l} can be appended to indicate that locking should be
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34 used.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 The optional \var{mode} parameter is used to indicate the \UNIX{}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 permission bits that should be set if a new database must be
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 created; this will be masked by the current umask value for the
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 process.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 \end{funcdesc}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 \begin{seealso}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
10625
ad55bdba5dff bsddb docs from Skip Montanaro; added interesting links.
Fred Drake <fdrake@acm.org>
parents: 10612
diff changeset
45 \seemodule{bsddb}{Lower-level interface to the BSD \code{db} library.}
10607
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 \seemodule{whichdb}{Utility module used to determine the type of an
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 existing database.}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48 \end{seealso}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 \subsection{Database Objects \label{dbhash-objects}}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 The database objects returned by \function{open()} provide the methods
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 common to all the DBM-style databases. The following methods are
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 available in addition to the standard methods.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 \begin{methoddesc}[dbhash]{first}{}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 It's possible to loop over every key in the database using this method
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 and the \method{next()} method. The traversal is ordered by
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 the databases internal hash values, and won't be sorted by the key
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 values. This method returns the starting key.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62 \end{methoddesc}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 \begin{methoddesc}[dbhash]{last}{}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 Return the last key in a database traversal. This may be used to
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 begin a reverse-order traversal; see \method{previous()}.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 \end{methoddesc}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 \begin{methoddesc}[dbhash]{next}{key}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 Returns the key that follows \var{key} in the traversal. The
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 following code prints every key in the database \code{db}, without
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 having to create a list in memory that contains them all:
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 \begin{verbatim}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 k = db.first()
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 while k != None:
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77 print k
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 k = db.next(k)
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 \end{verbatim}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \end{methoddesc}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 \begin{methoddesc}[dbhash]{previous}{key}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 Return the key that comes before \var{key} in a forward-traversal of
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 the database. In conjunction with \method{last()}, this may be used
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85 to implement a reverse-order traversal.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 \end{methoddesc}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 \begin{methoddesc}[dbhash]{sync}{}
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 This method forces any unwritten data to be written to the disk.
fcaac41f6f3a Document the dbhash module, and link to it from appropriate places.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 \end{methoddesc}