summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libanydbm.tex
blob: eef4d03e2447c25ee3a86db53970cc7bd74b4c08 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
\section{\module{anydbm} ---
         Generic access to DBM-style databases}

\declaremodule{standard}{anydbm}
\modulesynopsis{Generic interface to DBM-style database modules.}


\module{anydbm} is a generic interface to variants of the DBM
database --- \refmodule{dbhash}\refstmodindex{dbhash} (requires
\refmodule{bsddb}\refbimodindex{bsddb}),
\refmodule{gdbm}\refbimodindex{gdbm}, or
\refmodule{dbm}\refbimodindex{dbm}.  If none of these modules is
installed, the slow-but-simple implementation in module
\refmodule{dumbdbm}\refstmodindex{dumbdbm} will be used.

\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
Open the database file \var{filename} and return a corresponding object.

If the database file already exists, the \refmodule{whichdb} module is 
used to determine its type and the appropriate module is used; if it
does not exist, the first module listed above that can be imported is
used.

The optional \var{flag} argument can be
\code{'r'} to open an existing database for reading only,
\code{'w'} to open an existing database for reading and writing,
\code{'c'} to create the database if it doesn't exist, or
\code{'n'}, which will always create a new empty database.  If not
specified, the default value is \code{'r'}.

The optional \var{mode} argument is the \UNIX{} mode of the file, used
only when the database has to be created.  It defaults to octal
\code{0666} (and will be modified by the prevailing umask).
\end{funcdesc}

\begin{excdesc}{error}
A tuple containing the exceptions that can be raised by each of the
supported modules, with a unique exception \exception{anydbm.error} as
the first item --- the latter is used when \exception{anydbm.error} is
raised.
\end{excdesc}

The object returned by \function{open()} supports most of the same
functionality as dictionaries; keys and their corresponding values can
be stored, retrieved, and deleted, and the \method{has_key()} and
\method{keys()} methods are available.  Keys and values must always be
strings.


\begin{seealso}
  \seemodule{dbhash}{BSD \code{db} database interface.}
  \seemodule{dbm}{Standard \UNIX{} database interface.}
  \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
  \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
  \seemodule{shelve}{General object persistence built on top of 
                     the Python \code{dbm} interface.}
  \seemodule{whichdb}{Utility module used to determine the type of an
                      existing database.}
\end{seealso}


\section{\module{dumbdbm} ---
         Portable DBM implementation}

\declaremodule{standard}{dumbdbm}
\modulesynopsis{Portable implementation of the simple DBM interface.}


A simple and slow database implemented entirely in Python.  This
should only be used when no other DBM-style database is available.


\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
Open the database file \var{filename} and return a corresponding
object.  The \var{flag} argument, used to control how the database is
opened in the other DBM implementations, is ignored in
\module{dumbdbm}; the database is always opened for update, and will
be created if it does not exist.

The optional \var{mode} argument is the \UNIX{} mode of the file, used
only when the database has to be created.  It defaults to octal
\code{0666} (and will be modified by the prevailing umask).
\versionchanged[The \var{mode} argument was ignored in earlier
                versions]{2.2}
\end{funcdesc}

\begin{excdesc}{error}
Raised for errors not reported as \exception{KeyError} errors.
\end{excdesc}


\begin{seealso}
  \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  \seemodule{whichdb}{Utility module used to determine the type of an
                      existing database.}
\end{seealso}