mirror of https://github.com/python/cpython
* document open() function
* promote the example and the documented restrictions to \subsection status * document the flag parameter of the DbfilenameShelf class
This commit is contained in:
parent
327098a613
commit
190613cee9
|
@ -13,46 +13,35 @@ instances, recursive data types, and objects containing lots of shared
|
||||||
sub-objects. The keys are ordinary strings.
|
sub-objects. The keys are ordinary strings.
|
||||||
\refstmodindex{pickle}
|
\refstmodindex{pickle}
|
||||||
|
|
||||||
To summarize the interface (\code{key} is a string, \code{data} is an
|
\begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,binary=\code{False}}}}
|
||||||
arbitrary object):
|
Open a persistent dictionary. By default, the underlying database file is
|
||||||
|
opened for reading and writing. The optional \var{flag} pararameter, if set
|
||||||
|
to \code{'r'}, can be used to force the file to be opened in read-only mode.
|
||||||
|
By default, ASCII pickles are used to serialize values. If the optional
|
||||||
|
{}\var{binary} parameter is set to \var{True}, binary pickles will be used
|
||||||
|
instead.
|
||||||
|
\end{funcdesc}
|
||||||
|
|
||||||
\begin{verbatim}
|
Shelve objects support all methods supported by dictionaries. This eases
|
||||||
import shelve
|
the transition from dictionary based scripts to those requiring persistent
|
||||||
|
storage.
|
||||||
|
|
||||||
d = shelve.open(filename) # open -- file may get suffix added by low-level
|
\subsection{Restrictions}
|
||||||
# library
|
|
||||||
|
|
||||||
d[key] = data # store data at key (overwrites old data if
|
|
||||||
# using an existing key)
|
|
||||||
data = d[key] # retrieve data at key (raise KeyError if no
|
|
||||||
# such key)
|
|
||||||
del d[key] # delete data stored at key (raises KeyError
|
|
||||||
# if no such key)
|
|
||||||
flag = d.has_key(key) # true if the key exists
|
|
||||||
list = d.keys() # a list of all existing keys (slow!)
|
|
||||||
|
|
||||||
d.close() # close it
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
In addition to the above, shelve supports all methods that are
|
|
||||||
supported by dictionaries. This eases the transition from dictionary
|
|
||||||
based scripts to those requiring persistent storage.
|
|
||||||
|
|
||||||
Restrictions:
|
|
||||||
|
|
||||||
\begin{itemize}
|
\begin{itemize}
|
||||||
|
|
||||||
\item
|
\item
|
||||||
The choice of which database package will be used
|
The choice of which database package will be used
|
||||||
(such as \refmodule{dbm} or \refmodule{gdbm}) depends on which interface
|
(such as \refmodule{dbm}, \refmodule{gdbm} or \refmodule{bsddb}) depends on
|
||||||
is available. Therefore it is not safe to open the database directly
|
which interface is available. Therefore it is not safe to open the database
|
||||||
using \refmodule{dbm}. The database is also (unfortunately) subject
|
directly using \refmodule{dbm}. The database is also (unfortunately) subject
|
||||||
to the limitations of \refmodule{dbm}, if it is used --- this means
|
to the limitations of \refmodule{dbm}, if it is used --- this means
|
||||||
that (the pickled representation of) the objects stored in the
|
that (the pickled representation of) the objects stored in the
|
||||||
database should be fairly small, and in rare cases key collisions may
|
database should be fairly small, and in rare cases key collisions may
|
||||||
cause the database to refuse updates.
|
cause the database to refuse updates.
|
||||||
\refbimodindex{dbm}
|
\refbimodindex{dbm}
|
||||||
\refbimodindex{gdbm}
|
\refbimodindex{gdbm}
|
||||||
|
\refbimodindex{bsddb}
|
||||||
|
|
||||||
\item
|
\item
|
||||||
Depending on the implementation, closing a persistent dictionary may
|
Depending on the implementation, closing a persistent dictionary may
|
||||||
|
@ -92,10 +81,35 @@ class.
|
||||||
A subclass of \class{Shelf} which accepts a \var{filename} instead of a dict-like
|
A subclass of \class{Shelf} which accepts a \var{filename} instead of a dict-like
|
||||||
object. The underlying file will be opened using \function{anydbm.open}.
|
object. The underlying file will be opened using \function{anydbm.open}.
|
||||||
By default, the file will be created and opened for both read and write.
|
By default, the file will be created and opened for both read and write.
|
||||||
|
The optional \var{flag} parameter has the same interpretation as for the
|
||||||
|
\function{open} function.
|
||||||
The optional \var{binary} parameter has the same interpretation as for the
|
The optional \var{binary} parameter has the same interpretation as for the
|
||||||
\class{Shelf} class.
|
\class{Shelf} class.
|
||||||
\end{classdesc}
|
\end{classdesc}
|
||||||
|
|
||||||
|
\subsection{Example}
|
||||||
|
|
||||||
|
To summarize the interface (\code{key} is a string, \code{data} is an
|
||||||
|
arbitrary object):
|
||||||
|
|
||||||
|
\begin{verbatim}
|
||||||
|
import shelve
|
||||||
|
|
||||||
|
d = shelve.open(filename) # open -- file may get suffix added by low-level
|
||||||
|
# library
|
||||||
|
|
||||||
|
d[key] = data # store data at key (overwrites old data if
|
||||||
|
# using an existing key)
|
||||||
|
data = d[key] # retrieve data at key (raise KeyError if no
|
||||||
|
# such key)
|
||||||
|
del d[key] # delete data stored at key (raises KeyError
|
||||||
|
# if no such key)
|
||||||
|
flag = d.has_key(key) # true if the key exists
|
||||||
|
list = d.keys() # a list of all existing keys (slow!)
|
||||||
|
|
||||||
|
d.close() # close it
|
||||||
|
\end{verbatim}
|
||||||
|
|
||||||
\begin{seealso}
|
\begin{seealso}
|
||||||
\seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
|
\seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
|
||||||
\seemodule{bsddb}{BSD \code{db} database interface.}
|
\seemodule{bsddb}{BSD \code{db} database interface.}
|
||||||
|
|
Loading…
Reference in New Issue