Create the dbm package from PEP 3108. #2881.

11 files changed, 348 insertions, 480 deletions

diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index 3cc1da92e9..616b99cd09 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -316,7 +316,7 @@ For example, if you need to link against libraries known to be in the standard
 library search path on target systems ::
 
    Extension(...,
-             libraries=['gdbm', 'readline'])
+             libraries=['_gdbm', 'readline'])
 
 If you need to link with libraries in a non-standard location, you'll have to
 include the location in ``library_dirs``::
diff --git a/Doc/library/anydbm.rst b/Doc/library/anydbm.rst
deleted file mode 100644
index f35a41636f..0000000000
--- a/Doc/library/anydbm.rst
+++ /dev/null
@@ -1,96 +0,0 @@
-
-:mod:`anydbm` --- Generic access to DBM-style databases
-=======================================================
-
-.. module:: anydbm
-   :synopsis: Generic interface to DBM-style database modules.
-
-
-.. index::
-   module: dbhash
-   module: bsddb
-   module: gdbm
-   module: dbm
-   module: dumbdbm
-
-:mod:`anydbm` is a generic interface to variants of the DBM database ---
-:mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`.  If none of
-these modules is installed, the slow-but-simple implementation in module
-:mod:`dumbdbm` will be used.
-
-
-.. function:: open(filename[, flag[, mode]])
-
-   Open the database file *filename* and return a corresponding object.
-
-   If the database file already exists, the :mod:`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 *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 ``0666`` (and will be modified
-   by the prevailing umask).
-
-
-.. exception:: error
-
-   A tuple containing the exceptions that can be raised by each of the supported
-   modules, with a unique exception also named :exc:`anydbm.error` as the first
-   item --- the latter is used when :exc:`anydbm.error` is raised.
-
-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 :meth:`has_key` and :meth:`keys` methods 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 anydbm
-
-   # Open database, creating it if necessary.
-   db = anydbm.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:`dbhash`
-      BSD ``db`` database interface.
-
-   Module :mod:`dbm`
-      Standard Unix database interface.
-
-   Module :mod:`dumbdbm`
-      Portable implementation of the ``dbm`` interface.
-
-   Module :mod:`gdbm`
-      GNU database interface, based on the ``dbm`` interface.
-
-   Module :mod:`shelve`
-      General object persistence built on top of  the Python ``dbm`` interface.
-
-   Module :mod:`whichdb`
-      Utility module used to determine the type of an existing database.
-
diff --git a/Doc/library/bsddb.rst b/Doc/library/bsddb.rst
index 1b153c97ea..9fde725c5c 100644
--- a/Doc/library/bsddb.rst
+++ b/Doc/library/bsddb.rst
@@ -92,7 +92,7 @@ arguments should be used in most instances.
 
 .. seealso::
 
-   Module :mod:`dbhash`
+   Module :mod:`dbm.bsd`
       DBM-style interface to the :mod:`bsddb`
 
 
