diff options
Diffstat (limited to 'Doc/library/dbm.rst')
| -rw-r--r-- | Doc/library/dbm.rst | 351 |
1 files changed, 334 insertions, 17 deletions
diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index 52923e8..2a314dc 100644 --- a/Doc/library/dbm.rst +++ b/Doc/library/dbm.rst @@ -1,14 +1,294 @@ - -:mod:`dbm` --- Simple "database" interface -========================================== +:mod:`dbm` --- Interfaces to Unix "databases" +============================================= .. module:: dbm + :synopsis: Interfaces to various Unix "database" formats. + +:mod:`dbm` is a generic interface to variants of the DBM database --- +:mod:`dbm.bsd` (requires :mod:`bsddb`), :mod:`dbm.gnu`, or :mod:`dbm.ndbm`. If +none of these modules is installed, the slow-but-simple implementation in module +:mod:`dbm.dumb` will be used. + + +.. exception:: error + + A tuple containing the exceptions that can be raised by each of the supported + modules, with a unique exception also named :exc:`dbm.error` as the first + item --- the latter is used when :exc:`dbm.error` is raised. + + +.. function:: whichdb(filename) + + This functionattempts to guess which of the several simple database modules + available --- :mod:`dbm.bsd`, :mod:`dbm.gnu`, :mod:`dbm.ndbm` or + :mod:`dbm.dumb` --- should be used to open a given file. + + Returns one of the following values: ``None`` if the file can't be opened + because it's unreadable or doesn't exist; the empty string (``''``) if the + file's format can't be guessed; or a string containing the required module + name, such as ``'dbm.ndbm'`` or ``'dbm.gnu'``. + + +.. function:: open(filename[, flag[, mode]]) + + Open the database file *filename* and return a corresponding object. + + If the database file already exists, the :func:`whichdb` function 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 *flag* argument can be ``'r'`` to open an existing database for + reading only, ``'w'`` to open an existing database for reading and writing, + ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will + always create a new empty database. If not specified, the default value is + ``'r'``. + + The optional *mode* argument is the Unix mode of the file, used only when the + database has to be created. It defaults to octal ``0o666`` (and will be + modified by the prevailing umask). + + +The object returned by :func:`open` supports most of the same functionality as +dictionaries; keys and their corresponding values can be stored, retrieved, and +deleted, and the :keyword:`in` operator and the :meth:`keys` method are +available. Keys and values must always be strings. + +The following example records some hostnames and a corresponding title, and +then prints out the contents of the database:: + + import dbm + + # Open database, creating it if necessary. + db = dbm.open('cache', 'c') + + # Record some values + db['www.python.org'] = 'Python Website' + db['www.cnn.com'] = 'Cable News Network' + + # Loop through contents. Other dictionary methods + # such as .keys(), .values() also work. + for k, v in db.iteritems(): + print(k, '\t', v) + + # Storing a non-string key or value will raise an exception (most + # likely a TypeError). + db['www.yahoo.com'] = 4 + + # Close when done. + db.close() + + +.. seealso:: + + Module :mod:`shelve` + Persistence module which stores non-string data. + + +The individual submodules are described in the following sections. + + +:mod:`dbm.bsd` --- DBM-style interface to the BSD database library +------------------------------------------------------------------ + +.. module:: dbm.bsd + :synopsis: DBM-style interface to the BSD database library. +.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> + +.. index:: module: bsddb + +The :mod:`dbm.bsd` module provides a function to open databases using the BSD +``db`` library. This module mirrors the interface of the other Python database +modules that provide access to DBM-style databases. The :mod:`bsddb` module is +required to use :mod:`dbm.bsd`. + +.. exception:: error + + Exception raised on database errors other than :exc:`KeyError`. It is a synonym + for :exc:`bsddb.error`. + + +.. function:: open(path[, flag[, mode]]) + + Open a ``db`` database and return the database object. The *path* argument is + the name of the database file. + + The *flag* argument can be: + + +---------+-------------------------------------------+ + | Value | Meaning | + +=========+===========================================+ + | ``'r'`` | Open existing database for reading only | + | | (default) | + +---------+-------------------------------------------+ + | ``'w'`` | Open existing database for reading and | + | | writing | + +---------+-------------------------------------------+ + | ``'c'`` | Open database for reading and writing, | + | | creating it if it doesn't exist | + +---------+-------------------------------------------+ + | ``'n'`` | Always create a new, empty database, open | + | | for reading and writing | + +---------+-------------------------------------------+ + + For platforms on which the BSD ``db`` library supports locking, an ``'l'`` + can be appended to indicate that locking should be used. + + The optional *mode* parameter is used to indicate the Unix permission bits that + should be set if a new database must be created; this will be masked by the + current umask value for the process. + + The database objects returned by :func:`open` provide the methods common to all + the DBM-style databases and mapping objects. The following methods are + available in addition to the standard methods: + + .. method:: dbhash.first() + + It's possible to loop over every key/value pair in the database using this + method and the :meth:`next` method. The traversal is ordered by the databases + internal hash values, and won't be sorted by the key values. This method + returns the starting key. + + .. method:: dbhash.last() + + Return the last key/value pair in a database traversal. This may be used to + begin a reverse-order traversal; see :meth:`previous`. + + .. method:: dbhash.next() + + Returns the key next key/value pair in a database traversal. The following code + prints every key in the database ``db``, without having to create a list in + memory that contains them all:: + + print(db.first()) + for i in range(1, len(db)): + print(db.next()) + + .. method:: dbhash.previous() + + Returns the previous key/value pair in a forward-traversal of the database. In + conjunction with :meth:`last`, this may be used to implement a reverse-order + traversal. + + .. method:: dbhash.sync() + + This method forces any unwritten data to be written to the disk. + + +:mod:`dbm.gnu` --- GNU's reinterpretation of dbm +------------------------------------------------ + +.. module:: dbm.gnu + :platform: Unix + :synopsis: GNU's reinterpretation of dbm. + + +This module is quite similar to the :mod:`dbm` module, but uses the GNU library +``gdbm`` instead to provide some additional functionality. Please note that the +file formats created by ``gdbm`` and ``dbm`` are incompatible. + +The :mod:`dbm.gnu` module provides an interface to the GNU DBM library. +``gdbm`` objects behave like mappings (dictionaries), except that keys and +values are always strings. Printing a :mod:`dbm.gnu` object doesn't print the +keys and values, and the :meth:`items` and :meth:`values` methods are not +supported. + +.. exception:: error + + Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is + raised for general mapping errors like specifying an incorrect key. + + +.. function:: open(filename, [flag, [mode]]) + + Open a ``gdbm`` database and return a :class:`gdbm` object. The *filename* + argument is the name of the database file. + + The optional *flag* argument can be: + + +---------+-------------------------------------------+ + | Value | Meaning | + +=========+===========================================+ + | ``'r'`` | Open existing database for reading only | + | | (default) | + +---------+-------------------------------------------+ + | ``'w'`` | Open existing database for reading and | + | | writing | + +---------+-------------------------------------------+ + | ``'c'`` | Open database for reading and writing, | + | | creating it if it doesn't exist | + +---------+-------------------------------------------+ + | ``'n'`` | Always create a new, empty database, open | + | | for reading and writing | + +---------+-------------------------------------------+ + + The following additional characters may be appended to the flag to control + how the database is opened: + + +---------+--------------------------------------------+ + | Value | Meaning | + +=========+============================================+ + | ``'f'`` | Open the database in fast mode. Writes | + | | to the database will not be synchronized. | + +---------+--------------------------------------------+ + | ``'s'`` | Synchronized mode. This will cause changes | + | | to the database to be immediately written | + | | to the file. | + +---------+--------------------------------------------+ + | ``'u'`` | Do not lock database. | + +---------+--------------------------------------------+ + + Not all flags are valid for all versions of ``gdbm``. The module constant + :const:`open_flags` is a string of supported flag characters. The exception + :exc:`error` is raised if an invalid flag is specified. + + The optional *mode* argument is the Unix mode of the file, used only when the + database has to be created. It defaults to octal ``0666``. + + In addition to the dictionary-like methods, ``gdbm`` objects have the + following methods: + + .. method:: gdbm.firstkey() + + It's possible to loop over every key in the database using this method and the + :meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal + hash values, and won't be sorted by the key values. This method returns + the starting key. + + .. method:: gdbm.nextkey(key) + + Returns the key that follows *key* in the traversal. The following code prints + every key in the database ``db``, without having to create a list in memory that + contains them all:: + + k = db.firstkey() + while k != None: + print(k) + k = db.nextkey(k) + + .. method:: gdbm.reorganize() + + If you have carried out a lot of deletions and would like to shrink the space + used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm`` + will not shorten the length of a database file except by using this + reorganization; otherwise, deleted file space will be kept and reused as new + (key, value) pairs are added. + + .. method:: gdbm.sync() + + When the database has been opened in fast mode, this method forces any + unwritten data to be written to the disk. + + +:mod:`dbm.ndbm` --- Interface based on ndbm +------------------------------------------- + +.. module:: dbm.ndbm :platform: Unix :synopsis: The standard "database" interface, based on ndbm. -The :mod:`dbm` module provides an interface to the Unix "(n)dbm" library. Dbm -objects behave like mappings (dictionaries), except that keys and values are +The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library. +Dbm objects behave like mappings (dictionaries), except that keys and values are always strings. Printing a dbm object doesn't print the keys and values, and the :meth:`items` and :meth:`values` methods are not supported. @@ -17,13 +297,10 @@ compatibility interface, or the GNU GDBM compatibility interface. On Unix, the :program:`configure` script will attempt to locate the appropriate header file to simplify building this module. -The module defines the following: - - .. exception:: error - Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised for - general mapping errors like specifying an incorrect key. + Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised + for general mapping errors like specifying an incorrect key. .. data:: library @@ -61,14 +338,54 @@ The module defines the following: modified by the prevailing umask). -.. seealso:: - Module :mod:`anydbm` - Generic interface to ``dbm``\ -style databases. +:mod:`dbm.dumb` --- Portable DBM implementation +----------------------------------------------- + +.. module:: dbm.dumb + :synopsis: Portable implementation of the simple DBM interface. + +.. index:: single: databases + +.. note:: + + The :mod:`dbm.dumb` module is intended as a last resort fallback for the + :mod:`dbm` module when no more robust module is available. The :mod:`dbm.dumb` + module is not written for speed and is not nearly as heavily used as the other + database modules. + +The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which +is written entirely in Python. Unlike other modules such as :mod:`gdbm` and +:mod:`bsddb`, no external library is required. As with other persistent +mappings, the keys and values must always be strings. + +The module defines the following: + + +.. exception:: error + + Raised on dbm.dumb-specific errors, such as I/O errors. :exc:`KeyError` is + raised for general mapping errors like specifying an incorrect key. + + +.. function:: open(filename[, flag[, mode]]) + + Open a dumbdbm database and return a dumbdbm object. The *filename* argument is + the basename of the database file (without any specific extensions). When a + dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions + are created. + + The optional *flag* argument is currently ignored; the database is always opened + for update, and will be created if it does not exist. + + The optional *mode* argument is the Unix mode of the file, used only when the + database has to be created. It defaults to octal ``0o666`` (and will be modified + by the prevailing umask). - Module :mod:`gdbm` - Similar interface to the GNU GDBM library. + In addition to the methods provided by the :class:`collections.MutableMapping` class, + :class:`dumbdbm` objects provide the following method: - Module :mod:`whichdb` - Utility module used to determine the type of an existing database. + .. method:: dumbdbm.sync() + Synchronize the on-disk directory and data files. This method is called + by the :meth:`Shelve.sync` method. |