Create the dbm package from PEP 3108. #2881.
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 @@
: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 @@
modified by the prevailing umask).
-.. seealso::
- Module :mod:`anydbm`
- Generic interface to ``dbm``\ -style databases.
+:mod:`dbm.dumb` --- Portable DBM implementation
+-----------------------------------------------
- Module :mod:`gdbm`
- Similar interface to the GNU GDBM library.
+.. module:: dbm.dumb
+ :synopsis: Portable implementation of the simple DBM interface.
- Module :mod:`whichdb`
- Utility module used to determine the type of an existing database.
+.. 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).
+
+ In addition to the methods provided by the :class:`collections.MutableMapping` class,
+ :class:`dumbdbm` objects provide the following method:
+
+ .. method:: dumbdbm.sync()
+
+ Synchronize the on-disk directory and data files. This method is called
+ by the :meth:`Shelve.sync` method.