diff --git a/Doc/library/dbhash.rst b/Doc/library/dbhash.rst
deleted file mode 100644
index aadb14f35f..0000000000
--- a/Doc/library/dbhash.rst
+++ /dev/null
@@ -1,114 +0,0 @@
-
-:mod:`dbhash` --- DBM-style interface to the BSD database library
-=================================================================
-
-.. module:: dbhash
-   :synopsis: DBM-style interface to the BSD database library.
-.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-
-
-.. index:: module: bsddb
-
-The :mod:`dbhash` 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:`dbhash`.
-
-This module provides an exception and a function:
-
-
-.. 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.
-
-
-.. seealso::
-
-   Module :mod:`anydbm`
-      Generic interface to ``dbm``\ -style databases.
-
-   Module :mod:`bsddb`
-      Lower-level interface to the BSD ``db`` library.
-
-   Module :mod:`whichdb`
-      Utility module used to determine the type of an existing database.
-
-
-.. _dbhash-objects:
-
-Database Objects
-----------------
-
-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.
-
diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index 52923e826d..2a314dc8f3 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.
diff --git a/Doc/library/dumbdbm.rst b/Doc/library/dumbdbm.rst
deleted file mode 100644
index 4e91ac93df..0000000000
--- a/Doc/library/dumbdbm.rst
+++ /dev/null
@@ -1,78 +0,0 @@
-
-:mod:`dumbdbm` --- Portable DBM implementation
-==============================================
-
-.. module:: dumbdbm
-   :synopsis: Portable implementation of the simple DBM interface.
-
-
-.. index:: single: databases
-
-.. note::
-
-   The :mod:`dumbdbm` module is intended as a last resort fallback for the
-   :mod:`anydbm` module when no more robust module is available. The :mod:`dumbdbm`
-   module is not written for speed and is not nearly as heavily used as the other
-   database modules.
-
-The :mod:`dumbdbm` 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 dumbdbm-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 ``0666`` (and will be modified
-   by the prevailing umask).
-
-
-.. seealso::
-
-   Module :mod:`anydbm`
-      Generic interface to ``dbm``\ -style databases.
-
-   Module :mod:`dbm`
-      Similar interface to the DBM/NDBM library.
-
-   Module :mod:`gdbm`
-      Similar interface to the GNU GDBM library.
-
-   Module :mod:`shelve`
-      Persistence module which stores non-string data.
-
-   Module :mod:`whichdb`
-      Utility module used to determine the type of an existing database.
-
-
-.. _dumbdbm-objects:
-
-Dumbdbm Objects
----------------
-
-In addition to the methods provided by the :class:`UserDict.DictMixin` class,
-:class:`dumbdbm` objects provide the following methods.
-
-
-.. method:: dumbdbm.sync()
-
-   Synchronize the on-disk directory and data files.  This method is called by the
-   :meth:`sync` method of :class:`Shelve` objects.
-
diff --git a/Doc/library/gdbm.rst b/Doc/library/gdbm.rst
deleted file mode 100644
index f69e667e56..0000000000
--- a/Doc/library/gdbm.rst
+++ /dev/null
@@ -1,122 +0,0 @@
-
-:mod:`gdbm` --- GNU's reinterpretation of dbm
-=============================================
-
-.. module:: gdbm
-   :platform: Unix
-   :synopsis: GNU's reinterpretation of dbm.
-
-
-.. index:: module: dbm
-
-This module is quite similar to the :mod:`dbm` module, but uses ``gdbm`` instead
-to provide some additional functionality.  Please note that the file formats
-created by ``gdbm`` and ``dbm`` are incompatible.
-
-The :mod:`gdbm` 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 ``gdbm`` object doesn't print the keys and values,
-and the :meth:`items` and :meth:`values` methods are not supported.
-
-The module defines the following constant and functions:
-
-
-.. 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 ``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:
-
-
-.. function:: 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.
-
-
-.. function:: 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)
-
-
-.. function:: 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.
-
-
-.. function:: sync()
-
-   When the database has been opened in fast mode, this method forces any
-   unwritten data to be written to the disk.
-
-
-.. seealso::
-
-   Module :mod:`anydbm`
-      Generic interface to ``dbm``\ -style databases.
-
-   Module :mod:`whichdb`
-      Utility module used to determine the type of an existing database.
-
diff --git a/Doc/library/persistence.rst b/Doc/library/persistence.rst
index 3708d17fb8..c5c2aa401e 100644
--- a/Doc/library/persistence.rst
+++ b/Doc/library/persistence.rst
@@ -22,11 +22,5 @@ The list of modules described in this chapter is:
    copyreg.rst
    shelve.rst
    marshal.rst
-   anydbm.rst
-   whichdb.rst
    dbm.rst
-   gdbm.rst
-   dbhash.rst
-   bsddb.rst
-   dumbdbm.rst
    sqlite3.rst
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 262b4a482e..ee839e8c56 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -21,7 +21,7 @@ lots of shared  sub-objects.  The keys are ordinary strings.
    the underlying database.  As a side-effect, an extension may be added to the
    filename and more than one file may be created.  By default, the underlying
    database file is opened for reading and writing.  The optional *flag* parameter
-   has the same interpretation as the *flag* parameter of :func:`anydbm.open`.
+   has the same interpretation as the *flag* parameter of :func:`dbm.open`.
 
    By default, version 0 pickles are used to serialize values.  The version of the
    pickle protocol can be specified with the *protocol* parameter.
@@ -53,12 +53,12 @@ Restrictions
 ------------
 
   .. index::
-     module: dbm
-     module: gdbm
+     module: dbm.ndbm
+     module: dbm.gnu
      module: bsddb
 
-* The choice of which database package will be used (such as :mod:`dbm`,
-  :mod:`gdbm` or :mod:`bsddb`) depends on which interface is available.  Therefore
+* The choice of which database package will be used (such as :mod:`dbm.ndbm`,
+  :mod:`dbm.gnu` or :mod:`bsddb`) depends on which interface is available.  Therefore
   it is not safe to open the database directly using :mod:`dbm`.  The database is
   also (unfortunately) subject to the limitations of :mod:`dbm`, if it is used ---
   this means that (the pickled representation of) the objects stored in the
@@ -107,7 +107,7 @@ Restrictions
 .. class:: DbfilenameShelf(filename[, flag='c'[, protocol=None[, writeback=False]]])
 
    A subclass of :class:`Shelf` which accepts a *filename* instead of a dict-like
-   object.  The underlying file will be opened using :func:`anydbm.open`.  By
+   object.  The underlying file will be opened using :func:`dbm.open`.  By
    default, the file will be created and opened for both read and write.  The
    optional *flag* parameter has the same interpretation as for the :func:`open`
    function.  The optional *protocol* and *writeback* parameters have the same
@@ -152,25 +152,12 @@ object)::
 
 .. seealso::
 
-   Module :mod:`anydbm`
-      Generic interface to ``dbm``\ -style databases.
+   Module :mod:`dbm`
+      Generic interface to ``dbm``-style databases.
 
    Module :mod:`bsddb`
       BSD ``db`` database interface.
 
-   Module :mod:`dbhash`
-      Thin layer around the :mod:`bsddb` which provides an :func:`open` function like
-      the other database modules.
-
-   Module :mod:`dbm`
-      Standard Unix database interface.
-
-   Module :mod:`dumbdbm`
-      Portable implementation of the ``dbm`` interface.
-
-   Module :mod:`gdbm`
-      GNU database interface, based on the ``dbm`` interface.
-
    Module :mod:`pickle`
       Object serialization used by :mod:`shelve`.
 
diff --git a/Doc/library/whichdb.rst b/Doc/library/whichdb.rst
deleted file mode 100644
index 5c698183fc..0000000000
--- a/Doc/library/whichdb.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-
-:mod:`whichdb` --- Guess which DBM module created a database
-============================================================
-
-.. module:: whichdb
-   :synopsis: Guess which DBM-style module created a given database.
-
-
-The single function in this module attempts to guess which of the several simple
-database modules available--\ :mod:`dbm`, :mod:`gdbm`, or :mod:`dbhash`\
---should be used to open a given file.
-
-
-.. function:: whichdb(filename)
-
-   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'`` or ``'gdbm'``.
-
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 3912d1efc1..7460dce855 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -394,12 +394,12 @@ Mappings
       section :ref:`dict`).
 
       .. index::
-         module: dbm
-         module: gdbm
+         module: dbm.ndbm
+         module: dbm.gnu
          module: bsddb
 
-      The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
-      additional examples of mapping types.
+      The extension modules :mod:`dbm.ndbm`, :mod:`dbm.gnu`, and :mod:`bsddb`
+      provide additional examples of mapping types.
 
 Callable types
    .. index::